Dynamic field mapping

Dynamic field mapping enables Embed Partners to configure common recipe use cases to leverage dynamic field mappings between different third-party systems. Dynamic field mappings can be configured by Embedded customers outside of the recipe builder interface, for example, within the partner’s platform. This feature allows end customers to easily map standard or custom fields from a source step to a destination step within a recipe, without interacting directly with the core recipe logic that powers the automation.

FEATURE AVAILABILITY

Contact your Customer Success Manager to start using the Dynamic field mapping feature or to discuss your operational requirements and ask questions.

Dynamic field mapping consists of the following two components:

• Dynamic mapping recipe configuration: This is a toggle within each recipe action step that allows you to enable field mapping for that specific step. You are prompted to select a prior source step from which you can map data. Each action in a recipe can have dynamic mapping configured for all connectors.

Dynamic field mapping in the recipe editor

• Field map schemas and corresponding introspection APIs: A field map schema is the defined user mappings in JSON format. The field map schema is unique to each action step that has dynamic mapping turned on within a recipe. You can use our API endpoints to retrieve field map introspections or schemas for both source and target systems, and update the field map schema. These APIs allow Embed partners to build a unique mapping interface for their product and customers.

Field map schema

Set up Dynamic field mapping

Complete the following steps to set up Dynamic field mapping:

1

Go to your Embed admin workspace if you're using Recipe Lifecycle Management to distribute this recipe to multiple customers, or go to an individual customer workspace, if you're creating a more customer-specific recipe, and create a new recipe.

2

Identify the action step where you plan to apply dynamic field mapping, and click the Use dynamic mapping toggle.

3

Select the prior step you plan to use in the recipe as the Source.

DYNAMIC MAPPINGS OVERRIDE STATIC MAPPINGS

Before you can start the recipe, you must map all required fields for this step. As soon as you set a field map schema, the mappings override any fields statically mapped within the recipe builder during the recipe's runtime.

4

Repeat steps 2 and 3 to add additional dynamic field mapping steps, if necessary. You can view the field map schema for each configured step, including the unique field map ID, which has the latest mappings set by your customers.

You can use field map introspection APIs to build the mapping interface after enabling recipes to use dynamic field mapping.

Roles and permissions

Dynamic field mapping is automatically available to users with a system Admin role. However, if you use custom roles, you must update your roles to add access to this feature.

Required role permissions

API access

You must have access to the following endpoints when building your mapping user experience:

• Field maps introspections in recipe | GET /api/v2/managed_users/:managed_user_id/recipes/:id/field_map_introspections
• Field maps introspection | GET /api/v2/managed_users/:managed_user_id/recipes/:id/field_map_introspections/:id
• Update Field maps introspection | PUT /api/v2/managed_users/:managed_user_idrecipes/:id/field_map_introspections/:id
• Refresh recipe's schema for Field maps introspection | POST /api/v2/managed_users/:managed_user_id/recipes/:id/field_map_introspections/:id/refresh_schema
• Fetch pick_list for recipe's Field maps introspection | POST /api/v2/managed_users/:managed_user_id/recipes/:id/field_map_introspections/:id/pick_list

Required fielding mapping endpoints

We recommend that you update your API client roles that require access to the Dynamic Field Mapping feature to include these endpoints.

ENDPOINTS FOR ADMIN WORKSPACE AND CUSTOMER WORKSPACES

Select all field map introspection endpoints under both Your workspace and Customer workspaces.

Considerations for Dynamic field mapping

You can make adjustments to most types of fields. Refer to the following list for additional considerations when building your mapping experience:

• Complex data structures: We do not support mappings for array fields or complex data transformations.

• Schema integrity: We prevent field mappings that could significantly change the data schema, including fields marked with extends_schema: true. This precaution helps maintain the integrity and stability of your integrations.

• Mapping types: You can set the type of mapping to the following values: map, static, nullify, or skip.

• Decoupled logic: Recipe lifecycle management allows for the export and import of dynamic field mapping configurations. However, the field map schema definition is intentionally excluded from your manifests. Additionally, the Field Map ID remains consistent when importing new versions of a recipe with recipe lifecycle management.

• Audit activity: Updates to field map schemas are reflected within the activity audit page of the current workspace.