Xledger integration

Table of Contents

Set up integration

• Multiple connections
• Step 1: Get an API token from Xledger
• Step 2: Connect Huma to Xledger
• Step 3: Activate the integration. Synchronize users and choose how to handle conflicts or missing value
• Step 4: Your connection between Huma and Xledger is active 🥳

Active integration

• How to sync users
• Deactivated or deleted users 
• Supported fields

General questions

• Why isn't the "Job Title" field updated in Xledger?
  
  

 

---

Xledger

Xledger integration makes HR and payroll more efficient and reliable by keeping your people data consistent across Huma and Xledger. 

Multiple connections

If you need to configure multiple integration instances, follow the setup guidance provided here.

 

1. Get an API token from Xledger

To create a token in Xledger, you must be an "Administrator".

1. Log in as "Administrator"
2. Go to Administration > System Access > GraphQL > API tokens
3. Generate a new access token and give the following access
4. Click "Generate token"
5. Copy token to clipboard
   
   
   
   
   
   

   Scope	Access (read/write)
   Human Resources	Employee: read/write
   Common	Address: read Contact: read/write Company: read Country: read Object Value: read Subledger: read/write Supplier: read/write System Value: read
   General ledger	General ledgerBank: read

   
   
   
   
   
    
   
   
   
   

2a. Connect Huma to Xledger

To set up the integration in Huma, you must be a "System administrator with full access to Organization > Organization-wide settings". 

1. Login to your Huma account as Administrator
2. Go to 'Integrations' in the main menu
3. Open 'Xledger'
   1. Read through the documentation in the "Overview" and "Details" tabs.
4. Click 'Set up' in the upper right corner
5. Paste the created Xledger API token key and check the box to verify you have the proper authority.

2b. Configure integrations settings

When adding users in Huma, you can choose if they should automatically be added in Xledger. If you leave this inactive, you need to do a manual sync to add the user in Xledger.

• If you're using the Teamtailor integration, users added to Huma via that integration will also be added to Xledger.

• You can turn this on later if you prefer not to enable it now.
  
  

Click 'Save' and a connection is now established between the two systems. 

Step 3: Activate the integration, synchronize users, and choose how to handle any conflicts or missing values

After you click “Save”, you’ll be taken to the connection overview page. To activate the integration, you need to “Sync users.”

1. Click “Sync users.”

2. Matching users: Users found in both Huma and Visma (same email address in both systems).

    

   1. Click “View users” to see which supporting fields don’t match or are missing.

       

   2. Resolve any non-matching or missing values.

       

   3. Click “Next.”

3. Non-matching users: Users who exist in only one of the systems.

   1. Choose whether to create all users / selected users / do not create.

   2. Choose how users should be created:

      1. Visma → Xledger: Add users to Huma.

      2. Huma → Xledger: Add users to Xledger.

 

         4.  Click “Sync users.” You’ll receive an email with the results.

 

Note

• Users who have not completed the “Required fields” will not be synchronized.

 

4. Your connection between Huma and Xledger is active 

• Any changes made to supported fields in Huma (listed below) will be automatically updated in Xledger in real-time. 
• Please be aware that you need to sync users to get the latest changes from Xledger. Changes made in Xledger will not be automatically be updated in Huma. 

 

 

How to sync users

Use "synchronize users" when you have updated supported fields in Xledger, or when you have created new users in Huma. 

If you need to do a manual sync between Xledger and Huma

1. Go to the integration page for Xledger in Huma 
2. Click "Synchronize users" and follow the steps. Read more about the steps here. 

 

Note

• Please be aware that you need to sync users to get the latest changes from Xledger. Changes made in Xledger will not be automatically be updated in Huma. 

   

• When a transfer of data from Huma to Xledger is triggered, the name of the user who created the API token in Xledger, will remain in the history of the change.

• If an error occurs during synchronization, you can see detailed information in the “Error log” on the Entra ID-integration page in Huma.

 

Deactivated or deleted users

When a user is deactivated in Huma...

• the user will not be deactivated in Xledger.
• the user will be locked for updates.

 

When a user is deleted in Huma...

• the user will not be deleted in Xledger.
• and not the other integration, the manual sync will ask you to create this user in Xledger.
• the user cannot be synced if there have been changes to their record in Xledger.
  
  

Supported fields

Huma field	Xledger Field
Email address*	employee.contact.email employee.subledger.email Huma requires this field’s value to be unique.
Employment ID	employee.code Huma requires this field’s value to be unique.
Given name	employee.contact.firstName employee.subledger.description
Family name	employee.contact.lastName employee.subledger.description
Phone number	employee.contact.phone employee.subledger.phone Huma requires this field’s value to be unique.
Date of birth	employee.contact.birthday
Bank account number	employee.subledger.bankAccount The integration will update this field in Xledger.  employee.subledger.company.country The integration can’t update this field’s value in Xledger with the value in Huma.
Address	contact.address.streetAddress contact.address.zipCode contact.address.place contact.address.country.code subledger.address.streetAddress subledger.address.zipCode subledger.address.place subledger.address.country.code The integration can’t unset this field’s value in Xledger when the value is unset in Huma.
Gender	employee.contact.gender
Job title	employee.contact.jobTitle
Employment start date	employee.employmentFrom
Probation end date	employee.trialTo
Termination notice date	employee.noticeDate
Employment end date	employee.employmentTo
Identification	SSN - social security number

 

Note

• If you receive "Error parsing query: Unterminated string", it may indicate that one of the supported fields contains a special character that cannot be interpreted.

 

 

Why isn't the "Job Title" field updated in Xledger?

You can enter job titles in two places in Xledger, and customers use Xledger in different ways, not always utilizing the job title field Huma actually support.

Today, job titles are synced from Huma to the field in Xledger called employee.contact.jobTitle.

You can find this field in Xledger by navigating to:

1. XRM 
2. Contact 
3. Select Employee 
4. View the "Job Title" field.