The Configuration Object

The object field is the heart of every line in an import file. It holds the actual configuration and is where most of the work goes. This page walks through building it from scratch.

Object structure

The object takes one of two shapes, depending on whether the type uses named prototypes or a single default prototype:

{
  "prototype": "http-subscriber",
  "parameters": {
    "uri": "https://api.example.org"
  }
}

{
  "parameters": {
    "uri": "https://api.example.org"
  }
}

The first form names a prototype explicitly. The second is for types with a single default prototype, so no prototype key is needed.

Step by step

Pick a top-level type

The type at the top level of the line decides what you are building. Only the types below are allowed at the top level of an import line.The main types you start from:

Type	What it is
`route-configuration`	Connects one incoming to one outgoing and applies transformers
`incoming-configuration`	Pulls data in and creates tasks
`outgoing-configuration`	Pushes data out to a destination
`scheduler-entry`	Runs an incoming or a route’s outgoing on a cron schedule
`list-transformer`	A reusable, named data-processing pipeline

Connection types, referenced by the ones above:

Type	What it is
`http-client`	A reusable HTTP connection
`http-authentication`	Reusable authentication for HTTP clients
`soap-client`	A SOAP connection
`database-connection`	A database connection
`email-server`	An email server (SMTP or SendGrid)
`filesystem`	Remote or local file storage

Helper types:

Type	What it is
`entity`	Defines how items are identified, for deduplication and display
`storage`	An internal key-value store

Find the prototypes for that type

Each type offers a set of prototypes or a default prototype: templates with a JSON schema that lists the fields you fill in. Fetch the supported prototypes for a type from the Alumio API:

GET /api/v1/di/list/{type}/prototypes

See Finding configuration types and schemas below for more information.

Set the prototype and its parameters

Put the chosen prototype identifier in prototype, and fill the fields from its schema into parameters:

{
  "prototype": "pattern-move",
  "parameters": {
    "pattern": "sku",
    "replacement": "product_code"
  }
}

For a type that uses its default prototype, omit the prototype key and provide only parameters.

Reference or inline a nested configuration

Some fields hold another prototype or configuration rather than a plain value. The field’s schema tells you which through its di:type and di:allow properties (see Common schema properties below). When a reference is allowed, you have two options.Inline as its own prototype and parameters:

{
  "serializer": {
    "prototype": "json",
    "parameters": {
      "flags": [128]
    }
  }
}

Or reference a configuration that is already saved in the environment (or defined on another line in the same file), by its identifier:

{
  "client": {
    "identifier":"webshop-http-client"
  }
}

To see what already exists to reference, list the saved configurations of that type:

GET /api/v1/di/list/{type}/configurations

Nest as deep as you need

Prototypes can hold other prototypes, so the structure nests. In the example below, a list-transformer (prototype data) contains an http-transformer, whose client is a reference to a saved http-client (webshop) and whose request.serializer is an inline json prototype:

{
  "$schema": "https://di.schema.alumio.com/register.configuration.json",
  "type": "list-transformer",
  "identifier": "transformer-example",
  "name": "Transformer Example",
  "description": "",
  "object": {
    "prototype": "data",
    "parameters": {
      "transformers": [
        {
          "prototype": "http-transformer",
          "parameters": {
            "client": {
              "identifier": "webshop"
            },
            "request": {
              "uri": "/api/v1/orders",
              "method": "GET",
              "payload": "&{@}",
              "serializer": {
                "prototype": "json",
                "parameters": { "flags": [128] }
              },
              "payloadType": "data"
            }
          }
        }
      ]
    }
  }
}

ULIDs

Alumio stamps a ulid on every prototype object during import validation. Do not generate them yourself.

When creating: omit ulid everywhere. The server injects them.
When updating: start from the exported or fetched JSON and keep the ulid fields it already contains, so embedded objects keep their identity.

Finding configuration types and schemas

Use the Alumio API to find prototypes and configurations.

Search for prototypes of a type

To list all available prototypes for a type use the following API call.

GET /api/v1/di/list/{type}/prototypes

List saved configurations

To see what is already configured in the environment (so you reuse instead of duplicate), list the saved configurations of a type.

GET /api/v1/di/list/{type}/configurations

Common schema properties

When you read a prototype’s schema, a handful of properties tell you how to fill in a field. They live under a field’s ui object.

di:type

Marks a field that holds a nested configuration of a given type, rather than a plain value. For example, a field with di:type: subscriber expects a subscriber prototype (inline) or a reference to a saved subscriber. The value is either an inline prototype object or a reference object, as shown in the steps above.

di:allow and di:force

These say whether a di:type field may point at a saved configuration.

di:allow: configuration means a reference to a saved configuration is allowed. Use a reference object { "identifier": "..." }, or inline the prototype if you prefer. The route’s incoming and outgoing fields work this way.
di:force: configuration means the value must be its own saved configuration, referenced by identifier. Every transformers array uses this: create a standalone list-transformer line and reference it. Inline objects are accepted by the importer but render poorly in the dashboard.

ui:supportsPlaceholders

Marks a field that accepts a placeholder. For example &{id}. See Placeholders.

ui:patterns

Marks a field that uses path patterns to select or write data. For example products.*.sku. See Patterns.

Templates

Import & Export

Packages

Example configurations

Object structure

Step by step

ULIDs

Finding configuration types and schemas

Search for prototypes of a type

List saved configurations

Common schema properties

di:type

di:allow and di:force

ui:supportsPlaceholders

ui:patterns

​Object structure

​Step by step

​ULIDs

​Finding configuration types and schemas

​Search for prototypes of a type

​List saved configurations

​Common schema properties

​di:type

​di:allow and di:force

​ui:supportsPlaceholders

​ui:patterns

Object structure

Step by step

ULIDs

Finding configuration types and schemas

Search for prototypes of a type

List saved configurations

Common schema properties

di:type

di:allow and di:force

ui:supportsPlaceholders

ui:patterns