Technology Blogs by SAP
Learn how to extend and personalize SAP applications. Follow the SAP technology blog for insights into SAP BTP, ABAP, SAP Analytics Cloud, SAP HANA, and more.
cancel
Showing results for 
Search instead for 
Did you mean: 
Dan_Wroblewski
Developer Advocate
Developer Advocate
930

SAP Build Process Automation has introduced the "Wait for an API Call" step, that pauses a process instance and waits for some system – any system – to call a specific API to resume the process instance. 

Dan_Wroblewski_0-1737539446734.png

NOTE: The step was scheduled to be introduced this week and next to all the SAP BTP landscapes, but there are no guarantees, and the release could be delayed.

 

Why Use It

I believe the idea behind this is a scenario where, from your process, you call an external system that must execute some task before the rest of the process resumes.

Dan_Wroblewski_0-1737552130496.png

For example:

  • A process receives an event from S/4HANA of a new employee/BP.
  • Some approval steps and other steps are executed.
  • Once approved, the process calls a Badge system to create an entry badge for the new person to get into the premises.
  • That Badge system does what it does.
  • When the Badge system is finished, it calls the API connected to the "Wait for an API Call" step, which resumes the process. 

P.S.: This is the idea behind our new SAP Build CodeJam.

 

How It Works

Add "Wait for an API Call" Step

Simply click the + sign to add a step, and go to Controls and Events area.

Dan_Wroblewski_0-1737543672895.png

Then select the Wait for an API Call step.

Dan_Wroblewski_2-1737543723602.png

You then give the trigger a name.

Dan_Wroblewski_3-1737543882718.png

That's all you need to do.

If you want the API call that resumes the process to include additional data, you can define "input" parameters. The UI is the same as when specifying Process Inputs.

Dan_Wroblewski_4-1737544055199.png

 

Create API Key

When calling the API for resuming the process instance, you must provide an API key with the proper permissions.

Go to the Control Tower, enter your environment, and select API Keys

Dan_Wroblewski_1-1737622472537.png

Click Add API Key.

  1. Give the key a name.
  2. Give the key the following scopes:
    • trigger_read
    • trigger_execute

When calling the API, you must send the API key under a header called irpa-api-key.

 

Call the API 

Once you deploy the process to an environment, a separate trigger is created in that environment for that step -- in the same way an API trigger is created to trigger a new process instance.

Go into your environment, then to the Triggers tab. You'll see a trigger for your wait step.

Dan_Wroblewski_0-1737544619770.png

Select the trigger and click View.

Dan_Wroblewski_1-1737544711471.png

This will show you API details that are slightly different than the API details for the standard process API trigger.

Dan_Wroblewski_2-1737544857795.png

The URL:

The payloads are also different.

  • Standard API Trigger: Contains a definitionId (plus all the process inputs) so the system knows which process you want to trigger.
  • Wait Trigger: Contains an executionId (plus any inputs defined for the Wait trigger) so the system knows which process instance needs to be resumed.

That API can only be used if the specified process instance is actually waiting for that specific API call.

Remember to send your API key under the irpa-api-key header.

 

Getting the Process Instance ID 

You will need to send the process instance ID to the 3rd-party system that will resume the process instance, so they can include it in the request body of the API.

One way to do this is to create a custom variable to hold the instance ID.

Dan_Wroblewski_3-1737546624287.png

Add Script Task to get the instance ID from the info object and put it in the custom variable.

Dan_Wroblewski_4-1737546722566.png

 

Deleting Wait Triggers

A kind of quirky behavior occurs when you delete a "Wait" trigger and then redeploy – AND you have process instances still running from the previous version of your process.

👉If you delete the "Wait" trigger, what happens to those process instances?

Well, no worries. 

The old processes will continue to run and the old "Wait" trigger can still be used. It will continue to appear in the Control Tower.

Dan_Wroblewski_0-1737547475060.png

When the last process that uses that trigger is completed, that "Wait" trigger will disappear from the Control Tower.

 

Errors

I have not re-created all the potential errors, but so far have figured out when the following status codes are returned when calling the "Wait" API.

  • 204: Success
  • 400: The GUID in the URL does not represent an existing "Wait" trigger, or you did not send an API key.
  • 403: The process instance ID passed in the request body does not exist or that process instance is not waiting for an API call.

This is just based on a few minutes testing, so it may not be 100% accurate. And there may be cases when the API returns other status codes. If you experience any, please let us all know.

 

 

3 Comments