Articles in this section

ServiceNow Hierarchy Integration

The ServiceNow integration keeps your ClickTime Clients and Jobs in sync with records in your ServiceNow instance. You choose which ServiceNow tables represent Clients and Jobs, map their fields to ClickTime, and the integration creates or updates the matching Clients and Jobs automatically. The sync is one‑directional (ServiceNow → ClickTime), runs on a schedule, and is incremental — each run only processes records that have changed since the previous run. This guide covers how the integration behaves, what you need before you start, how your ServiceNow data maps to ClickTime, how to configure it, and what to expect day‑to‑day.

Quick Navigation

How the Integration Works

The integration synchronizes records from your ServiceNow tables into ClickTime Clients and Jobs. Syncing is one‑directional: changes flow from ServiceNow into ClickTime, never the other way. Two things drive a sync:

  • A scheduled incremental sync — runs automatically on a set schedule (every 30 minutes by default) and processes only the records that have changed since the last run.
  • An optional re‑sync from a date — lets you reprocess all records changed since a date you specify, without waiting for the schedule.

As part of setup, you decide:

  • Which ServiceNow table represents your Clients and which represents your Jobs (or turn either off).
  • How each ServiceNow field maps to the matching ClickTime field.
  • Which field indicates whether a record is active, and which values count as active.
  • A default ClickTime Client for any Job that cannot resolve a parent Client from ServiceNow.

Note: This integration does not use real‑time ServiceNow events. Changes you make in ServiceNow appear in ClickTime on the next scheduled sync (within 30 minutes by default), or when you run a re‑sync from a date.

Before You Begin

Two things must be in place before the integration can connect to ServiceNow:

  • ServiceNow Instance URL — your instance base URL (for example, https://instance.service-now.com), entered on the Configuration page. This is used for all ServiceNow API calls.
  • ServiceNow connection — a valid ServiceNow connection (OAuth or, where applicable, Basic credentials). Follow Setting Up the ServiceNow OAuth Connection below to register the OAuth application in ServiceNow and configure the connection.

Important: If the ServiceNow connection or Instance URL is missing or invalid, the field mapping and active‑value screens will not load and will surface a connection error. Complete the OAuth connection setup first.

Setting Up the ServiceNow OAuth Connection

The integration connects to ServiceNow using OAuth. You configure this once by registering an OAuth application in ServiceNow, then entering the generated credentials into the ClickTime connection. You’ll need an account in ServiceNow with permission to create an Application Registry entry.

Step 1 — Create a new Application Registry entry

In ServiceNow, navigate to the Application Registry and start a new inbound integration:

  1. Go to All → System OAuth → Application Registry.
  2. Click New.
  3. Select New Inbound Integration Experience, then New Integration.
  4. Choose OAuth — Authorization code grant.

Step 2 — Configure the application and scope

Complete the application form:

  • Name — enter a descriptive name, for example ClickTime Integration.
  • Redirect URL — enter https://oauth2.prismatic.io/callback.
  • OAuth Entity Scopes — under the related list, create a new scope and make sure it includes permissions for the Table API so the integration can read your records.
  • Click Submit (or Update) to save the entry.

Important: After you submit, ServiceNow generates a Client ID and Client Secret. Copy both values somewhere secure right away — you’ll need them for the ClickTime connection, and the secret may not be fully retrievable later.

Step 3 — Enter the connection details in ClickTime

When the ClickTime–ServiceNow integration prompts you for OAuth connection details, enter the following. Replace [your-instance] with your own ServiceNow instance name (for example, dev12345).

Field Value
Authorize URL https://[your-instance].service-now.com/oauth_auth.do
Token URL https://[your-instance].service-now.com/oauth_token.do
Client ID Paste the Client ID from Step 2.
Client Secret Paste the Client Secret from Step 2.

Tip: Once the OAuth connection is saved and authorized, return to the setup wizard. The field mapping and active‑value screens will now be able to read your ServiceNow tables and fields.

Default Behavior

With the standard configuration in place, the integration will:

  • Run an incremental sync every 30 minutes.
  • Sync both Clients and Jobs (each can be turned off independently).
  • On its very first run, perform a SEED pass covering the previous 90 days that links existing ClickTime records to their ServiceNow counterparts by Client Number / Job Number without overwriting any existing ClickTime data.
  • Query the ServiceNow tables you selected as the Client Record Type and Job Record Type.
  • Process only records whose ServiceNow updated timestamp is newer than the last successful sync.

Important: The first sync after the integration is enabled runs in SEED mode. It matches and links records that already exist in ClickTime but will not change their data. Regular syncing (creating and updating records) begins with the scheduled runs that follow.

Tip: To disable syncing for a record type entirely, select --DO NOT SYNC-- as the Client Record Type or Job Record Type. That entity path is then skipped on every run.

How ServiceNow Data Maps to ClickTime

You tell the integration which ServiceNow table holds your Clients and which holds your Jobs, then map the fields on those tables to ClickTime fields.

Choosing the Client and Job tables

ClickTime entity What you select
Client A ServiceNow company, account, or department table — or a matching custom (u_*) table.
Job A table that references your Client table, or a work/project table. Selecting a Client table first helps surface the right Job tables.

Both selectors include a --DO NOT SYNC-- option so you can sync Clients only, Jobs only, or both.

What gets set on a Client

ClickTime field Where it comes from
Client Number / External ID The ServiceNow record’s sys_id
Name Your mapped name field (truncated to 50 characters)
Short Name Optional mapping, or defaults to the Name
Active status From your active‑status field plus the active values you select — or active if set to “Always Active”
Accounting Package ID Optional mapping
Custom fields Any additional fields you map

What gets set on a Job

ClickTime field Where it comes from
Job Number / External ID The ServiceNow record’s sys_id
Name Your mapped name field (truncated to 50 characters)
Parent Client Your mapped reference field pointing to the Client record (optional)
Short Name Optional mapping, or defaults to the Name
Active status From your active‑status field plus active values — or active if set to “Always Active”
Start Date, End Date, Accounting Package ID Optional mappings
Custom fields Any additional fields you map

Note: The unique identifier for both Clients and Jobs is always the ServiceNow sys_id. ClickTime uses it to recognize the same record on future syncs, so it stays stable even if names or other fields change.

Field Mapping

Field mapping is configured on the Field Mapping page of the setup wizard. At a minimum you map the name and active‑status fields for each entity you are syncing; the rest are optional.

  • Client name — the ServiceNow field that supplies the Client name.
  • Client active status — a choice field indicating active/inactive, or Not Mapped (Always Active).
  • Job name — the ServiceNow field that supplies the Job name.
  • Job parent (Client link) — the reference field on the Job table that points to its parent Client.
  • Job active status — a choice field, or Not Mapped (Always Active).
  • Optional field mappings — map additional ServiceNow fields to ClickTime standard or custom fields for both Clients and Jobs.

Tip: If the field mapper shows too many or too few ServiceNow fields, adjust ServiceNow Field Types on the Configuration page to control which column types are offered for mapping.

Active Status

If you map an active‑status field, you then use Active Value Selections (on the Value Mapping page) to tell the integration which choice values mean “active.”

  • Select one or more choice values that should mark a Client or Job as active. Any other value marks the record inactive.
  • If you set active status to Not Mapped (Always Active), every synced record is treated as active and the value‑mapping page shows an informational label instead of a picker.
  • If active status is mapped but the choice values cannot be loaded, all records are treated as active.

Setting Up the Integration

Setup is completed through a configuration wizard. The pages, in order, are:

  1. Configuration — ServiceNow Instance URL, ClickTime connection, notification settings, and ServiceNow field types.
  2. Client Mapping — choose the ServiceNow table for Clients.
  3. Job Mapping — choose the ServiceNow table for Jobs.
  4. Field Mapping — map the ServiceNow fields to ClickTime fields.
  5. Value Mapping — set the default Client and active values.
  6. Finalize — confirm the sync schedule, name formats, and whether Client and Job sync are enabled.

Settings you control

Setting What it does
ServiceNow Instance URL Your ServiceNow instance base URL.
ClickTime Connection Your ClickTime API key.
Notification Email Address Where error and notification emails are sent.
Disable Emails Turns notification emails off.
Client Record Type The ServiceNow table used for Clients (or --DO NOT SYNC--).
Job Record Type The ServiceNow table used for Jobs (or --DO NOT SYNC--).
Field Mappings Your field mapping choices.
Default Client The fallback ClickTime Client for Jobs with no resolved parent.
Active Value Selections The choice values that mean “active.”

Note: The ServiceNow connection, database, email delivery, sync schedule, record filters, name formats, and the master Client/Job sync switches are managed by ClickTime during setup. Client and Job sync can be turned off temporarily during testing without removing the integration.

Client and Job Name Formats

How names appear in ClickTime is controlled by the name format settings (configured during setup):

  • Client Name Format — Name (default) shows the mapped name only; ClientNumber--Name prefixes the Client Number.
  • Job Name Format — Name (default) shows the mapped name only; JobNumber--Name prefixes the Job Number.

How Syncing and Change Detection Work

The integration runs in one of two modes:

Mode When it runs What it does
SEED The first time the integration is enabled (90‑day lookback) Links existing ClickTime records to ServiceNow by Client Number / Job Number, without changing their data.
SYNC Every scheduled run, and re‑syncs from a date Creates new records and updates changed records.

Each scheduled sync is incremental: it only looks at ServiceNow records whose updated timestamp is newer than the last successful sync, so unchanged records are skipped entirely. When a changed record is found, the matching ClickTime record is created or updated as needed. If a record is inactive and the matching ClickTime record is already inactive, it is skipped to avoid unnecessary updates.

Re-syncing from a Specific Date

If you need to reprocess records that changed before the last sync — for example, after a bulk update in ServiceNow or to recover from a gap — a re‑sync can be run from a date you specify. This moves the sync starting point back to that date so the next run reprocesses everything changed since then.

Tip: Use a re‑sync from a date to backfill after large or historical ServiceNow changes rather than waiting for records to be touched again.

Linking Existing ClickTime Records

If ClickTime already contains Clients and Jobs that should be tied to ServiceNow records, a one‑time reverse seed can backfill those links. It matches existing ClickTime records to ServiceNow using their Client Number and Job Number so the integration recognizes them as the same records going forward. This is typically run once during onboarding.

Sync Behaviors and Troubleshooting

Common situations and how the integration handles them:

Situation What happens
A Job has no resolvable parent Client and no default Client is set The Job is skipped for that run (result: JOB-SKIPPED-CLIENTNOTFOUND).
A record is inactive and active status is not mapped The record is logged and skipped (result: CLIENT-SKIPPED-INACTIVE / JOB-SKIPPED-INACTIVE).
A create or update call fails The item is retried once after a short delay; the outcome is recorded in the logs.
A record is created or updated An optional notification email can be sent (unless emails are disabled).
Syncs appear to stop running A safety lock prevents overlapping runs. If a run ends unexpectedly while holding the lock, later runs are skipped until it clears automatically (within about 4 hours) or is cleared by ClickTime.
Mapping or active-value screens show a connection error The ServiceNow connection or Instance URL is missing or invalid — see Before You Begin and Setting Up the ServiceNow OAuth Connection.

Heads up: If Jobs are being skipped unexpectedly, check that each Job either maps to a valid parent Client reference or that a Default Client is configured on the Value Mapping page. A default Client is required for Job sync whenever parent Client references are not mapped or cannot be matched.

Things to Know

  • Syncing is scheduled and incremental, not real‑time. Changes in ServiceNow appear in ClickTime on the next scheduled run (or when you re‑sync from a date), and each run only processes records changed since the last sync.
  • Client and Job names are truncated to 50 characters when written to ClickTime.
  • A default Client is needed for Jobs without a mapped parent. Set one on the Value Mapping page to avoid skipped Jobs.
  • Record filters can scope what syncs. Additional ServiceNow query filters for Clients and Jobs can be applied during setup so only matching records are pulled in.
  • The field mapper is tunable. Use ServiceNow Field Types on the Configuration page if the mapper shows too many or too few fields.

Comments

0 comments

Article is closed for comments.