Jira Integrations
Relevant source files
The following files were used as context for generating this wiki page:
The Jira Integration in Hoop allows organizations to synchronize infrastructure access sessions and ad-hoc executions with Jira Cloud. It facilitates automated ticket creation, custom field mapping, and issue state transitions based on session lifecycles. By integrating with Jira Service Management (JSM), Hoop ensures that every production access event is audited and tracked within the existing IT Service Management (ITSM) workflows.
The integration is scoped at the organization level and supports granular configuration through Issue Templates. These templates define how session metadata—such as the user performing the action, the script executed, and the connection tags—is mapped to Jira issue fields. Additionally, the system supports JSM Assets (CMDB) to link sessions to specific infrastructure objects.
Integration Architecture
The architecture consists of organization-wide configuration and connection-specific templates. The Hoop Gateway acts as the orchestrator, communicating with the Jira Cloud API using Basic Authentication (User and API Token).
Data Flow for Issue Lifecycle
When a session concludes, the gateway can automatically transition the linked Jira issue to a finalized state (e.g., "Done").
The transition logic is managed by the TransitionIssue function, which fetches available transitions for a specific issue key and applies the one matching the template configuration.
Sources: gateway/jira/issuesapi.go:23-58, gateway/api/integrations/jira.go:21-48
Configuration and Management
Integration settings are managed via the /integrations/jira endpoint. For security, non-admin users can verify if the integration is active, but the API Token is redacted in responses.
Integration Properties
| Field | Description | Constraints |
|---|---|---|
URL | The base URL of the Jira instance | Required |
User | The username for Basic Auth | Required |
APIToken | The Jira API Token | Required (Write-only for non-admins) |
Status | enabled or disabled | Required |
Sources: gateway/api/integrations/jira.go:55-75, gateway/api/openapi/openapiv3.json
Jira Issue Templates
Issue Templates define the structure of the tickets created in Jira. They are associated with specific Hoop connections and include mapping for automated fields, user prompts, and CMDB objects.
Mapping Types
- Preset: Automatically extracts data from the Hoop session context (e.g.,
session.user_email,session.script). - Custom: Uses a static value defined in the template.
- Prompt: Requires the user to provide input in the webapp before the session starts (e.g., "Reason for access").
- CMDB (JSM Assets): Integrates with the Jira Assets API to select objects from a schema.
Sources: gateway/models/jira_issue_templates.go:17-48, gateway/api/integrations/issuetemplates.go:193-242
Data Mapping and Presets
Hoop provides a set of internal variables that can be mapped to Jira custom fields using "Preset" mapping rules. If a script exceeds 32,700 characters, it is truncated to comply with Jira text field limits.
Available Preset Fields
| Preset Key | Description |
|---|---|
session.id | Unique identifier of the session |
session.user_email | Email of the user performing the action |
session.user_name | Display name of the user |
session.type | Connection protocol (e.g., database, custom) |
session.script | The actual command or SQL script executed |
session.webapp_link | URL to view the session replay in Hoop |
session.connection_tags.{key} | Values from tags assigned to the connection |
Sources: gateway/jira/issuesapi.go:145-168, gateway/api/integrations/issuetemplates.go:15-38
Plan Limitations (Free vs. Enterprise)
The Jira integration enforces specific limits based on the organization's license type. Organizations on the Free (OSS) plan are restricted to a single template and a limited number of mapping rules.
| Feature | Free Plan Limit | Enterprise Plan Limit |
|---|---|---|
| Total Templates | 1 | Unlimited |
| Preset Mapping Rules | 1 | Unlimited |
| Custom Mapping Rules | 1 | Unlimited |
| Prompt Rules | 1 | Unlimited |
| CMDB Rules | 1 | Unlimited |
Sources: gateway/api/integrations/issuetemplates.go:49-65, gateway/api/integrations/issuetemplates.go:167-183
JSM Assets Integration
Hoop can query Jira Service Management (JSM) Assets to allow users to link sessions to configuration items. The GetAssetObjects function utilizes AQL (Asset Query Language) to filter objects by type, schema, or name.
The gateway constructs a query such as objectTypeId = "101" AND name LIKE "prod-db%" to retrieve relevant infrastructure objects.
Sources: gateway/api/integrations/issuetemplates.go:119-152, gateway/models/jira_issue_templates.go:40-48
Conclusion
The Jira Integration serves as a critical bridge between real-time infrastructure access and organizational compliance workflows. By leveraging flexible templates, preset session data mapping, and JSM Asset integration, Hoop automates the documentation of production interventions, ensuring that every session is backed by a corresponding Jira issue and transitioned correctly upon completion.