Introduction
Now it is possible for 3rd party apps to send out of office information or query out of office period with the newly added REST endpoints.
There are 4 REST Resources which can be accessed.
- ConfigResource - Used for configuring options and JQL Filter.
- OutOfOfficeOneTimeRuleResource - Used for configuring any one time rule.
- OutOfOfficePeriodResource - Used for configuring OutOfOffice Period.
- OutOfOfficeRecurRuleResource - Used for configuring OutOfOffice Recurring Rule.
Resources
/rest/ooo/1.0
ConfigResources
Attributes
| Data Type | Attribute Name | Default Value | Remarks |
|---|
| String | ignoreSelfAssign | false | true/false to ignore self assignment of issue |
| String | allowCovererAssignBack | false | true/false to allow coverer to assign issue back |
| String | oooReplyWhenMentioned | false | true/false to thread reply when being mentioned |
| String | exclusionMode | default | Exclusion mode for JQL which can be either default or user |
| String | defaultJql |
| Default JQL used in the global level |
| String | userJql |
| User defined JQL |
Create JQL Exclusion Filter for OOO (POST)
| METHOD | URL | Data | Remarks |
|---|
| POST | /rest/ooo/1.0/ | STATUS 200 - successful creation of JQL Exclusion Filter.
STATUS 401 - UNAUTHORIZED - Not logged in or do not have administrator access
STATUS 406 - NOT_ACCEPTABLE - error in JQL
| Can only be performed by an user with Administrator privilege
|
Example DATA to POST:
{
"exclusionMode": "default",
"defaultJql": "project = ExampleProject"
}
If exclusion Mode is "user" , "userJql" would be modified instead of "defaultJql".
Only attributes which needs to be changed are to be added, attributes not specified in the DATA are set to their default values as defined in the attributes table as above.
Update the OOO advance settings of User (PUT)
| METHOD | URL | Data | Remarks |
|---|
| PUT | /rest/ooo/1.0/ | STATUS 200 - successful update of OOO advance settings
STATUS 401 - UNAUTHORIZED - Not logged in or do not have administrator access
STATUS 406 - NOT_ACCEPTABLE - error in JQL
|
|
Example DATA to PUT :
{
"ignoreSelfAssign": "true",
"allowCovererAssignBack": "false",
"oooReplyWhenMentioned": "true"
}
Only attributes which needs to be changed are to be added, attributes not specified in the DATA are set to their default values as defined in the attributes table as above.
If only "oooReplyWhenMentioned" needs to be changed, the DATA can be only
{ "oooReplyWhenMentioned": "false"}
Retrieve the OOO advance settings of user (GET)
| METHOD | URL | Data | Remarks |
|---|
| GET | /rest/ooo/1.0/ | STATUS 200 - Returns the Config Object for Rendering
STATUS 401 - UNAUTHORIZED - Not logged in or do not have administrator access
|
|
/rest/ooo/1.0/onetimerule
OutOfOfficeOneTImeRuleResource
Attributes
| Data Type | Attribute Name | Default Value | Remarks |
|---|
| String | projectIdString | "-1" | "-1" will be all other project If not, it will be the projectId of project |
| String | covererId |
| The coverer username if reassignMode is set to "coverer" Set to "-" for do not re-assign issue |
| String | covererAvatar |
| The small avatar img of coverer which is used to populate in one time rule table |
| String | covererDisplayName |
| The coverer full name which is used to populate in one time rule table |
| String | projectInfo |
| The project name and key which are configured |
| String | reassignMode |
| Can use "reassign", for re-assigning issue Can use "unassign", for unassigning issue ( the option is only available if JIRA allow unassign issue) Can use "same", for do not re-assign issue |
| String | oneTimeMessage |
| Message to be added into comment should the user is OOO |
| String | startDateString |
| String of the out of office start date format ("yyyy-MM-dd HH:mm") |
| String | endDateString |
| String of the out of office end date format ("yyyy-MM-dd HH:mm") |
| int | oneTimeId | 0 | The id of the one time rule for update and delete rule |
| boolean | byAdmin | false | if the rule is configured by admin |
| boolean | byTeam | false | if the rule is configured by team |
| String | creatorAvatar |
| The small avatar img of rule creator which is used to populate in one time rule table |
| String | creatorDisplayName |
| The creator full name which is used to populate in one time rule table |
| String | assigneeId |
| The ooo user's username |
| String | assigneeAvatar |
| The ooo user's avatar |
| String | assigneeDisplayName |
| The ooo user's full name |
Getting all your own One-Time Rule (GET)
| METHOD | URL | Data | Remarks |
|---|
| GET | /rest/ooo/1.0/onetimerule | Return an array of OneTimeRule object See above inner class section on data transaction
Example
[
{
"projectIdString": "10001",
"covererId": "",
"covererAvatar": "",
"covererDisplayName": "",
"projectInfo": "Akeles [AKELES]",
"reassignMode": "unassign",
"startDateString": "2018-10-11 00:00",
"endDateString": "2018-10-18 23:59",
"oneTimeId": 5,
"byAdmin": false,
"byTeam": false,
"creatorAvatar": "http://192.168.9.150:8080/secure/useravatar?size=xsmall&avatarId=10337",
"creatorDisplayName": "John",
"assigneeId": "",
"assigneeAvatar": "",
"assigneeDisplayName": ""
}
]
| Does not allow you to search based on assigneeId. It will return all the one time rule configured for the current logged in user |
Create a new One-Time Rule (POST)
| METHOD | URL | Data | Remarks |
|---|
| POST | /rest/ooo/1.0/onetimerule | Required the following field: - assigneeId
- projectIdString
- reassignMode
- covererId if reassignment mode is set to coverer
- startDateString
- endDateString
STATUS 200 - successful creation of new one time rule
STATUS 401 - UNAUTHORIZED - Not logged in or do not have administrator access
STATUS 406 - NOT_ACCEPTABLE - error when validating data or invalid user
| Will perform validateUser() and validateOneTimeRule() User - Check if user is admin if byAdmin is set to true OneTimeRule - Check for data format and mandatory data required |
Example Data to POST:
{
"assigneeId": "1000222",
"projectIdString": "2",
"reassignMode": "unassign",
"covererId": "",
"startDateString": "2018-09-14 12:00",
"endDateString": "2018-09-20 12:00"
}
Edit an existing One-Time Rule (PUT)
| METHOD | URL | Data | Remarks |
|---|
| PUT | /rest/ooo/1.0/onetimerule | Required the following field: - oneTimeId
- assigneeId
- projectIdString
- reassignMode
- covererId if reassignment mode is set to coverer
- startDateString
- endDateString
STATUS 200 - successful editing of existing one time rule
STATUS 401 - UNAUTHORIZED - Not logged in or do not have administrator access
STATUS 406 - NOT_ACCEPTABLE - error when validating data or invalid user
| Will perform validateUser() and validateOneTimeRule() User - Check if user is admin if byAdmin is set to true OneTimeRule - Check for data format and mandatory data required |
Example Data to PUT:
{
"oneTimeId": "2",
"assigneeId": "1000222",
"projectIdString": "2",
"reassignMode": "coverer",
"covererId": "1000232",
"startDateString": "2018-09-14 12:00",
"endDateString": "2018-09-20 12:00"
}
Delete and existing One-Time Rule (DELETE)
| METHOD | URL | Data | Remarks |
|---|
| DELETE | /rest/ooo/1.0/onetimerule | Required the following field:
STATUS 200 - successful editing of existing one time rule
STATUS 401 - UNAUTHORIZED - Not logged in or do not have administrator access
STATUS 406 - NOT_ACCEPTABLE - error when validating data or invalid user
| Will perform validateUser() and validateOneTimeRule() User - Check if user is admin if byAdmin is set to true OneTimeRule - Check for data format and mandatory data required |
Example Data to DELETE:
Get all Rule configured by adminstrator
| METHOD | URL | Data | Remarks |
|---|
| Get all rule configured by administrator | GET | /rest/ooo/1.0/onetimerule/admin | Return an array of OneTimeRule See above inner class section on data transaction |
Same as getting all of your own one time rule just that this is all rules created by admin.
/rest/ooo/1.0/period
OutOfOfficePeriodResource
Attributes
| Data Type | Attribute Name | Default Value | Remarks |
|---|
| String | periodMessage |
| Message to be added into comment should the user is OOO This message will be pre-pend infront of the one-time message as comment |
| String | startDateString |
| String of the out of office start date, date format ("yyyy-MM-dd HH:mm") |
| String | endDateString |
| String of the out of office end date, date format ("yyyy-MM-dd HH:mm") |
| int | periodId | 0 | The id of the period for update and delete of period |
Retrieve all your own Out Of Office period (GET)
| METHOD | URL | Data | Remarks |
|---|
| GET | /rest/ooo/1.0/period | Return an array of Period object See above inner class section on data transaction Example of array returned.
[
{
"periodMessage": "Out of Office",
"startDateString": "2018-09-14 12:00",
"endDateString": "2018-09-20 12:00"
}
]
| Does not allow you to search based on assigneeId. It will return all the period configured for the current logged in user |
Add a new Out Of Office period for yourself (POST)
| METHOD | URL | Data | Remarks |
|---|
| POST | /rest/ooo/1.0/period | Required the following field: - startDateString
- endDateString
periodMessage is Optional, if a message is needed. STATUS 200 - successful editing of existing one time rule
STATUS 401 - UNAUTHORIZED - Not logged in or do not have administrator access
STATUS 406 - NOT_ACCEPTABLE - error when validating data
|
|
Example Data to POST:
{
"periodMessage": "I am out of office",
"startDateString": "2018-09-14 12:00",
"endDateString": "2018-09-20 12:00"
}
Delete an existing Out Of Office period (DELETE)
| METHOD | URL | Data | Remarks |
|---|
| DELETE | /rest/ooo/1.0/period | Required the following field: STATUS 200 - successful editing of existing one time rule
STATUS 401 - UNAUTHORIZED - Not logged in or do not have administrator access
STATUS 406 - NOT_ACCEPTABLE - invalid user
| Will perform validateUser() to check if the period belongs to user |
Example Data to DELETE:
Update an existing Out Of Office period (PUT)
| METHOD | URL | Data | Remarks |
|---|
| PUT | /rest/ooo/1.0/period | Required the following field: - periodId
- startDateString
- endDateString
STATUS 200 - successful editing of existing one time rule
STATUS 401 - UNAUTHORIZED - Not logged in or do not have administrator access
STATUS 406 - NOT_ACCEPTABLE - error when validating data or invalid user
| Will perform validateUser() to check if the period belongs to user |
Example Data to PUT:
{
"periodId": "3",
"startDateString": "2018-09-14 12:00",
"endDateString": "2018-09-20 12:00"
}
/rest/ooo/1.0/recurrule
OutOfOfficeRecurRuleResource
Attributes
| Data Type | Attribute Name | Default Value | Remarks |
|---|
| String | projectIdString | "-1" | "-1" will be all other project If not, it will be the projectId of project |
| String | covererId |
| The coverer username if reassignMode is set to "coverer" Set to "-" for do not re-assign issue |
| String | covererAvatar |
| The small avatar img of coverer which is used to populate in recur rule table |
| String | covererDisplayName |
| The coverer full name which is used to populate in recur rule table |
| String | projectInfo |
| The project name and key which are configured |
| String | reassignMode |
| Can use "coverer", for re-assigning issue Can use "unassign", for unassigning issue ( the option is only available if JIRA allow unassign issue) Can use "same", for do not re-assign issue |
| String | oneTimeMessage |
| Message to be added into comment should the user is OOO
This message will be appended into period's message as comment |
| int | oneTimeId | 0 | The id of the recur rule for update and delete rule |
Retrieve all your own Out Of Office recur rule (GET)
| METHOD | URL | Data | Remarks |
|---|
| GET | /rest/ooo/1.0/recurrule | Return an array of RecurRule object See above inner class section on data transaction
| Does not allow you to search based on assigneeId. It will return all the recur rule configured for the current logged in user |
Example
[
{
"projectIdString": "10001",
"covererId": "",
"covererAvatar": "",
"covererDisplayName": "",
"projectInfo": "Akeles [AKELES]",
"reassignMode": "unassign",
"oneTimeMessage": "out of office",
"oneTimeId": 5
}
]
Add a new Out Of Office recur rule for yourself (POST)
| METHOD | URL | Data | Remarks |
|---|
| POST | /rest/ooo/1.0/recurrule | Required the following field: - recurRuleId
- assigneeId
- projectIdString
- reassignMode
- covererId if reassignment mode is set to coverer
STATUS 200 - successful editing of existing one time rule
STATUS 401 - UNAUTHORIZED - Not logged in or do not have administrator access
STATUS 406 - NOT_ACCEPTABLE - error when validating data
|
|
Example Data to POST:
{
"recurRuleId": "1",
"assigneeId": "10002",
"projectIdString": "2",
"reassignMode": "coverer",
"covererId": "20001"
}
Delete an existing Out Of Office recur rule (DELETE)
| METHOD | URL | Data | Remarks |
|
|---|
| Delete an existing out of office recur rule | DELETE | /rest/ooo/1.0/recurrule | Required the following field: STATUS 200 - successful editing of existing one time rule
STATUS 401 - UNAUTHORIZED - Not logged in or do not have administrator access
STATUS 406 - NOT_ACCEPTABLE - invalid user
| Will perform validateUser() to check if the recur rule belongs to user |
Example Data to DELETE:
Update an existing Out Of Office recur rule (PUT)
| METHOD | URL | Data | Remarks |
|
|---|
| Update an existing out of office recur rule | PUT | /rest/ooo/1.0/recurrule | Required the following field: - recurRuleId
- assigneeId
- projectIdString
- reassignMode
- covererId if reassignment mode is set to coverer
STATUS 200 - successful editing of existing one time rule
STATUS 401 - UNAUTHORIZED - Not logged in or do not have administrator access
STATUS 406 - NOT_ACCEPTABLE - error when validating data or invalid user
| Will perform validateUser() to check if the recur rule belongs to user |
Example Data to PUT:
{
"recurRuleId": "2",
"assigneeId": "20202",
"projectIdString": "20",
"reassignMode": "unassign",
"covererId":""
}
