Discover and explore Commercial Project APIs

API Business Hub: https://api.sap.com/

A good starting point to understand, which API to use and how, is the SAP API Business Hub. It lists the APIs that you can use for integration including a testing tool and detailed information on the structure of the API.

Under APIs --> S/4HANA Cloud --> Artifacts, you can search for your desired API on the right side, in our case I filter for “project”:

Currently we have five APIs related to projects. In this blog we will be using the APIs:

Create and Update Commercial Projects (OData)
Read Commercial Projects (OData)

In the overview page you get details regarding the communication scenario of your APIs, in our case SAP_COM_0054. This communication scenario you will need to activate in your S/4HANA Cloud system to be able to use the relevant APIs. Additionally you can find a link to a documentation of your API on the overview page under Business Documentation.

The API documentation is very important to understand the complete functionality of the API, what the service nodes are and which fields are mandatory and optional. For our read and create/update APIs the service nodes are ProjectSet, WorkpackageSet, WorkItemSet, PlanDataSet (read), DemandSet (create/update). In this blog we will be using the service node ProjectSet.

Clicking on service node ProjectSet will lead you to the parameter list of mandatory and optional parameters of the service. In our case we have 12 mandatory fields for the create API which need to be filled out to test the create/update service.

If you want to visualise your OData model, you can do it in SAP Web IDE in your SAP Cloud Platform account (trial account also works).

Please read Denise's blog on how to visualise your OData model: https://blogs.sap.com/2016/12/16/sap-web-ide-odata-model-viewer/

For the create/update project API you will receive following OData model. Here you can see how the different entity sets relate to each other:

Enable APIs in S/4HANA Cloud

Communication Management

To be able to address the API, we need to activate the relevant communication scenario (SAP_COM_0054). You can find detailed steps on how to activate the communication scenario in API Business Hub under S/4HANA Cloud --> Documents --> Testing API Services of SAP S/4HANA Cloud

In your S/4HANA Cloud system under communication management you need to setup:

A communication user for the technical exchange with your source system
Define your source system from where the messages will come from, for this test you can tip in any name, I used APIHUB
Activate communication arrangement SAP_COM_0054

Once you activated the scenario you can see that both read and create/update APIs are in communication scenario SAP_COM_0054.

Consume S/4HANA Cloud API directly

Testing

In this scenario we will be testing the APIs that we just activated in S/4HANA Cloud directly via Postman.

Read project

Once you have activated your communication arrangement in S/4HANA Cloud the read API will have an endpoint similar to this. Please replace <S4HC> with your S/4HANA Cloud tenant:

https://<S4HC>api.s4hana.ondemand.com/sap/opu/odata/CPD/SC_EXTERNAL_SERVICES_SRV

As mentioned before you need to include the service node that you want to address in the URL, in our case ProjectSet:

https://<S4HC>api.s4hana.ondemand.com/sap/opu/odata/CPD/SC_EXTERNAL_SERVICES_SRV/ProjectSet

In Postman you can execute the method GET with the credentials of your communication user, which you created when you setup the communication arrangement, and will receive the details regarding the current commercial projects in the system. If you want to search for a specific project, you can add the project ID at the end of your URL, in our case the project ID is “API”:

https://<S4HC>api.s4hana.ondemand.com/sap/opu/odata/CPD/SC_EXTERNAL_SERVICES_SRV/ProjectSet('API')

Running the read API first before using the create project API helps us understand the structure of the message, with which we address the create API. Note:

The cost center field requires 10 digits, our cost center (10201903) has only 8 digits, we need to add 2 leading zeros
Specific date and time format for start and end date.
Read API gives you the value of the project manager ID, while using the create API you require the project manager external ID. The project manager ID is the personnel ID of business user, while project manager external ID is the user name of the business user.

Create project

To create a project you need to execute the POST method on the create project API with relevant service node, in our case ProjectSet:

https://<S4HC>api.s4hana.ondemand.com/sap/opu/odata/CPD/SC_PROJ_ENGMT_CREATE_UPD_SRV/ProjectSet

Before we want to use the POST method, we require the x-csrf-token. We can get this by using the GET method on the API service with parameter x-csrf-token=fetch. Note that you do not need the service node here:

You need to have the payload in JSON format ready, which includes all the relevant project details and all 12 mandatory fields as mentioned before are maintained. You can get the model schema for the API in API Business Hub:

It included some optional fields and not all mandatory field, which I included manually. Below payload has only mandatory fields for service node ProjectSet:

{
  "ProjectCategory": "C",
  "OrgID": "your Org ID",
  "CostCenter": "your 10 digit cost center",
  "ProfitCenter": "your profit center",
  "Customer": "your customer ID",
  "Currency": "EUR",
  "ProjectID": "API",
  "ProjectName": "ProjectAPI",
  "ProjectStage": "P001",
  "ProjManagerExtId": "your user name",
  "StartDate": "2018-03-29T00:00:00.0000000",
  "EndDate": "2018-03-29T00:00:00.0000000"
}

Now you can use the POST method on the read API with the payload, the x-csrf-token and credentials of your communication user. If you are able to post it successfully, you should be able to search for project in S/4HC:

By default a work package is automatically created with the name of the project. If you want to post additional information when creating a project, such as work packages, work items or project role demand, you can use following payload structure:

{
  "ProjectCategory": "C",
  "OrgID": "your Org ID",
  "CostCenter": "your 10 digit cost center",
  "ProfitCenter": "your profit center",
  "Customer": "customer ID",
  "Currency": "EUR",
  "ProjectID": "API2",
  "ProjectName": "ProjectAPI2",
  "ProjectStage": "P001",
  "ProjManagerExtId": "user name",
  "StartDate": "2018-04-29T00:00:00.0000000",
  "EndDate": "2018-05-29T00:00:00.0000000",
  "WorkPackageSet": {
    "results": [
      {
        "ProjectID": "API2",
        "WorkPackageID": "API2.1.1",
        "WorkPackageName": "WorkPackageAPI2",
        "WPStartDate": "2018-04-29T00:00:00.0000000",
        "WPEndDate": "2018-05-29T00:00:00.0000000",
        "WorkItemSet": {
          "results": [
            {
              "ProjectID": "API2",
             "WorkPackageID": "API2.1.1",
              "WorkPackageName": "WorkPackageAPI2",
              "Workitem": "your work item",
              "Workitemname": "your work item name"
            }
          ]
        },
        "DemandSet": {
          "results": [
            {
              "ProjectID": "API2",
              "WorkPackageID": "API2.1.1",
              "ResType": "your resource type",
              "ResourceId": "your resource ID",
              "Effort": "10",
              "Uom": "H",
              "Workitem": "your work item",
              "WorkPackageName": "WorkPackageAPI2"
            }
          ]
        }
      }
    ]
  }
}

Again, if you struggle to find your values for any of these fields, you can use the read (GET) method to read the existing data of these fields in your S/4HANA Cloud system. This is an indication for you what the field value you need to enter could be.

If you set it up correctly another project is created:

Additionally a work package is created with the ID we specified and the work item is assigned to the work package. In our case the work item ID is "P002" and the work item name is "Testing":

Also a project role is created in our work package:

Project Integration Part 1 Hoang Vu about 1 year ago Creator: Hoang Vu 0 Views 0 Likes Cross Area Topics / Knowledge Base

Related Content

Comments

Updated by Hoang Vu

Metadata

Project Integration Part 1

Hoang Vu about 1 year ago Creator: Hoang Vu 0 Views 0 Likes

Cross Area Topics

/ Knowledge Base