ActiveWorkflow

ActiveWorkflow is an intelligent process automation platform that uses software agents; autonomous entities that act on schedule or react to external triggers. These unsupervised agents connect to APIs, process information, perform routine tasks, and enable you to automate internal or external workflows.

Overview

ActiveWorkflow is an intelligent process automation platform that uses software agents. A key objective when using ActiveWorkflow is to automate and orchestrate activities that would typically require human time and involvement. Thus, think more along the lines of replacing manual checking of websites, APIs, emails, and calendars rather than building low-level data pipelines (though that's also certainly possible). The basic concepts in ActiveWorkflow are agents and workflows. An overview of each follows below.

Agents

Agents are of different types and each type typically knows how to perform a simple task. For example, the HTTP Status Agent checks the status returned from an HTTP request and emits a corresponding message, while the Twilio Agent sends SMS messages or initiates phone calls.

Agents emit and receive messages (some only emit, or only receive). A structure of agents designated as message sources and message targets forms a network. This is what allows a group of agents to coordinate themselves and transform a collection of simple tasks into sophisticated and complex behaviour.

Some agents are self-contained, like the Trigger Agent that watches for specific values in the messages it receives. Others depend on complex third party services, like the aforementioned Twilio Agent.

Agents perform actions either on schedule or when they receive a message. There are also agents that can be triggered by external events. Agents are generally stateful and can have memory. For example, the IMAP Folder Agent remembers the last email it retrieved.

Each instance of an agent is configured by giving it a name, setting its schedule, selecting the sources of the messages it receives (other agents), and choosing among other common options:

Settings specific to a type of agent are often configured by editing the agent's "options" presented as a JSON document:

Each agent type has in-line documentation explaining its functionality and all its configuration options.

Workflows

A network of agents can quickly become crowded, making it hard to discern the whole picture. This is where the other key ActiveWorkflow concept comes into play. Agents sharing common goals can be organised into workflows.

Workflows allow you to view and control groups of agents all at once. They can also be exported and imported, so you can share automation solutions as a unit.

Usage

Once you have ActiveWorkflow up and running you will want to create some agents and most probably to arrange them in one or more workflows. You can use ActiveWorkflow via its web interface and its REST API as illustrated in the diagram below where a1-a6 are six agents and w1-w3 are three workflows these agents participate in.

Creating Agents

There are currently three ways to create agents, listed below in order of ease:

1. You can create a new instance of a built-in agent type and configure it via the web interface following the agent's configuration options and inline documentation. With 30+ built-in agents you have the ability to address many common business workflows.
2. If the functionality you wish to achieve isn't directly possible with any of the built-in agents then you can use the (built-in) JavaScript agent which let's you write custom JavaScript code that can send and receive messages.
3. Finally, if none of the above offers you the flexibility or the functionality you wish to achieve you can code and plug-in your own ActiveWorkflow agent. This is currently possible in Ruby and we are working on providing the functionality to code first-class custom agents in other programming languages (Python, JavaScript, Clojure, etc.).

In the near future you'll also be able to programmatically create agents via the REST API.

Creating Workflows

To create a workflow you simply use the web interface (the "New Workflow" button) to enter a name, description, select an icon for your workflow, and then link to it the agents that participate in it. As we have already mentioned agents can participate in multiple workflows and exist independently of them. In this respect a workflow is more like a "tag" or a "label", rather than a "container".

In the near future you'll also be able to programmatically create workflows via the REST API.

Built-in Agents

Below is a list of 30+ agents that come with ActiveWorkflow. These cover a wide spectrum of functionality and can be extensively configured and composed in workflows. Each agent comes with inline documentation within the web interface.

For writing your own custom agents see Custom Agents.

Input/Output Agents

These are agents that connect your workflows to the outside world. Some of them can be used to interface with third party services when a dedicated agent is not (yet) available.

Workflow and Data Processing Agents

These are agents that control the workflow and perform common and simple data processing operations.

Third Party Service Agents

These agents use third party services to provide functionality. They typically require an account with these services.

Custom Agents

You can create and use your own custom agents with ActiveWorkflow. There are two ways to accomplish this:

• If you prefer to write your agents in Ruby you can do so by using the custom agent API.
• However, the more flexible and recommended way is to use the remote agent API, which allows you to write your agents in any programming language you choose.

REST API

ActiveWorkflow provides a REST API to allow you to query and control your agents and workflows programmatically from your own code. We plan to provide ActiveWorkflow API clients in multiple languages starting with Ruby and Python.

You can read more details about interfacing with ActiveWorkflow programmatically in the REST API documentation.

Deployment

One-Click Heroku Deployment

The easiest way to start using ActiveWorkflow is by deploying it to Heroku.

If you are reading this document in a browser all you need to do is click the button bellow and fill in the environment variables for your seed user (admin): SEED_USERNAME, SEED_PASSWORD and SEED_EMAIL. Please note that SEED_PASSWORD must be at least 8 characters long.

A free Heroku plan could be used to try out ActiveWorkflow, but it wouldn't be enough for real use. That's because the limited run time and automatic turning off of unused workers inhibits ActiveWorkflow from running scheduled tasks.

Manual Heroku Deployment

If you would like more control or intend to deploy ActiveWorkflow from a modified source tree, you could do that using Heroku's command line interface.

Please install Heroku's command line interface tool from Heroku Toolbelt.

For your convenience there is a helper script that guides you through all the steps necessary to deploy to Heroku. It helps with Heroku app creation, plugin installation, initial configuration and repository synchronisation. Helper script is run with:

make setup-heroku

For additional configuration options please take a look at the .env file. Don't forget to set any configuration options you may require using the heroku config command line tool.

The default ActiveWorkflow configuration uses the same single dyno to run both the web server and workers.

Deployment with Docker

If you want to deploy ActiveWorkflow to a platform that uses docker containers, you could make an ActiveWorkflow image.

Note: currently there is no official ActiveWorkflow image.

Requirements

To build, use, or try out a docker image you would need the following tools: docker and docker-compose. (docker-compose is required if you plan to run docker images locally for testing).

On a Mac the recommended way to install docker is here.

On Linux please use your package manager or follow this docker installation guide.

Building the Image

You can build a docker image for deployment with:

make build-image

This creates an image named local/active_workflow.

Deployment with Docker to Heroku

You may prefer to use Heroku in a container mode (instead of deploying via GitHub). Please be sure to login to Heroku docker registry before doing that:

heroku container:login

Docker deployment to Heroku happens in two steps. Push:

make heroku-docker-push

And release:

make heroku-docker-release

If you no longer wish to use image based deployment to Heroku you will need to reset Heroku stack to heroku-18 like this:

heroku stack:set heroku-18

Development

Requirements

ActiveWorkflow is built using Ruby and is a Ruby on Rails app.

Install all dependencies with:

gem install bundler
bundle

Diagrams are rendered using the dot tool from Graphviz. On a Mac install Graphviz with:

brew install graphviz

Running Locally without Docker

If you want to test out ActiveWorkflow locally you can start a demo instance using a local sqlite database. First prepare the database with:

bundle exec rake db:create
bundle exec rake db:migrate
bundle exec rake db:seed

You can start the instance by running:

make start

This starts the ActiveWorkflow instance on a local address localhost:3000 with default username "admin" and password "password".

The local instance uses the configuration stored in a .env file. You could tweak it or use it as guidance when configuring your deployment target.

Tests can be run with make test.

Running Locally with Docker

You can test ActiveWorkflow using docker locally. Run it (with a PostgreSQL database in a separate container):

docker-compose up

This starts ActiveWorkflow instance on a local address localhost:3000 with default login "admin" and password "password".

Stop containers with:

docker-compose down

Acknowledgements

ActiveWorkflow started as a fork of Huginn with the goal of solely targeting business use. ActiveWorkflow is incompatible with Huginn.

License

ActiveWorkflow is released under the MIT License.