1 of 100

v4.4

Introduction

Appmixer is a workflow engine together with a web user interface that allows end-users to create business processes in an easy-to-use drag&drop UI without writing a single line of code.

For companies that seek to embed the Appmixer workflow technology into their own products (OEM), it is important to know that thanks to its modular architecture, customizations are possible both on the process level but also in the UI layer.

The Appmixer workflow engine provides features that are critical to workflow applications:

Error handling. Errors are handled gracefully, logged and actions repeated when possible.
Message passing. Data messages are delivered once and only once between connected components in a workflow.
Custom components. Components in a workflow are seen as black-boxes by the engine and their behaviour can be completely customized (they can call either external APIs, internal APIs, do some processing or scheduling).
Quotas and Limits. Appmixer engine can throttle the processing of components to make sure API usage limits are respected.
Authentication. Appmixer supports industry standards for authentication out-of-the box (API keys, OAuth 1, OAuth 2). All tokens are automatically refreshed when necessary.
Monitoring. All transactions and data passing through Appmixer are logged. Get real-time insight to all activities.

The Appmixer system can be installed on a number of different systems such as private clouds (OpenShift), cloud computing platforms (AWS) or plain Linux machines.

Migration from 4.3

Appmixer SDK

The Appmixer SDK has been heavily improved. On the other hand, it is not fully backward compatible. Especially, if you have some custom CSS hack to show/hide different parts of the UI widgets, these hacks may stop working. We have simplified the customization of the UI, you can now set only a few variables and change the whole look. It also means that the structure of the themes and strings objects have changed.

appmixer.ui

widget.destroy method removed, use widget.close instead.

appmixer.ui.Designer

options.beforeInspectorOpen replaced by a new event: component:open
options.beforeInspectorClose replaced by a new event: component:close
options.changeActionCallback replaced by a new event: component:update-type
options.renameCallback replaced by a new event: component:rename
options.onComponentAddCallback replaced by a new event: component:add

appmixer.ui.FlowManager

options.filters list changed to support following presets:

filters: [
    { property: 'stage', label: 'Running flows', value: 'running' },
    { property: 'stage', label: 'Stopped flows', value: 'stopped' },
    { property: 'sharedWith', label: 'My flows', value: 'myFlows' },
    { property: 'sharedWith', label: 'Shared with others', value: 'sharedWithOthers' },
    { property: 'sharedWith', label: 'Shared with me', value: 'sharedWithMe' }
],

appmixer.ui.Components

widget name changed to appmixer.ui.Connectors

Appmixer engine

New ENV variables

There are a few new ENV variables. You should set this one if you are running Appmixer self-managed.

The first one is for the Appmixer engine:

APPMIXER_FE_URL which has to point to your FE application (defaults to http://localhost:8080). You have to set this, only if you are using the built-in FE app, not if you use the Appmixer SDK.

Another one for the Frontend application (if you use it):

APPMIXER_BACKOFFICE_URL which has to point to your Backoffice URL. If the signed-in user is an admin, the FE displays a new icon in the left menu that can take the user straight to the Backoffice.

Webhook can return 202 response

Webhook components may return 202 code. That can happen when a component needs a quota to process the incoming webhook, but there is no quota available at that time. The webhook will be enqueued for processing and 202 returned to the caller. In the previous versions, the response to the webhook was delayed (until the quota was granted) which lead to timeouts

Components

Component versioning

It is important to re-install all the Appmixer built-in modules that you use through the Backoffice. This way, the source codes of those modules will be stored in the Appmixer database. Future releases of Appmixer (4.5) will be released without modules. New modules will be released and updated only through the Backoffice.

We introduced versioning for modules and components. This will allow us to deliver component updates independent of Appmixer releases. When we develop a new module, it will be directly available in your Backoffice and ready for installation. When we develop a fix for a module or a component, you will be able to update it through the Backoffice.

The Appmixer 4.4 version still contains all the built-in modules stored the old way - located on the filesystem. This is due to migration, when you update to 4.4, there will be no downtime for your flows that use the Appmixer modules. But the next major release will no longer include the built-in modules, all of them will be available and released only through the Backoffice! This means, that when you update to Appmixer 4.4, you have to install the modules you use, through the Backoffice, to be ready for the next Appmixer versions.

If you don't use any built-in modules, only your custom ones, you can skip the next part. If you use some of the built-in modules (including utils like OnStart, Each, ...), you should do the following AFTER you update to Appmixer 4.4. Go to the Backoffice and the Modules section. You should see something like this:

A bunch of modules, some of them could be marked with a purple Update available label. At the top of the screen, you could see a yellow box with an exclamation mark. You will see that yellow box only if you have a generic components ACL rule in your system:

And if you click it:

That ACL rule is in the system by default. If you never used the ACLs, then you have it there. This rule says, that every user in the system can use every module/component. This generic default rule should be removed and replaced with an ACL rule per each installed module. Before you can do so, you need to create an ACL rule per each installed module, to make it easier for you, we added a button for that - ADD USER RULES FOR INSTALLED MODULES.

So the first thing, you need to do is to click this button:

A whole new set of ACL rules will be added, one per each installed module:

At this point, it is safe to remove the generic rule:

When a Backoffice user installs a module, they have to decide, when this newly installed module will be available to the users. The reason is simple. When you install a new module (either through the Backoffice or through the CLI) into Appmixer, you usually need to configure it first. In the case of an OAuth module, you need to set up the clientId and clientSecret, for example. Before you set up the module, you don't want your users to see it in the application. After the module is installed and set up, you want to test it. You can have tester accounts that will have access to these new modules through ACL. Once the module is tested, you can release it to your users by adding the proper ACL rule.

For details on installing modules from the Backoffice, refer to the Installing and updating modules tutorial.

At this point, you can go back to the modules page and install the modules you want to have in your Appmixer instance. Let's say you are using the Slack module. You go to the Modules section and look for Slack:

Every module will have the Update available mark on top of it. Some of them do contain new fixes or features, but some have no changes (only their version is set to 1.0.1 to distinguish them from the old versions in 4.3).

When you open the module, you can install it by clicking the Update this Modules button:

At this point, the module has been installed into Appmixer and is stored in its database. Such Appmixer is now ready for a future update which will be distributed WITHOUT modules located in the filesystem (in the zip file).

This step has to be repeated for every module that you use in your Appmixer.

Module changes

Few modules (Slack, JIRA, Microsoft OneDrive, and Tasks) were migrated into plugins. If you use those, you need to change some settings.

Slack Event API

Slack Events API endpoint URL has been changed from https://acme.com/services/appmixer/slack/events to https://acme.com/plugins/appmixer/slack/events

More information in the Slack Events API registration.

Microsoft OneDrive file picker

The file picker frontend component is using a BE API endpoint. Has been changed from https://acme.com/plugin/onedrive/picker to https://acme.com/plugins/appmixer/microsoft/onedrive/picker

More information in the Microsoft OneDrive file picker registration.

Utils Tasks

The Tasks module has been migrated into a plugin.

It does not affect functionality. In the previous version of Appmixer, some features this module requires in order to work were part of the engine. Like the Tasks API, collections, where the tasks are stored, were defined in the engine, and jobs that process the due tasks were part of the engine as well. The first disadvantage was, that you did not have access to this code, second, you did not have the possibility to extend the Appmixer engine with similar features (extending its API, adding new collections or jobs).

So the Tasks API endpoints have been migrated, the older ones removed and the new ones defined in the routes.js file located inside the appmixer/utils/tasks folder. And the collections were changed. Former peopleTaskTasks is now pluginAppmixerUtilsTasksTasks and peopleTaskWebhooks is now pluginAppmixerUtilsTasksWebhooks. The migration will perform automatically when Appmixer 4.4 loads the Tasks plugin for the first time. There is no need to do anything unless you access the Tasks API or collections directly.

Overview

Introduction

Appmixer is a workflow engine together with a web user interface that allows end-users to create business processes in an easy-to-use drag&drop UI without writing a single line of code.

The Appmixer workflow engine provides features that are critical to workflow applications:

Error handling. Errors are handled gracefully, logged and actions repeated when possible.
Message passing. Data messages are delivered once and only once between connected components in a workflow.
Custom components. Components in a workflow are seen as black-boxes by the engine and their behaviour can be completely customized (they can call either external APIs, internal APIs, do some processing or scheduling).
Quotas and Limits. Appmixer engine can throttle the processing of components to make sure API usage limits are respected.
Authentication. Appmixer supports industry standards for authentication out-of-the box (API keys, OAuth 1, OAuth 2). All tokens are automatically refreshed when necessary.
Monitoring. All transactions and data passing through Appmixer are logged. Get real-time insight to all activities.

The Appmixer system can be installed on a number of different systems such as private clouds (OpenShift), cloud computing platforms (AWS) or plain Linux machines.

Component

Components are the building blocks of Appmixer. Each component in a flow reacts on incoming messages, processes them and produces outgoing messages. User can wire components together to define complex behaviour and workflows. Usually, components call external APIs but they can also do some internal processing, logic or scheduling.

Take the example above. There are three components in the flow. The first one (Timer) we call a trigger because it does not have any input ports and so the component generates outgoing messages based on its internal logic. In our case, the Timer component sends messages to its output port out in regular intervals that the user can specify in the UI. As soon as a message leaves an output port, it travels through all the connected links to input ports of other connected components. In our scenario, when a message leaves the out port of our Timer, it goes to the location input port of the GetCurrentWeather component. As soon as the GetCurrentWeather component receives a message on its input port, it starts processing it. In this case, it requests current weather information from the https://openweathermap.org API. Once a response is received from the API, the component continues to send the result to its output port weather. Note that the location for which we're requesting the current weather can be specified by the user in the UI. The process then repeats for all the other connected components until no message is generated on an output port or there is no other component connected.

To make our example flow complete, it is important to note that any component can be configured using data generated on output ports of any component back in the chain of connected components. In our example, our SendChannelMessage component sends a message on Slack channel #qa-messages with text containing the city, humidity, pressure and temperature as it was received from the weather API. The user configures the flow in the designer UI simply by selecting placeholders (variables in the Appmixer engine jargon) that will eventually be replaced when the flow goes to the running state and the actual data is available.

Components have some important properties that we should mention before diving into the details:

Components don't know about each other. All components are totally independent and loosely coupled. They only react on incoming messages and produce outgoing messages. The linkage between components is not internal to the components themselves but rather a mechanism of the Appmixer engine and its protocol.
Components are black-boxes to the Appmixer engine. The engine does not know and also does not need to know what components internally do and how they are implemented. It only wires them together through ports and makes sure messages are always delivered and in the right order.

Flow

A flow consists of an orchestrated pattern of business activity enabled by interconnecting components together that transform input data (coming from trigger-type of components), perform actions, store data and/or load data to external systems.

Appmixer provides an interpreter for running flows and UI to manage flows.

Flow Descriptor

Flows are represented as JSON objects in the Appmixer engine. The JSON object is called "flow descriptor" in the Appmixer jargon and for the example image above, it may look like this:

{
    "76a77abf-d5ec-4b1c-b6e8-031359a6a640": {
        "type": "appmixer.utils.timers.Timer",
        "label": "Timer",
        "x": 265,
        "y": 115,
        "config": {
            "properties": {
                "interval": 15
            }
        }
    },
    "a0828f32-34b8-4c8d-b6b3-1d82ca305921": {
        "type": "appmixer.utils.weather.GetCurrentWeather",
        "label": "GetCurrentWeather",
        "source": {
            "location": {
                "76a77abf-d5ec-4b1c-b6e8-031359a6a640": [
                    "out"
                ]
            }
        },
        "x": 515,
        "y": 115,
        "config": {
            "transform": {
                "location": {
                    "76a77abf-d5ec-4b1c-b6e8-031359a6a640": {
                        "out": {
                            "type": "json2new",
                            "lambda": {
                                "city": "Prague",
                                "units": "metric"
                            }
                        }
                    }
                }
            }
        }
    },
    "11f02d1e-106e-4cf5-aae2-5514e531ea4d": {
        "type": "appmixer.slack.list.SendChannelMessage",
        "label": "SendChannelMessage",
        "source": {
            "message": {
                "a0828f32-34b8-4c8d-b6b3-1d82ca305921": [
                    "weather"
                ]
            }
        },
        "x": 735,
        "y": 115,
        "config": {
            "properties": {
                "channelId": "C3FNGP5K5"
            },
            "transform": {
                "message": {
                    "a0828f32-34b8-4c8d-b6b3-1d82ca305921": {
                        "weather": {
                            "type": "json2new",
                            "lambda": {
                                "text": "City: {{{$.a0828f32-34b8-4c8d-b6b3-1d82ca305921.weather.[name]}}}\nHumidity: {{{$.a0828f32-34b8-4c8d-b6b3-1d82ca305921.weather.[main.humidity]}}}\nPressure: {{{$.a0828f32-34b8-4c8d-b6b3-1d82ca305921.weather.[main.pressure]}}}\nTemperature: {{{$.a0828f32-34b8-4c8d-b6b3-1d82ca305921.weather.[main.temp]}}}"
                            }
                        }
                    }
                }
            }
        }
    }
}

The flow descriptor contains information about the components in the flow and their types, how they are interconnected (source), their properties (config.properties) and data transformation for all input ports (config.transform).

If any component position property (x, y) is not a number, Appmixer SDK will apply a tree layout on the entire diagram after the flow is loaded.

End User Guide

Knowledge base

Please visit the Appmixer Knowledge base for end-user tutorials.

Component Definition

Basic Structure

Introduction

Components in Appmixer are structured into "services", "modules" and "components" hierarchy. Each service can have multiple modules and each module can have multiple components. For example, "Google" service can have "gmail", "calendar" or "spreadsheets" modules and "gmail" module can have "SendEmail", "NewEmail" and other components:

This hierarchy is reflected in the directory structure of component definitions. Typically, services and modules are structured in two ways. Either the service itself appears as an "app" in Appmixer or modules are separate apps. If a module has its own manifest file (module.json), it is considered a separate app in Appmixer.

For example, in case of Google, we want to have separate apps for each module (GMail, Calendar, Analytics, ...):

But in case of Twilio, we may just want to have one app and all the actions/triggers as different components of the Twilio app:

Directory Structure

As mentioned in the previous section, services, modules and components must follow the service/module/component directory structure. The following images show the two different ways you can structure your services (i.e. modules as separate apps or a service as one single app).

Service Manifest File

Service manifest is defined in the service.json file. The file has the following structure:

{
    "name": "[vendor].[service]",
    "label": "My App Label",
    "category": "applications",
    "categoryIndex": 2,
    "index": 1,
    "description": "My App Description",
    "icon": "data:image/svg+xml;base64,PHN2ZyB3aWR0aD...."
}

Available fields are:

Field

Description

name

label

The label of your app.

category

App category. By default, components shipped with Appmixer are divided into two categories "applications" and "utilities" but you can have your own custom categories too. Just use any custom category name in the service manifest file to create a new category and add your service to it. This category will become automatically visible e.g. in the Appmixer Designer UI.

categoryIndex

App category index. By default, categories are sorted alphabetically, you can change that using this index property. Optional.

index

The app index within the category. This allows sorting the apps within the same category.

description

Description of your app.

icon

App icon in the Data URI format.

Module Manifest File

Module manifest is defined in the module.json file. The file has the following structure (similar to the service.json file):

{
    "name": "[vendor].[service].[module]",
    "label": "My App Label",
    "category": "applications",
    "categoryIndex": 2,
    "index": 3,
    "description": "My App Description",
    "icon": "data:image/svg+xml;base64,PHN2ZyB3aWR0aD...."
}

Available fields are:

Field

Description

name

label

The label of your app.

category

App category. By default, components shipped with Appmixer are divided into two categories "applications" and "utilities" but you can have your own custom categories too. Just use any custom category name in the module manifest file to create a new category and add your app to it. This category will become automatically visible e.g. in the Appmixer Designer UI.

categoryIndex

App category index. By default, categories are sorted alphabetically, you can change that using this index property. Optional.

index

The app index within the category. This allows sorting the apps within the same category.

description

Description of your app.

icon

App icon in the Data URI format.

Manifest

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.

name

(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.

label

(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" }

icon

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..."
}

marker

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..."
}

author

The author of the component. Example:

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

description

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."
}

auth

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.

authConfig

This section specifies which service should be used to search for additional configuration values.

{
	"authConfig": {
		"service": "appmixer:deepai"
	}
}

To set additional global values for a service, use the authConfig API. See the Service Configuration section for more information. The purpose of this property is to offer authentication settings for components/services that do not require user authentication. Consider that deepai service. It is a service that requires authentication (API key), but you don't want your users to provide their API keys for it. You want to use your API key for all your users. You cannot use define the auth property in component.json, because that would tell Appmixer to show Connect Account button to users in the frontend.

This is not needed since version 4.2. Appmixer will look for service configuration for each component without auth section. More details in here.

quota

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.

properties

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:

Option

Description

format

enableTime

Boolean. Enables time picker.

enableSeconds

Boolean. Enables seconds in the time picker.

maxDate

String representing the maximum date that a user can pick to (inclusive).

minDate

String representing the minimum date that a user can pick to (inclusive).

mode

Mode of the date/time picker. Possible values are "single", "multiple", or "range".

time_24hr

Boolean. Displays time picker in 24 hour mode without AM/PM selection when enabled.

weekNumbers

Boolean. Enables display of week numbers in calendar.

{
    "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:

Click the ADD button to create a second group
Select variableA on the myText field inside the first group using the variables picker
When opening the variables picker in myText field inside the second group, only variableB will be available, because variableA is already been used

filepicker

An input that allows selecting and uploading files from the user's computer. When clicked, it will open the browser's file selector, and the file selected will be uploaded to Appmixer and referenced on the input.

"inputs": {
    "fileId": {
        "type": "filepicker",
        "label": "Select file",
        "index": 1,
        "tooltip": "Pick a CSV file to import into the flow"
    }
}

googlepicker

Similar to the filepicker input, this one allows users to select files or folders on their Google Drive accounts. When clicked a Google Drive file picker is opened, showing the user's Google Drive content. When selecting a folder/file, the input value becomes an object which includes the Id of the folder/file which should be used on Google API calls to reference that asset.

"inputs": {
    "file": {
        "type": "googlepicker",
        "index": 1,
        "label": "File",
        "placeholder": "Choose a file...",
        "tooltip": "Choose a file to export."
    }
}

You can use googlepicker to pick folders instead of files:

"inputs": {
    "file": {
        "type": "googlepicker",
        "index": 1,
        "label": "Folder",
        "placeholder": "Choose a folder...",
        "tooltip": "Choose a folder.",
        "view": "FOLDERS"
    }
}

This input type needsappmixer.google.drive.GooglePicker component to be installed.

onedrivepicker

Similar to the googlepicker, this one allows users to select files or folders from their OneDrive accounts. When clicked, an OneDrive file picker is opened, showing the user's OneDrive content. When selecting a folder/file, the input value becomes an object which includes the id of the folder/file which should be used on OneDrive API calls to reference that asset.

"input": {
    "folder": {
        "type": "onedrivepicker",
        "index": 1,
        "label": "Folder",
        "placeholder": "Choose a folder...",
        "tooltip": "Choose a folder to upload the file to.",
        "view": "folders"
    }
}

The view property works similar to the same property on googlepicker. It can be used to determine what is shown on the picker. You can use 3 values: files, folder, all. As their names indicate, if select files, only files will be shown, if you select folder it will show only your folders and if you select all it will show both. This input type needs appmixer.microsoft.onedrive.OneDrivePicker component to be installed.

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",
        "index": 1
    },
    "field2": {
        "when": { "eq": { "field1": true }}
        "type": "text",
        "label": "This field will be only rendered if field1 is set to true",
        "index": 2
    }
}

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.

inPorts

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.

An example of how the source property can be used to generate the input port Inspector dynamically for the appmixer.google.spreadsheets.CreateRow component. When showing the Inspector for the CreateRow, we need to know the structure (columns) of the Worksheet, the Inspector input fields will copy the columns in the Worksheet

{
...
    "inPorts": [
        {
            "name": "in",
            "schema": {
                "type": "object"
            },
            "source": {
                // The ListColumns component can return an array of columns in a
                // Worksheet.
                "url": "/component/appmixer/google/spreadsheets/ListColumns?outPort=out",
                "data": {
                    // The ListColumns component needs two properties in order
                    // to get the list of columns, the Spreasheet Id and the
                    // Worksheet Id. Both will be taken from properties of the
                    // CreateRow component (the caller).
                    "properties": {
                        // Appmixer will replace 'properties/sheetId' with
                        // the actual value before making the call
                        "sheetId": "properties/sheetId",
                        "worksheetId": "properties/worksheetId"
                    },
                    // A transformer function 'columnsToInspector' from the 
                    // ListColumns.js will be executed in order to transform a list
                    // of columns to the Appmixer Inspector.
                    "transform": "./ListColumns#columnsToInspector"
                }
            }
        }
    ]
}

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 components. This might not be desirable in some cases. One can set scopeDepth to a number that represents the depth (levels back 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.

outPorts

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.source

The definition is similar to the source source of properties. When used for the output port definition, it allows defining the output port schema dynamically.

There is one difference though. When defined in the output port, the source definition can reference both component properties and input fields, while the properties source definition can only hold references to other properties' values.

An example is a Google Spreadsheet component UpdatedRow. The output port options of this component consist of the column names in the spreadsheet. But that is specific to the selected Spreadsheet/Worksheet combination. Therefore it has to be defined dynamically.

Here is an example of the UpdatedRow output port definition.

{
    "outPorts": [
        {
            "name": "out",
            "source": {
                // We will call another component to construct the output port
                // options, in this case, the GetRows component
                "url": "/component/appmixer/google/spreadsheets/GetRows?outPort=out",
                // Every Appmixer component can have 'properties' and input ports,
                // the 'data' sections is used to create the input data object 
                // for the component
                "data": {
                    // in this particular case, the GetRows component has an
                    // optional property called 'generateOutputPortOptions', we
                    // will pass that property with the value 'true'. The GetRows
                    // component will use this property to change its return value
                    // and instead of returning rows from Worksheet, it will
                    // return the 'options' array.
                    "properties": {
                        "generateOutputPortOptions": true
                    },
                    // the GetRows component expects the Spreadsheet ID and
                    // Worksheet ID as part of the message at its input port
                    // called 'in'. The UpdatedRow component is a trigger, it
                    // does not have an input port, but it has the same options like
                    // 'allAtOnce', 'withHeaders', ... and since it does not have
                    // an input port, it has these options defined in the
                    // 'properties' section. The next 'messages' section is used
                    // to construct an input port object for the GetRows component.
                    // It copies the user defined properties from the UpdatedRow.
                    // Appmixer will replace these with the actual values before
                    // calling the GetRows component.
                    "messages": {
                        "in/sheetId": "properties/sheetId",
                        "in/worksheetId": "properties/worksheetId",
                        "in/allAtOnce": "properties/allAtOnce",
                        "in/withHeaders": "properties/withHeaders",
                        "in/rowFormat": "properties/rowFormat"
                    }
                }
            }
        }
    ]
}

outPort.maxConnections

Set the maximum number of outgoing links that can exist from the output port. The 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.

firePatterns

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:

Symbol

Description

(Any) The input port must have zero or more messages in the queue.

(Exists) The input port must have at least one message in the queue.

(Empty) The input port must have no message in the queue.

(All) The input port must have at least one message from all the connected components in the queue. This is a synchronization pattern that lets you specify that the component must wait for all the connected components to send a message before it can start processing. A typical example is a "Multiple-to-Single" join component. This component must wait for all the LoadCSV components to send a message before it can produce an SQL-like join schema.

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.

tick

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.

private

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

webhook

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.

state

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.

localization

An optional object containing localization strings. For example:

{
    "name": "appmixer.twilio.sms.SendSMS",
    "author": "David Durman <david@client.io>",
    "icon": "data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMjUwMCIgaGVp...",
    "description": "Send SMS text message through Twilio.",
    "private": false,
    "auth": {
        "service": "appmixer:twilio"
    },
    "outPorts": [
        {
            "name": "sent",
            "options": [
                { "label": "Message Sid", "value": "sid" }
            ]
        }
    ],
    "inPorts": [
        {
            "name": "message",
            "schema": {
                "type": "object",
                "properties": {
                    "body": { "type": "string" },
                    "to": { "type": "string" },
                    "from": { "type": "string" }
                },
                "required": [
                    "from", "to"
                ]
            },
            "inspector": {
                "inputs": {
                    "body": {
                        "type": "text",
                        "label": "Text message",
                        "tooltip": "Text message that should be sent.",
                        "index": 1
                    },
                    "from": {
                        "type": "select",
                        "label": "From number",
                        "placeholder": "Type number",
                        "tooltip": "Select Twilio phone number.",
                        "index": 2,
                        "source": {
                            "url": "/component/appmixer/twilio/sms/ListFromNumbers?outPort=numbers",
                            "data": {
                                "transform": "./transformers#fromNumbersToSelectArray"
                            }
                        }
                    },
                    "to": {
                        "type": "text",
                        "label": "To number",
                        "tooltip": "The destination phone number. <br/><br/>Format with a '+' and country code e.g., +16175551212 (E.164 format).",
                        "index": 3
                    }
                }
            }
        }
   ],
   "localization": {
       "cs": {
           "label": "Pošli SMS",
           "description": "Pošli SMS pomocí Twilia",
           "inPorts[0].name": "Zpráva",
           "inPorts[0].inspector.inputs.body.label": "Textová zpráva",
           "inPorts[0].inspector.inputs.from.label": "Číslo volajícího",
           "inPorts[0].inspector.inputs.from.placeholder": "Hledej číslo",
           "outPorts[0].name": "Odesláno",
           "outPorts[0].options[sid].label": "Sid zprávy"
       },
       "sk": {
           "label": "Pošli SMS",
           "description": "Pošli SMS pomocou Twilia",
           "inPorts[0].name": "Správa",
           "inPorts[0].inspector.inputs.body.label": "Textová správa",
           "inPorts[0].inspector.inputs.from.label": "číslo volajúceho",
           "outPorts[0].name": "Odoslané",
           "outPorts[0].options[sid].label": "Sid správy"
       }
   }
}

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

Behaviour

Components receive incoming messages, process them, and generate outgoing messages. The way messages are processed is called component behaviour. It defines what components do internally and how they react to inputs.

Components are implemented as NodeJS modules that return an object with a set of methods (Component Virtual Methods) that the Appmixer engine understands. Let's start with a simple example, a SendSMS component that has one input port (message), no output ports and its purpose is to send an SMS using the Twilio API.

const twilio = require('twilio');

module.exports = {

    receive(context) {
        let { fromNumber } = context.properties;
        let { accountSID, authenticationToken } = context.auth;
        let message = context.messages.message.content;
        let client = new twilio(accountSID, authenticationToken);
        return client.message.create({
            body: message.body,
            to: message.to,
            from: fromNumber
        });
    }
};

Component Virtual Methods

As was mentioned in the previous paragraph, components are simple NodeJS modules that can implement a certain set of methods the Appmixer engine understands. The one most important method is the receive() method. This method is called by the engine every time messages are available on the input ports and the component is ready to fire (fire patterns match). The method must return a promise that when resolved, acknowledges the processing of the input messages. If the promise is rejected, the Appmixer engine automatically re-tries to send the messages again in the next turn (with some delay).

Messages that have been rejected 30-times are put in a special internal "dead-letter" queue and never returned to the flow for processing again. They can only be recovered manually by the Administrator.

For trigger-type of components, the most important virtual methods to remember is tick() and start().

Virtual Method

Description

receive(context)

Called whenever there are new messages on the input ports that the component is ready to consume. This method must return a promise that when resolved, tells the engine that the messages were successfully processed. When rejected, the engine re-tries to send the messages to the component again in the next turn (or with an arbitrary delay).

tick(context)

Called whenever the polling timer sends a tick. This method is usually used by trigger Components.

start(context)

Called when the engine signals the component to start (when the flow starts). This method is usually used by some trigger components that might schedule an internal timer to generate outgoing messages in regular intervals.

stop(context)

Called when the engine signals the component to stop (when the flow stops). This is the right place to do a graceful shutdown if necessary.

Context

All virtual methods have one argument, the context. The context contains all the information you need to process your messages and send new messages to the output ports.

Input/Output message(s)

context.messages

(applies to receive())

Incoming messages. An object with keys pointing to the input ports. Each message has a content property that contains the actual data of the message after all variables have been replaced. For example:

{
    receive(context) {
        const smsContent = context.messages.message.content;
    }
}

Remember, if before running the flow, the input port message was defined in the Inspector using variables:

where the flow descriptor would contain something like this:

Humidity: {{{$.ec8cd99f-0ad3-4bca-9efc-ebea5be6b596.weather.main.humidity}}}

the context.messages object contains the result of replacing variables with actual data that was sent through the output port of the connected component, i.e.

context.messages.message.content === 'Humidity: 75'

Each message also contains the correlation ID in the context.messages.myInputPort.correlationId property.

correlationId is a "session ID" that associates all the messages in one pass through the flow. Every time a trigger component sends a message to the flow (e.g. webhook, timer, ...) and the message does not have a correlation ID yet, the Appmixer engine assigns a new correlation ID to the message. This correlation ID is then copied to all the messages that were generated as a reaction to the original trigger message.

async context.sendJson(messageContent, outPort)

A method on the context object that you should call when you want to emit a message on one of the components output ports. The first argument can be any JSON object and the second argument is the name of an output port. The function returns a promise that has to be either returned from the receive() , tick() or start() methods or awaited.

async context.sendArray(arrayOfObjects, outPort, options)

A method for sending an array of objects to an output port.

const Promise = require('bluebird');

module.exports = {
    async receive(context) {
 
        // this is the old way, without context.sendArray function
        const arrayOfObjects = [
            { name: 'John', surname: 'Doe' },
            { name: 'Martin', surname: 'Tester' }
        ];   
        await Promise.map(arrayOfObjects, item => {
            return context.sendJson(item, 'out');
        });
        
        // and the new way
        await context.sendArray(arrayOfObjects, 'out');
        // by default it will be sending 5 items in parallel to the
        // output port. That default amount depends on Appmixer
        // configuration
        
        // the concurrency can be changed
        await context.sendArray(arrayOfObjects, 'out', {
            // sending one by one
            concurrency: 1  
        });
    }
}

Authentication

context.auth

The authentication object. It contains all the tokens you need to call your APIs. The authentication object contains properties that you defined in the auth object in your Authentication module (auth.js) for your service. For example, if our authentication module for our service (auth.js) looks like this:

const twilio = require('twilio');
module.exports = {
    type: 'apiKey',
    definition() {
        return {
            tokenType: 'authentication-token',
            accountNameFromProfileInfo: 'accountSID',
            auth: {
                accountSID: {
                    type: 'text',
                    name: 'Account SID',
                    tooltip: 'Log into your Twilio account and find <i>API Credentials</i> on your settings page.'
                },
                authenticationToken: {
                    type: 'text',
                    name: 'Authentication Token',
                    tooltip: 'Found directly next to your Account SID.'
                }
            },
            validate: context => {
                let client = new twilio(context.accountSID, context.authenticationToken);
                return client.api.accounts.list();
            }
        };
    }
};

we can use the context.auth.accountSID and context.auth.authenticationToken in the component virtual methods:

{
    receive(context) {
        let { accountSID, authenticationToken } = context.auth;
    }
}

There are components that do not require user authentication, but they use API keys to authenticate to other third-party services. For example the Weather components. They use an API key to https://openweathermap.org/api. In order to configure this API key (and not have it hardcoded), you can use access the context.auth.apiKey in the component and insert the apiKey into Backoffice:

module.exports = {

    receive(context) {

        // prepare the qs

        // the 'apiKey' value set in the Backoffice will be available
        // at context.auth.apiKey (and context.config.apiKey, context.config
        // is an alias to context.auth)
        return weather.get('/weather', qs, context.auth.apiKey)
            .then(body => {
                // process results
            });
    }
};

Backoffice configuration

context.config

When you configure your service/module in the Backoffice, you can access those values in the context.auth or context.config objects. context.config is just an alias to the original context.auth.

Properties

context.properties

The configuration properties of the component. This corresponds to the properties object from the component manifest file. For example, if our component defines the following properties in the manifest file:

{
    "properties": {
        "schema": {
            "properties": {
                "fromNumber": { "type": "string" }
            }
        },
        "inspector": {
            ...
        }
    }
}

context.properties.fromNumber will contain the value the user entered in the Designer UI Inspector:

{
    receive(context) {
        const fromNumber = context.properties.fromNumber;
    }
}

Component State

context.state

A persistent state of the component. Sometimes you need to store data for the component that must be available across multiple receive() calls for the same component instance. If you also need the data to be persistent when the flow is stopped and restarted again, set the state: { persistent: true } property in your component manifest. context.state is a simple object with keys mapped to values that are persistently stored in DB. This object is loaded on-demand in each receive() call. It is not recommended to store large amounts of data here. Example:

{
    async receive(context) {
        // Emit a message only once per day for this component instance.
        const day = (new Date).getDay();
        const state = context.state;
        if (!state[day]) {
            state[day] = true;
            await context.saveState(state);
            return context.sendJson({ tick: true }, 'out');
        }
    }
}

The context.state is especially useful for trigger-type of components when polling an API for changes to store the ID of the latest processed item from the API.

The context.state object should not be used to store large amounts of data. The state is loaded with each received message on a component input port. The maximum limit is 16MB but storing such large objects will slow down the processing of the component input messages.

async context.loadState()

Load the component's state from DB. The Component's state is loaded just before the component is triggered and the state is available it context.state, but there are cases when a component needs to reload the state from the DB.

async context.saveState(object)

Save an updated state object. See context.state for details. The function returns a promise that resolves if storing of the state was successful and rejects otherwise.

async context.stateSet(key, value)

Set a state key to hold the value. key must be a string. value can be any JSON object.

async context.stateGet(key)

Get a state value stored under key.

async context.stateUnset(key)

Remove a value under key.

async context.stateClear()

Clears the entire state.

async context.stateAddToSet(key, value)

Add value into set under key.

async context.stateRemoveFromSet(key, value)

Remove value from set under key.

async context.stateInc(key, value = 1, returnOriginal = false)

Increment value under key. The second parameter is optional, can be used to set the increment value. The function return by default the new value (after incremented), if returnOriginal is set to true, it will return the value before the increment.

Flow State

Similar to the component state, this state is available to all components in the flow.

async context.flow.loadState()

Load the state from the DB.

async context.flow.stateSet(key, value)

Set a state key to hold the value. key must be a string. value can be anything that can be stored in Mongo DB.

async context.flow.stateGet(key)

Get a state value stored under key.

async context.flow.stateUnset(key)

Remove a value under key.

async context.flow.stateClear()

Clears the entire state.

async context.flow.stateAddToSet(key, value)

Add value into a Set stored under key.

async context.flow.stateRemoveFromSet(key, value)

Remove value from Set stored under key.

async context.flow.stateInc(key, value = 1, returnOriginal = false)

Increment value under key. The second parameter is optional and can be used to set the increment value. The function return by default the new value (after incremented), if returnOriginal is set to true, it will return the value before the increment.

Service State

This is similar to the component state, but this state is available to all components in the module.

async context.service.loadState()

Load the state from the DB.

async context.service.stateSet(key, value)

Set a state key to hold the value. key must be a string. value can be anything that can be stored in Mongo DB.

async context.service.stateGet(key)

Get a state value stored under key.

async context.service.stateUnset(key)

Remove a value under key.

async context.service.stateClear()

Clears the entire state.

async context.service.stateAddToSet(key, value)

Add value into a Set stored under key.

module.exports = {

    async start(context) {

        // register webhook in the slack plugin
        return context.service.stateAddToSet(
            context.properties.channelId,
            {
                componentId: context.componentId,
                flowId: context.flowId
            }
        );
    },

    async stop(context) {

        return context.service.stateRemoveFromSet(
            context.properties.channelId,
            {
                componentId: context.componentId,
                flowId: context.flowId
            }
        );
    }
}

async context.service.stateRemoveFromSet(key, value)

Remove value from Set stored under key.

async context.service.stateInc(key, value = 1, returnOriginal = false)

Files

async context.saveFile(fileName, mimeType, buffer)

This method has been deprecated. Use context.saveFileStream instead. Save a file to the Appmixer file storage. This function returns a promise that when resolved gives you a UUID that identifies the stored file (this is different from the file Mongo ID). You can pass this ID through your flow (send it to an output port of your component) so that later components can load the file from the Appmixer storage using the file ID.

{
    receive(context) {
        // getAttachment() is some function that retrieves a file from an API
        return getAttachment(context.auth, context.messages.attachment.content.id)
            .then((file) => {
                return context.saveFile(file.name, file.mimeType, Buffer.from(file.data, 'base64'));
            })
            .then((result) => {
                return context.sendJson({ fileId: result.fileId }, 'file');
            });
    }
}

async context.saveFileStream(fileName, stream)

Save a file to the Appmixer file storage. The function returns a Promise that resolves with the ID of the stored file. This is a more efficient and recommended version of context.saveFile(name, mimeType, buffer).

async context.getFileInfo(fileId)

Returns a promise, which when resolved returns the file information (name, length, content type...). For backward compatibility, fileId can be either Mongo ID or UUID.

Example:

{
  "filename": "testFile",
  "contentType": "text",
  "length": 7,
  "chunkSize": 261120,
  "uploadDate": "2021-01-22T12:20:29.227Z",
  "metadata": {
    "userId": "5f804b96ea48ec47a8c444a7",
    "fileId": "fd0e9149-3249-4d42-b519-bfd9ab6773c5"
  },
  "md5": "9a0364b9e99bb480dd25e1f0284c8555",
  "fileId": "fd0e9149-3249-4d42-b519-bfd9ab6773c5"
}

async context.loadFile(fileId)

Load a file from the Appmixer file storage. For backward compatibility, fileId can be either Mongo ID or UUID. The function returns a promise that when resolved, gives you the file data as a Buffer.

{
    receive(context) {
        return context.loadFile(context.messages.file.content.fileId)
            .then((fileContent) => {
                // uploadFileToAPI() is some function that uploads a file to an API
                return uploadFileToAPI(context.auth, content.messages.file.content.fileName, fileContent);
            });
    }
}

context.readFileStream(fileId)

This method has been deprecated. Use context.getFileReadStream instead. Read a file stream from the Appmixer file storage. The function returns a NodeJS read stream that you can e.g. pipe to other, write streams (usually to a request object when uploading a file to a 3rd party API). This is a more efficient and recommended version of context.loadFile(fileId). fileId must be Mongo ID.

async context.getFileReadStream(fileId)

Read a file stream from the Appmixer file storage. The function returns a Promise, which when resolved, returns a NodeJS read stream that you can e.g. pipe to other, write streams (usually to a request object when uploading a file to a 3rd party API). This is a more efficient and recommended version of context.loadFile(fileId). This method is backward compatible, sofileId can be either be Mongo ID or UUID.

async context.removeFile(fileId)

Remove a file from the Appmixer file storage. The function returns a promise. fileId can be either Mongo ID or UUID.

Webhook

context.getWebhookUrl()

Get a URL that you can send data to with HTTP POST or GET. When the webhook URL is called, the receive() method of your component is called by the engine with context.messages.webhook object set and context.messages.webhook.content.data contains the actual data sent to the webhook URL:

module.exports = {
    async receive(context) {
        if (context.messages.webhook) {
            // Webhook URL received data.
            await context.sendJson(context.messages.webhook.content.data, 'myOutPort');
            // Send response to the webhook HTTP call.
            // Note: you can also skip sending response immediately and send it
            // in other connected components in the flow.
            // If context.response() is not called, the engine waits for the first component
            // that sends the response (in the same "session", i.e. the same "message flow").
            return context.response('<myresponse></myresponse>', 200, { 'Content-Type': 'text/xml' });
        }
        // Otherwise, normal input port received data.
        const input = context.messages.myInPort.content;

        // The webhook URL. Do something with it (send to your API, send to other connected,
        // components, send to your backend, ...)
        const url = context.getWebhookUrl();
    }
};

Note: The context.getWebhookUrl() is only available if you set webhook: true in your component manifest file (component.json). This tells the engine that this is a "webhook"-type of component.

The full context.messages.webhook object contains the following properties:

Property

Description

content.method

HTTP method of the request.

content.hostname

Hostname of the Appmixer API.

content.headers

HTTP headers of the request.

content.query

Object with query parameters, i.e. query string parsed into a JSON object.

content.data

Object with the body parameters of the request.

correlationId

A special ID generated by the Appmixer engine uniquely identifies the input message which resulted in generating the webhook URL. In other words, if you call context.getWebhookUrl() in the receive() method in a reaction to an input message that arrived on an input port of the webhook component, the correlationId will be part of the returned webhook URL. This allows you to later associate the input message with the HTTP call to the webhook. A common pattern is to store the input message in the context.state object and later use the context.messages.webhook.correlationId to retrieve it back. For example, if you have an input port named myInPort, you can get the correlationId of the input message that just arrived by accessing the context.messages.myInPort.correlationId.

async context.response(body, statusCode, headers)

Send a response to the webhook HTTP call. When you set your component to be a webhook-type of component (webhook: true in your component.json file), context.getWebhookURL() becomes available to you inside your component virtual methods. You can use this URL to send HTTP POST requests.

When a request is received by the component, the context.messages.webhook.content.data contains the body of your HTTP POST call. In order to send a response to this HTTP call, you can use the context.response() method. See context.getWebhookUrl() for details and examples.

HTTP

async context.httpRequest

Component do often trigger HTTP request. You don't have to install any library for that, you can use context.httpRequest. It is a wrapper around the axios library.

module.exports = {
  async receive(context) {
    const { data } = await context.httpRequest({
      url: "https://some-url.com/api",
      method: "POST",
      data: {
        username: "someuser",
        password: "somepass",
      },
      headers: { Authentication: "some"}        
    });
        
    // it is also possible to execute dedicated http methods
    // see here https://axios-http.com/docs/api_intro
    // for example
    // context.httpRequest.get(url[, config])
    const { data } = await context.httpRequest.get("https://url", { params: { name: "some" }, headers: {}});
    // context.httpRequest.post(url[, data[, config]])
    const { data } = await context.httpRequest.post("https://url", { username: "some" }, headers: {});
        
    return context.response(data);
  }
}

Store

async context.store.listStores()

Get the list of user's Data Stores.

async context.store.get(storeId, key)

Get value from the Data Store, stored under key.

async context.store.set(storeId, key, value)

Set value to the Data Store under key.

async context.store.remove(storeId, key)

Remove key from the Data Store.

async context.store.clear(storeId)

Clear all data from the Data Store.

async context.store.find(storeId, query)

Find items in the Data Store.

await context.store.find(storeId, { query: { key: { $nin: rowIds } } })

async context.store.getCursor(storeId, query, options)

Get cursor.

async context.store.registerWebhook(storeId, events = undefined)

Register Data Store webhook. If no events are specified, then the component will get all events from the Data Store. Possible events are insert, update and delete.

module.exports = {

    async receive(context) {

        // whenever there is an item added/updated/removed from the data
        // store, this component will get triggered with data on the
        // context.messages.webhook.content
        const data = context.messages.webhook.content.data.currentValue;

        if (context.messages.webhook.content.data.type === 'insert') {
            await context.sendJson({
                key: data.key,
                storeId: data.storeId,
                value: data.value,
                updatedAt: data.updatedAt,
                createdAt: data.createdAt
            }, 'item');
        }
        return context.response('ok');
    },

    async start(context) {

        // register without specifying 'events'.
        await context.store.registerWebhook(context.properties.storeId);
    },

    async stop(context) {

        await context.store.unregisterWebhook(context.properties.storeId);
    }
};

And the same functionality with registering only for the insert events.

module.exports = {

    async receive(context) {

        const data = context.messages.webhook.content.data.currentValue;
        await context.sendJson({
            key: data.key,
            storeId: data.storeId,
            value: data.value,
            updatedAt: data.updatedAt,
            createdAt: data.createdAt
        }, 'item');
        return context.response('ok');
    },

    async start(context) {

        // register only the 'insert' events on the data store.
        await context.store.registerWebhook(context.properties.storeId, ['insert']);
    },

    async stop(context) {

        await context.store.unregisterWebhook(context.properties.storeId);
    }
};

async context.store.unregisterWebhook(storeId);

Unregister webhook.

Miscellaneous

async context.setTimeout(messageContent, delay)

Set a timer that causes the component to receive messageContent in the receive() method in the special context.messages.timeout.content object. delay is the time, in milliseconds, the timer should wait before sending the messageContent to the component itself. Note that this is especially useful for any kind of scheduling component. The context.setTimeout() function works in a cluster environment as opposed to using the global setTimeout() JavaScript function. For example, a component that just slows down incoming messages before sending them to its output port, waiting e.g. 5 minutes, can look like this:

module.exports = {
    receive(context) {
        if (context.messages.timeout) {
            // Timeout message.
            return context.sendJson(context.messages.timeout.content, 'out');
        } else {
            // Normal input message.
            return context.setTimeout(context.messages.in.content, 5 * 60 * 1000);
        }
    }
};

You can also access the correlation ID of the timeout message which can be useful in some scenarios. The correlation ID is available in the context.messages.timeout.correlationId property.

The return value from this context method is a timeout Id (a UUID string). Each timeout has its own unique identifier. That can be used to clear that timeout.

async context.clearTimeout(timeoutId)

Will clear (cancel) scheduled timeout.

async context.callAppmixer(request)

Call an Appmixer REST API endpoint. You can call any of the Appmixer endpoints defined in the API section. The main advantage of this method (as opposed to calling the API endpoint manually) is that the method automatically populates the "Authorization" header of the request to the access token of the user who owns the flow this component lives in. For example:

const task = await context.callAppmixer({
    endPoint: '/people-task/tasks',
    method: 'POST',
    body: {
        title: 'My Task',
        description: 'My Example Task',
        requester: 'john@example.com',
        approver: 'alice@example.com',
        decisionBy: (function() {
            const tomorrow = new Date;
            tomorrow.setDate(tomorrow.getDate() + 1);
            return tomorrow.toISOString();
        })()
    }
});

async context.stopFlow()

Stop the running flow. Example:

module.exports = {
    async receive(context) {
        return context.stopFlow();
    }
};

context.componentId

The ID of the component.

context.flowId

The ID of the flow the component lives in.

context.flowDescriptor

The flow descriptor of the flow in which the component instance lives. This allows you to access configuration of the entire flow within your component virtual methods. To get the configuration of the component itself, you can use context.flowDescriptor[context.componentId]. Note that this is normally not necessary since you can access the properties of the components by context.properties and the current input message by context.messages.myInPort.content but can be useful in some advanced scenarios.

context.customFields

Flow customFields property is available here.

async context.loadVariables()

Allows you to load variables in your component definition. Variables are data available from components connected back in the chain. loadVariables() returns a promise that resolves to an array that looks like this:

[
  {
    "variables": {
      "dynamic": [
        {
          "label": "Column A",
          "value": "columnA",
          "componentId": "2c724dff-a04b-43ed-9787-c9a891a721cc",
          "port": "out"
        },
        {
          "label": "Column B",
          "value": "columnB",
          "componentId": "2c724dff-a04b-43ed-9787-c9a891a721cc",
          "port": "out"
        }
      ],
      "static": {}
    },
    "sourceComponentId": "2c724dff-a04b-43ed-9787-c9a891a721cc",
    "outPort": "out",
    "inPort": "in"
  },
  {
    "variables": {
      "dynamic": [
        {
          "label": "Column C",
          "value": "columnC",
          "componentId": "71eb1f40-ce29-4963-8922-102739bafee4",
          "port": "out"
        },
        {
          "label": "Column D",
          "value": "columnD",
          "componentId": "71eb1f40-ce29-4963-8922-102739bafee4",
          "port": "out"
        }
      ],
      "static": {}
    },
    "sourceComponentId": "71eb1f40-ce29-4963-8922-102739bafee4",
    "outPort": "out",
    "inPort": "in"
  }
]

The return array has as many items as there are other components connected to this component.

Example:

{
    receive(context) {
        return context.loadVariables()
            .then(data => {
                const newSchema = data.reduce((acc, item) => {
                    return acc.concat(item.variables.dynamic.map(o => ({ label: o.label, value: o. value })));
                }, []);
                context.sendJson(newSchema, 'leftJoin');
                context.sendJson(newSchema, 'innerJoin');
                context.sendJson(newSchema, 'rightJoin');
            });
    }
}

async context.log(object)

Log message into InsightsLogs. The argument has to be an object.

Example:

{
    async start(context) {
        
        await context.log({ test: 'my test log' });
        return context.sendJson({ started: (new Date()).toISOString() }, 'out');
    }
}

And the object can be seen in logs (and InsightsLogs as well):

async context.lock(lockName, options)

This method allows components to create a lock. This is useful when creating a mutually exclusive section inside the component's code. Such a thing can be achieved in Appmixer using either quota (you can define quota the way that only one receive call can be executed at a time) or using this lock. This method returns the lock instance. Don't forget to call lock.unlock() when you're done. Otherwise, the lock will be released after TTL.

lockName string will be prefixed with vendor.service:. If a component type is appmixer.google.gmail.NewEmail, then the lockName will be prefixed with appmixer.google:. This allows you to create a lock that is shared among all components within a service and prevents possible collisions between components from different vendors or services.

The first parameter is required, the second (options) is optional with the following optional properties:

ttl, number, 20000 by default (ms)
retryDelay, number, 200 by default (ms)
maxRetryCount, number, 30 by default

Example:

    async receive(context) {

        let lock = null;
        try {
            lock = await context.lock(context.flowId, {
                ttl: 30000,
                maxRetryCount: 1
            });
            let { callCount = 0, messages = [] } = await context.loadState();
            messages.push(context.messages.in.originalContent);

            if (++callCount === context.messages.in.content.callCount) {
                await context.sendJson(messages || [], 'out');
                await context.saveState({ callCount });
                return;
            }

            await context.saveState({ callCount, messages });
        } finally {
            if (lock) {
                await lock.unlock();
            }
        }
    }

Error Handling

Every function a component implements may throw an exception (or return rejected promise).

receive(context)

If this function throws an exception, then the Appmixer engine will try to process the message that triggered this receive call again in a minute. There is an exponential backoff strategy, so the next attempt will happen in a minute and a half and so on. In total, Appmixer will try to process that message 30 times before it is saved into unprocessedMessages collection. Every unsuccessful attempt will be logged and visible in Insights.

Sometimes you, as a developer of a component, know that there is no point in retrying a message. It would fail, again and again, 30 times. In such a case, you can tell Appmixer to cancel the message.

/**
 * Example of context.CancelError
 */
module.exports = {

    async receive(context) {

        let data = context.messages.in.content;

        try {
            // In this component is trying to create a record in a 3rd party
            // system.
            const resp = await someAPI.createSomething(data);
            await context.sendJson(resp, 'out');
        } catch (err) {
            // And there might be a unique constraint, let's say an email
            // address. And the 3rd party API will return an error with a
            // message saying that this record cannot be created.
            if (err.message === 'duplicate record') {
                // In this case, we can tell Appmixer to cancel the message.
                // Because next attempt would fail again with the same result.
                throw new context.CancelError(err.message);
            }
            // In case of any other error, rethrow the exception. Appmixer will
            // then try to process it again.
            throw err;
        }
    }
};

tick(context)

If a tick function throws an exception, such exception is logged (and visible in Insights) and that is it. Appmixer will trigger this function again in the future.

start(context)

Appmixer won't start a flow if any component in the flow throws an exception in the start function. Such error will be logged and visible in Insights.

stop(context)

Appmixer will stop the flow even when a component in the flow throws an exception in the stop function. Such errors will be logged and visible in Insights.

Dependencies

Component NodeJS modules can use 3rd party libraries which are defined in the standard package.json file. An example:

{
    "name": "appmixer.twilio.sms.SendSMS",
    "version": "1.0.0",
    "private": true,
    "main": "SendSMS.js",
    "author": "David Durman <david@client.io>",
    "dependencies": {
        "twilio": "^2.11.0"
    }
}

The package.json file from the example above tells the Appmixer engine to load the twilio library that the appmixer.twilio.sms.SendSMS component requires for its operation.

More information on the package.json file can be found at https://docs.npmjs.com/files/package.json.

Authentication

Components that require authentication from the user must implement an authentication module for the service/module they belong to. The authentication module must be named auth.js and must be stored under either the service or module directory (i.e. [vendor]/[service]/auth.js or [vendor/[service]/[module]/auth.js. Appmixer currently supports four types of authentication mechanisms that are common for today's APIs: API key, Password, OAuth 1, and OAuth 2.

Appmixer provides an easy way to configure authentication modules. Most of the time, it's just about configuring a 3rd party service provider URLs for authentication, requesting access tokens, and token validation.

Authentication Module Structure

Each authentication module is a NodeJS module that returns an object with type and definition properties. type can be either apiKey, pwd, oauth (for OAuth 1) and oauth2 (for OAuth 2). definition is either an object or a function (useful in cases where there's a code that you need to run dynamically).

type

The type of authentication mechanism. Any of apiKey, pwd, oauth and oauth2.

definition

The definition of the authentication mechanism is specific to the API service provider. An object or a function. This differs significantly between authentication mechanisms.

If the definition property is specified as a function, in that case, it has one argument context. It is an object that contains either consumerKey, username and password, consumerSecret (OAuth 1) or clientId, clientSecret (OAuth 2) and it always contains callbackUrl property. This will be shown later in the examples.

Authentication mechanisms

As it was mentioned in the beginning, Appmixer authentication supports four mechanisms: API Key, Password, OAuth 1 and OAuth 2. Each of them has a different definition.

function, object, or a URL string

In the following examples we will show how a particular property of the definition object can be specified as a function, object or string. Let's demonstrate that on a requestProfileInfo property, that one is common for all authentication mechanisms.

// or any library you want to perform API requests
const request = require('request-promise');

module.exports = {

    // there will be some other properties based on the authentication mechanism
    // defined prior requestProfileInfo
    
    definition: {
    
        // requestProfileInfo can be defined as a function. In this case, you
        // can do whatever you need in here and return object with user's
        // profile information (in promise)
        requestProfileInfo: async context => {
    
            // curl https://mydomain.freshdesk.com/api/v2/agents/me \
            //  -u myApiKey:X'
            return request({
                method: 'GET',
                url: `https://${context.domain}.acme.com/api/v2/agents/me`,
                auth: {
                    user: context.apiKey  // 'context' will be explained later
                },
                json: true
            });
        },
        
        // or you can specify it as an object. In this case, the object follows
        // the 'request' (https://www.npmjs.com/package/request) javascript library
        // options.
        requestProfileInfo: {
            method: 'GET',
            url: 'https://acme.com/get-some-records/app_id={{appId}}',
            headers: {
                'Authorization': 'Basic {{apiKey}}'  // {{apiKey}} explained later
            }
        },
        
        // the last way is to specify just the URI. In this case Appmixer
        // will perform GET request to that URI.
        requestProfileInfo: 'https://acme.com/get-profile-info?apiKey={{apiKey}}'
        // if you define 'requestAccessToken' property in an Oauth2 authentication
        // module with a string that contains a URL, then a POST request will be \
        // sent to that URL. In other words, what will happen, when a property 
        // is defined as a string, depends on the context (Oauth vs ApiKey ...).
    }
}

API key

This is the most basic type of third-party authentication since you only need to provide a sort of ID and a key provided by the app in concern. In order to use this mechanism, type property must be set to apiKey. Here is an example from Freshdesk components:

module.exports = {

    type: 'apiKey',

    definition: {

        tokenType: 'authentication-token',

        auth: {
            domain: {
                type: 'text',
                name: 'Domain',
                tooltip: 'Your Freshdesk subdomain - e.g. if the domain is <i>https://example.freshdesk.com</i> just type <b>example</b> inside this field'
            },
            apiKey: {
                type: 'text',
                name: 'API Key',
                tooltip: 'Log into your Freshdesk account and find <i>Your API Key</i> in Profile settings page.'
            }
        },

        accountNameFromProfileInfo: 'contact.email',

        requestProfileInfo: async context => {

            // curl https://mydomain.freshdesk.com/api/v2/agents/me \
            //  -u myApiKey:X'
            return context.httpRequest({
                method: 'GET',
                url: `https://${context.domain}.freshdesk.com/api/v2/agents/me`,
                auth: {
                    user: context.apiKey,
                    password: 'X'
                },
                json: true
            });
        },

        validate: async context => {

            // curl https://mydomain.freshdesk.com/api/v2/agents/me \
            //  -u myApiKey:X'
            const credentials = `${context.apiKey}:X`;
            const encoded = (new Buffer(credentials)).toString('base64');
            await context.httpRequest({
                method: 'GET',
                url: `https://${context.domain}.freshdesk.com/api/v2/agents/me`,
                headers: {
                    'Authorization': `Basic ${encoded}`
                }
            });
            // if the request doesn't fail, return true (exception will be captured in caller)
            return true;
        }
    }
};

Now we explain the fields inside the definition object:

auth (object)

This is basically the definition for the form that will be displayed to the user to collect the data required by the third-party application. Freshdesk requires the domain name and the API key in order to authenticate Appmixer. So we define two fields representing those items and we define the label and tooltip that will appear in the form for each field. In this case, the auth definition will make Appmixer render a form like this:

The values introduced by the user will be exposed in the context object with the same keys as in the auth object. In this case, we will be able to access the values as context.domain and context.apiKey.

requestProfileInfo (function, object or string) (optional)

While this field is optional, is recommended for a better UX. This field can be a function that returns a promise, object, or string. It is about calling an endpoint from the third-party app which returns the current user info. This will be used to display a name for this account in Appmixer.

accountNameFromProfileInfo (function or string)

This field is the path in the object returned by requestProfileInfo that points to the value that will be used as the account name. Following the example, the object returned by requestProfileInfo would have a structure like this:

{
    contact: {
        email: 'appmixer@example.com',
        name: 'Appmixer example',
        // More properties here...
    }
    // There can be more properties here as well...
}

We want to use the email to identify the Freshdesk accounts in Appmixer, so we set accountNameFromProfileInfo as contact.email.

If requestProfileInfo is not defined, the auth object will be used instead. The account name will be the resolved value for the property specified by accountNameFromProfileInfo.

validate (function, object or string)

Similar to requestProfileInfo. This is used to validate if the authentication data entered by the user is correct. For this purpose you can call any endpoint that requires authentication, you can even use the same endpoint as requestProfileInfo. If the data is correct, this function should resolve to any non-false value. Otherwise, throw an error or resolve to false. You can define validate as an object. In that case, that object has the same structure as the object passed into the request library. In that case, it will look like this:

'use strict';

module.exports = {

    type: 'apiKey',

    definition: {

        tokenType: 'apiKey',

        accountNameFromProfileInfo: 'appId',

        auth: {
            appId: {
                type: 'text',
                name: ' APP ID',
                tooltip: 'Log into your account and find Api key.'
            },
            apiKey: {
                type: 'text',
                name: 'REST API Key',
                tooltip: 'Found directly next to your App ID.'
            }
        },

        // In the validate request we neet the appId and apiKey specified by user.
        // All properties defined in the previous 'auth' object will be
        // available in the validate call. Just use {{whatever-key-from-auth-object}}
        // anywhere in the next object. Appmixer will replace these with the
        // correct values.
        validate: {
            method: 'GET',
            url: 'https://acme.com/get-some-records/app_id={{appId}}',
            headers: {
                'Authorization': 'Basic {{apiKey}}'
            }
        }
    }
};

If the validate function throws an exception and the exception contains message property, the message will be shown in the Connecting Account Failed page.

The validate can be specified as an object and the Appmixer engine will perform such a request. In this case, the response error can vary from API to API. Appmixer will try to find the error message in the response. If the error message is not shown on the Connecting Account Failed page, then the validate response can always be parsed and proper exception thrown in the auth.js module using the validateErrCallback function:

validate: {
    'method': 'GET',
    'uri': 'https://api.apify.com/v2/users/{{apiUserId}}?token={{apiToken}}'
},

 validateErrCallback: err => {

    if (err?.someNestedObject?.message) {
        throw new Error(err.someNestedObject.message);  // message for the UI
    }
    throw err;
}

Password

The password-based authentication is almost similar to key-based authentication as explained in the above section. The only difference is that you will use username and password inputs. The auth property inside definition will need to have two inputs as shown in the below-given code snippet. The validate method is used to validate the input values provided. You can make API call by using the context.username and context.password properties. If the API you are validating returns a token, it will have to be returned from the validate method as shown below.

'use strict';

module.exports = {

    type: 'pwd',

    definition: {

        // As opposed to the 'apiKey' module, the 'auth' property inside the 
        // definition object is optional for the 'pwd' type. If omitted, it will 
        // have the following structure. If you want to change name of the field,
        // change the content of the tooltip or add another field, you can do
        // that here. 
        auth: {
            username: {
                type: 'text',
                name: 'Username',
                tooltip: 'Username'
            },
            password: {
                type: 'password',
                name: 'Password',
                tooltip: 'Password'
            }
        },

        // the only mandatory property for the 'pwd' authentication type
        validate: async context => {
        
            const { username, password } = context
            const { data } = await context.httpRequest.post(
                // the URL for the username/password authentication
                'https://service-server-api-url/auth',
                { username, password }
            );
            
            // verify authentication works
            if (!data.isValid) {
                throw new Error("Invalid username/password combination.");
            }
            
            // if the API does not return a token for exchange, then return here.
            // in such case, the components using this authentication module
            // will have to use the username/password to perform each request.
            // There will be properties context.auth.username and 
            // context.auth.password available in the context object in a component.
            
            // if the API returns a token and expiration then return them using 
            // the following way - object with 'token' and 'expires' properties.
            const { token, expiresIn } = data;
            
            // the token and expiration (if provided) will be available in a
            // component's context object under context.auth.token and
            // context.auth.expires
            return {
                token,
                // expires can be a Date - token expiration date (timestamp),
                // or number/string with seconds representing a token lifetime.
                // Appmixer will use this to request a new token (using stored
                // username and password) when the current one is about to expire
                expires: expiresIn
            };
            
            // if the API returns a token that does not expire, just return
            // that token 
            // return { token };
        }
    }
};

HTTP Basic Authentication

The pwd type can be used for the HTTP Basic Authentication. Here's a sample code:

'use strict';
module.exports = {

    type: 'pwd',

    definition: {

        validate: async context => {

            await context.httpRequest.get('https://postman-echo.com/basic-auth', {
                auth: {
                    username: context.username,
                    password: context.password
                }
            });
        }
    }
}

Then the username and password is available in the components:

'use strict';
module.exports = {

    async start(context) {

        await context.httpRequest.get('https://postman-echo.com/basic-auth', {
            auth: {
                username: context.auth.username,
                password: context.auth.password
            }
        });
    }
}

OAuth 1

In order to use this mechanism, type property must be set to oauth. Here is an example from Trello components:

'use strict';
const OAuth = require('oauth').OAuth;
const Promise = require('bluebird');

module.exports = {

    type: 'oauth',

    // In this example, 'definition' property is defined as a function. 
    definition: context => {

        let trelloOauth = Promise.promisifyAll(new OAuth(
            'https://trello.com/1/OAuthGetRequestToken',
            'https://trello.com/1/OAuthGetAccessToken',
            context.consumerKey,
            context.consumerSecret,
            '1.0',
            context.callbackUrl,
            'HMAC-SHA1'
        ), { multiArgs: true });

        return {

            accountNameFromProfileInfo: 'id',

            authUrl: context => {

                return 'https://trello.com/1/OAuthAuthorizeToken' +
                    '?oauth_token=' + context.requestToken +
                    '&name=AppMixer' +
                    '&scope=read,write,account' +
                    '&expiration=never';
            },

            requestRequestToken: () => {

                return trelloOauth.getOAuthRequestTokenAsync()
                    .then(result => {
                        return {
                            requestToken: result[0],
                            requestTokenSecret: result[1]
                        };
                    });
            },

            requestAccessToken: context => {

                return trelloOauth.getOAuthAccessTokenAsync(
                    context.requestToken,
                    context.requestTokenSecret,
                    context.oauthVerifier
                ).then(result => {
                    return {
                        accessToken: result[0],
                        accessTokenSecret: result[1]
                    };
                });
            },

            requestProfileInfo: context => {

                return trelloOauth.getProtectedResourceAsync(
                    'https://api.trello.com/1/members/me',
                    'GET',
                    context.accessToken,
                    context.accessTokenSecret
                ).then(result => {
                    if (result[1].statusCode !== 200) {
                        throw new Error(result[1].statusMessage);
                    }
                    result = JSON.parse(result[0]);
                    // get rid of limits for now
                    // may and will contain keys with dots - mongo doesn't like it
                    delete result.limits;
                    return result;
                });
            },

            validateAccessToken: context => {

                return trelloOauth.getProtectedResourceAsync(
                    'https://api.trello.com/1/tokens/' + context.accessToken,
                    'GET',
                    context.accessToken,
                    context.accessTokenSecret
                ).then(result => {
                    if (result[1].statusCode === 401) {
                        throw new context.InvalidTokenError(result[1].statusMessage);
                    }
                    if (result[1].statusCode !== 200) {
                        throw new Error(result[1].statusMessage);
                    }

                    result = JSON.parse(result[0]);
                    if (result['dateExpires'] === null) {
                        return;
                    }
                    throw new context.InvalidTokenError('Invalid token.');
                });
            }
        };
    }
};

Note that in this case, the definition is a function instead of an object, but it still returns an object with the items needed for OAuth 1 authentication, similar to API key authentication. Now we explain the fields from the definition object:

accountNameFromProfileInfo (function or string)

Works exactly the same way as described in the API Key section.

requestRequestToken (function, object or string)

This must be a function (or an object, or just a string URL as explained here) that returns a promise which must resolve to an object containing requestToken and requestTokenSecret the same way that is shown in the example. Those are needed to get the access token and become exposed by the context - context.requestToken and context.requestTokenSecret.

requestAccessToken (function, object or string)

This must be a function (or an object, or just a string URL as explained here) that returns a promise which must resolve to an object containing accessToken and accessTokenSecret the same way that is shown in the example. Usually, you will be using the requestToken and requestTokenSecret inside this function, as they are required by the OAuth 1 flow in this step. Similarly to requestRequestToken function, accessToken and accessTokenSecret will become exposed by the context - context.accessToken and context.accessTokenSecret.

authUrl (function, object or string)

Function, object or a string URL returning auth URL. Appmixer will then use this URL to redirect the user to the proper login page. The requestToken is available in the context. The example shows the authUrl declaration using the token provided by the context.

requestProfileInfo (function, object or string) (optional)

Works exactly the same way as described in the API Key section.

validateAccessToken (function or object)

This property serves the same purpose as validate property in the API Key mechanism. This is used by Appmixer to test if the access token is valid and accepted by the third-party app. You have access to context.accessToken and context.accessTokenSecret to make authenticated requests. If the token is valid, this function should resolve to any non-false value. Otherwise, throw an error or resolve to false.

OAuth 2

The latest OAuth protocol and industry-standard, OAuth 2.0 improved many things from the first version in terms of usability and implementation, while maintaining a high degree of security. It is easier to implement in Appmixer as well. In order to use this mechanism, type property must be set to oauth2. Here is an example from Asana auth.js:

'use strict';
const request = require('request-promise');

module.exports = {

    type: 'oauth2',

    // function definition is used in this case because of the 'profileInfo'
    // property. It is set in the 'requestAccessToken' function and then
    // later returned in 'requestProfileInfo' function.
    definition: () => {

        let profileInfo;

        return {

            accountNameFromProfileInfo: context => {

                return context.profileInfo['email'] || context.profileInfo['id'].toString();
            },

            authUrl: 'https://app.asana.com/-/oauth_authorize',

            requestAccessToken: context => {

                // don't put params into post body, won't work, have to be in query
                let tokenUrl = 'https://app.asana.com/-/oauth_token?' +
                    'grant_type=authorization_code&code=' + context.authorizationCode +
                    '&redirect_uri=' + context.callbackUrl +
                    '&client_id=' + context.clientId +
                    '&client_secret=' + context.clientSecret;

                return request({
                    method: 'POST',
                    url: tokenUrl,
                    json: true
                }).then(result => {
                    profileInfo = result['data'];
                    let newDate = new Date();
                    newDate.setTime(newDate.getTime() + (result['expires_in'] * 1000));
                    return {
                        accessToken: result['access_token'],
                        refreshToken: result['refresh_token'],
                        accessTokenExpDate: newDate
                    };
                });
            },

            requestProfileInfo: () => {

                return profileInfo;
            },

            refreshAccessToken: context => {

                // don't put params into post body, won't work, have to be in query
                let tokenUrl = 'https://app.asana.com/-/oauth_token?' +
                    'grant_type=refresh_token&refresh_token=' + context.refreshToken +
                    '&redirect_uri=' + context.callbackUrl +
                    '&client_id=' + context.clientId +
                    '&client_secret=' + context.clientSecret;

                return request({
                    method: 'POST',
                    url: tokenUrl,
                    json: true
                }).then(result => {
                    profileInfo = result['data'];
                    let newDate = new Date();
                    newDate.setTime(newDate.getTime() + (result['expires_in'] * 1000));
                    return {
                        accessToken: result['access_token'],
                        accessTokenExpDate: newDate
                    };
                });
            },

            validateAccessToken: {
                method: 'GET',
                url: 'https://app.asana.com/api/1.0/users/me',
                auth: {
                    bearer: '{{accessToken}}'
                }
            }
        };
    }
};

Notice that there is no requestRequestToken method in OAuth 2, but there is the requestAccessToken used to get the token and refreshAccessToken method, which is used by Appmixer to refresh the access tokens. Now we explain the definition object's properties:

accountNameFromProfileInfo (function or string)

Works exactly the same way as described in the API Key section.

authUrl (function, object or string)

Similar to OAuth 1, we should provide the authentication URL for the third-party app. However, due to the different authentication flows supported by OAuth 2, the way this is defined may vary according to the third-party implementation. If the OAuth 2 implementation is standard, you can define the authUrl with just a string like:

authUrl: 'https://www.dropbox.com/oauth2/authorize'

Standard means, there is a response_type parameter set to code, then there is the client_id, redirect_uri, state and scope parameter. If the OAuth 2 implementation requires any other parameters (or the standard ones use different names), then you have to define this property as a function and provide all the additional parameters. The same logic applies to the following property requestAccessToken.

requestAccessToken (function, object or string)

This function should return a promise with an object which contains accessToken, refreshToken (optional, some OAuth 2 implementations do not have refresh tokens) and accessTokenExpDate or expires_in (also options if the implementation does not have tokens that expire). Inside this function, we call the endpoint which handles the access tokens for the application. Inside this function you have access to context properties you need: clientId, clientSecret, callbackUrl and authorizationCode.

requestProfileInfo (function, object or string) (optional)

Works exactly the same way as described in the API Key section.

refreshAccessToken (function, object or string)

Part of the OAuth 2 specification is the ability to refresh short-lived tokens via a refresh token that is issued along with the access token. This function should call the refresh token endpoint on the third-party app and resolve to an object with accessToken and accessTokenExpDate properties, as shown in the example. You have access to context properties clientId, clientSecret, callbackUrl and refreshToken.

validateAccessToken (function, object or string)

Has the exact same purpose as the same method in the OAuth 1.

There are more ways the OAuth 2 can be implemented. It always depends on the third-party server and its OAuth 2 implementation.

This is an example of the Dropbox auth.js module:

'use strict';

module.exports = {

    type: 'oauth2',

    definition: {

        accountNameFromProfileInfo: 'email',

        authUrl: 'https://www.dropbox.com/oauth2/authorize',

        requestAccessToken: 'https://api.dropbox.com/oauth2/token',

        requestProfileInfo: {
            'method': 'POST',
            'uri': 'https://api.dropboxapi.com/2/users/get_current_account',
            'headers': {
                'authorization': 'Bearer {{accessToken}}'
            }
        }
    }
};

It can be that simple, if the third party API implements OAuth 2 according to standards. And in this Dropbox case, their OAuth 2 implementation does not contain refresh tokens.

Sometimes the OAuth 2 needs a scope or a different scope delimiter. Here is a full example of the Microsoft authentication module with such features:

'use strict';
const TENANT = 'common';

module.exports = {

    type: 'oauth2',

    definition: {

        scope: ['offline_access', 'user.read'],

        scopeDelimiter: ' ',

        authUrl: `https://login.microsoftonline.com/${TENANT}/oauth2/v2.0/authorize`,

        requestAccessToken: 'https://login.microsoftonline.com/common/oauth2/v2.0/token',

        refreshAccessToken: 'https://login.microsoftonline.com/common/oauth2/v2.0/token',

        accountNameFromProfileInfo: 'displayName',

        emailFromProfileInfo: 'mail',

        requestProfileInfo: 'https://graph.microsoft.com/v1.0/me',

        validateAccessToken: {
            method: 'GET',
            url: 'https://graph.microsoft.com/v1.0/me',
            auth: {
                bearer: '{{accessToken}}'
            }
        }
    }
};

scope

String or an array of strings.

scopeDelimiter

String. The default one is , and you can change it to ' ' for example.

refreshBeforeExp

By default, the Appmixer engine will try to refresh the access token five minutes before its expiration. This is fine for most of the OAuth2 implementations, where an access token is usually valid for hours or days. However, there are OAuth2 implementations with stricter rules. With this property, you can define how many minutes (default, see refreshBeforeExpUnits) before the access token expiration should Appmixer refresh the token. Appmixer will not try to refresh the token before this value.

module.exports = {

    type: 'oauth2',

    definition: () => {

        // telling Appmixer it cannot refresh it sooner than 30 seconds 
        // before access token expiration
        refreshBeforeExp: 30,
        refreshBeforeExpUnits: 'seconds',   // 'minutes' by default
        
        // the rest is business as usual
        authUrl: 'https://www.acme.com/oaut2/authorize'
        
        ...
    }
}

refreshBeforeExpUnits

Works in cooperation with the refreshBeforeExp property. Useful if you need to go down to seconds. See the example above.

OAuth 2 redirect URI

When you're developing an OAuth 2 application, at some point you have to register an app in the 3rd party system. For that, you need the redirect URI that points to the Appmixer API. The format of the redirect URI is https://[appmixer-url]/auth/[service]/callback.

So if the service you're developing is called myService then the redirect URI will be https://[appmixer-url]/auth/myService/callback.

Context

Context properties are different for each authentication type. But some of them are common for all types.

async context.httpRequest

Wrapper around the axios library.

module.exports = {

    type: 'pwd',

    definition: {

        // the only mandatory property for the 'pwd' authentication type
        validate: async context => {
        
            const { username, password } = context;
            const { data } = await context.httpRequest.post(
                // the URL for the username/password authentication
                'https://service-server-api-url/auth',
                { username, password }
            );
            
            // verify authentication works
            if (!data.isValid) {
                throw new Error("Invalid username/password combination.");
            }            
            return true;
        }
    }
};

Setting OAuth 1,2 secrets

The OAuth applications need some secrets: consumerKey, consumerSecret (OAuth 1), or clientId, clientSecret (OAuth 2).

You can use the Backoffice to do that. This is the preferable way.

Another way is the credentials.json file which has to be located where your auth.js file is.

Then when you pack and publish your component archive, Appmixer will read the file and store the values into Mongo DB. Later it will use them to create the context object for your auth.js module.

Quotas & Limits

The majority of APIs define limits on the API usage. Components that call APIs need to make sure that these limits are respected, otherwise their API calls would start failing quickly. The quota.js module allows you to specify what those limits are on a per-service, per-module or even per-component basis. The Appmixer engine uses this module to make sure API calls are throttled so that the usage limits are respected.

The quota module must be named quota.js and must be stored under either the service, module or component directory (i.e. [vendor]/[service]/quota.js , [vendor/[service]/[module]/quota.jsor [vendor/[service]/[module]/[component]/quota.js.

An example of a quota module:

module.exports = {
    rules: [
        {
            limit: 2000,
            throttling: 'window-sliding',
            window: 1000 * 60 * 60 * 24,
            scope: 'userId',
            resource: 'messages.send'
        },
        {
            limit: 3,
            window: 1000,
            throttling: 'window-sliding',
            queueing: 'fifo',
            resource: 'messages.send',
            scope: 'userId'
        }
    ]
};

The quota definition above tells the engine to throttle the receive() call of the component to a max of 2000-times per day and 3-times per second.

Quota Module Structure

Quota modules are NodeJS modules that return an object with one property rules.

rules

An array of rules that define usage limits. Each rule can have the following properties:

limit

Maximum number of calls in the time window specified by window.

window

The time window in milliseconds.

throttling

The throttling mechanism. Can be either a string 'window-sliding' or an object with type and getStartOfNextWindow function. Example of a quota module for LinkedIn:

const moment = require('moment');

module.exports = {
    rules: [{
        // The limit is 25 per day per one user.
        limit: 25,
        window: 1000 * 60 * 60 * 24,
        throttling: 'window-sliding',
        queueing: 'fifo',
        resource: 'shares',
        scope: 'userId'
    }, {
        // The limit is 125000 per day per application.
        limit: 125000,
        throttling: {
            type: 'window-fixed',
            getStartOfNextWindow: () => {
                // Daily quotas refresh at midnight PST.
                return moment.utc().startOf('day').add(1, 'day').add(8, 'hours').valueOf();
            }
        },
        resource: 'shares'
    }]
};

resource

An identifier of the resource to which the rule applies. The resource is a way for a component to pick rules that apply to that specific component. This can be done in the component manifest file in the quota.resources section.

You can also configure system webhook to receive the quota errors when raised. Read more about it here.

Configuration

Sometimes you need to configure your module and have a different configuration for different environments. QA vs Production for example.

You can use the Backoffice to set the configuration key/values:

The key to the Backoffice Service Configuration depends on the component.json. If it is a component with auth section, then the key is the service. Let's take a Slack component.json for example:

{
    "name": "appmixer.slack.list.NewChannelMessageRT",
    "description": "As opposed to NewChannelMessage and NewPrivateChannelMessage this trigger fires immediately every time a message is posted to a channel. Works both for public and private channels.",
    "webhook": true,
    "auth": {
        "service": "appmixer:slack",  // appmixer:slack will be used as a 'key'
        "scope": [
            "channels:read",
            "channels:history"
        ]
    },
    "outPorts": [
    ...
}

In this case, the appmixer:slack will be used as a key into the Backoffice. Then you can store various key/value pairs in the Service Configuration:

A good example is the clientID and clientSecret. Slack is an Oauth2 application and it needs a different Oauth application for each environment (due to the redirect URL). All of these values will be available in the component's context object (and in the context object in the auth.js file as well).

module.exports = {

    async tick(context) {
    
        context.auth.clientId;
        context.auth.clientSecret;
        context.auth.orAnythingElse;
        
        // all of those will be available at context.config as well
        context.config.clientId;
        context.config.clientSecret;
        context.config.orAnythingElse;        
    }
}

If your component/module does not use user authentication (no auth section in the component.json file), then the key to the Backoffice Service Configuration depends on the name of the component. Here's an example.

// component.json file without "auth" section
{
    // the property "name" will be used to look for configuration stored through
    // the Backoffice. Appmixer will try to look for a key [vendor]:[service] and
    // [vendor]:[service]:[module]
    "name": "appmixer.utils.tasks.RequestApprovalEmail",
    "description": "People Task is a feature of Appmixer that allows human interaction inside workflows.",
    "webhook": true,
    "inPorts": [
        {
   ...
}

For such component/module you can store configuration under appmixer:utils or under appmixer:utils:tasks. Such key/value configuration pairs will be then available under context.config.

Example Component

Here's a how a full example of a component that sends SMS via the Twilio service can look like:

Directory Structure

twilio/
├── auth.js
├── package.json
├── service.json
└── sms
    ├── ListFromNumbers
    │   ├── ListFromNumbers.js
    │   ├── component.json
    │   ├── package.json
    │   └── transformers.js
    └── SendSMS
        ├── SendSMS.js
        ├── component.json
        └── package.json

Component Behaviour (sms/SendSMS/SendSMS.js)

Defines how the component reacts on incoming messages.

const twilio = require('twilio');

module.exports = {

    receive(context) {

        let { accountSID, authenticationToken } = context.auth;
        let client = twilio(accountSID, authenticationToken);
        let message = context.messages.message.content;

        return client.messages.create({
            body: message.body,
            to: message.to,
            from: message.from
        }).then(message => {
            return context.sendJson(message, 'sent');
        });
    }
};

Component Manifest (sms/SendSMS/component.js)

Defines the component properties and metadata.

{
    "name": "appmixer.twilio.sms.SendSMS",
    "author": "David Durman <david@client.io>",
    "icon": "data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMjUwMCIgaGVpZ2h0PSIyNTAwIiB2aWV3Qm94PSIwIDAgMjU2IDI1NiIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIiBwcmVzZXJ2ZUFzcGVjdFJhdGlvPSJ4TWlkWU1pZCI+PGcgZmlsbD0iI0NGMjcyRCI+PHBhdGggZD0iTTEyNy44NiAyMjIuMzA0Yy01Mi4wMDUgMC05NC4xNjQtNDIuMTU5LTk0LjE2NC05NC4xNjMgMC01Mi4wMDUgNDIuMTU5LTk0LjE2MyA5NC4xNjQtOTQuMTYzIDUyLjAwNCAwIDk0LjE2MiA0Mi4xNTggOTQuMTYyIDk0LjE2MyAwIDUyLjAwNC00Mi4xNTggOTQuMTYzLTk0LjE2MiA5NC4xNjN6bTAtMjIyLjAyM0M1Ny4yNDUuMjgxIDAgNTcuNTI3IDAgMTI4LjE0MSAwIDE5OC43NTYgNTcuMjQ1IDI1NiAxMjcuODYgMjU2YzcwLjYxNCAwIDEyNy44NTktNTcuMjQ0IDEyNy44NTktMTI3Ljg1OSAwLTcwLjYxNC01Ny4yNDUtMTI3Ljg2LTEyNy44Ni0xMjcuODZ6Ii8+PHBhdGggZD0iTTEzMy4xMTYgOTYuMjk3YzAtMTQuNjgyIDExLjkwMy0yNi41ODUgMjYuNTg2LTI2LjU4NSAxNC42ODMgMCAyNi41ODUgMTEuOTAzIDI2LjU4NSAyNi41ODUgMCAxNC42ODQtMTEuOTAyIDI2LjU4Ni0yNi41ODUgMjYuNTg2LTE0LjY4MyAwLTI2LjU4Ni0xMS45MDItMjYuNTg2LTI2LjU4Nk0xMzMuMTE2IDE1OS45ODNjMC0xNC42ODIgMTEuOTAzLTI2LjU4NiAyNi41ODYtMjYuNTg2IDE0LjY4MyAwIDI2LjU4NSAxMS45MDQgMjYuNTg1IDI2LjU4NiAwIDE0LjY4My0xMS45MDIgMjYuNTg2LTI2LjU4NSAyNi41ODYtMTQuNjgzIDAtMjYuNTg2LTExLjkwMy0yNi41ODYtMjYuNTg2TTY5LjQzMSAxNTkuOTgzYzAtMTQuNjgyIDExLjkwNC0yNi41ODYgMjYuNTg2LTI2LjU4NiAxNC42ODMgMCAyNi41ODYgMTEuOTA0IDI2LjU4NiAyNi41ODYgMCAxNC42ODMtMTEuOTAzIDI2LjU4Ni0yNi41ODYgMjYuNTg2LTE0LjY4MiAwLTI2LjU4Ni0xMS45MDMtMjYuNTg2LTI2LjU4Nk02OS40MzEgOTYuMjk4YzAtMTQuNjgzIDExLjkwNC0yNi41ODUgMjYuNTg2LTI2LjU4NSAxNC42ODMgMCAyNi41ODYgMTEuOTAyIDI2LjU4NiAyNi41ODUgMCAxNC42ODQtMTEuOTAzIDI2LjU4Ni0yNi41ODYgMjYuNTg2LTE0LjY4MiAwLTI2LjU4Ni0xMS45MDItMjYuNTg2LTI2LjU4NiIvPjwvZz48L3N2Zz4=",
    "description": "Send SMS text message through Twilio.",
    "auth": {
        "service": "appmixer:twilio"
    },
    "outPorts": [
        {
            "name": "sent",
            "options": [
                { "label": "Message Sid", "value": "sid" }
            ]
        }
    ],
    "inPorts": [
        {
            "name": "message",
            "schema": {
                "type": "object",
                "properties": {
                    "body": { "type": "string" },
                    "to": { "type": "string" },
                    "from": { "type": "string" }
                },
                "required": [
                    "from", "to"
                ]
            },
            "inspector": {
                "inputs": {
                    "body": {
                        "type": "text",
                        "label": "Text message",
                        "tooltip": "Text message that should be sent.",
                        "index": 1
                    },
                    "from": {
                        "type": "select",
                        "label": "From number",
                        "tooltip": "Select Twilio phone number.",
                        "index": 2,
                        "source": {
                            "url": "/component/appmixer/twilio/sms/ListFromNumbers?outPort=numbers",
                            "data": {
                                "transform": "./transformers#fromNumbersToSelectArray"
                            }
                        }
                    },
                    "to": {
                        "type": "text",
                        "label": "To number",
                        "tooltip": "The destination phone number. <br/><br/>Format with a '+' and country code e.g., +16175551212 (E.164 format).",
                        "index": 3
                    }
                }
            }
        }
    ]
}

Component Dependencies (sms/SendSMS/package.json)

Our component uses the twilio NodeJS library. Therefore, we need to list it as a dependency.

{
    "name": "appmixer.twilio.sms.SendSMS",
    "version": "1.0.0",
    "main": "SendSMS.js",
    "author": "David Durman <david@client.io>",
    "dependencies": {
        "twilio": "^3.14.0"
    }
}

Service Manifest (service.json)

Metadata about the Twilio service. The Appmixer UI uses this information to display the Twilio app in the Apps panel of the Designer UI.

{
    "name": "appmixer.twilio",
    "label": "Twilio",
    "category": "applications",
    "description": "Twilio is a cloud communications platform as a service.",
    "icon": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAGQAAABkCAYAAABw4pVUAAAABmJLR0QA/wD/AP+gvaeTAAAACXBIWXMAAAsTAAALEwEAmpwYAAAPEElEQVR42u2df5RVVRXHP+85MyA/hBBLkHO1pGsqCqL9wsRqlSmWUVFqGEiR/VyZQVlp1kL7g5X9tlZqRZpkJrmszFr2a6EtTE1+iGAdMexcbMxAMkdkBpjpj7Mv3m5v3rvn3PNm3iB7rbfWc+Tdc87+3rN/nb33qdAClEQxyuj83zqA4UAHcChwAhDLZxLwQmA8cCAwTH7WDTwLbAWeALYAWj5rgMeBHmCnMrqn0RwGgyqtBEQSxQcDRwNTgOnyOU5ACUE9wHpgtXweBB5SRm9rFWAqLQLE6cBcYCpwGDBugKbyJPAYsA5Yroz+9WADUxksIJIoHg18GLgYeAGtQduBpcC3ldFPDwYwAw3IMGAysAC4EGijNWk38HVgGbBJGd09UANXm70jMt9nAtcC9wKLWhgMZG6LZK7Xytz/b01DZoekk1ZGk0TxGOC7wCxgBEOTdgC3AwuV0U9l19fSgOSAaAfOA65p8d3gKsouAG5QRu9qBjCVkGBkFPZ04HPAbPZNuhW4XBm9OrTiDy6ykiheDHwCmMC+TZ3AV5TRV7aUyMoouQ4RT/MG2+EcQOoDrhcx1hNCfFXLAiETmAj8AZj/PAIjfaHny9onZkT2oO6QU4HrgMN5ftPfgfnK6JUDLrJSJZZE8euBm7BBvmbTLuA+YC3wF+BR4J9Al4iOdD2jgBcBRwAvA6YBLwfaB2COW4GzldG/91X0FR8g5PvLgT81ybnsBfYI028AViijNzZyPuvJ8CSKjwHmiCl+BHBAE+f+KmX0fT4WmO8OeT3wmyYs6D/AA8AdwI3K6E1NclwnA+cCpwHHAwc1AZQ3KqN/37QdkhFTpwIrAoupXcDV8tz7ldFdNQyHoI6r/Pco4ETZOR8ILNa2AnOU0StddknFcTETgVWBFfhNwGKgUxm9pxlAFADmAPGbrgTODqzoZwD/KLqWatHJi59xcyAw+rAHRScro89RRm8RnbGXUc0Medd4/h5l9BZl9DnAyTK3vgBDHS486yhqDleLKnFx+mYEmGQX8AXg1croVc3eDUUByqx3FfBqmWNXgMfPEN6lIr+8YyjhkHkBJrcOOEUZvUQZ/UyrnGNngZE5PaOMXgKcInMuS/OEh/46JKPEpwO3BYhN/Qo4Nw1ftxIQDdY/BrgROCNA7OvNyujV9dbfSGS1Y6O2ZcG4DjhzqICR2y1PAWfKGsrQBOBzwlM3kZVh2nmUD6Ffqow+XxndN1TAqAFKnzL6fODSko+cDZxXT5fUE1ljxJYuc7h0KbBUGb17qIHRj/hqwyZlXFHicbuB8bLznAC5WRwmbzElb9U+R0kU/wAb5fWlFcrod7qIrJnYM/AyCnxBUdt7KO0UoQWyRl+alU2c6BeQJIrTVJ2F+CckrBNrqpDOKAJYCFBDjJPVKRIL8zWJRwALkygelh+zUmNSx2LTX3wA6RI/Y21RMDJO2YnAW7FppCOAf8k8blFGP1bDUXWS//L9UODtwCuxucHPAhuBXwD3ZBheVKdMA+7ChvxdaQfwCmX0hpo7JLcdfcDoA75UBIzMWAclUXx2EsUPA38WE/ttwJvEwvsGsCWJ4l8mUfyKdL6ub3sSxSclUXyr+ALfEif3dBnrEuwxwuYkis8DxjYaIwPcWuBLnmGWEbXEeiW3iNHYfFcfy2q9hEOeKfh2xcDXHByu3cBXgcuU0TsL7o52CYEs4rkM+Ub0W+DjyugNBXfLSOBubFK4j8U1Lk1bpcYb9+ESZu4H03BIAUZNBH7q6P22AZ8EvplEcUe9cUQXtguAn3UAA+ANwC1JFKuC4vAZ4IOePGsTnu/FoJoL7F3s+eCb0kBhARlfwaaUTvEcayEwtz/nKjOHOcBHPMeIsdkk1YJKfhX2GMGHLs5iUE0XJSUBPlnou7DnGUX1xrySJjXAd5IoPqTWeMKksdgDrzL02vzb2x8oQouFF670AuE9SRRTzTxwrufErwY6i5iMQl8O4BJ0AEtqKO/062eA0QHGuSKJ4o6CpntniZdgbsqjVIccjC2WcaX/iNe5p4g5mkTxWYQrxlmQ35WZ7x8JNMZBwDuKxLzktHOF8MSVpgoGe2XkMdjKJVd6ALjfUQyEovYkil9VA/TjCJdlXwFOdXBO7xeeuNJhgsFeQI71eHN7gTuU0V0OnvRLCJfZWJHn5enIwBGTFzfSjxljogubMdPrOMY4wYCqVLtO95joHuzBjQsND8ysYQMwhmvB6Y1k8gMcaHoSxR1VWYAPIJuV0ZscwxnbAzPr3zX+9iRhEhSyetIlzrUJ2OwDCDC8Km+Aj5e53FPnhGJWpZ/g3gMBxWKaHeMaQ/PhzXFARxVblO9TB77CY6I/C8iszcrov9V4Ux+XgGEo0H9e9B9neLHCUzQeWsV2SHB2BvvLtW0w4Y3APYGYVc8PuSzQGA8qo+/1XKePk3hCVcIErnRfWf+hJG1QRv8gr78ycvyWknNM6XwHkzcEj2JfQNb6zFCY9RDwqRJM2k6x49OF2DMVX/q8Mvr+ErkAa30BmeTxw7/4zDATEPwa8BWPR+zGFsX0y6jMLnkAe6biU/T/bWBpycQMHx5NasOenLnSo76zlAXuAhYlUbwZewhVRNH/A5viv7ERozKg3CEnoL+jeE7yJwMVcvrw6IVt+JUV/LPMTDP5vFclUXyLKOGT5eUYjS2m6QaewrZY+mnKpKJvbQaUR4Ajkii+EJvZPgl7KjhMHLguEW13A0uU0SZQvrEPj8ZXkijeidsBThpq2Vg2zyp33n0wtg/KeGydxg5sf6u/pr1GApypdwBHYbMIR4gI3Ao8ooz+l+8Y/bxwxwAbHH/a3eYBBqGcu2xSgfSs2tZgR5XRW0jTsvWps1cPvEBOpXMoqKnNZ1qFhlLGZJvIatddEsTbrtE/KxVZbdgUnU7gYWV0b1mRldkpcU5kbROR9VTRNKAm8qi7kkTxdlFyLvRKHw82J4Iqkkw3Fpv+8zpsOfNo7LFAjyh1gy0A/Y4rKDnA3wu8R6ytsRKq6BWl/gRwpyj1rSGUuqQtuUYl/l2RnKjJjj88Sxn9iwA7ZB62dVORYstHgDcoox91TGabiE3tObrAGL3Ah5TR1wRY21tc4mBCm9rk7XAF5IiSu6MNmy91icNPjwQeSqL4LGX0b+qBkgFjJrbP1ciCY1SBq5Mofik2fWhXiV3iw6MnqmLnu9JRJXXGhxzBSGk4sDyJ4uPr1VjI/zsa+LEDGFlaDFxUpCYwMI+2VLE9bV3J50ArZdSR4p370iHA9xs5ndhCyzKVX0uTKJ5SYof48Ej7AnJSiYV+P4AFc2ISxefk3+CMqDoTeE2AccqUsZ3kC8gajx+2S+8QV5EVAzMDmexL8pZQ5vsXA40xPYniEzzWeQx+XSHWVHmu/bYrzcmJiCI0m3BHuC9NovjwGsw4BNu/JJS3PdsBiP/hjSP1AI+n9v56jwf4ZDpOJex597Qaf59G2HP7qR4vng9v1gM9VWAntg+6K704ieLJjpZI6Bbi4/r5W8iudmOLOIkZ/TUZyeVypNXAzqoE3HwAOQBb1uW6LUNSzyCNUY/OFd44A6KM7kmDixuw+UwuVAVOS6J4lINp+LeA4qSP2vlPIccAOWgqmJc1CtuDyzVo+6RgsPeHG7G3BLjS8dh+U0XpzoCM2iN1GXnGrMPv2LY/0O9yiGud6GlQPCYY7C3Y2YZfRelBwJwkig8oqEd+Ru1sQx/6Yf7NzXy/OtAYXdhKr4b6Q3puzcGvO9269A6TamYRyz0n/QFgQkGl14ut3ShLvUibi378kCvEWClLlyujdxSsfZkgvPCh5SmP9hbsyGUmPrm37dhObEUrja7FJh2UoY8qozvrlLRtw8bLytA9FCguyszhSk9ncHt6kUy2YGdv/MZz8mcnUTyjoAncC7wXeNhzrBuAZY3SgIAfAd8rocjfLXMtElWegX9rwKVZDAazLHoKNsj4OocxrgI+3WiMzFgHApcDFzlYPn8EPqaMXjNoZdEZRj2NvVnGh6Zg68GLFt0/iC0Xex8256oe3SUxsIscSq9RRj+LzZI8BWjUsvUJbHnzbGX0mkaWVWYOi/CvKP66MvrpfhsHyEAD3lojieK0dOxt2BSjkcKge4GbldE6++8dA33ZY9wjgXdhW2u8CJtqtFGsvz8oo/cMdmuNSg3Uh4nifY8n6uuAU4t2j3NpUON7NlH0945gjAFW4lcsm5rt7we6s2NW+hl0Jrb9kG/x5O3Y/oJ9Q7lxWYMdfRv+9fY7gDOU0XfWCn/UkvN3ClN9aRb2hrN9BozcWpZRrvnB7bXAoIHlsVCsAF+an0TxJdIWb0g3Mst0u2hLovgSynWT2y28pTAgmW6cF5RcyxVkenkMRVByIrdsv0WAC7I3veWp0uCtaAd+QvnOpNcBC4aaTsnpjGUldwbYy8TeRZ30okbdbnaJY9VZciLzgduSKB4zVHZKzpq6LQAYnRIbq1t7WC3gwK3GVjuVPWOYBaxMonhaiLuamq0vMn7GSsp3L+rD3ui2upGEKBROkGKZ6wOsdypwVxLFlyVRPLLVdktmV4xMovgycfqmBnj09UWrsgo16EqVEfbukLI0CptGencakBzs3ZLbFTMkNvUFTw88T6tS46iI/tx/oQutdaHL/iuPhuqVR7mF7b8UrD41/1KwvAwcoGvzNmOPN0NemzcXmze1T12bN1gXS/4Zm0P2V4pdLHkUNgv9JPbFiyX7AWf/1avPKfDSV6+GuJx4pVgSq57HYKwCZqRgDPblxOnX/dd3B7AI919wXy42FfyC+2pAILJhljdjI5v7Kt2KPRFtmI82qDskF4Jox7ZHuoZy91i1Eu0W8XSDMnpXMyIKTZH1OWDGYGvRZxGuwfFA0w7skfbC7OFSM0I7TVW+OUdyJvbo8h1DCJgd2GTr76Zn4M0+YBtQa0jut5qM7bt4YQuLst3YhMFlwKa0PdRA0EB3A+pWRm9QRi/Glp59hvDNlcvQdpnTOGX0Ykli6x7ICQyKv5Df9nJ/xlzsYdBhhK9F7I+exBbLrAOWp1noAyGaWgqQOsAcjO3Ediw2BjUd6fgcaMi04ni1fDZgO+NtG2wgWgKQekyQdnzDBYwJ2HLnWD6TsP0ZxwMH8ly/r25sn62t2NzgLdhOFRrbtrVTQNkpxa60ChAp/RdLBDnJ9t9abQAAAABJRU5ErkJggg=="
}

Service Authentication Module (auth.js)

Defines the authentication for the Twilio service. This information is used both for rendering the Authentication dialog (displayed when the user clicks on "Connect New Account" button in the Designer UI inspector) and also for the actual authentication to the Twilio API and validation of the tokens.

const twilio = require('twilio');
module.exports = {
    type: 'apiKey',
    definition: () => {
        return {
            tokenType: 'authentication-token',
            accountNameFromProfileInfo: 'accountSID',
            auth: {
                accountSID: {
                    type: 'text',
                    name: 'Account SID',
                    tooltip: 'Log into your Twilio account and find <i>API Credentials</i> on your settings page.'
                },
                authenticationToken: {
                    type: 'text',
                    name: 'Authentication Token',
                    tooltip: 'Found directly next to your Account SID.'
                }
            },
            validate: context => {
                let client = new twilio(context.accountSID, context.authenticationToken);
                return client.api.accounts.list();
            }
        };
    }
};

Service Authentication Module Dependencies (package.json)

Our auth.js module uses the twilio NodeJS library. Therefore, we need to list it as a dependency.

{
    "name": "appmixer.twilio",
    "version": "1.0.0",
    "dependencies": {
        "twilio": "^3.14.0"
    }
}

Helper Component (sms/ListFromNumbers/ListFromNumbers.js)

This is a helper component that is used to list the phone numbers registered in the user's Twilio account. You can see that this component is called in the "static" mode in the SendSMS component manifest. Note that this component is not used out of necessity but more as a convenience for the user. Thanks to this component, the user can just select a phone number from a list of all their registered phone numbers in the Designer UI inspector. An alternative would be to let the user enter the phone number in a text field. However, that might result in errors to the API calls to Twilio if the phone number does not exist in the user's list of registered phone numbers in their Twilio account.

const twilio = require('twilio');

module.exports = {

    receive(context) {

        let { accountSID, authenticationToken } = context.auth;
        let client = twilio(accountSID, authenticationToken);
        return client.incomingPhoneNumbers.list()
            .then(res => {
                return context.sendJson(res, 'numbers');
            });
    }
};

Helper Component Manifest (sms/ListFromNumbers/component.json)

Note the component is marked as "private" meaning that it will not be available in the Designer UI as a standalone component.

{
    "name": "appmixer.twilio.sms.ListFromNumbers",
    "author": "David Durman <david@client.io>",
    "description": "When triggered, returns a list of numbers from user.",
    "private": true,
    "auth": {
        "service": "appmixer:twilio"
    },
    "inPorts": [ "in" ],
    "outPorts": [ "numbers" ]
}

Helper Component Dependencies (sms/ListFromNumbers/package.json)

{
    "name": "appmixer.twilio.sms.ListFromNumbers",
    "version": "1.0.0",
    "description": "Appmixer component for twilio to get a list of phone numbers of a user.",
    "main": "ListFromNumbers.js",
    "author": "David Durman <david@client.io>",
    "dependencies": {
        "twilio": "^3.14.0"
    }
}

Helper Component Transfomer (sms/ListFromNumbers/transformers.js)

The numbers output port of our helper component returns a list of numbers. However, when the component is called in a static mode from our SendSMS component Inspector UI, the expected value is a list of objects with label and value properties so that it can be rendered by the UI. Alternatively, we could have just skip the transformer altogether and use this array structure right in our context.sendJson() call in our ListFromNumbers.js file. The advantage of using transformers is that we can use the ListFromNumbers component as a regular component (i.e. not private) and so allow the user to put the component in their flows. In other words, the same component can be used for static calls (to show a list of available phone numbers in the Inspector UI of the SendSMS component) as well as in a normal mode (as a regular component that can be put in a flow).

module.exports.fromNumbersToSelectArray = (numbers) => {
    let transformed = [];
    if (Array.isArray(numbers)) {
        numbers.forEach(number => {
            transformed.push({
                label: number['phoneNumber'],
                value: number['phoneNumber']
            });
        });
    }
    return transformed;
};

Customizing UI

Custom Inspector Fields

The Inspector widget in the Designer UI provides built-in types such as text, number, toggle, select and others (See the Properties section of the Component Manifest for details). However, thanks to the modular design of the Designer UI, customized installations of the Appmixer system allows to extend the set of Inspector fields by custom types.

Defining Custom Inspector Fields

To define your custom inspector field, use the Appmixer JavaScript SDK appmixer.registerInspectorField(type, definition, options) method. To style your inspector field, just use regular CSS. definition is a Vue JS component. The component must call the change(value) method to tell the SDK to change the value of the inspector field and save the flow. The componet additionally adds this.value which stores the current value of the field in the flow descriptor. Therefore, calling change(newValue) will also change this.value. options are additional options that control the behaviour of the inline editor that replaces your inspector field when the user selects a variable from the variable picker. Available options are:

Option

Default value

Description

readOnly

false

Set read only mode on the inline editor. Available values are true, false, "nocursor" (similar to true but no cursor is blinking).

singleVariable

false

Allow only a single variable to be selected in the variable picker, i.e. selecting another variable will replace the current inline editor content.

clearButton

true

Show clear button at the right edge of the inline editor allowing the user to switch back to your custom field.

Note that the definition is an Appmixer specific wrapper around a Vue JS component. The basic functions and properties you can use are:

Template and Render function: https://vuejs.org/v2/api/#template, https://vuejs.org/v2/api/#render
Data objects: https://vuejs.org/v2/api/#data, https://vuejs.org/v2/api/#computed, https://vuejs.org/v2/api/#methods, https://vuejs.org/v2/api/#watch
Livecycle hooks: https://vuejs.org/v2/api/#Options-Lifecycle-Hooks
this.invalid computed property is a boolean value that tells the field whether its value is valid or not. An example is a required field that is empty. In that case this.invalid will be true.
Properties propagated by Appmixer are (properties that can be accessed via this keyword, e.g. this.value):

props: { context: { type: Object }, value: { type: null, required: false }, errors: { type: Array, default: () => ([]) }, disabled: { type: Boolean, default: false } }

The context object contains contextual data from the component and the current input. It has the following structure: context: { componentId: { type: String }, inputManifest: { type: Object }, componentManifest: { type: Object }, descriptorPath: { type: String }, variables: { type: Object } }

Basic example

Here's a very basic example of a custom inspector field with just one HTML input element. Note how we use the Vue JS template definition. Also note that we need to call the change() method to propagate the value back to the flow descriptor (i.e. to save the flow with the new value of the field when the user makes a change):

appmixer.registerInspectorField('your-custom-text-input', {
    template: `
        <div class="your-custom-text-input">
            <label>Name</label>
            <input :value="value" @change="change($event.target.value)">
        </div>
    `
});

Advanced example

Here's another example of a custom inspector field that accepts a value that represents first and last name of a person in one string. The inspector field renders two HTML inputs, one for first name and one for last name. The returned value (the one stored back to the flow descriptor) is again one string. Note how we call this.change(value) to propagate value of the inspector field to the flow descriptor (i.e. to save the flow with a new value for this field):

appmixer.registerInspectorField('your-custom-input-type', {
    template: `
        <div class="your-custom-input-field">
            <label>Firstname</label>
            <input v-model="firstname" @change="onChange">
            <label>Lastname</label>
            <input v-model="lastname" @change="onChange">
        </div>
    `,
    watch: {
        value: {
            immediate: true,
            handler(value = '') {
                this.firstname = value.split(' ')[0] || '';
                this.lastname = value.split(' ')[1] || '';
            },
        },
    },
    data() {
        return {
            firstname: '',
            lastname: '',
        };
    },
    methods: {
        onChange() {
            const name = [
                this.firstname.trim(),
                this.lastname.trim(),
            ].join(' ');
            this.change(name);
        },
    },
});

To style your inspector field, just use regular CSS in your application, e.g:

.your-custom-input-field {
    font: 14px 'Segoe UI', Verdana, sans-serif;
}
.your-custom-input-field label {
    display: block;
    margin: 10px 0 5px;
    color: #888;
}
.your-custom-input-field input {
    display: block;
    padding: 0.5em;
    border: solid 1px #e8e8e8;
    border-radius: 5px;
}

Custom Theme

Customize UI widgets. You can change the colors, the typography, and much more.

Basic usage

To customize the widgets, you need to specify a theme JSON object. However, this is optional; the UI comes with a default light theme. Create a new Appmixer instance with the theme option:

const appmixer = new Appmixer({
    theme: {
        variables: {
            font: {
                family: “sans-serif”
            },
            colors: {
                neutral00: “orange”
            }
        }
    }
});

Or/and use the option with individual widgets:

const flowManager = appmixer.ui.FlowManager({
    el: "#my-flow-manager",
    theme: {
        variables: {
            colors: {
                neutral00: 'purple'
            }
        }
    }
});

Usage with multiple themes

If you wish to switch between themes, use the set("theme") method, this will re-render the UI:

// change the theme of all widgets
appmixer.set('theme', {
    variables: {
        font: {
            family: 'serif'
        },
    }
})

// or/and change the theme of a single widget
widget.set('theme', {
    variables: {
        colors: {
            neutral00: 'green'
        }
    }
});

Variables

Change the overall styling with a few global CSS properties. Here is a complete example with defaults:

appmixer.set('theme', {
    variables: {
        font: {
            family: '\'SF Pro Text\', \'Helvetica Neue\', \'Helvetica\', \'Arial\', sans-serif',
            familyMono: '\'SF Mono\', \'ui-monospace\', Menlo, monospace',
            weightRegular: 400,
            weightMedium: 500,
            weightSemibold: 600,
            size: 14
        },
        colors: {
            base: '#FFFFFF',
            neutral: '#131314',
            focus: '#3688EB',
            error: '#DE3123',
            warning: '#B56C09',
            success: '#09CD96',
            modifier: '#C558CF',
            highlighter: '#FFA500'
        },
        shadows: {
            backdrop: 'rgba(0 0 0 / 6%)',
            popover: '0 3px 9px rgba(0 0 0 / 12%)',
            icon: '0 1px 3px rgb(0 0 0 / 6%)'
        },
        corners: {
            radiusSmall: '3px',
            radiusMedium: '6px',
            radiusLarge: '9px'
        },
        dividers: {
            regular: '1px',
            medium: '2px',
            semibold: '3px',
            bold: '6px',
            extrabold: '9px'
        }
    }
})

Colors

The numbers in the names of colors refer to a foreground opacity of the color over the base background color:

neutral96 is a foreground color with 96% opacity over the background neutral00.
Some colors need a negative color NG on top. For example, a white text on a blue button.

Font

The numbers in size of the font refer to the defaults in pixels: size13 variable default is 13px.

Shapes

Shapes of connectors in diagrams are customizable by choosing a preset in your theme.

appmixer.set('theme', {
    ui: {
        shapes: {
            action: "action",
            trigger: "trigger",
            selection: "selection"
        }
    }
})

Change the values of the entries to switch between presets. Here are built-ins per shape type:

action

action-vertical

action-dark

action-dark-vertical

trigger

trigger-vertical

trigger-dark

trigger-dark-vertical

selection

selection-vertical

selection-dark

selection-dark-vertical

Use Custom Shapes to create new presets or override the defaults.

Charts

Charts are customizable by a unique set of non-CSS properties. The values default to the current theme variables, except for colorway. The colorway option specifies the dynamic colors automatically picked by charts.

appmixer.set('theme', {
    ui: {
        charts: {
            legendFontSize: 12px,
            legendFontFamily: "sans-serif",
            legendFontColor: "black",
            tickFontSize: "black",
            tickFontFamily: "monospaced",
            tickFontColor: "black",
            gridColor: "lightgray",
            colorway: [
                '#1452cc',
                '#8a47c4',
                '#c636b0',
                '#ef2c94',
                '#ff3d74',
                '#ff5e52',
                '#ff8230',
                '#ffa600'
            ]
        }
    }
})

Selectors

The theme JSON object references the entire Appmixer SDK UI in a complex tree of selectors. Elements use a hash symbol (#) prefix and dynamic states use the at sign (@). Each branch in the tree may hold nested selectors and any valid CSS properties for the element. The selectors are available for advanced customizations, but the structure may change between the Appmixer versions.

appmixer.ui.FlowManager({
    el: '#app',
    theme: {
        ui: {
            '#FlowManager': {
                background: 'lightblue',
                '#header': {
                    padding: '0 0 24px 0',
                    '#buttonCreateFlow': {
                        color: 'yellow',
                        '@hovered': {
                            color: 'white'
                        }
                    }
                }
            }
        }
    }
});

Complete Theme Object

For reference, we prepared a dark theme for all the Appmixer UI widgets that you can use as a quick overview of all the UI elements that you can set your custom theme for:

wget  https://my.appmixer.com/appmixer/package/theme-light.json
wget  https://my.appmixer.com/appmixer/package/theme-dark.json

Screenshots of the dark theme for some of the UI widgets:

Custom Strings

Appmixer SDK allows you to change all the strings of all the UI widgets it provides (Designer, FlowManager, Insights, ...). This is especially useful to localize the entire Appmixer UI.

Setting Custom Strings

A strings object is represented as a JSON object that you set on your Appmixer SDK instance using the set('strings', myStrings) method:

var appmixer = new Appmixer({ baseUrl: BASE_URL });
appmixer.set('strings', STRINGS);

You can set the strings object anywhere in your application but usually, you'll do that right after initializing your appmixer instance. Note that you can even set the strings multiple times with different configurations in which case the Appmixer SDK will automatically re-render all the UI widgets using the configuration with new strings.

If you don't set strings, the default strings will be applied.

Structure of the Strings Object

The strings object is a JSON object (with one exception, see below) that contains references to various UI elements within the Appmixer UI. The final values of the JSON objects are the actual strings used in the UI.

Example of setting the strings object:

appmixer.set('strings', {
    ui: {
        flowManager: {
            search: 'Search flows',
            header: {
                buttonCreateFlow: 'Create new Flow'
            }
        }
    }
});

Complete Strings Object

For reference, we prepared a complete strings object for you to download and inspect to see all the possibilities for strings customization/localization.

wget  https://my.appmixer.com/appmixer/package/strings-en.json

Time Localization

For localization of time-related strings, a special time root scope of the strings object can be modified:

appmixer.set('strings', {
  time: {
    months: [...],
    monthsShort: [...],
    weekDaysShort: [...],
    ordinal(number){ ... },
    relativeTime: {...}
  }
});

Please download the default strings object above to see all the possibilities for time localization. Notice in the code above that there is one specialty to the time localization which (if used) makes the strings object non-JSON compliant. That's the ordinal(number) function. Given a number, this function returns a string representing the number in ordinal form (i.e. 1 becomes "1st", 2 becomes "2nd", ...). Since this is hard to describe declaratively in JSON, the strings object may contain the oridnal(number) function for you to be able to localize ordinal numbers. The default implementation looks like this:

ordinal(number) {
   const b = number % 10;
   const output = (~~(number % 100 / 10) === 1) ? 'th'
       : (b === 1) ? 'st'
           : (b === 2) ? 'nd'
               : (b === 3) ? 'rd' : 'th';
   return number + output;
}

Pluralization and Strings with Variables

Some text can contain both singular and plural versions based on whether the number variable used inside the text equals 1 or not. For example, the pagination widget in the Flows Manager:

The "of 198 flows" string used above can vary based on whether the total number of flows is more than one or if it equals one. The two versions can be expressed using the | character in the strings object like so:

appmixer.set('strings', {
    ui: {
        flowManager: {
            pagination: '{{range}} of {{total}} flow|{{range}} of {{total}} flows'
        }
    }
});

Also, notice the use of variables ({{total}} in the example above). Variables are always enclosed by two curly brackets and are replaced by the SDK with the actual numbers when used. See the Appmixer default strings object for all occurrences of variables.

Custom API

Appmixer SDK allows you to override any API method used by the SDK instance.

Setting a custom API option

Custom API is represented as an object composed of asynchronous methods that you set on your Appmixer SDK instance using the api option:

var myCustomApi = {
  /* the key must match an existing API method */
  myCustomApiMethod(/* arguments of the original method */) {
    return new Promise((resolve) => {
      resolve(myCustomResponse);
    });
  }
}

/* Use a custom API on the entire SDK instance */
var appmixer = new Appmixer({ api: myCustomApi });

/* Use a custom API on a particular SDK UI widget */
var designer = new appmixer.ui.Designer({ api: myCustomApi });

The list of API methods can be found here.

An example how to redefine the flow update request.

/* Create "Designer". */
var designer = appmixer.ui.Designer({
    el: '#your-designer',
    options: designerOptions(),
    api: {
        // extending the updateFlow request
        updateFlow(flowId, update) {
            // at this place you can call your own API every time the flow 
            // gets updated
            // carefully catch errors, timeouts ... so calling your 
            // external API does not affect the Designer behaviour
            console.log('Calling your own API.');
            console.log(JSON.parse(JSON.stringify(update)));

            // in order to update the flow in Appmixer, call the Flow API
            return this._request({
                url: `${this.get('baseUrl')}/flows/${flowId}`,
                method: 'PUT',
                data: update
            });
        }
    }
});

Custom Component Strings

Appmixer lets you manage the components' inspector fields through the manifest or the strings object.

There are two ways how to customize component's strings:

Through a localization object inside the component's manifest
Adding custom strings to components namespace inside strings object

Component's manifest localization object

You can include custom strings inside the component's manifest using a localization object. The following is an example how to do it:

{
    "name": "appmixer.twilio.sms.SendSMS",
    "author": "David Durman <david@client.io>",
    "icon": "data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMjUwMCIgaGVp...",
    "description": "Send SMS text message through Twilio.",
    "private": false,
    "auth": {
        "service": "appmixer:twilio"
    },
    "outPorts": [
        {
            "name": "sent",
            "options": [
                { "label": "Message Sid", "value": "sid" }
            ]
        }
    ],
    "inPorts": [
        {
            "name": "message",
            "schema": {
                "type": "object",
                "properties": {
                    "body": { "type": "string" },
                    "to": { "type": "string" },
                    "from": { "type": "string" }
                },
                "required": [
                    "from", "to"
                ]
            },
            "inspector": {
                "inputs": {
                    "body": {
                        "type": "text",
                        "label": "Text message",
                        "tooltip": "Text message that should be sent.",
                        "index": 1
                    },
                    "from": {
                        "type": "select",
                        "label": "From number",
                        "placeholder": "Type number",
                        "tooltip": "Select Twilio phone number.",
                        "index": 2,
                        "source": {
                            "url": "/component/appmixer/twilio/sms/ListFromNumbers?outPort=numbers",
                            "data": {
                                "transform": "./transformers#fromNumbersToSelectArray"
                            }
                        }
                    },
                    "to": {
                        "type": "text",
                        "label": "To number",
                        "tooltip": "The destination phone number. <br/><br/>Format with a '+' and country code e.g., +16175551212 (E.164 format).",
                        "index": 3
                    }
                }
            }
        }
   ],
   "localization": {
       "cs": {
           "label": "Pošli SMS",
           "description": "Pošli SMS pomocí Twilia",
           "inPorts[0].name": "Zpráva",
           "inPorts[0].inspector.inputs.body.label": "Textová zpráva",
           "inPorts[0].inspector.inputs.from.label": "Číslo volajícího",
           "inPorts[0].inspector.inputs.from.placeholder": "Hledej číslo",
           "outPorts[0].name": "Odesláno",
           "outPorts[0].options[sid].label": "Sid zprávy"
       },
       "sk": {
           "label": "Pošli SMS",
           "description": "Pošli SMS pomocou Twilia",
           "inPorts[0].name": "Správa",
           "inPorts[0].inspector.inputs.body.label": "Textová správa",
           "inPorts[0].inspector.inputs.from.label": "číslo volajúceho",
           "outPorts[0].name": "Odoslané",
           "outPorts[0].options[sid].label": "Sid správy"
       }
   }
}

You can customize the component's label and description. You can customize the component's input/output port labels, the inspector input field labels, and output variables as well.

There's a slightly different specification when localizing output variables. As you can see in the example, after outPorts[0].options the next path fragment is the option's value, instead of the index. This is because the component could have a dynamic output instead and different output variables can share the same index, so we use the value to specify them instead.

To switch the language in UI, you call the Appmixer instance set method:

// Create an SDK instance
var appmixer = new Appmixer()

// Will use the strings under 'cs' key
appmixer.set('lang', 'cs')

// Will switch the strings to the ones under 'sk' key
appmixer.set('lang', 'sk')

Note that if you want to customize the whole UI, you must use this in conjunction with the strings object. Here's an example:

var appmixer = new Appmixer();

var mySkStrings = { /* Strings definition for sk language */ };
var myCsStrings = { /* Strings definition for cs language */ };

// This function will be called when the user clicks on some
// "Switch to sk" button
function setLangToSk() {
    appmixer.set('lang', 'sk');
    appmixer.set('strings', mySkStrings);
}

// This function will be called when the user clicks on some
// "Switch to cs" button
function setLangToCs() {
    appmixer.set('lang', 'cs');
    appmixer.set('strings', myCsStrings);
}

Strings object's component namespace

The alternative way to customize the component's strings is using the Strings Object. There is a root namespace components which contains all the custom strings definitions for components:

{
	components: {
		"appmixer.twilio.sms.SendSMS": {
			"inPorts[0].inspector.inputs.body.label": "Textová zpráva",
      "inPorts[0].inspector.inputs.from.label": "Číslo volajícího",
      "inPorts[0].inspector.inputs.from.placeholder": "Hledej číslo"
		}
	}

	// Other namespaces (designer, storage, accounts...)
}

service.json and module.json localization

Example using localization object in service.json

{
    "name": "appmixer.twilio",
    "label": "Twilio",
    "category": "applications",
    "description": "Twilio is an easy tool for developers to send and receive SMS and voice calls.",
    "icon": "data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMj...",
    "localization": {
        "cz": {
            "label": "Modul Twilio",
            "description": "Twilio je snadný nástroj pro vývojáře k odesílání a přijímání SMS a hlasových hovorů."
        },
        "sk": {
            "label": "Modul Twilio",
            "description": "Twilio je ľahký nástroj pre vývojárov na odosielanie a prijímanie SMS a hlasových hovorov."
        }
    }
}

Example using Strings object

It follows the same pattern as in components, but we use the service/module path as a key for the definition:

"appmixer.twilio": {
    "label": "Modul Twilio",
    "description": "Twilio je snadný nástroj pro vývojáře k odesílání a přijímání SMS a hlasových hovorů."
}

Application groups localization

Labels of groups of application modules can be localized/changed without rewriting a single module.json file.

Use the localization strings to do so:

appmixer.set('strings', {
    ui: {
        designer: {
            stencil: {
                groups: {
                    applications: 'Connectors',
                    utilities: 'Tools'
                }
            }
        }
    }
});

Strings resolving

When rendering the component's inspector, the strings are resolved with the following priority:

Localization object in the manifest (component.json).
Strings object components namespace.
Property in the manifest (component.json).

For example, when resolving an input's label, it will first look if there is a localization object in the manifest with a path to that input's label. If not, it will search the Strings Object. If none of that is defined, it will use values from the manifest.

Custom Component Shapes

Fully customize appearance of components in diagrams.

Usage

Shape registration in the Appmixer SDK:

var appmixer = new Appmixer({
    componentShapes: {
        action: myCustomComponentShape,
        trigger: myCustomComponentShape,
        myUniqueShape: myCustomComponentShape
    },
});

Use "action" and "trigger" keys to override defaults. You can define a custom shape for any component in the system, shape reference in a component manifest looks like this:

{
    shape: "myUniqueShape"
}

Built-in shapes are action, trigger, actionVertical and triggerVertical.

Definition

Special selectors

Dynamic properties of the component, such as label and icon, are mapped to optional selectors in the markup.

Special attributes

var customComponentShape = {
    attributes: {
        size: {
            height: 72,
            width: 72
        },
        markup: [
            {
                tagName: 'rect',
                selector: 'body'
            },
            {
                tagName: 'text',
                selector: 'label'
            },
            {
                tagName: 'image',
                selector: 'icon'
            },
            {
                tagName: 'g',
                selector: 'element-halo',
                children: [
                    {
                        tagName: 'image',
                        selector: 'element-halo-copy',
                        children: [
                            {
                                tagName: 'title',
                                selector: 'element-halo-copy-tooltip'
                            }
                        ]
                    },
                    {
                        tagName: 'image',
                        selector: 'element-halo-cut',
                        children: [
                            {
                                tagName: 'title',
                                selector: 'element-halo-cut-tooltip'
                            }
                        ]
                    },
                    {
                        tagName: 'image',
                        selector: 'element-halo-remove',
                        children: [
                            {
                                tagName: 'title',
                                selector: 'element-halo-remove-tooltip'
                            }
                        ]
                    }
                ]
            }
        ],
        attrs: {
            body: {
                fill: 'white',
                stroke: 'black',
                strokeWidth: 1,
                refWidth: 1,
                refHeight: 1
            },
            icon: {
                ref: 'body',
                refX: 0.5,
                refY: 0.5,
                xAlignment: 'middle',
                yAlignment: 'middle',
                width: 24,
                height: 24,
                clipPath: 'url(#icon-clip)'
            },
            label: {
                ref: 'body',
                textAnchor: 'middle',
                refX: 0.5,
                refY: '100%',
                refY2: 12,
                xAlignment: 'middle',
                fontFamily: 'sans-serif',
                fontWeight: 'bold',
                fontSize: 14,
                fill: 'black'
            },
            'element-halo': {
                display: 'none',
                ref: 'body',
                width: 68,
                height: 44,
                refX: 0.5,
                refY: 0,
                refY2: -24,
                xAlignment: 'middle'
            },
            'element-halo-copy': {
                event: 'element-copy',
                x: 0,
                y: 0,
                width: 20,
                height: 20,
                xlinkHref: 'data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9Ii01IC0yIDI0IDI0IiB3aWR0aD0iMjQiIGhlaWdodD0iMjQiIHByZXNlcnZlQXNwZWN0UmF0aW89InhNaW5ZTWluIiBjbGFzcz0iaWNvbl9faWNvbiI+PHBhdGggZD0iTTUgMnYyaDRWMkg1em02IDBoMWEyIDIgMCAwIDEgMiAydjE0YTIgMiAwIDAgMS0yIDJIMmEyIDIgMCAwIDEtMi0yVjRhMiAyIDAgMCAxIDItMmgxYTIgMiAwIDAgMSAyLTJoNGEyIDIgMCAwIDEgMiAyem0wIDJhMiAyIDAgMCAxLTIgMkg1YTIgMiAwIDAgMS0yLTJIMnYxNGgxMFY0aC0xek00IDhoNmExIDEgMCAwIDEgMCAySDRhMSAxIDAgMSAxIDAtMnptMCA1aDZhMSAxIDAgMCAxIDAgMkg0YTEgMSAwIDAgMSAwLTJ6Ij48L3BhdGg+PC9zdmc+',
                cursor: 'pointer'
            },
            'element-halo-cut': {
                event: 'element-cut',
                x: 24,
                y: 0,
                width: 20,
                height: 20,
                cursor: 'pointer',
                xlinkHref: 'data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9Ii0yLjUgLTIuNSAyNCAyNCIgd2lkdGg9IjI0IiBoZWlnaHQ9IjI0IiBwcmVzZXJ2ZUFzcGVjdFJhdGlvPSJ4TWluWU1pbiIgY2xhc3M9Imljb25fX2ljb24iPjxwYXRoIGQ9Ik05LjEwNyAxMC41NTRMNy4zNjMgMTIuNjNhMy45OTMgMy45OTMgMCAwIDEtLjE5MiA0Ljg5IDQuMDA0IDQuMDA0IDAgMCAxLTUuNjM1LjQ5MiAzLjk5MSAzLjk5MSAwIDAgMS0uNDkzLTUuNjI4IDQuMDA1IDQuMDA1IDAgMCAxIDQuNzg4LTEuMDM4TDcuODAxIDkgMi40MTMgMi41ODdhLjk5OC45OTggMCAwIDEgLjEyMy0xLjQwNyAxIDEgMCAwIDEgMS40MDkuMTIzbDUuMTYyIDYuMTQ0IDUuMTYxLTYuMTQ0YTEgMSAwIDAgMSAxLjQxLS4xMjMuOTk4Ljk5OCAwIDAgMSAuMTIzIDEuNDA3TDEwLjQxMiA5bDEuOTcgMi4zNDVhNC4wMDUgNC4wMDUgMCAwIDEgNC43ODggMS4wMzggMy45OTEgMy45OTEgMCAwIDEtLjQ5MyA1LjYyOCA0LjAwNCA0LjAwNCAwIDAgMS01LjYzNS0uNDkyIDMuOTkzIDMuOTkzIDAgMCAxLS4xOTItNC44OWwtMS43NDMtMi4wNzV6bS02LjI4NSA1LjkyN2EyIDIgMCAwIDAgMi41NzEtMy4wNiAyLjAwMiAyLjAwMiAwIDAgMC0yLjgxOC4yNDZjLS43MS44NDUtLjYgMi4xMDUuMjQ3IDIuODE0em0xMi41NyAwYTEuOTk2IDEuOTk2IDAgMCAwIC4yNDYtMi44MTQgMi4wMDIgMi4wMDIgMCAwIDAtMi44MTctLjI0NiAxLjk5NiAxLjk5NiAwIDAgMC0uMjQ3IDIuODE0Yy43MS44NDUgMS45NzIuOTU1IDIuODE4LjI0NnoiPjwvcGF0aD48L3N2Zz4'
            },
            'element-halo-remove': {
                event: 'element-remove',
                x: 48,
                y: 0,
                width: 20,
                height: 20,
                cursor: 'pointer',
                xlinkHref: 'data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9Ii0zIC0yIDI0IDI0IiB3aWR0aD0iMjQiIGhlaWdodD0iMjQiIHByZXNlcnZlQXNwZWN0UmF0aW89InhNaW5ZTWluIiBjbGFzcz0iaWNvbl9faWNvbiI+PHBhdGggZD0iTTYgMlYxYTEgMSAwIDAgMSAxLTFoNGExIDEgMCAwIDEgMSAxdjFoNGEyIDIgMCAwIDEgMiAydjFhMiAyIDAgMCAxLTIgMmgtLjEzM2wtLjY4IDEwLjJhMyAzIDAgMCAxLTIuOTkzIDIuOEg1LjgyNmEzIDMgMCAwIDEtMi45OTMtMi43OTZMMi4xMzcgN0gyYTIgMiAwIDAgMS0yLTJWNGEyIDIgMCAwIDEgMi0yaDR6bTEwIDJIMnYxaDE0VjR6TTQuMTQxIDdsLjY4NyAxMC4wNjhhMSAxIDAgMCAwIC45OTguOTMyaDYuMzY4YTEgMSAwIDAgMCAuOTk4LS45MzRMMTMuODYyIDdoLTkuNzJ6TTcgOGExIDEgMCAwIDEgMSAxdjdhMSAxIDAgMCAxLTIgMFY5YTEgMSAwIDAgMSAxLTF6bTQgMGExIDEgMCAwIDEgMSAxdjdhMSAxIDAgMCAxLTIgMFY5YTEgMSAwIDAgMSAxLTF6Ij48L3BhdGg+PC9zdmc+'
            },
            'element-halo-copy-tooltip': {
                fontFamily: 'nunitosans-regular, Helvetica, Arial, sans-serif',
                fontSize: 13
            },
            'element-halo-cut-tooltip': {
                fontFamily: 'nunitosans-regular, Helvetica, Arial, sans-serif',
                fontSize: 13
            },
            'element-halo-remove-tooltip': {
                fontFamily: 'nunitosans-regular, Helvetica, Arial, sans-serif',
                fontSize: 13
            }
        }
    },
    ports: {
        attributes: {
            in: {
                position: {
                    name: 'left'
                },
                attrs: {
                    '.port-body': {
                        r: 5,
                        strokeWidth: 2,
                        stroke: 'black',
                        fill: 'white'
                    },
                    'connection-port-label': {
                        fill: 'black',
                        fontFamily: 'sans-serif',
                        fontSize: 12
                    }
                },
                label: {
                    position: {
                        name: 'left',
                        args: {
                            x: -8,
                            y: 14
                        }
                    },
                    markup: [
                        {
                            tagName: 'text',
                            selector: 'connection-port-label'
                        }
                    ]
                }
            },
            out: {
                position: {
                    name: 'right'
                },
                attrs: {
                    '.port-body': {
                        r: 5,
                        strokeWidth: 2,
                        stroke: 'black',
                        fill: 'white'
                    },
                    'connection-port-label': {
                        fill: 'black',
                        fontFamily: 'sans-serif',
                        fontSize: 12
                    }
                },
                label: {
                    position: {
                        name: 'right',
                        args: {
                            x: 8,
                            y: 14
                        }
                    },
                    markup: [
                        {
                            tagName: 'text',
                            selector: 'connection-port-label'
                        }
                    ]
                }
            }
        }
    },
    link: {
        attributes: {
            router: {
                name: 'metro'
            },
            connector: {
                name: 'rounded',
                args: {
                    radius: 8
                }
            },
            markup: [
                {
                    tagName: 'path',
                    selector: 'wrapper'
                },
                {
                    tagName: 'path',
                    selector: 'line'
                }
            ],
            tools: [
                {
                    z: 100,
                    distance: '50%',
                    event: 'link-remove',
                    markup: [
                        {
                            tagName: 'circle',
                            selector: 'button',
                            attributes: {
                                cx: -0.5,
                                cy: -0.5,
                                r: 10,
                                fill: config.colors.bodyStrokeActive,
                                cursor: 'pointer'
                            }
                        },
                        {
                            tagName: 'path',
                            selector: 'icon',
                            attributes: {
                                pointerEvents: 'none',
                                transform: 'translate(-6.4 -7)',
                                d: 'M8,1.333h3.333A.667.667,0,0,1,12,2V3.333A.667.667,0,0,1,11.333,4H.667A.667.667,0,0,1,0,3.333V2a.667.667,0,0,1,.667-.667H4V.667A.667.667,0,0,1,4.667,0H7.333A.667.667,0,0,1,8,.667Zm2.533,4-.409,6.133a2,2,0,0,1-2,1.867H3.884a2,2,0,0,1-2-1.864L1.47,5.333ZM4.667,6A.667.667,0,0,0,4,6.667v4.667a.667.667,0,0,0,1.333,0V6.667A.667.667,0,0,0,4.667,6ZM7.333,6a.667.667,0,0,0-.667.667v4.667a.667.667,0,0,0,1.333,0V6.667A.667.667,0,0,0,7.333,6Z',
                                fill: 'white'
                            }
                        }
                    ]
                }
            ],
            attrs: {
                line: {
                    pointerEvents: 'none',
                    connection: true,
                    stroke: 'black',
                    strokeWidth: 1.5,
                    strokeDasharray: '4 4',
                    fill: 'transparent'
                },
                wrapper: {
                    connection: true,
                    cursor: 'pointer',
                    stroke: 'transparent',
                    strokeWidth: 24,
                    fill: 'transparent'
                }
            }
        }
    },
    states: {
        '@active': {
            attributes: {
                attrs: {
                    body: {
                        stroke: 'blue',
                        strokeWidth: 3
                    },
                    label: {
                        fill: 'black'
                    },
                    'element-halo': {
                        display: 'initial'
                    }
                }
            },
            ports: {
                attributes: {
                    in: {
                        attrs: {
                            '.port-body': {
                                stroke: 'blue'
                            }
                        }
                    },
                    out: {
                        attrs: {
                            '.port-body': {
                                stroke: 'blue'
                            }
                        }
                    }
                }
            },
            link: {
                attributes: {
                    attrs: {
                        line: {
                            strokeDasharray: 0,
                            stroke: 'blue'
                        }
                    }
                }
            }
        },
        '@invalid': {
            attributes: {
                attrs: {
                    body: {
                        stroke: 'red',
                        strokeWidth: 2
                    },
                    label: {
                        fill: 'red'
                    }
                }
            },
            ports: {
                attributes: {
                    in: {
                        attrs: {
                            '.port-body': {
                                stroke: 'red'
                            }
                        }
                    },
                    out: {
                        attrs: {
                            '.port-body': {
                                stroke: 'red'
                            }
                        }
                    }
                }
            }
        }
    }
};

var customSelectionShape = {
    attributes: {
        markup: [
            {
                tagName: 'rect',
                selector: 'body'
            },
            {
                tagName: 'g',
                selector: 'halo',
                children: [
                    {
                        tagName: 'image',
                        selector: 'halo-copy'
                    },
                    {
                        tagName: 'image',
                        selector: 'halo-cut'
                    },
                    {
                        tagName: 'image',
                        selector: 'halo-remove'
                    }
                ]
            }
        ],
        attrs: {
            body: {
                pointerEvents: 'none',
                fill: 'rgba(0, 0, 0, 0.1)',
                stroke: 'black',
                strokeWidth: 1
            },
            halo: {
                ref: 'body',
                width: 68,
                height: 44,
                refX: 0.5,
                refY: 0,
                refY2: -24,
                xAlignment: 'middle'
            },
            'halo-copy': {
                event: 'element-copy',
                x: 0,
                y: 0,
                width: 20,
                height: 20,
                xlinkHref: 'data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9Ii01IC0yIDI0IDI0IiB3aWR0aD0iMjQiIGhlaWdodD0iMjQiIHByZXNlcnZlQXNwZWN0UmF0aW89InhNaW5ZTWluIiBjbGFzcz0iaWNvbl9faWNvbiI+PHBhdGggZD0iTTUgMnYyaDRWMkg1em02IDBoMWEyIDIgMCAwIDEgMiAydjE0YTIgMiAwIDAgMS0yIDJIMmEyIDIgMCAwIDEtMi0yVjRhMiAyIDAgMCAxIDItMmgxYTIgMiAwIDAgMSAyLTJoNGEyIDIgMCAwIDEgMiAyem0wIDJhMiAyIDAgMCAxLTIgMkg1YTIgMiAwIDAgMS0yLTJIMnYxNGgxMFY0aC0xek00IDhoNmExIDEgMCAwIDEgMCAySDRhMSAxIDAgMSAxIDAtMnptMCA1aDZhMSAxIDAgMCAxIDAgMkg0YTEgMSAwIDAgMSAwLTJ6Ij48L3BhdGg+PC9zdmc+',
                cursor: 'pointer'
            },
            'halo-cut': {
                event: 'element-cut',
                x: 24,
                y: 0,
                width: 20,
                height: 20,
                cursor: 'pointer',
                xlinkHref: 'data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9Ii0yLjUgLTIuNSAyNCAyNCIgd2lkdGg9IjI0IiBoZWlnaHQ9IjI0IiBwcmVzZXJ2ZUFzcGVjdFJhdGlvPSJ4TWluWU1pbiIgY2xhc3M9Imljb25fX2ljb24iPjxwYXRoIGQ9Ik05LjEwNyAxMC41NTRMNy4zNjMgMTIuNjNhMy45OTMgMy45OTMgMCAwIDEtLjE5MiA0Ljg5IDQuMDA0IDQuMDA0IDAgMCAxLTUuNjM1LjQ5MiAzLjk5MSAzLjk5MSAwIDAgMS0uNDkzLTUuNjI4IDQuMDA1IDQuMDA1IDAgMCAxIDQuNzg4LTEuMDM4TDcuODAxIDkgMi40MTMgMi41ODdhLjk5OC45OTggMCAwIDEgLjEyMy0xLjQwNyAxIDEgMCAwIDEgMS40MDkuMTIzbDUuMTYyIDYuMTQ0IDUuMTYxLTYuMTQ0YTEgMSAwIDAgMSAxLjQxLS4xMjMuOTk4Ljk5OCAwIDAgMSAuMTIzIDEuNDA3TDEwLjQxMiA5bDEuOTcgMi4zNDVhNC4wMDUgNC4wMDUgMCAwIDEgNC43ODggMS4wMzggMy45OTEgMy45OTEgMCAwIDEtLjQ5MyA1LjYyOCA0LjAwNCA0LjAwNCAwIDAgMS01LjYzNS0uNDkyIDMuOTkzIDMuOTkzIDAgMCAxLS4xOTItNC44OWwtMS43NDMtMi4wNzV6bS02LjI4NSA1LjkyN2EyIDIgMCAwIDAgMi41NzEtMy4wNiAyLjAwMiAyLjAwMiAwIDAgMC0yLjgxOC4yNDZjLS43MS44NDUtLjYgMi4xMDUuMjQ3IDIuODE0em0xMi41NyAwYTEuOTk2IDEuOTk2IDAgMCAwIC4yNDYtMi44MTQgMi4wMDIgMi4wMDIgMCAwIDAtMi44MTctLjI0NiAxLjk5NiAxLjk5NiAwIDAgMC0uMjQ3IDIuODE0Yy43MS44NDUgMS45NzIuOTU1IDIuODE4LjI0NnoiPjwvcGF0aD48L3N2Zz4'
            },
            'halo-remove': {
                event: 'element-remove',
                x: 48,
                y: 0,
                width: 20,
                height: 20,
                cursor: 'pointer',
                xlinkHref: 'data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9Ii0zIC0yIDI0IDI0IiB3aWR0aD0iMjQiIGhlaWdodD0iMjQiIHByZXNlcnZlQXNwZWN0UmF0aW89InhNaW5ZTWluIiBjbGFzcz0iaWNvbl9faWNvbiI+PHBhdGggZD0iTTYgMlYxYTEgMSAwIDAgMSAxLTFoNGExIDEgMCAwIDEgMSAxdjFoNGEyIDIgMCAwIDEgMiAydjFhMiAyIDAgMCAxLTIgMmgtLjEzM2wtLjY4IDEwLjJhMyAzIDAgMCAxLTIuOTkzIDIuOEg1LjgyNmEzIDMgMCAwIDEtMi45OTMtMi43OTZMMi4xMzcgN0gyYTIgMiAwIDAgMS0yLTJWNGEyIDIgMCAwIDEgMi0yaDR6bTEwIDJIMnYxaDE0VjR6TTQuMTQxIDdsLjY4NyAxMC4wNjhhMSAxIDAgMCAwIC45OTguOTMyaDYuMzY4YTEgMSAwIDAgMCAuOTk4LS45MzRMMTMuODYyIDdoLTkuNzJ6TTcgOGExIDEgMCAwIDEgMSAxdjdhMSAxIDAgMCAxLTIgMFY5YTEgMSAwIDAgMSAxLTF6bTQgMGExIDEgMCAwIDEgMSAxdjdhMSAxIDAgMCAxLTIgMFY5YTEgMSAwIDAgMSAxLTF6Ij48L3BhdGg+PC9zdmc+'
            }
        }
    }
};

new Appmixer({
    componentShapes: {
        action: customComponentShape,
        trigger: customComponentShape,
        selection: customSelectionShape        
    }
});

Appmixer hosted

Getting started

You can start with our or .

Creating Custom Components

In order to successfully follow the next tutorials, you need few URLs that you should have already received.

Appmixer Backend API URL. Looks like https://api.[acme].appmixer.cloud

Appmixer Backoffice URL. Looks like https://backoffice.[acme].appmixer.cloud

Appmixer Frontend URL. Looks like https://my.[acme].appmixer.cloud

In order to publish your custom components into the Appmixer, you need an account with a certain permission. You need your admin account, visit the and set it up. More information can be found .

Customers tend to write their own components with the appmixer prefix. Something like appmixer.[acme].crm.CreateCustomer. This is not recommended. The first part of the module/component ID should not be appmixer, but your own vendor ID. You can use your company name, or the name of the product you're trying to build with Appmixer. Something like [acme].crm.customers.CreateCustomer could be the ID of your custom component.

There are a couple of tutorials you can follow in order to learn how to create and publish your own components.

First, you're gonna need to understand what a component is and how does a module with components look like. .

Note that the HelloAppmixer tutorial, mentioned in the next paragraph, is written for the Appmixer running on a local machine. You can see a http://localhost:2200 URL mentioned a couple of times there. In the hosted version of Appmixer, you have your own Appmixer Backend API URL which you will use instead of the localhost:2200.

Then you can write your own component. Before doing so, it is a good time to learn something about our . You will use that tool to create packages of your components and publish them into your hosted Appmixer. is a simple HelloAppmixer tutorial on how to build your first module with a component.

Another can be found in our Knowledge base.

Using Appmixer SDK

The Appmixer JavaScript SDK allows you to embed any of the UI widgets of Appmixer into your own web products. You can also take advantage of the SDK methods to communicate with the Appmixer engine REST API.

Open the Appmixer SDK demo

Start with opening the Appmixer SDK demo in your browser:

# Download the Appmixer SDK:
$ wget http://my.[acme].appmixer.cloud/appmixer/appmixer.js
# Download the demo page:
$ wget http://my.[acme].appmixer.cloud/appmixer/demo.html
# Download the example theme object:
$ wget http://my.[acme].appmixer.cloud/appmixer/theme.js
$ open demo.html

Notice that this won't work yet since we haven't configured the basic required variables. First, we need to edit the demo HTML file to add the base URL of our Appmixer engine REST API ( and our user credentials. Open the demo.html file in your editor and find the following section:

    <script>
            var BASE_URL = '<your-base-url>';
            var USERNAME = '<your-username>';
            var PASSWORD = '<your-password>';

Replace <your-base-url> with https://api.[acme].appmixer.cloud and <your-username> and <your-password> with the user credentials. You can use the credentials that you received after your hosted environment was created. Or you can create a new user at http://my.[acme].appmixer.cloud. Now you can open the demo.html file in your browser. You should see something like this:

The demo shows a plain HTML page that embeds the Appmixer UI widgets via the Appmixer JS SDK. Try to switch to different widgets using the select control at the top:

Study the source code of the demo.html file to understand how the Appmixer SDK can be used to embed Appmixer UI into your own page. As you can see, we start by authenticating the user:

appmixer.api.authenticateUser(USERNAME, PASSWORD).then((auth) => {
    appmixer.set('accessToken', auth.token);
    start();
});

Then we initialize the Appmixer UI widgets passing a reference to a <div> container element they will render in:

<div id="your-flow-manager"></div>

var flowManager = appmixer.ui.FlowManager({ el: '#your-flow-manager' });

Once our widgets are initialized, we can just call open() and close() methods to render the widgets inside their container or close them:

flowManager.open();

And react on events the UI widgets provide. For example, if the user clicks a flow inside the flow manager, the flow manager widget triggers the "flow:open" event which we can react on to open the designer for that flow:

flowManager.on('flow:open', (flowId) => {
    designer.set('flowId', flowId);
    flowManager.close();
    designer.open();
});

To revoke the authenticated user access, unset the access token:

appmixer.set('accessToken', null);

Using Appmixer API

The Appmixer API allows you to access all the features that the UI works with via a REST API. You should have already received some user credentials when your hosted environment was created. Or you could have already tried the sign-up page (https://my.[acme].appmixer.cloud) and created other users. In order to access the data of the user via the API, you need to have their access token. Use the following API call to get the token (don't forget to replace the "abc@example.com" and "abc321" with your own user's username and password):

curl -XPOST "https://api.[acme].appmixer.cloud/user/auth" -d '{"username": "abc@example.com", "password": "abc321"}' -H 'Content-Type: application/json'

You should see a response that looks like this:

{"user":{"id":"5c88c7cc04a917256c726c3d","username":"abc@example.com","isActive":false,"email":"abc@example.com","plan":"free"},"token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjVjODhjN2NjMDRhOTE3MjU2YzcyNmMzZCIsInNjb3BlIjpbInVzZXIiXSwiaWF0IjoxNTUyNDkzMTA0LCJleHAiOjE1NTUwODUxMDR9.sdU3Jt2MjmVuBNak0FwR0ETcjleRyiA6bqjMPA6f-ak"}

Copy the token and use it to authorize the user in your next API calls. For example, to get the number of flows the user created, use:

curl "https://api.[acme].appmixer.cloud/flows/count" -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjVjODhjN2NjMDRhOTE3MjU2YzcyNmMzZCIsInNjb3BlIjpbInVzZXIiXSwiaWF0IjoxNTUyNDkyNjA5LCJleHAiOjE1NTUwODQ2MDl9.9jVcqY0qo9Q_1GeK9Fg14v7OrdpWvzmqnv4jDMZfqnI"

You should see a response that tells you how many flows the user has in their account:

{"count":5}

Please see the API section to learn more about all the endpoints that you use.

Using Oauth applications

Appmixer comes with a set of prepared components (applications). Some of them use OAuth 1 (Twitter) authentication mechanism and some of them (Slack, Google) use OAuth 2 authentication mechanism.

If you try to use the Slack component right after fresh Appmixer installation you will get an error Missing client ID.

In the case of the OAuth 1 application, the error will be Missing consumer key. As described here the OAuth applications need these secrets. The reason we do not provide these secrets with Appmixer is simple. Part of the OAuth application registered in the third party service is the redirect URL which points to your server URL where the Appmixer backend API is running.

Therefore you need to create these OAuth applications on your own. At the end of the process, you will always get a client ID and client Secret (OAuth 2).

Before installing an OAuth application, please visit the APP registration section. It contains specific settings for each application.

The OAuth variables can be set through the Backoffice.

Appmixer Self-Managed

Installation

Appmixer Self-Managed package is shipped as a zip archive and allows you to install the Appmixer platform on your own infrastructure or in a cloud-computing platform.

Prerequisites

Installation

First, unzip the appmixer.zip archive and change to the appmixer/ directory.

Install and Start Appmixer

docker-compose --project-name appmixer up

Stop Appmixer

docker-compose --project-name appmixer stop

Now you can open the Appmixer Frontend in your browser at http://localhost:8080. Before you start creating flows with applications that require user authentication (OAuth), read this section.

Stop and Clean Up

Stop Appmixer and remove all containers and images:

docker-compose --project-name appmixer down --volumes --remove-orphans --rmi all

Using Webhook Components

Some components require that the Appmixer engine URL is accessible on the Internet. This is especially true for any component that uses webhooks. In order to get these components working on your local machine, you need to set the APPMIXER_API_URL environment variable on the Appmixer engine to point to a public URL. When using the Appmixer trial on your local machine, we recommend using the ngrok utility:

$ ngrok http 2200
ngrok by @inconshreveable                                                                                                                                                                                                                     (Ctrl+C to quit)

Session Status                online
Account                        (Plan: Basic)
Version                       2.3.35
Region                        United States (us)
Web Interface                 http://127.0.0.1:4040
Forwarding                    http://568284c4.ngrok.io -> http://localhost:2200
Forwarding                    https://568284c4.ngrok.io -> http://localhost:2200

Connections                   ttl     opn     rt1     rt5     p50     p90
                              0       0       0.00    0.00    0.00    0.00

Copy the URL it gives you, in our case https://568284c4.ngrok.ioand replace the following line in the docker-compose.yml file in the root directory of the Appmixer package:

  engine:
    ...
    environment:
      - APPMIXER_API_URL=${APPMIXER_API_URL:-http://localhost:2200}
    ...

with the URL from ngrok:

engine:
    ...
    environment:
      - APPMIXER_API_URL=https://568284c4.ngrok.io
    ...

Now restart Appmixer:

docker-compose --project-name appmixer down # or kill existing with Ctrl-c
docker-compose --project-name appmixer up

Or you can keep the docker-compose.yml file as it is and run it with:

APPMIXER_API_URL=https://568284c4.ngrok.io docker-compose --project-name appmixer up

But this command will set the GRIDD_URL to https://568284c4.ngrok.io as well. See more information about GRIDD_URL here.

The information about automatic setting the GRIDD_URL is valid only when our docker-componse.yml file is used. When you run Appmixer without it, the GRIDD_URL has to be set. This variable affects the OAuth redirect URL.

Creating an Admin User

Users in Appmixer can have a special "admin" scope defined which gives them access to the entire system. Such users have access to all flows and all users and also access to the Backoffice UI application that gives these admin users an overview of users and flows in the system. Due to security reasons, the only way to give a user the "admin" scope is to modify a user record right inside the MongoDB database:

docker-compose -p appmixer exec mongodb mongo appmixer --quiet --eval 'db.users.update({"email": "admin@example.com"}, { $set: {"scope": ["user", "admin"]}})'

Replace the "admin@example.com" email address with an email address of an existing user which you want to grant admin rights. If you don't have a user created yet, please continue to the next "Getting Started" section to see how you can create one using the Appmixer Front-end UI interface. The command above should have the following output:

WriteResult({ "nMatched" : 1, "nUpserted" : 0, "nModified" : 1 })

As you can see, we have set the "scope" property on our user record to ['user', 'admin']. From now on, our user will have admin rights. Now you can sign-in to the Backoffice UI at http://localhost:8081 using the email address and password of your admin user. If you visit the Users page, you should see something like this:

Enabling Users to Publish Custom Components

Once you have your admin user created. You can use the Backoffice UI to enable users to upload custom components. This can be done by setting the "Vendor" property on your users. Only users with the "Vendor" property set can upload components and only those components that have a matching [vendor] in their names. For example, component "appmixer.utils.forms.CreateForm" can only be uploaded by a user who has "Vendor" set to "appmixer".

Note that the Appmixer Trial package automatically sets the "appmixer" vendor on ALL newly created users so any user of the Trial package can publish custom components with no extra action required.

It is a good practice to set the "appmixer" vendor so that you can upload all of the connectors we provide without modifying all the component/service/module names:

From now on, my "david@client.io" user will be able to publish new custom components using the appmixer CLI tool.

Getting Started

If you successfully installed the Appmixer self-managed package, you should be able to open the Appmixer front-end application at http://localhost:8080. You should see the sign-in page:

Click on the "Sign up" button to create a new account:

Once you have created an account, you should see a page that lists all your flows (3 sample flows are pre-populated in the Trial package):

Click on the "Create Flow" button, drag&drop components from the left palette to the canvas and connect them together by dragging lines from output ports of components to input ports of other components:

Our first flow contains the OnStart component that fires immediately when you click on the "Start Flow" button, GetCurrentWeather component that requests current weather information from the http://openweathermap.org API and CreateTweet component that creates a new tweet. The right panel tells you what is the missing required configuration for the flow to be able to start. In our case, we need to authenticate to Twitter. Click on the Twitter component and fill in all the details. As you can see in the Inspector, we're entering the text of the tweet. You can use the "variables picker" to insert placeholders containing data from components back in the chain of connected components. These placeholders will be eventually replaced by real data once it is available (when the flow runs).

Then fill in all the details for the GetCurrentWeather component (in our case, we enter the city name):

Now we're ready to start our flow by clicking on the "Start Flow" button. Once you do that, you'll see the Designer shows you the flow is now in the running state. In this state, the flow can only be viewed but not edited. If you want to change the configuration of your flow, you have to stop it first and start again.

Congrats, you run your first flow! Now when you visit your Twitter account, you should see a new tweet:

Custom Component: HelloAppmixer

At this point, you have your Appmixer system up and running and you know how to create and start a flow. Now it's time to guide you through the process of implementing your own, custom component. In our tutorial, we implement a component that has one input and one output port, consumes messages on its input port, sends an HTTP request to an external API for each incoming message and outputs the response to the output port for other connected components to ingest.

Directory structure and files

Our component will live in a namespace "appmixer.myservice.mymodule.HelloAppmixer". All components in Appmixer are organized in the hierarchy [vendor].[service].[module].[component].

We prepared the HelloAppmixer component from this tutorial for you. You can download it from here:

You can just download the component and publish it with:

# Install and initialize the Appmixer CLI tool if you haven't done so already:
$ npm install -g appmixer
$ appmixer url http://localhost:2200
# Use e.g. the same user as you signed-up with in the Getting Started guide.
$ appmixer login your@user.com
$ appmixer publish appmixer.myservice.zip

If you prefer to go step by step instead (which we recommend), create the following files and the required directories:

myservice/mymodule/HelloAppmixer/HelloAppmixer.js, component source code file
myservice/mymodule/HelloAppmixer/component.json, component manifest file
myservice/service.json, service manifest file

The resulting directory structure should look like this:

$ tree myservice/
myservice/
├── mymodule
│   └── HelloAppmixer
│       ├── component.json
│       └── HelloAppmixer.js
└── service.json

2 directories, 3 files

Component Definition

Now let's fill up the files with the minimum content necessary for the engine to consider this as a valid component.

myservice/mymodule/HelloAppmixer/HelloAppmixer.js

This file exports a plain NodeJS module. Normally, this module exports virtual methods that the Appmixer engine understands (the most important one is the receive()). For now, we just leave the module empty. It's enough to create bare minimum for the engine to be able to work with our component.

module.exports = {};

myservice/mymodule/HelloAppmixer/component.json

The component manifest file defines properties of our component (such as name, icon, input/output ports, ....). For now, we just fill in the only required field, the name and the optional but useful icon. It's important to note that the name must be a fully qualified namespace or our component:

{
    "name": "appmixer.myservice.mymodule.HelloAppmixer",
    "icon": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAgAAAAICAIAAABLbSncAAAACXBIWXMAAAsTAAALEwEAmpwYAAAAB3RJTUUH4gEeCRYRYwe3nwAAABl0RVh0Q29tbWVudABDcmVhdGVkIHdpdGggR0lNUFeBDhcAAAAXSURBVAjXY2BgYPj//z8WErsoBAw+HQBdc1+hmBJKIwAAAABJRU5ErkJggg=="
}

myservice/service.json

The service manifest defines properties of our app as it appears in the left palette in the Designer UI.

{
    "name": "appmixer.myservice",
    "label": "My Service",
    "category": "applications",
    "description": "My Custom App",
    "icon": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAgAAAAICAIAAABLbSncAAAACXBIWXMAAAsTAAALEwEAmpwYAAAAB3RJTUUH4gEeCRYRYwe3nwAAABl0RVh0Q29tbWVudABDcmVhdGVkIHdpdGggR0lNUFeBDhcAAAAXSURBVAjXY2BgYPj//z8WErsoBAw+HQBdc1+hmBJKIwAAAABJRU5ErkJggg=="
}

Now you can pack and publish your component using the Appmixer CLI tool. When you then refresh the Designer page in your browser, you should see a new app in the left pane:

# Initialize your Appmixer CLI client if you haven't done that already:
$ npm install -g appmixer
$ appmixer url http://localhost:2200
# Use e.g. the same user as you signed-up with in the Getting Started guide.
$ appmixer login your@user.com

# Now we can pack and publish our component:
$ appmixer pack myservice
$ appmixer publish appmixer.myservice.zip

Extending our Component Definition

Now let's make our component actually do something. First, we start with extending the component manifest file (component.json) by adding an input port so that we can connect our component to other components:

{
    "name": "appmixer.myservice.mymodule.HelloAppmixer",
    "icon": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAgAAAAICAIAAABLbSncAAAACXBIWXMAAAsTAAALEwEAmpwYAAAAB3RJTUUH4gEeCRYRYwe3nwAAABl0RVh0Q29tbWVudABDcmVhdGVkIHdpdGggR0lNUFeBDhcAAAAXSURBVAjXY2BgYPj//z8WErsoBAw+HQBdc1+hmBJKIwAAAABJRU5ErkJggg==",
    "inPorts": [
        {
            "name": "in"
        }
    ]
}

This is enough to define an input port with no restrictions. However, we would like to add two properties (text and count) that we can count on in our component behaviour and that we can assume are always defined (i.e. marked as required in the Designer UI). Moreover, we will also define the Inspector UI for both our properties so that the user can fill them in in the Designer UI.

{
    "name": "appmixer.myservice.mymodule.HelloAppmixer",
    "icon": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAgAAAAICAIAAABLbSncAAAACXBIWXMAAAsTAAALEwEAmpwYAAAAB3RJTUUH4gEeCRYRYwe3nwAAABl0RVh0Q29tbWVudABDcmVhdGVkIHdpdGggR0lNUFeBDhcAAAAXSURBVAjXY2BgYPj//z8WErsoBAw+HQBdc1+hmBJKIwAAAABJRU5ErkJggg==",
    "inPorts": [
        {
            "name": "in",
            "schema": {
                "type": "object",
                "properties": {
                    "text": { "type": "string" },
                    "count": { "type": "number" }
                },
                "required": ["text"]
            },
            "inspector": {
                "inputs": {
                    "text": {
                        "type": "text",
                        "group": "transformation",
                        "label": "Text",
                        "index": 1
                    },
                    "count": {
                        "type": "number",
                        "group": "transformation",
                        "label": "Count",
                        "index": 2
                    }
                },
                "groups": {
                    "transformation": {
                        "label": "Transformation"
                    }
                }
            }
        }
    ]
}

When you now republish your component, refresh the Designer page and connect our component to another component, you should see both our properties in the Inspector:

$ appmixer pack myservice
$ appmixer publish myservice.zip

Note that we're using the Controls/OnStart component in our flow below. This utility component is useful especially during development of your custom components as the only thing it does is that it triggers/fires as soon as we start our flow.

Note that at this point, our component will still not work. If you try to run this flow, you will notice errors coming from the engine in the Insights/Logs page (click on the triple dot and then go to Insights):

This is because we have defined an input port on our component but did not yet implement the receive() method.

Sending HTTP Requests

In this section, we will show how to extend our component to be able to receive messages, call an external API and send the result to the output port so that other connected components can work with the data. Let's now again extend the component manifest file (component.json) by adding an output port:

{
    "name": "appmixer.myservice.mymodule.HelloAppmixer",
    "icon": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAgAAAAICAIAAABLbSncAAAACXBIWXMAAAsTAAALEwEAmpwYAAAAB3RJTUUH4gEeCRYRYwe3nwAAABl0RVh0Q29tbWVudABDcmVhdGVkIHdpdGggR0lNUFeBDhcAAAAXSURBVAjXY2BgYPj//z8WErsoBAw+HQBdc1+hmBJKIwAAAABJRU5ErkJggg==",
    "inPorts": [
        {
            "name": "in",
            "schema": {
                "type": "object",
                "properties": {
                    "text": { "type": "string" },
                    "count": { "type": "number" }
                },
                "required": ["text"]
            },
            "inspector": {
                "inputs": {
                    "text": {
                        "type": "text",
                        "group": "transformation",
                        "label": "Text",
                        "index": 1
                    },
                    "count": {
                        "type": "number",
                        "group": "transformation",
                        "label": "Count",
                        "index": 2
                    }
                },
                "groups": {
                    "transformation": {
                        "label": "Transformation"
                    }
                }
            }
        }
    ],
    "outPorts": [
        {
            "name": "out",
            "options": [
                { "label": "Hello Data", "value": "mydata" }
            ]
        }
    ]
}

Our component behaviour will also change. We will call an external HTTP endpoint and pass the result to our output port. For a convenience, we will use a NodeJS library Axios to send HTTP requests. Before we can start using the library, we have to install it first. This can simply be done by creating a package.json file with the Node package manager and installing our library:

$ cd myservice/mymodule/HelloAppmixer/
$ npm init -y
$ npm install axios --save

Now we can use the library in our component module (HelloAppmixer.js):

const axios = require('axios');
module.exports = {
    receive(context) {
        let count = context.messages.in.content.count || 1;
        let text = context.messages.in.content.text;
        return axios.get('https://postman-echo.com/get?text=' + text + '&count=' + count)
            .then(response => {
                return context.sendJson({
                    mydata: 'Received from Postman echo: ' + JSON.stringify(response.data.args)
                }, 'out');
            });
    }
};

Notice the context.messages object that is a dictionary with keys pointing to input ports and values containing the content property that gives us a dictionary with all our properties that we defined on the input port.

Now we can republish our component again and create a flow like this:

When you run this flow, you should see a new tweet in your Twitter account that looks something like this:

You can also check the Insights page for this flow to see the logs:

Conclusion

In this tutorial, we demonstrated how you can create a custom component that processes incoming messages, calls an external HTTP API and sends outgoing messages for other connected components to consume. We used simple example flows with the OnStart component as a trigger. However, instead of our OnStart trigger component, we could have used other triggers, such as schedulers, polling components (e.g. the included PipeDrive.NewPerson trigger that checks for new contacts in the Pipedrive CRM), webhooks and more. We suggest to browse the online documentation to learn more about all the features of Appmixer and how you can apply them in your custom components.

Using Appmixer SDK

Open the Appmixer SDK demo

Start with opening the Appmixer SDK demo in your browser:

$ cd appmixer/frontend/appmixer/
$ open demo.html

Or you can download the necessary files from the Appmixer front-end:

# Download the Appmixer SDK:
$ wget http://localhost:8080/appmixer/appmixer.js
# Download the demo page:
$ wget http://localhost:8080/appmixer/demo.html
# Download the example theme object:
$ wget http://localhost:8080/appmixer/theme.js
$ open demo.html

Notice that this won't work yet since we haven't configured basic required variables. First we need to edit the demo HTML file to add base URL of our Appmixer engine REST API and our user credentials. Open the frontend/appmixer/demo.html file in your editor and find the following section:

    <script>
        var BASE_URL = '<your-base-url>';
        var USERNAME = '<your-username>';
        var PASSWORD = '<your-password>';

Replace <your-base-url> with http://localhost:2200 and <your-username> and <your-password> with the user credentials that you used in the Getting Started guide to sign-up your first user. Now you can open the demo.html file in your browser. You should see something like this:

The demo shows a plain HTML page that embeds the Appmixer UI widgets via the Appmixer JS SDK. Try to switch to different widgets using the select control at the top:

Study the source code of the demo.html file to understand how the Appmixer SDK can be used to embed Appmixer UI into your own page. As you can see, we start by authenticating the user:

appmixer.api.authenticateUser(USERNAME, PASSWORD).then((auth) => {
    appmixer.set('accessToken', auth.token);
    start();
});

Then we initialize the Appmixer UI widgets passing a reference to a <div> container element they will render in:

<div id="your-flow-manager"></div>

var flowManager = appmixer.ui.FlowManager({ el: '#your-flow-manager' });

Once our widgets are initialized, we can just call open() and close() methods to render the widgets inside their container or close them:

flowManager.open();

And react on events the UI widgets provide. For example, if the user clicks a flow inside the flow manager, the flow manager widget triggers the "flow:open" event which we can react on to open the designer for that flow:

flowManager.on('flow:open', (flowId) => {
    designer.set('flowId', flowId);
    flowManager.close();                        
    designer.open();
});

To revoke the authenticated user access, unset the access token:

appmixer.set('accessToken', null);

To learn more about the Appmixer JavaScript SDK, please visit the Appmixer SDK section.

Webpack usage

We recommend to include Appmixer SDK as a script (the same way it is used in demo.html) whenever possible. This is because Appmixer SDK is too big to be processed as a module in a bundler like Webpack, which can lead to increased bundle processing times for both development and production environments.

Nevertheless, if your entry html file is being generated by Webpack using html-webpack-plugin, you would not be able to include manually the Appmixer SDK on a script tag. In this case you can use add-asset-html-webpack-plugin plugin to include it in your generated html file. Usage example:

var HtmlWebpackPlugin = require('html-webpack-plugin');
var AddAssetHtmlPlugin = require('add-asset-html-webpack-plugin');

module.exports = {
    // ...
    plugins: [
        new HtmlWebpackPlugin({
            template: 'index.html',
        }),

        new AddAssetHtmlPlugin({
            filepath: require.resolve('path/to/appmixer/appmixer.js'),
        }),
    ],
};

Using Appmixer API

The Appmixer API allows you to access all the features that the UI works with via a REST API. If you followed the "Getting Started" section, you should have a user signed-up in Appmixer. In order to access the data of the user via the API, you need to have their access token. Use the following API call to get the token (don't forget to replace the "abc@example.com" and "abc321" with your own user's username and password):

curl -XPOST "http://localhost:2200/user/auth" -d '{"username": "abc@example.com", "password": "abc321"}' -H 'Content-Type: application/json'

You should see a response that looks like this:

{"user":{"id":"5c88c7cc04a917256c726c3d","username":"abc@example.com","isActive":false,"email":"abc@example.com","plan":"free"},"token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjVjODhjN2NjMDRhOTE3MjU2YzcyNmMzZCIsInNjb3BlIjpbInVzZXIiXSwiaWF0IjoxNTUyNDkzMTA0LCJleHAiOjE1NTUwODUxMDR9.sdU3Jt2MjmVuBNak0FwR0ETcjleRyiA6bqjMPA6f-ak"}

Copy the token and use it to authorize the user in your next API calls. For example, to get the number of flows the user created, use:

curl "http://localhost:2200/flows/count" -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjVjODhjN2NjMDRhOTE3MjU2YzcyNmMzZCIsInNjb3BlIjpbInVzZXIiXSwiaWF0IjoxNTUyNDkyNjA5LCJleHAiOjE1NTUwODQ2MDl9.9jVcqY0qo9Q_1GeK9Fg14v7OrdpWvzmqnv4jDMZfqnI"

You should see a response that tells you how many flows the user has in their account:

{"count":5}

Please see the section to learn more about all the endpoints that you use.

Using OAuth applications

How to install pre-packed OAuth applications.

Appmixer comes with a set of prepared components (applications). Some of them use OAuth 1 (Twitter) authentication mechanism and some of them (Slack, Google) use OAuth 2 authentication mechanism.

If you try to use the Slack component right after fresh Appmixer installation you will get an error Missing client ID.

In the case of the OAuth 1 application, the error will be Missing consumer key. As described the OAuth applications need these secrets. The reason we do not provide these secrets with Appmixer is simple. Part of the OAuth application registered in the third party service is the redirect URL which points to your server URL where the Appmixer backend API is running.

Therefore you need to create these OAuth applications on your own. At the end of the process, you will always get a client ID and client Secret (OAuth 2).

Before installing an OAuth application, please visit the APP registration section. It contains specific settings for each application.

GRIDD_URL

There is another ENV variable that is used for OAuth redirects. It is called GRIDD_URL.

engine:
    ...
    environment:
      - APPMIXER_API_URL=${APPMIXER_API_URL:-http://localhost:2200}
      - GRIDD_URL=${APPMIXER_API_URL:-http://localhost:2200}
    ...

By default, the GRIDD_URL will be set to http://localhost:2200. This is fine for local development. For most of the services, you can register http://localhost:2200 as a callback URL. In production, this has to point to your Appmixer's public API URL.

If you run the following command:

APPMIXER_API_URL=https://247bb870a6f4.ngrok.io docker-compose --project-name appmixer up

Another way would be replacing the variables directly in docker-compose.yml file.

engine:
    ...
    environment:
      - APPMIXER_API_URL=https://247bb870a6f4.ngrok.io
      - GRIDD_URL=https://247bb870a6f4.ngrok.io
    ...

Or you can set just the GRIDD_URL like this:

engine:
    ...
    environment:
      - GRIDD_URL=https://247bb870a6f4.ngrok.io
    ...

If APPMIXER_API_URL is not set, Appmixer will use the value from GRIDD_URL.

Appmixer engine will print out values of these variables when starting so you can check they are set correctly:

Installation GCP

Installation of Appmixer Self-Managed Package on Google Cloud Platform

Follow instructions in this document:

System Webhooks

Appmixer Engine Events.

Component Errors

Components might throw exceptions. Such exceptions/errors are logged and users can see them in the . However, you might want to implement your custom logic or notification system for when this occurs. You may want to notify your users or handle/log the errors in a totally custom way.

If you want to listen for component errors you can set the WEBHOOK_FLOW_COMPONENT_ERROR environment variable to a URL that the Appmixer engine will send an HTTP POST request to whenever an error occurs. It can you any external (but accessible) URL or you can even create a flow in Appmixer and point this URL to a Webhook component to handle these errors using Appmixer itself (e.g. by sending an email, Slack notification, ...).

Set the WEBHOOK_FLOW_COMPONENT_ERROR variable in the docker-compose.yml file:

  engine:
    build:
      context: .
      dockerfile: Dockerfile
    depends_on:
      - mongodb
      - rabbitmq
      - elasticsearch
      - redis
    environment:
      # this variable has to point to your Webhook
      - WEBHOOK_FLOW_COMPONENT_ERROR=https://your.example.com/error-handling-ur

Example of an error POSTed to your URL (a validation error in this case):

{
    "err": {
        "message": "Validation error on ports: in",
        "error": {
            "in": [
                [
                    {
                        "keyword": "format",
                        "dataPath": ".to",
                        "schemaPath": "#/properties/to/format",
                        "params": {
                            "format": "email"
                        },
                        "message": "should match format \"email\""
                    }
                ]
            ]
        },
        "code": "GRID_ERR_VAL_PORTS",
        "name": "ValidationFlowError",
        "stack": "ValidationFlowError: Validation error on ports: in\n    at MessagesProcessor.process (/Users/martinkrcmar/Programming/client/appmixer/appmixer-core/engine/src/context/MessagesProcessor.js:67:19)\n    at Context.prepare (/Users/martinkrcmar/Programming/client/appmixer/appmixer-core/engine/src/context/Context.js:68:31)\n    at ContextHandler.createContext (/Users/martinkrcmar/Programming/client/appmixer/appmixer-core/engine/src/context/ContextHandler.js:60:17)\n    at async InputQueue.consume (/Users/martinkrcmar/Programming/client/appmixer/appmixer-core/engine/src/InputQueue.js:151:23)\n    at async InputQueue.onMessage (/Users/martinkrcmar/Programming/client/appmixer/appmixer-core/engine/src/AMQPClient.js:378:20)"
    },
    "type": "component",
    "flowId": "32f605b2-8fbe-4f68-9db9-ce182b35c159",
    "flowName": "New flow",
    "userId": "5f804b96ea48ec47a8c444a7",
    "componentId": "0bb33e42-fbc4-464e-98f1-459f1ff626ac",
    "componentType": "appmixer.utils.email.SendEmail",
    "inputMessages": {
        "in": [
            {
                "properties": {
                    "correlationId": "339bc448-a806-4e61-8d38-4211fcedaf12",
                    "gridInstanceId": null,
                    "contentType": "application/json",
                    "contentEncoding": "utf8",
                    "sender": {
                        "componentId": "e8c581b4-9985-4f2c-bf30-895bf1d5541b",
                        "type": "appmixer.utils.controls.OnStart",
                        "outputPort": "out"
                    },
                    "destination": {
                        "componentId": "0bb33e42-fbc4-464e-98f1-459f1ff626ac",
                        "inputPort": "in"
                    },
                    "correlationInPort": null,
                    "componentHeaders": {},
                    "flowId": "32f605b2-8fbe-4f68-9db9-ce182b35c159",
                    "messageId": "47293e2c-4e33-4558-8805-386de392ef04",
                    "flowRunId": 1607683798995
                },
                "content": {
                    "to": "2020-12-11T10:49:59.050Z"
                },
                "scope": {
                    "e8c581b4-9985-4f2c-bf30-895bf1d5541b": {
                        "out": {
                            "started": "2020-12-11T10:49:59.050Z"
                        }
                    }
                },
                "originalContent": {
                    "started": "2020-12-11T10:49:59.050Z"
                }
            }
        ]
    },
    "accessTokenId": null
}

This error was triggered in a sample flow that looks like this:

The email address in the "To" configuration field of the SendEmail component points to a variable from the OnStart component. Its value is dynamic, it is only known during runtime. Therefore the user is allowed to start such a flow, but it will fail at runtime. Start time variable contains a date string, but the SendEmail address requires a valid email address in the To input field. The error will be logged and seen in the log viewer.

Consider the flow is configured correctly this time and the email address is valid. But there is a network error and Appmixer cannot send the email.

This error will be logged and the user will be able to see it in the log viewer or in the Insights. And the JSON representing this error will look like this:

{
    "err": {
        "stack": "Error: getaddrinfo ENOTFOUND mandrillapp.com\n    at GetAddrInfoReqWrap.onlookup [as oncomplete] (dns.js:66:26)",
        "message": "getaddrinfo ENOTFOUND mandrillapp.com",
        "errno": "ENOTFOUND",
        "code": "ENOTFOUND",
        "syscall": "getaddrinfo",
        "hostname": "mandrillapp.com",
        "name": "Error"
    },
    "type": "component",
    "flowId": "0ab287ef-7bd6-4cc3-b53b-c916c857cbe7",
    "flowName": "Invalid email test",
    "userId": "5fd744d5e9ed7d0011ca35f9",
    "componentId": "cb3f4ff5-7b6e-4d24-b7a8-2115c8254baa",
    "componentType": "appmixer.utils.email.SendEmail",
    "inputMessages": {
        "in": [
            {
                "properties": {
                    "correlationId": "254ad628-f9c1-4483-81ed-33a22ac3ddc6",
                    "gridInstanceId": null,
                    "contentType": "application/json",
                    "contentEncoding": "utf8",
                    "sender": {
                        "componentId": "bcbeda1d-9036-45af-a25d-a57cf06e3f90",
                        "type": "appmixer.utils.controls.OnStart",
                        "outputPort": "out"
                    },
                    "destination": {
                        "componentId": "cb3f4ff5-7b6e-4d24-b7a8-2115c8254baa",
                        "inputPort": "in"
                    },
                    "correlationInPort": null,
                    "componentHeaders": {},
                    "flowId": "0ab287ef-7bd6-4cc3-b53b-c916c857cbe7",
                    "messageId": "33b9fcbf-b326-4eb4-bba6-cf34979f4ba2",
                    "flowRunId": 1607944841843,
                    "quotaId": "qs-4882d03d-65e1-44dc-983e-d2a33071779d"
                },
                "content": {
                    "to": [
                        {
                            "email": "martin@client.io",
                            "type": "to"
                        }
                    ],
                    "from_email": "no-reply@appmixer.com"
                },
                "scope": {
                    "bcbeda1d-9036-45af-a25d-a57cf06e3f90": {
                        "out": {
                            "started": "2020-12-14T11:20:41.858Z"
                        }
                    }
                },
                "originalContent": {
                    "started": "2020-12-14T11:20:41.858Z"
                }
            }
        ]
    },
    "accessTokenId": null
}

Quota Limit Errors

Single quota error does not necessarily mean something is wrong. Let's say a flow is writing rows into a Google Spreadsheet. And the flow is about to write 200 rows. There is a Google quota, a maximum of 60 requests at the same time. After writing 60 rows, the component will reach the quota limit and generate one of these notifications. But after some time, the quota will be available again and the component will write the remaining 140 rows.

{
    "err": {
        "message": "Ran out of quota for appmixer:utils:weather",
        "error":429,
        "data":429,
        "name":"QuotaError",
        "stack":"QuotaError: Ran out of quota for appmixer:utils:weather\\n    at Request._callback (/Driver.js:67:31)\"
    },
    "type": "quota",
    "flowId": "b7db896e-0e5c-4ee1-9cb3-1099c9f43b62",
    "flowName": "Daily Rainy Day Alert",
    "userId": "60ef4fd533d6143ba09c400f",
    "componentId": "13ad74e3-3354-463c-bf30-ea6e0c157ad8",
    "componentType": "appmixer.utils.weather.GetCurrentWeather",
    "inputMessages": {
        "location": [
            {
                "properties": {
                    "correlationId": '4dc33f4c-dbd0-4e97-ab05-381d785851f3',
                    "gridInstanceId": null,
        ...
            }
        ]
    }
}

Forgot Password

// WEBHOOK_USER_FORGOT_PASSWORD = 'http://hosted-url.com/events/forgot-password';

{
  'code': 'unique code generated for identifying forgot password request',
  'email': 'email address of user requesting for forgot password',
  'userId': 'USER id of user',
  'created': 'Date when a user requested for forgot password',
  'link': 'Link to access forgot password page on frontend'
}

If forgot password webhook is configured as explained above, the Appmixer engine will not send the email to the user and trigger the webhook instead.

Configuration

Appmixer Engine

APP_NAME

The authentication popup windows do contain the Appmixer title by default. If you want to change that, set the APP_NAME env variable in the Appmixer engine.

Example from the docker-compose.yml

  engine:
    ...
    environment:
      - APP_NAME=ACME
    ...

LOG_LEVEL

By default set to info. Can be changed to error, warn or debug.

LOG_COMPONENT_DATA_MESSAGE

When set to false, the component's input/output messages won't be logged into Elasticsearch.

Important! Appmixer Insights and Designer log messages won't contain any items if logging data messages are turned off.

APPMIXER_HTTPS_PROXY and APPMIXER_HTTP_PROXY

Setup proxy using these ENV variables. All HTTP(S) requests from Appmixer will be redirected to the proxy URL.

Appmixer Architecture

High-Level Architecture

Appmixer System Components/Applications

Appmixer Engine

The main system that manages flows, accounts, users, orchestrates components within running flows and provides a HTTP REST API interface to access all the entities within Appmixer. The Appmixer engine is implemented in NodeJS and can run on a single node or in cluster. The engine is horizontally scalable providing high availability and fault tolerance capabilities.

Appmixer UI SDK

JavaScript HTML 5 SDK that allows to seamlessly embed any of the Appmixer UI widgets (including the drag&drop workflow designer) to any 3rd party web page. The SDK communicates with the engine via REST API. Appmixer JavaScript SDK offers heavy customization capabilities, including changing of the look&feel (via themes), localization of all the text in the UI and even implementing custom component configuration Inspector fields.

Appmixer Backoffice

A standalone admin panel providing overview of all the flows and users in Appmixer together with system and modules configuration, ACL lists, system webhooks and more.

Appmixer CLI

Command line tool for development, testing and management of custom components. It can also be used to manage, export and import flows.

Supporting Technologies

RabbitMQ

Appmixer Engine uses RabbitMQ as a message broker for all data messages passing through the running flows. Also, RabbitMQ serves as an intermediary for logs before entering ElasticSearch.

MongoDB

Storage for all static data such as:

Flows
Users
System Configuration
Accounts
Component States
Dead-letter collection
Component Behaviour (code)
Modifiers (code)
Files (GridFS)
Data Stores
Telemetry

Redis

Key-value store that holds the state of the cluster, provides caching and synchronization (distributed locks).

ElasticSearch

Search & analytics engine that stores all the activity of all the running flows, system logs & errors. Logs can be retrieved by using the Appmixer REST API (Insights). Alternatively, standard tools such as Kibana can be used for in-depth analysis, technical support and maintenance.

Flow Design Phase Architecture

Clients (Appmixer Studio, Appmixer JavaScript SDK) provide a drag&drop No-code designer for workflow automations. In design phase, the user is adding components to a flow, configures components, assigns accounts and interconnects components to form a data flow pipeline, possibly with logic and loops.When configuring components, the user can use variables to reference data that will be available at the flow runtime. These variables are outputs of components back in the chain (collection of all the outputs of all the ancestors of the configuring component).Variables can be modified at the flow runtime by applying modifiers. These modifiers are configurable and are represented as parametrized JavaScript functions that manipulate a single input. Modifiers can be chained to produce more complex expressions.The result of the design phase is a new or updated flow descriptor (JSON representation of the flow graph) and metadata, together with account assignment (externally linked) and modifiers (externally linked). Note that the flow descriptor in itself is not complete, the engine assumes the linked components and modifiers exist in the system. Therefore, copying a flow descriptor to another tenant can only work if the linked components and modifiers also exist in the target tenant.

Flow Running Phase Architecture

Flow is in the running phase when its configuration has been completed and the flow has been started. From this point, the flow does not require any user interaction and is executed and maintained by the engine in the background.During the flow running phase, the engine is responsible for passing external inputs to the associated trigger components (e.g. webhooks), scheduling polling type of triggers, orchestrating message passing between connected components, handling errors, retries, making sure defined quota limits are honored and logging all activity.The engine reports all unexpected events via system defined webhooks. This allows the customer to define custom actions in case e.g. the flow can’t run since a component in it lost authentication tokens (e.g. a 3rd party connected account was externally revoked).The engine has a built-in support for the most common authentication mechanisms (OAuth 1, OAuth 2, API keys, Basic auth, …) and can be extended with new ones. It automatically handles token refreshing for relevant authentication types.Components within a flow (and in general, when defined) don’t know about each other. They are black boxes that can be arbitrarily interconnected to produce different automations.If a message cannot be processed (e.g. a component tried to call an API which keeps failing multiple times - configurable) the engine stores such a message in a dead-letter collection in MongoDB and notifies a system configured webhook. This allows the customer to further inspect such messages, retry their processing and/or notify the end-user of such errors.The engine provides built-in scheduling mechanism, offering component developers an intuitive way for defining different types of timers, schedulers and throttles.

Appmixer Deployment Models

Appmixer supports all cloud deployment models:

Public cloud
Private cloud
VPC
Hybrid cloud

All 3rd party managed services and integrations are optional and customizable. For example, you can choose for which of the supporting technologies you prefer to use a 3rd party managed alternative. You can also choose what integrations you would like to offer to your end/internal-users and configure your own notifications (e.g. email) via customizable webhooks.

Appmixer Supporting Technologies

Appmixer uses multiple supporting technologies to function: MongoDB, RabbitMQ, Redis and ElasticSearch. All the supporting technologies are open-source.

Managed Services

Supporting technologies can be either installed and managed on an “as-is” basis or 3rd party managed (e.g. CloudAMQP’s RabbitMQ as a Service can be used).

For help with deploying Appmixer with full compatibility with AWS managed services for all the supporting technologies (Amazon MQ, ElasticCache, DocumentDB, OpenSearch), please contact our customer support (support@appmixer.com).

Appmixer Kubernetes Deployment

Appmixer self-managed package includes Docker and Kubernetes configuration files for easy deployment.

Appmixer engine (together with Appmixer Backoffice and Appmixer Studio) images are available via Appmixer Docker Registry.

API

ACL

Routes for setting ACL. Used in Backoffice.

Get ACL types

GET https://api.appmixer.com/acl-types

There are two types of access control lists, for components and for API routes. Restricted to admin users only.

[
    "routes",
    "components"
]

Get ACL rules for components|routes

GET https://api.appmixer.com/acl/:type

Get list of all the ACL rules for given type. Restricted to admin users only.

Path Parameters

Name

Type

Description

type

string

components | routes

[
    {
        "role": "admin",
        "resource": "*",
        "action": [
            "*"
        ],
        "attributes": [
            "non-private"
        ]
    },
    {
        "role": "user",
        "resource": "*",
        "action": [
            "*"
        ],
        "attributes": [
            "non-private"
        ]
    },
    {
        "role": "tester",
        "resource": "*",
        "action": [
            "*"
        ],
        "attributes": [
            "non-private"
        ]
    }
]

Update ACL rules

POST https://api.appmixer.com/acl/:type

Update ACL rule set for given type. Restricted to admin users only.

Path Parameters

Name

Type

Description

type

string

components | routes

Request Body

Name

Type

Description

array

Body has to be an array of ACL rules, where each rule has the following structure: { role: string - admin | user | tester ... resource: string - flows | appmixer.utils.* ... action: array of strings - * | read ... attributes: array of strings - * | non-private | ... }

Get available resource values

GET https://api.appmixer.com/acl/:type/resources

Get available values for resource property for an ACL rule. This is used for building UI in Backoffice for setting ACL rules. Restricted to admin users only.

Path Parameters

Name

Type

Description

type

string

components | routes

['*', 'flows']

Get available action values

GET https://api.appmixer.com/acl/:type/actions

Get available values for action property for an ACL rule. This is used for building UI in Backoffice for setting ACL rules. Restricted to admin users only.

Path Parameters

Name

Type

Description

type

string

components | routes

['*', 'read', '!read', 'create', '!create', 'update', '!update', 'delete', '!delete']

Get available options for attributes property.

GET https://api.appmixer.com/acl/:type/resource/:resource/attributes

Get available values for attributes property for an ACL rules. This is used for building UI in Backoffice for setting ACL rules. Restricted to admin users only.

Path Parameters

Name

Type

Description

type

string

components | routes

resource

string

resource name - flows, appmixer.utils.controls.*, ...

Accounts

Authentication to apps.

Get Accounts

GET /auth/:componentType

Get the list of accounts the user has previously authenticated with for this component type. curl "https://api.acme.com/auth/appmixer.slack.list.SendChannelMessage?componentId=e15ef119-8fcb-459b-aaae-2a3f9ee41f15" -H "Authorization: Bearer [ACCESS_TOKEN]"

Path Parameters

Name

Type

Description

Query Parameters

Name

Type

Description

  "componentType": "appmixer.slack.list.SendChannelMessage",
  "auth": {
    "accounts": {
      "5a6e21f3b266224186ac7d03": {
        "accessTokenValid": true,
        "accountId": "5a6e21f3b266224186ac7d03",
        "tokenId": "5a6e21f3b266224186ac7d04",
        "componentAssigned": true,
        "componentId": "e25dc901-f92a-46a2-8d29-2573d4ad65e5",
        "scopeValid": true,
        "authorizedScope": [
          "channels:read",
          "chat:write:user"
        ],
        "name": "U0UFJ0MFG - client IO",
        "displayName": "client IO"
      }
    }
  }
}

Get All Accounts

GET /accounts

Get the list of all accounts the user has authenticated with to any component. curl "https://api.appmixer.com/accounts" -H "Authorization: Bearer [ACCESS_TOKEN]"

Query Parameters

[
  {
    "accountId": "5a6e21f3b266224186ac7d03",
    "name": "U0UFJ0MFG - client IO",
    "displayName": null,
    "service": "appmixer:slack",
    "userId": "58593f07c3ee4f239dc69ff7",
    "profileInfo": {
      "id": "U0UFJ0MFG - client IO"
    },
    "icon": "data:image/png;base64,...rkJggg==",
    "label": "Slack"
  },
  {
    "accountId": "5a7313abb3a60729efe76f1e",
    "name": "t.o.mas@client.io",
    "displayName": null,
    "service": "appmixer:pipedrive",
    "userId": "58593f07c3ee4f239dc69ff7",
    "profileInfo": {
      "name": "tomas",
      "email": "t.o.mas@client.io"
    },
    "icon": "data:image/png;base64,...rkJggg==",
    "label": "Pipedrive"
  }
]

Example of filtering certain accounts:

// filtering acme accounts and aws accounts
curl --request GET 'http://api.acme.com/accounts?filter=service:!acme:[service]&filter=service:!appmixer:aws' \
--header 'Authorization: Bearer [ACCESS_TOKEN]'

Update Account Info

PUT /accounts/:accountId

Update account information. Currently, only the display name can be updated. The display name is visible in the Designer inspector when selecting available accounts for a component type and also on the Accounts page. curl -XPUT "https://api.appmixer.com/accounts/5a6e21f3b266224186ac7d03" -H "Authorization: Bearer [ACCESS_TOKEN]" -H "Content-Type: application/json" -d '{ "displayName": "My Account Name" }'

Path Parameters

Request Body

Create Account

POST /accounts

This can be used to create an account. Usually, an account is created when the user authenticates a component. There are scenarios where it is beneficial to create an account without user interaction (Integrations). There has to be an authentication module (auth.js) installed in Appmixer corresponding to the `service` ID. All the built-in authentication types are supported (Oauth1, Oauth2, API Key).

Query Parameters

Request Body

{
    "accountId": "5f841f3a43f477a9fa8fa4e9",
    "name": "[Name of the account]",
    "displayName": null,
    "service": "[vendor:service]",
    "userId": "5f804b96ea48ec47a8c444a7",
    "profileInfo": {
        
    },
    "pre": {},
    "revoked": false
}

Below is an example of a request to create s Slack (Oauth2) account.

curl --request POST 'https://api.acme.com/accounts' \
--header 'Authorization: Bearer [ACCESS_TOKEN]' \
--header 'Content-Type: application/json' \
--data-raw '{
    "service": "appmixer:slack",
    "token": {
        "accessToken": "[slack access token]",
        "scope": [
            "channels:write", 
            "groups:write", 
            "channels:read", 
            "channels:history", 
            "groups:read", 
            "groups:history", 
            "users:read", 
            "chat:write:user"
        ]
    },
    "profileInfo": {
        "id" : "[Name of the account that will be used in the frontend]"
    }
}'

Below is another example, this time for Google (Oauth2) account with access token expiration:

curl --request POST 'https://api.acme.com/accounts' \
--header 'Authorization: Bearer [ACCESS_TOKEN]' \
--header 'Content-Type: application/json' \
--data-raw '{
    "service": "appmixer:google",
    "token": {
        "token": "[google access token]",
        "expDate": "2021-02-04 15:34:48.833Z",
        "refreshToken": "[google refresh token]",
        "scope": [
            "https://www.googleapis.com/auth/analytics", 
            "https://www.googleapis.com/auth/analytics.readonly", 
            "https://www.googleapis.com/auth/calendar", 
            "https://www.googleapis.com/auth/calendar.readonly", 
            "https://www.googleapis.com/auth/drive", 
            "https://www.googleapis.com/auth/drive.appdata", 
            "https://www.googleapis.com/auth/drive.file", 
            "https://mail.google.com/", 
            "https://www.googleapis.com/auth/gmail.compose", 
            "https://www.googleapis.com/auth/gmail.send", 
            "https://www.googleapis.com/auth/gmail.readonly", 
            "https://spreadsheets.google.com/feeds", 
            "profile", 
            "email"
        ]
    }
}'

One more example, this time an API Key account:

curl --request POST 'https://api.acme.com/accounts' \
--header 'Authorization: Bearer [ACCESS_TOKEN]' \
--header 'Content-Type: application/json' \
--data-raw '{
    "service": "appmixer:aws",
    "token": {
        "accessKeyId" : "[AWS access key ID]",
        "secretKey" : "[AWS secret key]"
    }
}'

Test Account

POST /accounts/:accountId/test

Test account. Check if all the credentials (tokens) are still valid for the account. curl -XPOST "https://api.appmixer.com/accounts/5a6e21f3b266224186ac7d03/test" -H "Authorization: Bearer [ACCESS_TOKEN]"

Path Parameters

{ "5a6e21f3b266224186ac7d04": "valid" }

Remove Account

DELETE /accounts/:accountId

Remove the account and stop all the flows that this account is used in. curl -XDELETE "https://api.appmixer.com/accounts/5a6e21f3b266224186ac7d03" -H "Authorization: Bearer [ACCESS_TOKEN]"

Path Parameters

{ "accountId": "5abcd0ddc4c335326198c1b2" }

List All Flows Using Account

GET /accounts/:accountId/flows

List all the flows where the account is used. curl "https://api.appmixer.com/accounts/5a6e21f3b266224186ac7d03/flows" -H "Authorization: Bearer [ACCESS_TOKEN]"

Path Parameters

[
  {
    "flowId": "9251b4b6-4cdb-42ad-9431-1843e05307be",
    "name": "Flow #1"
  },
  {
    "flowId": "777d3024-43f6-4034-ac98-1cb5f320cb3a",
    "name": "Flow #2"
  },
  {
    "flowId": "9089f275-f5a5-4796-ba23-365412c5666e",
    "name": "Flow #3"
  }
]

Generate Authentication Session Ticket

POST /auth/ticket

Generate an authentication session ticket. This is the first call to be made before the user can authentication to a service. The flow is as follows: 1. Generate an authentication session ticket. 2. Get an authentication URL. 3. Start an authentication session. 4. Open the authentication URL in a browser to start the authentication flow. 5. Once the user completes the authentication flow, the browser redirects the user to a special Appmixer page which posts a message of the form "appmixer.auth.[success/failure].[ticket]" via the window.postMessage() call: https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage. Note that this is a low-level mechanism that you don't have to normally deal with. The Appmixer JS SDK handles all this for you. curl "https://api.appmixer.com/auth/ticket" -H "Authorization: Bearer [ACCESS_TOKEN]"

{ "ticket": "58593f07c3ee4f239dc69ff7:1d2a90df-b192-4a47-aaff-5a80bab66de5" }

Get Authentication URL

GET /auth/:componentType/auth-url/:ticket

Get an authentication URL. curl "https://api.appmixer.com/auth/appmixer.slack.list.SendChannelMessage/auth-url/58593f07c3ee4f239dc69ff7:1d2a90df-b192-4a47-aaff-5a80bab66de5" -H "Authorization: Bearer [ACCESS_TOKEN]"

Path Parameters

Query Parameters

{
    "authUrl": "https://slack.com/oauth/authorize?response_type=code&client_id=25316748213.218351034294&redirect_uri=http%3A%2F%2Flocalhost%3A2200%2Fauth%2Fslack%2Fcallback&state=38133t07c3ee4f369dc69ff7%3A1d2a90df-b192-4a47-aaff-5a80bab66de5&scope=channels%3Aread%2Cchat%3Awrite%3Auser"
}

Start Authentication Session

PUT /auth/:componentType/ticket/:ticket

Start the authentication session. curl -XPUT "https://api.appmixer.com/auth/appmixer.slack.list.SendChannelMessage/ticket/58593f07c3ee4f239dc69ff7:68982d38-d00c-4345-9a4a-82360d7e1649" -H "Authorization: Bearer [ACCESS_TOKEN]"

Path Parameters

{
    "service": "appmixer:slack"
}

Clear Authentication From Component

DELETE /auth/component/:componentId

Clear authentication associated with the component. Note that this call does not remove the account, it only removes the association of an account with a component. curl -XDELETE "https://api.appmixer.com/auth/component/e25dc901-f92a-46a2-8d29-2573d4ad65e5" -H "Authorization: Bearer [ACCESS_TOKEN]"

Path Parameters

{ "componentId": "e25dc901-f92a-46a2-8d29-2573d4ad65e5" }

Assign Account To Component

PUT /auth/component/:componentId/:accountId

Assign an account to a component. curl -XPUT "https://api.appmixer.com/auth/component/e25dc901-f92a-46a2-8d29-2573d4ad65e5/5a6e21f3b266224186ac7d03" -H "Authorization: Bearer [ACCESS_TOKEN]"

Path Parameters

{
    "accountId":"5a6e21f3b266224186ac7d03",
    "componentId":"e25dc901-f92a-46a2-8d29-2573d4ad65e5"
}

Apps

Get Apps

GET https://api.appmixer.com/apps

Returns all applications (services or modules) available. curl "https://api.appmixer.com/apps" -H "Authorization: Bearer [ACCESS_TOKEN]"

{
    "appmixer.asana": {
        "name": "appmixer.asana",
        "label": "Asana",
        "category": "applications",
        "description": "Asana is a collaborative information manager for workspace. It helps you organize people and tasks effectively.",
        "icon": "data:image/png;base64,iVBORw0KGgoA....kJggg=="
    },
    "appmixer.calendly": {
        "name": "appmixer.calendly",
        "label": "Calendly",
        "category": "applications",
        "description": "Calendly helps you schedule meetings without the back-and-forth emails. It does not work with the free Basic account. It works with Premium or Pro account.",
        "icon": "data:image/png;base64,iVBORw0KGgoA....kJggg=="
    },
    "appmixer.clearbit": {
        "name": "appmixer.clearbit",
        "label": "Clearbit",
        "category": "applications",
        "description": "Clearbit is a data API that lets you enrich your person and company records with social, demographic, and firmographic data.",
        "icon": "data:image/png;base64,iVBORw0KGgoA....kSuQmCC"
    },
    "appmixer.dropbox": {
        "name": "appmixer.dropbox",
        "label": "Dropbox",
        "category": "applications",
        "description": "Dropbox is a home for all your photos, documents, videos, and other files. Dropbox lets you access your stuff from anywhere and makes it easy to share with others.",
        "icon": "data:image/svg+xml;base64,PHN2Z....3N2Zz4="
    },
    "appmixer.evernote": {
        "name": "appmixer.evernote",
        "label": "Evernote",
        "category": "applications",
        "description": "Evernote is a powerful note taking application that makes it easy to capture ideas, images, contacts, and anything else you need to remember. Bring your life's work together in one digital workspace, available on all major mobile platforms and devices.",
        "icon": "data:image/png;base64,iVBORw0KGgoA....kSuQmCC"
    }
}

Get App Components

GET https://api.appmixer.com/apps/components

Returns all components of an app including their manifest files. curl "https://api.appmixer.com/apps/components?app=appmixer.dropbox" -H "Authorization: Bearer [ACCESS_TOKEN]"

Path Parameters

[
    {
        "name": "appmixer.twilio.sms.SendSMS",
        "author": "David Durman <david@client.io>",
        "icon": "data:image/png;base64,iVBORw...gg==",
        "description": "Send SMS text message through Twilio.",
        "auth": { "service": "appmixer:twilio" },
        "inPorts": [
            {
                "name": "message",
                "schema": {
                    "type": "object",
                    "properties": {
                        "body": { "type": "string" },
                        "to": { "type": "string" }
                    },
                    "required": [ "to" ]
                },
                "inspector": {
                    "inputs": {
                        "body": {
                            "type": "text",
                            "label": "Text message",
                            "tooltip": "Text message that should be sent.",
                            "index": 1
                        },
                        "to": {
                            "type": "text",
                            "label": "To number",
                            "tooltip": "The destination phone number. <br/><br/>Format with a '+' and country code e.g., +16175551212 (E.164 format).",
                            "index": 2
                        }
                    }
                }
            }
        ],
        "properties": {
            "schema": {
                "properties": {
                    "fromNumber": { "type": "string" }
                },
                "required": [ "fromNumber" ]
            },
            "inspector": {
                "inputs": {
                    "fromNumber": {
                        "type": "select",
                        "label": "From number",
                        "tooltip": "Select Twilio phone number.",
                        "index": 1,
                        "source": {
                            "url": "/component/appmixer/twilio/sms/ListFromNumbers?outPort=numbers",
                            "data": {
                                "transform": "./transformers#fromNumbersToSelectArray"
                            }
                        }
                    }
                }
            }
        }
    },
    {
        "name": "appmixer.twilio.calls.NewCall",
        "author": "David Durman <david@client.io>",
        "icon": "data:image/png;base64,iVBORw...gg==",
        "description": "Receive a call through Twilio.",
        "auth": { "service": "appmixer:twilio" },
        "webhook": true,
        "webhookAsync": true,
        "outPorts": [
            {
                "name": "call",
                "options": []
            }
        ],
        "properties": {
            "schema": {
                "properties": {
                    "generateInspector": { "type": "boolean" },
                    "url": {}
                }
            },
            "inspector": {
                "inputs": {
                    "url": {
                        "source": {
                            "url": "/component/appmixer/twilio/calls/NewCall?outPort=call",
                            "data": {
                                "properties": {
                                    "generateInspector": true
                                }
                            }
                        }
                    }
                }
            }
        }
    }
]

Get All Components

GET https://api.appmixer.com/components

Get all available components. curl "https://api.appmixer.com/components" -H "Authorization: Bearer [ACCESS_TOKEN]"

Query Parameters

[
    "appmixer.asana.projects.CreateProject",
    "appmixer.asana.projects.NewProject",
    "appmixer.asana.tasks.CreateStory",
    "appmixer.calendly.events.InviteeCanceled",
    "appmixer.calendly.events.InviteeCreated",
    "appmixer.clearbit.enrichment.FindCompany",
    "appmixer.clearbit.enrichment.FindPerson"
]

Publish A Component/Module/Service

POST https://api.appmixer.com/components

Publish a new component, new module or an entire service or update an existing component/module/service. The uploaded entity must be zipped and must have a proper directory/file structure inside (See Basic Component Structure for more details). Note that you can use the Appmixer CLI tool to pack your component/service/module to a zip archive (appmixer pack command). Alternatively, you can also use a regular zip command line utility but you should omit the node_modules/ directories before archiving and the root directory of the zip archive must match the vendor name. The directory hierarchy must have a well defined structure: [vendor]/[service]/[module]/[component]. The size limit of the zip archive is 10MB. Publishing a new component can take more time than a lifespan of a single HTTP request. Therefore, the result of the publishing HTTP call is a JSON object with ticket property. You can use the ticket to check for progress of the publish using the /components/uploader/:ticket endpoint. curl -XPOST "https://api.appmixer.com/components" -H "Authorization: Bearer [ACCESS_TOKEN]" -H "Content-type: application/octet-stream" --data-binary @appmixer.myservice.zip

{
    "ticket":"a194d145-3768-4a8a-84a4-4f1e4e08c4ad"
}

Check for Publishing Progress

GET https://api.appmixer.com/components/uploader/:ticket

Check for progress of publishing a component. curl -XGET "https://api.appmixer.com/components/uploader/2e9dd726-2b7f-46f7-bea4-8db7f7175aa8" -H "Authorization: Bearer [ACCESS_TOKEN]" -H "Content-type: application/json"

Path Parameters

// Successful upload. No errors:
{
  "finished": "2020-02-28T15:57:34.549Z"
}


// Upload finished. Errors encountered:
{
  "finished": "2020-02-28T15:25:39.515Z",
  "err": "Invalid schema for appmixer/utils/service.json",
  "data": [
    {
      "keyword": "required",
      "dataPath": "",
      "schemaPath": "#/required",
      "params": {
        "missingProperty": "label"
      },
      "message": "should have required property 'label'"
    },
    {
      "keyword": "required",
      "dataPath": "",
      "schemaPath": "#/required",
      "params": {
        "missingProperty": "description"
      },
      "message": "should have required property 'description'"
    }
  ]
}

Delete a Component/Module/Service

DELETE https://api.appmixer.com/components/:selector

Delete a component/module or an entire service. curl -XDELETE "https://api.appmixer.com/components/appmixer.myservice" -H "Authorization: Bearer [ACCESS_TOKEN]" -H "Content-type: application/json"

Path Parameters

Authentication

All API calls to Appmixer must include the Authorization header set to Bearer ACCESS_TOKEN.

curl "https://api.appmixer.com/apps" -H "Authorization: Bearer [ACCESS_TOKEN]"

POST https://api.appmixer.com/user/auth

Sign-in a user with credentials and get their access token. curl -XPOST "https://api.appmixer.com/user/auth" -H "Content-type: application/json" -d '{ "username": "abc@example.com", "password": "abc321" }'

Request Body

Name

Type

Description

password*

string

Password.

username*

string

Username, has to have an email format.

{
    "user": {
        "id": "5c88c7cc04a917256c726c3d",
        "username":"abc@example.com",
        "isActive": false,
        "email": "abc@example.com", 
        "plan":"free"
    },
    "token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjVjODhjN2NjMDRhOTE3MjU2YzcyNmMzZCIsInNjb3BlIjpbInVzZXIiXSwiaWF0IjoxNTUyNDkyNjA5LCJleHAiOjE1NTUwODQ2MDl9.9jVcqY0qo9Q_1GeK9Fg14v7OrdpWvzmqnv4jDMZfqnI"
}

Create User

POST https://api.appmixer.com/user

Create user. curl -XPOST "https://api.appmixer.com/user" -H "Content-type: application/json" -d '{ "username": "abc@example.com", "email": "abc@example.com", "password": "abc321" }'

Request Body

Name

Type

Description

password*

string

Password.

string

Email address.

username

string

Email address.

{
    "token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjVjODhjN2NjMDRhOTE3MjU2YzcyNmMzZCIsInNjb3BlIjpbInVzZXIiXSwiaWF0IjoxNTUyNDkyNjA5LCJleHAiOjE1NTUwODQ2MDl9.9jVcqY0qo9Q_1GeK9Fg14v7OrdpWvzmqnv4jDMZfqnI"
}

Get User Information

GET https://api.appmixer.com/user

Get user information. curl "https://api.appmixer.com/user" -H "Authorization: Bearer [ACCESS_TOKEN]"

{
  "id": "58593f07c3ee4f239dc69ff7",
  "username": "tomas@client.io",
  "isActive": true,
  "email": "tomas@client.io",
  "scope": [
    "user"
  ],
  "plan": "beta"
}

Charts

Create Chart

POST https://api.appmixer.com/charts

This method is not meant to be implemented by applications embedding Appmixer SDK. Creating chart requires complex objects (options, query, traces), their structure goes beyond this documentation. appmixer.ui.InsightsChartEditor SDK component should be used to build Charts.

Request Body

Name

Type

Description

{
    chartId: '5defb3901f17d98d974fbb00'
}

{
    "name":"Test create chart",
    "index":1,
    "type":"bar",
    "options":{
        "layout":{
            "showlegend":true,
            "xaxis":{
                "showline":true
            },
            "yaxis":{
                "showline":false
            },
            "barmode":"group",
            "bargap":0.2,
            "bargroupgap":0.1
        },
        "showgrid":true,
        "showticklabels":true,
        "horizontal":false
    },
    "query":{
        "range":{
            "from":{
                "endOf":null,
                "startOf":"day",
                "subtract":[7,"day"]
            },
            "to":{}
        }
    },
    "traces":{
        "2f985875-4149-4c7b-a4ab-e204269c0c0f":{
            "name":"Trace 1",
            "hidden":false,
            "agg":{
                "date_histogram":{
                    "interval":"1d",
                    "min_doc_count":"0",
                    "field":"@timestamp"
                }
            },
            "options":{
                "type":"bar",
                "linewidth":0,
                "opacity":1
            },
            "source":{
                "type":"flow",
                "targets":{
                    "dbd206a4-23b3-44a4-a6c4-59db74aa3fb5":[]
                }
            }
        }
    }
}

Update Chart

PUT https://api.appmixer.com/charts/:chartId

The same properties as in Create Chart API endpoint.

Path Parameters

{
    chartId: "5defa30cbd1ca06288202346"
    index: 1
    mtime: "2019-12-10T13:52:12.288Z"
    name: "Updated Chart"
    options: {,…}
    query: {,…}
    traces: {,…}
    type: "bar"
    userId: "5dee76c19462fe6b3fd42d79"   
}

Get Charts

GET https://api.appmixer.com/charts

Get a list of all charts the user has configured in their Insights Dashboard.

Query Parameters

[
    {
        "chartId": "5defa30cbd1ca06288202346",
        "userId": "5dee76c19462fe6b3fd42d79",
        "name": Chart 1",
        "index": 0,
        "type": "bar",
        "query": { ... },
        "options": { ... },
        "traces": { ... },
        "mtime": "2019-12-10T13:52:12.288Z"
    },
    {
        "chartId": "5defa30cbd1ca06288202347",
        "userId": "5dee76c19462fe6b3fd42d79",
        "name": Chart 2",
        "index": 0,
        "type": "bar",
        "query": { ... },
        "options": { ... },
        "traces": { ... },
        "mtime": "2019-13-10T13:52:12.288Z"
    }
]

Get One Chart

GET https://api.appmixer.com/charts/:id

Path Parameters

{
        "chartId": "5defa30cbd1ca06288202346",
        "userId": "5dee76c19462fe6b3fd42d79",
        "name": Chart 1",
        "index": 0,
        "type": "bar",
        "query": { ... },
        "options": { ... },
        "traces": { ... },
        "mtime": "2019-12-10T13:52:12.288Z"
}

Delete a Chart

DELETE https://api.appmixer.com/charts/:id

Path Parameters

Config

System configuration

Get current user-defined configuration values

GET /config

Only returns the values that have been stored by the user through the API

[
  {
    "key": "JWTSecret",
    "value": "OQekJ3DH4pRnWFl4wlN0hzhc5UIjdihEwFnwYLYUdXGXk+/f5JieT/1VLPUJnvALIGK014md41rUuarqYZscl2T5azHQmFhQmUKj8dEuoIELWB45wlkxDKcojCQi9Otk76itnmvKrbm/ZokDJxePNv2Edgc7/mLrTHG7l54w44c="
  },
  {
    "key": "WEBHOOK_FLOW_COMPONENT_ERROR",
    "value": "https://example.com/webhook"
  }
]

Create a configuration key/value pair

POST /config

Request Body

Name

Type

Description

{
  "key": "myConfigKey",
  "value": "My Custom Value"
}

Removes a configuration entry

DELETE /config/:key

Path Parameters

{ "ok": true }

Data Stores

Access Data Stores (built-in key-value store).

Get All Stores

GET https://api.appmixer.com/stores

Get all key-value stores. curl "https://api.appmixer.com/stores" -H "Authorization: Bearer [ACCESS_TOKEN]"

[{
    "name": "My Store 1",
    "storeId": "5c6fc9932ff3ff000747ead4"
}, {
    "name": "My Store 2",
    "storeId": "2a3fc9512bb3fca23747lai2"
}]

Get One Store metadata

GET https://api.appmixer.com/stores/:id

Get name of a store. curl "https://api.appmixer.com/stores/5c6fc9932ff3ff000747ead4" -H "Authorization: Bearer [ACCESS_TOKEN]"

Path Parameters

Name

Type

Description

{
    "name": "My Store 1",
    "storeId": "5c6fc9932ff3ff000747ead4"
}

Get Number of Records in a Store

GET https://api.appmixer.com/store/count

Get number of records in a store. curl "https://api.appmixer.com/store/count?storeId=5c6fc9932ff3ff000747ead4" -H "Authorization: Bearer [ACCESS_TOKEN]"

Path Parameters

{
    "count": 681
}

Get Store Records

GET https://api.appmixer.com/store

Get records. Supports search and pagination. curl "https://api.appmixer.com/store?storeId=5b213e0ef90a6200113abfd4&offset=0&limit=30&sort=updatedAt:-1" -H "Authorization: Bearer [ACCESS_TOKEN]"

Query Parameters

[{
    "key":"Box 8RE1",
    "storeId":"5b214ba6f90a6200113abfd8",
    "userId":"583c06511afb7b0016ef120b",
    "updatedAt":"2019-03-06T10:02:20.419Z",
    "value":"321",
    "createdAt":"2019-03-06T10:02:20.419Z"
},{
    "key":"T-shirt T41B",
    "storeId":"5b214ba6f90a6200113abfd8",
    "userId":"583c06511afb7b0016ef120b",
    "updatedAt":"2019-03-06T10:01:59.360Z",
    "value":"18",
    "createdAt":"2019-03-06T10:01:59.360Z"
},{
    "key":"T-shirt A12C",
    "storeId":"5b214ba6f90a6200113abfd8",
    "userId":"583c06511afb7b0016ef120b",
    "updatedAt":"2019-03-06T10:01:45.204Z",
    "value":"12",
    "createdAt":"2019-03-06T10:01:45.204Z"
}]

Create a new Store

POST https://api.appmixer.com/stores

Create a new key-value store. Returns the newly created Store ID. curl -XPOST "https://api.appmixer.com/stores" -H "Authorization: Bearer [ACCESS_TOKEN]" -H "Content-Type: application/json" -d '{ "name": "My Store" }'

Request Body

{
    "storeId": "5c7f9bfe51dbaf0007f08db0"
}

Delete a Store

DELETE https://api.appmixer.com/stores/:id

Delete a store and all the records in the store. curl -XDELETE "https://api.appmixer.com/stores/5c7f9bfe51dbaf0007f08db0" -H "Authorization: Bearer [ACCESS_TOKEN]"

Path Parameters

Rename a Store

PUT https://api.appmixer.com/stores/:id

Rename an existing store. curl -XPUT "https://api.appmixer.com/stores/5c7f9bfe51dbaf0007f08db0" -H "Authorization: Bearer [ACCESS_TOKEN]" -H "Content-Type: application/json" -d '{ "name": "My New Name" }'

Path Parameters

Request Body

{
    "oldName":"My Old Store Name",
    "storeId":"5c7f9bfe51dbaf0007f08db0"
}

Create a new Store Item

POST https://api.appmixer.com/store/:id/:key

Create a new value in the store under a key. curl -XPOST "https://api.appmixer.com/store/5c7f9bfe51dbaf0007f08db0/mykey" -H "Authorization: Bearer [ACCESS_TOKEN]" -H "Content-Type: text/plain" -d "my value"

Path Parameters

Request Body

{
    "key":"mykey",
    "value":"myvalue",
    "createdAt":"2019-03-06T10:17:58.796Z",
    "updatedAt":"2019-03-06T10:17:58.796Z"
}

Update key or value of an existing store item

PATCH https://api.appmixer.com/store/:id/:key

Use this endpoint to rename a key or update the value against the key. Updates are passed in the body payload.

curl --location --request PATCH 'https://api.appmixer.com/store/623632fb3eb18366c82aa9fd/existingKey' --header 'Authorization: Bearer [ACCESS TOKEN]' --header 'Content-Type: application/json' --data-raw '{ "key": "newKey", "value": "newValue" }'

Path Parameters

Request Body

{
    "key": "New Key",
    "value": "New Value"
    "createdAt": "2021-09-01T11:34:00.258+0000",
    "updatedAt": "2021-09-01T11:34:00.258+0000",
}

Delete Store Items

DELETE https://api.appmixer.com/store

Delete one or multiple items from a store. curl -XDELETE "https://api.appmixer.com/store" -H "Authorization: Bearer [ACCESS_TOKEN]" -H "Content-Type: application/json" -d '[{ key: "mykey", storeId: "5c7f9bfe51dbaf0007f08db0" }, { "key": "mykey2", "storeId": "5c7f9bfe51dbaf0007f08db0" }]'

Request Body

{
    "deletedCount": 1
}

Files

Appmixer allows you to upload files to use them in your flows.

Get file info

GET https://api.appmixer.com/files/metadata/:fileId

Get the information for the specified file. Note that the file content is not included.

Path Parameters

Name

Type

Description

{
    "length": 146737,
    "chunkSize": 261120,
    "uploadDate": "2020-07-24T19:19:49.755Z",
    "filename": "chart1.png",
    "md5": "1d0ed5eb2cacbab4526de272837102dd",
    "metadata": {
        "userId": "5f15d59cef81ecb3344fab55"
    },
    "contentType": "image/png",
    "fileId": "f179c163-2ad8-4f9d-bce5-95200691b7f9"
}

Upload a file

POST https://api.appmixer.com/files

Upload file to Appmixer. Uploads by chunks are supported, and whether if sent file is treated as a chunk or a new file depends on the headers sent. Also, Content-type must be set to multipart/form-data.

Headers

Request Body

{
  "length": 146737,
  "chunkSize": 261120,
  "uploadDate": "2020-07-24T20:23:38.565Z",
  "filename": "chart1.png",
  "md5": "1d0ed5eb2cacbab4526de272837102dd",
  "metadata": {
    "userId": "5f15d59cef81ecb3344fab55"
  },
  "contentType": "image/png",
  "fileId": "8cb8fed0-0cd8-4478-8372-9f7cb4eb16e3"
}

Appmixer SDK

Constructor

Appmixer Constructor lays a foundation for building user interfaces with widgets.

Configuration

Set up a new appmixer instance with config parameters and set/get methods:

const appmixer = new Appmixer({/* [name]: value */})

appmixer.set(name, value)
appmixer.get(name)

`config.baseUrl`

Type: String | Default: null

Base URL of your Appmixer engine REST API.

`config.accessToken`

Type: String | Default: null

Access token of an authorized user.

`config.debug`

Type: Boolean | Default: false

Enable debugger for development purposes.

`config.theme`

Type: Object | Default: DefaultTheme

`config.l10n`

Type: Object | Default: DefaultL10N

Define custom localization texts.

`config.lang`

Type: String | Default: en

Specify a language code for the localization of components.

`config.api`

Type: Object | Default: {}

Set custom API methods.

Instance

`appmixer.ui`

appmixer.ui('Widget', {/* ... */})
appmixer.ui.Widget({/* ... */})

`appmixer.api`

Use methods of built-in API Module.

`appmixer.set`

appmixer.set(key, value)

Set configuration property.

`appmixer.get`

appmixer.get(key, value)

Get configuration property.

`appmixer.registerCustomComponentShape`

appmixer.registerCustomComponentShape(name, shape)

`appmixer.registerInspectorField`

appmixer.registerInspectorField(type, Field, options)

Basic Usage

Connect to Appmixer engine REST API and render user interfaces with a built-in widget:

<html lang="en">
<head>
  <meta charset="UTF-8">
  <script src="https://my.YOURTENANT.appmixer.cloud/appmixer/appmixer.js"></script>
</head>
<body>
  <div id="your-widget"></div>

  <script async type="module">
    const appmixer = new Appmixer({ baseUrl: BASE_URL })

    const auth = await appmixer.api.signupUser(USERNAME, PASSWORD)
    appmixer.set('accessToken', auth.token)

    appmixer.ui.FlowManager({ el: '#your-widget' }).open()
  </script>
</body>
</html>

Change USERNAME and PASSWORD parameters to valid credentials for registration of a new user.

Learn more about the basic usage with the Quick Start example.