Label Workflow Element

The Label Workflow Element streamlines the implementation process by eliminating the need to instantiate individual elements (Purchase Label, Shipment Summary, Void Label).

Under the hood, using a shipmentId, salesOrderId, or externalShipmentId the Label Workflow Element will check for labels and determine which step of the label purchase process needs to be displayed.

NOTE:

If any labels (active or voided) correspond to the provided ID, the Shipment Summary Element will be displayed.

If a salesOrderId is provided, the Label Workflow will first check for the corresponding shipments. While ShipEngine Sales Orders have a one-to-many relationship with Shipments, the Label Workflow is designed to handle only one Shipment at a time. If you plan to use the Label Workflow Element with Sales Orders, we recommend that you limit one Shipment to each Sales Order. Initially, the workflow will search for shipments with a status of pending indicating that these shipments are eligible for purchase. A new shipment will be created if one cannot be found using the provided salesOrderId.

Check out the shipment documentation to learn more about Shipments and their statuses.

NOTE:

It is recommended to initialize a workflow Element as a whole; however, all nested Elements can be instantiated individually.

To hydrate the Label Workflow Element with shipment data, you can provide a salesOrderId, shipmentId, or externalShipmentId; a new shipment will be created as a side-effect if a salesOrderId is provided. Check out the Sales Order documentation to learn more about making a sales order.

NOTE:

If you are using Sales Orders and created them with either externalOrderId, externalOrderNumber, or orderSourceCode, you can use that to hydrate the Label Workflow Element.

React Component

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
import { LabelWorkflow, ElementsProvider } from '@shipengine/elements';
import { themeConfig } from '../themeConfig';

const tokenPath = '/path/to/token/endpoint';

const Foo = ({ shipmentId }) => {
  const getToken = useCallback(() => {
    return fetch(tokenPath).then((res) => res.text());
  }, []);

  return (
    <ElementsProvider
      getToken={getToken}
      themeConfig={themeConfig}
      onError={handleError}
      features={{
        globalFeatures: {
          // The list of all ShipEngine carriers available to be activated
          enabledShipEngineCarriers: ['ups', 'stamps_com'],
        },
        purchaseLabelFeatures: {
          rateForm: { enableFunding: true },
          shipmentForm: { shippingPresets: true },
        },
        shipmentSummaryFeatures: {
          schedulePickup: true,
        },
      }}
    >
      <LabelWorkflow.Element
        multiplexedId={shipmentId}
        onLabelCreateSuccess={() => console.log('Label Purchased!')}
        onViewShipment={() => console.log('go to shipment summary.')}
        onVoidLabelSuccess={() => console.log('Label Voided!')}
      />
    </ElementsProvider>
  );
};

SDK

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
// Creates a new instance of the Elements SDK.
const elements = new ElementsSDK(getToken, {
  onError: (err: Error) => console.error(err),
  themeConfig: themeConfig,
  locale: 'en-US',
  features: {
    globalFeatures: {
      // The list of all ShipEngine carriers available to be activated
      enabledShipEngineCarriers: ['ups', 'stamps_com'],
    },
    purchaseLabelFeatures: {
      rateForm: { enableFunding: true },
      shipmentForm: { shippingPresets: true },
    },
    shipmentSummaryFeatures: {
      schedulePickup: true,
    },
  },
});

const labelWorkflow = elements.create('labelWorkflow', {
  multiplexedId: {
    shipmentId: 'se-4352331',
  },
  onViewShipment: () => console.log('go to shipment summary.'),
  onVoidLabelSuccess: () => console.log('Label Voided!'),
  onLabelCreateSuccess: () => console.log('Label Purchased!'),
});

The Label Workflow takes all of the Props/Arguments that the Purchase Label, Shipment Summary, and Void Label Element with a few minor adjustments. First, rather than individually accepting each shipment entity ID, the Label Workflow accepts a multiplexedId prop containing any ShipEngine entity IDs used to associate shipments. Second, to provide some differentiation between props, the void label callback was renamed to be more conspicuous. Lastly, the features props of each Element are combined into a single features prop.

Features

Features are optional configuration keys used to customize the label workflow experience. Any features in the Label Workflow Element will override what is set in the features prop/argument within the ElementsProvider or ElementsSDK constructor. We recommend setting these within the feature prop/argument within the ElementsProvider or the ElementsSDK class constructor.

Callbacks

WARNING:

The callbacks prop has been deprecated as of Elements version 2.15.0. The Label Workflow has been updated to directly accept all the props available on each of the individual Elements (Purchase Label, Shipment Summary, and Void Label Element), including those previously available in the callbacks prop.

Multiplexed ID