Passing Linked Data in a Template Link Query String
When creating template links, LinkData is an optional parameter you can add to a template link query string. Using this parameter, you can pass additional data to the interview and compatible webhooks through the template link.
For example, you can use the LinkData property to identify users and pass user-specific answer data back to the interview.
Overview
You use the LinkData parameter to pass string data from the template link to the interview and any compatible webhooks you have configured in Advance. When you pass data to Advance using LinkData, Advance makes the data accessible to you in the following ways:
- From the user context data in the interview, using the HD_UserContext_LinkData variable.
- As part of the JSON data sent from compatible webhooks to your web application.
The following webhooks are compatible with the LinkData parameter:
- Custom interview event webhooks
- Load interview event webhooks
You can use the LinkData property to pass any desired string data to a webhook. However, a typical use case is to identify which user has used the template link. To do this, you use the LinkData property to pass a user's account ID from the template link through a webhook to a web application endpoint, then retrieve data specific to that user and return it to the interview as answer data.
The LinkData property allows a maximum of 100 characters.
You must not pass sensitive data using the LinkData parameter, as data passed in URLs is unsecured.
Workflow
The following diagram demonstrates the flow of LinkData data from a template link in your own web application to an Advance interview.
Sensitive Data
You must not pass sensitive data in the URL. URLs are unsecured as they can be accessed through web server logs, browser history, referrer headers, and so on. In particular, personally identifiable information and long-term secrets (usernames, passwords, API tokens, and long-lasting access tokens) should never be sent in the query string. You should use ephemeral tokens, such as CSRF tokens, where possible.
Getting a LinkData Value in the HotDocs Interview
During the interview, you can access any LinkData value passed from a template link by using the HD_UserContext_LinkData user context data variable in the template.
LinkData Sent from Advance to your Endpoint
Advance sends LinkData to the endpoints you configure when creating custom interview event and interview load event webhooks.
Custom Interview Event
The LinkData value passed in a custom interview event is displayed in the user context data of the JSON response.
Example JSON Response Data
{
"linkedVariable": { "ParameterValue": "Event Dialog Button" },
"userContextData": {
"UserId": "8727d822-7b4a-5f6d-ab56-781f498af6cc",
"UserFirstName": "John",
"UserLastName": "MacDiarmid",
"UserEmailAddress": "jm@example.com",
...
"LinkData": "ExampleValue"
}
Interview Load Events
The LinkData value passed in a load interview event is displayed in both the linkedVariable's parameter value and the user context data of the JSON response.
Example JSON Response Data
{
"linkedVariable": { "ParameterValue": "LinkData String" },
"userContextData": {
"UserId": "8727d822-7b4a-5f6d-ab56-781f498af6cc",
"UserFirstName": "John",
"UserLastName": "MacDiarmid",
"UserEmailAddress": "jm@example.com",
...
"LinkData": "ExampleValue"
}
Common Reference Topics
Among others, the following reference topics may relate to this conceptual area:
- Creating a Webhook
- Copying a Template Link
- Template Link Query String Parameters