DeskDirector Forms - Dynamic Fields

Dynamic fields provide a way to add and display dynamic content within your DeskDirector forms.

Usage & Limitations

Before continuing, it's important to provide some context regarding what these dynamic fields can and can't do.

• The dropdown menu for a dynamic field can display up to 30 items.
• Each item's name is limited to a maximum of 100 characters and must be a string.
• Each item's identifier is limited to a maximum 50 characters and must be a string.

Web Service (API) design blue print

Request (GET or POST):

https://{domain}/{path}?{query parameters}

Query parameters or properties in JSON body payload

• term Search term, use for type-ahead system
• ticketId Ticket ID that form is attached to
• access_token Access Token is an JWT token, where web service can use to gather user information. Such as user ID, email, company ID etc. It can be verified through an public hash key.
• access_token_expiration How long before access token expires (Number in seconds).

Example of GET request is:

https://test.deskdirector.com/api/v2/ddforms/dynamic/contacts?term=john&ticketId=&access_token={token}

Example of POST request is:

POST request is more secure than GET request. Since anything within body payload been encrypted and secured by HTTPS. Where anything passed through query parameter through URL are expost. This is by HTTPS design. Thus, access token is better passed through HTTP requesty body.

// POST https://host/api/path

{
    "term": "john",
    "ticketId": 3032,
    "access_token": "token",
    "access_token_expiration": 3600
}

Response

The response payload must be according to following JSON schema. It is case insensitive:

{
  "value": [
    {
      "name": "max length of 100 chars",
      "identifier": "max length of 50 chars"
    },
    {
      "name": "max length of 100 chars",
      "identifier": "max length of 50 chars"
    }
  ],
  "request": {
    "term": "search term",
    "ticketId": number
  }
}

Fallback "Other" Choice

Due to the inherently unreliable nature of web services, an escape option is provided to the user for all dynamic fields. This is so a user won't be prevented from completing a form in the event of API failure or the inability to find the correct choice (e.g. the contact they are looking for is not presented in the list, even though it should be).

The format of the other choice will be:

{
    "name": "Other",
    "identifier": "{field_identifier}_other",
    "selected": true
}

In the case where the "Other" choice is selected, a new choice will appear in the choices collection on the field and their answer will be placed into the value property on the field.

e.g.

{
    "type": "api_single_choice",
    "name": "Choose a contact",
    "identifier": "d4ptmn",
    "required": false,
    "choices": [
        {
            "name": "Other",
            "identifier": "d4ptmn_other",
            "selected": true
        }
    ],
    "meta": {
        "render": "radio"
    },
    "value": "Bob Smith"
}

Error Response

Any service API error should be according to the following schema. If the error format is incorrect, the portal should display generic error.

{
 error: string,
 errorDescription: string
}

If an error is returned from the API, the form will allow the user to skip the question. They will be presented with an "Other" choice.

The error will be reported to Application Insights.

{
 "name": 'DynamicFieldError';
 "customDimensions": {
  "form_entity_id": string;
  "field_identifier": string;
  "field_type": 'api_multi_select' | 'api_single_select';
  "url": string;
  [queryParamKey: string]: string;
 }
}

Deliver answer from previous fields

From portal version 3.15.1 (17th of Nov, 2020), dynamic field in form is able to deliver answer from previous fields. Desktop portal require version 4.x+.

To achieve delivery of answers to the target API, you should specify previous field identifier as query parameter.

• Field has to be before current field. It can be from previous sections.
• It can be any field, include other dynamic fields
• Field identifier should record as parameter key inside API URL.

Use build in priorities API as an example.

/api/v2/ddform/dynamic/priorities

For the identifier for each field, you can navigate to webhook page of given the form. On that page, it will breakdown all sections and fields with their associated identifiers.

To access webhook page, open the dropdown from top right corner of form editor, and open webhook page in another tab.

To add birthday and select the user's answer to 'priority request', we should translate API URL from above to:

/api/v2/ddform/dynamic/priorities?epzipi&l2lunn

'Select priorities' field should now able to pass selected contact ID and birth day value to given API.

For example:

/api/v2/ddform/dynamic/priorities?epzipi=1985-03-20​&​l2lunn=203

Frequently Asked Questions:

Q: What happens to an API response that contains more than 30 items?

A: From a user experience point of view, too many items will give the users a hard time to scan through, this is why the dropdown of a dynamic field will only display first 30 items. It is best to provide search capability at API level if there are more than 30 items.

Q: What if one of item has name more than 100 chars?

A: Dropdown of the dynamic field is limited to display 100 chars only. Extra characters will be chopped off upon form submission.

Q: What if one of item's identifier has more than 50 chars?

A: Similar as name, on form submission, extra characters will be chopped off.

Q: What if the identifier is essential and it is more than 50 chars? What can we do about it?

A: You can hash those identifiers into a fixed length, then store it inside a key value pair data table.

Q: What if dynamic field is required, but the given API is broken or throws an error?

A: Forms would allow submission without answer from the API. The error would be submitted alongside the ticket.

Q: Adding previous field identifier to dynamic field seems complicated - are there any improvements planned?

A: Yes, we are planning to improve UI/UX to support that, once implemented, you no longer have to specify identifier inside the API URL, until it's implemented, parameter key is an alternative way to achieve it ahead of admin portal improvements.