Dynamic Lists

Dynamic Lists allow you to populate autocomplete, select, radio, and checkbox form elements with options returned from an API. They work similarly to Lists, but instead of configuring all options directly in the platform, Dynamic Lists retrieve options from an external service.

TABLE OF CONTENTS

• Creating a Dynamic List
• Expected Payload
  • Option Set JSON Example
• CORS HTTP Headers
• Filtering Dynamic Lists
  • Expected Attributes
• Multiple Attributes
• Code Example
• Setting Attributes
• Testing
• Offline Behaviour
• Getting Help

Creating a Dynamic List

Custom URL and Hosted Dynamic Lists can be configured using APIs. This allows you to integrate with an external data source and manage your list options outside the OneBlink platform.

A Custom URL Dynamic List requires you to provide your own API URL.

A Hosted API Dynamic List allows you to select from a Hosted API environment and a route configured within the platform.

If you are using an API to return a list, the endpoint must be configured with a GET method. This endpoint must return the expected payload format described below.

Expected Payload

Your API should return a JSON array. Each item in the array can include the following 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: The colour of the button when using radio buttons displayed as buttons. Optional.
• attributes: Values used to filter Dynamic Lists. Attributes contain their own label and value. Optional.
• imageUrl: An image used to provide additional context for the option. This must use a OneBlink S3 URL. Optional.

For more information about attributes, see the Filtering Dynamic Lists section 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"
  }
]

CORS HTTP Headers

When hosting your own Dynamic List, make sure your CORS configuration accepts the required HTTP headers.

Below is an example of accepted headers:

<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>

Filtering Dynamic Lists

Dynamic Lists can include attributes. Attributes are used to filter the list based on the value selected in another form element.

For example, you may have a list of users where each user has a supervisor. You can filter the user list so that only users assigned to the selected supervisor are shown.

Expected Attributes

Each attribute should include the following keys:

• label: The displayed name for the attribute in the Forms Builder. Required.
• value: The value that will be filtered by a separate configured option set. Required.

The option set may 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"
      }
    ]
  }
]

When a supervisor is selected, the list will be filtered to show only users with that supervisor.

When no supervisor is selected, the full list of users is shown. When Lisa Daniels is selected as the supervisor, the list is filtered to only display users assigned to Lisa.

Multiple Attributes

Attributes are an array, which means each option can have multiple attributes.

When multiple attributes are configured, an option will display if any of the attribute values match the configured filters.

For example, if you filter by both supervisor and position, the list will show users who match either selected attribute.

In this example, Alex and Mary have Lisa as their supervisor, and Alex and Jacob are in the Marketing team. Because the Dynamic List matches any configured attribute, all three users are displayed.

Code Example

Code examples are available in the OneBlink GitHub repository. The examples use standard Node.js and can be used in a OneBlink Hosted API or in your own code as a starting point:

Dynamic Form Element Options Example

Setting Attributes

When implementing attributes, you need to assign the form element that will be used as the filter.

Using the supervisor example above, the user list would be conditionally based on the supervisor element.

Testing

Once you have set up your endpoint in the OneBlink Console, you can use the Test button to check that the endpoint is returning data in the expected format.

If the test is successful, the platform will return the number of records found and allow you to view the response details.

Offline Behaviour

App users may be working with intermittent coverage or no coverage. In these cases, the app will continue to operate using a cached version of the Dynamic List results.

When the app is first opened, all Lists in all forms are automatically cached.

The app works with a connected-first assumption. If the user has an internet connection, options are populated directly from your API. If the user does not have an internet connection, the cached version of the Dynamic List is displayed.

Getting Help

If you need any assistance with Dynamic Lists, please reach out through the Report Issue menu or email support@oneblink.io.