Creating issues based on Initiatives

By integrating your issue tracking tools with Cortex, you can take Initiatives and action items to the next level. Through integrations with tools like Jira, ClickUp, Azure DevOps, and GitHub, you can automatically create issues for outstanding action items based on Initiatives in Cortex.

How to create issues based on Initiatives

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.

Prerequisites

An integration with an issue tracking tool (Jira, ClickUp, Azure DevOps, or GitHub) must be set up before you can create an issue configuration.

Create an issue configuration

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.

See the tabs below for instructions on creating an issue for each issue tracking tool option.

Jira

1. Navigate to the Initiative you want to work with. Under its Issue configs tab, click Create issue config.

2. Configure the issue form:

   • Issue config name: Enter a descriptive name for the issue configuration.

     • The name can help users understand which team the issue belongs to and the project the issues should be assigned to.

   • Integration: Select Jira.

   • Inherit project from entity YAML: When this toggle is enabled, the issue will use the Jira project defined in a given entity's YAML.

   • Default Jira project: Select the Jira project where Cortex-created issues will be directed.

   • Issue type: Select a Jira issue type.

     • Jira issue types are designed to distinguish and categorize different types of work to introduce more structure into the process.

     • Additional optional fields differ depending on the issue type selected and your Jira instance requirements for new issues.

   • Subtask issue type: Select a subtask issue type.

     • Note that the subtask issue type can only apply to child issues.

     • Additional optional fields differ depending on the subtask issue type selected and your Jira instance requirements for new issues.

   • Apply to specific entities: Optionally choose to include or exclude specific entity types. By default, the issue will apply to all entities in an Initiative.

     • Advanced options: Further refine entity selecting by applying filters for groups or a CQL expression.

3. Click Create issue config.

ClickUp

1. Navigate to the Initiative you want to work with. Under its Issue configs tab, click Create issue config.

2. Configure the issue form:

   • Issue config name: Enter a descriptive name for the issue configuration.

     • The name can help users understand which team the issue belongs to and the project the issues should be assigned to.

   • Integration: Select ClickUp.

   • Inherit project from entity YAML: When this toggle is enabled, the issue will use the ClickUp list defined in a given entity's YAML.

   • Default space: Choose a space where the Cortex-created issues will be directed.

   • List: Select a ClickUp list.

   • Tag: Select a tag.

   • Priority: Select a priority for this issue.

   • Add entity tag: Toggle this setting on to add an entity tag to the issue.

   • Apply to specific entities: Optionally choose to include or exclude specific entity types. By default, the issue will apply to all entities in an Initiative.

     • Advanced options: Further refine entity selecting by applying filters for groups or a CQL expression.

3. Click Create issue config.

Azure DevOps

1. Navigate to the Initiative you want to work with. Under its Issue configs tab, click Create issue config.
2. Configure the issue form:

   • Issue config name: Enter a descriptive name for the issue configuration.

     • The name can help users understand which team the issue belongs to and the project the issues should be assigned to.

   • Integration: Select Azure DevOps.

   • Work item type: Select a work item type.

     • Azure DevOps work item types are designed to distinguish and categorize different types of work to introduce more structure into the process.

   • Sub-item type: Select a sub-item type.

     • Note that the sub-item type can only apply to child issues.

     • Additional optional fields differ depending on the issue type and sub-item type selected and your Azure DevOps instance requirements for new issues.

   • Apply to specific entities: Optionally choose to include or exclude specific entity types. By default, the issue will apply to all entities in an Initiative.

     • Advanced options: Further refine entity selecting by applying filters for groups or a CQL expression.

3. Click Create issue config.

GitHub

1. Navigate to the Initiative you want to work with. Under its Issue configs tab, click Create issue config.
2. Configure the issue form:

   1. Name: Enter a descriptive name for the issue configuration.

      • The name can help users understand which team the issue belongs to and the project the issues should be assigned to. Use issue defined in entity yaml: When this toggle is enabled, the issue will use the GitHub issue defined in a given entity's YAML.

   2. Integration: Select GitHub.

   3. Labels: Select or create a label.

   4. Apply to specific entities: Optionally choose to include or exclude specific entity types. By default, the issue will apply to all entities in an Initiative.

      • Advanced options: Further refine entity selecting by applying filters for groups or a CQL expression.

3. Click Create issue config.

Automatic issue creation in your issue tracking tool

After saving the issue configuration, 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.

Closing and reopening issues

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, including issues that have been manually closed by a user.

Viewing and editing issue configurations

You can modify or delete your configurations.

To edit an existing configuration:

1. Navigate to the Initiative and click the Issue configs tab.

2. On the right side of the issue config, click the 3 dots icon, then click Edit config.

   

   Next to an issue config, click the 3 dots then select "Edit config."
3. Make changes to the configuration.

   • The integration option will be grayed out, but you can edit the other fields.

4. Click Save issue config.

To delete an existing configuration:

1. Navigate to the Initiative and click the Issue configs tab.

2. On the right side of the issue config, click the 3 dots icon, then click Delete config.