API and Adapter
Sending data to an API
The form builder platform has the ability to send the data to an API (application programming interface) endpoint. The data is a JSON format and includes the question, answers and links to any uploaded documents. The JSON is encrypted by a key pair. There are 2 Architecture Decision Records outlining exactly how they work: ( ADR-002 and ADR-003 )
Legacy
Config vars
Your form needs to be configured in Publisher to enable the JSON output feature. You must set both:
SERVICE_OUTPUT_JSON_ENDPOINTwhich is the external endpoint you want JSON sent to.SERVICE_OUTPUT_JSON_KEYwhich is the 16 byte shared secret used for encryption.
Encryption & Decryption
The JSON output is sent as an encrypted payload, you will need to decrypt it to use it. Images are also attached as URLs and stored encrypted.
JSON Payload
{
"serviceSlug":"my-form-name",
"submissionId":"3c50f43d-55a9-4ada-949d-b9bc2363966d",
"submissionAnswers":{
"first_name":"Luke",
"last_name":"Skywalker",
"email_address":"luke.skywalker@digital.justice.gov.uk",
"auto_name__1":"Not answered",
"auto_name__2":"Not answered",
"form_date":"1982-04-14",
"description":"Best day ever",
"address_1":"The Moisture Farm",
"address_2":"Mos Eisley",
"address_3":"Tatooine",
"postcode":"SW1A 9AJ",
"checked_no":"yes"
},
"attachments":[
{
url: 'example.com/1',
encryption_key: 'bar1',
encryption_iv: 'baz1',
mimetype: 'application/pdf',
filename: 'form1.pdf'
}, {
url: 'example.com/2',
encryption_key: 'bar2',
encryption_iv: 'baz2',
mimetype: 'application/pdf',
filename: 'form2.pdf'
}
]
}
The key in the submissionAnswers hash is the Input_name that is set on your form
field either in the editor or in the JSON.
Encrypted Body
The JSON payload is encrypted with JSON Web Encryption.
You can decrypt the payload using the shared secret key that you set as the
SERVICE_OUTPUT_JSON_KEY. For an example of this see the
HMCTS Complaints Adapter
Encrypted Files
Attachment payload
Attachments are sent in the JSON payload as an attachments array. Each attachment
object has the following data:
urlwhich is the URL to the encrypted file data. This expires after 15 minutes.encryption_keywhich is the key needed to decrypt the file.encryption_ivwhich is the initialisation vector needed to decrypt the file.mimetypewhich is the mimetype of the file.filenamewhich is the user generated name of the file.
Decrypting Files
Files are encrypted using the AES-256-CBC protocol. You need both the encryption_key and
encryption_iv to decrypt the file. These values are unique per file.
Links Expire
Please note that the URLs to the encrypted files expire 15 minutes after being generated. You cannot re-request new URLs so you will need to retrieve the file within this timeframe.
Creating the SERVICE_OUTPUT_JSON_KEY
Ruby
irb
require 'securerandom'
puts SecureRandom.hex(8)
This will generate a string of the correct size (16 bytes) - you can verify with string.bytesize in irb
HMCTS Adapter [Legacy]
Handles submissions for two forms on behalf of HMCTS. It maps submission payloads to the required keys before sending them on to the OPTICS case management system.
Repository: hmcts-complaints-formbuilder-adapter
Despite the name it accepts submissions for both complaints and correspondence form types.
The two namespaces associated with it are:
- hmcts-complaints-formbuilder-adapter-production
- hmcts-complaints-formbuilder-adapter-staging
Both forms require SERVICE_OUTPUT_JSON_ENDPOINT and SERVICE_OUTPUT_JSON_KEY to be set in their configuration before publishing.
Complaints
Form repository: fb-hmcts-complaints
It is called complain-about-a-court-or-tribunal in the
Publisher.
The API endpoint is /v1/complaint.
The first. It works. Just let it be.
Correspondence
Form repository: money-claim-queries
It is called Money claim queries in the Publisher.
The API endpoint is /v1/correspondence.
This has significant business logic in order to map the correct properties that OPTICS is expecting. The code is very much the documentation here so there is no need to repeat it.
The form caters for two different types of users (the person filling out the form). In terms of nomenclature the Applicant
is always the person filling out the form.
Representing
The Applicant in these instances are also known as a Representative. OPTICS also has the idea of an Intermediary
but currently there is nothing in the form that maps this in the payload.
They will be filling out the form on behalf of a Client or Subject.
OPTICS will log this user as an Agent.
Self Representing
The Applicant is filling out the form for themselves.
OPTICS will log this user as Main.
Other considerations
There is one unused field, CaseContactCustom18.Subject, which was meant the Intermediary mentioned above but
in the end it was decided not to be used. We have left it in there as OPTICS still allows the property in the payload despite it not being filled.
Comments
Form repository: hmcts-comments-form
It is called Comments Form in the Publisher.
The API endpoint is /v1/comments.
The adapter has to map the correct properties that OPTICS is expecting. The code is very much the documentation here so there is no need to repeat it.
Feedback
Form repository: hmcts-user-feedback-form
It is called User Feedback in the Publisher.
The API endpoint is /v1/feedback.
The adapter has to map the correct properties that OPTICS is expecting. The code is very much the documentation here so there is no need to repeat it.
Testing Adapter Changes
Changes to the adapater can be tested in the staging environment using the Optics UAT platform
To get access to the UAT platform, an account needs to be created using your ‘justice.gov.uk’ account. A request to create an account can be made to the HMCTS team.
Once access is gained, you can complete an online form that has been published to the test environment and your completed submission should be visible in the UAT platform. When entering a case from the online form, use ‘Aberystwyth Magistrates’ as the location.
Troubleshooting
If you are unable to see the case in UAT, it may be an issue with the Optics API key and secret.
An option is to request a new Optics API key and secret from the HMCTS team, and rotate these in the deploy repo.
Submission and Attachments Queues
The complaint form has a submission and a attachment queue. Feedback, Comments and Correspondence form have just one queue for submission. Those form get the data from the runner and maps it correctly with a presenter and create a case in OPTICS.
The complaint job also has to present the data in the right payload format. In addition, it has to get the attachments and decrypt them. Once this is done it can send the case to OPTICS. This process is described in the diagramm below:
HMCTS Adapter [v2]
In order to migrate HMCTS legacy forms created with FormBuilder to their new forms using MoJ Forms, the adapter has to be updated.
There are 3 forms being migrated : complaints, feedback and comments.
They use v2 API endpoints, respectively /v2/complaint, /v2/feedback, /v2/comment.
The mapping had to change because the field name for v2 services have changed. However just the names of the inputs have changed, the processing to produce the outputs of the adpter is the same. The behaviour and methods described for legacy adapter remain applicable for v2.
There is also the enquiry endpoint /v2/enquiry used by the MOJ - Online enquiry form - eng and cy forms.