Part 1C: Working with Task APIs in your Custom HTML5 application

In this concluding section of Part1, let us know how-to update the user interface to show the task data and workflow context.

The whole objective here is to use task APIs to (a) get task related data and enhance the workflow context (b) add task action button implementation and (c) bind the UI elements with the workflow context data.

So, when you want to use your custom UI application as a user task-interface of workflow then these steps need to be performed to ensure that workflow context and task context is seamlessly connected.

Each step mentioned below is not mandatory, you can choose to use them at your discretion and based on your requirement. But in most of the cases, for our internal showcase scenario, I have more or less followed the same steps and the integration of user interfaces works like butter.

Get started now:

1. Open the Web IDE
2. Open Component.js file of your project
3. Add the following code snippets in init function to:
   • Get the task instance data

     // Step 1: get task data
     var startupParameters = this.getComponentData().startupParameters;
     var taskModel = startupParameters.taskModel;
     var taskData = taskModel.getData();
     var taskId = taskData.InstanceID;
     ​

     

   • Get the workflow context and enhance it with the task data

     var processContext = new sap.ui.model.json.JSONModel();
     
     $.ajax({
     url: "/bpmworkflowruntime/rest/v1/task-instances/" + taskId + "/context",
     method: "GET",
     contentType: "application/json",
     dataType: "json",
     success: function(result, xhr, data) {
     //Get the process context
     processContext.context = data.responseJSON;
     
     //Get task related data to be set in ObjectHeader
     processContext.context.task = {};
     processContext.context.task.Title = taskData.TaskTitle;
     processContext.context.task.Priority = taskData.Priority;
     processContext.context.task.Status = taskData.Status;
     
     if (taskData.Priority === "HIGH") {
     processContext.context.task.PriorityState = "Warning";
     } else if (taskData.Priority === "VERY HIGH") {
     processContext.context.task.PriorityState = "Error";
     } else {
     processContext.context.task.PriorityState = "Success";
     }
     
     processContext.context.task.CreatedOn = taskData.CreatedOn.toDateString();
     }
     });
     ​

   • Get the task description and add it to UI model

     //get task description and add it to the UI model
     var jsonModel = new sap.ui.model.json.JSONModel();
     startupParameters.inboxAPI.getDescription("NA", taskData.InstanceID).done(function(dataDescr) {
     processContext.context.task.Description = dataDescr.Description;
     jsonModel.setProperty("/context/task/Description", dataDescr.Description);
     }).
     fail(function(errorText) {
     jQuery.sap.require("sap.m.MessageBox");
     sap.m.MessageBox.error(errorText, {
     title: "Error"
     });
     });
     
     jsonModel.setData(processContext);
     this.setModel(jsonModel);
     ​

   • Next, add buttons and their implementation in the task interface.
     Here in this example, I have just added one button, you can choose to create other buttons based on your project requirement like button to Reject or Confirm etc.

     //Implementation for the approve button action
     var oPositiveAction = {
     sBtnTxt: "Approve",
     onBtnPressed: function(e) {
     var model = that.getModel();
     model.refresh(true);
     //Call a local method to perform further action
     that._triggerComplete(that.oComponentData.inboxHandle.attachmentHandle.detailModel.getData().InstanceID, true,
     jQuery.proxy(
     //on successful competion, call a local method to refresh the task list in My Inbox
     that._refreshTask, that));
     }
     };
     
     //Add 'Approve’ action to the task
     startupParameters.inboxAPI.addAction({
     action: oPositiveAction.sBtnTxt,
     label: oPositiveAction.sBtnTxt,
     type: "Accept"
     //Set the onClick function
     }, oPositiveAction.onBtnPressed);
     

     — All the above code snippet is added to the init function of the Component.js file —-

4. Now, add few more functions in the Component.js file to:
   • Trigger action to complete the task.You need to implement this function for the button, whose click would complete the task. In this, you call task API to set the status as completed.You can find more details on the API here:
     https://help.sap.com/doc/40db36d987084ab09e496381090e9a2e/Cloud/en-US/wfs-core-api-docu.html

     //This method is called when the confirm button is click by the end user
     _triggerComplete: function(taskId, approvalStatus, refreshTask) {
     $.ajax({
     //Call workflow API to get the xsrf token
     url: "/bpmworkflowruntime/rest/v1/xsrf-token",
     method: "GET",
     headers: {
     "X-CSRF-Token": "Fetch"
     },
     success: function(result, xhr, data) {
     //After retrieving the xsrf token successfully
     var token = data.getResponseHeader("X-CSRF-Token");
     var dataText;
     //form the context that will be updated - approval status and the equipment list
     dataText = "{ \"status\":\"COMPLETED\",\"context\": {\"workplaceConfirmed\": \"" + approvalStatus + "\" }}";
     
     $.ajax({
     //Call workflow API to complete the task
     url:"/bpmworkflowruntime/rest/v1/task-instances/"+taskId,
     method: "PATCH",
     contentType: "application/json",
     //pass the updated context to the API
     data: dataText,
     headers: {
     //pass the xsrf token retrieved earlier
     "X-CSRF-Token": token
     },
     //refreshTask needs to be called on successful completion
     success: refreshTask
     });
     }
     });
     },
     
     

   • Finally, write a function to refresh the inbox once the task is completed

     //Request Inbox to refresh the control once the task is completed
     _refreshTask: function() {
     var taskId = this.getComponentData().startupParameters.taskModel.getData().InstanceID;
     this.getComponentData().startupParameters.inboxAPI.updateTask("NA", taskId);
     }
     ​

      

This completes the updates to Component.js file. Now let us modify the view.xml file to bind the UI element of the user interface such that they fetch the respective value from the workflow context

5. Open the view.xml and change the Text field of FirstName label element to {/context/user/FirstName} where {/context} reads the data from the workflow context and remaining path is the relative payload path as passed to the workflow.Similarly do the same for other elements as shown below.

6. Save and Deploy the SAPUI5 application
7. Start a new workflow instance with the following payload and open the task in My Inbox

   {
   "user":{
   "FirstName":"Kate",
   "LastName":"Beckett",
   "city":"London",
   "country":"United Kingdom"
        }
   }
   ​

Now you will see the data in the form data from the workflow context

With this we complete Part1 of our learning. In this part you learnt how to create an HTML5 application and modify the application artefacts so that it can be successfully integrated in user task of SAP Cloud Platform Workflow. You also learnt about task APIs and how they can be used to associate task data with workflow context, so that the text in the UI element are shown appropriately when the task in opened in MyInbox application.

In the upcoming Part 2 and Part 3 you will learn some advanced options which might help you while using your custom UI5 application as user-task or to start the workflow.

Previous 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

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