Transformers overview

When data is transferred between two systems it is often necessary to transform the data. To accommodate these transformations Alumio uses transformers. Transformers can be configured for subscribers, routes and publishers.

  • Subscriber transformers are used to transform and filter entities that are provided by a subscriber.
  • Route transformers are used to transform and filter entities before tasks are created for them.
  • Publisher transformer are used to transform entities before they are sent to a destination.

To introduce custom transformer logic, a new transformer can be created. It is preferred to first attempt to solve transformations with a new data transformer, then a new entity transformer and as last resort a new transformer.

Entity transformers

When configuring a transformer in Alumio, a transformer type has to be chosen. The following entity transformer types are available in a standard Alumio environment.

When a custom entity transformer is required, a new entity transformer can be created.

Entity data transformer

Transforms data regardless of the entity type. Multiple data transformers and data filters can be added to this this transformer.

Code: data

{
"prototype": "data",
"parameters": {
"transformers": [
{
"prototype": "value-mapper",
"parameters": {
"mappers": [
{
"prototype": "standard",
"parameters": {
"to": 20,
"from": "high"
}
}
],
"accessor": {
"prototype": "key",
"parameters": {
"keys": [
"tax_rate"
]
}
}
}
}
]
}
}

Input:

{
"tax_rate": "high"
}

Output:

{
"tax_rate": 20
}

Entity node transformer

Code: node

Applies data transformations on nodes of the entities. This can for example be used to transform order items of order entities.

{
"prototype": "node",
"parameters": {
"accessor": {
"prototype": "pattern",
"parameters": {
"pattern": "items.*"
}
},
"nodeTransformers": [
{
"prototype": "value-mapper",
"parameters": {
"mappers": [
{
"prototype": "dictionary-map",
"parameters": {
"map": [
[
"low",
6
],
[
"high",
20
]
]
}
}
],
"accessor": {
"prototype": "key",
"parameters": {
"keys": [
"tax_rate"
]
}
}
}
}
]
}
}

Input:

{
"items": [
{
"tax_rate": "high"
},
{
"tax_rate": "low"
}
]
}

Output:

{
"items": [
{
"tax_rate": 20
},
{
"tax_rate": 6
}
]
}

Conditional entity transformer

Code: conditional

Executes a transformer only on the entities that pass an entity filter.

The following transformer will transform the sku property character casing, if the name of the same entity starts with a T.

{
"prototype": "conditional",
"parameters": {
"filters": [
{
"prototype": "value-condition",
"parameters": {
"accessor": {
"prototype": "key",
"parameters": {
"keys": [
"name"
]
}
},
"conditions": [
{
"prototype": "string-match",
"parameters": {
"value": "T*"
}
}
]
}
}
],
"transformers": [
{
"prototype": "value-mapper",
"parameters": {
"mappers": [
{
"prototype": "string-upper"
}
],
"accessor": {
"prototype": "key",
"parameters": {
"keys": [
"sku"
]
}
}
}
}
]
}
}

Entities:

[
{
"sku": "tnt-1000",
"name": "TNT"
},
{
"sku": "timer-1000",
"name": "Timer"
},
{
"sku": "dynamite-1000",
"name": "Dynamite"
}
]

Output:

[
{
"sku": "TNT-1000",
"name": "TNT"
},
{
"sku": "TIMER-1000",
"name": "Timer"
},
{
"sku": "dynamite-1000",
"name": "Dynamite"
}
]

Chain entity transformer

Code: chain

Allows to chain multiple transformers into one.

The following example combines the examples from the node transformer and the conditional transformer.

{
"prototype": "chain",
"parameters": {
"transformers": [
{
"prototype": "node",
"parameters": {
"accessor": {
"prototype": "pattern",
"parameters": {
"pattern": "items.*"
}
},
"nodeTransformers": [
{
"prototype": "value-mapper",
"parameters": {
"mappers": [
{
"prototype": "dictionary-map",
"parameters": {
"map": [
[
"low",
6
],
[
"high",
20
]
]
}
}
],
"accessor": {
"prototype": "key",
"parameters": {
"keys": [
"tax_rate"
]
}
}
}
}
]
}
},
{
"prototype": "conditional",
"parameters": {
"filters": [
{
"prototype": "value-condition",
"parameters": {
"accessor": {
"prototype": "key",
"parameters": {
"keys": [
"name"
]
}
},
"conditions": [
{
"prototype": "string-match",
"parameters": {
"value": "T*"
}
}
]
}
}
],
"transformers": [
{
"prototype": "value-mapper",
"parameters": {
"mappers": [
{
"prototype": "string-upper"
}
],
"accessor": {
"prototype": "key",
"parameters": {
"keys": [
"sku"
]
}
}
}
}
]
}
}
]
}
}

Entities:

[
{
"sku": "tnt-1000",
"name": "TNT",
"items": [
{
"tax_rate": "high"
}
]
},
{
"sku": "timer-1000",
"name": "Timer"
},
{
"sku": "dynamite-1000",
"name": "Dynamite",
"items": [
{
"tax_rate": "low"
}
]
}
]

Output:

[
{
"sku": "TNT-1000",
"name": "TNT",
"items": [
{
"tax_rate": 20
}
]
},
{
"sku": "TIMER-1000",
"name": "Timer"
},
{
"sku": "dynamite-1000",
"name": "Dynamite",
"items": [
{
"tax_rate": 6
}
]
}
]

Entity type setter

Code: type-setter

Sets a new entity type on the entities. This can be used together with data transformers to transform from one entity type to another.

{
"prototype": "type-setter",
"parameters": {
"entityType": "acme-product"
}
}

In the example above, acme-product is the chosen entity type.

Note: The entity type must be registered within Alumio. This will be done by libraries specific to handling that entity type, like a publisher library.

Entity brancher

Code: brancher

The brancher gets nodes from the entities and creates new entities for them. This can for example be used to branch customer entities into address entities.

{
"prototype": "brancher",
"parameters": {
"pattern": "addresses.*",
"entityType": "customer-address"
}
}

Entities:

[
{
"id": 1,
"name": "John Doe",
"addresses": [
{
"address": "1 Unknown st.",
"city": "Nowhere"
}
]
},
{
"id": 2,
"name": "Jane Doe",
"addresses": [
{
"address": "2 Unknown st.",
"city": "Nowhere"
},
{
"address": "3 Random blvd.",
"city": "Nowhere"
}
]
}
]

Output:

[
{
"address": "1 Unknown st.",
"city": "Nowhere"
},
{
"address": "2 Unknown st.",
"city": "Nowhere"
},
{
"address": "3 Random blvd.",
"city": "Nowhere"
}
]

Entity type validator

Code: type-validator

Validates the data according to the entity schema.

This leans on the identifier path of an entity type, to validate that all data required to identify the entity is present.

In the example below, we assume that sku is the identifier for the entities.

{
"prototype": "type-validator"
}

Entities:

[
{
"sku": "foo"
},
{
"stock-keeping-unit": "bar"
}
]

Output:

[
{
"sku": "foo"
}
]