ZenHR – NetSuite Native Integration

Modified on Tue, 13 May at 3:44 PM

ZenHR’s native integration with NetSuite allows customers to push/transfer their employee's data and the calculated salaries from ZenHR to NetSuite to gain all the benefits that come with the most user-friendly HRMS, ZenHR.

TABLE OF CONTENTS

How to Activate This Integration
On NetSuite: Generate the Client ID and Client Secret
On NetSuite: Create New User With Role
NetSuite: Creating New Access Token
On NetSuite: Get the Authorization Realm
On ZenHR: Create New API Key
On NetSuite: Running The Scripts
How to Use NetSuite Integration
Posting Provisions From ZenHR to NetSuite
NetSuite Events Status & Verifying Issues

How to Activate This Integration

To activate NetSuite's built-in integration on ZenHR, the first step is to create a user token within NetSuite. This process begins by creating an integration app to generate the client ID and secret.

Important Note : The use that will have the ZenHr Role must not be an admin on NetSuite.

The user token is essential for establishing a secure connection between NetSuite and ZenHR, ensuring seamless data and functionality transfer between both systems.

On NetSuite: Generate the Client ID and Client Secret

go to Setup → Company → Enable Features → SuiteCloud and tick the option “Token Based Authentication” from the section “Manage Authentication.”

On NetSuite again, go to Setup → Integrations → Manage Integrations.

Click “New” to set up a new integration.

Then Select the Below :

Name the integration name “ZenHR_Integration”
Make sure to select the State: Enabled
Tick the option “Token-based authentication”
Select the Scope: RESTLETS
Uncheck these options:
- “TBA: ISSUETOKEN ENDPOINT”
- “TBA: AUTHORIZATION FLOW”
- “AUTHORIZATION CODE GRANT”
- “USER CREDENTIALS”

A Consumer Key and Consumer Secret will be generated. Make sure that you copy and save them as they only appear once.

On NetSuite: Create New User With Role

Go to Setup → Users/Roles → Manage Roles, create a new role and make sure that the user can access All Subsidiaries.

From the Transactions, make sure that the user has full permission to Make Journal Entries.

From the Lists, add the full permission for accessing :
- Accounts
- Departments
- Employee Records
- Employees.

From the Setup, make sure that the user has full permission on the User Access Token.

Link the user that you will use for the integration with this role by going to Setup → Users/Roles → Manage Users then find the user and add the Role . Noting that the user should not have any other role on NetSuite (Only ZenHR Admin).

NetSuite: Creating New Access Token

Go to Setup → Users/Roles → Access Token and create a new access token.

Select the integration Application Name, the User, and the Role.
Insert the Token Name.
Then click “Save”.

Copy and Save the generated token details and keep them with you, as they will only be generated once.

On NetSuite: Get the Authorization Realm

Go to Setup → Company → Company Info and copy the Account ID.

On ZenHR: Create New API Key

Go to User Menu → System Preferences → Integration Setup → API Keys and click on Add API Key

Add the API key name and choose the authentication type OAuth 1

Fill the Key & Secret with the Token ID & Secret that you generated from NetSuite.

Fill in the consumer key and consumer secret obtained from the Client ID & Secret generated from NetSuite, along with the Authentication Realm ( Account ID ) retrieved from the company information on NetSuite.
Then "Save"

On NetSuite: Running The Scripts

NetSuite scripts are custom scripts written in SuiteScript, which is a JavaScript-based scripting language used to extend the functionality of NetSuite ERP system. Put in mind that the scripts are made for the standard NetSuite.

NetSuite Scripts

Three essential scripts are required for this integration. You can download these scripts through the provided links: NetSuite Scripts

Note : If the NetSuite account is One World use the below scripts (If there is multiple subsidiaries)

If the account has no Subsidiaries (Not OneWorld):

Go to Customization → Scripting → Scripts → create a new script → press on the “+” sign :

Upload the scripts from your computer, make sure that the script name ends with .js and select the folder SuiteApps.

Then go back to Customization → Scripting → Scripts → choose the script you just created by searching the file name → Press Create Script Record. Enter the script name, and proceed to create a new entry in the deployments section with the following details: Status: Released and Log Level: Debug.

After saving the script details, it will be created, and you will be able to check the deployment details from the Deployments section.

Click on the script deployment title to check and update the details if needed.

Ensure that the script has access to all roles, subsidiaries, employees, and groups by pressing on Edit then selecting all of them. The script is now prepared for utilization by ZenHR. You will simply need to copy the External URL for inclusion in the NetSuite integration setup on ZenHR.

To get the needed URLs from your NetSuite account:

Go to NetSuite → Customization → Scripts → Script Deployments
Click “View” in the needed script record.
Copy the External URL to add it to the ZenHR NetSuite integration setup.

Note: Do the same for all the Scripts to fetch the External URL of Employee URL, GL Account Identifiers URL, Journal entries URL

ZenHR: NetSuite Integration Setup

Go to System Preferences → Integration Setup → Marketplace Integrations → NetSuite Setup.
To get the needed URLs from your NetSuite account:
- Go to NetSuite → Customization → Scripts → Script Deployments
- Click “View” in the needed script record.
- Copy the External URL to add it to the ZenHR NetSuite integration setup.

Activate the toggle in the Employee, GL Account Identifiers, and Journal Entry sections and add the External URL retrieved from your NetSuite account.

Make sure that the branch name on ZenHR and the subsidiary name on NetSuite match by going to System Preferences → Branch Setup → Subsidiary id.

Make sure that the organization levels (work location, departments, etc.) match on both ZenHR & NetSuite by going to System Preferences → Organizational level setup.

NetSuite: Adding Customized Fields

On NetSuite, go to Customization → Lists Records & Fields → Custom Entity Fields from your NetSuite account, and click on new.

Insert the label “zenhr_employee_id”, and the ID will be generated as “ns_zenhr_employee_id.”
Select the type “Free Form Text”.
Tick the option “Store Value”.
Select the option Employees from the section Applies To.

Important Note: Prior to enabling the integration for employees, it is crucial to input the internal ID of ZenHR employees into the designated custom field. Not to include the employee's ID in the custom field when updating the employee on ZenHR will result in the creation of a duplicate record for the same employee on NetSuite. This duplication issue must be avoided.

Adding NetSuite Subsidiary ID

To link your branch to the correct NetSuite account:

On NetSuite, go to Setup → Company → Subsidiaries list.
Find the Subsidiary ID, where you can find it in the page URL when you try to edit or view a subsidiary.

On ZenHR, go to System Preferences → General → Branch Setup.
Locate and modify the details of the specific branch you wish to link, and input the Financial integration Subsidiary ID which you can find in the URL same as the one shown above ( in our Ex the ID is 1 ).

And now, the integration between ZenHR and NetSuite is currently active. It's important to ensure that the branch name on ZenHR aligns with the subsidiary name on NetSuite. Additionally, make sure that the organization levels (such as work location, departments, etc.) are consistent across both ZenHR and NetSuite.

How to Use NetSuite Integration

Upon successfully integrating NetSuite with your ZenHR account, you gain the ability to map the GL account, manage employee records by creating and updating them on ZenHR, and seamlessly transfer journal entries for salaries, off-cycle financial transactions, employee settlements, company contributions, expenses, and provisions from ZenHR to your NetSuite account.

Mapping NetSuite GL Identifiers With ZenHR Financial Transactions

Once the integration with NetSuite is enabled, the chart of accounts will be accessed through the APIs. Consequently, the GL account will be displayed in the GL Accounts fields across all financial transaction types in the same page.

To add and Map GL Accounts:

On ZenHR, click your user icon in the upper right corner and go to System Preferences → Marketplace Integrations → NetSuite Setup → GL Accounts.
Select the correct GL account for each salary transaction type from the dropdown list which will show the GL Accounts in your NetSuite Account.
Then click “Update”.

To add Financial Transactions GL Accounts:

Navigate to Incomes & Deduction Tab in the same page above
Access the Financial Transaction Type by selecting “✎” icon on the Transaction Type entry.
Choose the GL Account Number and Clearance account Or Enter them Manually.
Finally, press on the “✔” icon.

To add Loans GL Accounts:

Navigate to Loans Tab in the same page above
Access the specific Loan Type by selecting “✎” icon on the corresponding record.
Choose the GL Identifier and the Clearance account.
Finally, press on the “✔” icon.

Adding Overtime GL Accounts

Access the Overtime Type by selecting “✎” icon on the corresponding record.
Choose the GL Identifier and Clearance account.
Finally, press on the “✔” icon.

Add Leaves and Vacations GL account:

Access the Leaves and Vacations Type by selecting “✎” icon on the corresponding record.
Select the GL Identifier and Clearance Account.
Finally, press on the “✔” icon.

Syncing Employees Records

Upon activating the integration, employee records will automatically transfer or update on NetSuite when you create or update employee data on ZenHR.

If there is already employees that are created in NetSuite then you can connect them by locating current employees on NetSuite, navigate to List > Employees, then modify the employee record by entering the unique internal ID from ZenHR into the designated field “ZenHR_Employee_ID“ within the Custom section.

Posting Journal Entries

Upon activating the integration, you will be able to transfer journal entries for salaries, off-cycle financial transactions, employee settlements, company contributions, expenses, and provisions from ZenHR to your NetSuite account.

Set Up Journal Entries Structure

Before initiating the transmission of journal entries from ZenHR to NetSuite, it is essential to configure the Journal Entries Structure. This setup enables you to specify the types of journal entries for transfer, whether they are detailed on an employee level or summarized by a specific cost center, and if they should be dispatched automatically or manually. To accomplish this, please adhere to the following steps:

On ZenHR, go to System Preferences → Integration Setup → Journal Entries Structure.

Set up the way you would like your journal entries structured by completing the following fields, then click “Save”.

Posting salaries from ZenHR to NetSuite

On the left side of the page, go to Main Menu → Payroll → Manage Salaries.
Filter the desired Salary Year and Month for all employees, and click “Filter”.
Then click “Send to NetSuite”, and your salaries will be transferred as journals.

Posting Off-Cycle Payments and Vacation In-Advance Salaries From ZenHR to NetSuite
To auto-generate separate journals for off-cycle payments and post them with your payroll journal entries, follow these steps:

Click your user icon in the upper right corner and go to System Preferences → Journal Entries Structure.
Activate the Auto-generate separate journals for off-cycle checkboxes Below and click “Save”.

You can then post salaries from ZenHR to NetSuite, and the transferred journals will include separate journal entries for your off-cycle payments and vacation in-advance salaries.

To manually generate your off-cycle payments journal entries, follow these steps:

Click your user icon in the upper right corner and go to System Preferences → Integration Setup → Journal Entries Structure.
Clear the Auto-generate separate journals for off-cycle payments checkbox and click “Save”.
To Send Off-Cycle Payments to NetSuite :

Go to Main Menu → Payroll → Manage Financials → Manage Financial Transactions → Off-Cycle Payments
Use the “Date from” and “to” filters to filter out the duration of the transactions you wish to include in your journal entries, and click “Filter”.
In the Employee ID column, select the transactions you wish to include in your journal entries.
Then click “Send to NetSuite”, and your off-cycle payments will be transferred as journals.

To manually generate your off-cycle vacation in-advance journal entries, follow these steps:

Click your user icon in the upper right corner and go to System Preferences → Integration Setup → Journal Entries Structure.
Clear the Auto-generate separate journals for off-cycle vacation in-advance checkbox.
Then click “Save”.

Go to Main Menu → Payroll → Manage Financials → Manage Vacation In-Advance Salary.
Filter out the vacation in-advance salaries that fall within a specific time period by using the “In-advance from date” and “In-advance to date” filters.
Select “Off-cycle” under Payroll status and click “Apply Filters”.
Then, under the Employee No. column, select the in-advance salaries you wish to include in your exported journal entries. Or you can select all the filtered salaries by clicking the “Select all” checkbox.
Then click “Send to NetSuite”, and your off-cycle vacation in-advance salaries will be transferred as journals.

Posting Provisions From ZenHR to NetSuite

To auto-generate journals for provisions and post them with your payroll journal entries, follow these steps:

Click your user icon in the upper right corner and go to System Preferences → Integration Setup → Journal Entries Structure
Activate the Calculate employees' provisions toggle.
Activate the Auto-generate journal entries for employees' provisions toggle.
Then select the desired option under “How to generate provision journal entries”.
click “Save”.

You can then post salaries from ZenHR to NetSuite, and the transferred journals will include journal entries for your provisions.

To manually generate provisions journal entries, follow these steps:

Click your user icon in the upper right corner and go to System Preferences → Integration Setup → Journal Entries Structure.
Activate the Calculate employees' provisions toggle.
Deactivate the Auto-generate journal entries for employees' provisions toggle.
Then select the desired option under select “How to generate provision journal entries”.
Click “Save”.

Then on the left side of the page, go to Main Menu → Payroll → Manage Monthly Provision.
Enter the desired salary Year and Month for all employees, and click “Filter”.
Then click the“Send to NetSuite” and your provisions will be transferred as journals.

NetSuite Events Status & Verifying Issues

Just as with any integration between two platforms, having a monitoring tool is essential to oversee all events and activities. This tool plays a crucial role in tracking the outcomes of these events efficiently, which can be achieved through the NetSuite Events Viewer on ZenHR.

NetSuite Events Viewer on ZenHR provides the functionality to retry sending failed posts. To access this feature, navigate to User Menu → System Preferences → Integration Setup → Financial Integrations → NetSuite Setup and click on “Retry”.

You can also monitor event statuses in NetSuite by accessing the Execution Log of the related script.