Background runs pull eligible HubSpot updates into Jira on a fixed cadence.
Documentation validated against connector build on May 19, 2026
Technical deployment guide for the HubSpot Connector for Jira
This guide covers installation, HubSpot private app authentication, Smart Connected Items, custom per-field sync ownership, Conditional Sync Rules, associated records, and issue-panel operations for enterprise Jira deployments.
Marketplace app
Forge app
Jira admin page
HubSpot CRM
Custom sync
Issue, comment, and attachment events push qualifying changes back to HubSpot.
Larger files are skipped to stay inside platform runtime and payload boundaries.
Standard objects are curated and custom objects are discovered from the connected portal.
Fast Path
Deployment quick start in six steps
Install the app
A Jira site admin installs the app from Atlassian Marketplace and opens the HubSpot Connector admin page from Jira administration.
Create a HubSpot private app
In HubSpot, create a private app for this integration and grant the CRM, notes, and files permissions your team needs.
Gather the Hub ID and token
Copy the HubSpot portal ID and the private app token. You will enter both into the Jira admin page connection form.
Save the HubSpot connection
Enter the HubSpot Portal ID and Private App Token, then save the connection. The token is stored securely in Forge storage.
Create Smart Connected Items
Choose display-only, one-way sync, two-way sync, or custom per-mapping sync behavior, then set Jira scope, HubSpot object, field mappings, and optional sync features.
Link or auto-create records
Jira users can link HubSpot records from the issue panel, and synchronized items can optionally auto-create Jira issues, apply Conditional Sync Rules, and show associated HubSpot records for extra context.
Architecture
How the connector works
Current sync model in this build
The scheduled trigger runs every five minutes. It can create Jira issues for new HubSpot records when auto-create is enabled, evaluates Conditional Sync Rules, and applies eligible HubSpot-to-Jira updates for fields, status, comments, and attachments on linked records.
Jira-to-HubSpot updates are event-driven. Jira issue updates push eligible field and status changes, Jira comment events push comments, and Jira attachment events push new files to HubSpot. In Custom Sync per Mapping mode, each field mapping decides whether HubSpot, Jira, or both sides can own updates for that field.
Where configuration lives
- HubSpot connection settings are stored in Forge app storage.
- The private app token is stored in Forge secret storage when available.
- Smart Connected Item definitions and issue-to-record links are stored in Forge app storage.
- Paid environments are license-gated, while development installs bypass Marketplace license checks.
How Jira users see the integration
- The issue panel shows one card per Smart Connected Item that applies to the Jira project.
- Display-only items wait for a manual link before showing HubSpot fields.
- Synchronized items can either be manually linked or auto-managed by the scheduler.
- Linked records can expose field previews, associated record groups, a direct HubSpot link, refresh, and unlink actions.
Object Catalog
Supported HubSpot objects in this connector
| Module / object group | Objects exposed by the connector | Notes |
|---|---|---|
| HubSpot CRM | Contacts, Companies, Deals, Tickets, Products, Line Items, Quotes, Leads | These are the most common CRM records for display-only, one-way, and two-way flows. |
| HubSpot Activities | Notes, Meetings, Calls, Emails, Tasks, Appointments | Useful when Jira issues need to reference or sync activity-oriented records. |
| HubSpot Commerce | Invoices, Orders, Payments, Subscriptions | Available when the connected token can read those commerce objects. |
| HubSpot Operations | Projects, Services, Listings | Operations objects are included in the curated connector catalog. |
| HubSpot Marketing | Marketing Events | Marketing records can be targeted the same way as other supported HubSpot objects. |
| Custom objects | Live HubSpot custom object schemas discovered from the portal | The available list depends on the connected HubSpot account and the private app token scopes. |
What admins should expect
The connector combines a curated default catalog with live metadata. That means standard objects stay predictable, while custom objects can still appear automatically when HubSpot exposes them to the connected token.
Terminology
Key terms used in this guide
Display-only Smart Connected Item
A manual mapping that lets Jira users link a HubSpot record in the issue panel and view selected fields. It does not auto-create Jira issues or run scheduled field sync.
Synchronized Smart Connected Item
A one-project, one-issue-type mapping that can create Jira issues from HubSpot and keep mapped fields aligned in one direction or both directions.
Custom Sync per Mapping
A synchronized mode where every mapped field has its own owner: HubSpot owns, Jira owns, or both own. This lets one Smart Connected Item combine HubSpot-to-Jira, Jira-to-HubSpot, and two-way field behavior.
Conditional Sync Rule
An optional rule that evaluates a HubSpot property and moves the linked Jira issue to the configured status when the condition is met. The rule can also decide whether new records that do not meet the condition should still create Jira issues.
Associated records
Read-only HubSpot records related to the linked record, such as associated contacts or companies for a deal. They provide context in the issue panel without becoming extra Jira links or sync targets.
Auto-managed link
A record link created by the scheduler when auto-create is enabled. Auto-managed records are read-only in the issue panel and can be refreshed but not manually unlinked there.
HubSpot status field
A field detected from HubSpot metadata that behaves like a stage or status. Status sync relies on one of these fields when the chosen object exposes one.
Admin Setup
Install from Atlassian Marketplace
Install the app on the Jira Cloud site
Install the HubSpot Connector from Atlassian Marketplace using a Jira site admin account. After installation, open Jira administration and locate the app under the Marketplace apps area.
Confirm the license state
Paid and trial environments must have an active Marketplace license. If the license is missing or expired, both the admin page and the issue panel will show a license-required message and block normal usage.
Prepare HubSpot credentials before the first save
The app will not let you complete setup until you provide a valid HubSpot Portal ID and private app token, so create the private app first and keep both values ready.
HubSpot
Create the HubSpot private app
Connection help shown inside Jira
While the app is not connected, the Jira admin page shows a helper message titled Need help connecting to HubSpot? with a link to the HubSpot private app guide.
Create a private app in HubSpot
Create a private app in the target HubSpot account. This token is the app's single authentication secret for all object, notes, and files access.
Add the scopes your use case needs
Grant access to every HubSpot object family you plan to expose in Smart Connected Items. If you want comment sync or attachment sync, the token must also have the HubSpot permissions needed for notes and files operations.
Copy the Hub ID and token
Save the HubSpot portal ID and the generated private app token. You will use both values in the Jira admin page. The app validates that the entered portal ID matches the Hub ID returned by the token.
Important validation behavior
If the token lacks access to an object, HubSpot usually returns a 403 error that names one or more required scopes. The connector turns that into a Jira-friendly message that tells the admin exactly which HubSpot scopes to add before reconnecting.
Jira Admin
Authenticate in the Jira admin page
Connection form fields
- HubSpot Portal ID: numeric Hub ID, for example
12345678. - Private App Token: password-style field, for example
pat-na1-.... - Save connection: validates the token and stores it securely.
Connected-state summary
- Connection Configuration to HubSpot heading.
- Connected lozenge.
- Portal ID, Private App ID, and a stored-securely token indicator.
- Revoke Connection button to disconnect the portal.
Validation cases called out by the app
The connector rejects empty tokens, mismatched portal IDs, and invalid HubSpot
credential responses. It also includes a specific recovery message for certain
pat-eu1- tokens that return a HubSpot 404 during validation.
Core Configuration
Create Smart Connected Items
Smart Connected Items are the core configuration objects for this connector. The admin dashboard shows one unified table for display-only, one-way, two-way, and custom per-mapping items:
Entry point
From the dashboard, admins use Create Smart Connected Item and first choose the synchronization mode. The modal then switches into the correct flow for display-only setup, standard synchronized setup, or custom per-field sync ownership.
Display-only item
Use this when Jira users only need to search for a HubSpot record, link it manually, and view selected properties in the issue panel. No scheduled field sync runs for this mode.
Synchronized item
Use this when one Jira project and issue type should connect to one HubSpot object. Synchronized items can auto-create Jira issues and can sync fields, status, comments, and attachments depending on the options you enable.
Custom Sync per Mapping
Use this synchronized mode when different fields need different owners. For example, HubSpot can own the Jira summary, Jira can own an internal triage field, and both systems can share ownership of a description field.
Associated record display
Use this option when Jira users need to see related HubSpot CRM records, such as contacts or companies associated with the linked deal, ticket, or other object.
Display-only Mode
Configure display-only Smart Connected Items
Choose the None mode
This flow is used when the issue panel should only display selected HubSpot fields for a record after a Jira user manually links it.
Set the display name and Jira projects
Display-only items can target multiple Jira projects. The admin chooses every project that should use the same HubSpot object and field preview.
Select the HubSpot module / object group and object
The object list is loaded from HubSpot metadata for the selected module. Once the object is chosen, the field selector loads the full live property metadata.
Choose the fields to display in the issue panel
The admin selects one or more HubSpot fields. Jira users will see those values in the issue panel after they link a record.
Optionally show associated records
Enable association display when the issue panel should also show related HubSpot records for context. Associated records are read-only and do not start a scheduled sync.
Synchronized Modes
Configure synchronized Smart Connected Items
Step 1: choose the basics
- Display name.
- Synchronization mode.
- Target Jira project.
- Target Jira issue type.
- HubSpot module / object group.
- HubSpot object.
Step 2: choose sync behavior
- Auto-create Jira issues from new HubSpot records.
- Associated HubSpot record display.
- Field mappings between Jira and HubSpot.
- Conditional Sync Rules.
- Status sync.
- Comments sync.
- Attachments sync.
What the mode names mean in the UI
One-Way Sync (HubSpot -> Jira) keeps HubSpot as the source of truth for mapped fields. Two-Way Sync (HubSpot <-> Jira) keeps mapped fields aligned in both directions. Custom Sync per Mapping lets each mapped field decide whether HubSpot owns, Jira owns, or both sides own that field.
Save-time validation
The app blocks save when required Jira fields are still unmapped, when a Jira field is mapped more than once, or when the selected Jira field types are not yet safe for the scheduled sync to transform. In Custom Sync per Mapping mode, each field mapping also needs a field owner before the item can be saved.
Field Ownership
Field mapping rules
How mappings work
A mapping pairs one HubSpot property with one Jira issue field. In one-way mode the connector writes HubSpot values into Jira. In two-way mode, Jira issue field changes can also flow back to HubSpot.
How custom field owners work
In Custom Sync per Mapping, every mapping includes a field owner. Choose HubSpot owns for HubSpot -> Jira, Jira owns for Jira -> HubSpot, or Both own for two-way synchronization on that individual field.
When mappings are optional
You can create a synchronized Smart Connected Item with no field mappings if the goal is status-only synchronization, comment-only synchronization, attachment-only synchronization, or manual linking with associated record context.
What the dashboard shows
The grid summarizes each mapping direction. A right arrow means HubSpot owns that field, a left arrow means Jira owns it, and a two-way indicator means both sides can update the mapped value.
Direction is per field
Custom Sync per Mapping changes only mapped field ownership. Status sync, comments sync, attachments sync, auto-create, Conditional Sync Rules, and associated record display still follow their own enabled or disabled settings on the Smart Connected Item.
Conditional Routing
Conditional Sync Rules
What the rule evaluates
A Conditional Sync Rule checks one HubSpot property on each eligible linked or newly discovered HubSpot record. The admin selects the property, operator, and expected value from the metadata available for the selected HubSpot object.
What the rule changes in Jira
The admin chooses one Jira status for records that meet the condition. If a record does not meet the condition, the connector either skips auto-creating the Jira issue or uses the configured not-met status, depending on the checkbox described below.
How the not-met checkbox works
Create Jira issue when rule is not met applies only when Auto-Create Issue is enabled. When checked, new HubSpot records that fail the condition can still create Jira issues. When unchecked, new non-matching HubSpot records are ignored by auto-create and no Jira issue is created.
What happens to existing links
The checkbox controls new issue creation for records found by the scheduler. Already linked Jira issues can still be refreshed and synchronized according to the Smart Connected Item settings and the Jira workflow transitions available at that time.
| Configuration field | Meaning | Example from the UI |
|---|---|---|
| HubSpot property | The HubSpot property the connector evaluates for the condition. | Deal Type |
| Operator | The comparison rule used against the selected property value. | Equals |
| Value | The expected value for the condition. | New Business |
| Jira status when condition is met | The workflow status used when the HubSpot record satisfies the rule. | To Do |
| Create Jira issue when rule is not met | Controls whether auto-create should still create a Jira issue for new HubSpot records that fail the condition. | Checked |
| Jira status when condition is not met | The fallback workflow status used when the record does not satisfy the rule and a Jira issue exists or is allowed to be created. | In Progress |
How this interacts with status sync
Conditional statuses take precedence over the generic status synchronization target for that Smart Connected Item. Field mappings still follow the selected sync mode or custom field owner settings, while comments and attachments continue to follow their own switches.
Use the checkbox as an auto-create filter
Leave Create Jira issue when rule is not met unchecked when the rule should act as a gate for Jira issue creation. Check it when all eligible HubSpot records should create Jira issues, but non-matching records should start in a different Jira status.
Workflow transition requirement
Jira must expose a transition from the issue's current status to the configured target status. If the workflow does not allow that move, the connector cannot force the issue into the selected status.
Issue Context
Display associated HubSpot records
What the toggle does
When enabled, the Jira issue panel looks up HubSpot records associated with the linked record and groups them by object type. Common examples include contacts and companies associated with a deal, or related CRM records exposed by HubSpot associations.
What users see
Users see expandable groups under the linked HubSpot record. Each returned record shows a compact preview of useful fields and an Open action when the connector can build a HubSpot URL for that associated record.
Read-only context
Associated records are displayed for context. They do not create Jira links, do not become sync targets, and do not change the main linked HubSpot record. The primary linked record remains the only record controlled by the Smart Connected Item.
Permission boundary
The private app token must be able to read the associated object types. If users expect associated contacts or companies but those groups are empty, confirm that the token has the relevant HubSpot object scopes and that associations exist in HubSpot.
Behavior Matrix
Sync options matrix
| Option | What it does | Important notes |
|---|---|---|
| Automatically create Jira issues from new HubSpot records | Lets the scheduled trigger create new Jira issues for records that match the Smart Connected Item. | When off, users can still manually search and link records from the issue panel. |
| Field mappings | Defines how HubSpot properties populate Jira issue fields, or which fields stay aligned in two-way and custom modes. | Each Jira field can only be mapped once. Custom mode also requires a field owner for each mapping. |
| Custom field owner | Lets each mapped field decide whether HubSpot owns, Jira owns, or both sides own updates. | Only applies to Custom Sync per Mapping. Other sync modes use the selected global direction. |
| Associated records display | Shows related HubSpot CRM records in expandable issue-panel groups. | Read-only context only. Associated records do not become separate Jira links or sync targets. |
| Conditional Sync Rules | Evaluates a HubSpot property, routes matching records to a configured Jira status, and can gate auto-create for non-matching records. | The Create Jira issue when rule is not met checkbox decides whether new non-matching HubSpot records are skipped or still created in Jira with the fallback status. |
| Status sync | Aligns Jira workflow status with a detected HubSpot status-like field. | Even when the Smart Connected Item is one-way, status sync still behaves bidirectionally and the newest side wins. |
| Comments sync | Mirrors HubSpot notes into Jira and pushes Jira comments back to HubSpot. | Deletions are not removed automatically. |
| Attachments sync | Reconciles unmatched Jira and HubSpot attachments during scheduled sync, manual linking, and manual refresh. | Jira attachment events push new files quickly, connector-managed Jira comments are added for synced files, and files over 10 MB are skipped. |
Permissions
Permissions and scope reference
Forge scopes in the manifest
storage:appread:jira-workwrite:jira-workread:jira-userread:issue:jirawrite:issue:jira
HubSpot private app scope guidance
- Add object scopes for every HubSpot object family you plan to configure.
- Add object scopes for associated record types that should appear in the issue panel.
- Enable notes access if comments sync is required.
- Enable files access if attachment sync is required.
- If a scope is missing, the connector surfaces the exact HubSpot scope names returned by the API.
Jira User Guide
Issue panel overview
Before the app is usable
The issue panel can show License required, HubSpot connection not configured, or No Smart Connected Items for this project depending on the current admin setup state.
What a Smart Connected Item card shows
Each card shows the Smart Connected Item name, HubSpot module, HubSpot object, sync mode, status-sync indicator when relevant, and either a linked record preview table or a link button when no record is linked yet. Custom mapping items also show the configured sync mode so users can see that field ownership is managed per mapping.
What appears for linked records
When a record is linked, the card shows the linked record ID, a preview table of the selected or mapped fields, an Open in HubSpot action, a Refresh action, and an Unlink action when the link is manually managed. If associated records are enabled, the card also shows expandable related-record groups below the linked record preview.
What associated records add
Associated records give Jira users read-only context from HubSpot without changing the primary link. For example, a linked deal can show associated contacts and companies with their own Open actions.
Manual Flow
Link, refresh, and unlink
Click Link on the issue-panel card
The modal title is Link a HubSpot record. It prompts the user to enter the record ID for the selected HubSpot module and object.
Search by name or title
The modal includes a field labeled Search by name/title with the
placeholder Start typing to search HubSpot records. Matching records
appear as selectable results.
Use Refresh for an immediate pull
Refresh pulls HubSpot data into Jira right away instead of waiting for the next five-minute scheduled run. This is useful after editing the record in HubSpot.
Use Unlink only on manual links
The Unlink action appears only for manually managed links. Auto-managed links created by the scheduler stay read-only in the issue panel.
Scheduled Flow
Auto-managed links created by the scheduler
How the issue panel describes auto-managed records
When a Jira issue was linked automatically by a synchronized Smart Connected Item, the issue panel explains that the linked HubSpot record is read-only there and can still be refreshed without waiting for the next scheduled run.
When auto-managed links happen
- Only synchronized Smart Connected Items can auto-create Jira issues.
- The auto-create checkbox must be enabled.
- If Conditional Sync Rules are enabled and Create Jira issue when rule is not met is unchecked, records that fail the rule are skipped by auto-create.
- The selected Jira issue type must have enough supported mappings to create issues safely.
What users can still do
- Open the linked HubSpot record.
- Refresh the preview.
- Review mapped field values and status information.
- Review associated HubSpot records when association display is enabled.
- See comments and attachment effects as they sync over time.
HubSpot Effects
What changes in HubSpot after linking
Field updates
One-way mode applies HubSpot changes to Jira. Two-way mode also allows Jira issue updates to flow back to the linked HubSpot object. Custom Sync per Mapping follows the owner selected for each mapped field.
Custom field ownership
Fields owned by HubSpot are updated from HubSpot into Jira. Fields owned by Jira are pushed back to HubSpot from Jira issue updates. Fields owned by both sides can update in either direction according to the connector's normal sync processing.
Status changes
When status sync is enabled and the object exposes a suitable HubSpot status field, Jira transitions and HubSpot status changes can update each other.
Conditional status routing
When a Conditional Sync Rule is enabled, the selected HubSpot property determines the Jira status for matching records. The not-met checkbox controls whether new non-matching HubSpot records are skipped or still created with the fallback Jira status.
Associated records
Associated HubSpot records are read for issue-panel context only. They are not updated, linked, unlinked, or synchronized as separate Smart Connected Item targets.
Comments via HubSpot notes
HubSpot notes are the connector's persistence model for synced comments. Jira comments can create or update connector-managed notes in HubSpot.
Attachments via HubSpot files and notes
Files are uploaded to HubSpot and associated through notes. The connector also adds Jira-side evidence so users can see where synced files came from.
Traceability
Connector-managed HubSpot notes
| Note type | Connector marker text | Purpose |
|---|---|---|
| Issue link note | [HubSpot Connector for Jira] Issue link note |
Marks the relationship between a HubSpot record and a Jira issue. |
| Comment sync note | [HubSpot Connector for Jira] Comment sync note |
Tracks Jira comments that have been mirrored into HubSpot. |
| Jira attachment sync note | [HubSpot Connector for Jira] Jira attachment sync note |
Tracks Jira files that were uploaded and associated in HubSpot. |
Operations
Troubleshooting
The connection cannot be saved
Check that the HubSpot Portal ID matches the Hub ID behind the private app token.
If the token is an EU token starting with pat-eu1- and validation
still fails, rotate the token and try again. Also verify the Marketplace license is active.
Objects or fields do not appear in the selector
The selected token may not have access to that HubSpot object family, or the portal may not expose metadata for it. Custom-object availability depends on live HubSpot schema discovery and the token's permissions.
Auto-create is enabled but Jira issues are not being created
The chosen issue type may still require unmapped Jira fields, or the mapping may include unsupported Jira field types. The scheduled trigger also runs every five minutes, so new records are not created instantly.
Comments, status, or attachments are not syncing
Confirm that the corresponding sync checkbox is enabled on the Smart Connected Item, that the token has the required HubSpot scopes, and that the chosen object exposes a usable status field when status sync is expected.
A custom mapped field is not syncing in the expected direction
Check the field owner on that specific mapping. HubSpot owns only pulls HubSpot values into Jira, Jira owns only pushes Jira values into HubSpot, and Both own allows the field to participate in two-way updates.
A Conditional Sync Rule is not changing the Jira status
Confirm that the HubSpot property still has the expected value and that the Jira workflow exposes a transition from the issue's current status to the configured target status. The connector cannot bypass Jira workflow rules.
Non-matching HubSpot records are not creating Jira issues
Check whether Create Jira issue when rule is not met is enabled on the Conditional Sync Rule. If it is unchecked, the scheduler intentionally skips new HubSpot records that do not satisfy the rule, even when Auto-Create Issue is enabled.
Associated records are empty in the issue panel
Verify that association display is enabled on the Smart Connected Item, that the linked HubSpot record has associated records in HubSpot, and that the private app token can read the associated object types.
Files or comments were deleted on one side but still appear on the other
This is expected in the current build. Comment deletions and attachment deletions are not removed automatically by the connector after they have already synced.
Known Limits
Current limitations and operational notes
Functional limits
- Display-only Smart Connected Items do not run scheduled synchronization.
- Attachment sync skips files over 10 MB.
- Status sync requires a detectable HubSpot status-like field.
- Conditional Sync Rules require valid Jira workflow transitions to the selected statuses.
- The not-met auto-create checkbox only affects new Jira issue creation when Auto-Create Issue is enabled.
- Comment and attachment deletions are not mirrored automatically.
Operational limits
- Auto-create is only available for synchronized items.
- Object and field availability depends on HubSpot permissions and portal metadata.
- Associated records are read-only issue-panel context and are not independent sync targets.
- Custom Sync per Mapping controls mapped fields only; status, comments, and attachments use their own feature toggles.
- Outside development installs, an active Marketplace license is required.
- Auto-managed issue-panel links are intentionally read-only.
References