Creating a RapidForm through API

Follow the steps below to create a RapidForm through the Truto API.

Basic structure of a RapidForm

Taking the example of an Asana RapidForm which asks the user to select a Workspace and its Projects, it can be defined like so,

{
  "type": "form",
  "config": {
    "fields": [
      {
        "name": "workspace_id",
        "type": "single_select",
        "label": "Workspace",
        "help_text": "The workspace to sync",
        "placeholder": "Select a workspace",
        "required": true,
        "data_source": {
          "type": "unified",
          "resource": "ticketing/workspaces",
          "method": "list"
        },
        "options": {
          "value": "id",
          "label": "name",
          "subText": "id"
        }
      },
      {
        "name": "collections",
        "type": "multi_select",
        "label": "Projects",
        "depends_on": [
          "workspace_id"
        ],
        "help_text": "The projects to sync",
        "required": true,
        "data_source": {
          "type": "unified",
          "resource": "ticketing/collections",
          "method": "list",
          "query": {
            "workspace_id": "{{workspace_id}}"
          }
        },
        "disabled_text": "Please select a workspace",
        "options": {
          "value": "id",
          "label": "name",
          "subText": "id"
        }
      }
    ]
  }
}

• type specifies that it's a form.
• config.fields is an array containing all the form fields. The order of the array items dictates the order of the form fields in the UI.
• config.fields.name is the variable name that is stored in the context object of an Integrated account. This is the name that will appear in the Variables section in the UI and will be used as a placeholder in the Sync Job configuration.
• config.fields.type can be single_select and multi_select for now. Multi select fields will return an array of values.
• config.fields.label is the Label of the field that appears in the UI to the end user.
• config.fields.help_text is the help text that appears below the field to help the end user in selecting the values.
• config.fields.required marks the field as required in the UI where the end user needs to select a value.
• config.fields.disabled_text is used in multi_select fields when they are dependent on the value of another field. In the example above, Projects field requires a Workspace to be selected, so until a Workspace is selected the Projects field will show the disabled_text.
• config.fields.depends_on is an array used to create dependency between the fields. In the example above, Projects is dependent on Workspace, so the depends_on has the value workspace_id (name of the field that Projects field depends on). Multiple dependencies can be specified.
• config.fields.data_source specifies the data to be fetched from the Unified or Proxy API to populate the options in the single and multi select fields.
  • type can be unified for fetching Unified API data and proxy for fetching Proxy API data.
  • resource is the name of the resource endpoint to fetch the data from. For Unified API, the format is unified_api_name/resource_name.
  • method can be list or get. It can also be a custom method for Proxy API.
  • query is the query parameters to send to the resource endpoint. You can use placeholders to refer to the values of other fields in the form. In the example above, the query for Projects fields refers to the Workspace field's value through the name attribute - workspace_id.
• config.fields.options is the mapping for showing the options in the single dropdown and multi select checkboxes.
  • value the attribute in the data_source to use as the value.
  • label the attribute in the data_source to show as the label in the selection dropdown.
  • subText the attribute in the data_source to show as the help text to make a better selection or to distinguish two options with the same label value.

Get the installed integration

To create the RapidForm defined above, we'll first need to get the id of the installed Asana integration. Use the following request to get it,

curl --location 'https://api.truto.one/environment-integration?integration.name=asana' \
--header 'Authorization: Bearer <your_api_token>' \

{
    "result": [
        {
            "id": "09b8d7dd-d7c1-42ba-8fae-d3c9278ade35",
            "integration_id": "91dcffb7-d9db-4c70-9ac8-91c71578f9a0",
            ...
            }
        }
    ],
    "next_cursor": null,
    "limit": 500
}

integration.name can be used to filter the integration based on its identifier.

Use the result.id attribute in the steps going forward for the installed integration ID.

Add RapidForm to the installed integration

Now let's add the RapidForm defined above to the installed integration. To do this, issue a PATCH request on the installed integration with the request below. Use the id retrieved in the previous step.

curl --location --request PATCH 'https://api.truto.one/environment-integration/09b8d7dd-d7c1-42ba-8fae-d3c9278ade35' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <your_api_key>' \
--data '{
    "override": {
        "actions": {
            "post_connect_user_form": {
                "steps": [
                    {
                        "type": "form",
                        "config": {
                            "fields": [
                                {
                                    "name": "workspace_id",
                                    "type": "single_select",
                                    "label": "Workspace",
                                    "help_text": "The workspace to sync",
                                    "placeholder": "Select a workspace",
                                    "required": true,
                                    "data_source": {
                                        "type": "unified",
                                        "resource": "ticketing/workspaces",
                                        "method": "list"
                                    },
                                    "options": {
                                        "value": "id",
                                        "label": "name",
                                        "subText": "id"
                                    }
                                },
                                {
                                    "name": "collections",
                                    "type": "multi_select",
                                    "label": "Projects",
                                    "depends_on": [
                                        "workspace_id"
                                    ],
                                    "help_text": "The projects to sync",
                                    "required": true,
                                    "data_source": {
                                        "type": "unified",
                                        "resource": "ticketing/collections",
                                        "method": "list",
                                        "query": {
                                            "workspace_id": "{{workspace_id}}"
                                        }
                                    },
                                    "disabled_text": "Please select a workspace",
                                    "options": {
                                        "value": "id",
                                        "label": "name",
                                        "subText": "id"
                                    }
                                }
                            ]
                        }
                    }
                ]
            }
        }
    }
}'

The form definition is added to the following path, override.actions.post_connect_user_form.steps.

Accessing RapidForm values in Sync Job

The values selected by the user in a RapidForm can be accessed using placeholders in a Sync Job like shown below. The example is of a Sync Job which fetches tasks in selected projects in Asana. Learn more about Sync Jobs.

{
    "integration_name": "asana",
    "args_schema": {},
    "resources": [
        {
            "resource": "ticketing/collections",
            "method": "get",
            "loop_on": "{{collections}}",
            "id": "{{collections}}"
        },
        {
            "resource": "ticketing/tickets",
            "method": "list",
            "depends_on": "ticketing/collections",
            "query": {
                "collection_id": "{{resources.ticketing.collections.id}}"
            }
        }
    ]
}

In the example above, the {{collections}} placeholder refers to the name attribute of the Projects field in the RapidForm defined above.