Best practices and tips

This article is part of the Getting Started: Integrations help series.

Good integrations are usually built from a small number of repeatable patterns. A directory synchronization, for example, can retrieve records on a schedule, synchronize them as Bosbec units, update existing units, create missing units, and remove units that are no longer present in the source system.

Use the following practices when designing a workflow. They make the workflow easier to understand, safer to run repeatedly, and simpler to troubleshoot.

Give every part a clear purpose

Use names and descriptions that explain what a job does and why it exists. A name such as Update existing unit is much more useful than job_7 when someone is investigating a failed run.

Use names such as source_records, current_record, matched_unit, and stale_marker to reveal the workflow's stages and make dynamic values easier to recognize in expressions.

Keep each pipeline focused on one operation. For example:

• Retrieve data from the source system.
• Parse the response and save it as a resource.
• Transform the data into the shape needed by the next step.
• Find, update, create, or delete units.

This also makes it easier to test one part without changing the rest of the workflow.

Keep external data in resources

Save important intermediate results as named resources instead of repeating an HTTP request or a long expression. A resource gives later jobs a stable hand-off point and makes the workflow context easier to inspect.

A common sequence is:

1. Send an HTTP request to the source system.
2. Parse the response into JSON.
3. Save the parsed response as a resource.
4. Build smaller resources for the operations that follow.

For collections, use For Each Resource and give the current item a meaningful name, such as current_agent. Do not repeatedly address an entire collection when the operation only concerns one item.

Make synchronization repeatable

An integration should be safe to run more than once. Choose a stable identifier from the source system and use it to find the corresponding Bosbec unit. Phone numbers are one possible identifier when they are normalized consistently; an external customer ID is often even better.

The usual update-or-create pattern is:

1. Look up the source record in Bosbec.
2. Route based on whether a matching unit was found.
3. Update the existing unit when there is a match.
4. Create and save a new unit when there is no match.

Keep the two branches explicit. A Route from metadata job makes the no-match case visible and prevents a failed lookup from silently becoming a duplicate.

Handle removed records deliberately

Updating records that still exist is only half of a synchronization. Records removed from the source system also need a defined outcome.

For a full synchronization, a two-pass approach is useful:

1. Find the units in the target group and mark them with a dedicated stale-record flag.
2. Process every current source record. When a record is found or created, update it and clear or replace the stale marker as appropriate.
3. Find the units that still have the marker and delete or archive them according to the integration's requirements.

This is safer than deleting records while iterating through the source response. It gives the workflow a complete view of the incoming data before cleanup begins. Use a dedicated group or another clearly defined scope so the cleanup cannot affect unrelated units.

Validate data at the boundaries

External systems can return missing fields, unexpected values, empty arrays, or a successful HTTP response containing an application-level error. Validate the response after the request and before writing units.

Useful checks include:

• The response has the expected status and structure.
• The collection exists before starting a loop.
• The identifier needed for lookup is present and normalized.
• Required metadata is available before creating or updating a unit.
• Empty results follow an intentional route instead of being treated as a failure.

When a value is optional, decide whether to omit it, use a default, or stop processing that item. Making this decision explicitly prevents malformed units and confusing downstream errors.

Use groups as clear boundaries

Groups are useful for both organization and safe processing. Save synchronized units to a dedicated group, and use that same group as the scope for update and cleanup operations.

Avoid broad searches when a group, account scope, or other precise filter is available. Narrow scopes reduce accidental changes and make the workflow faster as the account grows.

Make loops and branches easy to follow

Keep the work inside a For Each Resource loop limited to the current item. A readable synchronization loop commonly looks like this:

current item
  -> normalize values
  -> find matching unit
  -> route on match
       -> update existing unit
       -> create new unit

Use descriptions on loop starts, routes, and pipelines to document the decision being made. Keep the success path and the no-match path visually separate in the Workflow Builder.

Design for operations and troubleshooting

Use a trigger that matches the source system's behavior. A scheduling trigger is appropriate for periodic synchronization; a webhook is better when changes must be processed immediately. Keep the trigger configuration separate from the processing logic so the workflow can be tested with another entry point.

When troubleshooting, inspect the workflow in stages: trigger input, HTTP response, parsed resource, loop item, lookup result, and final unit operation. The troubleshooting guide covers the most common configuration problems.

Before going live with a workflow, test at least these cases:

• A valid response containing a new record.
• A valid response containing an existing record.
• An empty response.
• A record with a missing required identifier.
• A source record that was removed since the previous synchronization.
• An HTTP or parsing failure.

Related articles

• Building Your First API explains the basic GET, POST, and DELETE workflow patterns.
• Dynamic data explains how to insert values into strings and job properties.
• Accessing Values Inside JSON Arrays covers nested response data.
• Authentication methods compares common ways to authenticate API requests.
• Integration Examples contains workflows that can be adapted for other systems.

⬅️ Previous