Input and Output Mappings

TABLE OF CONTENTS

• Mapping Interface Overview
• Input Mapping
  • Input Mapping Example
• Output Mapping
  • Output Mapping Examples

Input and Output mappings are part of configuring an External API Data set. They let you transform data between your app and an external API, giving you more control over what gets passed into an API call and how the response is interpreted by your app. This is especially useful when the API expects parameters or returns data in a format that doesn’t align with your app’s structure.

These mappings become available in the Add new data set dialog for External API data sets after you select the Source.

Mapping Interface Overview

When mapping is enabled:

• The left side of the dialog represents the structure visible to your app.
• The right side represents the structure expected by (input) or returned from (output) the API.

You define how values are mapped between these two sides.

Input Mapping

Input mapping is used to transform the data passed into the API call so it matches the format or structure the API expects.

To configure input mapping:

1. Toggle Remap input parameters to enable input mapping. 
2. Once enabled, the screen shows:
   Data set inputs (left): the structure visible to your app.
   API input parameters (right): the structure expected by the API.
   
3. For each input field on the left, enter the Input field, select its Location in app (where in your app the data comes from) and Requirement. 

Use Add field to add more input fields or the recycle bin icon to remove a field.

4. For each field on the right (API input parameter), use the Location in data set inputs dropdown to specify how the API field gets its value from the data set inputs. Available options:
   None – No mapping; the field will not be passed to the API.
   Field mapping – Select a specific field from the data set inputs.
   Expression – Enter a Mustache expression referencing data set input fields.
   Function – Write a custom JavaScript function (click Edit code).

Input Mapping Example

Scenario: Your App collects a user’s first name and last name as separate fields (firstName and lastName fields), but your API expects a single fullName parameter in the URL, for example: http://myapi.com/user?fullName=JohnSmith.

Solution: You can apply an Expression mapping that combines the two fields: {{firstName}}{{lastName}}. This expression concatenates the firstName and lastName values into a single fullName parameter for the API request.
 

Output Mapping

Output mapping is applied to the data returned from the API to transform it into a structure your app can use.

To configure output mapping:

1. Toggle Remap output schema to enable output mapping. 
2. Once enabled, the screen shows:
   Data set outputs (left): the structure visible to your app.
   API response schema (right): the structure returned by the API.
   
3. On the left, set Output data type (Text, Number, Date, Boolean, or Object) for the entire response.
4. Enable the Array toggle if the response returns a list of values.
5. For Mapped by, choose one of the following options (available options vary depending on the Output data type selected):
   None – No mapping; the field will not receive or send any value.
   Field mapping – Allows to select a specific field from the API.
   Expression – Allows to enter a Mustache expression referencing API fields.
   Function – Allows to write a custom JavaScript function (click Edit code) to perform more complex logic. You can reference API fields.
   Children – Available when the output data type is set to Object. Allows you to map each child field individually. Once selected, you can configure the child fields by clicking the Edit attribute icon next to the field.
   
   Note: When a parent object is already mapped, child fields may show a read-only Parent value displayed in the Mapped by dropdown. This option is informational.

Output Mapping Examples

Example A: Renaming a field

Scenario: The API returns a field named firstName, but the app expects a field named userLabel.

Solution: You can add a new field and name it userLabel. Next, set Mapped by to Field mapping and select firstName.
As a result, the value from the firstName field returned by the API will appear in your app as userLabel.

Example B: Combining fields with an expression

Scenario: The API returns firstName and lastName as separate fields, but your app expects a single field called label.

Solution: You can add a new field and name it label. Next, set Mapped by to Expression and enter: {{firstName}} {{lastName}}. This expression concatenates the API’s firstName and lastName fields into a single label field for your app.