In this article

Overview

Use this Snap to transform incoming data with the specific mappings and produce new output data (binary or document). The Mapper Snap evaluates an expression and writes the result to the target path. Use the Views tab to specify error handling if an expression fails to evaluate. 

note

Pass Binary Data

  • To convert binary data to document data add the Binary-to-Document Snap upstream of the Mapper Snap. Similarly, add the Document-to-Binary Snap downstream of the Mapper Snap to convert the document output to binary data.

  • You can also transform binary data to document data in the Mapper Snap itself with the $content expression. 

Binary Input and Output

  • If you only work with a binary stream as both input and output, you must set both source and target fields with $content, then use the Expression Builder to manipulate the binary data. If you do not specify this mapping, then the binary stream from the binary input document passes through with no change.

Pass Binary Data

  • To convert binary data to document data add the Binary-to-Document Snap upstream of the Mapper Snap. Similarly, add the Document-to-Binary Snap downstream of the Mapper Snap to convert the document output to binary data.

  • You can also transform binary data to document data in the Mapper Snap itself with the $content expression. 

Binary Input and Output

  • If you only work with a binary stream as both input and output, you must set both source and target fields with $content, then use the Expression Builder to manipulate the binary data. If you do not specify this mapping, then the binary stream from the binary input document passes through with no change.

Snap Type

The Mapper Snap is a Transform-type Snap that transforms data and passes it to the downstream Snap.

Support for Ultra Pipelines

Works in Ultra Pipelines.

Limitations

Snap Views

Type

Format

Number of Views

Examples of Upstream and Downstream Snaps

Description

Input 

  • Document

  • Binary

  • Min: 0

  • Max: 1

Binary-to-Document

This Snap can have at most one document or binary input view. If you do not specify an input view, the Snap generates a downstream flow of one row.

note

By default, the Input type is Document. You can select Binary type if your input is in Binary format.

By default, the Input type is Document. You can select Binary type if your input is in Binary format.

Output

  • Document

  • Binary

  • Min: 1

  • Max: 1

Any Document Snap

This Snap has exactly one document or binary output view.

note

By default, the Output type is Document. You can select the Binary type to view the output in the Binary format.

By default, the Output type is Document. You can select the Binary type to view the output in the Binary format.

Error

Error handling is a generic way to handle errors without data loss or Snap execution failure. You can handle the errors that the Snap might encounter when running the pipeline with one of the following options from the When errors occur list under the Views tab. The available options are:

  • Stop Pipeline Execution: Stops the current pipeline execution when the Snap encounters an error.

  • Discard Error Data and Continue: Ignores the error, discards that record, and continues with the remaining records.

  • Route Error Data to Error View: Routes the error data to an error view without stopping the Snap execution.

Learn more about Error handling in Pipelines.

Snap Settings

  • Asterisk (*): Indicates a mandatory field.

  • Suggestion icon ((blue star)): Indicates a list that is dynamically populated based on the configuration.

  • Expression icon ((blue star)): Indicates whether the value is an expression (if enabled) or a static value (if disabled). Learn more about Use Expressions in SnapLogic.

  • Add icon ((blue star) ): Indicates that you can add fields in the field set.

  • Remove icon ((blue star)): Indicates that you can remove fields from the field set.

Field Name

Field Type

Description

Label*

Default Value: Mapper
Example: Extract Employee Data

String

The name for the Snap. You can modify this to be more specific, especially if you have more than one of the same Snap in your pipeline.

Null-safe access

Default Value: Deselected
Example: Selected

Checkbox

Select this checkbox to set the target value to null if the source path does not exist. For example, $person.phonenumbers.pop() ->$ lastphonenumber might result in an error if person.phonenumbers does not exist in the source data. But, when you select this checkbox, the Snap does not display an error. Instead, it writes null to lastphonenumber
If you deselect this checkbox, the Snap fails if the source path does not exist. The Snap either ignores the entire record or writes the record to the error view (based on the setting of the error view field).

Pass through

Default Value: Deselected
Example: Selected


Checkbox

Select this checkbox so the Snap passes all the original input data into the output document with the data transformation results.

If you deselect this checkbox, only the data transformation results in the mapping section appear in the output document and the input data is discarded.

This setting is impacted by Mapping Root. If Mapping Root is set to $ and Pass through is deselected, anything not mapped in the table does not pass through. However, if Mapping Root is set to $customer and Pass through is deselected, it only applies to the items in the Mapping Root level. That means that anything above the Mapping Root level passes through and items at the Mapping level that are not mapped in the table do not pass through. 

Always select Pass through if you plan to leave the Target path field blank. Otherwise, an error displays to indicate that the field you want to delete does not exist. This is the expected behavior.

For example, if you have an input file that contains a number of attributes and you need only two of these downstream. To accomplish that:

1. Connect a Mapper Snap to the downstream Snap.

2. List the two attributes you need in the Expression fields,

3. Leave the Target path field blank.

4. Select Pass through.

When you execute the pipeline, this Snap evaluates the input document/binary data, extracts the two attributes that you want, and passes the entire document/binary data through to the Target schema. From the list of available attributes in the Target Schema, the Mapper Snap picks up the two attributes you listed in the Expression fields, and passes them as output. However, if you do not select the Pass through checkbox, the Target Schema would be empty, and the Snap displays the No schema available error.

Transformations*


Use this field set to configure the settings for data transformations.

Mapping Root

Default Value: $
Example: $

String/Suggestion

Specify the subsection of the input data to map.  Learn more: Understand the Mapping Root.

Input Schema

Dropdown list

Select the input data (from the upstream Snap) that you want to transform. Drag the item you want to map and place it under the Mapping table.

Sorted

Default Value: Selected

Checkbox

Select this checkbox to sort the input schema and the target schema. The sort options are:

  • All: Sorts both mapped and unmapped data.

  • Mapped: Sorts only the mapped data.

  • Unmapped: Sorts only the unmapped data.

Mapping table*

Use this field set to specify the source path, expression, and target path columns used to map schema structure. The mapping table makes it easier to:

  • Determine which fields in a schema are mapped or unmapped.

  • Create and manage a large mapping table through drag-and-drop.

  • Search for specific fields.

Learn more: Use the Mapping Table.

Expression*

Default Value: N/A
Example: $first.concat(" ", $last) 

String/Expression

Specify the function to use to transform the data. For example, combine, concatenate, or flatten. Expressions that are evaluated replace the source targets at the end of the pipeline runtime.

The data from previous undefined Snaps in the Mapping Table pass through the Data Snap to the next Snap. However, when you define output fields in the Target Path, and if the field name is the same as a field name that would otherwise pass through, the field in the mapping table overrides the output. 

Learn More: Understand Expressions in SnapLogic and Use Expressions for usage guidelines.

When you work with upstream numeric data, you might see some unexpected behavior. For example, consider a mapping that reads as follows:

Expression: $num +100
Target path: $numnew

Now, the value passes from upstream for $num is 20.05. You expect the value of $numnew to now be 120.05. However, when you execute the Snap, the value of $numnew is shown as 20.05100.

This happens because, as of now, the Mapper Snap reads all incoming data as strings, unless they are specifically listed as integers (INT) or decimals (FLOAT). So, to ensure that the upstream numeric data is appropriately interpreted, parse the data as a float to convert the numeric data into a decimal, and all calculations on the upstream data in the Mapper Snap work as expected:

Expression: pareFloat($num1)+100
Target path: $numnew

The value of $numnew shows 120.05.

Target path

Default Value: N/A
Example: $FirstName

String/Suggestion

Specify the target JSON path where the value from the evaluated expression is written. For example, after evaluation of the $person.firstname expression, the Snap inserts the firstname for the person object.

Target Path Recommendation

Iris simplifies configuring the Target path property in this Snap with suggestions for the Expression and Target path fields mapping. To make these suggestions, Iris analyzes Expression and Target path mappings in other pipelines in your Org and suggests the exact matches for the Expressions in your current pipeline. The suggestions display when you click the Suggestion (blue star) icon in the Target path. 

For example, you have the Expression $Emp.Emp_Personal.FirstName in one of your pipelines. You set the Target path for this expression as $FirstName. Now, if you use the expression $Emp.Emp_Personal.FirstName in a new pipeline, then Iris recommends $FirstName as one of the Target paths to help you standardize the naming standards in your org.

The following shows how Iris recommends the Target path in a Mapper Snap:

Snap Execution

Dropdown list

Select one of the three modes in which the Snap executes. Available options are:

  • Validate & Execute: Performs limited execution of the Snap, and generates a data preview during pipeline validation. Subsequently, performs full execution of the Snap (unlimited records) during pipeline runtime.

  • Execute only: Performs full execution of the Snap during pipeline execution without generating preview data.

  • Disabled: Disables the Snap and all Snaps that are downstream from it.

Input and Output Preview

The Input Schema of the Mapper Snap displays the input strings from the upstream Snap. On validation, the Input Preview displays the preview of the input from the upstream Snap, and the Output Preview displays the output preview that passes to the downstream Snap. The following elements are available in the input and output previews:

Number

Element

Description

1

Expand All

Expands the objects in the Input/Output.

2

Collapse All
Collapse Level

Collapses the objects in the Input/Output.
Collapses the level of objects from 0-2 or All.

3

Render whitespace

When you select this checkbox, the blank spaces (leading, trailing, or in the middle of a string) in an expression field renders as symbols in the output:

  • Each blank space renders as a dot (“.”) in the output.

  • Each tab renders as an underscore ( _ ) in the output.

When you deselect this checkbox, the Snap renders blank spaces and tabs as-is. By default, the Render whitespace checkbox is selected.

4

Download

Downloads the JSON file.

Data Output Example

Successful Mapping

If your source data looks like

And your mapping looks like

Your output data will look like

{
  "first_name": "John",
  "last_name": "Smith",
  "phone_num": "123-456-7890"
}  
  • Expression: $first_name.concat(" ", $last_name)

  • Target path$full_name 

{
  "full_name": "John Smith",
  "phone_num": "123-456-7890"
} 

Unsuccessful Mapping

{
  "first_name": "John",
  "last_name": "Smith",
  "phone_num": "123-456-7890"
}  
  • Expression$middle_name.concat(" ", $last_name)

  • Target path$full_name 

An error displays.

Mapper Examples


Watch the Data Mapper in Action

The Data Mapper

 Best Practices: Data Transformations and Mappings


Related Content