The Gloop map step is used to set variable values and to declare new variables. There are two ways to set a variable in a map step:
- A map line
- A set expression
When a map step is chosen in the service editor, the Mapper view in Martini will show all of the available input and output variables. This is where you declare and map variable values, and add set expressions.
To map a variable, or in other words, assign the value of a variable to the value of another, simply drag and drop a variable to another as shown below:
The line in the GIF above is the same as the following code:
To delete a line, first click on the line to highlight it, then press or right click on the line and select Delete.
If the value of a variable is to be hardcoded, or requires some more advanced logic in order to set its value (such as performing lookups, or some sort of transformation, etc.), you can use a set expression instead of a map line.
When adding a set expression, you have the option whether to write it as code, or use a plain hardcoded string. When the set expression is plain text, then the expression itself is used as the value of the variable. When a code language is used, then the set expression is executed at runtime, and the output of the code snippet is used as the value of the variable.
Set step guidelines
Set expressions have no limit on how much code you can write, so you can (in theory) write dozens of lines of code in a set expression; however it's bad practice to do so. Instead, you should use a script step, script service, or write a reuseable Groovy class.
To add a set expression to a variable, you can:
- right click on a variable in the output half of the Mapper view, and then select Add Set Expression;
- double click a variable from the Mapper view;
- select the variable and then press ; or
- use content-assist while focused on the variable
Here's how to add an expression via a double click:
The (Groovy DSL) set expression provided in the demonstration above is the same as the following code:
1 2 3 4 5 6
The Set Expression dialog has the available Gloop properties in a tree on the right hand side. If you double click on a variable in the tree while editing your expression, the code for accessing the variable is inserted into the set expression at the location of the cursor. Focus is kept on the script editor even when double clicking so the code can continue to be edited without having to manually put focus back on the editor.
Set Expression dialog
The Set Expression dialog is very similar to the script step editor, which you can learn about here.
Inserting property expressions on the fly
If you wish to insert a property path and surround the path with
}, hold down whilst
double clicking. You can also use the context menu when you right click on the tree,
and then select 'Insert Property Path in Template String'.
If you wish to insert a property path with Groovy's safe navigation operator
? as well, hold down
whilst double clicking. You can also use the context menu when you right click on the tree,
and then select 'Insert Property Path with Safe Navigation'.
These operations can also be used to replace existing content in the code text area. Simply select/highlight the text you wish to replace prior to using the menu or shortcuts to insert the path.
To delete a set expression, right click on the variable and choose Delete Set Expression, or highlight the variable, and press .
Accessing the entire Gloop variable context
Set expressions also have a variable called
$context included, which is actually a Gloop model
that contains all of the variables that you see in the Mapper!
Map line and set expression priority
You may have noticed in the screenshots above that the Set Expression dialog has a Priority field. This field is used to determine the order in which the map lines and set expressions are executed. This allows you to map the same fields more than once in the same step. Take the following map step for example:
If all the lines in this example had the same priority, then there will be no guarantee on the order in which the lines were executed. Thankfully with the priority feature you can safely determine the order.
Map steps execute map lines and set expressions which have the lowest priority number first. This means that if the lines were configured like so:
Then it would be the same as the following Java code:
1 2 3 4
Priorities for map lines can be configured by clicking on the line itself (in the Mapper area in the middle) until it
is highlighted, then changing the value of the
Priority field in the Properties view.
Errors in set expressions
If your set expression throws an exception (regardless whether it was from a syntax error or not), Gloop will
produce a standard Gloop stacktrace, but with an extra suffix telling you the line number where the error occurred in
your set expression, and which set expression it was. For example, given the error below, the set expression at
message threw an exception at line 6:
The second line in the stacktrace tells us the name of the service that threw the error, which step, and which specific line number.
Here is a screenshot showing the set step:
Errors in set expressions
Exceptions are thrown at runtime if your set step has a syntax error. Like any other exception, they will be
caught by any parent block step with a
Gloop lets you declare variables in a map step. Similar to Java, variables have a concept of scope, meaning that if you declare a variable in a nested block step, then its parents will not see the declared variable. In Martini, there are four ways in which you can declare a variable:
- The context menu of the Mapper view's Output side
- Hotkeys (e.g. will declare a new string);
- Pressing the full-stop key, which will bring up the content-assist feature (unsupported by Martini Online)
- Dragging and dropping a model from the Navigator view to the Mapper view
Gloop also lets you remove declared variables once you're finished with them. This feature is useful in helping keep the Mapper view in Martini nice and clean, and also makes Gloop code easier to read. When a variable is unloaded, it will not show in the Mapper for any steps after the step that has unloaded it. To unload a declared variable, right click on it, then select Unload Property, or press .
Rules for declaring and unloading variables
Gloop lets you declare and unload variables in map and invoke steps only.