Building Connector Actions

Search…
We provide our SaaS customers an easy way to manage their own connectors and its actions and endpoints.
UI Form Schema Rendering
Below is an extensive list of form schema variations:
1
{
2
  "ui_form_schema": {
3
    "classicinput": {
4
      "required": true,
5
      "title": "input",
6
      "type": "text"
7
    },
8
    "date": {
9
      "title": "date",
10
      "type": "date"
11
    },
12
    "daterange": {
13
      "title": "date A and B",
14
      "type": "daterange"
15
    },
16
    "datetime": {
17
      "required": true,
18
      "title": "date and time",
19
      "type": "datetime"
20
    },
21
    "email": {
22
      "placeholder": "E-mail zum bestätigen",
23
      "title": "Email",
24
      "type": "email"
25
    },
26
    "multiselect": {
27
      "default": [
28
        "normal",
29
        "low"
30
      ],
31
      "enum": [
32
        "urgent",
33
        "high",
34
        "normal",
35
        "low"
36
      ],
37
      "allowCreate": true,
38
      "multiple": true,
39
      "title": "multi select",
40
      "type": "select"
41
    },
42
    "number": {
43
      "default": 2,
44
      "max": 3,
45
      "min": -1,
46
      "step": 0.25,
47
      "title": "Zahl zwischen -1 und 3",
48
      "type": "number"
49
    },
50
    "password": {
51
      "title": "password",
52
      "type": "password"
53
    },
54
    "singleselect": {
55
      "default": "problem",
56
      "enum": [
57
        "problem",
58
        "incident",
59
        "question",
60
        "task"
61
      ],
62
      "title": "single selct",
63
      "type": "select"
64
    },
65
    "switch": {
66
      "default": true,
67
      "title": "Aus/An",
68
      "type": "switch"
69
    },
70
    "textarea": {
71
      "info": "Type some text",
72
      "maxLength": 20,
73
      "minLength": 10,
74
      "placeholder": "Type...",
75
      "required": true,
76
      "rows": 3,
77
      "title": "textarea",
78
      "type": "text"
79
    }
80
  }
81
}
Copied!
To allow a user to add manually their own custom options in a select dropdown, add the below to:
1
"type": "select",
2
"allowCreate": true
Copied!
Multiple select
Example of a multi select in the UI form schema:
1
{
2
  "include": {
3
    "title": "Details to include",
4
    "type": "select",
5
    "multiple": true,
6
    "enum": [
7
      "owner",
8
      "creater",
9
      "updater",
10
      "source",
11
      "contacts",
12
      "sales_account",
13
      "deal_stage",
14
      "deal_type",
15
      "deal_reason",
16
      "campaign",
17
      "deal_payment_status",
18
      "deal_product",
19
      "currency",
20
      "probability",
21
      "created_at",
22
      "updated_at"
23
    ]
24
  }
25
}
Copied!
Rendered UI form schema
​
Example of a multi select in the URL parameters  to get a list as a result: [ "owner", "contacts",... ]
1
{% if include != [] %}&include={{include |replace("[", "")|replace("]", "")|replace("'", "")|replace(" ", "")}}{% endif %}
Copied!
​
Action endpoints and building their query strings dynamically
In order to build query strings dynamically (i.e. not having to take care of when to player a ? vs a &) always use & and our backend will dynamically take care of placing the ? correctly by replacing the first occurrence of & with a ? Note: This is only being done if the query string does not include a ?
Request body examples for dealing with files
Example for getting a file and uploading it to e.g. DropBox, GoogleDrive, etc. as a binary. The key `request_binary_url` is a reserved key and take whatever input it gets and converts it to a binary and sends it as such on a later following request.
1
{
2
  "request_binary_url": {
3
    "info": "The file can come from a previous step of a Locoia flow or from a static location on the web",
4
    "required": true,
5
    "rows": 2,
6
    "title": "File URL where the file is fetched from",
7
    "type": "text"
8
  }
9
}
Copied!
Example to make file-paths look right:
1
{
2
  {% if path[0] == "/" %}
3
    "path": "{{path}}"
4
  {% else %}
5
    "path": "/{{path}}"
6
  {% endif %}
7
​
8
  {% if parent_rev is defined %}
9
    , "parent_rev": "{{parent_rev }}"
10
  {% endif %}
11
}
Copied!
It's best to use if variable is defined always, even for required variables.
Custom Fields
In order to allow custom fields where the type may not be known to send data in the right format, the following formats have to be used.
Request Body
I.e. booleans and numbers without quotation marks the following line has to be inserted, instead of "{{item.key}}": "{{item.value}}", when configuring the connector action request body:
1
{% if custom_fields | length > 0 %},{% endif %}
2
{% for item in custom_fields %}
3
  "{{ item.key }}": {% if item.type == 'number' %}{{ item.value }}{% elif item.type == 'switch' %}{{ item.value | lower }}{% else %}"{{item.value}}"{% endif %}
4
  {% if not loop.last %},{% endif %}
5
{% endfor %}
Copied!
Endpoint
Custom fields can also be used in the endpoint:
1
{% if custom_fields is defined %}{% for item in custom_fields %}&{{item.key}}={{item.value}}{% endfor %}{% endif %}
Copied!
The most known use-case for this is for APIs, such as Zendesk or Salesforce, that are popular for using custom fields, added by each user individually.
Code Highlighting for SQL, htmlmixed, jinja2, javascript, python
Add code highlighting by making type `code` and adding the mode type to one of these five sql, htmlmixed, jinja2, javascript, python (letters all lower case). Further syntax highlighting can be added upon request as per: Code Highlighting​
1
{
2
  "myField": {
3
    "type": "code",
4
    "mode": "sql",
5
    "title": "My Title"
6
  }
7
}
Copied!
Nested Form Schema
Example image
Example code
1
{
2
  "clickEvent": {
3
    "title": "Click Event",
4
    "type": "nested_object",
5
    "children": {
6
      "shouldReactOnClick": {
7
        "title": "Click on/off",
8
        "type": "switch",
9
        "info": "Determinte if click on a value on the chart should open a link.",
10
        "default": false
11
      },
12
      "urlTemplate": {
13
        "title": "URL template",
14
        "info": "Base URL with placeholders (use the SQL columns with doubly curly braces).",
15
        "type": "text",
16
        "placeholder": "https://www.google.com/search?q={{category}}"
17
      },
18
      "test": {
19
        "title": "Test",
20
        "info": "test",
21
        "type": "nested_object",
22
        "children": {
23
          "testChild": {
24
            "title": "testChild",
25
            "type": "text"
26
          },
27
          "testChild2": {
28
            "title": "testChild2",
29
            "type": "text"
30
          },
31
          "test": {
32
            "title": "Test",
33
            "info": "test",
34
            "type": "nested_object",
35
            "children": {
36
              "testChild": {
37
                "title": "testChild",
38
                "type": "text"
39
              },
40
              "testChild2": {
41
                "title": "testChild2",
42
                "type": "text"
43
              },
44
              "test": {
45
                "title": "Test",
46
                "info": "test",
47
                "type": "nested_object",
48
                "children": {
49
                  "testChild": {
50
                    "title": "testChild",
51
                    "type": "text"
52
                  },
53
                  "testChild2": {
54
                    "title": "testChild2",
55
                    "type": "text"
56
                  },
57
                  "test": {
58
                    "title": "Test",
59
                    "info": "test",
60
                    "type": "nested_object",
61
                    "children": {
62
                      "testChild": {
63
                        "title": "testChild",
64
                        "type": "text"
65
                      },
66
                      "testChild2": {
67
                        "title": "testChild2",
68
                        "type": "text"
69
                      }
70
                    }
71
                  }
72
                }
73
              }
74
            }
75
          }
76
        }
77
      }
78
    }
79
  }
80
}
Copied!
Sending emails
Often email providers expect content to be send based64 encoded. Please use the Jinja filter base64_encode (or base64_decode) for this like this:
1
{{ myEmailContent | base64_encode }}
Copied!
Regular Expression (RegEx) Validation
To validate the user input for the fields, you can make use of RegEx in order to be fully flexible with the validation. To use it, these two fields need to be added to the form schema:
pattern -  The RegEx pattern (Note : The backslash (\) which is commonly used in RegEx patterns needs to be escaped, so instead of \ two backslashes need to be used: \\)
regexErrorMessage - The error message that should be displayed when the input doesn't match the pattern
For example the the FTP Helper' authentication form has a field for the Server URL, which validates the user input:
1
"server_url": {
2
  "title": "FTP Server URL",
3
  "type": "text",
4
  "required": true,
5
  "placeholder": "ftp://my.server.com:22",
6
  "info": "Start your path with the protocol (ftp/ftps/sftp), followed by the domain of your server and followed by the port.",
7
  "pattern": "/^s{0,1}ftps{0,1}:\\/\\/[\\w-_./]+:\\d+$/",
8
  "regexErrorMessage": "Required formats: ftps://server-domain.com:22 or starting with sftp:// ftp://"
9
}
Copied!
Example error message
For a typical connector the pattern looks often similar to the one of the Freshsales connector:
1
"pattern": "/^https:\\/\\/[\\w-_]+\\.freshsales\\.io\\/api\\/$/"
Copied!
In order to validate Jinja reference or url input this pattern can be used:
1
"pattern": "/^({{|{%http).+$/"
Copied!
If the entire input should match the pattern you need to include /^your_pattern$/.
^ is the start of the line and $ is the end of the line.
You can easily setup and test your RegEx patterns in tools like RegExr.
Ignore http errors
The following field `ignore_http_errors` can be included on any endpoint in order to exclude http errors. Like this
1
{
2
  "ignore_http_errors": {
3
    "type": "switch",
4
    "title": "Ignore http Errors",
5
    "default": false
6
  }
7
}
Copied!