Skip to content
Local environment Preproduction — not production data

Tracking imports into Factorial

An App that imports data into Factorial — payroll results from a payroll provider, expenses from a card provider, vendors from an ERP — can track every import as an integrations-framework sync run. Each run has one row per imported record, and each row ends as success, invalid or failed, with a message. The customer sees in Factorial what was imported, what was not and why, instead of an import that fails silently.

It is the inbound counterpart of the integrations framework: the same runs, rows and statuses, in the other direction (external system → Factorial), and the same building blocks in base-integration-app.

For the data model behind runs and rows, see the Factorial inbound integrations docs.

Use it when your App writes records into Factorial on behalf of an external system and the customer should see the result: a payroll results import, an expense import, a scheduled poll that creates records…

The records must be of a type Factorial tracks as inbound sync rows. Today that is compensations, expenses, finance vendors and financial documents, and employee updates.

  • Your App sends data from Factorial to an external system: that is the integrations framework.
  • Your App doesn’t write into Factorial at all: reports, notifications, read-only automations.

An importing App needs the Integrations-framework app type: that is what makes it inherit base-integration-app when the App is created. An App created without it can’t open sync runs: ask your Factorial contact to move it onto the integrations framework. They also give the companies that installed it before the move what they are missing, so those companies don’t have to reinstall it.

  1. Fetch — the App reads the external system. No run should be opened when there’s nothing to import.
  2. Open the run — optionally linked to what it imports into (for example a payroll run).
  3. Declare every row as running, before reporting any outcome: Factorial closes a run as soon as no row is left running.
  4. Import and report — each record is written into Factorial and its row reported as soon as it settles, so the customer sees the import progress.
  5. Finish — rows that were never reported are failed, so the run always closes. If the import breaks halfway, the run is cancelled instead.

Only one run per company and integration can be open at a time. What to do when one is already running — tell the user, retry later, abort the old one — is your App’s decision.

StatusMeaning
runningDeclared, not finished yet
successWritten into Factorial, linked to the record it created
invalidA data or setup problem the customer has to fix (a missing mapping, a bad value)
failedAnything else; it may work next time

Write the messages for an end user: Factorial shows them to the customer.

You don’t call the sync-run API by hand. base-integration-app ships two modules, in JavaScript and Python:

  • inbound-record-sync — the InboundRecordSync base class. Your App extends it, says what it imports, and implements two hooks: fetch the items from the external system and write one item (or a batch) into Factorial. The base class runs the whole import: it opens the run, declares the rows, reports each result and finishes the run. It is the inbound twin of the outbound record-sync.
  • inbound-sync — the InboundSyncClient underneath: open, declare, report, finish and abort runs, and list an integration’s runs. Use it directly for what the base class doesn’t cover, for example a form that opens the run and hands it to a background worker, or aborting open runs when the App is uninstalled.

An App created with the Integrations-framework type inherits base-integration-app from the start (see Workspace hierarchy).

The walkthrough — a complete import, a bulk write, the form-and-worker hand-off, and the gotchas — is in the fcode-examples skill: inbound import reference. Your agent reads it through the AI skills.