Add dynamic input fields: HTTP example

This is an Early Access feature for existing Workflows users. To enable it, use the Early Access Feature Manager as described in Manage Early Access and Beta features.

Builders can use helper flows to populate a card’s inputs dynamically when a request to an API is needed to retrieve a list of available fields, or the list of fields required for the action changes based on a user’s choices in the options section.

The following basic example uses two flows to create a simple list of inputs: a processing flow that shapes the results into the correct list of objects, and a flow to retrieve the list of fields itself from a service. This is often used when a service allows for the creation of custom fields or other schema modifications to a user’s instance. This is only an example meant to relay the basic required flow building.

Build a processing flow

A processing flow accepts each individual item from the list of items returned by the retrieval flow that's documented in the next section. It's used to extract the necessary information from each object and format it into the correct shape with the correct keys.

In a scenario, a service returns a simple list of JSON objects that represents the fields that are available in a user's tenant. The processing flow will take the object for each field (for example, Summary, Priority, and Due Date) and format it so the platform can display the list as inputs on the card. This is an example response for illustration purposes only.

Copy
[
   {
      "required":true,
      "schema":{
         "type":"string"
      },
      "name":"Summary",
      "key":"summary"
   },
   {
      "required":false,
      "schema":{
         "type":"number"
      },
      "name":"Priority",
      "key":"priority"
   },
   {
      "required":true,
      "schema":{
         "type":"date"
      },
      "name":"Due Date",
      "key":"date"
   }
]

The goal of the flow below is to turn the above API response into the Workflows supported JSON below.

Copy
[
   {
      "displayname":"Summary",
      "name":"summary",
      "type":"Text",
      "required":true
   },
   {
      "displayname":"Priority",
      "name":"priority",
      "type":"Number",
      "required":false
   },
   {
      "schema":{
         "type":"date"
      },
      "displayname":"Due Date",
      "name":"date",
      "type":"Date & Time",
      "required":true
   }
]

  1. Click + New Flow to create a new flow.

  2. Add a Helper Flow card as the first card in your flow.

  3. Click Save and name the flow Format Input Fields.

  4. Enter Processes a list of items and reformats the list to be used as an input list as the flow description, select Save all data that passes through the flow, and click Save.

  5. Add a field to the Helper Flow card by clicking Click or drag to create. Add a label, enter field_object as its name, and then click Enter.

  6. Select Object as the field type.

  7. Add an Object Get Multiple function card to the flow.

  8. Drag the field_object field from the Helper Flow card into the object input of the Get Multiple card.

  9. Add the key names for the values you want to extract as outputs to the Get Multiple function. Using the above JSON as an example, those would be name, key, required, and schema.type. Note that required is a True/False boolean field.

  10. Add a Branching Lookup function card following the Get Multiple function card.

  11. Since the field types (schema.type) from the service don’t line up with the field types used by Workflows, we’ll want to convert those using the Lookup function card. Drag the schema.type field from the Get Multiple function card into the Value field of the Lookup function card.

  12. Enter the type string under the When Value is column, and Text under the Then Result is column.

  13. Enter the type number under the When Value is column, and Number under the Then Result is column.

  14. Enter the type date under the When Value is column, and Date & Time under the Then Result is column.

  15. Enter Text in the Otherwise Result is field to make sure that an unknown types get a type added.

  16. Rename the output on the Lookup card to converted_type.

  17. Add a field called displayname to the Return card by clicking Click or drag to create, and drag in the name field from the output of the Get Multiple function card.

  18. Add a field called name to the Return card by clicking Click or drag to create, and drag in the key field from the output of the Get Multiple function card.

  19. Add a field called type to the Return card by clicking Click or drag to create, and drag in the converted_type field from the output of the Lookup function card.

  20. Add a field called required to the Return card by clicking Click or drag to create, and drag in the required field from the output of the Get Multiple function card.

  21. Save and test your flow by pasting a single object from above into the field_object field on the test dialog.

Build a retrieval flow

A retrieval flow is used to retrieve a list of objects from the service. It makes a HTTP request, identifies the list of objects in the request, and passes the list to the above Format Input Fields processing flow where the list gets shaped into the correct format.

  1. Switch to the Flows tab. Click + New Flow to create a new flow.

  2. Add a Helper Flow card as the first card in your flow.

  3. Click Save and name the flow Retrieve Input Fields.

  4. Enter Retrieves a list of available fields and format the list to display as inputs on the connector card as the flow description, select Save all data that passes through the flow, and click Save.

  5. Add a Flow Control Call Flow function card as the first card in the flow.

  6. Click Choose Flow.

  7. Build an httpHelper flow or select a previously created http_helper flow. See Build an httpHelper flow. The card is automatically populated with the inputs defined in the http_helper flow.

  8. Enter GET as the request method.

  9. Enter the relative URL for the endpoint from which you’ll receive the list of fields.

  10. Drag the auth object from the Child Flow card to the Connection input field of the Call Flow function card.

  11. For the outputs on the Call Flow card, you’ll need to define the same keys as the http_helper flow’s outputs: status_code (Number), headers (Object), and body (Object).

  12. Add a List Map function card to the flow.

  13. Drag the body field from the Call Flow function card into the list field of the Map function card. Remember that this assumes the same object shape as provided in the above object example.

  14. Click Choose Flow and select the List Input Fields flow from the previous example.

  15. Select the dropdown beside field_object and select Item. This will pass each item from field_object to the processing flow and return a new, correctly formatted list.

  16. Rename the output on the Map function card to new_field_object.

  17. Create a field on the Flow Control Return function card by clicking Click or drag to create and label the field output. This label is required to be recognized by the platform.

The label output is required for this field. If you assign any other label to this field, it will not be recognized by the platform.

  1. Drag the new_field_object field from the Map function card into the output field on the Return card.

  2. Save and test your flow.

Call the flow from the Inputs dialog

These flows get called from the Inputs section of the dialog. Here is a quick example of how to use these flows with the dynamic inputs functionality.

  1. Switch to the Flows tab. Click + New Flow to create a new flow.

  2. Add an Action card as the first card in your flow.

  3. Click Save and name the flow Create Item.

  4. Enter Create a new item using the custom fields implemented on your instance. as the flow description, select Save all data that passes through the flow, and click Save.

  5. Click Add Inputs on the Connector Action card.

  6. Click on the more actions menu next to the Add group button and click Add Dynamic Fields.

  7. Update the Group Name field with a descriptive string about the fields that you’re retrieving. Dynamic Fields are all contained in a single group.

  8. Click Choose Flow.

  9. Select the Retrieve Input Fields flow that you already created.

  10. Click Save.

  11. To test these flows, go to the Deployment tab and click Deploy test version.

  12. Once the deployment is complete, navigate back to the flow builder by clicking Home in the top menu.

  13. Create a new flow, and add the connector action to the flow. The input fields should appear on the card.

Next steps

Build an httpHelper flow