Integration setup: endpoints, flows, mappings, schedules and monitoring

#Purpose and scope

The Integration Hub moves data between BSuit and other systems. This chapter covers setting up the connection, the flow that moves data, mapping, scheduling, inbound credentials and day-to-day operation. The whole module is for administrators; it has no approval workflow.

#Before you start

1. Get the partner’s URL, authentication method and credentials. Prefer secret references or let BSuit encrypt typed secrets; secrets are encrypted at rest and masked when shown.
2. Know the BSuit entity the flow reads or writes, and its field names.
3. For inbound writes into a company-scoped entity, plan a constant company_id mapping. Without it the write is rejected rather than saved without a company.

#1. Create an endpoint

1. Start from Connectors: choose Install on a template to create a starter endpoint, then add credentials to finish. Or add an endpoint directly in Endpoints.
2. Set code, name, direction (inbound or outbound), type, base URL, authentication, timeout, retry count, SSL verify and Active.
3. For OAuth 2.0 choose Client Credentials or Authorization Code and fill token URL, client id, client secret, scope and, for authorization code, authorization URL and redirect URI. The list shows OAuth status as not connected, expired or connected.
4. For SFTP and file-drop endpoints put the settings in the connection configuration JSON, using secret references rather than raw passwords.

#2. Create a flow

1. Use Flow templates for ERP, EDI and file flows: pick a template, choose an endpoint and a flow code. It creates an inactive flow with its field mappings; replace placeholder values and review before activating.
2. Or create one in Flows: code, name, direction, endpoint, connector, entity type, trigger (Manual, Scheduled, Event or Webhook), trigger event, request method and path, batch size and Active.
3. Optionally choose a canonical payload schema (Order, ASN, Shipment Status, Invoice, Inventory Snapshot or Master Data) so payloads are validated.
4. For inbound flows the form shows the ingress URL plus a static ingress key and an HMAC secret.

#3. Map fields

1. In Field mappings choose the flow, then add rows with source field, target field, transform, transform config, default value, required and order.
2. Without mappings the raw payload is sent unchanged. If a required field has no value after the default, the whole item fails rather than writing part of it.

#4. Schedule, receive and notify

1. In Schedules pick a flow, enter a five-field cron expression (for example 0 2 * * *) and a time zone (default UTC). There is one schedule per flow.
2. Webhooks defines incoming or outgoing webhooks with URL, secret key and an events filter. Outgoing webhooks are signed when a secret is set and retried on temporary failures.
3. API keys generates a key with name, endpoint, scopes and expiry. The full key is shown once only; afterwards just the prefix is kept.
4. Alerts notifies the addresses in Notify Emails when a failed log entry matches an active alert.

#5. Operate the queue

1. Queue shows flow, entity, event type, status, attempts and priority. A worker takes pending items about every 30 seconds.
2. A failed attempt is retried with a growing delay until the maximum attempts (3 by default) is reached; the item then moves to Dead Letter.
3. In Dead letter queue choose Replay for one item, Replay all (optionally for one flow) or Discard, which marks the item cancelled.
4. Logs records each dispatch with direction, status, method, URL, status code and duration. Reconciliation shows queued, sent, acknowledged and failed items per flow and day for the last 7, 14, 30 or 90 days.

#Other reference screens