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 - Employee fields
• Supported fields - Position fields

General questions

• FAQ: Xledger and Huma position integration
  
  
  

 

---

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.”

1. 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 - Employee fields that are synchronized.

Changes made to supported fields in Huma (listed below) are automatically updated in Xledger in real time. Changes made in Xledger, however, must be synchronized manually in Huma.

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
Identification	employee.contact.socialSec Only Norwegian national identity numbers are supported in Xledger.

 

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.

 

 

Supported fields - Position fields that are synchronized.

📄 Learn more about how employee data synchronization works in integrations in general.

⚠️ Note that activating the integration does not transfer historical position data to Xledger. Only positions that are created or updated in Huma after the integration is activated will be synchronized.

Position data is synchronized only from Huma to Xledger, not from Xledger to Huma.

 

 

FAQ: Huma to Finago position integration

Where is 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.

 

 

Does the integration update position data?

Yes. When supported position fields are changed in Huma, the updates are automatically sent to Xledger.

This includes changes such as updates to contract dates and title.

 

 

In which direction is data synchronized?

Position data is synchronized in one direction only:

Huma → Xledger.

Changes made directly in Xledger. will not be sent back to Huma.

 

 

When is position data sent to Xledger?

Position data is sent to Xledger when:

• A new position is created in Huma

• An existing position is updated in Huma

• A user with a position in Huma, are created in Xledger through a manual sync.

• The change happens after the integration has been activated

 

 

Can historical positions be transferred?

No. The integration does not automatically transfer historical position data that existed before the integration was activated.

 

 

Why aren’t all position fields synchronized?

Not all position fields can be synchronized between Huma and Xledger because the two systems store and structure employment information differently. Some fields exist only in one system, or their data structures do not match directly. In other cases, limitations in the Xledger API or in how data is handled in Huma prevent a full one-to-one mapping between the systems.