This processor uses Jira search API to fetch issues matching the specified JQL filter. The user may set a project name, or a JQL expression, non-exclusively. If none of these are set, the processor attempts to fetch all the Jira issues, it has access to.
Search API usage by the processor
With the configured settings, a JQL expression gets built, based on the following rules:
ORDER BY {state tracking field} DESCproject = '[field value]' is added as prefix.project = '{field value}' AND {jql} is added as prefix.Note that, the value of Project field is not validated against JQL injection. Also note that, the user defined JQL is always extended by an ORDER BY clause, so this must not be present. Otherwise, syntax error messages will be reported during the processor execution.
After the processor's constructed the final JQL, it inserts it to the following URL template, along with
other configuration settings:
{URL}/rest/api/2/search?fields=*all&jql={Query}&maxResults={Page Size}
Where the Query is of course, URL encoded. The results then will be retrieved by issuing a HTTP GET request,
with an additional 'Authorization' header added, if the Personal Access Token is set.
The Jira server may require the client to authenticate itself, in order to return any (all) of the issues matching the configured filter. This processor supports authentication through Personal Access Token, in case of Jira Server, and user e-mail & API token, in case of Jira Cloud. The credential must be provided in the same format, as Jira presents it to the user. Providing an invalid token might result in either error messages, or empty responses, depending on the access policy configuration on the server side. You can do anonymous queries, by choosing the 'none' option.
User can choose which field to be monitored by the processor, to trigger re-emission of a particular issue. The currently supported choices are 'Updated' (default) and 'Created'. In the latter case, each issue is emitted at most once during their lifetime.
Each emitted FlowFile contains a Json array, containing at least one object, describing
a Jira issue, as returned by Jira. No further processing is made. The issues are emitted only once,
unless their state tracking field (user-configured) has been updated since the last query.
This processor does not implement support for iterating through multiple pages of Jira search results. The reason for this is, that Jira re-evaluates the JQL every time a new page is fetched, and thus the order of returned issues may vary during the query. Implementing a method that can properly handle this is not trivial, because it requires caching meta info about the visited items into some external cache. In the current version, only the first page is polled every time the processor is scheduled by NiFi, and thus the maximum amount of emitted (historical) issues is limited by the page size, which is configurable by user. There is no upper limit for this number, but the Jira server might deny or truncate response in case of too high number specified. The default configuration is 50 items, which is expected to be supported by any Jira instance. Refer to Confluence support to find out how can this value be configured.
The processor keeps track of the highest value of the configured state tracking field, on each query. Let's have the following example: A Jira issue is not matched by the configured filter during its creation, but later it matches, because let's say a label has been added to it. In this case it'll only be picked up by the processor, if state tracking is configured to the 'Updated' field. The reason for this is, that the 'Created' field never changes, and it will always be potentially lower than the highest number found in the last query.