Appmixer CLI

Appmixer command-line tool.

Use the Appmixer CLI tool to interact with the Appmixer engine remotely from the command line. It can be used to list flows, start/stop flows but more importantly, to develop and publish custom components.

Installation

  • Download and install NodeJS: https://nodejs.org (version 14 is required)

  • npm install -g appmixer

On Windows, the installation might fail. In that case, try an older version of the CLI.

npm install -g [email protected]

Help

Display the command options with the -h option:

$ appmixer -h
Usage: appmixer [options] [command]

Appmixer command line interface.

Options:
  -v, --version  output the version number
  -h, --help     output usage information

Commands:
  download|d     Download component.
  flow|f         Flow commands.
  init|i         Initialize component.
  login|l        Login into Appmixer API.
  logout|o       Logout from Appmixer API.
  pack|p         Pack component into archive.
  publish|pu     Publish component.
  remove|rm      Remove component.
  test|t         Test component, authentication module, ...
  url|u <url>    Set Appmixer API url.
  help [cmd]     display help for [cmd]

Go to https://docs.appmixer.com/appmixer/ to find more information.

Each command has its own help information:

Initialization

First set the Appmixer API URL. This is the URL of your hosted Appmixer engine instance or your own custom URL where the self-managed engine is located. If you have a trial package or local installation, you can use http://localhost:2200.

Login to your Appmixer account and enter your password:

Creating Custom Components

Generate a sample component

The best way to start implementing your own custom components is to use the generator tool to generate a sample component. This gives you the basic skeleton of your component/service that you can later tweak. Use the appmixer init example command to generate a sample component:

As you can see, we have to give this command a type of example we want to generate. We will start with the most simple service type that does not use any authentication (OAuth1, OAuth2, API keys). In other words, the component will not ask the user to connect any account in the Inspector panel when using the component in a flow.

The command prints all the generated files and the directory structure. Note that we have just generated a working component with the myservice.mymodule.MyComponent type.

Pack your component

Now we're ready to pack our service (i.e. create a zip archive with all the generated files) using the appmixer pack appmixer/myservicecommand:

You can pack the entire service or just the module or even individual components by providing the path to the appmixer pack command.

The pack command generated the appmixer.myservice.zip file in the current directory.

Publish your component

Before you publish a component. Your user account has to have property vendor set to a string or an array of strings. The value depends on what vendor is used in component(s) you're about to publish. More about that in here. In the examples in this section we use appmixer as a vendor, but you should use your own. If your company is called acme then the vendor property should be set to acme as well. You can use Backoffice for that as shown in the next picture.

Using Backoffice to set vendor property.

The last step is to publish our component for our users to use. This is done using the appmixer publish command:

Our component is now published and ready to be used:

Custom component published

Notice the labels and icons of the service in the component panel on the left and of the component in the Inspector selector match our definitions from the myservice/service.json and myservice/mymodule/MyComponent/component.json manifest files.

List all available components

To see all the available components uploaded to Appmixer, use the appmixer component ls command:

Remove your component

If you decide your component is no longer needed, you can remove your component from the system with the appmixer remove command:

The remove command lets you specify any portion of the fully qualified component type. For example, if you want to remove the entire service, you can do that with:

It's important to note that removing a component that is used in any of the running flows will cause the flows to stop working. The flows will start generating errors that will be visible in the Insights section. The remove command does not automatically stop the flows. Always make sure the component is not used in any of the running flows before you remove it. IMPORTANT: Removing a component cannot be undone!

Updating your component

You can re-publish (appmixer publish) your component which effectively replaces the old component with the new one.

Note that re-publishing a component will not replace the component in a running flow. Flows wanting the new version of the component have to be stopped and started again to load the new version of the component.

Also note that if you "dramatically" change your component, e.g. removing ports, flows using the component type might require re-configuration since the ports that were used to connect to other components will not exist. The same goes for other major changes: changing output parameters that are used in connected components, changing inspector config and properties, etc.

Testing your component

Writing/updating code of your component, re-publishing it and re-configuring/restarting your flow every time you need to test your component would be a long process. Therefore, the Appmixer CLI tool provides a command to test your component locally on your machine, before publishing it to Appmixer. The appmixer test command allows you to test your component by sending messages to it, configuring properties and testing authentication methods:

We'll start by exploring the component testing tool:

Let's say we want to send a message to our component and see how it reacts, i.e. what is the output of our component. We know our component has an input port called in and requires the sourceData property as part of the incoming messages (see the component.json file of your MyComponent, especially the inPorts section). We can use the test command for this:

The command prints out a lot of useful information, for example the output of the component (see "Component sent a message to its output port: out"). Since our component just forwards the same data that it received, we see the same object we sent to it: { sourceData: 'foo' }.

Now suppose we have a bug in our code in MyComponent.js, a syntax error:

Now re-running the test gives us:

Downloading your component

When your component is published, you can always download it back to your local file system. To download the source code of your component, use the appmixer download command:

In our case, the download command would look like:

Working With Flows

Listing Flows

You can list all your flows using the appmixer flow ls command:

If you want to see see just one flow and its stage (running/stopped), you can pass the ID of the flow in the flow ls command:

To see the flow descriptor of a flow (i.e. JSON object that represents the entire configuration of the components in the flow and their connections), add the --descriptor or -d flag:

Starting and Stopping Flows

You can start and stop flows using the appmixer flow start and appmixer flow stop commands:

Removing Flows

To remove flows, use the appmixer flow remove command:

Note that the removed flow will be automatically stopped if it was running. Also note that this action cannot be undone.

Working with Modifiers

You need admin privileges to run these commands. You should not modify Modifiers if there are any running flows using them. Such operation would break the flows.

Downloading Modifiers

The next command will download modifiers from Appmixer and save into modifiers.json file.

Publishing Modifiers

The next command will publish modifiers into Appmixer.

Deleting Modifiers

The next command will delete existing modifiers from Appmixer. The next time Appmixer starts, it will load the default set of Modifiers.

OpenAPI Components Generator

This is an experimental feature. The OpenAPI spec generator is only available in the Beta version of the Appmixer CLI (install with npm install -g appmixer@beta).

The OpenAPI generator can automatically generate Appmixer components out of OpenAPI v3 specification.

Example

The following example generates Appmixer connector (service) from an OpenAPI v3 specification for the "Bored API" example API (https://www.boredapi.com/):

2KB
boredapi-openapi-v3.json
Open
OpenAPI v3 specification for the https://www.boredapi.com

The picture below shows how the different sections of the OpenAPI specification map to the Appmixer service/module/component metadata.

The generated boredapi service can then be published to the Appmixer engine with:

After that, you should see a new connector in your Appmixer Designer:

In our example, we generated only one component called GetActivity which we can use in our flows:

OpenAPI Coverage

The OpenAPI generator is very experimental at this stage. While it does support many of the OpenAPI v3 features, it is not yet complete. For example, the following features are not supported:

  • JSON Schema allOf is not supported.

  • JSON Schema oneOf is partially supported. Only the first option is considered.

  • JSON Schema anyOf is not supported.

  • Only http and apiKey security schemes are supported.

PreviousAppmixer Virtual UsersNextAzure Cognitive Services

Last updated

Was this helpful?