Directives Toolkit Reference

Declarative instructions used inside recipes to reshape and normalize JSON nodes.

Directives Summary

Directive Type Purpose Target Scenarios
alterKey string Renames the source key in the output JSON. Converting uppercase enterprise keys to camelCase/idiomatic names.
transform object Nests transformation directives for child objects or arrays. Drilling down through nested collections (vouchers, inventory, batches).
valueKey string Unwraps a child property from an object, flattening it into a scalar. Extracting #text from XML text wrapper objects.
valueType "array" Guarantees output is wrapped in an array, even if input is a single object. Normalizing single-element collections into reliable arrays.

1. alterKey: Renaming Fields

Renames incoming enterprise property names into clean API property names on the output object:

// Recipe
{
  "transform": {
    "STOCKITEM": { "alterKey": "stockItems" }
  }
}

// Input:  { "STOCKITEM": [...] }
// Output: { "stockItems": [...] }

2. transform: Nested Tree Traversal

Instructs the engine to descend recursively into child structures. When an incoming node is an object or array of objects, transform defines what to alter inside those children:

// Recipe
{
  "transform": {
    "STOCKITEM": {
      "alterKey": "items",
      "transform": {
        "NAME": { "alterKey": "name" },
        "BASEUNITS": { "alterKey": "units" }
      }
    }
  }
}

3. valueKey: Unwrapping XML Text Objects

XML parsers often produce nested text wrapper objects like { "#text": "Main Location", "@_TYPE": "String" }. valueKey extracts the inner value directly:

// Recipe
{
  "transform": {
    "GODOWNNAME": {
      "alterKey": "location",
      "valueKey": "#text"
    }
  }
}

// Input:  { "GODOWNNAME": { "#text": "Main Location", "@_TYPE": "String" } }
// Output: { "location": "Main Location" }

4. valueType: "array": Collection Normalization

XML parsers output a plain object when there is only one child tag, but an array when there are multiple child tags. valueType: "array" enforces array output:

// Recipe
{
  "transform": {
    "BATCHALLOCATIONS.LIST": {
      "alterKey": "batches",
      "valueType": "array",
      "transform": {
        "BATCHNAME": { "alterKey": "batchNumber" }
      }
    }
  }
}

// Input:  { "BATCHALLOCATIONS.LIST": { "BATCHNAME": "B-01" } }
// Output: { "batches": [ { "batchNumber": "B-01" } ] }
← Previous: Overview & Story Next: Enterprise Cookbook →