Description

The useHotglue is the primary way of using the @hotglue/widget package outside of the inline Connections component. Use this to launch the widget and access utility functions.

Usage

First you must include the HotglueConfig provider as a higher order component in your React app. For example, in index.js:

index.js

import React from 'react';
import ReactDOM from 'react-dom';
import App from './App';
import HotglueConfig from '@hotglue/widget';

ReactDOM.render(
  <HotglueConfig
    config={{
      apiKey: 'your-public-environment-api-key',
      envId: 'your-env-id'
    }}
  >
    <App />
  </HotglueConfig>,
  document.getElementById('root')
);

Then you can use the useHotglue hook anywhere, as shown below:

App.js

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

const App = (props) => {
   const { openWidget } = useHotglue();

  return (
    <div>
        <button onClick={() => openWidget('test-user')}>Open</button>
    </div>
  );
};

export default App;

Functions

Below is a reference of all of the currently supported functions from the useHotglue hook.

openWidget

Opens the widget for a user with options.

Usage

HotGlue.openWidget(user id, options)

Parameters

Name	Type	Description
user id	`string`	ID of current user of your application.
options	`objects`	option objects

link

Usage

HotGlue.link(user id, flow id, source, preloaded, options)

Parameters

Name	Type	Description
user id	`string`	ID of current user of your application.
flow id	`string`	ID of flow you wish to connect. Every flow in hotglue has an ID which can be found from the admin panel or API. source
source	`string`	ID of source you wish to connect – typically just the name of the source in lowercase. Full catalog is accessible via API. Ex. `salesforce`
preloaded	`boolean`	Mark this flag as `true` if you used the `HotGlue.preload` function to improve load time. Defaults to `false`
options	`object`	Object containing options to configure the form: `json { "helperText": "Need help finding credentials? [Read the docs](https://docs.hotglue.xyz)" }`

Description

If specified source is not linked, this will open a popup window for user to login If specified source is linked, this will open the hotglue widget under specified flow so user can manage the source.

reconnect

Usage

HotGlue.reconnect(user id, flow id, entity id, options)

Parameters

Name	Type	Description
user id	`string`	ID of current user of your application.
flow id	`string`	ID of flow you wish to reconnect. Every flow in hotglue has an ID which can be found from the admin panel or API. source
entity id	`string`	ID of source or target you wish to connect – typically just the name of the source in lowercase. Full catalog is accessible via API. Ex. `salesforce`
options	`object`	Object containing options to configure the form: `json { "isTarget": false }`

Description

Used to reconnect an OAuth entities. Note for non-OAuth sources or targets, this will have no effect. In order to reconnect a target, you must pass the isTarget parameter to the options object.

disconnect

Usage

HotGlue.disconnect(user id, flow id, entity id, options)

Parameters

Name	Type	Description
user id	`string`	ID of current user of your application.
flow id	`string`	ID of flow you wish to disconnect. Every flow in hotglue has an ID which can be found from the admin panel or API.
source
entity id	`string`	ID of source or target you wish to disconnect – typically just the name of the source in lowercase. Full catalog is accessible via API. Ex. `salesforce`
options	`object`	Object containing options to configure the form: `json { "isTarget": false }`

Description

Used to disconnect an entity (source or target). Note you must pass the isTarget parameter to the options object if disconnecting a linked target.

setListener

Usage

HotGlue.setListener(listener)

Parameters

Name	Type	Description
listener	`object`	Object containing all listeners. See list of available events here. ex. `{onSourceLinked: (source, flow) => console.log(JSON.stringify(source))}`

Description

Updates current listener configuration to specified listener object

createJob

Usage

HotGlue.createJob(flowId, tenantId, startDate)

Parameters

Name	Type	Required	Description
`flowId`	`string`	Yes	ID of flow
`tenantId`	`string`	Yes	ID of user
`startDate`	`string` (ISO date)	No	Optional. Used to override start date of the job. ex: `2022-10-16T00:00:00Z`

Response

Returns a Promise which must be awaited or assigned a callback to extract relevant data

JSON

{
    "job_id": "lmaEbA",
    "env_id": "dev.example-env.hotglue.xyz",
    "job_name": "test_job:_V-vgdlLN",
    "tenant": "default",
    "started_by": "default",
    "flow": "l8odS2mce",
    "s3_root": "default/flows/l8odS2mce/jobs/lmaEbA",
    "start_time": "2020-12-30T18:01:01.828266+00:00",
    "state": {},
    "tap": "quickbooks:sandbox",
    "status": "ETL_FAILED",
    "message": "ETL error...",
    "last_updated": "2020-12-30T20:31:00.081282+00:00"
}

Description

Convenience function wrapping the hotglue API to run a job for the user.

close()

Usage

const { link, close } = useHotglue()

function onClick() {
  link(tenantId, flowId, sourceId, false, {
    hideBackButtons: true,
    listener: {
      onSourceLinked: () => {
        close();
      }
    }
  })
}

Description

Closes the hotglue widget.

setOptions

Usage

const { setOptions } = useHotglue()

setOptions({
  hideBackButtons: true,
  listener: {
    onSourceLinked: (source, flow) => console.log('Source linked!')
  }
})

Parameters

Name	Type	Description
options	`Options`	Object containing widget configuration options. See available options for complete reference.

Description

Updates the current widget configuration with new options. This function allows you to widget behavior globally. The options object can contain any of the supported widget configuration parameters.

Available Options

The options parameter accepts an object with the following properties:

Option	Type	Description
`hideBackButtons`	`boolean`	Hides back buttons in the widget. Useful for preventing users from navigating away from specific flows.
`listener`	`object`	Object containing event listeners. See listener options for available events.
`multipleSources`	`boolean`	Allows tenants to connect multiple distinct connectors in the same flow.
`flow`	`string`	Opens the widget directly to a specific flow instead of showing the flow list.
`flowFilter`	`function`	Function to filter which flows are displayed.
`localization`	`object`	Object containing text overrides for widget UI elements.
`createMetadata`	`object`	Object containing metadata to be created with new connections.
`customFieldMapping`	`object`	Object containing custom field mapping configuration.

Example

const { setOptions, openWidget } = useHotglue()

// Configure widget options
setOptions({
  hideBackButtons: true,
  multipleSources: true,
  flow: "h8Dksj2",
  listener: {
    onSourceLinked: (source, flowId, tenantId) => {
      console.log(`Source ${source.name} linked to flow ${flowId}`)
    },
    onWidgetClose: () => {
      console.log('Widget closed')
    }
  },
  localization: {
    startingScreen: {
      header: "Connect Your Data",
      subtitle: "Choose your integration below"
    }
  }
})

// Open widget with the configured options
openWidget('user-123')

setSchema

Usage

import { useHotglue } from '@hotglue/widget'

const { setSchema, openWidget } = useHotglue()

const schemas = [
  {
    flowId: 'flow_123',
    schema: [
      {
        table: 'Leads',
        fields: [
          { id: 'first_name', name: 'First Name' },
          { id: 'last_name', name: 'Last Name' },
          { id: 'email', name: 'Email' }
        ]
      }
    ]
  }
]

setSchema(schemas, { enforceOneToOneMapping: true })
openWidget('user-123')

Parameters

Name	Type	Description
`schemas`	`Array<Schema>`	Array of flow-level schema definitions. Each item includes `flowId` and a `schema` array with `table` and `fields` (`id`, `name`).
`options`	`SchemaOptions`	Optional behavior overrides for mapping. Currently supports `enforceOneToOneMapping` (`boolean`).

Description

Enables the custom mapping component and sets the source schema for the widget at runtime when using @hotglue/widget in React. Use this to define the fields your users map from before opening the widget. When enforceOneToOneMapping is true, each source field can only map to one target field, preventing duplicate mappings in the UI. For full schema structure details, see custom field mapping.

​Description

​Usage

​Functions

​openWidget

​Usage

​Parameters

​link

​Usage

​Parameters

​Description

​reconnect

​Usage

​Parameters

​Description

​disconnect

​Usage

​Parameters

​Description

​setListener

​Usage

​Parameters

​Description

​createJob

​Usage

​Parameters

​Response

​Description

​close()

​Usage

​Description

​setOptions

​Usage

​Parameters

​Description

​Available Options

​Example

​setSchema

​Usage

​Parameters

​Description

Description

Usage

Functions

openWidget

Usage

Parameters

link

Usage

Parameters

Description

reconnect

Usage

Parameters

Description

disconnect

Usage

Parameters

Description

setListener

Usage

Parameters

Description

createJob

Usage

Parameters

Response

Description

close()

Usage

Description

setOptions

Usage

Parameters

Description

Available Options

Example

setSchema

Usage

Parameters

Description