Basic concepts

Overview

Unity Cloud Collaboration's Jira Management features provide a robust integration between Unity projects and Jira, enabling seamless project tracking, issue management, and team collaboration. Understanding the core concepts of Jira Management is essential for configuring, linking, and using Jira within your Unity projects.

Key concepts

Jira Server Configurations

A Jira Server Configuration (ServerConfig) represents the connection details for a Jira server instance. It stores the server URL, credentials, and related metadata required to authenticate and interact with Jira.

Key characteristics:

  • Server URL: The base URL of the Jira server.
  • Credentials: Username and API key/token for authentication.
  • Organization Scope: ServerConfigs are created at the Unity Organization level and can be linked to multiple Unity projects.
  • Security: Credentials are securely managed and used only for authorized API calls.

Jira Project Configurations

A Jira Project Configuration (ProjectConfig) links a Unity project to a specific Jira project, defining how issues and users are mapped between the two systems.

Key characteristics:

  • Jira Project ID: The unique identifier for the Jira project.
  • Default Reporter: The Jira user to be used as the default reporter for issues created from Unity.
  • Restriction: ProjectConfigs can be restricted to specific Unity projects or shared across the organization.
  • Linked Projects: A ProjectConfig can be linked to one or more Unity projects for targeted integration.

Issues

Issues are the core work items in Jira, representing tasks, bugs, features, or other actionable items.

Key characteristics:

  • Issue Types: Each issue has a type (e.g., Bug, Task, Story) defined by the Jira project configuration.
  • Fields: Issues contain fields such as summary, description, status, assignee, and priority.
  • Hierarchy: Issues can have sub-tasks and parent-child relationships.
  • Linking: Issues can be linked to Unity annotations for traceability and context.

Users and Permissions

Jira Management supports searching for users and checking permissions to ensure proper access and assignment.

Key aspects:

  • User Search: Find Jira users by organization or project context for assignment or reporting.
  • Permission Checks: Validate that the Jira configuration and user have the required permissions to perform actions (e.g., create issues, link projects).
  • Role Mapping: Map Unity users to Jira users for accurate attribution and notifications.

Linking and Integration

Linking Unity projects and annotations to Jira projects and issues enables cross-system traceability and collaboration.

Key aspects:

  • Project Linking: Associate a Unity project with a Jira ProjectConfig to enable issue creation and synchronization.
  • Issue Linking: Link or unlink Jira issues to Unity annotations for context and traceability.
  • Synchronization: Changes in Jira (e.g., status updates) can be reflected in Unity, and vice versa, depending on integration depth.

Best practices

When working with Jira Management in the Collaboration SDK, consider these best practices:

  1. Centralize Server Configs: Manage Jira server connections at the organization level for consistency and security.
  2. Link Projects Thoughtfully: Only link Unity projects to relevant Jira projects to avoid clutter and confusion.
  3. Use Permission Checks: Always verify permissions before performing actions to prevent errors and ensure compliance.
  4. Map Users Clearly: Maintain clear mappings between Unity and Jira users for accurate assignments and notifications.
  5. Leverage Issue Types: Use Jira's issue types and fields to categorize and track work effectively.
  6. Monitor Integration Health: Regularly review linked configs and permissions to ensure smooth operation.

For detailed information on implementing specific features, see the use cases section in the documentation.

Note

These concepts provide the foundation for integrating Jira with Unity projects. Understanding how they interrelate will help you design effective project tracking and collaboration workflows tailored to your team's needs.