This blog will introduce how to set up the HTTP API step of multi actions to integrate external applications—not only SAP applications, but also non-SAP products.
The new feature, called API step, allows you to integrate your own functionality to SAP Analytics Cloud multi actions without having to modify the original applications. The API step creates customer exits. You can hang your own add-on functionality onto these hooks.
Before we start to build the API step in multi actions, you’re required to create a connection that is for API integration specifically. To create the connection:
Fill in the mandatory information for connection configuration. The API step in multi actions is for backend services integration, hence HTTP API connection supports basic authentication and OAuth2.0’s client credentials. Therefore, customer should offer the public API that supports at least one of above authentications.
Simply speaking, a GET method URL with JSON MINE type for response, need basic/client credential authentication type, which must return HTTP code 200 is OK to be used here for connection saving. It is same as the other connections.
For on-premise connection, it needs port to be explicitly specified due to SCC restriction.
The connection also supports the on-premise landscape. If the HTTP API resides in the network that SAP Analytics Cloud could not access, then it is necessary to setup SAP Cloud Connector in customer’s network, because it plays the role that creates the bridge between SAP Analytics Cloud and the customer’s on-premise service. For how to set up and configure SAP Cloud Connector, please refer to the blog Installation and Configuration of SAP Cloud Connector.
Create API Step
If the above prerequisites are finished, you can go to multi actions and create an API step from the toolbar or from the popup menu. Now you will see the connection you created in the list. Select the connection you want to use.
Secondly, specify the API URL of the HTTP API to integrate with SAP Analytics Cloud. The API step supports only the POST method and only JSON MIME type, which is predefined in the default headers.
If needed, you can add header fields. Additional Header fields allow only ‘Prefer’:’respond-async’ and customized headers with keys beginning with ‘X-‘, except ‘x-forwarded-host’.
To set multiple values for a header field, you can separate the values using a comma or enter multiple header fields with the same key.
Now you need to specify the body of the POST request, if any. You can also click the Edit JSON button to open the edit dialog if the default editor is too small to edit.
Depending on the API provider, you can choose to determine the trigger status by HTTP code or the combination of HTTP code and response body.
According to the common design standard:
HTTP code returns 202 if the asynchronous activity is triggered successfully, which represents that the remote API starts to process the backend job in the remote system. If it returns 40x/50x, HTTP API fails to process the backend job in the remote system, which causes the API step to fail in multi actions.
If the status of HTTP API is determined by both HTTP code and response body, two mandatory properties (status, jobId) and one optional property (message) are required in Response Body.
For the status representing the asynchronized activity status, its accepted value could be “DONE”, “FAILED”, or “IN_PROCESS”. Another property called jobId stands for the asynchronous activity, and its value can be used to query the status of the running job remotely. The Message field is for detailed warning/error messages of the HTTP API trigger.
As mentioned above, in order to get the asynchronized activity, the system assumes a corresponding query API should be available for querying. You are supposed to set the URL in the section Get API Execution Result. However, if such API completion follows the OData standard, it is not mandatory for user to set the URL here, because the location in the trigger response header should be valid for query the status.
API Step integration case description
The integration supports 2 most popular protocols, including OData and normal REST API. Therefore, if the triggering response follows OData standard, it expects 202 for HTTP code and the corresponding location in headers. Refer to the following example:
If the polling response follows the OData standard, it expects 202 for HTTP code if the job is still in process, and 200 if the job is completed.
If the API is a non-OData interface, it accepts 200/202 for the HTTP code, concreate information in the response body which indicates the job status.
The corresponding polling response for non-OData accepts 202 or 200 if the job is still in process; however, only the detailed information in the body can tell whether the job is completed or not.
At the end, the API step also offers the option to judge the API status by code only. If you choose this option, the body will be ignored.
Welcome to share your feedback or thoughts in a comment part and refer to below SAP community resource for more information.
Conclusion:
Using the instructions of this blog posting, you will be able to set up HTTP API connection and integrate external API with API step in Multi Actions.
I hope this blog post can help your team doing the same implementation faster.
If you find this blog post helpful – please press like button 🙂
The new feature, called API step, allows you to integrate your own functionality to SAP Analytics Cloud multi actions without having to modify the original applications. The API step creates customer exits. You can hang your own add-on functionality onto these hooks.
Before we start to build the API step in multi actions, you’re required to create a connection that is for API integration specifically. To create the connection:
- Go to Connections > Add Connection.
add a connection
- Under Connect to Public API, choose Select HTTP API Connection.
select HTTP API connection
Fill in the mandatory information for connection configuration. The API step in multi actions is for backend services integration, hence HTTP API connection supports basic authentication and OAuth2.0’s client credentials. Therefore, customer should offer the public API that supports at least one of above authentications.
Simply speaking, a GET method URL with JSON MINE type for response, need basic/client credential authentication type, which must return HTTP code 200 is OK to be used here for connection saving. It is same as the other connections.
For on-premise connection, it needs port to be explicitly specified due to SCC restriction.
configure HTTP API connection
The connection also supports the on-premise landscape. If the HTTP API resides in the network that SAP Analytics Cloud could not access, then it is necessary to setup SAP Cloud Connector in customer’s network, because it plays the role that creates the bridge between SAP Analytics Cloud and the customer’s on-premise service. For how to set up and configure SAP Cloud Connector, please refer to the blog Installation and Configuration of SAP Cloud Connector.
Create API Step
If the above prerequisites are finished, you can go to multi actions and create an API step from the toolbar or from the popup menu. Now you will see the connection you created in the list. Select the connection you want to use.
Secondly, specify the API URL of the HTTP API to integrate with SAP Analytics Cloud. The API step supports only the POST method and only JSON MIME type, which is predefined in the default headers.
basic configuration
If needed, you can add header fields. Additional Header fields allow only ‘Prefer’:’respond-async’ and customized headers with keys beginning with ‘X-‘, except ‘x-forwarded-host’.
To set multiple values for a header field, you can separate the values using a comma or enter multiple header fields with the same key.
specify request headers
Now you need to specify the body of the POST request, if any. You can also click the Edit JSON button to open the edit dialog if the default editor is too small to edit.
when triggering
Depending on the API provider, you can choose to determine the trigger status by HTTP code or the combination of HTTP code and response body.
According to the common design standard:
HTTP code returns 202 if the asynchronous activity is triggered successfully, which represents that the remote API starts to process the backend job in the remote system. If it returns 40x/50x, HTTP API fails to process the backend job in the remote system, which causes the API step to fail in multi actions.
If the status of HTTP API is determined by both HTTP code and response body, two mandatory properties (status, jobId) and one optional property (message) are required in Response Body.
For the status representing the asynchronized activity status, its accepted value could be “DONE”, “FAILED”, or “IN_PROCESS”. Another property called jobId stands for the asynchronous activity, and its value can be used to query the status of the running job remotely. The Message field is for detailed warning/error messages of the HTTP API trigger.
As mentioned above, in order to get the asynchronized activity, the system assumes a corresponding query API should be available for querying. You are supposed to set the URL in the section Get API Execution Result. However, if such API completion follows the OData standard, it is not mandatory for user to set the URL here, because the location in the trigger response header should be valid for query the status.
when polling
API Step integration case description
The integration supports 2 most popular protocols, including OData and normal REST API. Therefore, if the triggering response follows OData standard, it expects 202 for HTTP code and the corresponding location in headers. Refer to the following example:
Triggering - OData standard
If the polling response follows the OData standard, it expects 202 for HTTP code if the job is still in process, and 200 if the job is completed.
Polling - OData standard
If the API is a non-OData interface, it accepts 200/202 for the HTTP code, concreate information in the response body which indicates the job status.
Triggering - non-OData standard
The corresponding polling response for non-OData accepts 202 or 200 if the job is still in process; however, only the detailed information in the body can tell whether the job is completed or not.
Polling - non-OData standard
At the end, the API step also offers the option to judge the API status by code only. If you choose this option, the body will be ignored.
Welcome to share your feedback or thoughts in a comment part and refer to below SAP community resource for more information.
- Please refer to more topic in SAP Analytics Cloud Topic Page
- Ask questions about SAP Analytics Cloud and follow.
- Read other SAP Analytics Cloud and follow blog posts.
- Please follow my profile for future posts.
Conclusion:
Using the instructions of this blog posting, you will be able to set up HTTP API connection and integrate external API with API step in Multi Actions.
I hope this blog post can help your team doing the same implementation faster.
If you find this blog post helpful – please press like button 🙂
- SAP Managed Tags:
10 Comments
