StediDOCS
This product is in Developer Preview

Mappings

Getting Started

Mappings are Stedi’s tool for mapping JSON data from one shape to another, offering developers a visual no-code interface for transforming data with zero programming skills required.

Creating a mapping

Mappings can be created, updated, and tested within Terminal.

Authoring mappings is enabled by a web-based editor that helps you in the process by providing autocomplete, JSONata-driven transformation functions and a visual tree-based document structure representation.

To create a mapping, click on the Mappings tab in the navigation menu. Then, click on the Create mapping button located in the top right corner of the page. After providing a mapping name, you will be redirected to mapping editor page.

You will be prompted to select an example input and output document. Click on the left (input) panel, select an input example JSON document from your local file system, repeat the process for the right (output) panel to choose an output example document. Note that you can use drag & drop to select those files.

Now that you have selected both input and output file, proceed with creating the actual mapping.

To do that, click on Select keys. Next, choose all keys in the output document that you will be mapping values to. You may find the search input handy, especially for large output files.

Note that you don't have to choose all of them (if you do, you may find the Select all option useful) and you may want to e.g. select a single key for the time being to get yourself familiar with the tool.

To include selected keys in the mapping, click on Confirm. You will be presented with the Mapping Editor, where you can map the keys of the input document to the keys of the output document.

Before moving on, consider saving the mapping so you won't need to specify the input and output example documents in the future. Click on Save button in the upper right corner to achieve that.

Tip: You can rename a mapping at any time - to do that click on the pencil icon next to its name.

Mapping editor

After selecting the mapping keys you'll be presented with a Mapping Editor containing one or more rows in a tree-like structure (reflecting the shape of keys in the output document).

Each row consists of two parts:

  • left-hand side: a mapping expression editor
  • right-hand side: a field from the output document, displayed in a tree-like structure reflecting the shape of the output document

As an example, suppose you've chosen a CustomerID field from the output document to be mapped to.

In the mapping expression editor on the left, you can type one of the following:

  • a static string value (e.g. "HELLO WORLD") in order to map CustomerID to "HELLO_WORLD"
  • a static number value (e.g. 1234) in order to map CustomerID to 1234
  • a top-level path from an input document to be mapped to CustomerID. For instance, if input document looks like this:
{
  "UserID": 999,
  "Location": {
    "Country": "USA",
    "State": "Colorado"
  }
}

typing UserID in the mapping expression editor next to CustomerID will allow you to map CustomerID from whatever value is inside of UserID.

Note that if the type of CustomerID and UserID won't match (e.g. when trying to map a number to a string and vice versa), the UI will show a warning (you will be able to save a mapping regardless, but it's definitely something to keep a close eye on).

  • a nested path from an input document to be mapped to CustomerID. Given the same input document:
{
  "UserID": 999,
  "Location": {
    "Country": "USA",
    "State": "Colorado"
  }
}

typing Location.Country in the mapping expression editor next to CustomerID will allow you to map CustomerID to whatever value is inside of Country field inside of Location object. There are no limitations regarding the depth of nesting, for instance given a following input document:

{
  "NestedObjectField": {
    "elements": {
      "Field-01": {
        "value": 1
      },
      "Field-02": {
        "value": 2
      },
      "Field-03": {
        "value": 3
      }
    }
  }
}

you can map from any value in the input document by using the . dot operator, example: NestedObjectField.elements."Field-01".value. Note that a mapping expression needs to be JSONata compatible (more on that in section below), and as such keys with - in them need to be wrapped in quotation marks "".

  • a JSONata expression, read the section below for details.

JSONata expressions

As mentioned earlier, Mappings support writing JSONata expressions in order to allow you to write simple yet powerful expressions with no programming skills required.

JSONata is a lightweight query and transformation language for JSON data and Mappings support every function provided by it. See JSONata docs for a complete list.

A few notable examples of expressions that you may find useful while creating a Mapping:

  • $now() - a function that takes no arguments, returns a current date and time
    • Example: $now() returns 2021-09-30T15:12:59.152Z
  • $uppercase() - $uppercase() is a function that takes a string as an argument and returns an uppercase version of it.
    • Example: $uppercase("stedi") returns "STEDI".
  • condition ? if_true : if_false - Mapping support ternary logical expressions that allow you to create a mapping where the value in the output depends on a condition.
    • Example: Location.Country = "USA" ? "USD" : "EUR will return "USD" when given a {"Location": {"Country": "USA"}} input document and "EUR" if the "Country" value is not equal to "USA".
  • & operator - & allows you to concatenate string values with each other.
    • Example: "Hello," & " " & "world from " & Location.Country" will return a "Hello, world from USA when given a {"Location": {"Country": "USA"}} input document

Note that all functions can be composed with one another to handle all possible mapping logic and business cases.

  • Example: $uppercase("Test" & $number("123")) and more.

Mapping Transformation Editor

As you may have noticed, some mapping expressions are not straightforward. In order to make building complex mapping expressions easier, Mapping editor has a Mapping Transformation Editor which you can access by clicking a green icon next to a mapping expression input.

You will be presented with a modal containing a multi-line mapping expression input (giving you more space to work in, useful for building advanced mappings), as well as a preview of an input document shape and the output of running current mapping expression against the input document. Note that the mapping output box content updates in real-time, allowing you to create and debug complex expressions with ease.

At any time, you may click on a book icon in order to view JSONata function documentation. In order to confirm the newly updated mapping expression, click on Confirm button. Remember to Save the mapping as well.

Test a mapping

At any moment, you can click on Test button in the upper right corner to gain visibility into how the mapping you're working on will transform an input document. After clicking on Test button you will be presented with a modal showing the input document and the output of current mapping. Input document inside of this modal can edited to test your current mapping against different inputs.

In addition to that, once the mapping has been saved, you can navigate to Transform data page to test a mapping with an arbitrary input. In order to do that, select a mapping, copy\\&paste a test file into the editor on the left-hand side, and review the results on the right.

Mapping types

Mappings aim to serve all kinds of potential use cases - as such the UI gives you the ability to change a mapping type. There are three mapping types available:

  • Only mapped keys [default]

    • When creating a mapping from input document to an output document, only the keys from output document example that have been selected for mapping (using the Select keys menu) will be present in the mapping output. Everything else will be disregarded.
    • Example use case: mapping from a large input document (e.g. JSON representation of an EDI transaction - JEDI) to an output document - e.g.customer API shape. A mapping output will contain only the subset of (or all) keys selected from the output document.
  • Merge with output document example

    • When creating a mapping from input document to an output document, the keys selected from the output document example for a given mapping (using the Select keys menu) will be merged with all the other remaining keys in output document example. This type of mapping ensures that the structure of the output document after a mapping operation is consistent with the output document example used to create the mapping.
    • Example use case: mapping from a customer API shape to a JSON representation of an EDI transaction - JEDI. Merge with output document example mapping mode allows for modifying only a subset of all fields in a JEDI document while leaving the rest intact. This eliminates the need for mapping or hardcoding all fields present in the output JEDI document in order to maintain its structure.
  • Pass-through

    • When creating a mapping from input document to an output document, keys present in the input document will be passed through to the output document when:
      • there's a compatible key in the output document (e.g. there's a CustomerID key in both documents)
      • the output document key has not been mapped
    • All other mapping output document keys will be mapped according to the user-defined mapping.
    • Example use case: mapping from mapping from a JSON representation of an EDI transaction - JEDI to another JEDI document. Since both of those documents share the same structure, a pass-through mapping ensures that the mapping output will contain all keys present in an input to a map operation combined with values mapped according to the mapping.

API Reference