Transforms And Templates

This is the Documentation for Snow 0.4, old 0.3 docs can be found here.

Transforms are used by Bip hub objects to map and combine attributes between adjacent nodes. They are a JSON object where the object keys are the named imports of a target node on a hub and the value is the data to inject, evaluated as a text template.

For example if we have an email.smtp_forward node and we want to set two of its imports, subject and body_text. We can inject custom values like so :

{
  "subject" : "You Got Mail!",
  "body_text" : "An important message"
}

Templates can also be interpolated with variables from parent nodes or metadata as JSON Paths if they take the form

[%source.title%]

json_path in the example means the JSON Path of an attribute exported by a parent node, keyed by either an explicit channel UUID, action pointer (email.smtp_forward._0), or source (ie: whatever the bip receives or generates). This means you can concatenate exports and text together to create a custom import. With the previous email example, lets assume we're using an smtp bip and want to pass through some of the details to an email channel on its hub :

{
  "subject" : "[%source.subject%]",
  "body_text" : "I got an email from [%_client.repr%] : [%source.body_text%]"
}

Type Casting

The system will attempt to correctly cast values to their appropriate types during import, immediately after transformation. Type casting is inferred from the manifest.json file for a pod.

Object and Array Passthrough

Transform templates which only include a single JSONPath will be evaluated in-place, meaning that if the path evaluates to an object or array, then it will be replaced with that structured data.

For example, say we have a channel with a json_document import which expects a structured object and you need to map an export object from a complex payload like so (the 2nd object element of an array) :

{
  "374d9a1d-cc84-456d-9dad-e1e3065e8c4d" : {
    "payload" : [
      "Payload Title",
      {
        "name" : "This is the document name",
        "body" : {
          "title" : "Document Title",
          "message" : "Document Body"
        }
      }
    ]
  }
}

It can transformed as :

{
  "json_document" : "[%374d9a1d-cc84-456d-9dad-e1e3065e8c4d.payload[1].body%]"
}

Or to take the previous email forwarder example, we can just keep on drilling into the object to find what we're looking for :

{
  "subject" : "[%374d9a1d-cc84-456d-9dad-e1e3065e8c4d.payload[1].body.title%]",
  "body_text" : "[%374d9a1d-cc84-456d-9dad-e1e3065e8c4d.payload[1].body.message%]"
}

Easy, right?

Bip metadata exports (_bip|_client)

Additional metadata exports are available depending on the type of Bip that is evaluating. These exports are set in _bip and _client exports which can be discovered by calling the /rpc/describe/bip RPC.