Using custom script transformations#
Introduction#
- What are custom script transformations and what can they do?
A custom script transformation is made up of one or more versatile instructions that tell Adverity how to transform your data. You can use custom script transformations to add or remove fields from your data, perform calculations, convert data, and much more.
- How do I use custom script transformations?
Create a custom script transformation as described in this guide. Transformations can be assigned to multiple datastreams. Every time you fetch data using the datastream the transformation is assigned to, the collected data is transformed according to the instructions in the transformation.
Note
Use Adverity’s AI-powered Transformation Copilot to create custom script transformations quickly and easily. For more information, see Using the Transformation Copilot.
- Who can use a transformation that I create?
A transformation is available to all users with access to the workspace where the transformation was created. However, the transformation will only affect datastreams to which it is assigned.
- What instructions can I add to a custom script transformation?
You can add as many instructions as you want to a custom script transformation and configure the settings for each instruction individually. You can find a list of all available custom script instructions here.
- What other transformation types are there in Adverity?
Adverity also offers standard transformations, which provide a user-friendly interface that lets you tell Adverity how to transform your data within a certain framework. For more information, see Using Adverity’s standard transformations.
Creating a custom script transformation#
The process of creating a custom script transformation is made up of the following steps:
Type: Choose to create a custom script transformation.
Assignments: Choose the datastreams to which you want to apply the transformation.
Instruction: Create the custom script transformation by adding and configuring instructions so that it transforms your data according to your needs.
Name: Give your custom script transformation a name so it is easily identifiable.
Prerequisites#
Before you complete the procedure in this guide, perform all of the following actions:
Creating a custom script transformation#
To get started creating a transformation, follow these steps:
Go to the Transformations page.
In the top right corner, click + Create transformation.
In the Type step, click Custom script.
This guide only explains how to create a custom script transformations. To create a standard transformation, see Using Adverity’s standard transformations.
In the Assignments step, select the datastreams to which you want to assign this transformation:
To assign the transformation to one or more specific datastreams, select Individual datastreams and then select your chosen datastreams from the drop-down menu.
To assign the transformation to all datastreams that fetch data from one or more specific data sources, select Datastream types and then select your chosen data sources from the drop down menu.
(Optional) To exclude any datastreams that fetch data from your chosen data source, select the individual datastreams to exclude from the Do not assign to these individual datastreams drop-down menu.
In the Instruction step, in the Select instruction drop-down menu, enter and select an instruction for this transformation.
Use the Transformation Copilot to get the transformation instruction and its configuration for your specific use case. For more information, see Using the Transformation Copilot.
(Optional) Use the comment field below the instruction dropdown to describe what the instruction does. Comments stay visible when an instruction is collapsed (see Collapsing and expanding instructions below), so they help you scan a transformation with many instructions at a glance. Click the clear icon in the field to remove a comment.
Configure the settings for the instruction you have selected according to the Copilot’s response or the corresponding instruction guide.
If you change the instruction type after filling in any settings, a confirmation dialog warns you that your settings for the current instruction will be cleared. Changing the type of an instruction that has no settings filled in does not ask for confirmation.
Note
You can preview your transformation in the Preview tab. Here, you can see how your current transformation instructions will transform the data you have previously collected using the selected datastream.
Click Refresh Preview at the bottom of the Instruction tab to see the preview of your latest changes.
If an instruction is invalid, it gets a red border and a badge showing how many errors it has. Clicking Next or Refresh Preview expands any collapsed invalid instructions and scrolls to the first one. The error banner at the top of the Instruction step counts errors across all instructions, including collapsed ones.
For more information about the preview, see Previewing transformations.
(Optional) To add more instructions to this transformation, click + Add instruction and configure the corresponding settings.
Repeat this step until you have finished adding and configuring instructions.
(Optional) To remove an instruction, click its delete button.
If the instruction has a type selected and any data to lose (saved settings, filled-in fields, or a comment), a confirmation dialog names the instruction and asks you to confirm the deletion. Deleting an empty, unconfigured instruction does not ask for confirmation.
Click Next.
In the Name step, enter a name and a description for your transformation.
Click Create.
As a result, you have created a custom script transformation and assigned it to your chosen datastreams. From now on, every time you fetch data using these datastreams, the data extract will be transformed according to the instructions in your transformation.
You can also assign your transformations to a datastream from the datastream overview as well as manage the order in which the transformations are applied.
Collapsing and expanding instructions#
If a custom script transformation has many instructions, or instructions with long forms, collapse them to get a better overview and to make reordering easier with drag and drop.
To collapse or expand a single instruction, click the chevron on its header, or click anywhere on the header that is not a button or field.
To collapse or expand every instruction at once, click Collapse all / Expand all. The button’s label switches depending on whether any instruction is currently expanded.
Instructions are expanded by default. Collapsing only changes how an instruction is displayed — nothing is lost, and expanding it again shows the instruction exactly as you left it, including unsaved edits.
A collapsed instruction still shows its name, a truncated comment, the link to open documentation, the delete button, and the enable/disable toggle, so you can identify, disable, or delete it without expanding it.
While an instruction is collapsed, its type is locked — expand it to change the type. The type remains selectable if no instruction has been picked yet.
Picking a type on an instruction that has none yet opens the instruction and places the cursor in its first field.
Reordering instructions does not change which ones are collapsed.
Instructions added by the Copilot, and any instruction with a validation error, always open automatically.
The collapsed or expanded state of your instructions is not remembered after you leave the page.
Editing a custom script transformation#
You can edit a transformation after it has been created. To do so, follow these steps:
Go to the Transformations page.
Click the transformation you want to edit.
You will automatically be taken to the Instructions page of the transformation overview. Make any required changes to the transformation configuration here.
To change the list of datastreams to which the transformation is assigned, go to the Used by tab.
Click Save.
As a result, you have edited your custom script transformation. From now on, when you fetch data using a datastream to which this transformation is assigned, your data will be transformed according to the new instructions.