Friday, 13 April 2018

S/4HANA Cloud Integration | Commercial Project Part 2

Introduction


Consume S/4HANA Cloud APIs indirectly via SAP Cloud Platform Integration

In this blog we will focus on indirect S/4HANA Cloud API consumption via SAP Cloud Platform Integration (in this blog referred to as CPI).

Ideally you have read through part 1: http://www.saphanacentral.com/2018/04/s4hana-cloud-integration-commercial.html

S/4HANA Cloud Integration, SAP HANA Certifications, SAP HANA Tutorials and Materials, SAP HANA Guides, SAP HANA Learning

You might not want to address the API directly in S/4HANA Cloud but indirectly via a Middleware. This is the use case if you plan to connect S/4HANA Cloud to another system and an extensive mapping and routing operation is required. In our scenario we will use SAP Cloud Platform Integration (CPI). In CPI you are able to exploit an OData API, which both read and create project APIs are, as an Integration Flow or as an OData Service. In our case we will create an OData Service, and Integration Flow with an OData sender adapter and an Integration Flow with a HTTPS sender adapter. To do this you need to have activated the relevant APIs in S/4HANA Cloud (read part 1 for further information).

OData Catalog Service


If you are unsure of the URL to your OData service and want to view all deployed OData services in CPI, you can use the catalog service:

https://<CPI-tenant>/gw/CATALOGSERVICE;v=1/ServiceCollection

OData Service


In SAP Cloud Platform Integration you can expose existing S/4HANA Cloud SOAP and OData APIs as OData Services. The benefit here is that it creates relevant default mappings, while the Integration Flow does not. To do that instead of creating an Integration Flow in your integration package, create an OData Service:

S/4HANA Cloud Integration, SAP HANA Certifications, SAP HANA Tutorials and Materials, SAP HANA Guides, SAP HANA Learning

Then you define a service name and namespace, which will be used in the URL to address the OData service. Once the top right click on “Import Model Wizard” and import the EDMX file you downloaded for your API from the API Business Hub. Select the OData Hierarchy that you want to include in your OData Service, in our case we included all four service nodes:

S/4HANA Cloud Integration, SAP HANA Certifications, SAP HANA Tutorials and Materials, SAP HANA Guides, SAP HANA Learning

Once you check the structure and pressed on “finished”, you can view your OData model in the Graphical Model Viewer on the top right corner:

S/4HANA Cloud Integration, SAP HANA Certifications, SAP HANA Tutorials and Materials, SAP HANA Guides, SAP HANA Learning

It will display you the structure of your OData service graphically:

S/4HANA Cloud Integration, SAP HANA Certifications, SAP HANA Tutorials and Materials, SAP HANA Guides, SAP HANA Learning

Now we want to define the method, with which you want to address the OData service. Because we want to create a project in S/4HC we choose the method CREATE and press on “bind”:

S/4HANA Cloud Integration, SAP HANA Certifications, SAP HANA Tutorials and Materials, SAP HANA Guides, SAP HANA Learning

Here we set the entity set to “ProjectSet and our End Point is the S/4HC API:

S/4HANA Cloud Integration, SAP HANA Certifications, SAP HANA Tutorials and Materials, SAP HANA Guides, SAP HANA Learning

Once we press on OK, it will create an Integration Flow automatically for the CREATE method with these parameters. You need to check if both sender and receiver OData adapter have been configured correctly and if both mappings are correct:

S/4HANA Cloud Integration, SAP HANA Certifications, SAP HANA Tutorials and Materials, SAP HANA Guides, SAP HANA Learning

Once this is done, you can deploy the OData service. In our case we use “CREATEPROJECTS” as a service name and “SAP” as namespace, which means our URL will have following format:

https://<CPI-tenant>/gw/odata/SAP/CREATEPROJECTS;v=1/ProjectSet

Here again, you can use the same payload structure from part 1 of my blog series and just change the project ID and project name:

{
  "ProjectCategory": "C",
  "OrgID": "1020",
  "CostCenter": "0010201903",
  "ProfitCenter": "YB102",
  "Customer": "IC1020",
  "Currency": "EUR",
  "ProjectID": "API",
  "ProjectName": "ProjectAPI",
  "ProjectStage": "P001",
  "ProjManagerExtId": "<User_name>",
  "StartDate": "2018-03-29T00:00:00.0000000",
  "EndDate": "2018-03-29T00:00:00.0000000"
}

If successful, you should receive a successful message in the CPI monitor:

S/4HANA Cloud Integration, SAP HANA Certifications, SAP HANA Tutorials and Materials, SAP HANA Guides, SAP HANA Learning

Once you check the S/4HANA Cloud system you will see that a new project has been created:

S/4HANA Cloud Integration, SAP HANA Certifications, SAP HANA Tutorials and Materials, SAP HANA Guides, SAP HANA Learning

Integration Flow with OData sender adapter


In this case we create an Integration Flow with both OData sender and receiver adapter.

In the OData sender adapter
  • include the EDMX file of the OData API, which you can download from API Business Hub
  • set the Entity Set to ProjectSet:
S/4HANA Cloud Integration, SAP HANA Certifications, SAP HANA Tutorials and Materials, SAP HANA Guides, SAP HANA Learning

In the receiver OData adapter
  • enter the URL to your S/4HANA endpoint, then insert your name of your communication user and set resource path to “ProjectSet”:
S/4HANA Cloud Integration, SAP HANA Certifications, SAP HANA Tutorials and Materials, SAP HANA Guides, SAP HANA Learning

In our scenario our integration flow consists of
  • 2 scripts
  • 1 request-reply
  • 1 message mapping
S/4HANA Cloud Integration, SAP HANA Certifications, SAP HANA Tutorials and Materials, SAP HANA Guides, SAP HANA Learning
  • Firstly we add a script that let us read the request payload
  • On the left hand side navigate to Script
  • create a GroovyScript
  • replace the default script with the following:
/*
 * The integration developer needs to create the method processData 
 * This method takes Message object of package com.sap.gateway.ip.core.customdev.util
 * which includes helper methods useful for the content developer:
 * 
 * The methods available are:
    public java.lang.Object getBody()
    //This method helps User to retrieve message body as specific type ( InputStream , String , byte[] ) - e.g. message.getBody(java.io.InputStream)
    public java.lang.Object getBody(java.lang.String fullyQualifiedClassName)
    public void setBody(java.lang.Object exchangeBody)
    public java.util.Map<java.lang.String,java.lang.Object> getHeaders()
    public void setHeaders(java.util.Map<java.lang.String,java.lang.Object> exchangeHeaders)
    public void setHeader(java.lang.String name, java.lang.Object value)
    public java.util.Map<java.lang.String,java.lang.Object> getProperties()
    public void setProperties(java.util.Map<java.lang.String,java.lang.Object> exchangeProperties) 
    public void setProperty(java.lang.String name, java.lang.Object value)
 * 
 */
import com.sap.gateway.ip.core.customdev.util.Message;
import java.util.HashMap;
def Message processData(Message message) {
def messageLog = messageLogFactory.getMessageLog(message);
def bodyAsString = message.getBody(String.class);
messageLog.addAttachmentAsString("Request Message", bodyAsString, "text/xml");
return message;
}

Then the Request Reply
  • on the left hand side go to external call, then create a request reply:
S/4HANA Cloud Integration, SAP HANA Certifications, SAP HANA Tutorials and Materials, SAP HANA Guides, SAP HANA Learning

Then we will add a message mapping for the response message from S/4HANA Cloud. Here we do a 1-to-1 mapping of the entity set ProjectSet.
  • Create a message mapping
  • Go to “edit message”
  • under “Source Messages” go to “edit message”
  • choose the EDMX file of your OData API
  • select “ProjectSet” as Element
  • under “Target Messages” go to “edit message”
  • choose the EDMX file of your OData API
  • select “ProjectSet” as Element
  • press ok
S/4HANA Cloud Integration, SAP HANA Certifications, SAP HANA Tutorials and Materials, SAP HANA Guides, SAP HANA Learning

  • click on the ProjectSet node on both source and target structure
  • click on the AB mapping button on the top right corner, it will automatically do your 1-to-1 mapping
S/4HANA Cloud Integration, SAP HANA Certifications, SAP HANA Tutorials and Materials, SAP HANA Guides, SAP HANA Learning

Then we include a script to display our response payload:
  • On the left hand side navigate to Script
  • create a GroovyScript
  • replace the default script with the following:
/*
 * The integration developer needs to create the method processData 
 * This method takes Message object of package com.sap.gateway.ip.core.customdev.util
 * which includes helper methods useful for the content developer:
 * 
 * The methods available are:
    public java.lang.Object getBody()
    //This method helps User to retrieve message body as specific type ( InputStream , String , byte[] ) - e.g. message.getBody(java.io.InputStream)
    public java.lang.Object getBody(java.lang.String fullyQualifiedClassName)
    public void setBody(java.lang.Object exchangeBody)
    public java.util.Map<java.lang.String,java.lang.Object> getHeaders()
    public void setHeaders(java.util.Map<java.lang.String,java.lang.Object> exchangeHeaders)
    public void setHeader(java.lang.String name, java.lang.Object value)
    public java.util.Map<java.lang.String,java.lang.Object> getProperties()
    public void setProperties(java.util.Map<java.lang.String,java.lang.Object> exchangeProperties) 
    public void setProperty(java.lang.String name, java.lang.Object value)
 * 
 */
import com.sap.gateway.ip.core.customdev.util.Message;
import java.util.HashMap;
def Message processData(Message message) {
def messageLog = messageLogFactory.getMessageLog(message);
def bodyAsString = message.getBody(String.class);
messageLog.addAttachmentAsString("Response Message", bodyAsString, "text/xml");
return message;
}

Now we can test this integration flow. Below is the payload structure for posting. Please include your relevant data into this payload before posting.

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

Firstly we need to get the x-csrf-token, check part 1 of this blog series.

Once we have the token in Postman
  • we select the POST method
  • set URL, it depends on the namespace and integration flow name, in our case the URL:
    • https://<CPI>/gw/odata/SAP/CREATEPROJECT;v=1/ProjectSet
    • replace <CPI> with your CPI tenant
  • include our communication user for basic authentication
  • include x-csrf-token
  • include payload in message body
If successful a response message is displayed:

S/4HANA Cloud Integration, SAP HANA Certifications, SAP HANA Tutorials and Materials, SAP HANA Guides, SAP HANA Learning

In S/4HANA Cloud a new project is created including a workpackage, work item and role assigned:

S/4HANA Cloud Integration, SAP HANA Certifications, SAP HANA Tutorials and Materials, SAP HANA Guides, SAP HANA Learning

In the CPI monitor you will see a successful message:

S/4HANA Cloud Integration, SAP HANA Certifications, SAP HANA Tutorials and Materials, SAP HANA Guides, SAP HANA Learning

Under the tap “Attachments” you can view your request payload:

S/4HANA Cloud Integration, SAP HANA Certifications, SAP HANA Tutorials and Materials, SAP HANA Guides, SAP HANA Learning

And your response payload:

S/4HANA Cloud Integration, SAP HANA Certifications, SAP HANA Tutorials and Materials, SAP HANA Guides, SAP HANA Learning

Integration Flow HTTP sender adapter (READ)


In case you want to use the HTTP sender adapter in CPI to read projects, this is also possible. For the read operation, simply create an integration Flow with an OData receiver adapter, where you include the EDMX file, choose the GET method and the relevant query options of your resource path. Basically here you define which service node you want to address, in our case we want to read projects (ProjectSet), and will fields we want to see when viewing projects:

S/4HANA Cloud Integration, SAP HANA Certifications, SAP HANA Tutorials and Materials, SAP HANA Guides, SAP HANA Learning

As the sender adapter choose HTTPS and define an address. In our case the URL will be build as followed:

https://<CPI-tenant>/http/readprojects

S/4HANA Cloud Integration, SAP HANA Certifications, SAP HANA Tutorials and Materials, SAP HANA Guides, SAP HANA Learning

If you were able to successfully read the projects in S/4HANA Cloud, you will receive a response message in xml format:

<ProjectSet>
    <Project>
        <Customer>IC1020</Customer>
        <ProfitCenter>YB102</ProfitCenter>
        <ProjectName>ProjectAPI</ProjectName>
        <CostCenter>0010201903</CostCenter>
        <OrgID>1020</OrgID>
        <CostCenterName>"Cost center name"</CostCenterName>
        <ProjectStage>P001</ProjectStage>
        <ProjManagerId>50000701</ProjManagerId>
        <ProfitCenterName>"Profit center name"</ProfitCenterName>
        <Currency>EUR</Currency>
        <CustomerName>"Customer name"</CustomerName>
        <ProjectID>API</ProjectID>
    </Project>
</ProjectSet>

You can also see a successful message in the CPI monitor:

S/4HANA Cloud Integration, SAP HANA Certifications, SAP HANA Tutorials and Materials, SAP HANA Guides, SAP HANA Learning