hale»studio comes with a set of pre-defined transformation functions that cover most basic mapping cases. If you need other functionality the easiest way is to define a custom function directly in hale»studio. In a custom function you can use Groovy to determine the output, based on input and parameters, similar to the Groovy script function. The main difference to the Groovy script function is, that with a custom function you create something that is reusable, reducing the effort in creating and maintaining mappings that require a common functionality not covered by the standard functions.
Custom functions are stored in the alignment, and thus in your mapping project. This means that when you share your project, the custom functions you defined are included. In the future we plan to support sharing your functions easily for others to use, and easily discovering functions that may be useful for your mapping.
Right now custom functions are only supported for property relations, and the only way to define them is via Groovy. We are keen to hear your ideas and needs regarding custom functions and their use, and where you see possibilities for improvement.
To create a custom function, you need to access the Transformation menu as follows:
You need to specify an identifier and a name for your function. The name will later be shown when selecting the function for a mapping. The identifier serves as a unique identifier for referencing your function in the alignment.
The input for your function will come from source schema elements that are associated to the function with a mapping cell. Similarly the output will be placed in a target property that is the target of the mapping cell.
Before defining how your function is executed you need to define what kind of inputs you expect and what kind of output you will produce.
For every input you define you need to specify a name, that allows you to reference the input in the script. Each input can be configured with the type of value you expect to handle, either a simple type like String, or a complex type from the schema.
The Min, Max and unbounded settings control if an input can be connected to several different schema elements. Enabling the input to be eager on the other hand allows the function to consume all instances of an individual source property associated to that input (e.g. for aggregation).
A function may have only one output. Specify the type of result that you want to produce, either a simple value like a String or a complex object based on a type defined in the target schema.
Defining function parameters is not yet supported via the user interface. We plan to add this functionality in one of the next releases. Advanced users may define parameters by adapting a function's XML definition.
The next step is to define the behavior of the function with a Groovy script. The inputs you defined are available as variables here, and the result of the script is used as output.
To learn more on how to use Groovy for defining a custom function, please take a look at the Groovy script function documentation.
hale»studio generates an explanation for mapping cells that reference specific transformation functions. As a last step you have the opportunity to specify how this explanation is created for your custom function.
The explanation can be a fixed text, or it can be a template that creates different output depending on source, target and parameters defined in the mapping cell.
To support both text and HTML explanations with a single template, hale»studio provides Markdown support using the pegdown Markdown processor.
To render the template hale»studio uses the GStringTemplateEngine. The variables available to you in the template are the following:
_params provides an accessor to function parameters.
A parameter named
NAME
can be accessed with
_params.NAME
. If the parameter may occur more than once, the value yielded is a
list (which may be empty). Otherwise the value is the configured
parameter value, the default value for the parameter, or
null
.
positions in
the example above). Associated inputs are retrieved as a list if the
input can occur more than once.
