Personalisation

Modified on Mon, 17 Jul, 2023 at 2:18 PM

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.




Was this article helpful?

That’s Great!

Thank you for your feedback

Sorry! We couldn't be helpful

Thank you for your feedback

Let us know how can we improve this article!

Select at least one of the reasons
CAPTCHA verification is required.

Feedback sent

We appreciate your effort and will try to fix the article