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 and click the Issues tab.
   
2. Click Create issue to open a modal with the configuration workflow.
   
3. Configure the issue form:
   • Integration: Select Jira.
   • 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 project defined in entity yaml: When this toggle is enabled, the issue will use the Jira project defined in a given entity's YAML.
   • Project: Select the Jira project.
4. Click Next.
5. Configure the issue type fields:
   • 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.
   • 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 issue type and subtask issue type selected and your Jira instance requirements for new issues.
6. Click Next.
7. Configure the additional fields:
   • Summary: Select whether to use the entity name or entity tag as the summary displayed for this issue.
   • Description: Optionally enter a description.
   • Labels: Optionally enter a label to categorize the issue.
8. Click Next. On this page, you can optionally choose to include or exclude specific entity types. By default, the issue will apply to all entities in an Initiative.
   
9. Click Save issue config.

ClickUp

1. Navigate to the Initiative you want to work with and click the Issues tab.
   
2. Click Create issue to open a modal with the configuration workflow.
   
3. Configure the issue form:
   • Integration:
   • 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 list defined in entity yaml: When this toggle is enabled, the issue will use the ClickUp list defined in a given entity's YAML.
4. Click Next.
5. Configure the additional fields:
   • 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.
6. Click Next. On this page, you can optionally choose to include or exclude specific entity types. By default, the issue will apply to all entities in an Initiative.
   
7. Click Save issue config.

Azure DevOps

1. Navigate to the Initiative you want to work with and click the Issues tab.
   
2. Click Create issue to open a modal with the configuration workflow.
   
3. Configure the issue form:

• Integration:
• 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 Azure DevOps issue defined in a given entity's YAML.

1. Click Next.
2. Configure the additional fields:
   • 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.
3. Click Next. On this page, you can optionally choose to include or exclude specific entity types. By default, the issue will apply to all entities in an Initiative.
   
4. Click Save issue config.

GitHub

1. Navigate to the Initiative you want to work with and click the Issues tab.
   
2. Click Create issue to open a modal with the configuration workflow.
   
3. Configure the issue form:

• Integration:
• 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.

1. Click Next.
2. Under the Labels field, select a label.
3. Click Next. On this page, you can optionally choose to include or exclude specific entity types. By default, the issue will apply to all entities in an Initiative.
   
4. Click Save 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 configuration(s).

To edit an existing configuration:

1. Click on the config’s name in the Issues tab.
2. Make changes to the configuration.
   • The integration option will be grayed out, but you can edit the other fields.
3. Click Next then click Save issue config.

To delete an existing configuration:

1. Click on the config’s name in the Issues tab.
2. At the bottom of the modal, click Delete, then confirm the deletion.