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

 

[JefB]

Great functionality Sarau, and clear explanation!

When would parameters be supported, is it (going to be) soon on the roadmap?
We were wondering if we can let (key users) trigger a BW process chain from the SAC API step in multi-action, and if you have any more details how this can be setup?

[placido_pignataro]

Hello. Thanks a lot for the explanation.

Do you know if this would work for a Neo environment? Or only for Foundry?

Thank you!

[SarauShen]

Hi Placido,

This feature is supported for both NEO and CF.

Sarau

[adam_pazdziorko]

Hello,

 

It's really good blog that describes how to use the API Integration from PaPM Cloud to SAC.

 

However i would like to ask question that might be "out of the scope" of this blog but it's really important for me in my current project, i want to pass through the API the Parameters to PaPM Cloud and i am not sure about the syntax. Can You please provide some more information how to pass parameters to PaPM Cloud Process?

Best Regards

Adam Paździorko

[jonas_neurath]

Hi Sarau,

thank you very much for the blogpost. I have two questions regarding the functionality of API step in multi actions. Would be great if you or anybody else could answer them:

1. Is it possible to use the new parameters to pass data from a SAC model to the API? Or is there another possibility to pass data from a model (live or import) to an API?


2. Is there a way to use the "content" in the response body coming back from the API and transform it into a model / story or make it visible in the SAC anyhow?

For our current project it would be very helpful to get some answers on these questions.

Thanks in advance!

Best, Jonas

[SarauShen]

Hi Jonas,

Parameter used in API step is supported in the release of 2023.QRC3.

You can create Member type parameter or Number type parameter in multi action, and use the parameter in request body of API step (as well as other steps).

Hope this clarifies.

Sarau

[jonas_neurath]

Hi Sarau,

what we actually want to do is to pass data from a model to an API. I found no way to do this with the new parameter-feature.

So, to clarify, we have a given model with let's say 300 observations and we now want to send these 300 observations to the API.

Do you know a way to do this in SAC?

Thanks,

Jonas

[SarauShen]

Hi Jonas,

I might suggest the following way:

1. create a number type parameter in multi actions


2. get data from a given model via app designer API


3. set value for this number type parameter via app designer API


4. execute this multi action via app designer API

Sarau

[bkeraj]

Hi sarau.shen,

Thank you for this informative blog post. I have a question related to the response body.

I am currently using the API connection to prompt an endpoint and there is an action triggered which then returns some relevant results in the response.body. However currently I am able to successfully ping the endpoint but I only get the status 200 back. How can I get also the response.body content?

I tried the parameter field mapping, but the response body of the API i use has only 1 key-value pair, and not job_id or status. I am new to SAC so I am wondering if there is any other option I am missing to get the results and store them in SAC, and not only the status 200.

Thank you in advance,

Blirona

[SarauShen]

Hi Blirona,

Thanks for your interests in multi actions.

Currently, only job_id and status can be retrieved from response body.

Could you please explain more what information you expect to get from response body?

 

Sarau

[bkeraj]

the response body contains only the "results" field. Like the following json:

{"results": [0]}

There is no job_id or status and I cannot modify the API response body format. So when I execute the multi action in a story with the API step and ping the API endpoint, I get only the status 200 but not the actual response body to store it or further process it in the following stages of multi action.

Thank you

[SarauShen]

Hi Blirona,

I assume your API is a synchronous API, hence you might try below settings.

[bkeraj]

Hi Sarau,
I tried this but I only get status 200. How Can I ger and store the response body?

[damovand]

Thank you for this clear explanation of this topic.  👍