Start Process from SAP Build Apps using APIs

SAP Build combines Apps, Process Automation and Workzone to empower users, both professional and citizens developers, to build applications, automate processes and design customised dashboards with simple drag-and-drop options, integrate smoothy with SAP and non-SAP systems and collaborate effectively between business and developers.

With SAP Build Apps gaining popularity among the community as an intuitive no-code development tool to design beautiful user interfaces, I have been often asked on how to start the processes from SAP Build Apps, that are built and deployed via new SAP Build Process Automation studio.

In this blog, I will explain you how you can execute a process from custom application using the latest features of:

• API Trigger, Workflow Public APIs in SAP Build Process Automation
• SAP BTP Destination to connect to SAP in SAP Build Apps

Assumptions:

• You already have an application built in SAP Build Apps
• You already have a process designed in SAP Build Process Automation

Add API Trigger in process

API trigger is a new feature in Process Automation through which you can start or trigger the process using public REST APIs from anywhere – be it custom application, integration flows, CAP applications and from any SAP and non-SAP systems where there is provision to call APIs.

You can add API trigger to any existing process (where you might have used Form earlier) or you can create trigger to be added in new process. As there can be only one-way to start the process – form or API trigger – you will have to delete the start form first to be able to add API trigger.

Now, let us add an API trigger to a new process

You can give any name to the API trigger.

• Once the API trigger is created, you can click on “empty” canvas and you will see Inputs tab from where you can Configure the input fields that will be used to start the process.
• When you will create the API trigger an input structure will for formed with the name of the API trigger

In the configuration dialog, you can choose the input field name of your choice. The type could be some standard type like String, Number etc. Or an already available datatype. If you choose the datatype, then all the fields of the data types will automatically be part of the input fields.

• You can also choose a List as input if you want to pass multiple input or collection to the process like Sales Order Items etc.
• You can also choose input fields based on your requirements like combination of datatypes or standard fields. For example: in screenshot below I have used salesOrder type and then added two more inputs of standard types (customerName > String, orderStatus > String)

Model the process

While modelling the process, you can use the fields from the start process context to map the subsequent fields of the process activities.

Note: the fields from the API trigger will appear under Process Start Inputs node

Update API Trigger

You can edit, deactivate, or delete the API trigger properties from Triggers tab in the respective process builder overview. Deactivate means that while the trigger exists in design-time, but you can consume it in runtime. Delete will permanently delete the trigger from design-time but for already deployed process the trigger will still exist at runtime. In general, any changes in the trigger will be affective only when the process is released and deployed.

note: All the API triggers that are created in that project will be shown.

Release and deploy the process with API trigger

Once you have finished designing your process, you have to release and deploy the process so that it can consumed via APIs.

• If you go into the deployed view of the process, you can see the API details of how you can call the API Trigger.
  • The API triggers can be called via the public REST API
  • The API are available in API Business Hub
  • The URL shown in screenshot below is the complete API URL where:
    • https://spa-api-gateway-bpi-eu-prod.cfapps.sap.hana.ondemand.com : is the host URL and will change depending upon the system you have deployed the process
    • /workflow/rest/v1/workflow-instances: is the relative URL to start the workflow and remains static.
  • Method: POST
  • The payload in the screenshot is the body of the POST API call
    • The API documentation to initiate the workflow/process can be found in API Business Hub. [Workflow Instances > POST]
    • As per the documentation, the body for API call has to be given as:

      {
      
      "definitionId":  "<process definition ID>",
      
      "context”: {}
      
      }

• Context of the workflow API can be viewed and copied from the process trigger (as shown in the screenshot below)

• where definition ID is the ID of the workflow after it is deployed (note: you can get the workflow definition ID from Monitor application as shown in the screenshot below).

Consume the Workflow APIs to start the process/workflow

All Process Automation APIs (except Inbox APIs which are OData v2 API) are REST APIs which are based on OAuth 2.0 and other methods like API Keys. Explore them from API Business Hub

Getting authorization credentials

Once you have deployed the process with API trigger, to start the process you will need Authorization credentials to call the APIs. You will find these credentials in SAP Build Process Automation service instance.

Note: you have to create a service instance of SAP Build Process Automation from Instances and Services section in BTP cockpit, and then create a service key inside service instance to view the authorization details (this is standard BTP concept for connectivity)

Upon viewing the service key credentials, you can find different information like api-endpoint, client-ID, client-secret, token-URL, cloud-service-name, xsappname etc. These different credentials will be used when you want to call any SAP Build Process Automation APIs like getting list of deployed workflows, getting task for a user, invoking business rules, calling process visibility APIs etc.

Process Automation APIs can be called via different authorization protocols like authorization code and client credentials (read more). You can use them based on your needs as whether you want to access the APIs via technical user (which means client ID) or via a logged in user (which means authorization code or user token)

Testing Workflow APIs

Before consuming the workflow APIs in any application, it is important that you test it to ensure that you have right URL, credentials, and body for successful API call.

You can test the API via API Business Hub or any REST client of your choice using the authorization credentials obtained from the service-key.

Accessing the Workflow APIs

With these service credentials, you can now either create a destination to call process automation APIs in any application or you can directly consume them in you CAP or SAPUI5 applications using the api-endpoint and OAuth2.0 details.

Note: you can follow my earlier blog on how to start workflow from custom SAPUI5 application. All you have to do is adapt the sap.cloud.service.name, endpoint url, and service instance details as per your SAP Build Process Automation service instance.

In this blog, let me create a destination which will be called from the application to access the workflow APIs. Let us understand different destination configuration:

Destination URL: service-key endpoint url

Authentication: you can use OAuthClient2Crendetials or OAuth2JWTBearer or OAuth2UserTokenExchange etc. depending upon which way you want to connect or call APIs

If you choose OAuthClient2Crendetials then you get options to add:

• Client ID: which is service-key uaa client id
• Client Secret: service-key uaa client secret
• Token Service URL: service-key url appended with /oauth/token like https://my-account.authentication.sap.hana.ondemand.com/oauth/token

Note: The additional properties are for discovering this destination in SAP Build Apps.

Consuming Workflow APIs in SAP Build Apps

SAP Build Apps have recently released BTP Destination feature through which you can connect to SAP BTP system and call APIs deployed in SAP BTP platform without the need to worry about CORS issues.

If you want to start the workflow from application designed and deployed in SAP Build Apps or want to get all workflow definitions etc. – all you need do is:

1. Create destination in BTP Cockpit
2. Keep a note of the body of the API Trigger with definitionID and context

In SAP Build Apps,

1. Add the data entity for REST API Integration via SAP BTP Destination

2. Configure the BTP Destination with resource name of your choice and choose the destination name from the drop down. All destinations created in SAP BTP cockpit with property AppgyverEnabled = true will automatically be shown.

Next is to create the source schema which will be input to the API. Now as you want to start the process, you need to construct the schema same of the body of the POST API call which is:

{
"definitionId":  "<process definition ID>",
"context”: {}
}

Using the ADD NEW, you can create schema structure with definitionId, context  and inside construct you have to create the structure as in API trigger.

note: Schema fields are case-sensitive so ensure that you use the field name as defined in your process API trigger.

Finally, choose what API method(s) which you want in this data entity like create (which is POST), update (which is PATCH), list (which is GET) etc.

In this blog example, I want to configure create:

• • Set Request Headers as Content-Type as application/json
  • Set Request body as a formula:

note: It is mandatory to be configured with API calls that needs JSON body. This function ENCODE_JSON just ensures that the schema is converted and sent into JSON format.

ENCODE_JSON({ "definitionId": query.record.definitionId, "context": query.record.context})

You can now Test the data entity configuration to ensure that the process is triggered successfully.

3. Use the data entity in the SAP Build Apps application

In this blog example, I have added a button to start the process. In the logic of the button, I have added a create record data (because a new record or workflow instance has to be created.

In the properties, choose data resource that is created earlier. In my case I have added custom object where I have mapped the data resources fields with actual application fields.

The Sales Order is a variable here which is used to map the input fields in the forms.

So you saw how easily you can integrate process with application using APIs. In same way you can all any process automation APIs in your custom applications be it SAPUI5 or CAP.

To summarise the steps:

1. Enable SAP Build Process Automation in your account
2. Create service instance and service key in you account
3. Access Process Automation APIs in API Business Hub to view the API documentation
4. If you want to start the process using API then:
   • Add API trigger in the process
   • Deploy the process
   • Copy the body of the API trigger
5. If you want to start the process from SAP Build Apps
   • Create destination in BTP cockpit using service instance
   • Create data entity of SAP BTP Destination in SAP Build Apps
   • Add data logic to the control with created data resource

You can follow us and read more blogs on our SAP Community