This is without doubt the most exciting release of OpenProcess so far.
It extends the solution further and importantly enables you to interact with the solution using built in APIs. Unlike virtually every other back office application these APIs come as a part of OpenProcess. They are NOT separately chargeable. What's more these APIs adopt GDS best practice in terms of their design and enable testing with a built in Swagger UI function.
To provide an example this means that you could:
a) Build an online form in eDesigner
b) Kick off a process in OpenProcess from this
c) Pass the details of the specific process to a back office system
d) Then using the new APIs automatically:
- Add a note to the process when it is added in the back office
- Complete the process when that task is completed in the back office.
This functionality means you can now automate updates to processes automatically irrespective of use case.
One of the greatest challenges to innovation in digital transformation is the cost of APIs. With OpenProcess we're practising what we preach in terms of making the APIs free as a part of the function.
The following will now cover the content of this release:
General Enhancements
Before jumping into the new API capabilities we will cover some of the functionality that is more visible to users.
1) Enhanced UX for editing process steps
In the previous version of OpenProcess, you would click on the step of the process you want to update and this would take you into a new screen that you would then need to update and then go back to the steps screen. This is the previous step configuration screen:
This meant you lost context of the existing steps and also you'd need to wait for the step details to load and wait to go back to the steps screen on save.
Now we have introduced an improved user experience for this. When you view the list of steps in a process you will notice a little edit/bin icon to the top right of the step:
If you click on the edit icon the steps configuration slides out from the right:
Moreover, it is now more clear, by virtue of it being expanded by default, to see what actions will happen on step start/complete.
2) Auto-complete steps
Sometimes there are use cases where you want a step that automatically completes to save users needing to do this. Indeed sometimes you might want a process to automatically start/complete as soon as a form is submitted.
To cater for this there is now a new step type as shown below:
As the step automatically completes the only configuration needed is to set the name/description of it:
As there is only one step the instant the step is started it is automatically completed as shown:
OpenProcess API Enhancements
Our vision in 2015 was to enable users to build cross council online services that could kick off a process that could be tracked by citizens online in the same way that we would track a parcel. With OneVu and OpenProcess we realised that vision.
But a common question would be how can we remove the need for users to complete tasks in both a back office app as well as in OneVu. With the functionality delivered in this release we have provided an Open API that comes as a part of OpenProcess to enable process stages to be automatically completed.
Moreover, so that a back office or middleware understands the context of the process we have designed a new step type as a part of a process: REST API step. What this means is that when the data is passed to the back office we can also include details of the Process ID and Document ID to which the data relates.
We will first outline the new functionality and then provide a worked example for context and to reaffirm understanding:
1) A new REST API Step type
Now when creating a process you have a new option when creating a step which to create a REST API step at the bottom of the drop down:
Once this type is added the following configuration options are shown:
One can see that on top of the normal options there is one called:
- If the api call fails, allocate step to
So if it were to fail it would automatically assign it to a user of your selection.
There is also a Request Url setting. This will be the endpoint of the API that should be called when the process is started.
The Verb setting contains GET, PUT, POST for the purposes of futureproofing the functionality. Initially the POST option is the only one you will be using.
Likewise the Content type also needs to be in JSON format.
Request Headers
This is present to enable additional security on the post to the API should you're API require it. You can add n number of these.
Response Mapping
This enables you to map Key Information into a process from a response returned from an API. The key thing is this requires to be in JSON format. If a response is provided in anything other than JSON this will not work.
To provide an example let's say an API response provided a response which gave a case reference i.e.
{
"response:"200",
"3953403"
}
You could use the mapping element to automatically update the Key Information tab of the process in OpenProcess with this information. So the following shows how this would be mapped:
Once set up, as soon as the process is started, the API call is successful it would result in the following being added to the process:
For further information, the JSON path setting follows the standard methodology of doing this and more details of example can be found here:
https://www.newtonsoft.com/json/help/html/QueryJsonSelectToken.htm
2) Get Documents API
This API provides the means using:
- DocumentId
To retrieve a document associated with a process. As we will see with the worked example this is useful for the purposes of getting the XML document created as a part of an online form where the XML has been mapped in eDesigner.
3) Post a Note API
This API provides the means using:
- ProcessId
To add a note to a process. This therefore enables automated addition of notes to processes.
4) Get Current Step API
This API provides the means using:
- ProcessId
To find the current step id for a process. Therefore enabling this to be known should one want to complete it automatically, which is the next API.
5) Complete a Step API
This API provides the means using:
- ProcessId
- StepId
To automatically complete a step. I.e. back office update is completed and automatically sets the appropriate step to being completed.
A worked example
To aid understanding of each of the new functions we will walk through a worked example of all of these elements.
Let's say you need a new online service, which is Report Clinical Waste.
You would:
a) build the service using eDesigner as you would normally and then
b) add a Data Mapping XML template:
c) map the content from the form to the XML template:
d) test that the output is to your liking by looking at the Forms Portal:
e) publish the form to test
f) set up a new process with the first step being a REST API step type:
g) add an action to the online form in test in System Management to call the process you've just created in step f):
h) Go into OneVu Test and submit the form (NB - you only need to do this in OneVu if 'Customer account is mandatory' is set in the above action.)
g) Once submitted go into Search Processes in OpenProcess. You will see that the first step now has additional content that is not present on standard steps and if clicked on shows you the Request and Response sent/received from the API where the information was posted to:
A non-technical user has essentially created an online form with no code and then mapped it to an API!
The next section is where things become a little more technical.
h) In the request above we can see the 'payload' sent to the API. This contains both the ProcessId AND within the Links array the document that was created i.e. the XML document created from the online form. I.e.
"ProcessId": "0696d843-cef3-4af6-a4be-8d93191f8345"
"Href": "/open-api/documents/7dea286a-e44b-4414-b3e3-b28cfd8b6f62"
The DocumentId for the XML document is shown in bold above.
Swagger UI functionality
i) With this we can now jump over to OpenProcess's Swagger functionality found here (https://openprocess-test.azurewebsites.net/swagger/ui/index#/)
In order to use this functionality you will need to get the appropriate API Keys. To do so you need to go to Set Up in OpenProcess and click on the new API Developer Access function:
NB in order to access this you will need to be part of a group that has the new Api Admin permission:
Once you have got into the Api Developer Access area you are able to create API Keys yourself.
The name of the key is what will show when updates are made via API:
IMPORTANT
When you click save you are then given a ONE TIME ONLY means to copy/write down/put somewhere safe these codes as shown here:
So if you forget to do this you will need to create another key.
j) Now that we have done that we can go ahead and call the Get Documents API.
You can see that the documentid in the above request is placed into relevant field:
And the response we have back provides:
{
"filename": "Formmapping.xml",
"contents": "(base64 encoded content)",
"contentType": "text/xml"
}
j) We can then decode this content (this is useful for testing) into what was sent from the form:
<ServiceRequest> <Request> <RequestCategorisation> <FormType>NEEDLEREPORTTEST FormType> <RequestType/> <BackOfficeReference/> RequestCategorisation> <ClientInfo> <Title>Mr Title> <FirstName>J FirstName> <LastName>M LastName> <DOB>01/01/1980 DOB> <NINO/> <NHSNumber/> <DrivingLicenceNumber/> ClientInfo> <ContactInfo> <Email/> <Mobile/> <Telephone/> ContactInfo> <PropertyInfo> <AddressLine1>10 Downing Street AddressLine1> <AddressLine2>Test AddressLine2> <AddressLine3>Test AddressLine3> <AddressLine4/> <PostCode>B63 3TA PostCode> PropertyInfo> <RequestInfo> <RequestType>1 RequestType> <RequestSpecifics>It is dumped by the tree adjacent to the dog waste bin RequestSpecifics> <RequestLocation>4 RequestLocation> RequestInfo> Request> ServiceRequest>
Thereby enabling you to extrapolate the details for back office updates.
k) Now the back office is updated we might want to add a note to this process. This time, we will use the ProcessId passed in the original Request. With the note "Hello World" being added:
We can then check this update within OpenProcess:
As you can see rather than a user's name the name of the API Key is what is shown. So it would be worthwhile thinking of how you'd like this to be presented when creating your API Key.
l) Now let's say you want to automatically complete the step. To do this you need to retrieve the current stepid for the process. So we call the Get Current Step API using the processid:
We can see the response provides us with:
{
"stepId": "716896f7-7c2b-4080-a305-136bd239e9db",
"kind": "Standard",
"name": "Dealing with the dumped medical waste",
"startedOn": "2019-03-26T14:01:23.35",
"completedOn": null
}
I.e. the stepid, its type (kind), the name of the step, when it was started and the fact that it is not completed.
m) Using the stepid and processid we can then call the Complete a Step API to complete it:
With the response confirming that date / timestamp it was completed on.
Wrap Up
With this release we have shown that not only can you now automatically invoke back office APIs using data mapped from a form built without code. We have also shown how one can then subsequently update a process automatically using the inbuilt Open APIs.
This is us just getting started!
The following are the release versioning details:
| Release Date | Version Number |
| 26/03/2019 | 1.9 |