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 intoOneVuTest 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 inOpenProcess. 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"
}
k) 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.
l) 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.
m) Now let's say you want to automatically complete the step. To do this you need to retrieve the current step id for the process. So we call the Get Current Step API using the process id:
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.
n) 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.