FAQ

Roadmap

Yes. Additional user-facing detail for API errors, including request and response information to support troubleshooting, is in active development. Further updates will follow as the work progresses.

What's available today

While that work is underway, the current troubleshooting path:

• Job logs are reachable via the state link in the Latest Execution section, and are downloadable from the log section
• The Execution Steps section shows which step errored, along with details, total runtime, and any parameters included in that step
• Reviewing the parameter values recorded against the failing step is often the fastest way to identify a scoping or filter problem
• For errors originating in the target system, the publisher's own audit or activity log usually holds the rejection detail that isn't yet surfaced in DataBlend

Where a case needs deeper analysis, contact support with the workflow execution ID and the downloaded log.

Where the limits are published

API rate and volume limits are set by each system's publisher and documented in their developer documentation, not by DataBlend. Limits change without notice, so always work from the publisher's current documentation rather than a cached figure.

What DataBlend handles automatically

Optimisation is built into the platform, including:

• Exponential backoff and retry on throttling responses
• Request batching where the target API supports it
• Pagination handling on collection

You do not need to design around these behaviours. They apply by default.

Where publisher limits still constrain your design

Some publishers apply account-level usage limits that no amount of client-side optimisation avoids. Sage Intacct is a common example. Where those apply, the limit is consumed by everything hitting that account, not just DataBlend, so integration design has to account for other consumers too.

Levers available to you, in rough order of impact:

• Run frequency. The largest single factor. Hourly instead of every fifteen minutes is a 4x reduction, and most finance integrations do not need sub-hourly latency. Challenge the requirement before engineering around it
• Narrower collection windows and filters. Fewer records collected means fewer requests, both on the way in and on the way out
• Gate the workflow. Where a run only needs to act on change, collect a minimal dataset first, evaluate it, then enable or disable the remaining steps on the result
• Shared collectors. Collecting an object once and letting several integrations consume it removes duplicated calls against the same endpoint
• Schedule spacing. Stagger workflows hitting the same account rather than running them concurrently, so peaks don't collide

Short answer: no, and that is the correct reason not to use Bookmarks.

Your understanding of the mechanism is accurate. A Bookmark stores state from the last successful collection and uses it to constrain the next one. Collection and delivery are separate steps, and workflow execution is sequential: each step must complete before the next begins, and if a later step fails, earlier steps are not rolled back. So the sequence is: Datablend

• The collector runs successfully and advances its stored value
• A later step fails, or the target rejects some records
• The next run collects from the advanced value, and the affected records fall outside the window permanently

The failure is silent. The workflow reports the error at the time, but every subsequent run completes cleanly while the gap stays open. Nothing surfaces it later.

Bookmarks are a legacy feature and are no longer recommended. The current approach is to control the collection window with a date parameter instead.

Why a parameter solves this

• The window is recalculated from the run date on every execution, rather than advanced by the previous run
• A failed or partially failed run therefore leaves the next window unchanged
• Build deliberate overlap into that window (a rolling 30 days for a daily workflow, not a rolling 24 hours) and the next successful run re-collects and re-delivers anything the failed run missed
• Size the overlap to your tolerance for consecutive missed cycles, not to the minimum that works when everything succeeds

What overlap does and doesn't cover

Overlap is a recovery mechanism, not a substitute for monitoring. It handles a missed cycle. It will not handle a target-side rejection that recurs every run, because the record will simply be re-sent and re-rejected. Pair it with:

• Alerting on workflow execution state so failures are seen, not just logged
• A Data Quality Report to catch counts drifting apart between source and target
• Investigating the rejection cause rather than relying on the next run to clear it

Where sprawl comes from

Workflow-scoped design. Each new integration gets its own collectors, so the same customer, item, or GL object is collected three or four times on different schedules. Two consequences:

• Duplicated collection volume
• The same object holding different values depending on which workflow ran last

The consolidation pattern

Treat collectors as shared, reusable assets rather than workflow components:

• Identify objects collected by more than one workflow
• Build a single collector per source object, writing to a shared schema
• Where a workflow needs a narrower slice, apply that narrowing in the query, not by building a second collector

Then make sure every consumer reads the same collection

Sharing a collector is only half the work. Unless collection is sequenced ahead of consumption, workflows can still read different states of the same object. Two ways to guarantee it, in order of preference:

• Combine workflows that share collectors into a single workflow. Place the Run Collector step at the head, then all dependent query and target steps after it. Sequential execution means every step downstream reads data collected in that same run. This is the cleanest option and the only one that delivers both wins at once — one collector definition and one collection per run.
• Chain the workflows where they must stay separate: different cadences, different owners, or a need for independent failure isolation. Run the shared collector once at the head of the chain and have downstream workflows consume that collection rather than re-running it.

Which to choose

Situation	Approach
Same cadence, combined runtime within timeout	Merge into one workflow
Different cadences, or separate ownership, or failure isolation required	Chain, collector at the head
Neither viable	Shared collector on its own schedule, accept and document the freshness gap

Supporting controls

• Filters on the shared collector must be the union of what every consumer needs, not the intersection. A collector previously filtered to one entity now serving a workflow that needs two will cause that workflow to silently under-report. Widen the collector, narrow in the query
• Be deliberate about Schema Update Type, since multiple queries now depend on that schema staying stable
• Add a Run Credential Test at the start of each workflow. This matters more once merged, since credential failure now stops several integrations rather than one.

Validate before retiring anything

• Run the consolidated collector alongside the existing ones for at least one full cycle
• Compare record counts and control totals
• Add a Data Quality Report against the consolidated collector so drift surfaces on its own
• Retire duplicates only once that comparison is clean

 

These are two separate exercises and should be built as two separate workflows:

• The recurring integration handles everything from cutover forward
• The historical load runs once, then is retired

Serving both from a single workflow is what produces duplicate postings and reconciliation problems later.

Decide what "historical" means for this client

Approach	When it applies	What it requires
Full transactional history	The target needs complete detail, typically because the client will report or audit out of the target	Mechanically identical to the ongoing integration, run once with a date parameter covering the window. Chunk by month or quarter: volume and target API throughput are the constraints
Open items only	Most common for AR/AP cutover, and usually the right default	A status filter on the collector, plus a decision on how partially-paid items are represented
Opening balances only	The legacy system stays available for historical lookup	Summarised balances posted as of cutover; no transactional detail moves. Lowest risk and effort

Which applies is determined by how the target system is configured and how the client expects to use the historical data, not by what's easiest to build.

Establish these before design begins

• The exact cutover date and time, including timezone, mismatches here are the usual cause of gapped or duplicated records
• Whether historical records carry their original dates or post as-of cutover
• Whether the target has open periods for the historical dates
• How records straddling the cutover are treated: created before, modified after. This needs an explicit decision, because a Modified Date filter on the ongoing workflow will pull them in whether or not you intended it

Go-live sequence

1. Freeze the source
2. Run the historical load
3. Reconcile against source control totals
4. Enable the ongoing workflow, date parameter starting at cutover

Reconcile before enabling, not after.

The goal is to collect the smallest dataset that still supports the transformation, using selection criteria that are recomputed on every run rather than carried forward between runs.

Restrict the fields

• Collect only the fields your queries and data targets actually reference
• Fields collected "just in case" persist in the schema and inflate every subsequent run

Restrict the population

• Apply collector filters to limit records by entity, location, status, or dimension
• Filtering at the collector keeps the data out of DataBlend entirely, rather than discarding it later in the query

Restrict the time window

• For transactional or activity data, combine a filter with a date parameter against Created Date or Modified Date
• Example: start of last month through today, rather than the full history of the object

Prefer Relative Date parameters for anything scheduled

Relative Date parameters collect within a relative window such as start of the first quarter through end of the last quarter, rather than fixed Month/Day/Year values. Two reasons this matters:

• The window shifts automatically with each run, so nobody has to update it manually
• Because the window is recalculated from the run date each time rather than advanced by the previous run, a failed run doesn't create a permanent gap

Build deliberate overlap into the window, a rolling 30 days for a daily workflow, not a rolling 24 hours, so the next successful run recovers anything a failed run missed. Size the overlap to your tolerance for a missed cycle, not to the minimum that works when everything succeeds.

Reduce how often collectors run at all

Where a workflow only needs to act when something has changed, structure it as a gate:

1. Collect the minimum data needed to detect change
2. Run a query to evaluate it
3. Use a Boolean parameter to enable or disable the remaining steps based on the result

For example, an invoice workflow collects recent invoice data, checks whether any records are new, then switches the downstream collection and target steps on or off accordingly.

To validate that any of this worked, each workflow execution reports the total amount of data scanned, compare before and after.

Sage Intacct performs mandatory system maintenance every Friday from 7:30 PM to 11:30 PM PST/PDT, during which the system is fully unavailable. When DataBlend attempts to connect during this window, it will exhaust all retry attempts and return the Retry Count: 5 error. This is not a DataBlend issue. Intacct

To resolve this, avoid scheduling workflows during the Friday maintenance window. If a workflow failed during this time, simply rerun it once maintenance is complete. You can confirm Sage Intacct's current status at status.sage.com. Sage

If errors persist outside the maintenance window, investigate your credentials, Web Services authorization, and workflow configuration in DataBlend.

There are 4 options for Webhooks in DataBlend:

• Two specific webhook implementations because they don't match industry standard ones: Hubspot and Intacct.
• The other two options, Standard and Simple, should support >99% of all other systems that can send webhooks.

The main use case for webhooks is to add data to DataBlend when an event occurs in an external system. Events typically mean they should be added to a real time stream since there's no "collection" or boundary for events. The stream can then be processed on a recurring schedule that queries the stream for events that have not yet been "processed", typically a date.

We have investigated this but have constraints due to the nature of connectors. In our current architecture, credentials must be created before they can be associated with a collector or data target, data sources and schemas need to be created before creating a query, collectors and data targets have to be created before adding to a workflow. We also have some security concerns .e.g. How would sensitive data be deployed to another group/environment? How would queries be deployed when they reference schemas in other groups?

We are planning to revisit this and investigate options that may be made available only to implementers (Datablend + Partners) vs end users but unfortunately don’t have anymore details available to share.

For most users, templates are limited to be used in one group. Some Internal DataBlend users are granted the ability to create public templates that are available to all groups. Cross-group templates are difficult due to similar reasons described above.

Primary rationale for not supporting this is risk of easily creating an infinite loop of workflows e.g, Workflow A kicks off Workflow B which kicks off Workflow A again (also deeper where it gets to Workflow Z). However, there is a workaround that can be implemented using tools.
Linking Two Workflows Together

This message is being returned directly by Sage Intacct. It means Sage Intacct is temporarily throttling API traffic because too many requests were submitted in a short period of time. Sage identifies this as a 429 / GW-0010 error, which occurs when an API client reaches its assigned rate limit.

This is not a data validation or mapping issue within DataBlend. DataBlend is making API calls to Sage Intacct using Sage-supported API methods, but Sage controls the rate limits and throttling behavior on the Intacct side.

We recommend reviewing API activity within Sage Intacct to determine whether other connected applications or scheduled processes are contributing to the limit. In particular, please check whether any other integrations, reporting tools, custom scripts, AP/expense platforms, CRM connections, or BI/data warehouse tools are using the same Intacct company or shared Web Services credentials. It would also be helpful to confirm whether any other jobs are running at or near the same time as the DataBlend workflow.

Sage also indicates that throttle limits are tied to the customer’s contracted level of service, so if total API usage across all systems has increased, Sage may need to review whether the current API entitlement is sufficient.

At this point, the next step would be to engage Sage Intacct Support to review the API activity associated with your environment and determine what processes or integrations may be contributing to the throttle limit. Once additional information is available from Sage, we would be happy to review the findings and provide any guidance we can regarding the DataBlend workflow.

If one of the systems in your integration changes its IP address, this won't affect your integration. We use DNS-based routing to connect to servers, so IP address changes are handled automatically.