Overview

In nanoservices, a workflow outlines the sequence of nodes (execution steps), their configuration, data flow, and the trigger that starts the workflow.

​

Workflow Structure & Format

{
  "name": "World Countries",
  "description": "Workflow description",
  "version": "1.0.0",
  "trigger": {
    "http": {
      "method": "GET",
      "path": "/",
      "accept": "application/json"
    }
  },
  "steps": [
    {
      "name": "get-countries-api",
      "node": "@nanoservice/api-call",
      "type": "module"
    }
  ],
  "nodes": {
    "get-countries-api": {
      "inputs": {
        "url": "https://countriesnow.space/api/v0.1/countries/capital",
        "method": "GET",
        "headers": {
          "Content-Type": "application/json"
        },
        "responseType": "application/json"
      }
    }
  }
} 

​

Explanation of the Example

This section breaks down the provided workflow JSON example to explain its key components and how they work together.

​

Workflow Name and Description

• name: "World Countries"
  • This is the name of the workflow, used for identification.
• description: "Workflow description"
  • A short description of what the workflow does.

​

HTTP Trigger

The workflow is triggered via an HTTP request. The trigger configuration specifies:

• method: "GET"
  • The HTTP method used to access the workflow.
• path: "/"
  • The endpoint where the workflow is exposed.
• accept: "application/json"
  • Specifies the expected response format for the HTTP request.

This means that a GET request to the root endpoint (/) with an Accept header of application/json will activate the workflow.

​

Steps

The steps array outlines the sequence of execution for the workflow:

• name: "get-countries-api"
  • A unique identifier for this step.
• node: "@nanoservice/api-call"
  • The module or custom nanoservice being executed.
• type: "module"
  • Indicates the type of the node, which in this case is a pre-built module.

In this example, the workflow has one step that makes an API call to fetch country data.

​

Node Configuration

Each node in the workflow has a corresponding configuration in the nodes object.

• inputs: Parameters passed to the node for execution.
  • url: "https://countriesnow.space/api/v0.1/countries/capital"
    • The API endpoint to fetch data from.
  • method: "GET"
    • Specifies the HTTP method for the API request.
  • headers:
    • Includes a Content-Type header to indicate the type of data being sent or requested.
  • responseType: "application/json"
    • Indicates the expected format of the API response.

​

Customizing the Workflow

You can adapt and extend workflows to meet the needs of your application.

​

Adding More Steps

To enhance the workflow, include additional steps in the steps array. Each new step should have:

• A unique name.
• A reference to a node (node).
• A type specifying whether it’s a module or custom node.

Update the nodes object to configure the newly added steps.

Example: Adding a data transformation step.

"steps": [
  {
    "name": "get-countries-api",
    "node": "@nanoservice/api-call",
    "type": "module"
  },
  {
    "name": "transform-data",
    "node": "@nanoservice/transform",
    "type": "module"
  }
],
"nodes": {
  "get-countries-api": {
    "inputs": {
      "url": "https://countriesnow.space/api/v0.1/countries/capital",
      "method": "GET",
      "headers": {
        "Content-Type": "application/json"
      },
      "responseType": "application/json"
    }
  },
  "transform-data": {
    "inputs": {
      "mapping": { "country": "name", "capital": "capital" }
    }
  }
}

​

Modifying Triggers

Change the trigger to suit your requirements. For instance, modify the path to make the workflow accessible at a different endpoint:

"trigger": {
  "http": {
    "method": "POST",
    "path": "/countries",
    "accept": "application/json"
  }
}

​

Using Custom Nodes

You can replace pre-built modules with custom nanoservices to handle unique business logic.

Example: Replace @nanoservice/api-call with a custom node named custom-fetch-node:

"steps": [
  {
    "name": "fetch-data",
    "node": "custom-fetch-node",
    "type": "custom"
  }
],
"nodes": {
  "fetch-data": {
    "inputs": {
      "url": "https://example.com/api/data",
      "authToken": "Bearer <your-token>"
    }
  }
}

​

Combining Multiple Workflows

Workflows can also invoke other workflows, enabling you to build complex, multi-stage processes. Simply add a step that calls another workflow.

​

Data Mapping

​

CTX

CTX is a special object that contains the context of the workflow. It is used to pass data between nodes and steps as well as to extract information about the workflow itself. The structure of the object is defined on the trigger-level and can be modified when creating custom trigger.

• HTTP CTX structure

​

Global Methods

In addition to CTX, the data can be manipulated using global methods. These methods are available in all nodes and can be used to perform various operations on the data.

​

Creating Workflows

To create a new workflow, add a new file in the /workflows directory with the .json, .yaml, .toml, or .xml extension. The file should contain the workflow structure as described above.