Staffology HR Integration Set-up Guide

Within Chronicle, we offer the capability of integrating with Staffology HR. This integration pulls employee and absence data from Staffology HR into Chronicle (one-way). 

What is possible with this integration?

• Connect Chronicle to your Staffology HR tenant.
• Import new employees from Staffology HR.
• Refresh existing employee records from Staffology HR.
• Map Staffology HR absence types to Chronicle absence types.
• Import employee absences for a chosen date range.
• Let Chronicle run all of the above automatically every night.

Connecting Chronicle to Staffology HR

This process will only need to be actioned once. 

Before you start

You will need your Staffology HR API Username and API Password. These are generated by Staffology HR when an API user is created within their system. If you don't have this, ask your Staffology HR administrator or have a look at the Staffology API Guide found here: https://help.staffology.co.uk/hr/integrations/api-user-create.htm

With this information to hand, begin following the below steps: 

1. Open the Staffology HR integration set-up page in Chronicle.
2. Enter the API Username and API Password.
3. Click the action to test and establish the connection.
4. If the credentials are valid, the status changes to 'Connected' and the rest of the Staffology HR features unlock in Chronicle.

If it fails

• 'Credentials Invalid' - The username/password is wrong, the API user is inactive, or it has been revoked. Please re-check the values in Staffology HR. 
• 'Connection could not be established' - Chronicle could not reach Staffology HR. Try again shortly; if this persists, raise a support ticket. 

The connection stays active and you do not need to re-enter the credentials each time you visit the page. 

Import New Employees

Use this when you want to bring brand new starters from Staffology HR into Chronicle. To action the import, follow the below steps: 

1. Open the Staffology HR employee import page.
2. Click Fetch employees to retrieve the current list of employees from Staffology HR.
3. Review the list returned from Staffology HR.
4. Click Import employees to begin the import.
5. Confirm the prompt to start (Cancelling closes the prompt with no changes).
6. Wait for the import to finish. 
7. Chronicle then shows a list of the employees it just created.

When importing new employees, the below information gets imported for each new employee: 

• Forename & Surname
• Email & Secondary Email
• Gender
• Date of Birth
• Payroll Number
• Job Title
• Pay Frequency & Pay Category
• Annual & Hourly rates
• Leaving Date

Providing this import is successful, you'll see:

• Results List - Only the employees that were newly created, with their Staffology Employee ID, Name, E-mail, Payroll Number & Job Title. 
• No new employees found - Every Staffology HR employee already exists in Chronicle, so nothing was created.
• Import Failed - Staffology HR was unreachable or returned an error, no partial records created. Ensure the data in Staffology is correct and try again.

Please Note: Existing employees are never updated by this action - Please use the 'Update' page for this.

Updating Existing Employees

You can use this function to refresh employee data that already exists in Chronicle with the latest data within Staffology HR.

To action this, follow the below steps: 

1. Open the Staffology HR employee update page.
2. Click 'Fetch Employees' to retrieve the latest employee data from Staffology HR.
3. Review the list returned from Staffology HR.
4. Click 'Update employees' to apply the changes.
5. Chronicle updates only the records that are already linked to a Staffology HR employee.

This will update the same fields as the new employee import.

Upon actioning this, you may see: 

• Mapped - Total employees synced between Staffology HR and Chronicle
• Changes Detected - Employees that have been updated on Staffology HR since the last sync (These are the records that will change in Chronicle).
• Up to Date - Employees whose data already matches in Staffology HR, so nothing needs to be updated.

A 'per-employee' list is also shown with Staffology Employee ID, Name, E-mail and Update Status.

If no Chronicle employees are matched, you'll see a "no records updated" message and nothing changes. 

Map Staffology HR Absence Types

Before importing absences, tell Chronicle how each Staffology HR absence type maps to its own absence structure. You only need to do this once (and whenever new absence types are added in Staffology HR).

How the Mapping Works

Each Staffology HR absence type maps to: 

• One general type in Chronicle - Holiday, Sickness or Absence.
• One sub-type under that general type.

How to Map the Absences

1. Open the Staffology HR absence type mapping page.
2. Click 'Fetch absence types' to retrieve the current list of absence types from Staffology HR.
3. Review the list returned from Staffology HR.
4. For each row in the list:
   • Pick a general type (Holiday / Sickness / Absence).
   • Pick a sub-type. The list of sub-types changes based on the general type you chose.
5. Click Save.

Rules to Remember: 

• Both a general type and sub-type are required - Chronicle will not save an incomplete mapping. 
• If you change a general type, the sub-type is cleared, you must pick a fresh one.
• Saving a mapping affects future imports only - it does not retroactively re-classify absences already in Chronicle.
• Existing mappings are shown when you re-open the page, so you can review or amend them at any time.

If Staffology HR returns no absence types or the request fails, Chronicle shows a message and saves nothing. 

Importing Absences

To import absences from Staffology HR for a specific period: 

1. Open the Staffology HR Absence Import page. 
2. Enter a 'Start Date' and 'End Date'. Both are required, and the range is inclusive of both dates. 
3. Click 'Fetch Absences' to retrieve absences from Staffology HR for that period.
4. Review the list returned from Staffology HR. 
5. Click 'Import', then confirm the prompt.
6. Chronicle stores the absences against the matching employees.

What gets imported per absence:

• Employee identifier
• Staffology HR absence type
• Absence date
• Duration in days
• Duration in minutes

The Staffology HR absence type is stored as received - Categorisation into Chronicle's general/sub-type structure relies on the mappings configured in step 4. 

After actioning this, you may see: 

• Success Message - This confirms the import completed for the selected date-range. 
• "No absence records found" - If Staffology HR returned nothing for that period.
• "Absence Import Failed" - If the API was unreachable or returned an error. 

Automatic Sync

Chronicle can run the imports for you on a schedule, so the data stays current without manual effort. The automation page has three sections:

• Schedule Settings
• Manual Trigger
• Execution Log

Schedule Settings

To configure when the automatic sync runs, follow these steps: 

1. Open the Staffology HR automation settings page.
2. Toggle Enable automatic sync on. It runs in the background based on the schedule you configure below.
3. Choose a Frequency:
   • Daily — runs once per day at a fixed time.
   • Every N hours — runs on a repeating interval through the day.
4. Set Run at (UK time) — the hour at which the daily run starts (e.g. 00:00 for midnight, 06:00 for 6 AM). UK time is followed including daylight saving changes.
5. Set Absence lookback (days) — how far back from today the absence sync window reaches. Default is 7.
6. Click Save Settings to apply.

If no automatic run has happened yet, the page shows "No auto runs yet" next to the Save button.

Manual Trigger

If you don't want to wait for the next scheduled run, click Run Now in the Manual Trigger section. It synchronously imports employees first, then absences, and may take a few minutes for large datasets.

Execution Log

The Execution Log shows the results of every sync run (manual or automatic) from the last 30 days. Use it to verify that runs completed and to investigate any failures.

If there's nothing to show, you'll see "No sync runs in the last 30 days. Configure a schedule above or click Run Now to start."

Behaviour to Know About

• Runs in the configured order: employee sync (new + updates) first, then absences.
• No overlap. If a run is still in progress when the next scheduled time arrives, a second run is not started.
• Remember about licences. If your licence doesn’t have enough seats to import all new employees - none will be imported automatically.
• Partial failures are recorded. If one step fails, the others still run and each is logged in the Execution Log with its outcome.
• Disabling. Toggle Enable automatic sync off and save to stop scheduled runs. Manual Run Now still works.