Previous post in this series: Discovering SCP Workflow – The Monitor.
In this post we explore the part of the SCP Workflow API that deals with workflow instances, and look particularly at how we initiate a new workflow instance, paying particular attention to how we request, and then use, a cross site request forgery (XSRF) token.
In Discovering SCP Workflow – The Monitor, we saw that the Workflow API exposes these main entities:
Workflow Definitions
Workflow Instances
User Task Instances
Messages
We also understand that a workflow instance is a specific occurrence of a given workflow definition. So one might guess, again correctly, that as the Workflow API is informed by REST principles, we should look to the Workflow Instances entity to see how we might start a new workflow instance using the appropriate HTTP method.
Workflow instance operations
In the API documentation, the operations for Workflow Instances are shown as follows:
Considering that initiating a new workflow instance is certainly not idempotent, our eyes are drawn towards: POST /v1/workflow-instances
While our eyes are wandering over the operations summary, they also surely fall upon the path info given for some of the operations … whereupon we can surmise that workflow instances have context, error messages, and execution logs (in fact, we looked at some execution logs in Discovering SCP Workflow – The Monitor). Perhaps we’ll cover that in another installment.
Creating a new instance
Looking in more detail at the requirements for the POST operation call, we can see the following:
* the resource here is protected against cross site request forgery and an XSRF token will need to be supplied in each request
* the payload to supply is to be in JSON format, with two properties:
* definitionId: the ID of the actual workflow definition
* context: the data pertaining to the particular workflow instance to be initiated
It’s great to see that a successful response returns HTTP status code 201 CREATED, as it should, in a RESTful sense. As far as I can see, the Location header, that should normally accompany a 201 response, is missing (and the request URL is certainly not the location of the newly created resource, which is the alternative when no Location header is supplied). But let’s leave that for another time.
Regardless, the process is therefore fairly straightforward. Let’s have a look at some sample code from Archana Shukla ‘s post “Part 2: Start Workflow from your HTML5 application” to embed the process into our brains.
Fetching the XSRF token
First, we have the _fetchToken function defined thus: _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; }
This _fetchToken method is called before the main POST method (that’s the one that actually initiates the new instance). Let’s look closely.
There’s a GET request made to the following URL: /bpmworkflowruntime/rest/v1/xsrf-token
This URL is of course abstracted by the destination target entry in the app’s neo-app.json descriptor file, which has an entryPath defined as “/workflow-service”: { “path”: “bpmworkflowruntime”, “target”: { “type”: “destination”, “name”: “bpmworkflowruntime”, “entryPath”: “/workflow-service” }, “description”: “Workflow Service Runtime” }
Digression: Resource URLs and how to think about them
It’s worth stopping briefly to consider what this means and in what way we look at this Workflow API (and APIs for other services), particularly around how we think about different parts of the path info.
By the way, the “path info” is that part of the url that starts after the hostname and (optional) port, running up to any query parameters. So for example, in the URL http://host.example.com:8080/something/something-else/this?n=42
the path info part is: /something/something-else/this
So, back to the digression.
When you enable the Workflow service in the SCP cockpit, a new destination “bpmworkflowruntime” appears, with the URL pattern that looks like this for production accounts: https://bpmworkflowruntimewfs-.hana.ondemand.com
and this for trial accounts: https://bpmworkflowruntimewfs-trial.hanatrial.ondemand.com
So, with this in mind, and looking at the pattern defined for the Workflow API production URL, as described in the Overview section of the Workflow API documentation on the API Hub: https://bpmworkflowruntime{provideracctname}-{consumeracctname} .hana.ondemand.com /workflow-service/rest
(split for legibility) we can see that “wfs” is the provider account name, and that /workflowservice/rest
is the “root” part of the path info for the Workflow API resources. In other words, this “root” part is common to all resource URLs in the Workflow API.
Taking my trial account for example, it resolves to this: https://bpmworkflowruntimewfs-p481810trial .hanatrial.ondemand.com /workflow-service/rest
A complete URL for a given API resource, such as for the workflow instances, would look like this: https://bpmworkflowruntimewfs-p481810trial .hanatrial.ondemand.com /workflow-service/rest/v1/workflow-instances
You can see that after the “root” part of the path info, we have the resource-specific part: /v1/workflow-instances
This might seem like an unnecessary diversion, but I think it’s important to understand how resource identifiers (URLs) are structured, so you can think about them in an appropriate way, and have that thinking permeate your code and configuration.
So I think here it might be nicer to have a destination target entry like this: { “path”: “workflowservice”, Host: bpmworkflowruntimewfs-p481810trial.hanatrial.ondemand.com > User-Agent: curl/7.52.1 > Accept: */* > X-CSRF-Token: Fetch > Host: bpmworkflowruntimewfs-p481810trial.hanatrial.ondemand.com > User-Agent: curl/7.52.1 > Accept: */* > Content-Type: application/json > X-CSRF-Token: 10D04A3B50DDE972188AA980DFDC56D9 > Content-Length: 69 > } [69 bytes data] GET /workflow-service/rest/v1/xsrf-token HTTP/1.1 > Host: bpmworkflowruntimewfs-p481810trial.hanatrial.ondemand.com > User-Agent: curl/7.52.1 > Accept: */* > X-CSRF-Token: Fetch > Host: bpmworkflowruntimewfs-p481810trial.hanatrial.ondemand.com > User-Agent: curl/7.52.1 > Accept: */* > Cookie: JSESSIONID=2C505C957AD0B1E76BD0535F0AF66C10DD824F88F2FF5F3463DD56AF5020E8D0; BIGipServer~jpaas_folder~bpmworkflowruntimewfs.hanatrial.ondemand.com=!kdw/bjE6WrgieXWwDhtcRsHHmTA76BykeAKzJSQCxdxLV7mHZYmet6Q6LvtTA6c9gdNjkRxfo0Gi4So=; JTENANTSESSIONID_p481810trial=iIN12zFf3bAmLNOQA3tuM4YVkPI2WgN060d0hgv%2B6W4%3D > Content-Type: application/json > Content-Length: 69 >
