Interface

Interface describes the structure of output bundles and specifies the parameters which are seen in the next modules.

Interface uses the syntax of the parameters.

Parameters

The following basic common settings are only supported in the interface:

• "name": <String>,

• "label": <String>,

• "type": <String>

Since Interface describes only parameters that can be used in other modules, the type will never be Folder, File, Filter, Hidden, Path, Pkey, Select

Arrays and Collections

Arrays and Collections use the syntax spec to specify their structure.

Simple Array

{
	"name": "emails",
	"spec": {
		"type": "email",
		"label": "Email"
	},
	"type": "array",
	"label": "Emails"
}

Array of Collections

{
	"name": "emails",
	"type": "array",
	"label": "Emails",
	"spec": [
		{
			"name": "email",
			"type": "email",
			"label": "Email"
		},
		{
			"name": "source",
			"type": "text",
			"label": "Source"
		}
	]	
}

Collection

{
	"name": "address",
	"spec": [
		{
			"name": "city",
			"type": "text",
			"label": "City"
		},
		{
			"name": "street",
			"type": "text",
			"label": "Street"
		},
		{
			"name": "number",
			"type": "number",
			"label": "Number"
		}
	],
	"type": "collection",
	"label": "Address"
}

Arrays and collections with unknown structure

When you have a parameter that is type Collection or Array but you don't know the structure inside, you need to specify the structure like this:

Array

	{
    "name": "custom_fields",
    "type": "array",
    "label": "Custom Fields"
}

For array, spec is not specified.

Collection

{
    "name": "address",
    "type": "collection",
    "label": "Address",
    "spec": []
}

For collection, spec is set to an empty array.

This way, when the service returns any parameter inside the Collection or Array, the user will be able to map them.

Example

Appearance

Example of Interface

Output

Source

[
	{
		"name": "id",
		"type": "uinteger",
		"label": "User ID"
	},
	{
		"name": "createdAt",
		"type": "date",
		"label": "Created at"
	},
	{
		"name": "fullName",
		"type": "text",
		"label": "Full name"
	},
	{
		"name": "emails",
		"spec": {
			"type": "email",
			"label": "Email"
		},
		"type": "array",
		"label": "Emails"
	},
	{
		"name": "address",
		"spec": [
			{
				"name": "city",
				"type": "text",
				"label": "City"
			},
			{
				"name": "street",
				"type": "text",
				"label": "Street"
			},
			{
				"name": "number",
				"type": "number",
				"label": "Number"
			}
		],
		"type": "collection",
		"label": "Address"
	}
]

Interface Generator

Both the web interface and Visual Studio Code have interface generator tool, which helps with generating the interface.

Run a module for which you want to generate an interface, then in the panel with the output, click on the button circled below and choose Download output bundles option.

Download output bundles option

Then, a new panel will appear, with the original response from the endpoint. Copy the text to your clipboard.

Original response from /helloworld endpoint.

Generator in Web Interface

Go back to the tab with your app and make sure you are in the settings of the right module. Select tab INTERFACE. You can see a JSON snippet:

[
    {
        "name": "id",
        "type": "uinteger",
        "label": "User ID"
    }
]

In the right upper corner, click on Options button and choose Generator.

A new panel will appear. There, paste the previously copied JSON from your clipboard and click Generate.

A new data structure will be generated. Copy it to your clipboard and close the panel.

In the INTERFACE, replace the JSON structure with the new structure.

Generator in Visual Studio Code

Go back to VS Code and make sure you are in the settings of the right module. Select tab INTERFACE. You can see a JSON snippet:

[
    {
        "name": "id",
        "type": "uinteger",
        "label": "User ID"
    }
]

Click on the 'magic wand' icon.

Paste your data and copy the generated code. You still need to check all the labels and types, to make sure there are no errors. You might need to change some abbreviations to uppercase (such as URL, VAT, etc.).

Old structure

[
    {
        "name": "id",
        "type": "uinteger",
        "label": "User ID"
    }
]

List of available parameters to map before

New structure

[
  {
    "name": "result",
    "type": "text",
    "label": "Result"
  }
]

List of available parameters to map after

The generated code still needs to be reviewed!

Make sure the generated type for dates is date.

The label must be grammatically correct, use Title case and uppercase for abbreviations such as UID, URL, etc.

In the case of Search modules, you will need to delete the pagination data __IMTLENGTH__ and __IMTINDEX__.

Whenever you change INTERFACE in a module, you need to refresh your scenario in order to see the changes.

Dynamic Interface Using RPC

You can use RPC to generate the interface dynamically.

"rpc://nameOfTheRPC"

You can also define RPC to generate just a part of the interface.

[

	{
		"name": "id",
		"type": "uinteger",
		"label": "User ID"
	},
	"rpc://nameOfTheRPC"
]

You can access module parameters in remote procedures via {{parameters.foo}} syntax.

PRO TIP: If you call RPC from the interface of an instant trigger, you can use {{webhook.foo}} syntax to access webhook's parameters.