S/4HANA Cloud Integration | Commercial Project Part 1

Introduction

In a professional services project you might use S/4HANA Cloud in combination with other solutions to apply the relevant business processes for professional services such as opportunity to cash. Scenario could be that project opportunities are managed in another solution, once the opportunity gets realized and priced, a project in S/4HANA Cloud will be created.

To be able to integrate these processes you need to understand how the S/4HANA Cloud APIs related to commercial projects work and how to address them. Depending on the source system where the priced opportunity is created, you might need a middleware such as SAP Cloud Platform Integration to perform mapping requirements of the message structure.

In this blog I would like to show you how we can leverage these S/4HANA Cloud APIs. We will start by understanding what these APIs are, where we can find information and documentation and how to test the APIs directly in S/4HANA Cloud.

The scenario in this blog will look like this:

In a following blog we will create an OData Service and Integration Flows on SAP Cloud Platform Integration to consume the S/4HANA Cloud API. Once you have your OData Service established, other systems can connect to SAP Cloud Platform Integration to match their source structure to the structure of the OData service.

For this blog ideally you have some basic understanding in S/4HANA Cloud Integration, APIs and SAP Cloud Platform Integration.

Discover and explore Commercial Project APIs

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.

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’)

You will receive a response xml with the project details:

<?xml version="1.0" encoding="utf-8"?>

<entry xml:base="https://<S4HC>-api.s4hana.ondemand.com/sap/opu/odata/CPD/SC_EXTERNAL_SERVICES_SRV/" xmlns="http://www.w3.org/2005/Atom" xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata" xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices">

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

<title type="text">ProjectSet('API')</title>

<updated>2018-04-03T13:31:28Z</updated>

<category term="/CPD/SC_EXTERNAL_SERVICES_SRV.Project" scheme="http://schemas.microsoft.com/ado/2007/08/dataservices/scheme"/>

<link href="ProjectSet('API')" rel="self" title="Project"/>

<link href="ProjectSet('API')/WorkpackageSet" rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/WorkpackageSet" type="application/atom+xml;type=feed" title="WorkpackageSet"/>

<content type="application/xml">

<m:properties>

<d:ChangedBy>CC0000000002</d:ChangedBy>

<d:ProfitCenter>YB102</d:ProfitCenter>

<d:ChangedOn>2018-03-29T09:49:40.0000000Z</d:ChangedOn>

<d:ProfitCenterName>Consulting Unit B</d:ProfitCenterName>

<d:ProjectID>API</d:ProjectID>

<d:ProjectName>ProjectAPI</d:ProjectName>

<d:ProjectStage>P001</d:ProjectStage>

<d:StageDesc>In Planning</d:StageDesc>

<d:StartDate>2018-03-29T00:00:00</d:StartDate>

<d:EndDate>2018-03-29T00:00:00</d:EndDate>

<d:Customer>IC1020</d:Customer>

<d:CustomerName><CUSTOMERNAME></d:CustomerName>

<d:ProjManagerId>50000701</d:ProjManagerId>

<d:ProjManagerName><PM_Name></d:ProjManagerName>

<d:ProjAccountantId/>

<d:ProjAccountantName/>

<d:ProjControllerId/>

<d:ProjControllerName/>

<d:ProjPartnerId/>

<d:ProjPartnerName/>

<d:CostCenter>0010201903</d:CostCenter>

<d:CostCenterName>Csltg Unit B-(DE)</d:CostCenterName>

<d:ProjectCategory>P</d:ProjectCategory>

<d:Currency>EUR</d:Currency>

<d:Currencyname>European Euro</d:Currencyname>

<d:OrgID>1020</d:OrgID>

<d:OrgDesc><ORGDESCRIPTION></d:OrgDesc>

<d:Confidential>N</d:Confidential>

</m:properties>

</content>

</entry>

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: