DeskDirector Forms - Dynamic content

Jason He Updated by Jason He

Dynamic content is similar to dynamic field, where our form will hit an API defined by you and render content based on your API's result. It is a great way to display custom content at the time of user filling the form. It is secure and customizable.

Similar to Microsoft's Adaptive card, it can render different types of content based on the API result.

API design blue print

To use dynamic content, you need to have software developer to help you design API, or consult with our support to quote on consultation.

The API you create should meet following requirement.

  • Your API should take POST request call
  • API can optionally use the access_token and ticketId from POST request's JSON body payload to understand who is filling the form, and which ticket it belong to. That way you can render more customized content.
  • Respond with correct CORS header. Since your API will be under different host than our client portal, thus browser will ask your permission to allow our client portal to view the response. Without correct CORS header within HTTP response, our client portal won't be able to render any content.
  • Valid response format (Which I will explain below)

Example of HTTP request initialized by client portal.

POST https://your.host/path
Origin: https://xxx.deskdirector.com
Content-Type: application/json

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

Example of HTTP response from your API

HTTP/1.1 200 OK
Access-Control-Allow-Origin: *
Content-Type: application/json

{
"value": [
{
"type": "markdown",
"text": "### Content you would like to **render**.",
"color": "accent"
},
{
"type": "list",
"value": [
{
"title": "Title of the list item",
"description": "Optional description",
"url": "https://your.host/optional/link"
},
{
"title": "Second item without link",
"description": "Optional description"
},
]
},
{
"type": "stats",
"value": [
{
"title": "Num of open tickets",
"value": "34",
"color": "accent",
"secondary": {
"value": "from 100",
"color": "light"
}
}
]
}
],
"request": {
"ticketId": 3032
}
}

Response definition in TypeScript

From above example, you can see what kind of possibility your API can return, below I will write down the TypeScript spec for your API's response.

interface ContentRequest {
ticketId?: number;
access_token: string;
[key:string]: string[] | number | string;
}

type ContentType = 'list' | 'stats' | 'markdown';
type ContentColor = 'default' | 'accent' | 'good' | 'warning' | 'attention' | 'light';
type Content = ListContent | StatsContent | MarkdownContent;

interface ContentResponse {
// maximum of 5 contents.
value: Array<Content>;
request: ContentRequest;
}

// List
interface ListItem {
// max length of 200 chars
title: string;
// max length of 1_000 chars.
description?: string;
url?: string;
}

interface ListContent {
type: 'list';
// max of 30 items
value: Array<ListItem>;
}

// Stats
interface StatsItem {
// max of 50 chars
title: string;
// max of 50 chars.
value: string;
color?: ContentColor;
secondary?: {
value: string;
color?: ContentColor;
}
}

interface StatsContent {
type: 'stats';
// max of 30 items
value: Array<StatsItem>;
}

interface MarkdownContent {
type: 'markdown';
// maximum of 5_000 chars.
text: string;
color?: ContentColor;
}

Example of rendering.

FAQ

Q: The property name within responded JSON payload, is it case sensitive?

A: Yes, it is case sensitive.

Q: What happen to items or properties that has exceeded limit?

A: Our client portal will truncate any additional chars or items.

Q: Why do we need dynamic content rather than put iframe inside field's description?

A: iframe inside Markdown is insecure content. We have recently disallow any raw HTML to be rendered inside markdown. Even though you can claim your code and your responsibility, but when things go wrong, you will definitely after us. So, to provide a secure platform is essential for the era we are currently live on.

Q: Will dynamic content able to refresh based on the answer from other field?

A: No, not at moment. For now, you can put field ID within your API URL's query parameter, we will pass the value to your API at the time of rendering. Thus, content based on previous section is the way to go.

Q: Where can I setup dynamic content?

A: You can setup within statement field. Statement field was originally designed for content play. Thus, it make sense to introduce under that field.

Q: Have you considered to allow dynamic content under other field?

A: No, not at moment. Since dynmaic content allow multiple content to be return and rendered. Too many content could impact readability of form field.

How did we do?

Importing Wufoo Forms to DD Forms

Contact