Moving from Version 1 to Version 2 of the Enterprise Project OData API

[cczwebber]

Are you still using version 1 of the Enterprise Project OData API (API_ENTERPRISE_PROJECT_SRV) to create, read, update, and delete enterprise projects in SAP S/4HANA Cloud? If so, this blog will help you to move smoothly to version 2 (API_ENTERPRISE_PROJECT_SRV_0002).

Why You Should Move to the New Version

Version 1 of the Enterprise Project OData API was deprecated in SAP S/4HANA Cloud 2102 and decommissioned in SAP S/4HANA Cloud 2202. To prevent technical maintenance efforts for an outdated product version, SAP now plans to delete this API version soon. Ensure the stability of your processes and allow us to focus on new features for your benefit by moving to version 2 of theEnterprise Project OData API now.

Version 2 of the Enterprise Project OData API was introduced in SAP S/4HANA Cloud 2102. In addition to enterprise projects (investment projects, overhead projects, statistical projects, and projects with revenue), this new API version also supports professional services projects (customer projects and internal projects) as well as project responsibilities (entitlements), and it has been enhanced continually with further features, such as work items, deliverables and additional properties. Take advantage of these new features by moving to version 2 of theEnterprise Project OData API now.

What You Need to Do

Version 2 of the Enterprise Project OData API is available on the SAP Business Accelerator Hub under Enterprise Project. The following features have been changed and require you to adjust your API requests when moving from version 1 to version 2 of the API: 

• The API version you address in your HTTP requests
• The processing of project manager data
• The way you determine the position of project elements within the work breakdown structure
• The operations for changing the processing status of the project definition and enterprise project elements

How to Adjust the API Version in Your Requests

To call version 2 of the Enterprise Project API, replace v=0001 withv=0002 in your requests.

Example – API Version 1:

POST <host>/sap/opu/odata/SAP/API_ENTERPRISE_PROJECT_SRV;v=0001/A_EnterpriseProject

Example – API Version 2:

POST  <host>/sap/opu/odata/sap/API_ENTERPRISE_PROJECT_SRV;v=0002/A_EnterpriseProject

How to Adjust the Processing of Project Manager Data

In version 2 of the Enterprise Project API, the project manager data is no longer part of the header entity A_EnterpriseProject. Instead, you assign a project manager to a project using the new entities for project team members and their entitlements. Proceed as follows to adjust your requests:

• When creating an enterprise project (HTTP method POST of the A_EnterpriseProject entity):
  1. Remove property ProjectManagerUUID from the header data in your request.

     Example:

     POST <host>/sap/opu/odata/sap/API_ENTERPRISE_PROJECT_SRV;v=0002/A_EnterpriseProject

     {
     "Project": "TestProject",
     "ProjectDescription": "TestProjectDescription",
     "ProjectStartDate": "2023-01-07T00:00:00",
     "ProjectEndDate": "2023-12-07T00:00:00",
     "ResponsibleCostCenter": "17101501",
     "ProfitCenter": "YB600",
     "ProjectManagerUUID":"0894EF45-7D01-1EDA-B2E1-4D0D02BD4547",
     "ProjectProfileCode": "YP02",
     
     

  2. Assign the project manager as a team member to your project using entity A_EnterpriseProjectTeamMember; Assign the team member to the project role with the role type YP_RL_001 (Project Manager) using entity A_EntTeamMemberEntitlement. The project role is created automatically during project creation.

     Example:

     {
         "Project": "CXL230301Y1",
         "ProjectDescription": "CXL230301Y1",
         "ProjectStartDate": "2023-01-07T00:00:00",
         "ProjectEndDate": "2023-12-07T00:00:00",
         "ResponsibleCostCenter": "17101501",
         "ProfitCenter": "YB600",
         "ProjectProfileCode": "YP02",
         "to_EntProjTeamMember": [
            {
             "BusinessPartnerUUID": "42010AEF-4E36-1EDC-ADCB-3AC6A0784013",
             "to_EntProjEntitlement": [
                {
                   "ProjectRoleType": "YP_RL_0001"
                }
              ]
            }
         ]

     }

     For more information, see Create Project Definition, Create Team Member, Create Entitlement.

• When reading the project manager data of an enterprise project (in API version 1, HTTP method GET of the A_EnterpriseProject entity):

Instead of retrieving the data of the header entity, use the HTTP method GET of the A_EntTeamMemberEntitlement and A_EnterpriseProjectTeamMember entities to read the entitlement and team member data of the project manager (project role type YP_RL_001).

Example:

GET <host>/sap/opu/odata/sap/API_ENTERPRISE_PROJECT_SRV;v=0002/A_EnterpriseProjectRole?$filter=(ProjectRoleType eq 'YP_RL_0001' and ProjectUUID eq guid'e9d28130-f33a-1eef-96d4-c15bd5dbdba4')&$expand=to_EnterpriseProject/to_EntProjTeamMember

GET <host>/sap/opu/odata/sap/API_ENTERPRISE_PROJECT_SRV;v=0002/A_EnterpriseProjectTeam Member(guid'0894EF45-7D01-1EDA-B2E1-4D0D02BD4547')/to_EntProjEntitlement

• When updating the project manager data of an existing enterprise project (in API version 1, method PATCH of the A_EnterpriseProject entity):

  1. Remove property ProjectManagerUUID from the update request for header entity A_EnterpriseProject. If it is the only property to be updated, delete the request.

  2. If there is no project manager assigned to the project yet, create the team member and entitlement data for the project manager using the HTTP method POST of the A_EnterpriseProjectTeamMember entity.

     Example:

     
  3. If there is already a project manager assigned to the project:
     1. Delete the existing entitlement using the HTTP method DELETE of the A_EntTeamMemberEntitlement entity.

        Example:

        DELETE <host>/sap/opu/odata/sap/API_ENTERPRISE_PROJECT_SRV;v=0002/A_EntTeamMemberEntitlement(guid'9418820a-c0a9-1ed8-9a92-4bed96f211dd')
     2. Create the team member and entitlement data for the new project manager using the HTTP method POST of the A_EnterpriseProjectTeamMember entity (see the example in step 2).

For more information, see Update Team Member Assigned to Entitlement

How to Adjust the Way you Determine the Position of Project Elements

In version 2 of the Enterprise Project API, property SortingNumber of the A_EnterpriseProjectElement entity has been replaced by property ProjectElementOrdinalNumber. Like the sorting number in API version 1, the ordinal number determines the sequence of project elements that have the same parent object in the work breakdown structure of an enterprise project. However, in API version 2, properties ProjectElementOrdinalNumber and ParentObjectUUID can no longer be changed using the update operation for the A_EnterpriseProjectElement entity. Instead, you need to use a dedicated function import for changing the position of project elements. Proceed as follows to adjust your requests:

• When creating an enterprise project with project elements or creating project elements for an existing project (HTTP method POST of the A_EnterpriseProject or A_EnterpriseProjectElement entity):

Remove property SortingNumber in the project element data of your request. New project elements are added after existing project elements with the same parent object.

Example:

POST <host>/sap/opu/odata/sap/API_ENTERPRISE_PROJECT_SRV ;v=0002/A_EnterpriseProjectElement

{

"ProjectUUID" : "0894ef45-77a9-1ee8-b8b2-f5dc22f3f345",

"ProjectElement" : "EXAMPLE_EPPM_PROJECT_ELEMENT",

"ProjectElementDescription" : "Example Enterprise Project Element”,

"PlannedStartDate" : "2019-01-01T00:00:00",

"PlannedEndDate" : "2019-12-31T00:00:00

}

ProjectElementOrdinalNumber is read-only and calculated. It’s helpful to identify the position of project element.

For more information, see Project Element and Create Project Element.

• When reading the project element data of an enterprise project (for example, HTTP method GET of the A_EnterpriseProjectElement entity):

Instead of property SortingNumber, use property ProjectElementOrdinalNumber in combination with property ParentObjectUUID to determine the position of a project element.

• When updating the position of an enterprise project (in API version 1, method PATCH of the A_ EnterpriseProjectElement entity):
  1. Remove properties ProjectElementOrdinalNumber and ParentObjectUUID from the update request for the A_EnterpriseProject entity. If these are the only properties to be updated, delete the request.
  2. Use the http method POST to call the ChangeEntProjElmntPosition function import and specify the new position of the project element using the parameter ProjectElementUUID, ParentObjectUUID, and LeftSiblingUUID.
  3. Parameter LeftSiblingUUID indicates the project element preceding the shifted project element within the sequence of project elements that have the same parent object.

Example:

POST <host>/sap/opu/odata/sap/API_ENTERPRISE_PROJECT_SRV;v=0002/ChangeEntProjElmntPosition?ProjectElementUUID=guid'0894EF45-7741-1EDA-AEBA-0E072B97B70F'&ParentObjectUUID=guid'0894EF45-7741-1EDA-AEBA-0E072B97770F'&LeftSiblingUUID=guid'0894EF45-7741-1EDA-AEBA-0E072B99D70F'

In this example, project element 0894EF45-7741-1EDA-AEBA-0E072B97B70F is shifted to the structure level below project element 0894EF45-7741-1EDA-AEBA-0E072B97770F. In the sequence of project elements at this structure level, it is inserted as the direct successor of project element0894EF45-7741-1EDA-AEBA-0E072B99D70F.

For more information, see Change Position of Project Element.

How to Adjust the Operations for Changing the Processing Status

In version 2 of the Enterprise Project API, the actions for changing the processing status of the project definition and project elements have been replaced by two new function imports, which require the same parameters as the actions that they replace. Proceed as follows to adjust your requests:

• When updating the processing status of the project definition (in API version 1, method POST for the SetProcessingStatus action):

In your request, replace SetProcessingStatus with ChangeEntProjProcgStatus.

Example:

POST <host>/sap/opu/odata/sap/API_ENTERPRISE_PROJECT_SRV;v=0002/ChangeEntProjProcgStatus?ProjectUUID=guid'9418820a-c0a9-1ed8-9a92-4bed96f211dd'&ProcessingStatus='10'

• When updating the processing status of a project element (in API version 1, method POST for the SetProjElemProcessingStatus action):

In your request, replace SetProcessingStatus with ChangeEntProjProcgStatus.

Example:

POST <host>/sap/opu/odata/sap/API_ENTERPRISE_PROJECT_SRV;v=0002/ChangeEntProjElmntProcgStatus?ProjectElementUUID=guid'1c98ec18-1855-1ed9-87db-9bca6b653165'&ProcessingStatus='10'

For more information, see Change Processing Status of Project Definition and Change Processing Status of Project Element.

Communication Arrangement

There is no need to change communication arrangement.

And you could see that the version 1 has been deprecated since 2102.

Summary

In this blog, we have summarized the changes that require your attention when moving from version 1 to version 2 of the Enterprise Project OData API. By providing step-by-step procedures and examples, we hope to guide you through this transition as seamlessly as possible. Please feel free to ask any further question that you have related to this.