Keypup harmonizes the data model of applications (GitHub, GitLab, JIRA and others) to display consistent results and allow filtering on captured fields. This is convenient to get a single view of items across applications.
But sometimes you need to build custom reports that rely on fields that are specific to JIRA and/or that you have created in JIRA. Don't worry, this is possible with Keypup!
Keypup provides auto-discovery of JIRA custom fields. Upon connecting your JIRA instance, Keypup automatically fetches and make available for filtering all JIRA fields with supported data types.
> Using JIRA custom fields in the data explorer
Upon connecting JIRA, a new section will appear in the list of fields available for filtering inside the Data explorer.
You can use these fields to filter results in your report as you would with any other field.
JIRA custom fields can be complex and we do our best to provide filtering that makes sense. Base JIRA fields are often composed of arrays, nested objects etc.. The data explorer automatically generates field and sub-field filters for these complex fields as well.
Example 1: Select issues in a given JIRA status
Let's say you want to check all the issues that are currently in your JIRA backlog. By default these issues are assigned the status To Do in JIRA.
To build your report, simply create a filter in the Data Explorer that matches issues based on the Status name:
You'll note that Status is not a simple text field. Status is actually an object made of several fields (id and name in this case).
JIRA custom fields are often composed of lists and nested fields. When filtering on these fields it is often required to drill down inside these fields to filter on specific sub-fields. But worry not, we support that!
The next two examples will show you more complete examples of how to perform filtering using complex JIRA fields.
Example 2: Select all issues for a given JIRA sprint
Let's say our sprint is called KEYP Sprint 1 inside JIRA. Here is how you can list all issues related to this sprint.
Note that the Sprint JIRA custom field is an array of Sprint objects, because an issue in JIRA can be associated with multiple sprints. The filter above means "collect all the sprint names attached to the issue. If one of the sprint names is equal to KEYP Sprint then keep the issue".
Only array operators (include, exclude) are available when filtering on a list of values (in this case the list of Sprint names attached to the object).
More specific filters are available if you filter on a specific object inside the Sprint array. See the example in the next section.
Example 3: Select all issues with a sprint due date coming soon
The Sprint JIRA custom field is array of Sprint objects. Each Sprint object has a field called endDate. This value can be used to filter issues in our report.
Unfortunately it is not possible at this stage to filter on Any sprint end date. You'll have to select a specific Sprint inside the Sprint array to filter on.
The query above returns all open items whose first Sprint due date is overdue or coming within the next five days.
The word first is important because if you note on the screenshot above, we filter items based on the element at index 0 (first element) of the Sprint array. Using type-specific filters (>=, <=, before, after etc..) on nested array fields is only supported when selecting a specific element in the array.
In most cases this is fine because issues are not usually attached to multiple sprints. If you expect issues to be attached to multiple sprints you can always create an OR group with multiple sprint conditions.
The screenshot above shows a query that filters items based on the first two sprints attached to each item. Note how we select at index 0 and at index 1 in the filters.
> Supported types
Data explorer filters are automatically generated for the following JIRA custom field types:
Array of issue link objects (e.g. Linked Issues field)
Array of sprint objects (e.g. Sprint field)
Array of strings (e.g. Labels field)
Array of version objects (e.g. Affects versions and Fix versions field)
Status object (e.g. Status field)
String (e.g. Environment field)
More field types will be added on a regular basis. Stay tuned!
You do not see your JIRA custom field? Feel free to send us a message via chat and we'll be able to assist.