Part 2: Start Workflow from your HTML5 application

In my previous blogs, you learnt how to integrate your custom application UI as user task in workflow that is then shown in My Inbox app. While this is one part of the story, in another part you may want to start the workflow from your external user interface or any SAP Cloud based application.

You have modelled the workflow and deployed it in SAP Cloud Platform. Now, how will the workflow be triggered ? – It could be via an external application or other SAP Cloud Applications. For example: when the user form is filled and a button is clicked then a workflow has to be started – say an approval workflow for leave or approval for travel expenses or workflow for asset repair or extended approval workflow from SAP SuccessFactors application when the new hire is created etc.

From external application you can start the workflow by using publicly available Workflow Runtime API and making a small configuration in your external application. From SAP Cloud Applications, you can either directly call the workflow REST-based service via HTTP/HTTPS protocol or via SAP Cloud Integration service. For more details on the latter, you can refer my blog

⇒ There are two separate blogs on how to start a workflow from custom application for Neo and cloud foundry environment respectively: 

• This blog is for Neo Environment
• For Cloud Foundry refer blog

Here you go:

I am assuming you have an SAPUI5 application and have some action defined in the application to start the workflow, say a button click.

1. Open the SAPUI5 application in SAP WebIDE Full-stack
2. Define the destination route in neo-app.json in routes array:

   {
       "path": "bpmworkflowruntime",
       "target": {
           "type": "destination",
           "name": "bpmworkflowruntime",
           "entryPath": "/workflow-service"
       },
       "description": "Workflow Service Runtime"
   }
   ​

3. In the button action in Component.js or view.controller.js or where you have the action implementation do the following: (a) write the javascript function to call the API for fetching the XSRF token and (b) write the javascript function to call the API to start the workflow with desired initial payload

   _fetchToken: function() {
       var token;
       $.ajax({
           url: "/bpmworkflowruntime/rest/v1/xsrf-token",
           method: "GET",
           async: false,
           headers: {
               "X-CSRF-Token": "Fetch"
           },
           success: function(result, xhr, data) {
               token = data.getResponseHeader("X-CSRF-Token");
           }
       });
       return token;
   }
   ​

    

   »  where URL is <workflow-runtime-destination>/rest/v1/xsrf-token. You can find the destination in Connectivity –> Destinations in SAP Cloud Platform cockpit.

   »  bpmworkflowruntime is the default destination with ApptoAppSSO authentication type

   »  For more information on the workflow runtime API, refer the official API documentation

   _startInstance: function(token) {
       var model = this.getView().getModel();
       var inputValue = model.getProperty("/text");
       $.ajax({
           url: "/bpmworkflowruntime/rest/v1/workflow-instances",
           method: "POST",
           async: false,
           contentType: "application/json",
           headers: {
               "X-CSRF-Token": token
           },
           data: JSON.stringify({
               definitionId: <your workflow ID>,
               context: {
                   text: inputValue
               }
           }),
           success: function(result, xhr, data) {
               model.setProperty("/result", JSON.stringify(result, null, 4));
           }
       });
   }
   

   »  <your workflow ID> is the ID workflow. You can open the workflow SAP Web IDE and see the properties of the workflow to find the ID.

   »  inputValue is the initial payload with which the workflow starts. It can be your entire application model, a subset of your model or a completely new model.

   »  The only thing you have to ensure that the data model you pass must be of JSON type as the workflow API works on JSON body.

    

4. Finally, implement the button action to get the CSRF token and then call the public workflow runtime API to start the workflow with the token:

   buttonAction: function() {
       var token = this._fetchToken();
       this._startInstance(token);
   }
   ​

   Once the action is performed and the workflow has started successfully, you will see the response from API as:

   {
     id =13,
     definitionId=LeaveRequestWorkflow,
     definitionVersion=2,
     subject=Leave Request for Alice,
     businessKey=11203,
     status=RUNNING,
     startedAt=2017-12-03:40:60:40.000Z,
     startedBy=Lorin,
     completedAt=null
   }
   ​

Previous Related Blogs on Neo Environment
Understanding Custom UI Integration with SAP Cloud Platform Workflow
Part1A: Build your Custom HTML5 application in SAP WebIDE for Workflow
Part1B: Using your Custom HTML5 application as User Task in Workflow
Part1C: Working with Task APIs in your Custom HTML5 application

Related Blogs on Cloud Foundry Environment

• how to start workflow from custom application
• how to add start workflow custom UI as a tile in Portal Fiori Launchpad,
• how to use custom task UI as user task in your workflow
• how to call external service in the custom task UI