enableCustomMapping - hotglue Docs

Getting Started

Call enableCustomMapping to turn on the custom mapping UI for one or more connectors. The function accepts an array of connector settings and/or flow schemas.

<script src="https://hotglue.xyz/widgetv3.js"></script>
<script>
  const hotglue = new Hotglue({
    tenantId: '<your-tenant-id>',
    environmentId: '<your-environment-id>',
    apiKey: '<your-api-key>',
    jwt: '<tenant-jwt>'
  });

  hotglue.enableCustomMapping(['shopify', 'stripe', 'hubspot']);
</script>

Source to Target Custom Mapping Demo

Input formats

enableCustomMapping accepts EnableCustomMappingInput[]. Each item is either a connector setting or a flow schema.

Format	Shape	Use when
Catalog (Beta)	Connector ID string, e.g. `'shopify'`	Source tables and fields come from the connector’s discovered catalog. Available only for v2 flows.
Schema	`{ flowId, schema }`	You define the source tables and fields programmatically.

You can pass both formats in the same call. Connector settings and schemas are stored separately: connector IDs replace the connector list, while schemas are merged by flowId.

Catalog format

Pass connector IDs to enable custom mapping using the connector’s source catalog as the left (source) side of the mapping UI.

The catalog format is in Beta and works only with v2 flows. The flow must have a valid discovered catalog in v2_source; otherwise, the widget cannot populate the source tables and fields.

hotglue.enableCustomMapping(['shopify', 'stripe']);

Custom mapping is shown for a linked connector when its ID is in this list, the active flow is a v2 flow, and v2_source contains a valid discovered catalog.

Schema format

Pass a schema object to define your app’s source tables and fields at runtime. Your schema appears on the left (source) side of the mapping UI. The widget still fetches the connector’s catalog for the right (target) side. For more on schema structure, see custom field mapping.

hotglue.enableCustomMapping([
  {
    flowId: '40bZe-8xV',
    schema: [
      {
        table: 'customers',
        fields: [
          { id: 'id', name: 'Id' },
          { id: 'email', name: 'Email' },
          { id: 'first_name', name: 'First Name' },
          { id: 'last_name', name: 'Last Name' },
        ],
      },
      {
        table: 'orders',
        fields: [
          { id: 'id', name: 'Order Id' },
          { id: 'total_price', name: 'Total Price' },
          { id: 'created_at', name: 'Created At' },
        ],
      },
    ],
  },
]);

React example

import { useHotglue } from '@hotglue/widget';

const { enableCustomMapping, openWidget } = useHotglue({
  tenantId,
  environmentId,
  apiKey,
});

enableCustomMapping([
  {
    flowId: 'flow_123',
    schema: [
      {
        table: 'Leads',
        fields: [
          { id: 'first_name', name: 'First Name' },
          { id: 'last_name', name: 'Last Name' },
          { id: 'email', name: 'Email' },
        ],
      },
    ],
  },
]);

openWidget(tenantId);

Schema-based custom mapping does not require a v2 flow. If a schema is registered for the active flow, the mapping tab is available even when the flow version is not v2.

Combining catalog and schema

hotglue.enableCustomMapping([
  'shopify',
  {
    flowId: '40bZe-8xV',
    schema: [
      {
        table: 'customers',
        fields: [
          { id: 'email', name: 'Email' },
        ],
      },
    ],
  },
]);

Sample mapping output

After saving their mapping, the following field is added to the tenant’s tenant-config.

"hotglue_mapping": {
  "mapping": {
    "dynamics-bc": [
      {
        "source": "Supporters",
        "target": "Account",
        "fields": {
          "first_name": "FirstName",
          "last_name": "LastName",
          "email": "PersonEmail"
        }
      },
      {
        "source": "Contributions",
        "target": "GiftTransaction",
        "fields": {
          "givecloud_hgexid": "GiveCloud_Gift_Transaction_ID__c",
          "contribution_number": "Name"
        }
      }
    ]
  }
}

With the schema format, source values match the table names you passed in schema, and field keys in fields match the id values you defined.

​Getting Started

​Input formats

​Catalog format

​Schema format

​React example

​Combining catalog and schema

​Sample mapping output

Getting Started

Input formats

Catalog format

Schema format

React example

Combining catalog and schema

Sample mapping output