Manage a custom integration in Settings

A custom integration connects Flowstate to another system through that system's API. A scheduled sync from your HR system runs as one; see Connect your HR system. Your technical team writes small pieces of code, called hooks, that pull data into Flowstate or push changes out. This page covers setting one up and running it in Flowstate. For writing the code, see Custom integrations for developers.

Custom integrations are switched on per organisation. If you can't find Custom Integrations in the catalog, ask your Flowstate contact. You also need permission to create and update integrations.

Create an integration

1. Go to Settings → Integrations and select Browse catalog.
2. Open Custom Integrations and select Connect. If your organisation already has one, the button says Configure.
3. Select Create Integration.
4. Enter a Name and, if you like, a Description.
5. In Source System Key, enter a short identifier for the other system, such as workday. Flowstate uses it to recognise that system's records on every run, and you can't change it later.
6. Select Create.

Done when: the integration's page opens, with Credentials and Hooks sections.

Edit, switch off or delete an integration

On the integration's page, or on its row in the Custom Integrations list, select ⋯, then:

• Edit to change the Name or Description, then Save.
• Disabled to switch it off, or Enabled to switch it back on. While it's switched off, none of its hooks run on a schedule or react to changes.
• Delete to remove it. Its hooks and credentials are deleted too, and this can't be undone.

Store credentials

Keep API keys, tokens and passwords here rather than in the code.

1. Under Credentials, select Add Credential.
2. In Key, enter a name in capitals with underscores, such as API_KEY.
3. In Value, paste the secret.
4. Select Save.

Done when: the key is listed. The value is never shown again. The Accessor column shows how the code reads it; select it to copy.

To change a secret, for example when you rotate a key at the other system:

1. Select the pencil icon on its row. Edit Credential opens.
2. Paste the new Value. The Key can't be changed.
3. Select Save.

Hooks use the new value from their next run. To delete a credential, select the bin icon on its row, then Delete.

Create a hook

1. Under Hooks, select Create Hook.
2. Enter a Hook Name.
3. Choose a Hook Type: Pull brings data into Flowstate on a schedule. Push sends changes out when something changes in Flowstate.
4. Choose an Entity Type, such as Employee or Project.
5. Select Create.

Done when: the hook is listed under Hooks. Select its row to open the hook editor.

You can't change a hook's type or entity type later.

Write and save the code

The editor opens with a starting template for the hook's type and entity. Your technical team writes the code there. See Writing hooks.

1. Edit the code.
2. Select Save Code.

The number at the top right, such as v2, goes up each time the code changes. You can rename the hook in the bar at the top, then select Save Code.

Test with a dry run

A dry run runs the code as it is in the editor, even if it isn't saved, and writes nothing to Flowstate.

1. Select Test (Dry Run).
2. Check the result on the tabs beside the editor:
   • Console shows the hook's log messages, any error, and how many records it processed.
   • Preview shows what a real run would create, update and remove, including any teams, projects or job roles it would create.
   • HTTP Log lists each request the hook made, with its method, address, status and duration.

Choose when it runs

For a pull hook:

1. Open the Settings tab.
2. Turn on Run on schedule.
3. Choose an Interval, from Every 15 minutes to Daily. For Daily, choose a Preferred hour.
4. Select Save Code. It saves the schedule too.

Last pulled at shows when it last brought data in.

For a push hook:

1. Open the Settings tab.
2. Under Event types, tick Create, Update and Delete as needed.
3. Select Save Code.

Turn a hook on or off

1. Use the switch at the top of the hook editor, labelled Enable Hook or Disable Hook.
2. When turning it on, select Enable Hook to confirm.

Once it's on, a pull hook runs on its schedule and a push hook reacts to changes.

Run a pull hook now

1. Select Save Code if you've changed anything.
2. Select Trigger Now.

This is a real run: data is written to Flowstate. The run appears on the Execution History tab.

Check each run

Open the Execution History tab. Each run shows its Status (Running, Completed or Failed), Triggered By (Scheduled, Manual, Event or Test), Duration, Records and Started At.

The Hooks list on the integration's page shows each hook's Last Run.

If something's not right

I can't find Custom Integrations in the catalog. They aren't switched on for your organisation. Ask your Flowstate contact.

"Key must use UPPER_SNAKE_CASE". Use capital letters, digits and underscores only, starting with a letter, such as API_KEY.

The dry run worked, but nothing changed in Flowstate. Dry runs never write data. Select Trigger Now, or turn on Run on schedule and turn the hook on.

Trigger Now ran the old code. It runs the saved code. Select Save Code first.

A push hook doesn't react to changes. Check it's turned on, has at least one event type ticked, and that the integration isn't switched off.

A run failed with "A record with this … already exists in your organisation". The hook tried to create a record that already exists. Your technical team should match existing records by those fields in the code.