map

Add new values to your data extract using a mapping table and existing values.

This guide explains how to configure the map instruction. To learn about another instruction, go back to the Available custom script instructions overview.

Introduction

Use the map instruction to add new values to a new column in a data extract. The transformation looks at values in a given column, then uses these values to map new values into a new column. The map transformation uses a mapping table to determine what new values to create.

You must create a mapping table before using the map transformation. For more information, see Creating and applying mapping tables.

The Match & Map standard transformation enables you to match and map values in your data extract in a few easy steps, instead of using a custom script. For more information, see Match & Map.

Creating a custom script transformation using the map instruction

To create and configure a custom script using the map instruction, follow these steps:

  1. Create a custom script transformation.

  2. In the Configuration step, select the map instruction.

  3. To configure the custom script instruction, fill in the required fields below, as well as any optional fields you require:

Source field (required)

Enter the name of the column in the data extract that contains the source values. Use regular expressions in the MATCH column of the mapping table to expand the search criteria.

Field name (required)

Enter the name of the new column to be added to the data extract. This new column is populated with the target values.

Mapping (required)

Enter the name of the mapping table to use in the map transformation.

Missing

Select what Adverity does if a value in the data extract is not present in the MATCH column of the mapping table. Select one of the following options:

  • Select ignore to ignore the missing mapping entry and continue with the transformation process.

  • Select create to create a new entry in the mapping table and continue with the transformation. The MATCH column of the new entry is populated with the new value found in the data extract that is missing from the mapping table. By default, the VALUE column is left empty. However, you can enter a value in the Alternative field of the instruction which populates the VALUE column when the create feature is used. For example, if a data extract contains a value not present in the mapping table and the Alternative field contains the text 'Match not found', then the data in the new column is populated with the text Match not found.

  • Select stop to stop the transformation process. A new column is not created in the data extract and an error message is shown in the datastream overview.

  • Select create,stop to populate the new column with the value from the data extract that is missing from the mapping table and stop the transformation process.

Errors

To configure Adverity's behavior when an error occurs during the transformation process, select one of the following:

  • Select ignore to ignore the error and continue the transformation process.

  • Select raise to notify you about the error and continue the transformation process.

Notify

Select this checkbox to send notifications to users subscribed to the Datastream and transformation Issues and Mapping topics. For more information on setting up notifications, see Managing user notifications. Customize the text in the notifications using the Comment field.

Flush table

Select this checkbox to remove all values from a mapping table. Only select Flush Table if a mapping table is to be populated with values from a data extract.

If

Enter a python expression. The python expression looks at each row in the data extract and if a particular row is evaluated as TRUE, then the mapping is applied to that row.

Comment

Enter text to include in the notifications or error messages. The text must be entered as a Python expression. For example, to include the text Cannot find value: [name of value] in Data Extract, enter the following Python expression:

'Cannot find value: %s in Data Extract' %{sourcefield_column_name}

In this example, replace sourcefield_column_name with the name of the column in the data extract that contains the source values. You must contain the name of the column within braces {}.

Alternative

Enter a value to populate the new column of the data extract if a value in the Sourcefield column cannot be matched to a value in the mapping table. The text must be entered as a Python expression. For example, to populate the column with a value Invalid, enter the Python expression 'Invalid'. Alternatively, to populate the column with a value of the column date, enter the expression {date}.

Subtable

Enter the name for a subtable that you want to use within this custom script.

A subtable is a temporary table that only exists for this custom script. You can apply additional instructions within the same custom script to the subtable. However, the subtable cannot be used in any other custom scripts.

If a subtable does not exist for the current custom script, the transformation is applied to the data extract, and the enriched data is output into the subtable. If the subtable already exists for the custom script, the subtable is used as the input for the transformation and optionally as the output.