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

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.

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.

Designer Toolbar

The toolbar is configurable. You have to specify them in the appmixer.ui.Designer constructor, otherwise, it will be empty. More information .

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.

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

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

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.

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

The author of the component. Example:

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 section, especially the for details and example.

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 .

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.

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.

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

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

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

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

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

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

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

quota.manager

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

quota.resources

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

quota.scope

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

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

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.

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.

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

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

An example of outPorts definition can look like this:

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

outPort.maxConnections

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

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

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:

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

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.

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.

High-Level Architecture

Appmixer consists of multiple technologies that interact with each other:

Appmixer

appmixer.ui.Storage

The appmixer.ui.Storage is a UI widget that displays the user's data stores.

appmixer.ui.PeopleTasks

The appmixer.ui.PeopleTasks is a UI widget that displays people task dashboard for the user. Please see the for more details.

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:

Unfortunately, since August 20, 2018 no longer accepts signups.

We keep the module in Appmixer for the older customers who have their Oauth2 application. If you are a new Appmixer customer, you won't be able to create the OAuth2 application and therefore use the Highrise module. In that case, you should remove it from the platform.

User-Agent

Appmixer offers a built-in component for taking Screenshots.

It uses API. If you want to have this module on the platform you have to create your own Screenshot account and set the API token in the Backoffice.

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

appmixer.ui.InsightsLogs

The appmixer.ui.InsightsLogs is a UI widget that displays logs and histogram of all messages that passed through the user's flows. It can display logs of one flow or combine logs of all the user's flows.

Sign-up at DeepAI

Visit https://deepai.org and sign-up:

Copy api-key from your profile dashboard:

Set the DEEPAI_API_KEY environment variable in your Appmixer engine deployment.

Or set it through the Backoffice.

And then add you own apiKey value:

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:

An optional object containing localization strings. For example:

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

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:

Setting a Custom Theme

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

appmixer.ui.Accounts

The appmixer.ui.Accounts is a UI widget that displays the user's connected accounts.

Domain verification

In order to use Google API Webhooks you have to verify your domain ownership. More about domain verification can be found in . When Appmixer is running on your servers, you can use records to verify your domain ownership, but if you want to use components that use Google API Webhooks (appmixer.google.drive.NewFile for example) in an Appmixer instance running on your localhost (typical for testing the trial or when developing new components) you need something else. When running Appmixer on localhost, you usually use tools like to create public tunnel to the Appmixer API. In order to verify ngrok domain ownership you can use the .

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

Knowledge base

Please visit the for end-user tutorials.

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:

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:

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.

Time Localization

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

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:

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

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.

Slots

Sometimes words inside longer text have some functionality bound to them, typically a clickable link. For example, the Flow Manager displays the following text when there are no flows created yet:

The word "here", when clicked, opens up the Designer for the user to create a new flow. So how to localize the text and keep the functionality? Enter slots. Slots allow us to keep the functionality (and sometimes styling) bound to the words inside our localized strings. The strings object for this scenario looks like this:

The tokens (@createFlow) and (/@createFlow) are quite similar to HTML tags, meaning that what is between them will be bound to the event described by the token names (i.e. createFlow event).

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:

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

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:

Replace <your-base-url> with http://localhost:2200 and <your-username> and <your-password> with the user credentials that you used in the 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:

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

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

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:

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

To learn more about the Appmixer JavaScript SDK, please visit the 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:

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

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

An example of a quota module:

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

Quota Module Structure

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

rules

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

limit

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

window

The time window in milliseconds.

throttling

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

resource

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

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

Upload a file

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

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

Headers

Request Body

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.

appmixer.ui.InsightsDashboard

The appmixer.ui.InsightsDashboard is a UI widget that displays all the charts that the user has defined. The charts are interactive and can be re-arranged with drag&drop, refreshed to reflect the latest state, cloned and removed. Usually, you would listen to the chart:open event to open the appmixer.ui.InsightsChartEditor for the user to be able to re-configure their chart.

InsightsDashboard Events

Example

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

Sign-in User

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

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

Get User Information

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

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

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:

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

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

inPort.schema

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

inPort.inspector

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

inPort.source

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

inPort.variablesPipeline

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

inPort.maxConnections

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

Get Services Configuration

appmixer.ui.InsightsChartEditor

The appmixer.ui.InsightsChartEditor is a UI widget that allows the user to configure a new chart visualization of any data of their flows. Different types of charts are supported including bar, line, area, scatter, pie and more. Moreover, the user can select from a wide range of aggregations to create an aggregated visualization of their data such as Date Histogram, Sum, Min, Max, Average, Unique Count, Range and Filter.

Setting Custom Metadata

Each flow can have assigned a custom metadata object. This metadata object is called customFields throughout the documentation and can be any JSON object. In the examples below, we show how to define custom metadata on a flow using each of the available Appmixer interfaces (REST API, Appmixer SDK).

appmixer.ui.Integrations

The appmixer.ui.Integrations is a UI widget that displays available and active integrations.

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

• Docker

• v12.13.0 (only for )

Installation

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

Install and Start Appmixer

Stop Appmixer

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

Stop and Clean Up

Stop Appmixer and remove all containers and images:

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

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:

with the URL from ngrok:

Now restart Appmixer:

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

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

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:

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:

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

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.

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.

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

Update ACL rules

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

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

Path Parameters

Request Body

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

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

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

Embed Appmixer UI in your own web pages with the Appmixer SDK

You can use the provided Appmixer SDK to include the Appmixer UI widgets (including the Drag&Drop Designer, Flows manager, Insights, ...) any web page, right into your own web products, completely white-labeled. First, include the appmixer.js in your page:

Once you included the Appmixer SDK, you need to create an instance of the global Appmixer class and pass the base URL of the engine:

Now you can create your first user:

Now we can create the first flow and open the Appmixer Designer to let your user design their first flow.

At this point, you should see the Appmixer Designer rendered inside your <div id="my-am-designer"> element.

Once you create a user in Appmixer (appmixer.api.signupUser()) and have stored their username and password in your system, you can always request a new token by calling appmixer.api.authenticateUser():

Full Example

Register OAuth2 app

Got to https://api.slack.com/apps and create a new app.

Name your application and select a workspace.

Then you receive your clientID and clientSecret.

Copy and paste those secrets into the Backoffice.

The next thing is adding the redirect URL and scopes.

And add these scopes.

In order to use the application accross workspaces you have to distribute it.

Events API

Some components (NewChannelMessageRT) use Slack Events API (). In order to use this component(s) in Appmixer, you have to register Appmixer's Slack URI in Slack first.

Go to then choose your Appmixer app.

Go to your app settings ()

The Request URL has to point to your Appmixer backend server. The rest of the URL /services/appmixer/slack/events has to remain like this. Your Appmixer backend server has to be running before you enter the URL. Slack will immediately try to connect to that URL.

Then you need to subscribe to messages.channels and message.groups events.

Don't forget to hit Save Changes:

You can now use the appmixer.slack.list.NewChannelMessageRT component in a flow.

Slack app migration

In Appmixer 4.2 the Slack module was upgraded. We did remove all the legacy API and switched to their newest API. For some time, it was possible to use the Appmixer Slack module with both legacy Slack apps and the new Slack apps. But the legacy apps are deprecated and will retire in August 2021 (). If you use the legacy Slack app, you either have to create a new Slack app or migrate the existing one.

In order to migrate your Slack legacy app, go to Oauth & Permission section.

Then scroll down to Scopes and hit the Update Scopes button.

Ignore the first page, because that's all about scopes for bots.

Scroll all the way down and hit continue. You get to a second page with user scopes.

Select channels:read, channels:history, channels:write, groups:read, groups:write, groups:history, chat:write and users:read.

Verify the scopes and migrate the app.

And confirm. The Appmixer Slack module since version 4.2.1 is already updated and ready for the new Slack apps.

Flows that use the SendPrivateChannelMessage component won't work. The component will appear unauthenticated. The reason is a different Oauth scope in the new Slack app version. In this case, the user has to authenticate the component again.

Introduction

Appmixer provides a built-in support for sharing flows with other users. When a user shares their flow, they provide a list of email addresses of other Appmixer users that they want to share their flow with:

When a flow is shared, users from the share list can see the flow in their accounts.

Sharing Flows Using the Appmixer JavaScript SDK

To share a flow using the Appmixer SDK, update the flow with the special sharedWith list. The list contains objects with email and permissions properties where email is the email address of another Appmixer user and permissions is a list of permissions. Currently, the following permissions are available:

Example:

To unshare a flow, simply update the sharedWith array with an empty list:

Define Sharing Options in the Share Dialog

The FlowManager and Designer UI widgets contain menus that allow the user to share their flows. Invoking the share menu item brings up a dialog box that looks like this:

The Appmixer SDK allows you to configure the sharing options available to the user. For example, you can define that the share dialog will give the user permission to share their flow only for read (and not stop/start) with:

You can also define the share types (email, domain, scope):

Sharing Flows Using the Appmixer API

Sharing flows with the Appmixer API follows the same pattern as sharing flows using the Appmixer SDK. To share a flow, update the flow with the sharedWith list:

Get messages

GET https://api.appmixer.com/unprocessed-messages

Get the list of the unprocessed messages for the current user.

appmixer.ui.Designer

The appmixer.ui.Designer is a UI widget that displays the drag&drop Flow Designer.

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