Jira Worklog Query Plugin
Jira Worklog Query Plugin
The plugin can be downloaded or installed from Atlassian Marketplace.
To run queries, it is essential to be authenticated. The process of authentication can be performed in different ways:
By means of the plugin, three types of queries can be run: we may query the worklogs, or the modified worklogs during the spefied interval, or summarize worklogs worked time by issues.
The worklog query can be accessed from the link below:
http://myjira/rest/jira-worklog-query/REST-API-VERSION/find/worklogs
The query returns the worklogs that belong to the specified interval. The query considers the startdate value of the worklog.
GET parameters of the worklogs query:
| parameter | value | optional | description |
|---|---|---|---|
| startDate | "YYYY-MM-DD" | false | The start date from which the worklogs can be viewed. The query is run from the beginning of the given day (00:00:00) |
| endDate | "YYYY-MM-DD" | true | The end date until which the worklogs can be viewed. The query is run until the end of the given day (23:59:59). The default value is the current date. |
| group/user | string | false | A JIRA group or user name whose worklogs are to be listed. One of them is required. |
| project | string | true | The key parameter of a JIRA project. Unless it is defined, all projects are queried, otherwise only the ones under the defined project. |
| fields | string list | true | A list of additional fields to return. Available fields are: comment, updated. |
Available response representations:
[ [ { "id": 10204, "startDate": "2014-07-31T08:00:00+0200", "issueKey": "TEST-5", "userId": "admin", "duration": 22440 }, { "id": 10207, "startDate": "2014-07-31T14:14:00+0200", "issueKey": "TEST-2", "userId": "admin", "duration": 2340 } ] ]Error running search: There is no project matching the given 'project' parameter: NOPROJECTThe worklog query can be accessed from the link below:
http://myjira/rest/jira-worklog-query/REST-API-VERSION/find/updatedWorklogs
The query returns all the worklogs created and modified during the given interval. According to the logic of Jira, creation counts as modification. In the latter case, the value of the worklog update equals the value of createdate. The query considers the value of the worklog update.
GET parameters of the updatedWorklogs query:
| parameter | value | optional | description |
|---|---|---|---|
| startDate | "YYYY-MM-DD" | false | The start date from which the worklogs can be viewed. The query is run from the beginning of the given day (00:00:00) |
| endDate | "YYYY-MM-DD" | true | The end date until which the worklogs can be viewed. The query is run until the end of the given day (23:59:59). The default value is the current date. |
| group/user | string | false | A JIRA group or user name whose worklogs are to be listed. One of them is required. |
| project | string | true | The key parameter of a JIRA project. Unless it is defined, all projects are queried, otherwise only the ones under the defined project. |
| fields | string list | true | A list of additional fields to return. Available fields are: comment, updated. |
Available response representations:
[ [ { "id": 10204, "startDate": "2014-07-31T08:00:00+0200", "issueKey": "TEST-5", "userId": "admin", "duration": 22440 }, { "id": 10207, "startDate": "2014-07-31T14:14:00+0200", "issueKey": "TEST-2", "userId": "admin", "duration": 2340 } ] ]Error running search: There is no project matching the given 'project' parameter: NOPROJECTThe worklog query can be accessed from the link below:
http://myjira/rest/jira-worklog-query/REST-API-VERSION/find/worklogsByIssues
This function queries worklogs - filtered by the given parameters - and summarize the worked time by issues. The returned issues can be filtered by a JQL expression. The response are paginated, with default page size of 25 issues.
GET parameters of the worklogs query:
| parameter | value | optional | description |
|---|---|---|---|
| startDate | "YYYY-MM-DD" | false | The result will only contain worklogs after this date |
| endDate | "YYYY-MM-DD" | false | The result will only contain worklogs before this date. The default value is the current date. |
| group/user | string | false | A JIRA group or user name whose worklogs are queried. One of them is required. |
| jql | string | true | The returned issues are filtered by this JQL expression. By default, all issues are returned. |
| fields | string list | true | The list of fields to return for each issue. By default, no additional fields are returned. More info |
| startAt | int | true | The index of the first issue to return (0-based) |
| maxResults | int | true | The maximum number of issues to return (default is 25). |
Available response representations:
{ "startAt": 0, "maxResults": 25, "total": 2, "issues": [ { "id": "13405", "self": "http://localhost:8080/rest/api/2/issue/13405", "key": "TEST-1", "timespent": 1440 }, { "id": "13406", "self": "http://localhost:8080/rest/api/2/issue/13406", "key": "TEST-2", "timespent": 35760 } ] }Example response with "fields=summary,progress" parameter:
{ "startAt": 0, "maxResults": 25, "total": 1, "issues": [ { "id": "13411", "self": "http://localhost:8080/rest/api/2/issue/13411", "key": "NEW-1", "fields": { "progress": { "progress": 84000, "total": 84000, "percent": 100 }, "summary": "new issue1" }, "timespent": 67080 } ] }{ "errorMessages": [ "Cannot parse the 'startDate' parameter: 2013-0ghjg6-25" ], "errors": { } }In the case of a successful query the worklog information is returned (with HTTP 200 OK status) in JSON format as:
[[ { "id":int, "duration":int, "startDate":string, "userId":string, "issueKey":string },.. ]]
The items of the list consist of the following data:
200 - application/json Example:
[ [ { "id": 10204, "startDate": "2014-07-31T08:00:00+0200", "issueKey": "TEST-5", "userId": "admin", "duration": 22440 }, { "id": 10207, "startDate": "2014-07-31T14:14:00+0200", "issueKey": "TEST-2", "userId": "admin", "duration": 2340 } ] ]If the parameters of the query are defined erroneously, the following responses can be returned with an HTTP Error 400 Bad request status:
In the case of any other type of error the result is the HTTP Error 500 Internal Server Error status accompanied by the message of the current error.
If the user tries to run the query without authenticating to the JIRA server, then the result is the HTTP Error 401 Unauthorized status: Client must be authenticated to access this resource.
An empty response is returned if:
Using the plugin version 2.x, the REST-API-VERSION in the URL will be the major version of the REST API, which is currently 1.
Using the plugin version 1.x, the REST-API-VERSION in the URL will be the same as the plugin version until version 1.2.1 (including). After version 1.2.1 the REST-API-VERSION will remain 1.2.1. This decision was inspired by and we do not want to bother the users with MINOR and PATCH version changes in further 1.x releases.
The URLs of the examples represent the working of the plugin 2.x version. More about the plugin REST API version.
JIRA_URL/rest/jira-worklog-query/1/find/worklogs?startDate=2012-12-12&endDate=2013-01-12&user=testuserIt returns each worklog created by the testuser between 2012.12.12 and 2013.01.12 according to the permissions of user running the query.
A possible response:
[[ { "id":11000, "duration":14400, "startDate":"2013-01-07T08:00:00Z", "userId":"testuser", "issueKey":"TEST-1" }, { "id":11100, "duration":17100, "startDate":"2013-01-08T08:30:00Z", "userId":"testuser", "issueKey":"TEST-1" } ]]Example response with added "fields=comment" parameter:
[[ { "id": 103849, "startDate": "2015-01-10T10:15:00+0100", "issueKey": "TEST-7", "userId": "", "duration": 3900, "comment": "Comment of test worklog" }, { "id": 103947, "startDate": "2015-01-10T00:00:00+0100", "issueKey": "TEST-38", "userId": "", "duration": 17100, "comment": "Some important comment" } ]]JIRA_URL/rest/jira-worklog-query/1/find/worklogs?startDate=2012-12-12&group=test group&project=TESTFrom 2012.12.12 till today (let the current example date be 2013.01.30), the testgroup members’ worklogs that belong to the project with the TEST key are all returned. In case the authenticated user has no permission to access the project, an empty list is returned.
A possible response:
[[ { "id":11000, "duration":14400, "startDate":"2013-01-07T08:00:00Z", "userId":"testuser", "issueKey":"TEST-1" }, { "id":11100, "duration":17100, "startDate":"2013-01-08T08:30:00Z", "userId":"testuser", "issueKey":"TEST-1" }, { "id":11110, "duration":17100, "startDate":"2013-01-09T08:30:00Z", "userId":"testUser2", "issueKey":"TEST-2" } ]]In this example, testUser and testUser2 are members of the test group. The issues with the codes TEST-1 and TEST-2 belong to the TEST project.
If the authenticated user does not have permission to access the TEST project, the response is an empty list: [[]]
JIRA_URL/rest/jira-worklog-query/1/find/updatedWorklogs?startDate=2012-12-12&group=test group&project=TESTDuring the interval between 2012.12.12 and 2013.01.12, all the worklogs modified by the testuser are returned from every project to which the user has access to.
A possible response:
[[ { "id":11000, "duration":14400, "startDate":"2013-01-07T08:00:00Z", "userId":"testuser", "issueKey":"TEST-1" } ]]
The response is similar to the one in the first example, but the last worklog is missing from the response. One possible explanation for that may be that the testuser modified the worklog description to 2013.01.13. Therefore, the updateWorklogs query does not return it any longer, while a worklog query would return the results of the first example henceforward.
JIRA_URL/rest/jira-worklog-query/1/find/worklogsByIssues?startDate=2015-01-10&endDate=2015-01-11&user=testuserA possible response:
{ "startAt": 0, "maxResults": 25, "total": 2, "issues": [ { "id": "13405", "self": "http://localhost:8080/rest/api/2/issue/13405", "key": "TEST-1", "timespent": 1440 }, { "id": "13406", "self": "http://localhost:8080/rest/api/2/issue/13406", "key": "TEST-2", "timespent": 35760 } ] }Example response with "fields=summary,progress" parameter:
{ "startAt": 0, "maxResults": 25, "total": 1, "issues": [ { "id": "13411", "self": "http://localhost:8080/rest/api/2/issue/13411", "key": "NEW-1", "fields": { "progress": { "progress": 84000, "total": 84000, "percent": 100 }, "summary": "new issue1" }, "timespent": 67080 } ] }The version history and the release notes can be found on the page of the Github project.
The sources can be found on the page of the project.