Add jql annotation to jira plugin

Author: Frida Englund

examples/entities.yaml

@@ -14,7 +14,7 @@ metadata:
   name: example-website
   annotations:
     jira.com/project-key: BS
-    # jira/project-key: BS
+    jira.com/jql: resolution = Unresolved order by updated DESC
 
 spec:
   type: website

plugins/jira-dashboard-backend/src/api.ts

@@ -62,11 +62,17 @@ export const getIssuesByFilter = async (
   projects: JiraProject[],
   components: string[],
   query: string,
+  jqlInput?: string,
 ): Promise<Issue[]> => {
   const issues: Issue[] = [];
   for (const project of projects) {
     const { projectKey, instance } = project;
-    const jql = jqlQueryBuilder({ project: [projectKey], components, query });
+    const jql = jqlQueryBuilder({
+      project: [projectKey],
+      components,
+      query,
+      jqlInput,
+    });
     const response = await callApi(
       instance,
       `${getApiUrl(instance)}search?jql=${jql}`,
@@ -122,11 +128,11 @@ export type SearchOptions = {
 export const searchJira = async (
   instance: ConfigInstance,
   jqlQuery: string,
-  options: SearchOptions,
+  options?: SearchOptions,
 ): Promise<JiraQueryResults> => {
   const response = await callApi(instance, `${getApiUrl(instance)}search`, {
     method: 'POST',
-    body: JSON.stringify({ jql: jqlQuery, ...options }),
+    body: JSON.stringify({ jql: jqlQuery, ...(options ?? {}) }),
     headers: {
       Accept: 'application/json',
       'Content-Type': 'application/json',
@@ -143,6 +149,7 @@ export const searchJira = async (
 export const getIssuesByComponent = async (
   projects: JiraProject[],
   componentKeys: string,
+  jqlInput?: string,
 ): Promise<Issue[]> => {
   // Return an empty array if no projects are provided
   if (projects.length === 0) {
@@ -157,6 +164,7 @@ export const getIssuesByComponent = async (
   const jql = jqlQueryBuilder({
     project: projectKeys,
     components,
+    jqlInput,
   });
 
   const { instance } = projects[0];

plugins/jira-dashboard-backend/src/lib.ts

@@ -5,6 +5,7 @@ import {
   INCOMING_ISSUES_STATUS,
   Project,
   Issue,
+  JQL,
 } from '@axis-backstage/plugin-jira-dashboard-common';
 
 import type { ConfigInstance, JiraConfig } from './config';
@@ -15,6 +16,7 @@ export const getAnnotations = (config: JiraConfig) => {
   const projectKeyAnnotation = `${prefix}/${PROJECT_KEY_NAME}`;
   const componentsAnnotation = `${prefix}/${COMPONENTS_NAME}`;
   const filtersAnnotation = `${prefix}/${FILTERS_NAME}`;
+  const jqlAnnotation = `${prefix}/${JQL}`;
   const incomingIssuesAnnotation = `${prefix}/${INCOMING_ISSUES_STATUS}`;
 
   /*   Adding support for Roadie's component annotation */
@@ -24,6 +26,7 @@ export const getAnnotations = (config: JiraConfig) => {
     projectKeyAnnotation,
     componentsAnnotation,
     filtersAnnotation,
+    jqlAnnotation,
     incomingIssuesAnnotation,
     componentRoadieAnnotation,
   };

plugins/jira-dashboard-backend/src/queries.ts

@@ -7,6 +7,7 @@ export type JqlQueryBuilderArgs = {
   project: string | string[];
   components?: string[];
   query?: string;
+  jqlInput?: string;
 };
 
 /**
@@ -43,9 +44,15 @@ export const jqlQueryBuilder = ({
   project,
   components,
   query,
+  jqlInput,
 }: JqlQueryBuilderArgs) => {
   const projectList = Array.isArray(project) ? project : [project];
   let jql = createEscapedIncludeQuery('project', projectList);
+
+  if (jqlInput) {
+    jql += ` AND (${jqlInput})`;
+  }
+
   if (components?.length) {
     jql += ` AND ${createEscapedIncludeQuery('component', components)}`;
   }

plugins/jira-dashboard-backend/src/service/router.ts

@@ -108,6 +108,7 @@ export async function createRouter(
         projectKeyAnnotation,
         componentsAnnotation,
         filtersAnnotation,
+        jqlAnnotation,
         incomingIssuesAnnotation,
         componentRoadieAnnotation,
       } = getAnnotations(config);
@@ -150,6 +151,8 @@ export async function createRouter(
         }
       }
 
+      const jql = entity.metadata.annotations?.[jqlAnnotation];
+
       let userEntity: UserEntity | undefined;
 
       try {
@@ -198,6 +201,7 @@ export async function createRouter(
         filters,
         instance,
         cache,
+        jql,
       );
 
       /* Adding support for Roadie's component annotation */
@@ -212,6 +216,7 @@ export async function createRouter(
           components,
           instance,
           cache,
+          jql,
         );
         issues = issues.concat(componentIssues);
       }

plugins/jira-dashboard-backend/src/service/service.ts

@@ -46,7 +46,7 @@ export const getJqlResponse = async (
   jql: string,
   config: ConfigInstance,
   cache: CacheService,
-  searchOptions: SearchOptions,
+  searchOptions?: SearchOptions,
 ): Promise<Issue[]> => {
   let issuesResponse: Issue[];
 
@@ -154,6 +154,7 @@ export const getIssuesFromFilters = async (
   filters: Filter[],
   instance: ConfigInstance,
   cache: CacheService,
+  jql?: string,
 ): Promise<JiraDataResponse[]> => {
   const projects = await getJiraProjectsFromKeys(projectKeys, instance, cache);
   return await Promise.all(
@@ -165,7 +166,7 @@ export const getIssuesFromFilters = async (
         query: filter.query,
       }),
       type: 'filter',
-      issues: await getIssuesByFilter(projects, components, filter.query),
+      issues: await getIssuesByFilter(projects, components, filter.query, jql),
     })),
   );
 };
@@ -175,6 +176,7 @@ export const getIssuesFromComponents = async (
   componentAnnotations: string[],
   instance: ConfigInstance,
   cache: CacheService,
+  jql?: string,
 ): Promise<JiraDataResponse[]> => {
   const projects = await getJiraProjectsFromKeys(projectKeys, instance, cache);
   return await Promise.all(
@@ -185,7 +187,7 @@ export const getIssuesFromComponents = async (
         components: [componentKey],
       }),
       type: 'component',
-      issues: await getIssuesByComponent(projects, componentKey),
+      issues: await getIssuesByComponent(projects, componentKey, jql),
     })),
   );
 };

plugins/jira-dashboard-common/src/annotations.ts

@@ -20,6 +20,12 @@ export const COMPONENTS_NAME = 'components';
  */
 export const FILTERS_NAME = 'filter-ids';
 
+/**
+ * The annotation name used to provide a JQL query to filter issues in Jira
+ *  @public
+ */
+export const JQL = 'jql';
+
 /**
  * The annotation name used to provide the status for incoming issues in Jira
  *  @public

plugins/jira-dashboard-common/src/types.ts

@@ -76,7 +76,7 @@ export type Project = {
  */
 export type JiraResponse = {
   project: Project | Project[];
-  data: JiraDataResponse[];
+  data: JiraDataResponse[] | Issue[];
 };
 
 /**

plugins/jira-dashboard/README.md

@@ -184,6 +184,27 @@ metadata:
     jira.com/incoming-issues-status: Incoming # The name of the status for incoming issues in Jira. Default: New
 ```
 
+#### Custom JQL Annotation
+
+You can use the `jira.com/jql` annotation to specify a custom [Jira Query Language (JQL)](https://support.atlassian.com/jira-software-cloud/docs/advanced-search-reference-jql/) query for your entity.  
+**When this annotation is present, it will override the values set by `jira.com/components`, and `jira.com/filter-ids`.**  
+This allows you to fully customize which issues are shown in the Jira Dashboard for your entity.
+
+**Example:**
+
+```yaml
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  annotations:
+    jira.com/jql: component = OurProject AND Affected = 1.1
+```
+
+**Note:**
+
+- Make sure your JQL is valid and returns the issues you expect.
+- If you use `jira.com/jql`, you do not need to set `jira.com/components`, or `jira.com/filter-ids` for that entity. However, you still need to specify the `jira.com/project-key` annotation.
+
 ### New Frontend System (Alpha)
 
 The Jira Dashboard plugin also has support for the [new alpha frontend system](https://backstage.io/docs/frontend-system/). Here is how you can set it up: