The component manifest provides information about a component (such as name, icon, author, description and properties) in a JSON text file. The manifest file must be named component.json.

Example manifest file:

{
    "name": "appmixer.utils.controls.OnStart",
    "author": "Martin Krčmář <martin@client.io>",
    "label": "On Flow Start",
    "description": "This trigger fires once and only once the flow starts.",
    "icon": "data:image/svg+xml;base64,PD94bWwgdmV...",
    "outPorts": [
        {
            "name": "out",
            "schema": {
                "properties": {
                    "started": {
                        "type": "string",
                        "format": "date-time"
                    }
                },
                "required": [ "started" ]
            },
            "options": [
                { "label": "Start time", "value": "started" }
            ]
        }
    ]
}

Members

• name

  Name of the component.

• label

  Label that will be used instead of name.

• icon

  Component icon.

• marker Component badge icon giving users extra context.

• author

  Author.

• description

  Description.

• auth

  Authentication mechanism if the component requires authentication.

• quota

  Parameters for the quota module used in the component (to conform with API usage limits).

• properties

  Properties of the component.

• inPorts

  Definition of the input of the component and how data transforms before it is processed by the component.

• outPorts

  Definition of the output of the component and variables that other connected components can use in their input.

• firePatterns

  Requirements for the component input messages to decide whether the component is ready to fire.

• tick

  Enable polling mechanism on the component.

• private Make component private to hide it from the user.

• webhook Make component "webhook"-type meaning it can receive HTTP requests.

• state Controls whether component's internal state is preserved across flow restarts.

(required)

The name of your component. The name must have the following format: [vendor].[service].[module].[component]. Note that all the parts of the name must contain alphanumeric characters only. For example:

{ "name": "appmixer.twitter.statuses.CreateTweet" }

The vendor part of the component name is the ID of the author of the component set. service and module allows you to organize your components into categories. These categories not only help you keep your components in a tidy hierarchical structure but it also has a meaning in that you can share your authentication and quota definitions between modules and components (more on that later). component describes the actual component activity.

(optional)

The label of your component. If not label is specified, then last part of name will be used when component is dropped into Designer. If your component name is appmixer.twitter.statuses.CreateTweet then CreateTweet will be name of the component unless you specify label property. This allows you to use spaces as opposed to the name property.

{ "label": "Create Tweet" }

The icon representing the component in the UI. It must be in the Data URI image format as described here: https://en.wikipedia.org/wiki/Data_URI_scheme. image/png or image/svg+xml image types are recommended. Example:

{
    "icon": "data:image/svg+xml;base64,PD94bWwgdmV..."
}

The marker icon that can be added to the component in the UI to give some extra context. The most common use case is to display e.g. a "Beta" badge to tell the user that this component is in beta. The marker must be in the Data URI image format as described here: https://en.wikipedia.org/wiki/Data_URI_scheme. image/png or image/svg+xml image types are recommended. The marker icon is displayed in the top right corner of the component shape. Example:

{
    "marker": "data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL..."
}

The author of the component. Example:

{
    "author": "David Durman <david@client.io>"
}

Description of your component. The description is displayed in the Designer UI inspector panel like this:

The description should not be longer than a sentence or two. Example:

{
    "description": "This action gets the current weather conditions for a location."
}

The authentication service and parameters. For example:

{
    "auth": {
        "service": "appmixer:google",
        "scope": [
            "https://mail.google.com/",
            "https://www.googleapis.com/auth/gmail.compose",
            "https://www.googleapis.com/auth/gmail.send"
        ]
    }
}

The auth.service identifies the authentication module that will be used to authenticate the user to the service that the component uses. It must have the following format: [vendor]:[service]. The Appmixer engine looks up the auth.js file under that vendor and service category. auth.scope provides additional parameters to the authentication module. See the Authentication section for more details.

When auth is defined, the component will have a section in the Designer UI inspector requiring the user to select from existing accounts or connect a new account. Only after an account is selected the user can continue configuring other properties of the component.

Configuration of the quota manager used for this component. Quotas allow you to throttle the firing of your component. This is especially useful and many times even necessary to make sure you don't go over limits of the usage of the API that you call in your components. Quota managers are defined in the quota.js file of your service/module. Example:

{
     "quota": {
        "manager": "pipedrive",
        "resources": "requests",
        "scope": {
            "userId": "{{userId}}"
        }
    }
}

quota.manager

The name of the quota module where usage limit rules are defined.

quota.resources

One or more resources that identify rules from the quota module that apply to this component. Each rule in the quota module can have the resource property. quota.resources allow you to cherry-pick rules from the list of rules in the quota module that apply to this component. quota.resources can either be a string or an array of strings.

quota.scope

This scope instructs the quota manager to count calls either for the whole application (service) or per-user. Currently, it can either be omitted in which case the quota limits for this component apply for the whole application or it can be { "userId": "{{userId}}" } in which case the quota limits are counted per Appmixer user.

The configuration properties of the component. Note that unlike properties specified on input ports (described later on in the documentation), these properties cannot be configured by the user to use data coming from the components back in the chain of connected components. In other words, these properties can only use data that is known before the flow runs.

Configuration properties are defined using two objects schema and inspector.

properties.schema

schema is a JSON Schema definition (http://json-schema.org) of the properties, their types and whether they are required or not. An example looks like this:

{
    "properties": {
        "schema": {
            "properties": {
                "interval": {
                    "type": "integer",
                    "minimum": 5,
                    "maximum": 35000
                }
            },
            "required": [
                "interval"
            ]
        }
}

The JSON Schema gives you enough flexibility to describe your property types and the required format, possibly using regular expressions or other mechanisms. When the user fills in the forms in the Designer UI inspector to configure their components, the Designer automatically validates all inputs using the schema. If any of the properties are invalid, the Designer UI gives an immediate feedback to the user that they should correct their configuration:

properties.inspector

inspector tells the Designer UI how the input fields should be rendered. The format of this definition uses the Rappid Inspector definition format. Example:

{
    "properties: {
        "inspector": {
            "inputs": {
                "interval": {
                    "type": "number",
                    "group": "config",
                    "label": "Interval (in minutes, min 5, max 35000)"
                }
            },
            "groups": {
                "config": {
                    "label": "Configuration",
                    "index": 1
                }
            }
        }
    }
}

As you can see, fields (e.g. interval in this case) are nested inside the inputs object and have the following properties:

• type can be any of the built-in types. See below for more details. (Custom inspector fields are also possible for on-prem installations. See the Custom Inspector Fields page for more details.)

• group is an identifier of an Inspector group this field belongs to. As you can see in the example above, you can have one or more custom groups (like config in this case) that you can define in the groups object. Groups will render in the Inspector UI in an accordion-like fashion. This is handy to organize your fields.

• label is a short text that appears above your input field. This is a great place to tell your users what your field is.

Inspector built-in types:

text

A single line input field.

{
    "type": "text",
    "label": "Text message."
}

textarea

A multi-line text input field.

{
    "type": "textarea",
    "label": "A multi-line text message."
}

number

A numerical input field. Additional configuration includes min, max and step numbers.

{
    "type": "number",
    "label": "A numerical input.",
    "min": 1,
    "max": 10,
    "step": 1
}

select

A menu of options. Options are defined in the options array each item having content and value properties. Note that content can be HTML. You can optionally provide placeholder that is displayed if no option is selected. Default values can be defined with defaultValue. If you need one of the items to clear the value of the select input field, use { "clearItem": true, "content": "Clear" } as one of the objects in the options array.

multiselect

Similar to select type, multiselect defines options the user can choose from. The difference is that with multiselect, the user can select multiple options, not only one. The value stored in the flow descriptor is an array of values the user selected. Supported options are options and placeholder.

{
    "type": "multiselect",
    "options": [
        { "content": "one", "value": 1 },
        { "content": "two", "value": 2 },
        { "content": "three", "value": 3 }
    ],
    "placeholder": "-- Select something --",
    "label": "Multi Select box"
}

date-time

A date-time input field allows the user to select a date/time using a special date/time picker interface. The date-time input field can be configured to support different type of formats or modes (only date or date-time combination). The configuration is stored in the "config" object. The following table shows list of all the available options:

{
    "type": "date-time",
    "label": "Date",
    "config": {
        "enableTime": true
    }
}

toggle

A toggle input field allows the user to switch between true/false values.

{
    "type": "toggle",
    "label": "Toggle field"
}

color-palette

A menu of colors. Colors are defined in the options array each item having content and value properties, where values must be a color in any of the CSS color formats (named-color, hex-color, rgb() or hsl()).

{
    "type": "color-palette",
    "label": "Color palette",
    "options": [
        { "value": "green", "content": "Green" },
        { "value": "yellow", "content": "Yellow" },
        { "value": "orange", "content": "Orange" },
        { "value": "red", "content": "Red" },
        { "value": "purple", "content": "Purple" }
    ]
}

select-button-group

A group of toggle buttons. Both single and multiple selection is allowed (can be controlled with the multi flag). Buttons are defined in the options array each item having value, content and icon properties.

{
    "type": "select-button-group",
    "label": "Select button group",
    "options": [
        { "value": "line-through", "content": "<span style=\"text-decoration: line-through\">S</span>" },
        { "value": "underline", "content": "<span style=\"text-decoration: underline\">U</span>" },
        { "value": "italic", "content": "<span style=\"font-style: italic\">I</span>" },
        { "value": "bold", "content": "<span style=\"font-weight: bold\">B</span>" }
    ]
}

{
    "type": "select-button-group",
    "label": "Select button group",
    "multi": true,
    "options": [
        { "value": "line-through", "content": "<span style=\"text-decoration: line-through\">S</span>" },
        { "value": "underline", "content": "<span style=\"text-decoration: underline\">U</span>" },
        { "value": "italic", "content": "<span style=\"font-style: italic\">I</span>" },
        { "value": "bold", "content": "<span style=\"font-weight: bold\">B</span>" }
    ]
}

{
    "type": "select-button-group",
    "label": "Select button group with icons",
    "multi": true,
    "options": [
        { "value": "cloud", "icon": "data:image/png;base64,iVBORw0KGgoAA..." },
        { "value": "diamond", "icon": "data:image/png;base64,iVBORw0KGgoAAAA..." },
        { "value": "oval", "icon": "data:image/png;base64,iVBORw0KGgoAAAANSUh..." },
        { "value": "line", "icon": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUg..." },
        { "value": "ellipse", "icon": "data:image/png;base64,iVBORw0KGgoAAAANSUhEU..." }
    ]
}

expression

A multi-field type field that allows for definition of logical expressions (OR/AND) or dynamic field definitions. This field accepts a list of other inspector field types (text, textarea, number, toggle, ....) and renders a "field builder" UI that enables the user to dynamically create nested fields.

{
      "type": "expression",
      "label": "Filter expression",
      "levels": ["OR", "AND"],
      "exclusiveFields": ["myText"]
      "fields": {
          "myText": {
              "type": "text",
              "label": "Column",
              "required": true,
              "index": 1
          },
          "mySelect": {
              "type": "select",
              "label": "Filter action",
              "variables": false,
              "required": true,
              "options": [
                  { "content": "Equals", "value": "equals" },
                  { "content": "Not Equals", "value": "notEquals" }
              ],
              "index": 2
          },
          "myAnotherText": {
              "label": "Filter value",
              "type": "text",
              "defaultValue": "My Filter",
              "index": 3
          }
      ]
}

The value of this field has the following structure:

{
    "OR": [
        {
            "AND": [
                { "myText": "My column name", "mySelect": "My filter action", "myAnotherText": "My filter value" },
                { "myText": "Another column name", "mySelect": "Another filter action", "myAnotherText": "Another filter value" }
            ]
        },
        {
            "AND": [
                { "myText": "Alternative column", "mySelect": "Alternative action", "myAnotherText": "Alternative value" }
            ]
        }
    ]
}

Note that by specifying the levels option, you can define the nesting. Currently, maximum of 2 levels of nesting is supported. The common use case is to use just one level. In that case, set e.g. "levels": ["ADD"].

The exclusiveFields is an optional property which defines the fields that will use variables in an exclusive way. For example let's say that the component has variableA and variableB available for use in its fields. Now if the myText field is in exclusiveFields array that means that you can use each variable once across all the fields inside the expression groups. To clarify this further, imagine the following scenario configuring an expression type:

1. Click the ADD button to create a second group

2. Select variableA on the myText field inside the first group using the variables picker

3. When opening the variables picker in myText field inside the second group, only variableB will be available, because variableA is already been used

Conditional fields

There are some cases when you want to show input fields depending on other values in the inspector. This allows to a better UX for component configuration. For this we use the whenproperty in the field we want to be conditional:

"inputs": {
    "field1": {
        "type": "toggle",
        "label": "This input controls rendering of field2"
    },
    "field2": {
        "when": { "eq": { "field1": true }}
        "type": "text",
        "label": "This field will be only rendered if field1 is set to true"
    }
}

The when field has the following structure: { op: { field: comparisonValue }}.

• op: Is the operand that will be used to determine if the condition holds true or false. The following operands are supported:

  • eq: Equality between the values.

  • equal: Equality between the values by deep comparison. Used for objects and arrays.

  • ne: Values are not equal.

  • regex: Check if the value in given field matches the regex in the comparisonValue.

  • text: Check if the value in the given field contains the string in the comparisonValue.

  • lt: Check if the value in the given field is less than the comparisonValue.

  • lte: Check if the value in the given field is less or equal than the comparisonValue.

  • gt: Check if the value in the given field is greater than the comparisonValue.

  • gte: Check if the value in the given field is greater or equal than the comparisonValue.

  • in: Check if the value in the given field is included on the given comparisonValue array.

  • nin: Check if the value in the given path is not included in the given comparisonValue.

• field: The field that is used for comparison, there are several ways to reference the field:

  • field: The same form presented in the example. It will search the given fields in current input port fields.

  • properties/someProperty: Refer to a property inside component properties.

  • ./field: It will refer to sibling fields of the current field. Specially useful when working with expression types.

• comparisonValue: The value used to compare the field against.

As it was mentioned, conditional fields also work with expression types, allowing to control the field rendering inside those expressions:

{
      "type": "expression",
      "label": "Filter expression",
      "levels": ["OR", "AND"],
      "fields": {
          "myText": {
              "type": "text",
              "label": "Column",
              "required": true,
              "index": 1
          },
          "conditionalField": {
              "when": { "eq": { "./myText": "Render" }}
              "type": "select",
              "label": "Filter action",
              "variables": false,
              "required": true,
              "options": [
                  { "content": "Equals", "value": "equals" },
                  { "content": "Not Equals", "value": "notEquals" }
              ],
              "index": 2
          }
      ]
}

properties.source

Sometimes the structure of the inspector is not known in advance and it cannot be hardcoded in the manifest. Instead, the inspector fields are composed dynamically based on the data received from an API. A good example is the google.spreadsheets.CreateRow component where the inspector renders fields representing columns fetched from the actual worksheet. For this to work, we can define the source property in the manifest that calls a component of our choosing in a so called "static" mode. For example:

{
       "source": {
           "url": "/component/appmixer/google/spreadsheets/ListColumns?outPort=out",
           "data": {
               "messages": {
                   "in": 1
               },
               "properties": {
                   "sheetId": "properties/sheetId",
                   "worksheet": "properties/worksheet"
               },
               "transform": "./transformers#columnsToInspector"
           }
       }
}

In the example above, we call the ListColumns component and we're interested in the output coming from the output port out.Since this is just a normal component, we need to transform the result into the inspector-like object, i.e.:

{
    inputs: { ... },
    groups: { ... }
}

We need to tell Appmixer where it can find the transformation function. For this we use the transform property which tells Appmixer to look for the transformers.js file inside the ListColumns/ directory. The transformer must return an object with a function named columnsToInspector that can look like this:

module.exports.columnsToInspector = (columns) => {

    let inspector = {
        inputs: {},
        groups: {
            columns: { label: 'Columns', index: 1 }
        }
    };

    if (Array.isArray(columns) && columns.length > 0) {
        columns.forEach((column, index) => {
            inspector.inputs[column[0]] = {
                type: 'text',
                group: 'columns',
                index: index + 1
            };
        });
    }
    return inspector;
};

properties.source.url

A special URL that identifies a component that should be called in a "static" mode. It has to be of the form /component/[vendor]/[service]/[module]/[component]. It should also contain outPort in the query string that point to the output port in which we're interested to receive data from. Example:

"/component/appmixer/google/spreadsheets/ListColumns?outPort=out"

properties.source.data.messages

Messages that will be sent to the input port of the component referenced by the properties.source.url. Keys in the object represent input port names and values are any objects that will be passed to the input port as messages.

properties.source.data.properties

Properties that will be used in the target component referenced by the properties.source.url. The target component must have these properties defined in its manifest file. The values in the object are references to the properties of the component that calls the target component in the static mode. For example:

{
    "properties": {
        "targetComponentProperty": "properties/myProperty"
    }
}

properties.source.data.transform

The transformation function used to transform the output of the target component. It should return an inspector-like object, i.e.:

{
    inputs: { ... },
    groups: { ... }
}

Example:

{
    "transform": "./transformers#columnsToInspector"
}

The transform function is pointed to be a special format [module_path]#[function], where the transformation module path is relative to the target component directory.

The definition of the input ports of the component. It's an array of objects.

Each component can have zero or more input ports. If a component does not have any input ports, we call it a trigger. Input ports allow a component to be connected to other components. Input ports receive data from output ports of other connected components when the flow is running and the data is available. Each input port has a name and configuration that has the exact same structure as the configuration of properties, i.e. it has schema , inspector or source objects. The difference is that the user can use placeholders (variables) in the data fields that will be eventually replaced once the actual data is available. The placeholders (variables) can be entered by the user using the "variables picker" in the Designer UI inspector (see below). Example:

{
    "inPorts": [
        {
            "name": "message",
            "schema": {
                "type": "object",
                "properties": {
                    "body": { "type": "string" },
                    "phoneNumber": { "type": "string" }
                },
                "required": [ "phoneNumber" ]
            },
            "inspector": {
                "inputs": {
                    "body": {
                        "type": "text",
                        "group": "transformation",
                        "label": "Text message",
                        "index": 1
                    },
                    "phoneNumber": {
                        "type": "text",
                        "group": "transformation",
                        "label": "Phone number",
                        "index": 2
                    }
                },
                "groups": {
                    "transformation": {
                        "label": "Transformation",
                        "index": 1
                    }
                }
            }
        }
    ]
}

The message from the example looks like this in the raw form:

City: {{{$.a0828f32-34b8-4c8d-b6b3-1d82ca305921.weather.[name]}}}
Humidity: {{{$.a0828f32-34b8-4c8d-b6b3-1d82ca305921.weather.[main.humidity]}}}
Pressure: {{{$.a0828f32-34b8-4c8d-b6b3-1d82ca305921.weather.[main.pressure]}}}
Temperature: {{{$.a0828f32-34b8-4c8d-b6b3-1d82ca305921.weather.[main.temp]}}}

As you can see, the placeholders for variables use a special format that the Appmixer engine eventually replaces with real values that come from the GetCurrentWeather component once the data is available.

inPort.schema

Definition of the schema of the data that the input port expects. Please see the Properties section for more details.

inPort.inspector

Definition of the inspector UI for this input port. Please see the Properties section for more details.

inPort.source

Definition of the source of the variables or dynamic inspector that will be available in the designer UI for this input port.

inPort.variablesPipeline

This object allows you to control what variables will be available to this component in the UI and in the component receive() method. By default, variables are collected from all the components back in the chain of connected component. This might not be desirable in some cases. One can set scopeDepth to a number that represents the depth (levels back the the graph of connected components) used to collect variables. rawValue can be used to tell the engine not to resolve variable placeholders to their actual values but to treat variable names as values themselves. Example:

{
    "variablesPipeline": {
        "scopeDepth": 1,
        "rawValue": true
    }
}

inPort.maxConnections

Set the maximum number of links that can be connected to the input port. Maximum number of connections is infinite by default but in some applications, it might be desirable to set a limit on this, usually 1. The Appmixer Designer UI will not allow the user to connect more than maxConnections links to the input port.

The definition of the output ports of the component. It's an array of objects.

Components can have zero or more output ports. Each output port has a name and optionally an array options that defines the structure of the message that this output port emits. Without the options object, the user won't be able to see the possible variables they can use in the other connected components. For example, a component connected to the weather output port of our GetCurrentWeather component, can see the following variables in the variables picker:

An example of outPorts definition can look like this:

{
    "outPorts": [
        {
            "name": "weather",
            "options": [
                { "label": "Temperature", "value": "main.temp" },
                { "label": "Pressure", "value": "main.pressure" },
                { "label": "Humidity", "value": "main.humidity" },
                { "label": "Sunrise time (unix, UTC)", "value": "sys.sunrise" },
                { "label": "Sunset time (unix, UTC)", "value": "sys.sunset" },
                { "label": "City name", "value": "name" },
                { "label": "Weather description", "value": "weather[0].description" },
                { "label": "Weather icon code", "value": "weather[0].icon" },
                { "label": "Weather icon URL", "value": "weather[0].iconUrl" }
            ]
        }
    ]
}

outPort.maxConnections

Set the maximum number of outgoing links that can exist from the output port. Maximum number of connections is infinite by default but in some applications, it might be desirable to set a limit on this, usually 1. The Appmixer Designer UI will not allow the user to connect more than maxConnections links from the output port.

Fire patterns is an advanced configuration of a component that allows you to define when your component is ready to fire (ready to process input messages). Fire patterns can make the engine to hold input messages on components input ports until the pattern matches and then send the messages to the component in bulk. Fire patterns are defined as an array or a matrix. An example of fire patterns may look like this:

{
    "firePatterns": ['*', 1]
}

The fire pattern above is interpreted as follows: The component processes messages only if the first input port has zero or more messages waiting in the queue and at least one message waiting in the second input port queue. Another example can be a fire pattern:

{
    "firePatterns": [1, 1]
}

In this case, the component only processes messages if there is at least one message on each of its two input ports. A good example for this pattern is the Sum component:

The Sum component expects messages on both of its input ports before it can produce a sum of its inputs.

The following table lists all the possible fire pattern symbols:

Note that you can also define a set of fire patterns for a component, for example:

{
    "firePatterns": [
        ['*', 1],
        [1, 0]
    ]
}

When more fire patterns are used, there must be at least one fire pattern that matches before the component fires.

When set to true, the component will receive signals in regular intervals from the engine. The tick() Component Virtual method will be called in those intervals (see Component Behaviour). This is especially useful for trigger-type of components that need to poll a certain API for changes. The polling interval can be set by the COMPONENT_POLLING_INTERVAL environment variable (for custom on-prem installations only). The default is 60000 (ms), i.e. 1 minute.

When set to true, the component will not be visible to the user.

Set webhook property to true if you want your component to be a "webhook" type. That means that context.getWebhookUrl() method becomes available to you inside your component virtual methods (such as receive()). You can use this URL to send HTTP POST requests to. See the Behaviour section, especially the context.getWebhookUrl() for details and example.

Set state property to { persistent: true } to tell the engine not to delete component state when flow is stopped. See context.state for more information.

Optional object containing localization strings. For example:

{
    "localization": {
       "cs": {
             "inPorts[0].inspector.inputs.body.label": "Textova zprava",
             "inPorts[0].inspector.inputs.from.label": "Cislo volajiciho",
             "inPorts[0].inspector.inputs.from.placeholder": "Hledej cislo"
       },
       "sk": {
             "inPorts[0].inspector.inputs.body.label": "Textova zprava",
             "inPorts[0].inspector.inputs.from.label": "Cislo volajiciho"
       }
   }
}

Unfortunately, you cannot localize output port option's label at the moment. Neither the input/output port name.

For more information about component localization, refer to Custom Component Strings section.