Dynamic Lists

Dynamic Lists like Lists allow you to populate autocomplete, select, radio, or checkbox form elements. Where Lists are able to be configured in the platform Dynamic Lists allow you to call external services using an API. 

Creating a Dynamic List

URL and Hosted Dynamic Lists can be configured using APIs, allowing you to integrate with an external data source to manage your lists of options. URL requires you to add your own URL. Hosted API will allow you to select from a Hosted API environment and route configured within the platform. 

If you are using an API to return a list, the list must return from an endpoint that has a GET method configured. This is the endpoint needed to return the expected payload mentioned below. 

Expected Payload

Your API should return a payload in JSON format. It should be an array, with each item allowing four keys:

• value: the value that will be passed in the submission data (Required)

• label: the label that will be displayed to the user in the form (Required)

• colour: set the colour of your button when using radio buttons displayed as buttons (Optional)

• attributes: are used to filter dynamic lists, they contain their own label and value (Optional)

• imageUrl: are used to provide additional context to the option, these must use OneBlink S3 URLs (Optional)

For more on attributes see Filtering below

Option Set JSON example

[
   {
      "value":"1",
      "label":"Pass",
      "colour":"#00DD00"
      "imageUrl":"https://s3.ap-southeast-2.amazonaws.com/testapp.storage.test.oneblink.io/assets/user-uploads/6rtch-bgyt-jgygj-rdxj-76ehedt6d/tick.webp"
   },
   {
      "value":"0",
      "label":"Fail",
      "colour":"#DD0000"
      "imageUrl":"https://s3.ap-southeast-2.amazonaws.com/testapp.storage.test.oneblink.io/assets/user-uploads/juytg-syresy-vuytd-vjhtf-ytryt4duu/cross.webp"
   },
   {
      "value":"-1",
      "label":"N/A",
      "colour":"#CCCCCC"
      "imageUrl":"https://s3.ap-southeast-2.amazonaws.com/testapp.storage.test.oneblink.io/assets/user-uploads/iihfu-vhgrds-jhgj-jkgu6-hytryftvui7/na.webp"
   }
]

<httpProtocol>
  <customHeaders>
    <add name="Access-Control-Allow-Origin" value="*" />

    <add name="Access-Control-Allow-Methods" value="GET,OPTIONS,HEAD" />

    <add name="Access-Control-Allow-Headers"
      value="Accept,Authorization,Content-Type,If-None-Match,X-Amz-Date,X-Amz-Security-Token,X-Api-Key,X-OneBlink-User-Token" />

    <add name="Access-Control-Expose-Headers" value="Server-Authorization,WWW-Authenticate" />
  </customHeaders>
</httpProtocol>

For example, I have a list of users and each of those users have a supervisor. I am able to limit the list by selecting a specific supervisor.

Expected Attributes 

• label: the displayed name for the attributes in the forms builder — Required

• value: the value that will be filtered by a separate configured option set — Required

The option set will look like this:

    {
      value: 'ASmith',
      label: 'Alex Smith',
      attributes: [
        {
          'label': supervisor,
          'value': 'Lisa Daniels'
        },
        {
          'label': position,
          'value': 'Marketing' 
        }
      ]
    },
    {
        value: 'JCauthen',
        label: 'Mary Johnson',
        attributes: [
          {
            'label': supervisor,
            'value': 'Lisa Daniels'
          },
          {
            'label': position,
            'value': 'Operations' 
          }
        ]
    },
    {
        value: 'AWilliams',
        label: 'Alice Williams',
        attributes: [
          {
            'label': supervisor,
            'value': 'Liam Jackson'
          },
          {
            'label': position,
            'value': 'Sales' 
          }
        ]
    },
    {
        value: 'JDavis',
        label: 'Jacob Davis',
        attributes: [
          {
            'label': supervisor,
            'value': 'Liam Jackson'
          },
          {
            'label': position,
            'value': 'Marketing' 
          }
        ]
    }

Now when a supervisor is selected the list will be filtered so that it only include the users with that supervisor. See below:

When no supervisor is selected the entire list of users is shown. When Supervisor Lisa Daniels is selected the list is filtered to only display users assigned to Lisa.

Multiple Attributes

Attributes are an array, meaning you can have multiple attributes for the same option. 

When adding multiple attributes the options will display if ANY of the attributes are met.

So if we search on the position attribute to each of our users as well as the supervisor we will get the users who have ANY of those attributes.

As you can see, only Alex and Mary have Lisa as their supervisor, and Alex and Jacob are in the Marketing team so all 3 are being displayed.

Code Example

You can download code examples from our GitHub repo. This code is standard NodeJS, and can be used in a OneBlink Hosted API, or in your own code to get you started:

GitHub: Dynamic Form Elements

Setting Attributes

When implementing attributes you will assign the element which will be used as the filter.

Referring back to our Supervisor example you would conditionally base the users on the supervisor element as shown below. 

Testing

Once you’ve set up your endpoint in the OneBlink Console, you can click on the Test button. This will test your endpoint to ensure it is returning data in the expected format. If the test is successful it will return the number of records found, and allow you to view the response details.

Offline 

Your app users can often be in either intermittent coverage or no coverage at all. In these cases your app will continue to operate as usual, using a cached version of your Dynamic List results.

When the app is first opened, all Lists in all of your forms will be automatically cached.

The app will work in a “connected first” assumption, where if your user has an internet connection then your options will be populated directly from your API. If, however, they have no internet connection, the cached version of your Dynamic List will be displayed.

Get Help

If you have any questions or would like assistance with setting up your Dynamic Lists, please contact us via this support portal or email [email protected]. We are happy to assist in any way we can.