Object Mapping Component

The Fusebit Object Mapping Component gives you the capability to provide a custom mapping of fields between a source system (e.g. Salesforce, HubSpot) and your own target system during an installation flow. This makes the process of working with custom objects as part of ETL and other workloads a breeze.

Object Mapping ComponentObject Mapping Component

This Component is part of Fusebit's configuration system, which enables an Integration to collect data from end-users and store it as metadata in your Tenant's Install. Understanding this system is a pre-requisite here, please review Collecting User Configuration before proceeding, as you will need to understand some concepts introduced there.

In this guide, we will walk through the following items:

  • How to display the Object Mapping Component as part of an Integration's install process
  • How to retrieve the mapping and apply the transformation in the Integration code

📘

Get started with a live example

You can get started quickly in the Fusebit Portal by using our Salesforce Object Mapping Integration Template which contains all the pieces packaged together. You can also use our Sample App to see and end-to-end user-facing working example.

Display the Component

There are three distinct controls in the Object Mapping Control, available here on npm:

  • SourceTable which contains sample data to help your Tenant identify the correct fields to map
  • TransformedTable which will display the transformed data to help your Tenant see the final mapping
  • ObjectMap which contains the Target Schema (left) and Source Schema (right) that your Tenant will use to do the actual mapping

UISchema ElementsUISchema Elements

🚧

While all three controls are optional to display, please note that the TransformedTable control requires both ObjectMap and SourceTable controls in order to render and transform the mapping correctly.

To include one or more of these in your Integration's install flow, include a uiSchema.json file similar to the following:

{
  "type": "VerticalLayout",
  "elements": [
    {
      "type": "SourceTable",
      "scope": "#/properties/sourceTable"
    },
    {
      "type": "TransformedTable",
      "scope": "#/properties/transformedTable"
    },
    {
      "type": "ObjectMap",
      "scope": "#/properties/objectMap"
    }
  ]
}

The next step is to describe the source object the Component will be transforming from, and the target object you want as the output of the transformation. This enables the ObjectMap control to correctly render the object fields to allow the end-user to complete the mapping. If you want to enable the user to preview the source and transformed object via the SourceTable and TransformedTable controls, you can optionally provide some sample source data.

We use standard JSON Schema notation to describe these schemas, and they may be readily available as part of the OpenAPI spec of the respective system.

{
  "type": "object",
  "title": "Target Schema Configuration",
  "properties": {
    "ID": {
      "properties": {
        "PrimaryID": {
          "type": "string",
          "label": "ID_One"
        },
        "SecondaryID": {
          "type": "string",
          "label": "ID_Two"
        }
      }
    },
    "ContactName": {
      "type": "string",
      "label": "Name"
    }
  }
}
{
  "type": "object",
  "title": "Source Schema Configuration",
  "properties": {
    "Name": {
      "type": "string",
      "label": "Name"
    },
    "ID_One": {
      "type": "integer",
      "label": "Primary ID"
    },
    "ID_Two": {
      "type": "integer",
      "label": "Secondary ID"
    }
  }
}

{
  Name: 'Daisy Flower',
  ID_One: '1312',
  ID_Two: '9435'
}

As you can see, the target schema has some nested properties as well, which our Component can handle automatically.

The last step is to put everything together in your Integration's integration.js file. Please check this section as below we have omitted some additional required configuration steps. The code below uses the schemas provided as well as the sample source data, as well as a companion utility provided by Fusebit, to render the form.

const { objectMap } = require("@fusebit/objectmap-utils");
const SourceSchema = require('./SourceSchema.json');
const SourceData = require('./SourceData.json');
const TargetSchema = require('./TargetSchema.json');
const uiSchema = require('./uiSchema.json');

const { data, schema } =
    objectMap.createSchema({
      source: SourceSchema,
      target: TargetSchema,
      uischema: uiSchema,
      dataToTransform: SourceData
   });
      
const [form, contentType] = integration.response.createJsonForm({
  schema,
  uiSchema,
  data,
  dialogTitle: 'Map your Objects!',
  submitUrl: 'form/submitted',
  state: {
    session: ctx.query.session,
  },
});
 

Retrieve mapping and apply transformation

The above steps ensured the collection of object mapping data during the Integration install. In this section, we will show you how to execute the transformation at runtime, when data is actually flowing through your Integration.

The mapping configuration can be retrieved from the Install metadata for the Tenant. The transformData method provided by Fusebit's utility package uses the mapping information, along with the source data retrieved by your integration, and outputs the transformed data, as shown below:

const { objectMap } = require("@fusebit/objectmap-utils");

// Retrieve configuration
const configuration = await integration.tenant.getTenantInstalls(ctx, ctx.params.tenantId);

// Retrieve mapping (assuming the component name was 'objectMapping')
const tenantMapping = configuration[0].data.objectMapping;

// Example source data (usually coming from third-party system)
const sourceData = {
  Name: 'Basil Herb',
  ID_One: '1122',
  ID_Two: '7623'
}

const transformedData = objectMap.transformData(tenantMapping, sourceData)
// Output
// {ID.PrimaryID:'1122', ID.SecondaryID: '7623', ContactName:'Basil Herb'}

The transformed objects should be readily consumable by your system, as they will conform to the target schema you provided.