Personalisation

This is a developer feature. You will not be able to leverage this functionality without writing code.

There is often a need to be able to personalise the content of the form based on the logged-in user. To account for this need, we have added the personalisation feature allowing developers to:

• pre-fill form data
• change the form elements

Personalisation requires an API endpoint to return the new content for a form. The endpoint will have a request made to it every time a user opens the form.

Request

The request will be HTTP Post method with the following request headers:

Content-Type: application/json
Authorization: Bearer token (only if the user is logged in)

The request payload will be a JSON object, in the following format:

{
  "formsAppId": 1,
  "formId": 1
  "externalIdUrlSearchParam": "external-id-set-in-url",
  "draftId": "89705a1c-b28f-4d18-9dd8-8e2ecd058777",
  "preFillFormDataId": "72b11a5d-d1e5-4b69-a4ba-7de7d4c1e318",
  "jobId": "077e4335-9f33-4fd4-bb14-7a632813917b",
  "previousFormSubmissionApprovalId": "b41b6356-8607-4485-b8b6-534c274dcdb5"
}

Properties

formsAppId

The identifier for the App

formId

The identifier for the Form

externalIdUrlSearchParam

Your identifier provided via the URL when opening the form, will be set to null if not specified

draftId

The identifier for the draft if the user is attempting to resume a draft, will be set to null if not specified

preFillFormDataId

The identifier for the pre-fill data if the user is attempting to load pre-fill form data, will be set to null if not specified

jobId

The identifier for the job if the user is attempting to complete a job, will be set to null if not specified

previousFormSubmissionApprovalId

The identifier for the previous approval step if the user is attempting to complete a request for clarification as part of an approval flow, will be set to null if not specified

Response

The expected response from the endpoint should be in a JSON format. The properties you put in the JSON object response payload will be determined by your use case:

Pre-fill

To pre-fill form elements with dynamic data, return a "submission" property. The property keys within the submission object will be the name properties of the form elements you wish to pre-fill. E.g. If you have a form element with the name "email", you could return an object like so:

{ 
  "submission": { 
    "email": "user@domain.com"
  }
}

Change Form Elements

To replace the form elements dynamically, return an "elements" property like so:

{
  "elements": [
    // form elements go here
  ]
}

Note: you must return all of the elements for the form, not just elements to inject into the current form.

You can also return both properties to achieve both use cases in the same Personalisation endpoint.

Console

To add a Personalisation endpoint, navigate to the form you want to use. Open the Summary menu and scroll down to the Personalisation card. We offer two implementations: Custom URL and Hosted API. We recommend using the Hosted API option by leveraging OneBlink API Hosting. From here you can add your API endpoint.

Use Cases

Use Case 1: Pre-fill based on previous submission

If you have personal contact details that are required on an inspection form, you could use Personalisation to retrieve the last submission from the requesting inspector and pre-fill those details before they start completing the form. This removes the need for your inspectors to enter that information every time, saving them a significant amount of time. Retrieving the requesting inspectors previous submission can done using a OneBlink SDK.

Get Help

If you have any questions or would like assistance with setting up your Personalisation please contact us via this support portal or email support@oneblink.io. We are happy to assist in any way we can.