Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

NetSuite

This guide walks you through setting up Token-Based Authentication (TBA) in NetSuite so Harmony can securely read your vendor, contract, and procurement data.

What you'll do: Create a dedicated role with minimal permissions, generate authentication tokens, and collect the 5 values needed to complete the Harmony integration setup.

1. Prerequisites - Enable Features

Navigation: Setup › Company › Setup Tasks › Enable Features › SuiteCloud tab

Check both:

  • ✅ REST Web Services

  • ✅ Token-Based Authentication

Accept the SuiteCloud Terms of Service if prompted. Save.

2. Create the Role

Navigation: Setup › Users/Roles › Manage Roles › New

General settings:

Field
Value

Name

Harmony Integration Role (or any descriptive name)

Subsidiary Restrictions

All (so the token sees vendors/purchase orders across all subsidiaries)

Authentication

Leave all unchecked (Two-Factor: Not required)

Permissions - Minimal Required Set

Add the following permissions to the role. These are the minimum permissions required for Harmony to read your vendor, contract, and procurement data.

Setup tab:

Permission
Level
Notes

Log in using Access Tokens

Full

REST Web Services

Full

View Login Audit Trail

View

Only required for the Native App Integration* flow

Reports tab:

Permission
Level
Why

SuiteAnalytics Workbook

Edit

Unlocks SuiteQL query execution

Transaction Detail

View

Enables transaction table access in SuiteQL

Lists tab:

Permission
Level
Notes

Contacts

View

Employees

View

Employee Record

View

Only required for the Native App Integration* flow

Items

View

System Notes for Analytics and REST

View

Vendors

View

Transactions tab:

Permission
Level

Bills

View

Find Transaction

View

Purchase Order

View

* Native App Integration is the flow where Harmony surfaces per-user NetSuite activity (last-login, seat usage) alongside vendor and contract data - treating NetSuite itself as a SaaS app in your inventory. It reads employee records and the login audit trail to identify active users. If you only need vendor/contract/spend sync, you can skip these two permissions.

3. Assign the Role to a User

Navigation: Lists › Employees › Employees (find the user who will own the integration)

We recommend using a dedicated service account rather than a personal employee account, so the integration is not affected if the employee leaves.

  1. Open the employee/user record

  2. Go to the Access subtab

  3. In the Roles section, click Add

  4. Select the role you created (e.g. Harmony Integration Role)

  5. Save

Tip: If you cannot see the user in the Access Token dropdown later, it means this step was not completed - the role is not assigned to the user, or the role is missing the "Log in using Access Tokens" permission.

4. Create the Integration Record

Navigation: Setup › Integration › Manage Integrations › New

Field
Value

Name

Harmony Integration (or any descriptive name)

State

Enabled

Token-based Authentication

✅ Checked

TBA: issuetoken Endpoint

⬜ Unchecked

TBA: Authorization Flow

⬜ Unchecked

OAuth 2.0 section

Leave all unchecked

Click Save.

⚠️ IMMEDIATELY copy the two values shown - they appear only once and cannot be retrieved later:

  • Consumer Key

  • Consumer Secret

These may be labeled as Client ID and Client Secret in other documentation.

5. Create the Access Token

Navigation: Setup › Users/Roles › Access Tokens › New

Field
Value

Application Name

Select your integration record

User

Select the user with the role assigned

Role

Select the role you created

Click Save.

⚠️ IMMEDIATELY copy the two values - shown only once:

  • Token ID

  • Token Secret

6. The 5 Values You Need

Once you have completed the steps above, enter these 5 values in the Harmony integration setup screen to complete the connection:

#
Value
Where to find it

1

Account ID

Setup › Company › Company Information (format: 1234567 or 1234567_SB1 for sandbox)

2

Consumer Key

From Step 4 (Integration Record save)

3

Consumer Secret

From Step 4 (Integration Record save)

4

Token ID

From Step 5 (Access Token save)

5

Token Secret

From Step 5 (Access Token save)

Note: When you open the NetSuite integration setup form in Harmony, a "For more details, visit our documentation" link at the top of the form brings you directly back to this guide if you need a reference while filling in your credentials.

7. Choose Which Transaction Types to Sync

After entering your credentials, you can control which NetSuite transaction types Harmony pulls in as part of your contracts integration. Two toggles are available in your NetSuite integration settings:

Toggle
Default
When to use it

Sync Purchase Orders

On (enabled by default)

Standard purchasing workflow - most organizations use this

Sync Vendor Bills

Off (disabled by default)

Enable this if your team books vendor contracts directly as Vendor Bills with no associated Purchase Order

Both toggles can be enabled at the same time if your organization records spend through both transaction types. Existing NetSuite tenants retain their current behavior - Sync Purchase Orders remains on and Sync Vendor Bills remains off unless you explicitly enable it.

8. Optional (Strongly Recommended) - Service Start / End Date Columns

NetSuite does not have a single, standard "contract start date" or "contract end date" field. Instead, most customers track the service period on transaction lines (the individual lines of a Bill or Purchase Order) using custom transaction column fields

  • typically named something like custcol_service_start_date and custcol_service_end_date.

Harmony uses these two columns to populate the contract start date and contract end date for each vendor contract it derives from your NetSuite data. Without them, those fields will be left NULL in Harmony, which significantly reduces the value of renewal tracking, expiring-contract alerts, and spend-by-period reporting.

✅ We strongly recommend providing these two column IDs. If your organization tracks service periods on transaction lines under different field names, use those instead - the important thing is that the field is a transaction line column holding a date.

8.1 Supported column types

The service_start_date_column and service_end_date_column fields accept either of the following:

  • A custom column ID - any custcol_* field of type Date that your organization uses to record service periods (e.g. custcol_service_start_date).

  • A NetSuite native amortization column - if your organization uses NetSuite's built-in amortization schedule instead of custom fields, you can enter one of these two reserved values:

Value
What it maps to

amortizstartdate

NetSuite's native amortization start date column

amortizationenddate

NetSuite's native amortization end date column

This is an explicit, per-credential choice. There is no automatic fallback - Harmony uses exactly the column ID you provide.

8.2 Where these fields live in NetSuite

  • Transaction Line Fields (a.k.a. transaction column fields) - custom fields that appear on each line of a transaction (Bill, Purchase Order, Invoice, etc.), not on the transaction header.

  • Their internal ID is what Harmony needs. Internal IDs almost always start with the prefix custcol_ (for example custcol_service_start_date).

8.3 How to find the exact column IDs

Option A - Browse the Transaction Line Fields list (recommended)

  1. In NetSuite, go to Customization › Lists, Records, & Fields › Transaction Line Fields.

  2. In the list, look for fields whose Label describes a service period, contract period, subscription term, or similar - common names include:

    • Service Start Date / Service End Date

    • Contract Start / Contract End

    • Coverage Start / Coverage End

    • Subscription Start / Subscription End

  3. Confirm the Type column shows Date (not Free-Form Text, List/Record, etc.).

  4. Copy the value from the ID column - this is the internal ID you enter in Harmony (for example custcol_service_start_date). If the ID column is not visible, click the field name to open it - the ID is shown at the top of the record.

Option B - Inspect a real transaction

If you're not sure which custom fields your organization actually populates, open a representative Bill or Purchase Order that has the service period filled in:

  1. Open the transaction and go to the Items subtab (line items).

  2. Click a line to edit it, or expand the line detail.

  3. Hover the label of the start-date / end-date field - most browsers will show the underlying field ID in a tooltip. You can also right-click and choose Inspect - the field's HTML id attribute contains the internal ID (look for custcol_<something>).

Option C - Ask your NetSuite administrator

If you don't have permission to access Customization, your NetSuite admin can tell you the internal IDs of the service-period fields your organization uses.

8.4 Enter the IDs in Harmony

Paste the internal IDs (including the custcol_ prefix, or the native amortization column name) into the last two fields of the Harmony NetSuite setup screen:

Field
Example values

Service start date column

custcol_service_start_date or amortizstartdate

Service end date column

custcol_service_end_date or amortizationenddate

Leave either field blank to skip it - the corresponding contract date will remain NULL in Harmony.

⚠️ Common pitfalls

  • The value must be the internal ID (e.g. custcol_service_start_date), not the display label ("Service Start Date") - unless you are using one of the two native amortization column names listed above.

  • Custom fields must be Transaction Line Fields, not Transaction Body Fields or Item Fields.

  • Custom fields must be of type Date. Free-form text fields containing dates as strings are not supported.

  • The role you created in Step 2 must have View access to the transactions (Bills, Purchase Orders) whose lines carry these fields - the minimal permissions listed above already cover this.

  • Harmony validates your configured column IDs against your NetSuite instance at connection time. If a column ID contains a typo, references a non-date field, or points to the wrong table, you will receive a clear error message immediately so you can correct it before your first sync runs.

9. Native App Integration - User and License Insights

In addition to contract and spend sync, you can connect NetSuite as a native application integration in Harmony. This gives IT admins direct visibility into NetSuite user activity, roles, and license utilization from the Applications page - treating NetSuite itself as a managed SaaS app in your inventory.

Once connected, Harmony syncs your NetSuite data daily, with a manual refresh option available. The same Token-Based Authentication credentials used for contract sync power this integration.

What Harmony surfaces:

  • User inventory - active employees synced with name, email, role, status, and license class (Full User, Employee Center, Retail User, External Center, and others)

  • Last activity - last login date per user, derived from the NetSuite login audit trail

  • License utilization - a breakdown of license slots in use versus available, helping you identify unused or over-provisioned licenses

  • Role visibility - the NetSuite roles assigned to each user, useful for access reviews and offboarding checks

To enable this flow, make sure the role you created in Step 2 includes the two additional permissions noted in that section:

  • View Login Audit Trail (Setup tab) - required to read last-login data

  • Employee Record (Lists tab) - required to read employee details

Previousmonday.comNextSalesforce

Last updated

Was this helpful?