An OpenAPI spec driven automation tool to orchestrate workflows across different services.


stars 🌟issues ⚠️updated 🛠created 🐣size 🏋️‍♀️
05May 9, 2021Aug 7, 2018Minified + gzip package size for @chiaoti/automate in KB



An OpenAPI spec driven automation tool to orchestrate workflows across different services.

Build Status


Let's take a tour by creating an example flow for testing Swagger Petstore service.
The Petstore API spec with Automate Extension can be found here.


npm install @chiaoti/automate

Get started

Assuming we have the spec file Petstore.yaml installed in /my/own/specs/.

const Automate = require('@chiaoti/automate')

// Create an automate instance.
const automate = new Automate({ specPath: '/my/own/specs/' })

// Initialization process:
//  - Load and parse OpenAPI specs for generating services and methods
//  - Init event system (TODO)
//  - Init database and load saved flows (TODO)
  .then(function () {
    // Now you're able to call automate methods.
    // Create a flow here
  .catch(function (err) {
    // Oops! this shouldn't happen.

A set of methods is provided by the automate instance for managing actions and flows. You can use them after automate instance is initialized as you can see in the above code.

Create a flow

Let's create a flow by calling createFlow():

const flow = automate
    name: 'Example Flow',
    description: 'An example to test Petstore APIs.'

The flow we've just created does nothing since it still has no action at this moment.

It is worth noting that we add an Autorun trigger to the flow. This means the flow will be triggered to run automatically once the system starts.

A flow can be also triggered by arbitrary events defined by users. We will discuss this later.

Find methods from specific services

Before creating an action, we first need to find a method from a service.

A method, contains the definition of arguments and returns, is used for action runners to know how to run the action correctly. The codes below shows you the methods we need for creating actions for the example.

// Get CoreFunction & Petstore service.
const CoreFuncService = automate.findServiceByName('CoreFunction')
const PetstoreService = automate.findServiceByName('Petstore')

// Get methods from CoreFunction service.
const methodLog = CoreFuncService.findMethod('log')
const methodDelay = CoreFuncService.findMethod('delay')

// Get methods from Petstore service.
const methodAddPet = PetstoreService.findMethod('addPet')
const methodGetPetById = PetstoreService.findMethod('getPetById')
const methodDeletePet = PetstoreService.findMethod('deletePet')

The method name is specified by operationId property in the spec.

For all core methods provides by CoreFunction service, check here.

Create actions

In this section, we will create 5 actions for the flow and illustrate how data flows through all the actions.

// Create `log start message` action
const logStartMsg = automate
  .createAction({ name: 'LogStartMsg' })
  .withArgs({ message: 'Starting petstore test...' })

// Create `add pet` action
const addPet = automate
    name: 'AddPet',
    description: 'Add a pet',
    wait: true,
    timeout: 15000,
    onErrorAction: Automate.Action.Constants.ON_ERROR_STOP_FLOW,
    transform: {
      id: 'petId'
    name: 'kitty',
    category: {
      id: 25,
      name: 'Cats'
    photoUrls: ['http://hello.kitty/avatar.jpg'],
    status: 'available'

// Create `delay 3 seconds` action
const delay = automate
  .createAction({ name: 'Delay3Secs' })
  .withArgs({ ms: 3000 })

// Create `get pet by id` action
const getPetById = automate
    name: 'GetPetById',
    description: 'Find a pet by Id',
    onErrorAction: Automate.Action.Constants.ON_ERROR_STOP_FLOW,
    transform: {
      id: 'petId'

const deletePet = automate
    name: 'DeletePet',
    description: 'Delete a pet',
    wait: true,
    timeout: 15000,
    onErrorAction: Automate.Action.Constants.ON_ERROR_STOP_FLOW,
    transform: {
      $assignTo: 'message'

// Create `log start message` action
const logResult = automate
  .createAction({ name: 'LogResult' })


Add actions to the flow


  .onBeforeRunning((args) => {
    // Prepare to run the flow
  .onActionRunning((action) => {
    // Called on each action in the flow runs
  .onActionFailed((error, action) => {
    // Called while an action is failed to run
  .onAfterRunning((error, result, args) => {
    // The flow completed with result or error


Start automate service



Stop automate service

You can stop automate service whenever you want by calling stop() method. For example, you can stop service while a flow completed:

flow.onAfterRunning(() => {

Full source code

The full source code of above example (petstore-simple-flow) is here.
You can also find all example codes here.

Trigger a Flow by User-defined Event

Check out this example about this topic.

Action Runners

Core Runner


Fetch Runner




Create your own runner


Action Error Handling

const {
  ON_ERROR_IGNORE_ACTION, // Ignore failed action
  ON_ERROR_RETRY_ACTION,  // Retry failed action
  ON_ERROR_RESTART_FLOW,  // Restart entire flow on failure
  ON_ERROR_STOP_FLOW      // Stop flow on failure (default)
} = Automate.Action.Constants

OpenAPI Spec with Automate Extension




  - name: Petstore
    category: Demo
    runner: fetch
      - name: Inventory Empty
        description: Inventory is empty.
      - name: Inventory Full
        description: Inventory is full.




  - name: CoreFunction
    description: Provides automate core function methods.
    runner: core
    methodTag: x-automate-core-functions
      - name: Autorun
        description: >-
          This event is used to trigger flows that wish to run automatically on `Automate` service starts.
      - name: Error
        description: Errors reported by `error_report` runner.

  - name: Automate
    description: Provides web api for operating Automate service.
    category: Productivity
    runner: fetch

    summary: Log message
      - name: message
        type: string
        required: true
    summary: Delay an action.
      - name: ms
        description: Milliseconds
        type: number
        required: true
    summary: Transfer execution from a flow to another.
      - name: flow
        type: string
        required: true
        description: A flow id



If you find any bugs or have a feature request, please open an issue on github!

The npm package download data comes from npm's download counts api and package details come from npms.io.