Integrate remote application via API step of Multi Actions

[SarauShen]

Introduction

SAP Analytics Cloud (SAC) introduced Multi Actions in the release of 2021.Q3, then integrated Predictive Scenario into Multi Actions and Data Import Job into Multi Actions in the release of 2022.Q1 and 2022.Q3.

In the release of 2022.Q4, SAC is introducing a new feature called API step in Multi Actions. API step in Multi Actions empowers SAC users to further execute remote calculation or program as one step in a multi action sequence.

Multi actions help you orchestrate a set of planning operations across multiple models/versions in SAC and external operations outside of SAC.  This constitutes the straightforward UI, well-organized layout and easily-understood guide, which offers user a no-code experience. Users with little IT background are able to build a multi action integrating different types of actions.

What's more, Multi Actions can be parameterized which largely reduces maintenance effort for admin users.  Business users execute multi action with defined context and scope by assigning parameter values flexibly.

Scenarios

There are some typical examples that API step in Multi Actions can enable.

Scenario example #1

Multi actions can support extension to plugin the customer exit of any customized logic in remote engine. Assuming standard product can’t support business-critical calculations, hence customer develops the custom logic in a powerful calculation engine remotely. Multi actions can integrate the calculations of SAP Analytics Cloud and custom logic of remote engine in one sequence seamlessly via triggering a remote API which transfers data and calculates data.

Business planner just needs to click one button to trigger the complex process with the defined scope.

Scenario example #2

Customers expect to make model export flexible and powerful by leveraging Data Export Service. The motivations might be SAC is the main environment that business users are working in so that export workflow should be managed in SAC, e.g. export workflow can be triggered in story by business user instead of modeling by admin user, or export data is a succeeding step right after data calculations (e.g. data action, predictive…).

 

Create Multi Action with API Step to trigger SAP PaPM Cloud API

Now, I am going to show you one example how API step can help.

Assuming I would like to use SAP Profitability and Performance Management Cloud (SAP PaPM Cloud) to perform advanced allocation and execute further data calculation via data action on the post-allocation data.

As prerequisites, 1) it is mandatory to establish that SAC public API is reachable through SAP PaPM Cloud’s Model View ODATA function. The intention is for SAC public API to call SAC Data Export Service to export data from SAC to SAP PaPM Cloud, which then will be used as one of the inputs for further allocation and calculation. 2) a HTTP API connection is required. You can refer to "Appendix - Create HTTP API Connection" for details.

Once the pre-requisite has been stabilized, the multi-action creation is now possible. To create SAC multi action with API step, below minimal steps will be performed

1. Create Multi Action and add API step connecting to the public API of SAP PaPM Cloud


2. Add data import job to load data from SAP PaPM Cloud to SAC


3. Add data action step


4. Add a version management step to publish the data into public version as the last step.

This blogpost will explain how to add API step in Multi Actions in detailed. Other steps such as Data Import, Data Action, and Version Management are explained in separate blogposts.

 

I. Create Multi Action and add API step connecting to the public API of SAP PaPM Cloud

1.Create a Multi Action, and add API step.

2. Fill in HTTP API configuration

Step Name	Mandatory field for name of the connection.
HTTP API Connection	Mandatory field for HTTP API connection of the API step. Refer to "Appendix - Create HTTP API Connection" about how to create a HTTP API Connection.
API URL	Mandatory field for API URL of the API step The exact URL depends on SAP PaPM tenant in use and action to trigger, which is built on top of the below: Production URL: https://{host}.cfapps.{region}.hana.ondemand.com/sap/opu/odata4/NXI/P1_PROCESSING   Actions: /CreateDeployRunActivityAsync – creates process based on process template and run activity /RunActivityAsync – works like CreateDeployRunActivityAsync action, but expects that process is already defined /CreateInstance – creates process based on process template   Example: Please see below API URL for CreateDeployRunActivityAsync action for the following environment. https://papm-cloud-api-prod-pov.cfapps.eu10.hana.ondemand.com/sap/opu/odata4/NXI/P1_PROCESSING/Creat...   Further technical details regarding SAP PaPM Processes API can be found here.
Method	POST method is the only method supported in QRC4.2022 release.
Header Fields	Optional field for header fields of the API step API of SAP PaPM Cloud does not require any additional header fields to execute, hence the default fields and values are used in this blog.
Body	Optional field for request body of the API step The request body of SAP PaPM Cloud API in JSON format. Fields that are required to be provided depend on API action to execute. Technical details regarding SAP PaPM API request body can be found here. Example:   Following example environment, the below shows an example of body for request that will create a new process instance in SAP PaPM Cloud based on already existing process template and then execute it.   SAP PaPM Process Template: Activity to run within that Process Template: Request Body: { "envId": "SXP", "version": "0014", "procId": "PROCESS", "parameters": {}, "selections": {}, "procTemplateId": "SXP_P_", "activity": "EXECUTE" } "procId": "PROCESS" is only an example value which dictates the name of process instance created and deployed by the API action. Such value is not taken from existing environment, and if it is provided as blank, the API will create a random name automatically.
Parameterization	With multi action, user can set value dynamically during execution via parameters. API step in multi actions supports parameters as well. Member type parameter and Number type parameter are supported in Multi Actions, and can be used in API step as well. Assuming parameters are created in current Multi Action already. Now, you can use these parameters in API step. There are 2 ways: 1. Move cursor to the place where the parameter should be used, select a parameter from parameter list and insert it into Body. The chosen parameter is inserted into Body.                     2. Directly input ${parameter name} in body. The PaPM integration in this blog doesn't use parameters.
API execution status	Both synchronous API and asynchronous API are supported. The PaPM integration in this blog uses asynchronous execution. Asynchronous API execution API step of Multi Actions triggers the public API in an asynchronous way, and then polls the status of public service periodically. Hence, you need to specify the method to retrieve status of API triggering and also the method to poll execution status.  Status can be retrieved from HTTP status code or the combination of HTTP status code and response body. If the status is retrieved from the combination of HTTP status code and response body, you need to ensure mandatory fields are contained in response body. Refer to blog for detailed configurations. In this blog, PaPM public API returns status via HTTP status code, e.g. code 200/202 means success, and 404 means failure. Polling URL is returned in response header (location field), hence no need to specify polling URL.   Synchronous API execution API step of Multi Actions triggers the public API in synchronous way, and the status of public service is returned immediately. Hence, you need to specify the method to retrieve status of API triggering as "Synchronous Return"

 

II. Add data import job to load data from SAP PaPM Cloud to SAC

Now that SAP PaPM Cloud Allocation or Calculation has been concluded via API Step. The datarecords produced by SAP PaPM Cloud Allocation or Calculation can now be pulled automatically by SAC from SAP PaPM Cloud through ODATA Service (Temporary Tables) or HANA Live Connection (Auto Generated Calculation Views).

Once the connection to pull data from SAP PaPM Cloud to SAC has been established, a Data Import Job can now be integrated in Multi Action.

 

III. Add data action step

Further calculations on the allocated data records are needed, Data Action steps can be integrated in Multi Actions.

 

IV. Add a version management step to publish the data into public version as the last step

Finally adding Version Management step to publish data to target public version.

Refer to blogpost for details: blog

 

 

Execute Multi Action

This multi action can be executed in story, analytics application, and scheduled via Calendar.

Refer to blog for details: Integrating Data Import Job in Multi Actions

Now, planner can execute this multi action via one button / schedule job simply. Complexity of planning process is hidden from end-user: data export to PaPM, allocation calculation in PaPM, data import back to SAC, and post-allocation calculation in SAC are automated sequentially

 

Out of scope

GET request

POST method is the only method supported in QRC4.2022 release.

 

Appendix - Create HTTP API Connection

1.Choose Connections in the lower left corner of the screen

2.Choose Add Connections

3. In the screen which appears, search for HTTP API. Remain in the screen while getting information of the needed credentials in the next steps.

4.In order to feed the HTTP API Connection with proper information coming from SAP PaPM Cloud, login to Business Technology Platform (BTP) using the global account and get credentials from the service keys information of the space given by the following steps:

4a.Choose the subaccount

4b. Choose Cloud Foundry Environment and choose the space if created. If available go to step 4e, if not perform the next step.

4c. If space does not exist perform Create Space and fill in the name of the space and tick the roles to be given on space creator.

4d. Choose the space created.

4e. On the left panel, Choose (a) Services -> (b)Instances -> (c) search for ‘API’ -> (d) Choose papm-cloud-api-papm-default. If available go to step 4h, if not perform the next step.

4f. If instance does not exist, Choose dropdown of Create and choose Service Instance

4g. In the screen which appears

4g.1. Select Service: SAP PaPM Cloud  -> Plan: Default (Instance) -> Instance Name: Name of the instance. Choose Next.

4g.2. Adjust the Parameter by copying the JSON File information in Create Service Instance Documentation in Help Portal and pasting it on the textbox

4g.3. Choose Create and Service Instance will be available.

4h. On the lower right side choose Service Keys Name to get the Client ID and Secret needed for OData Services Connection Creation. If available proceed to Step5, if not proceed with the next step.

4i. If Service Keys does not exist yet, Choose Create button within the created service instance. Add Service Key Name -> Leave Parameter textbox empty -> Choose Create.

Service Keys are now available for usage in creation of HTTP API Connection in SAC. Take note of line 2, line 4 line 5, and line 6 for HTTP API Connection usage.

 

­­­­5.Go back to SAC webpage and fill in the required connection information then choose Create.

Connection Name	Mandatory field for name of the connection.
Connection Description	Optional field for description of the connection
Data Service URL	URL of data service of your SAP PaPM Cloud tenant. Such information can be found in BTP Cockpit in API service key details <https:// + Line 2 url information from Service keys >
Authentication Type	OAuth 2.0 Client Credentials
OAuth Client ID	clientid from Step 4 Service key line 4 without “
Secret	clientsecret from Step 4 Service key line 5 without “
Token URL	Modified* url value from Step 4 Service key line 6 without ‘’ that adheres to: https://{host}.authentication.{region}.hana.ondemand.com/oauth/token?grant_type=client_credentials   Example: https:// papmc.authentication.eu10.hana.ondemand.com/oauth/token?grant_type=client_credentials
Scope	Optional and should stay empty for SAP PaPM Cloud API connection configuration