Working with data

The basic interface

In many steps you will see an interface like this. It’s for specifying where to store or retrieve a value.

The several drop down boxes each mean different things, but all of them are still quite related as you may find out in the advanced section

First drop-down: Container

In the first box you can choose from a set of containers for storing and retrieving values:

• input: arguments passed to the Task
• output: returned on Task completion
• session: values that you wish to be available in all Tasks (not reset between runs)
• system: runtime values, currently only has a location key containing the current URL
• temp: starts empty every time and is never returned

The data browser at the bottom left of the builder reflects the values in each container as they were at the end of the last Task execution.

Second drop-down → Keys

You can choose from a list of keys (names for the value) that were defined in the Template, or you can name values as you please.

Generally the Template will provide all the names which external programs using the connector will expect in the output container and all the input they may pass in.

Third and fourth drop-downs → Records

Some templates may specify a key which refers to a list of records. In the search template that ships in our default configuration there is only one: “results”. The third drop down allows you to apply a step to a particular field in every record within such a key.

The fourth and final dropdown is for lists within each record. The search template defines the key “item” here to refer to holdings records containing the location, availability, etc.

Record lists are currently only populated by the XPattern step.

Appending, Concatenating and Replacing

When configuring the target for a step to write to you will notice three radio buttons providing options for how to handle any values already at that key.

• append: leave existing values and add the new one to the end of the list
• concatenate: append the new value to the end of the string in the target key
• replace: replace any existing value with the one generated by the step. If the step would produce an empty result the key will be deleted.

In-line value replacement.

Many steps will accept a reference that will be replaced with whatever data is currently in the specified location. To distinguish this from the rest of the string you use the unlikely {$ combination, like so: {$.container.key}. For example, you could configure Go to URL with a URL of “http://www.site.tld/sections/{$.input.database}” and the last part of the URL would be replaced by the parameter passed in as “database” when the Task is run. This shorthand will only take the first value in any given array. To display all values (for example, a list of authors delimited by semicolons), use the Join step to concatenate them together into one string in the temp container.

Advanced mode

Behind the scenes the steps find the values to run with by generating a JSONpath query from your step configuration. When you click on the “Advanced” button it switches to an interface that expresses your setting as a JSONpath that matches a set of objects and the key to operate on. For more information, see this guide.