Creating issues based on Initiatives
By integrating your issue tracking tool(s) with Cortex, you can take Initiatives and action items to the next level. Through integrations with tools like Jira, ClickUp, GitHub, and Azure DevOps, you can automatically create issues for outstanding action items based on Initiatives in Cortex.
Creating issue configurations
General setup
To automatically create issues based on Initiatives, you’ll need to set up an issue configuration. An issue configuration combines a set of filters and a configuration for an issue tracking tool integration. For example, an issue configuration could comprise the entity types that the config applies to and the Jira projects the issues should go into. This flexibility allows managers to be sure that issues for their teams end up in the right place.
To create an issue configuration, select the Initiative you want to work with and navigate to the Issues tab.
An integration with an issue tracking tool, such as Jira, ClickUp or GitHub, must be set up before you can create an issue configuration.
Select Create issue to open a modal with the configuration workflow.
First, select an integration from the Integration dropdown. Certain fields in the config form will update to reflect the integration you've chosen, but a few fields are common across integrations.
Enter a Name for the issue config. This should be a human-readable name so it’s clear whose team the issues belong to and the project that issues should be assigned to.
The Use ... defined in entity yaml toggle will use the Jira project, ClickUp list, or other integration component defined in a given entity's YAML. When this toggle is enabled, the following field will be overridden for you to select a default project where the issue will be created.
For example, if we toggled Use list defined in entity yaml when creating a ClickUp issue configuration, the Space field will be overriden with Default space.
The options available in the project dropdown are pulled in from your connected instances.
Jira-specific fields
When creating an issue configuration for Jira, the second page in the workflow will prompt you to select Issue Type and Subtask Issue Type from the dropdowns.
Jira issue types are designed to distinguish and categorize different types of work to introduce more structure into the process.
Like issue types, the subtask issue type categorizes the nature of the subtask. Note that the subtask issue type can only apply to child issues.
From the next two pages, you'll define how fields for the issue type and subtask issue type will populate.
This part of the workflow is dynamic, so it depends on the types selected and what your particular Jira instance requires for new issues. These fields are optional.
ClickUp-specific fields
When creating an issue configuration for ClickUp, the second page in the workflow will prompt you to select a List, Tag, and Priority for the issue.
You can also add an entity tag to the issue by toggling on Add entity tag.
GitHub-specific fields
When creating an issue configuration for GitHub, the second page in the workflow will prompt you to select Labels for the issue.
Azure DevOps-specific fields
When creating an issue configuration for Azure DevOps, you'll be asked to select a project. Next, you'll be prompted to select a Work item Type and Sub-item Type from the dropdowns.
Azure DevOps work item types are designed to distinguish and categorize different types of work to introduce more structure into the process.
Like work item types, the sub-item type categorizes the nature of the subtask. Note that the sub-item type can only apply to child issues.
From the next two pages, you'll define how fields for the issue type and subtask issue type will populate. This part of the workflow is dynamic, so it depends on the types selected and what your particular Azure DevOps instance requires for new issues. These fields are optional.
Filtering entities
The last stage is filtering the entities that the issue will apply to. By default, an issue will apply to all entities in an Initiative. You can apply a simple filter by including or excluding specific entities, or you can apply a more advanced filter through groups and/or a CQL expression.
Once you Save issue config, you’ll see it populate within the Issues tab.
At this stage, Cortex will automatically create a corresponding issue in your issue tracking tool for you. Cortex will create a single parent task for each entity, and each failing rule will be created as a subtask. This makes it easy for you to track the aggregate data while maintaining visibility into all failing rules.
Viewing and editing issue configurations
You can modify your configuration(s) at any point. To edit an existing configuration, click on the config’s name in the Issues tab.
The integration option will be grayed out, but you can edit the other fields.
If you want to delete an issue config, you can do so from the edit modal. When you click Delete, you’ll be asked to confirm the decision.
Once an entity passes an action item, Cortex will attempt to close out the corresponding issue. If Cortex is unable to close a issue, a comment will be left notifying you that an action item is now Passing. Cortex will go through this process any time a Scorecard is refreshed and rules are reevaluated.
If a new rule is added to an Initiative, a new issue will be created opened based on the configuration you’ve defined. Cortex will also reopen issues for existing configurations if a passing action item reverts to failure.
When using issue configurations, think about what makes the most sense for your team. You can create just one configuration for an Initiative, so that all Cortex-created issues are directed to a single project for team members to pick up from there.
There’s also no limit to the number of configs you can add. By setting up multiple configurations, you can automate which project each set of issues belongs to, minimizing the manual work involved in managing issues.