For Admins and HR users: Use this article to prepare your Employment Hero organisation before connecting Diversity Sync’d and syncing staff details and certificates.
Staff members should contact their manager or HR administrator if they have questions about their Employment Hero details or certificates.
Before connecting Employment Hero to Diversity Sync’d, ensure your Employment Hero setup is complete to avoid sync issues. Your organisation connects through its own Employment Hero app, so nobody at Diversity Sync’d signs in to your Employment Hero or sees your client secret. Confirm the following:
Pre-Integration Requirements
Your Employment Hero plan includes Developer Portal. It comes with Platinum HR, eOS Plus and eOS Unlimited. To check, open your profile menu in Employment Hero (top right) and look for Developer Portal.
You can sign in to Employment Hero with an admin login from the organisation you want to connect, and that login can open Developer Portal.
You have permission to manage integrations in Diversity Sync’d.
Every staff member you want to sync has an employee record in Employment Hero.
Each employee’s work email in Employment Hero matches their email in Diversity Sync’d. Diversity Sync’d suggests an employee for each staff member, matching by email first and then by name and date of birth, and you confirm each link. Matching emails make linking quickest.
Employee details are complete in Employment Hero: first and last name, phone number, date of birth and start date. These come from Employment Hero unless you choose otherwise. If you also want to sync addresses, emergency contacts, employment types or job titles, check those too.
Certification types are set up in Employment Hero, and each employee’s certifications have an expiry date. Certifications without an expiry date are skipped.
If you want Diversity Sync’d to copy certificate files across, they are tagged Certificate on the employee’s Employment Hero profile. Files without that tag are not copied.
You know which Employment Hero organisation you want to connect before you start.
Create the Employment Hero App
In Employment Hero, open your profile menu and select Developer Portal.
Select Add Application and enter:
Name: Diversity Sync
Tick every scope listed below, including the write scopes.
Save the app. Employment Hero then shows a Client ID and Client secret. Copy both.
Read scopes
urn:user:organisations:list:readurn:admin:organisations:employees:list:readurn:admin:organisations:certifications:list:readurn:admin:organisations:employees_certifications:list:readurn:admin:organisations:documents:list:readurn:admin:organisations:employing_entities:list:read
Write scopes
urn:admin:organisations:employees:personal_details:updateurn:admin:organisations:employees:employment_details:updateurn:admin:organisations:employees:quick_add_employee:createurn:admin:organisations:employees:onboard_employee:createurn:admin:organisations:employees:offboard:updateurn:admin:organisations:documents:new:create
The setup page in Diversity Sync’d doesn’t list these scopes, so copy them from here. The employing entities scope is for New staff, which creates staff added in Diversity Sync’d as Employment Hero employees and is coming soon. Tick it now so you won’t need a new app later.
Important: Tick every scope, including the write scopes. Employment Hero only lets you choose an app’s scopes when you create it, so a missing scope means creating a new app. Ticking the write scopes doesn’t make Diversity Sync’d send anything to Employment Hero. Nothing is sent until you switch on Sync to Employment Hero and choose what goes there.
Only create the app or connect Employment Hero if you are authorised to manage your organisation’s Employment Hero settings. Keep the client secret private.
Connect Diversity Sync’d
In Diversity Sync’d, go to Admin > Integrations > Employment Hero and select Connect.
Under Set up your app, paste the Client ID and Client secret, then select Save and review. Diversity Sync’d checks them with Employment Hero before saving.
Under Review access, select Connect Employment Hero.
Sign in with your Employment Hero admin account, choose Skip on the single sign-on page, then Allow access.
When you’re back in Diversity Sync’d, it shows Employment Hero is connected. The Employment Hero app panel then lists your app, and Permissions shows which scopes it was given. Next, link your staff and choose what syncs: see Link Staff to Employment Hero Employees and Sync with Employment Hero.
Notes
You choose what Diversity Sync’d syncs in Sync settings: Staff details, Certificate expiries for mapped certifications, Certificate documents and Leavers.
Each staff detail has its own direction. Name, phone number, date of birth, start date and address can each be From Employment Hero, To Employment Hero, Both ways or Off. Name, phone number, date of birth and start date start as From Employment Hero, and address starts as Off. From Employment Hero updates Diversity Sync’d to match Employment Hero. To Employment Hero sends the value in Diversity Sync’d to Employment Hero, overwriting Employment Hero’s. Both ways takes the change from whichever system changed since the two last matched. An empty value never replaces a filled one.
Emergency contact, employment type and position (Employment Hero’s job title) can only come from Employment Hero, because Employment Hero doesn’t let other apps change them. They start as Off.
Nothing is sent to Employment Hero until you switch on Sync to Employment Hero. While it is off, details set to Both ways come from Employment Hero, and details set to To Employment Hero don’t sync. When a save starts sending a detail, Diversity Sync’d asks you to confirm first. From then, details set to To Employment Hero or Both ways are sent every day and whenever you apply a sync, for each linked staff member whose values differ. Employment Hero’s values are overwritten, and payroll reads them from there.
If a Both ways detail changed in both systems since they last matched, or the two systems hold different values the first time it syncs, the sync changes neither value. The same happens when Employment Hero refuses a value Diversity Sync’d sends. These details wait under Needs a decision on the setup page until you select Keep next to the value you want. Diversity Sync’d then makes the other system match.
An address is sent to Employment Hero only when it has a street, suburb, state and four-digit postcode. An Employment Hero address that doesn’t read as an Australian street address isn’t brought across.
With Leavers ticked under Sync from Employment Hero, someone terminated in Employment Hero is archived in Diversity Sync’d on their last day: their login ends and their seat frees. Unticked, a termination only shows a warning. With Leavers ticked under Sync to Employment Hero, archiving a linked staff member in Diversity Sync’d asks whether to offboard them in Employment Hero too.
You can preview a sync’s changes before applying them, including anything that would be sent to Employment Hero and any leavers who would be archived. Use Sync from Employment Hero to choose whether the ticked types are brought across automatically each day.
Email addresses are never synced, because staff use them to sign in. If an employee’s email differs between the two systems, the sync shows a warning so you can update it.
A name is not synced if the first and last name together would be longer than 35 characters. A warning shows instead.
Each Employment Hero certification must be mapped to a Diversity Sync’d certificate, or created as a new one, on the setup page. Unmapped certifications are not synced. A sync adds and updates certificates, and never deletes them. Certificates only come from Employment Hero.
One Diversity Sync’d organisation connects to one Employment Hero organisation.
Each person who manages Employment Hero connects with their own Employment Hero login. Previewing, applying and keeping a value use your own login.
The write scopes let Diversity Sync’d send staff details and offboard leavers, and create new staff once New staff is released. If any write scope is missing, nothing can be sent.
If your app’s client secret changes, select Replace credentials in the Employment Hero app panel and enter the new secret. The connection keeps working. To switch to a different app, enter its client ID and client secret the same way. Employment Hero then opens so you can allow access again, and everyone else who connected needs to reconnect.
Troubleshooting
I can’t find Developer Portal in Employment Hero
Your Employment Hero plan doesn’t include it. Developer Portal comes with Platinum HR, eOS Plus and eOS Unlimited. Ask Employment Hero to change your plan, then return to the setup page.
Employment Hero doesn’t recognise the client ID
Copy the client ID from your app in Developer Portal again. Make sure you copied the client ID, not the app name.
Employment Hero won’t send people back to Diversity Sync’d
The app’s redirect URI doesn’t match. The message shows the exact redirect URI to use. Correct it in Developer Portal, or create a new app with that redirect URI, then select Save and review again.
The client secret doesn’t match the app
Enter the client secret again, making sure it belongs to the same app as the client ID and nothing is missing. If the app’s secret has changed, enter the new one with Replace credentials.
The app is missing a scope
Employment Hero can’t add a scope to an existing app. Permissions in the Employment Hero app panel shows which scopes are missing. Create a new app with every scope listed above, then enter its client ID and client secret in Diversity Sync’d. If only write scopes are missing, the connection still works, but nothing can be sent to Employment Hero until you connect an app that has them. Until then, a Both ways detail changed in Diversity Sync’d is held rather than replaced with Employment Hero’s value.
Emergency contacts don’t sync
Reading emergency contacts needs a scope that isn’t in the list above. If the sync warns that Employment Hero refused to give your app emergency contacts, set Emergency contact to Off, or contact Diversity Sync’d support.
The login belongs to a different Employment Hero organisation
You signed in with a login from another Employment Hero organisation. Sign out of Employment Hero, then connect again as a user of the organisation your Diversity Sync’d account is connected to.
A staff member isn’t matched to an employee
Check that the employee exists in Employment Hero and that their email matches Diversity Sync’d. You can also link them by hand under Staff linking on the setup page.
A certificate isn’t syncing
Check that Certificate expiries is ticked in Sync settings, that the staff member is linked, and that the Employment Hero certification is mapped on the setup page and has an expiry date.
A certificate file isn’t copied across
Check that Certificate documents is ticked in Sync settings, that the staff member is linked, and that the file is tagged Certificate on the employee’s Employment Hero profile.
A staff detail isn’t sent to Employment Hero
Check that Sync to Employment Hero is on, that Staff details is ticked and the detail is set to To Employment Hero or Both ways, that the staff member is linked, and that your app has every write scope. A detail that is empty in Diversity Sync’d is never sent, and one waiting under Needs a decision isn’t sent until you decide.
A staff detail is waiting under Needs a decision
It changed in both systems since they last matched, or Employment Hero refused the value Diversity Sync’d sent. Compare the two values, then select Keep next to the one you want, and Diversity Sync’d makes the other system match. If neither is right, correct it in one system first, then reload the setup page.
I am not sure whether the setup is ready
Review your plan, the app’s redirect URI and scopes, employee emails, certification expiry dates and certificate tags before connecting. Contact your HR administrator or Diversity Sync’d support if anything is unclear.