Skip to content
  • There are no suggestions because the search field is empty.

Workflow - Ticket | Assign Ticket Number to New Tickets

Use the Assign Ticket Number to New Tickets workflow

Automatically assigns a unique numeric Ticket Number to new HubSpot tickets using a ticket-based workflow and custom code. This ensures agents have a short, customer-quotable number instead of relying on HubSpot’s internal Record ID.

Tags: hubspot, tickets, workflows, custom-code, ticket-numbering, support-operations

Goal

This process ensures every HubSpot ticket has a customer-facing numeric Ticket Number.

The Ticket Number is used by agents and customers as the support reference number. It replaces the need to quote HubSpot’s internal Record ID, which is too long and not suitable for customer communication.

The final Ticket Number property is:

Property: ticket_number_numeric
Label: Ticket Number / Ticket Number Numeric
Object: Ticket
Field type: Number
Format: Unformatted
Decimals: 0
Currency: No
Unique value: Enabled
Customer-facing: Yes
Purpose: Stores the customer-quotable Ticket Number used by agents and customers.

Current System Behaviour

Historical Freshdesk tickets were backfilled before go-live.

New HubSpot tickets are now handled by the live workflow:

Workflow: Assign Ticket Number to New Tickets

When a new ticket is created without a Ticket Number, the workflow runs a custom code action that:

  1. Checks whether the enrolled ticket already has ticket_number_numeric.
  2. Searches existing tickets for the highest current ticket_number_numeric.
  3. Adds 1 to determine the next available number.
  4. Attempts to update the enrolled ticket.
  5. If HubSpot blocks the value because it is already in use, the code retries using the next number.
  6. If successful, the ticket receives the next available Ticket Number.

The workflow does not use HubSpot’s internal Record ID.

Why Custom Code Is Used

HubSpot workflows alone cannot reliably generate a global sequential ticket number.

A normal Ticket property cannot be used as a global counter because Ticket properties belong to individual tickets, not to the portal as a whole.

This means a workflow-only approach such as “add 1 to Ticket Sequence Number” is not valid for global ticket numbering.

Custom code is used because the workflow needs to:

  • look across existing tickets
  • find the highest assigned Ticket Number
  • calculate the next number
  • write that number back to the current ticket
  • handle duplicate-value conflicts if ticket creation happens concurrently

The ticket_number_numeric property is set as unique so HubSpot blocks duplicate Ticket Numbers.

Properties Used

Ticket Number Numeric

Property: ticket_number_numeric
Object: Ticket
Field type: Number
Format: Unformatted
Decimals: 0
Currency: No
Unique value: Enabled
Customer-facing: Yes
Visible to agents: Yes
Editable by agents: No, unless admin override is required

Description:
Customer-facing numeric ticket reference used by agents and customers. This value is automatically assigned to new HubSpot tickets and must remain unique.

Freshdesk Ticket ID

Property: Freshdesk Ticket ID
Object: Ticket
Field type: Number
Format: Unformatted
Decimals: 0
Currency: No
Unique value: Not required
Customer-facing: No
Visible to agents: Optional / hidden after migration

Description:
Original Freshdesk ticket reference retained for historical audit and migration traceability.

This property is no longer used for new ticket numbering, but should be kept for reference.

Workflow Configuration

Workflow Name

Assign Ticket Number to New Tickets

Workflow Description

Assigns the next available numeric Ticket Number to newly created HubSpot tickets. The workflow uses custom code to find the current highest ticket_number_numeric, add 1, and write the result to the current ticket. The ticket_number_numeric property is configured as unique so duplicate values are blocked by HubSpot if concurrent ticket creation occurs.

Workflow Type

Ticket-based workflow

Enrolment Criteria

All criteria must be met:

  • ticket_number_numeric is unknown
  • Create date is known

Re-enrolment

Re-enrolment should be turned off.

The workflow should only run once for a ticket that does not already have a Ticket Number.

Workflow Actions

Action 1: Custom Code

This is the only required workflow action.

There should be no additional Edit record action after the custom code action, because the custom code updates the enrolled ticket directly.

Custom Code Action Configuration

Custom Code Description

Assigns the next available unique numeric Ticket Number to the enrolled ticket. The code checks whether the ticket already has ticket_number_numeric, searches existing tickets for the highest current value, adds 1, then updates the enrolled ticket. If HubSpot rejects a value because the number is already in use, the code retries with the next number. This action relies on ticket_number_numeric being a unique, unformatted Number property with 0 decimals.

Secret

Secret name: PRIVATE_APP_ACCESS_TOKEN

Description:
Private app access token used by the custom code action to search existing tickets and update the enrolled ticket with the next available Ticket Number.

The code must reference this secret as:

process.env.PRIVATE_APP_ACCESS_TOKEN

Property Inputs

HubSpot uses the fields Key and Select a property.

Key is the variable name used by the code.
Select a property is the HubSpot property passed into the code.

Input 1

Key: hs_object_id
Select a property: Record ID

Description:
Passes the enrolled ticket’s HubSpot Record ID into the custom code so the code knows which ticket to update.

Input 2

Key: ticket_number_numeric
Select a property: Ticket Number Numeric

Description:
Passes the current Ticket Number value into the code so the code can skip the ticket if it already has a value.

Output Fields

status

Type: String
Description:
Shows whether the custom code action succeeded, skipped the ticket, or failed.

assignedTicketNumber

Type: Number
Description:
The Ticket Number assigned to the enrolled ticket by the custom code action.

attemptsUsed

Type: Number
Description:
Number of assignment attempts used before successfully assigning a unique Ticket Number.

message

Type: String
Description:
Readable result message from the custom code action for testing, troubleshooting, and workflow history review.

Custom Code Behaviour

The custom code:

  1. Gets the enrolled ticket ID.
  2. Checks whether the ticket already has ticket_number_numeric.
  3. If the ticket already has a number, the action skips the ticket.
  4. Searches tickets for the highest existing ticket_number_numeric.
  5. Calculates the next candidate number.
  6. Updates the enrolled ticket with the candidate number.
  7. If HubSpot rejects the value because it is already used, the code tries the next number.
  8. Repeats until successful or until the retry limit is reached.
  9. Returns output fields for workflow history and troubleshooting.

Starting Number Logic

The code includes a configured starting number.

The next assigned number is whichever is higher:

  • the highest existing ticket_number_numeric + 1
  • the configured START_FROM value

This prevents the workflow from assigning a number lower than the required go-live range.

Before editing the start number, first check the highest current ticket_number_numeric in HubSpot.

Duplicate Protection

ticket_number_numeric is configured as a unique property.

This means HubSpot should reject duplicate Ticket Numbers if two workflow executions attempt to assign the same value at the same time.

The custom code includes retry logic. If HubSpot blocks a duplicate value, the code tries the next number.

This is the key protection that makes the HubSpot-only solution workable without an external counter service.

Monitoring

Create and monitor a ticket view called:

Tickets Missing Ticket Number

Filters:

  • ticket_number_numeric is unknown
  • Create date is known

Expected result:

  • Tickets may briefly appear while the workflow is running.
  • Tickets should clear quickly.
  • Any ticket that remains in this view should be reviewed.

Validation Checks

After go-live, confirm:

  • New tickets receive ticket_number_numeric.
  • Ticket Numbers increment as expected.
  • Ticket view sorting by Ticket Number works numerically.
  • Workflow history shows the custom code action completed successfully.
  • The missing-number view is empty or clears quickly.
  • Agents can see Ticket Number on the ticket record.
  • Agents cannot edit Ticket Number unless they have admin-level access.

Operational Rules

Do not manually edit ticket_number_numeric unless correcting a controlled issue.

Do not reuse Ticket Numbers.

Do not disable the workflow unless ticket numbering needs to be paused.

Do not use Ticket Sequence Number.

Do not create a workflow action that tries to increment a Ticket property as a global counter.

Do not add an Edit record action after the custom code action unless the workflow design is deliberately changed.

Retired / Not Used

The following approach was discarded and should not be used:

  • Ticket Sequence Number as a Ticket property counter
  • Scheduled batch controller workflow
  • Daily scheduled numbering
  • Workflow-only add 1 action
  • Text-based Ticket Number sorting

These were not suitable because they did not provide reliable global sequential numbering for new tickets.

Troubleshooting

Ticket does not receive a number

Check:

  • Workflow is turned on.
  • Ticket meets enrolment criteria.
  • ticket_number_numeric is unknown.
  • Custom code action ran.
  • Private app token secret is available.
  • Private app has ticket access.
  • Workflow history contains no custom code errors.

Authentication error

If the workflow shows a 401 or invalid authentication error, check:

  • The secret name is exactly PRIVATE_APP_ACCESS_TOKEN.
  • The code references process.env.PRIVATE_APP_ACCESS_TOKEN.
  • The token value does not include the word Bearer.
  • The private app still exists and is active.
  • Scope changes have been committed in HubSpot.

Duplicate or unique value error

If HubSpot blocks a duplicate value, the code should retry with the next number.

If retry attempts are exhausted:

  • review workflow logs
  • check the highest assigned Ticket Number
  • confirm ticket_number_numeric is still unique
  • manually assign a number if needed
  • rerun or re-enrol only if safe

Ticket remains in the missing-number view

Check the workflow history for that ticket.

If the workflow did not enrol:

  • confirm Create date is known
  • confirm ticket_number_numeric is unknown
  • confirm the workflow was already active when the ticket was created

If the workflow failed:

  • review the custom code logs
  • resolve the error
  • manually re-enrol the ticket or manually assign the next available number

Related Notes

Workflow 1 for Freshdesk backfill is now off and is no longer required for new tickets.

Freshdesk Ticket ID remains available for historical reference only.

The active numbering process for new tickets is the custom code workflow using ticket_number_numeric.