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

The name of the service. The name must have the [vendor].[service] format where [vendor] is the Vendor name (See e.g. for more details). Normally you'll have just one vendor or use the default 'appmixer' vendor. [service] is the name of your service. Example: "appmixer.google", "appmixer.twilio", ... .

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

The name of the module. The name must have the [vendor].[service].[module] format where [vendor] is the Vendor name (See e.g. for more details). Normally you'll have just one vendor or use the default 'appmixer' vendor. [service] is the name of your service and [module] is the name of your module. Examples: "appmixer.google.gmail", "appmixer.google.calendar", .... . Note that the directory structure of your module must follow this name. In other words, if you have a module named "appmixer.myservice.mymodule", your directory structure will look like this: myservice/mymodule.

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ář <[email protected]>",
    "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.

icon

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

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 <[email protected]>"
}

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:

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.

To set additional global values for a service, use the authConfig API. See the 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 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 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 .

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.

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:

outPort.source

The definition is similar to the source source of . 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.

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.

Dependencies

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

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 .

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:

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

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.

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.

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

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: ,
Data objects: , , ,
Livecycle 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):

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):

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

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
            });
        }
    }
});

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);

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

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 "[email protected]" and "abc321" with your own user's username and password):

You should see a response that looks like this:

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:

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

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

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": "[email protected]"}, { $set: {"scope": ["user", "admin"]}})'

Replace the "[email protected]" 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 "[email protected]" 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:

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 "[email protected]" and "abc321" with your own user's username and password):

curl -XPOST "http://localhost:2200/user/auth" -d '{"username": "[email protected]", "password": "abc321"}' -H 'Content-Type: application/json'

You should see a response that looks like this:

{"user":{"id":"5c88c7cc04a917256c726c3d","username":"[email protected]","isActive":false,"email":"[email protected]","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 API 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 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.

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

It will set both the APPMIXER_API_URL and the GRIDD_URL to the https://247bb870a6f4.ngrok.io.

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: https://docs.google.com/document/d/e/2PACX-1vRNIciiW_uIQnKIlpFrhsRNqAyHmY5fueyJXAGt2ARgUPkkdwZVMnquKt33Z3nPt1jjJ3xwsltdlT1R/pub

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

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.

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.*, ...

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": "[email protected]", "password": "abc321" }'

Request Body

Name

Type

Description

password*

string

Password.

username*

string

Username, has to have an email format.

{
    "user": {
        "id": "5c88c7cc04a917256c726c3d",
        "username":"[email protected]",
        "isActive": false,
        "email": "[email protected]", 
        "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": "[email protected]", "email": "[email protected]", "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": "[email protected]",
  "isActive": true,
  "email": "[email protected]",
  "scope": [
    "user"
  ],
  "plan": "beta"
}

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

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

Name

Type

Description

Request Body

Name

Type

Description

Modifiers

Get Modifiers

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

Get available modifiers. Appmixer is shipped by default with its own set of modifiers by default. Checkout this API to see what they are. You can then redefine the default set with the following API endpoint.

{
    "categories": {
        "object": {
            "label": "Object",
            "index": 1
        },
        "list": {
            "label": "List",
            "index": 2
        },
        ...
    },
    "modifiers": {
        "g_stringify": {
            "name": "stringify",
            "label": "Stringify",
            "category": [
                "object",
                "list"
            ],
            "description": "Convert an object or list to a JSON string.",
            "arguments": [
                {
                    "name": "space",
                    "type": "number",
                    "isHash": true
                }
            ],
            "returns": {
                "type": "string"
            },
            "helperFn": "function(value, { hash }) {\n\n                return JSON.stringify(value, null, hash.space);\n            }"
        },
        "g_length": {
            "name": "length",
            "label": "Length",
            "category": [
                "list",
                "text"
            ],
            "description": "Find length of text or list.",
            "arguments": [],
            "returns": {
                "type": "number"
            },
            "helperFn": "function(value) {\n\n                return value && value.hasOwnProperty('length') ? value.length : 0;\n            }"
        },
        ...
    }
    
}

Edit Modifiers

PUT https://api.appmixer.com/modifiers

Change the modifiers and their categories as a whole. Restricted to admin users only. Before editing existing modifiers or adding new ones, checkout the GET /modifiers API to see the structure.

Request Body

Name

Type

Description

Delete Modifiers

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

Delete all modifiers. Restricted to admin users only.

{}

Test Modifier Function

POST https://api.appmixer.com/modifiers/test

This endpoint can be used to test a helper function with the desired arguments, to check how it will behave under different conditions. curl -XPOST "https://api.appmixer.com/modifiers/test" -H "Content-type: application/json" -H "Authorization: Bearer [ACCESS-TOKEN]" -d '{ "helperFn": "function(value) { return value && value.hasOwnProperty('\''length'\'') ? value.length : 0; }", "arguments": ["test"]}'

Request Body

Name

Type

Description

helperFn

string

The Javascript helper function as a string.

arguments

array

The arguments to be passed to the helper function.

{
    "statusCode": 400,
    "error": "Bad Request",
    "message": "The function returned \"undefined\""
}

Public Files

Returns a list of the public files

GET /public-files

The list returned does not contain the contents of the files.

Upload a public file

POST /public-files

Request Body

Name

Type

Description

Removes a public file

DELETE /public-files/:filename

Path Parameters

Name

Type

Description

Service Configuration

Appmixer allows you to save global configuration values for your service. If a component contains either an auth section or authConfig section, values for specified service will be injected.

Only users with admin scope can use these endpoints.

Get Services Configuration

GET /service-config

Get a list of stored configurations.

Query Parameters

Name

Type

Description

pattern

string

A term to filter configurations containing pattern on their service id

sort

string

Sorting parameter. Service id can be used to sort results alphabetically by their id. Example: serviceId:1

offset

number

Index of the first item returned. Default is 0. Useful for paging.

limit

number

Maximum items returned. Default is 100. Useful for paging.

[
	{
		"serviceId": "appmixer:google",
		"clientID": "my-global-client-id",
		"clientSecret": "my-global-client-secret"
	},
	{
		"serviceId": "appmixer:evernote",
		"sandbox": true,
	}
]

Get Service Configuration

GET /service-config/:serviceId

Get the configuration stored for the given service.

Path Parameters

Name

Type

Description

string

The service id. Example: appmixer:google

{
	"serviceId": "appmixer:google",
	"clientID": "my-global-client-id",
	"clientSecret": "my-global-client-secret"
}

Create Service Configuration

POST /service-config

Creates a new configuration for a service. The only required parameter on the payload is the serviceId. The rest of the payload can be any key/value pairs that will be the desired configuration for the service. For example: { "serviceId": "appmixer:google", "clientID": "my-global-client-id", "clientSecret": "my-global-client-secret" }

Request Body

Name

Type

Description

whatever

string

Any value for the whatever-key

serviceId

string

The serviceId. It should be in the form vendor:service. Example: appmixer:google

{
	"serviceId": "appmixer:google",
	"clientID": "my-global-client-id",
	"clientSecret": "my-global-client-secret"
}

Update Service Configuration

PUT /service-config/:serviceId

Updates the stored configuration for the given service. The payload should contain the whole configuration, as the payload content will overwrite the configuration stored under the service.

Path Parameters

Name

Type

Description

serviceId

string

The service id. Example

Request Body

Name

Type

Description

whatever-key

string

Any value you need

{
	"serviceId": "appmixer:google",
	"clientID": "my-global-client-id",
	"clientSecret": "my-global-client-secret"
}

Delete Service Configuration

DELETE /service-config/:serviceId

Removes the configuration from the given service.

Path Parameters

Name

Type

Description

serviceId

string

The service id. Example: appmixer:google

{}

Variables

GET flow variables

GET https://api.appmixer.com/variables/:flowId

Get variables. Variables are placeholders that can be used in component config or inputs. These placeholders are replaced either at runtime by data coming from components connected back in the chain (dynamic variables) or by real values (static variables). Get component config variables: curl "https://api.appmixer.com/variables/93198d48-e680-49bb-855c-58c2c11d1857?componentId=e25dc901-f92a-46a2-8d29-2573d4ad65e5" -H "Authorization: Bearer [ACCESS_TOKEN]" Get component input variables: In this case, we identify the connection (one path in the flow graph) by source and target components, output port of the source component and input port of the target component. This address uniquely identifies one "link" in the flow graph. curl "https://api.appmixer.com/variables/93198d48-e680-49bb-855c-58c2c11d1857?srcComponentId=ba09820f-db59-4739-b22d-414826842495&srcComponentOut=trigger&tgtComponentId=e25dc901-f92a-46a2-8d29-2573d4ad65e5&tgtComponentIn=message" -H "Authorization: Bearer [ACCESS_TOKEN]"

Path Parameters

Name

Type

Description

flowId*

String

Query Parameters

Name

Type

Description

srcComponentOut

String

Name of the output port of the source component.

srcComponentId

String

ID of the source (connected) component ID.

tgtComponentId

String

ID of the target component ID.

tgtComponentIn

String

Name of the input port of the target component.

componentId

String

The ID of the component for which we're requesting config static variables.

{
    // Response
}

Appmixer SDK

Introduction

Appmixer SKD is a toolkit to integrate workflow automation engine and embed white-labeled user interface widgets into your products. Gain a whole new set of comprehensive features with ease.

Installation

Appmixer SDK package includes two types of modules: basic UMD and advanced ESM.

Basic Usage

Load appmixer.js UMD module in your HTML file:

Advanced Usage

Download appmixer.es.js ESM module and include the file in your project:

Choose Appmixer UI widgets to include:

Quick Start

Let's start with a simple user interface to browse and manage your flows.

Create the html demo below and follow the steps ahead to learn the essentials.

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

  <script async type="module">
    const appmixer = new Appmixer()

    appmixer.set('baseUrl', BASE_URL)

    try {
        const auth = await appmixer.api.signupUser(USERNAME, PASSWORD)
        appmixer.set('accessToken', auth.token)
    } catch (error) {
        alert(error)
    }

    const flowManager = appmixer.ui.FlowManager({ el: '#flow-manager' })
    const designer = appmixer.ui.Designer({ el: '#designer' })

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

    flowManager.open()
  </script>
</body>
</html>

Get Appmixer constructor from appmixer.js file and create a new instance:

  <script src="https://my.YOURTENANT.appmixer.cloud/appmixer/appmixer.js"></script>

const appmixer = new Appmixer()

2. Set baseUrl to connect the API module to the REST API of your engine:

appmixer.set('baseUrl', BASE_URL)

3. Create a new user and set accessToken to authorize your appmixer instance:

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

Change USERNAME(e.g. [email protected]) and PASSWORD(e.g. 12345678) parameters to valid credentials for registration of a new user. Or use an authentication method if the user already exists:

const auth = await appmixer.api.authenticateUser(USERNAME, PASSWORD)

Thetoken is used by Appmixer to identify the user. Store the token and credentials in a database of your product. This way, you can always associate your users with the (virtual) ones created for Appmixer.

4. Create new instances of Flow Manager and Designer widgets:

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

const flowManager = appmixer.ui.FlowManager({ el: '#flow-manager' })
const designer = appmixer.ui.Designer({ el: '#designer' })

5. Open Flow Manager to browse the flows and switch to Designer when a flow is selected:

flowManager.open()

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

UI & Widgets

Appmixer UI is a tool for building user interfaces with component-based widgets.

Configuration

Widgets are included in appmixer.ui instances made with Appmixer constructor:

const appmixer = new Appmixer(/* ... */)
const widget = appmixer.ui.FlowManager(config)

`config.el`

Type: String|Element | Default: null

HTML DOM element to serve as a container of the widget.

`config.theme`

Type: Object | Default: DefaultTheme

Custom theme definition.

`config.l10n`

Type: Object | Default: DefaultL10N

Custom localization texts.

`config.lang`

Type: String | Default: en

Language code for localization of components.

`config.api`

Type: Object | Default: DefaultAPI

Custom API methods.

Instance

widget.open()

Mount the widget instance and render it inside the el container.

widget.close()

Unmount the widget instance and hide the el container.

widget.reload()

Reload the entire widget.

widget.reset()

Reset the state of the widget to defaults.

Use state for properties that may change at any time when the widget is active.

widget.state(path, value) // setter
widget.state(path) // getter

Example

{
  "foo": false,
  "bar": { "counter": 1 }
}

// set properties by key or path
widget.state('foo', true)
widget.state('bar', { counter: 2 })
widget.state('bar/counter', 3)

// get properties by key or path
widget.state('foo') // true
widget.state('bar') // { counter: 3 }
widget.state('bar/counter') // 3

// get the entire state
widget.state() // { foo: true, bar: { counter: 3 } }

// reset the state to defaults
widget.reset() // { foo: false, bar: { counter: 1 } }

widget.set(key, value)

Set config property.

widget.get(key, value)

Get config property.

widget.on(name, handler)

Add a new event listener and disable the default handler of the event.

widget.off(name)

Remove an event listener and enable the default handler of the event.

Insights Logs

Browse logs of messages that passed through flows.

Configuration

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

const insightsLogs = appmixer.ui.InsightsLogs(config)

insightsLogs.set(key, value)
insightsLogs.get(key)

`config.el` `...`

Learn about widget config here.

`config.flowId`

ID of a flow to filter the logs by.

Instance

Learn about widget instance here.

State

insightsLogs.state(name, value)

`loader`

Type: Boolean | Default: null

Toggle a custom loading state.

`error`

Type: String | Default: null

Toggle a custom error message.

Example

const insightsLogs = appmixer.ui.InsightsLogs({
    el: '#insights-logs'
})

insightsLogs.open()

Insights Chart Editor

Create charts to visualize logs of messages that passed through flows.

Configuration

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

const insightsChartEditor = appmixer.ui.InsightsChartEditor(config)

insightsChartEditor.set(key, value)
insightsChartEditor.get(key)

`config.el` `...`

Learn about widget config here.

Instance

Learn about widget instance here.

State

insightsChartEditor.state(name, value)

`loader`

Type: Boolean | Default: null

Toggle a custom loading state.

`error`

Type: String | Default: null

Toggle a custom error message.

Events

insightsChartEditor.on(event, handler)

`close`

insightsChartEditor.on('close', () => {/* ... */})

Close the editor.

Example

const insightsChartEditor = appmixer.ui.InsightsChartEditor({
    el: '#insights-chart-editor'
})

insightsChartEditor.open()

Insights Dashboard

Browse and manipulate charts created by the current user.

Configuration

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

const insightsDashboard = appmixer.ui.InsightsDashboard(config)

insightsDashboard.set(key, value)
insightsDashboard.get(key)

`config.el` `...`

Learn about widget config here.

Instance

Learn about widget instance here.

State

insightsDashboard.state(name, value)

`loader`

Type: Boolean | Default: null

Toggle a custom loading state.

`error`

Type: String | Default: null

Toggle a custom error message.

Events

insightsDashboard.on(event, handler)

`chart:clone`

insightsDashboard.on('chart:clone', chartId => {/* ... */})

Clone chart.

`chart:remove`

insightsDashboard.on('chart:remove', chartId => {/* ... */})

Remove chart.

`chart:open`

insightsDashboard.on('chart:open', chartId => {/* ... */})

Open chart in Chart Editor.

Example

const insightsDashboard = appmixer.ui.InsightsDashboard({
    el: '#insights-dashboard'
})

insightsDashboard.open()

Accounts

Manage accounts authorized by the current user.

Configuration

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

const accounts = appmixer.ui.Accounts(config)

accounts.set(key, value)
accounts.get(key)

`config.el` `...`

Learn about widget config here.

Instance

Learn about widget instance here.

State

accounts.state(name, value)

`loader`

Type: Boolean | Default: null

Toggle a custom loading state.

`error`

Type: String | Default: null

Toggle a custom error message.

Events

accounts.on(event, handler)

`flow:open`

accounts.on('flow:open', flowId => {/* ... */})

Select a flow to open in Designer widget.

Example

const accounts = appmixer.ui.Accounts({
    el: '#accounts'
})

accounts.open()

Storage

Manage records associated with data storage utility components of flows.

Configuration

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

const storage = appmixer.ui.Storage(config)

storage.set(key, value)
storage.get(key)

`config.el` `...`

Learn about widget config here.

`config.storeId`

Type: String | Default: []

ID of a store to open within the storage.

Instance

Learn about widget instance here.

State

storage.state(name, value)

`loader`

Type: Boolean | Default: null

Toggle a custom loading state.

`error`

Type: String | Default: null

Toggle a custom error message.

Example

const storage = appmixer.ui.Storage({
    el: '#storage'
})

storage.open()

People Tasks

Manage tasks created by utility components of flows.

Configuration

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

`config.el` `...`

Learn about widget config .

Instance

Learn about widget instance .

State

`loader`

Type: Boolean | Default: null

Toggle a custom loading state.

`error`

Type: String | Default: null

Toggle a custom error message.

Example

Connectors

Browse apps and components that are accessible to the current user inside flows.

Configuration

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

`config.el` `...`

Learn about widget config .

Instance

Learn about widget instance .

State

`loader`

Type: Boolean | Default: null

Toggle a custom loading state.

`error`

Type: String | Default: null

Toggle a custom error message.

Example

Integrations

Manage flows used as integration templates and instances.

Configuration

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

`config.el` `...`

Learn about widget config .

`config.options`

Type: Object | Default: {}

`config.options.customFilter`

Type: Object | Default: {}

Filter the integrations with additional parameters:

Instance

Learn about widget instance .

State

`loader`

Type: Boolean | Default: null

Toggle a custom loading state.

`error`

Type: String | Default: null

Toggle a custom error message.

Events

`integration:create`

Click a button to to create a new integration from template.

`integration:edit`

Click a button to edit integration.

`integration:remove`

Click a button to remove integration.

`integration:start`

Click a button to start integration.

`integration:stop`

Click a button to stop integration.

Example

Wizard

Manage a flow that is used as an integration instance.

Configuration

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

const wizard = appmixer.ui.Wizard(config)

wizard.set(key, value)
wizard.get(key)

`config.el` `...`

Learn about widget config here.

`config.flowId`

Type: String | Default: null

ID of a flow that is opened in the wizard.

Instance

Learn about widget instance here.

State

wizard.state(name, value)

`loader`

Type: Boolean | Default: null

Toggle a custom loading state.

`error`

Type: String | Default: null

Toggle a custom error message.

Events

wizard.on(event, handler)

`flow:start`

wizard.on('flow:open', flowId => {/* ... */})

Submit the form and start the flow.

`cancel`

wizard.on('cancel', () => {/* ... */})

Click a button to close the form.

Example

const wizard = appmixer.ui.Wizard({
    el: '#wizard',
    flowId: 'your-integration-id'
})

wizard.on('flow:start', async flowId => {
    await appmixer.api.startFlow(flowId)
    wizard.close()
})

wizard.open()

Developer mode

Developer mode enables tools that are useful to create and debug your flows

Enabling developer mode

Developer mode is disabled by default on the SDK instance. There are two ways to enabling/disabling developer mode. Through the SDK constructor:

// Create new instance with developer mode enabled
var appmixer = new Appmixer({
    devMode: true
})

Or using the SDK instance set method:

// Enable developer mode at runtime
appmixer.set('devMode', true)

Using the setter allows you to enable/disable developer mode dynamically.

Developer mode tools

Currently developer mode expose a show/hide logs button on the Designer UI:

This log panel allows you to inspect the messages of your running flow in real time, without needing to navigate away from the Designer UI. This is very useful when you are creating your flow and you want to make sure everything is working as expected. Moreover, you can get details from each message by clicking on it:

Appmixer Backoffice

Getting Started

Appmixer Backoffice is an administration UI for Appmixer. You need an admin user account in order to log into Backoffice. More about that in here.

Appmixer Backoffice runs on port 8081 by default. After you install the Appmixer package you can open http://localhost:8081.

And sign in with your Appmixer user account.

Services

Open Appmixer Backoffice and click the Services item in the main menu.

Appmixer comes with a set of components. Some of those can be used directly, but some require user authentication into a 3rd party system (Slack for instance). This authentication is usually done through the OAuth protocol. That protocol requires pair of secrets stored in Appmixer.

There are more ways how to save those secrets in Appmixer. Using Appmixer Backoffice is the easiest one. Let's say you want to start using Slack components. First, you need to register your Slack application on the Slack website, then you will be provided with clientId and clientSecret. Once you have those, you can save them into Appmixer like this:

As a Service ID you use appmixer:slack. This is the same value that is used in Slack component.json files in the auth section.

This tells Appmixer that the NewChannelMessageRT component uses appmixer:slack authentication module. Appmixer will try to locate authentication file auth.js in appmixer/slack directory.

We can now add the clientId and clientSecret.

Then add clientId (has to be clientId, not clientID or any other combination) key with your client Id.

And then the clientSecret.

After that, you can use the Slack components in Appmixer.

You can add any key/value pair here. All the keys and their values will be available in your component's code at context.auth object and in the case of auth.js files directly in the context object.

You can use this configuration even for components that do not require user authentication into 3rd party applications. DeepAI component is a good example. In this case, you need an API key in order to use the Deep AI API. But you don't want your users to provide that API key. You want to use your own API key for all your users. More about that here.

Quotas

You can customize the quotas used by your services through the Appmixer Backoffice. For more information about quotas, see the section. You can find the Quotas section in the left menu.

You will see a list of the existing quota definitions and a button for adding a new quota definition. What you can see here depends on what modules are installed in Appmixer. Brand new Appmixer installation without any modules will contain an empty list here. Once you add a module into Appmixer that uses quotas (appmixer.slack for example), a new row appmixer.slack will appear here.

The main purpose of this page is to give you the possibility to override the default quota rules that come with each module. Some third-party services offer the possibility to increase their quota limits by paying more money to them. When you do so, you need to tell Appmixer that it can start sending more API requests to such services. This is the way to do so.

Quota definitions that come by default are marked as non-user defined, and cannot be deleted, but they can be modified.

To create a new quota definition, click on the Add new quota definition button on the top left. This will popup a dialog like this:

You will have to provide a service name (this is the same service name defined in the component manifest):

Next are the quota rules. When the dialog is opened, you will find a rule definition as an example. More detailed info about the quota rules can be found . You can use the Test button to check if your definition is valid. Once you are done, just click the Save button. You will see the new quota in the list.

When quotas are created or edited by you, they are marked as user-defined. These quotas can be deleted, however, if you delete a quota definition not created by you (this is, that came by default), it will revert to the default definition. If you delete a quota that was created from scratch by you, deleting it will remove it entirely.

This is how the new quota looks in the quota list. You can see the options for editing and removing quotas in the Definition column.

For editing quotas, the dialog is the same as the one for creating new quotas.

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: '[email protected]',
        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.

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: '[email protected]',
        approver: '[email protected]',
        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.

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

String representing the format of the date/time. Please see the moment.js library documentation for all the available tokens: .

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.