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

appmixer.ui.FlowManager

options.filters list changed to support following presets:

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 ). 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 and the 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 , refer to the 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

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 .

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 .

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.

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:

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

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

End User Guide

Knowledge base

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

Component Definition

Basic Structure

Introduction

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

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

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:

Members

Name of the component.
label
Label that will be used instead of name.
Component icon.
Component badge icon giving users extra context.
Author.
Description.
Authentication mechanism if the component requires authentication.
Parameters for the quota module used in the component (to conform with API usage limits).
Properties of the component.
Definition of the input of the component and how data transforms before it is processed by the component.
Definition of the output of the component and variables that other connected components can use in their input.
Requirements for the component input messages to decide whether the component is ready to fire.
Enable polling mechanism on the component.
Make component private to hide it from the user.
Make component "webhook"-type meaning it can receive HTTP requests.
Controls whether component's internal state is preserved across flow restarts.

name

(required)

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

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

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

label

(optional)

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

{ "label": "Create Tweet" }

icon

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

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

marker

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

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

author

The author of the component. Example:

{
    "author": "David Durman <[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:

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

auth

The authentication service and parameters. For example:

The auth.service identifies the 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 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

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

inPorts

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

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

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:

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:

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

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

tick

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

private

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

webhook

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

state

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

localization

An optional object containing localization strings. For example:

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

Dependencies

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

{
    "name": "appmixer.twilio.sms.SendSMS",
    "version": "1.0.0",
    "private": true,
    "main": "SendSMS.js",
    "author": "David Durman <[email protected]>",
    "dependencies": {
        "twilio": "^2.11.0"
    }
}

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

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

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:

Customizing UI

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:

The list of API methods can be found here.

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

Using Oauth applications

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

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

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

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

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

The OAuth variables can be set through the .

Appmixer Self-Managed

Getting Started

If you successfully installed the Appmixer self-managed package, you should be able to open the Appmixer front-end application at . 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:

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.

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 .

GRIDD_URL

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

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:

It will set both the APPMIXER_API_URL and the GRIDD_URL to the .

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

Or you can set just the GRIDD_URL like this:

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:

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.

Appmixer Deployment Models

Appmixer supports all cloud deployment models:

Public cloud
Private cloud
VPC
Hybrid cloud

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

Appmixer Supporting Technologies

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

Managed Services

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

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

Appmixer Kubernetes Deployment

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

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

API

Config

System configuration

Get current user-defined configuration values

GET /config

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

[
  {
    "key": "

Create a configuration key/value pair

POST /config

Request Body

Name

Type

Description

Removes a configuration entry

DELETE /config/:key

Path Parameters

Name

Type

Description

Public Files

Returns a list of the public files

GET /public-files

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

[
  {
    "filename": "

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

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

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:

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

<script type="module">
const appmixer = new Appmixer(/* ... */)
</script>

Advanced Usage

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

Choose Appmixer UI widgets to include:

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:

Insights Dashboard

Browse and manipulate charts created by the current user.

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.

Events

`chart:clone`

Clone chart.

`chart:remove`

Remove chart.

`chart:open`

Open chart in Chart Editor.

Example

Storage

Manage records associated with data storage utility components of flows.

Configuration

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

`config.el` `...`

Learn about widget config .

`config.storeId`

Type: String | Default: []

ID of a store to open within the storage.

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

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

Wizard

Manage a flow that is used as an integration instance.

Configuration

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

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

API Module

The Appmixer SDK uses this API module internally to connect to the REST API.

Name

Description

api.set(name, value)

Set configuration property.

api.get(name)

Get configuration property.

Configuration

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

`config.baseUrl`

Type: String | Default: null

Base URL of your Appmixer engine REST API.

`config.accessToken`

Type: String | Default: null

Access token of an authorized user.

Methods

`api.authenticateUser`

Authenticate a user to Appmixer. Note that this can be a "virtual" user that exists for the sole purpose of associating a real user of your own product to a user in Appmixer. Each user in Appmixer can have a set of flows, can run and stop flows, and can see data going through their flows. The returned promise is either resolved with an object that contains a token (which you need to set with appmixer.set('accessToken', token) to be able to make calls to the API backend. Or the promise is rejected with an error object. If the error object returns a 403 status code (i.e. err.response.status === 403), the user does not exist in Appmixer.

`api.signupUser`

Create a new user in Appmixer. The returned promise is either resolved with an authentication object (containing the token property) or rejected if the sign-up fails.

`api.createFlow`

appmixer.api.createFlow(name, [descriptor], [properties])Create a new flow in Appmixer. The returned promise resolves to the ID of the newly created flow. The properties object can contain your own custom metadata inside the customFields property. This is especially useful for filtering flows based on your own custom metadata.

`api.deleteFlow`

Delete an existing flow identified by flowId.

`api.getFlow`

Get flow. The returned promise resolves to an object with the following information: { id, flow, name, stage, btime, mtime, thumbnail }, where flow is the Flow Descriptor, stage is either 'running' or 'stopped', btime is the time the flow was created ("birth" time), mtime is the time the flow was modified and thumbnail contains a thumbnail image (self-contained, in the format).

`api.getFlows`

Get all flows of the user or filter them by query. query is an object with the following properties: limit, offset, pattern (a string to filter flows containing pattern in their names), sort, projection (allows you to exclude properties from the returned flow objects), sharedWithPermissions and filter.Example:

`api.getFlowsCount`

Get the number of all flows of the user or filter them by query. query is an object with pattern property that can include a string to filter flows containing a pattern in their names. Example: { "pattern": "dropbox" }.

`api.updateFlow`

Update an existing flow. update can contain the following information: { flow, name, customFields }, where flow is the Flow Descriptor of the flow and customFields is an object with your own custom metadata for this flow.

`api.startFlow`

Start a flow.

`api.stopFlow`

Stop a flow.

`api.cloneFlow`

Create a copy of an existing flow. The returned promise resolves to the ID of the newly created flow.

`api.getUser`

Get current user. The returned promise resolves to an object with username.

`api.getStores`

Get all the data stores. The returned promise resolves to an array of stores each an object with name and storeId properties.

`api.getStore`

Get one store. The returned promise resolves to an object with name and storeId properties.

`api.getStoreRecordsCount`

Get the number of records in a store. query is an object with storeId and pattern properties where pattern is a string to filter records that contain the string in their keys or values.

`api.getStoreRecords`

Get store records. query is an object with storeId, pattern (string to search for in keys/values), limit , offset and sort properties. Example:

`api.createStore`

Create a new store. The returned promise resolves to the ID of the newly created store.

`api.deleteStore`

Delete a store.

`api.renameStore`

Rename an existing store.

`api.createStoreItem`

Create a new record in a store.

`api.deleteStoreItems`

Delete store items. items is an array of objects each having a key and storeId properties identifying the item and store from which the item should be removed.

`api.createAccount`

Create a custom account.

`api.getAccounts`

Get a list of connected accounts of the user. filter is a custom query string (see the for an example). The returned promise resolves to an array of objects of the form { accountId, name, displayName, service, icon, profileInfo }.

`api.getComponentAccounts`

Get a list of accounts connected to a specific component.

`api.getAccountFlows`

Get a list of flows this account is used in. The returned promise resolves to an array of objects with flowId and name properties.

`api.setAccountName`

Rename a connected account. Note that this name is displayed in the Accounts widget and also in the Inspector UI of the Designer.

`api.getLogs`

Get logs. The query is an object of the form { from, size, sort, query }:

Get logs of a specific flow:

`api.getLog`

Get one log. logId and index are values returned from getLogs().

`api.getPeopleTasks`

Get all tasks of the user. query.role can be either "approver" or "requester" and allows you to filter tasks based on the role. query.pattern filters returned tasks by a term that must be contained in the task title. Settingquery.secret to either the approverSecret or requesterSecret allows you to get a list of tasks of a different user for which you have the secret (other than the one identified by the access token, i.e. the currently signed-in user).

`api.getPeopleTasksCount`

Returns the number of tasks based on the query. See getPeopleTasks(query) for more info.

`api.getPeopleTask`

Return one task identified by id.

`api.approveTask`

Approve a task identified by id. params is an optional object that can contain the secret property (approver secret). Having the secret allows you to approve a task of any user for which you have the secret, not just the currently signed-in user.

`api.rejectTask`

Reject a task identified by id. params is an optional object that can contain the secret property (approver secret). Having the secret allows you to reject a task of any user for which you have the secret, not just the currently signed-in user.

`api.getCharts`

Returns all the Insights charts of the user.

`api.getChart`

Return one Insights chart identified by chartId.

`api.deleteChart`

Delete an Insights chart identified by chartId.

`api.getFlowAuthentication`

This request will return an object with all the components in the flow that have auth section with all the available accounts.

Events

`error`

The event is triggered when a request fails with an error or when the access token is invalid.

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.

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:

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

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:

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

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:

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:

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.

HTTP Basic Authentication

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

Then the username and password is available in the components:

OAuth 1

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

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

Works exactly the same way as described in the section.

requestRequestToken ()

This must be a function (or an object, or just a string URL as explained ) 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 ()

This must be a function (or an object, or just a string URL as explained ) 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 ()

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 () (optional)

Works exactly the same way as described in the section.

validateAccessToken ()

This property serves the same purpose as 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:

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

Works exactly the same way as described in the section.

authUrl ()

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:

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

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 () (optional)

Works exactly the same way as described in the section.

refreshAccessToken ()

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

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

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:

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:

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.

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

Setting OAuth 1,2 secrets

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

You can use the 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.

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

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:

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:

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.

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.

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:

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

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

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:

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

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:

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.

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.

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:

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.

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:

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:

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

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.

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.

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

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:

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

async context.stopFlow()

Stop the running flow. Example:

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

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

Example:

async context.log(object)

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

Example:

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

Example:

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

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.

v4.4

Introduction

Migration from 4.3

hashtagAppmixer SDK

hashtagappmixer.ui

hashtagappmixer.ui.Designer

hashtagappmixer.ui.FlowManager

hashtagappmixer.ui.Components

hashtagAppmixer engine

hashtagNew ENV variables

hashtagWebhook can return 202 response

hashtagComponents

hashtagComponent versioning

hashtagModule changes

hashtagSlack Event API

hashtagMicrosoft OneDrive file picker

hashtagUtils Tasks

Overview

Introduction

Component

Flow

hashtagFlow Descriptor

End User Guide

hashtagKnowledge base

Component Definition

Basic Structure

hashtagIntroduction

Manifest

hashtagMembers

name

label

icon

marker

author

description

auth

authConfig

quota

hashtagquota.manager

inPorts

outPorts

firePatterns

tick

private

webhook

state

localization

Dependencies

Configuration

Customizing UI

Custom API

hashtagSetting a custom API option

Appmixer hosted

Getting started

Creating Custom Components

Using Appmixer API

Using Oauth applications

Appmixer Self-Managed

Getting Started

Using OAuth applications

hashtagGRIDD_URL

Configuration

hashtagAppmixer Engine

hashtagAPP_NAME

hashtagLOG_LEVEL

hashtagLOG_COMPONENT_DATA_MESSAGE

hashtagAPPMIXER_HTTPS_PROXY and APPMIXER_HTTP_PROXY

Appmixer Deployment Models

hashtagAppmixer Supporting Technologies

hashtagManaged Services

hashtagAppmixer Kubernetes Deployment

API

Config

hashtagGet current user-defined configuration values

hashtagCreate a configuration key/value pair

hashtagRequest Body

hashtagRemoves a configuration entry

hashtagPath Parameters

Public Files

hashtagReturns a list of the public files

Appmixer SDK

appmixer.ui

appmixer.ui.Designer

appmixer.ui.FlowManager

appmixer.ui.Components

Appmixer engine

New ENV variables

Webhook can return 202 response

Components

Component versioning

Module changes

Slack Event API

Microsoft OneDrive file picker

Utils Tasks

Flow Descriptor

Knowledge base

Introduction

Members

quota.manager

Setting a custom API option

GRIDD_URL

Appmixer Engine

APP_NAME

LOG_LEVEL

LOG_COMPONENT_DATA_MESSAGE

APPMIXER_HTTPS_PROXY and APPMIXER_HTTP_PROXY

Appmixer Supporting Technologies

Managed Services

Appmixer Kubernetes Deployment

Get current user-defined configuration values

Create a configuration key/value pair

Request Body

Removes a configuration entry

Path Parameters

Returns a list of the public files

Upload a public file

Request Body

Removes a public file

Path Parameters

GET flow variables

Basic Usage

Advanced Usage

Configuration

Configuration

`config.el` `...`

Instance

State

`loader`

`error`

Events

`chart:clone`

`chart:remove`

`chart:open`

Example

Configuration

`config.el` `...`

`config.storeId`

Instance

State

`loader`

`error`

Example

Configuration

`config.el` `...`

Instance

State

`loader`

`error`

Example

Configuration

`config.el` `...`

Instance

State

`loader`

`error`

Example

Configuration

Enabling developer mode

Developer mode tools

Knowledge base