Custom integrations

A custom integration runs JavaScript you write, called hooks, inside Flowstate:

PULL hooks fetch records from another system, on a schedule or on demand, and create, update or delete Flowstate records to match.
PUSH hooks run when a record changes in Flowstate and send the change to another system.

Switched on per organisation

Flowstate switches custom integrations on for each organisation. Ask your Flowstate contact.

Choose an approach

	REST API	Webhooks	Custom integration
Who runs the code	You	You	Flowstate
What you host	A client	An endpoint Flowstate can reach	Nothing
Direction	Your system reads and writes Flowstate	Flowstate notifies your endpoint	PULL: other system to Flowstate. PUSH: Flowstate to other system.
Triggered by	Your code	A change in live data	PULL: a schedule or Trigger Now. PUSH: a change in live data.
Scenarios	Read and write	Events on merge only	PULL writes live data. PUSH runs on merge.
On failure	Your code retries	Not retried	Not retried

Custom integration: the other system has an HTTP API that Flowstate can reach over the internet, the data fits the supported entity types, the volume fits the limits, and you don't want to host a service.
REST API: anything else, including scenarios, entity types hooks don't cover, and volumes beyond the limits.
Webhooks: feeding a service you already run, as changes happen.

Deciding where people data should live and how it should flow: People data. A worked HR system sync: Sync an HR system.

Part	Description
Integration	Credentials and hooks for one other system. Its Source System Key identifies that system, is unique in the organisation, and can't be changed. PULL hooks match records on this key and each record's `externalId`.
Credential	A secret your code reads as `ctx.secrets.KEY`. Stored encrypted. The value isn't shown again after saving.
Hook	A PULL or PUSH function for one entity type. Neither can be changed after the hook is created. A new hook is switched off.
Execution	One run of a hook: status, trigger, duration, record counts, log entries, HTTP requests and any error.

Creating integrations, storing credentials, scheduling and switching hooks on: Manage a custom integration.

Entity type	PULL writes	PUSH receives
`employee`	Employees, with team and project allocations and salary adjustments	Employee changes
`contractor`	Contractors, with team and project allocations and rate adjustments	Contractor changes
`vacancy`	Vacancies, with team and project allocations and who fills them	Vacancy changes
`project`	Projects	Project changes
`team`	Teams, with parent and manager	Team changes
`assignment`	An employee's allocation to a project	Changes to any employee, contractor or vacancy allocation to a team or project
`functional_group`	Areas in the functional structure	Area changes
`functional_position`	Seats in an area	Seat changes
`functional_assignment`	A person's time in a seat	Assignment changes

Fields for each: Data model.

Going over the execution time or memory fails the run.
An HTTP request over the limit, a response over 10 MB, and a key or value over its limit each throw inside your code.
At 100 pages, a PULL run stops with a warning and completes.

PULL hook writes to	Sends webhooks and triggers PUSH hooks
`employee`, `contractor`, `vacancy`, `project`, `team`, `assignment`	No
`functional_group`, `functional_position`, `functional_assignment`	Yes, with `initiator.type` `user` and the integration's creator as `initiator.id`

If a PUSH hook writes to a system that a PULL hook reads, guard against loops for the functional structure.

Write hooks: PULL and PUSH contracts, pagination, schedules, dry runs, examples
Context API: ctx.http, ctx.secrets, ctx.org, ctx.kv, ctx.log, ctx.meta, ctx.event
Data model: fields and matching for each entity type
Sync positions as vacancies: filling, moving and closing positions