TABLE OF CONTENTS

• How It Works
• Configuration Steps
  • Example: Remapping an Array of Objects
  • Example: Building a Simple API Payload

The Data Mapper data set is designed for cases where you need to build a custom output object using data from other parts of your App. It can be useful when working with file uploads or other components that can't send large payloads through JavaScript data sets.

Unlike other data set types, Data mapper outputs are only triggered manually using an Evaluate a data set event handler. 

How It Works

When configuring a Data mapper, you define both the structure of the output and the source of each value. You can:

• Map values from another data set’s output (for example, data returned from an API call).
• Use an expression to fill in the value dynamically.

When working with objects, you can either:

• Map the entire object at once using a parent-level mapping, which automatically marks all children as Mapped by parent.
• Define mappings for each child attribute separately.

For arrays, you can:

• Map the array directly from a data set output.
• Use the Remap children option to reshape each item in the array into a new structure based on your needs.

Note: If you map an entire object but the incoming data doesn’t match the structure you defined, the output will still be generated, but it may not align with the expected format. This is similar to what happens in JavaScript data sets when the returned data doesn't match the defined output structure.

Configuration Steps

1. In the Explorer tab of the Design Editor, select App.
2. On the right side of the page, go to Appearance and Configuration > Configuration.
3. Scroll to the Data sets section and click Add data set.
   
4. Specify the Name for the data set.
5. For Type, select Data Mapper.
6. Select the output data type: Text, Number, Date, Boolean, or Object.
7. Enable the Array toggle if the data set should return a list of values.
8. For Mapped by, select either Data set output or Expression.
   1. For the Data set output, specify the Data set and the Data Path.
   2. For Expression, enter a JavaScript expression that returns the value.
9. If you’re mapping an object:
   1. You can map the entire object at once which will mark the child attributes as Mapped by parent.
   2. You can map each child attribute individually. If the object has child attributes, selecting Children as the parent’s mapping option will unlock individual mappings for each child.
10. If you're mapping an array of objects and have mapped the entire array from a data set output, you'll see an additional option to Remap children. This lets you to:
    1. Map a value directly from the original object.
    2. Use JavaScript to generate new values for each item in the array.
11. Click Add to create a data set.

Example: Remapping an Array of Objects

Suppose you have a data set called getAllUsers that returns an array of user objects. You want to transform each user into a simplified object with only selected fields.

In this example, the Data Mapper is configured to:

• Access the users array inside the API response.
• Remap each user in the array into a new object with two fields:
  • userCity: directly mapped from address.city in the original user object.
  • generatedUserName: created using a JavaScript expression.

Example: Building a Simple API Payload

In this simpler case, the Data Mapper creates a payload object for an API request.

The object includes:

• apiKey: populated using the value of the vApiKey variable.
• fileContent: generated using a mustache expression that selects the first file from the select-files list in a file upload component.