Forge - IO - Dynamic IO

Dynamic Inputs & Outputs

NOTE: This content only applies to connectors created after 4/20/17, or those with a connector flag “enableNewMetadata” set to true. Otherwise, your connector will run on old dynamic input and output format. To use this new format, navigate to this URL in connector builder, with the appropriate values subbed in: https://build.ui.azuqua.com/(ORG ID)/(CONNECTOR NAME)/full. Once there, underneath the key “channelformat”, add in “enableNewMetadata” and set it to true.

To see documentation for the old format, see this link.

Dynamic inputs and outputs allow you to generate your input or output structure using a helper function. This structure will then be rendered onto your card’s UI. When setting up dynamic inputs/outputs, there are two items you’ll need to adjust. First, is declaring the helper function in the input/output section of your connector method. To do so, take the “attributes” section you would like to dynamically generate, and replace it with this (making sure you use the “regular” form of your function name):

[
  {
    "metadata": "helperFunctionNameHere"
  }
]

Using this, you can dynamically generate in most places. Say you wanted to dynamically generate all fields, including the header sections. Your input section would look like so (Example #1):

{
  "extensible": false,
  "attributes": [
    {
      "metadata": "getFields"
    }
  ]
}

Or, if you wanted to just dynamically generate the fields underneath a static header, you could define your inputs like so (Example #2):

{
  "extensible": false,
  "attributes": [
    {
      "name": "Heading Example 2",
      "attributes": [
        {
          "metadata": "getFields"
        }
      ] 
    }
  ]
}

Now that you’ve told the engine to pull your inputs/outputs from a helper function, we have to make sure to handle the second part of dynamic UI - making sure our helper function properly generates the UI. To do this, first create a helper function under “Functions”. Now, we need to make sure that your helper function outputs the correct information in the correct format. The general rule of thumb with helper functions that dynamically generate inputs/outputs is to have your helper function return exactly what you would have filled into your attributes array statically.

If we take Example #1 (see above), where we are dynamically generating an entire heading and all of its fields, we would need our helper function to output something like this:

[
  {
    "name" : "Heading For Example 1"
    "attributes" : [
      {
        "name" : "Field 1",
        "type" : "string"
      },
      {
        "name" : "Field 2",
        "type" : "number"
      }
    ]
  }
]

Note that this is a list, because if we had wanted more groups of fields, we would have needed another object that contained those fields. Or, if we wanted to complete Example #2, where we were just dynamically generating fields underneath a static heading, our helper function’s output would need to look something like this:

[
  {
    "name" : "Field 1",
    "type" : "string"
  },
  {
    "name" : "Field 2",
    "type" : "number"
  }
]

Once you’ve done those two pieces, you’ve successfully gotten dynamically generated UI done for your connector method! The above two examples are quite basic, so feel free to add any types, or flags you would like. Finally, dynamically generated UI is really helpful when they are dependent on other values. Specifically, most dynamic input/output situations rely on either authentication values (username, password, instanceURL, etc) or parameter values. Both of these value sets are passed in and available to helper functions that are called from the engine when UI is generated. Authentication information is available in your helper function using “{{auth.authFieldName}}”, and parameter information is available by using “{{input.data.paramFieldName}}”.