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 an insecure content. We have recently disallowed 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 fall back to us.

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: How do we add field ID from previous section to the statement content API query?

A: Depends on your API URL, whether it already contains query parameter or not. I will give two examples below. The field ID we will use field_id_one and field_id_two as an example. Purple part is your API URL, where pink suffix is the additional query parameter we have added.

https://your.api.domain/path?field_id_one&field_id_two

https://your.api.domain/path?your_query=xxxx&another_query=yyyy&field_id_one&field_id_two

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

DeskDirector Forms - Field value format for automation

Contact