API Triggers & Notifiers in SAP Intelligent RPA

Introduction

With API triggers and notifiers, you can integrate SAP Intelligent RPA with external systems. API triggers provide the possibility to start a bot execution automatically based on an external event that occurs outside SAP Intelligent RPA via an API call. Of course, you want to know once the bot execution has started or has been executed successfully, if it has failed or if it has been canceled. This is the job of the notifiers. They are the complementing part of the API triggers and are responsible for communicating the execution status to the outside world. API notifiers in particular will communicate the execution status via API calls.

In this blog post, I will demonstrate how you can use API triggers and notifiers in SAP Intelligent RPA and how you can execute an API trigger. The following diagram gives an overview of the necessary steps needed for configuration:

1. Configuration in Cloud Factory

As a first step, you will create a project in the Cloud Factory. After generating a Package, you can add an API trigger:

You choose your environment, and then the trigger type. You can choose between attended, scheduled and API trigger. In this case, you would create a trigger of type API. You can give it a name and a description. You also need to select the scenario or process that will be executed by the API trigger:

After the creation is done, you can see the API trigger information. When executing an API trigger, you need to perform a POST request. The URL is the endpoint generated by the API trigger which you will call when executing it. The “irpa-trigger-token” secures this endpoint and you need to provide it either in the header or the body of your request (as irpaTriggerToken). You can also see an example payload. In the invocation context, which is basically a custom JSON object, you can pass transactional data or you can use it for call correlation. It is available in the attached notifiers and will not be processed by the bot during execution. The input is defined by the execution scenario and will be processed by the bot during execution (you can find more information about the input and invocation context here).

Once you created an API trigger, you can also add an API notifier. Notifiers are always attached to a trigger and you can use notifiers for API and Attended triggers. It is also possible to add multiple notifiers for a single trigger. In your environment, under “triggers” you can add a notifier to your trigger:

In this case, you would add a notifier of type API. The creation of an API Notifier contains a REST call configuration. First, you select on which job event the notifier should notify: success, start, canceled or failure. Depending on the event, there are different variables available that you can use in the payload. The invocation context is available for each event and contains the invocationContext JSON object provided in the API trigger payload. For success notifiers, you can additionally use the output variable which contains the output of the scenario or process executed by the bot. For failure notifiers, you can use the error variable in addition to the invocation context. The error variable contains detailed information about the error that occurred during the bot execution. You also need to define the Callback URL, which is the target endpoint of the application that you want to notify, and the HTTP Method. A selection between different types of authorization (None, Basic and OAuth 2.0) gives you flexibility on how to use this mechanism. If needed, it is also possible to add headers to the notifier. In the payload you can use the available variables which will be replaced at runtime with the actual data.

2. Get Service Key Credentials

In order to access SAP Intelligent RPA APIs from the outside, a service key from the service instance is needed. This can be created in the SAP Cloud Platform Cockpit by using the SAP Intelligent Robotic Process Automation Service. In the Cloud Platform Cockpit, after navigating to your subaccount, you need to create a new space. Select that newly created space and under “Service Marketplace”, choose the Intelligent Robotic Process Automation Service:

In the instances tab, create a new instance and then navigate to the Service Keys tab. Click the Create Service Key button to create a new service key. After the creation, you have the necessary information which is used to get the OAuth token: clientId, clientsecret and url (you need to add “/oauth/token” at the end of the URL provided). You can find some more detailed information about the creation of the service key credentials here.

3. Get OAuth Token

In the next section, I will show you how you to use the service key information to get the OAuth token using a REST client (here: Postman). You need to create a new request and under the Authorization tab, select “OAuth 2.0” as type and click on “Get New Access token”. Choose “Client Credentials” as Grant Type and enter the information from the service key. After entering the information, click on “Request Token” which will create your OAuth token.

4. Execution of an API Trigger

In this section, I will show you how you can execute an API trigger via Postman. After getting the OAuth token, you need to enter the API trigger URL as request URL and select the HTTP Method POST. In the headers tab, add a new header with the key “irpa-trigger-token” and paste the irpa-trigger-token value of your API Trigger. You could also provide the irpa-trigger-token in the Body of your request (add the value to the “irpaTriggerToken” property). Finally, you need to define the body of your request. You can refer to the example Payload of the API trigger. Depending on the scenario or process that will be executed by the API trigger, you need to provide the input data. You can also provide a custom JSON object in the invocation context which will be directly passed to attached notifiers.

After the configuration of the request is done, you can send the request which will trigger the bot execution. This can be verified by checking the jobs under the Monitoring tab in the SAP Intelligent RPA Cloud Factory. Once the execution has finished, you can check the notifier status in the job details. By clicking on the corresponding job, more details such as status history and notifier instances are provided. Once the execution has finished, you can see the status of the notifier under notifier instances.

Conclusion

I hope this gives a useful introduction on how you can use API Triggers and Notifiers. If you have any questions, don’t hesitate to leave a comment or contact me directly. Also, feel free to provide some feedback ?