Where configuration and state live

• Salesforce connection settings are stored in Forge app storage.
• The OAuth client secret is stored in Forge secret storage.
• OAuth access tokens are requested dynamically and cached for the current invocation.
• Smart Connected Item definitions and issue-to-record links are stored in Forge app storage.
• Comment and attachment pairing state is stored per linked issue and record pair.
• Production usage is license-gated, while development installs can still be tested.

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 selected Salesforce fields.
• Synchronized items can be manually linked or auto-managed by the scheduler.
• Linked records can expose field previews, a direct Salesforce link, refresh, and unlink actions.
• Associated Salesforce records can appear as read-only expandable groups below the primary linked record.
• Auto-managed links stay read-only in the issue panel but can still be refreshed.

Who installs the app

A Jira site admin installs the Salesforce Bridge for Jira and then opens the app from Jira admin settings > Apps.

• Install the published Marketplace listing into the target Jira Cloud site.
• Open the app from the left-side apps list in Jira administration.
• Confirm the app is connected before you create any Smart Connected Items.

What the admin page becomes

Once installed, the Jira admin page becomes the operating surface for the Salesforce connection, the Smart Connected Items table, and the latest sync state for each synchronized row.

• Connection summary: Login URL, Client ID, Org Name, Org ID, Instance URL.
• Smart Connected Items dashboard: mode, Jira scope, Salesforce source, mappings, and latest sync.
• Row actions: edit, delete, and manual refresh of the configuration list.

Recommended Salesforce-side access for the Run As user

• API Enabled on the user profile or permission set.
• Read access to object metadata so the bridge can load field catalogs.
• Read and update access on the Salesforce objects you plan to synchronize.
• Comment and feed access for CaseComment, FeedItem, and FeedComment where applicable.
• File access for ContentVersion, ContentDocument, and ContentDocumentLink.

Values you will enter into Jira

• Salesforce Login URL: login, test, or your My Domain base URL.
• OAuth Client ID: the value generated by the External Client App.
• OAuth Client Secret: the matching secret for that client.

The Jira admin page validates the credentials immediately by requesting a Salesforce access token and confirming the connected org and instance URL.

Connection form fields

• Salesforce Login URL: for example https://login.salesforce.com or your My Domain URL.
• OAuth Client ID: copied from Salesforce.
• OAuth Client Secret: copied from Salesforce.

Connected-state summary

• Connected status lozenge.
• Stored Login URL and OAuth Client ID.
• Salesforce Org Name and Org ID returned by validation.
• Salesforce Instance URL resolved from the token response.
• Revoke Connection button to clear the saved configuration.

When display-only is the right fit

• You want users to manually link a Salesforce record from the issue panel.
• You only need a readable preview of selected Salesforce fields.
• You want to reuse the same object preview across multiple Jira projects.
• You do not want the scheduler or Jira events to modify either side.

How the admin flow works

• Enter a display name.
• Select one or more Jira projects.
• Select the Salesforce module / object group and object.
• Select the Salesforce fields to show in the issue panel after linking.

One-Way Sync (Salesforce -> Jira)

• Salesforce is the source of truth for mapped field values.
• The scheduler applies Salesforce changes to Jira every five minutes.
• Optional auto-create can open Jira issues from new Salesforce records.
• Comment, attachment, and status sync can still be enabled where appropriate.

Two-Way Sync (Salesforce <-> Jira)

• The scheduler still pulls Salesforce changes into Jira.
• Jira issue update events can push mapped field changes back to Salesforce.
• Jira comment and attachment events can also push to Salesforce when enabled.
• This mode is best when Jira teams actively work the issue and Salesforce must stay aligned.

Custom Sync per Mapping

• Each mapped field chooses its own owner instead of following one global direction.
• Salesforce owns writes Salesforce values into Jira for that mapping.
• JSM owns pushes Jira issue field changes into Salesforce for that mapping.
• Both own allows two-way behavior for the individual mapped field.

Associated records and conditional status

• Association display can show related Salesforce records below the primary linked record.
• Conditional Sync Rules can move Jira issues based on a selected Salesforce field value.
• These options are configured in the same second step as field mappings, status, comments, and attachments.

How mappings work

A mapping pairs one Salesforce field with one Jira field. In one-way mode, the bridge only writes from Salesforce to Jira. In two-way mode, Jira issue update events can also push mapped Jira field changes back to Salesforce.

How custom field owners work

In Custom Sync per Mapping, each mapping includes a field owner. Choose Salesforce owns for Salesforce -> Jira, JSM owns for Jira -> Salesforce, or Both own for two-way synchronization on that one field.

When mappings are optional

You can create a synchronized Smart Connected Item with no field mappings when the goal is status-only synchronization, comment-only synchronization, attachment-only synchronization, associated record display, or manual linking without auto-create.

What the rule evaluates

A Conditional Sync Rule checks one Salesforce field on each eligible linked or newly discovered Salesforce record. The rule supports equality, inequality, empty, and not-empty checks. For picklist-like fields, the admin can select a Salesforce option value from the metadata-driven dropdown.

What happens when the rule is met

When a Salesforce record matches the configured condition, auto-create can create the Jira issue and the bridge uses the configured Jira status when condition is met. For already-linked records, scheduled sync and relevant link updates transition the Jira issue to that status when Jira exposes a valid workflow transition.

What the checkbox controls

Create Jira issue when condition is not met applies only when Auto-create Jira issues is enabled. When checked, new Salesforce records that do not match the rule can still create Jira issues and use the fallback status. When unchecked, those non-matching new Salesforce records are skipped by auto-create.

What happens when the rule is not met

The fallback Jira status still matters for records that are already linked, or for new records that are allowed through by the checkbox. In those cases, the bridge transitions the Jira issue to the configured Jira status when condition is not met when the workflow allows it.

What the toggle does

When enabled, the Jira issue panel looks up Salesforce records related to the primary linked record and groups them by record type. Common examples include Cases, Contacts, Opportunities, Activities, and other records exposed by the selected Salesforce object and relationship metadata.

What users see

Users see expandable groups under Associated Salesforce Records. Each returned record shows a compact preview of useful fields and an Open action when the bridge can build a Salesforce URL for that related record.

Forge-side access used by the app

• storage:app
• read:jira-work
• write:jira-work
• read:jira-user
• read:issue:jira
• write:issue:jira

Salesforce-side access the Run As user needs

• API access.
• Read access to Salesforce describe metadata for target objects.
• Read and update access on the objects selected in Smart Connected Items.
• Read access to related objects that should appear in associated record groups.
• Access to comment and feed objects used by the selected record type.
• Access to Salesforce Files APIs for attachment synchronization.

What each card shows

• The Smart Connected Item name plus the Salesforce module and object label.
• The current sync mode and status-sync context where applicable.
• The linked Salesforce record ID.
• A preview table containing the selected or mapped Salesforce fields.
• Open in Salesforce and Refresh actions.
• Unlink only for manual links.
• Associated Salesforce record groups when the admin enabled association display.

Record preview formatting

• Lookup search results adapt to the selected object's important fields.
• Cases typically display like 00001026 [Korvex Systems Sample Case Test].
• Other objects use the best identifier and descriptive fields available, such as Name [Email] or ContractNumber [Status].
• The issue panel preview itself uses the field names the admin selected in the configuration.

When links become auto-managed

• The five-minute scheduler finds a new Salesforce record that matches a synchronized item.
• Auto-create in Jira is enabled for that Smart Connected Item.
• The bridge creates the Jira issue and stores the link as scheduler-owned.

What Jira users can still do

• Open the linked Salesforce record.
• Refresh the record immediately.
• Read the mapped Salesforce preview fields.
• Work the Jira issue normally so mapped Jira changes can still flow back when enabled.

Mapped fields

• In one-way sync, Salesforce remains the source of truth for mapped field values.
• In two-way sync, Jira issue update events can push mapped field changes back to the linked Salesforce record.
• In Custom Sync per Mapping, each field follows its own owner: Salesforce owns, JSM owns, or both own.
• The admin controls exactly which fields participate in synchronization.

Status behavior

• Status sync uses the chosen Salesforce status-like field and Jira workflow status.
• Conditional Sync Rules can override generic status sync for the configured Smart Connected Item.
• The bridge looks for the closest safe alternative instead of requiring identical workflows.
• For Cases, Jira-to-Salesforce close handling uses the supported incident close behavior instead of faking an unsafe generic patch.

Comments and feed replies

• Cases use CaseComment for top-level comments.
• Case feed replies are also read from FeedItem and FeedComment.
• Other feed-capable records use FeedItem for top-level notes and FeedComment for replies.
• Reply threads are flattened into Jira comments because Jira comments do not preserve Salesforce feed threading one-to-one.

Attachments

• Salesforce Files are synchronized through ContentVersion, ContentDocument, and ContentDocumentLink.
• Scheduled sync and manual refresh can pull Salesforce files into Jira.
• New Jira attachments are uploaded to Salesforce quickly through Jira attachment events.
• Existing paired files are not duplicated. Deletions are not mirrored automatically.