transform

The transform service uses special JSON files to define a transformation (which can have multiple steps) on the JSON input data sent to the service. In the user interface the transform service is shown as a tree of JSON transform files which you can create, edit and delete. Reading and writing these files is done with GET and PUT requests. To use the service to transform a JSON data object, POST the object to the url of a transform file and the transformed data is returned.

JSON transform specification

A one-step transform is a JSON object which defines a transformation from input data to output data (both also JSON). The transform object's keys each generate a key with the same name on the output object. The values of these keys are used to generate the values for the output keys. Each value can be a sub-object, a string, or an array.

  • object: this is a transform object which is applied to the input object to get the output value
  • string: this is an expression which is evaluated in terms of the properties of the input object and the value assigned to the property in the output object
  • array: an array represents a function call like this: [ <function name>, <function arg 0>, <function arg 1>, ... ].

If the key is $this, where the normal behaviour would be to assign the generated value to a key $this on the output object, instead the generated value's properties are all added to the output object. This is done before any other key values on the transform object are applied to the input object, which means that the other key values will if the key already exists, overwrite the value of that key on the output object.

A special property $requests is used on the transform object to allow for the results of requests to be added into the transform. The value of $requests is an object, with keys and values where the value is a request spec (see request specs). For each one the request specified is executed, and a new property is added to the output at the top level whose key is the key of the request spec, and whose value is the result of the request. In evaluating the request spec, the context uses the url on which the transform was called, and the current input object for the data argument if one is given.

Responses with JSON data are parsed and the object resulting is used as the value. With text data, the text as a string is the value. For binary file data, the file is encoded to a Base 64 string and this string is the value.

Failed requests result in no corresponding keybeing added to the output object.

Expressions

Expressions are evaluated by using the BCX Expression Evaluator  package. This is a safe expression evaluator which allows you to use Javascript expression syntax. In these expressions, all properties of the input object can be referred to by name (and subproperties using normal JS dot notation). Also you can use most built-in JS functions with some significant exceptions:

  • Function literals are not supported
  • new is not supported
  • references on empty values return undefined not an error
  • regular expressions are not supported
  • typeof, instanceof and delete are not supported.

Partly to overcome some of these limitations, you can use certain special functions provided by the service as below.

Special functions

In these function which apply to lists, the expression takes each list item as an input and can refer to its properties, $this meaning the whole list object. Furthermore you can also refer to properties of the outer input item.

  • expressionFilter(list, expression): filters the list to items where expression evaluates to true.
  • expressionFind(list, expression): return the first item in the list where expression evaluates to true.
  • expressionMap(list, expression): apply the expression in order to each list item and return the list of outputs.
  • expressionReduce(list, init, expression): apply the expression to a context made from the union of the properties in the current value (which is init initially) and the current list item to get the next current value, then return the final current value.
  • expressionSort(list, expression, [direction]): apply the expression to each list item and sort based on comparison of the expression's result. Optional direction argument if 'desc' makes the sort descending.
  • transformMap(list, object): recursively uses the object given as a transform script to apply to each item in list and return the output in the same order.
  • pathPattern(pattern): resolve the url pattern given against the url on which the service was called and the input data.
  • newDate(args...): call date constructor to create a date value using the arguments given. If you supply a single string argument, this will use moment.js to parse the string.
  • formatDate(date, format): the optional format argument is a date formatting string in the syntax used by moment.js. It has an extra format 'forQuery' which returns a date literal for OData queries.

You can call the functions like a normal Javascript function in an expression string, or using an array of function name and arguments, which can simplify issues with string escaping which can get very involved otherwise.