[Server] API Methods for OKR board

Change log here.



Before we start, check the auth guide.


Get all Workspaces

GET /rest/oboard/1.0/api/v1/workspaces returns all the workspaces for the OKR board.

Request

1 GET https://jirainstanceurl/rest/oboard/1.0/api/v1/workspaces

Example

1 GET https://jirainstanceurl/rest/oboard/1.0/api/v1/workspaces

No parameters

Response

1 2 3 4 5 6 7 8 9 10 11 12 13 14 [ { "id": 163, "iss": "aaaa-02cd-aaa-aaa-0c946df6b24b", "name": "GIANT", "key": "GG" }, { "id": 164, "iss": "aaaa-02cd-aaa-aaa-0c946df6b24b", "name": "WS for Tests", "key": "CR" } ]

 


Get List of Intervals for a Workspace

GET /rest/oboard/1.0/api/v1/intervals returns all intervals for a given workspace.

Request

1 GET https://jirainstanceurl/rest/oboard/1.0/api/v1/intervals?workspaceId={{put_here_id}}

Example

1 GET https://jirainstanceurl/rest/oboard/1.0/api/v1/intervals?workspaceId=1

Field

Required

Description

Field

Required

Description

workspaceId

Yes

The if of workspace.

Response

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 [ { "id": 1902, "name": "Future (backlog)", "startDate": "2020-10-27T09:00:30.000Z", "endDate": "2020-10-27T09:00:30.000Z", "open": true, "backlog": true }, { "id": 2009, "name": "AD", "startDate": "2020-12-31T23:00:00.000Z", "endDate": "2021-03-31T21:59:59.000Z", "open": false, "backlog": false } ]

Get List of Groups

GET /rest/oboard/1.0/api/v1/groups returns all groupIds for a given workspace.

Request

1 GET https://jirainstanceurl/rest/oboard/1.0/api/v1/groups?workspaceId={{put_here_id}}&includeServiceGroups={{true/false}}

Example

1 GET https://jirainstanceurl/rest/oboard/1.0/api/v1/groups?workspaceId=141&includeServiceGroups=true

Response

Field

Required

Description

Field

Required

Description

workspaceId

Yes

The ID of workspace.

includeServiceGroups

No

Use includeServiceGroups = true if you need to get an id for the “no group“ entity.

Response

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 [ { "workspaceId": 141, "id": 1227, "name": "No Group", "description": "The group to store users until any other group has been assigned", "syncWithJira": false, "userCount": 1, "associatedJiraGroups": [] }, { "workspaceId": 141, "id": 1259, "name": "tes", "description": "", "syncWithJira": false, "userCount": 2, "associatedJiraGroups": [] } ]

Get List of Users from Workspace

GET /rest/oboard/1.0/api/v1/users returns all users for a given workspace.

Request

1 GET https://jirainstanceurl/rest/oboard/1.0/api/v1/users?workspaceId={{put_here_id}}&roleId={{put_here_roleid}}

Example

1 GET https://jirainstanceurl/rest/oboard/1.0/api/v1/users?workspaceId=141&roleId=1

Field

Required?

Description

Field

Required?

Description

workspaceId

Yes

The ID of workspace.

roleId

No

Id of the user role.

  • 1 – User

  • 2 – Team Leader

  • 3 – Workspace Administrator

groupid (will be ready soon)

No

Get users from a certain group.

Response

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 [ { "id": 347, "workspaceId": 164, "accountId": "5bfef3333c48883c86379fd3", "defaultTeamId": 1301, "teams": [ { "workspaceId": 164, "id": 1301, "name": "No Group", "description": "The group to store users until other group has assigned", "syncWithJira": false, "userCount": 1, "associatedJiraGroups": null } ], "roleId": 3, "name": "oboard test", "oboardUser": true, "userName": "5bfef3333c48883c86379fd3" }, { "id": 350, "workspaceId": 164, "accountId": "5bfef3333c48883c86379fd3", "defaultTeamId": 1302, "teams": [ { "workspaceId": 164, "id": 1302, "name": "Group1", "description": "", "syncWithJira": false, "userCount": 1, "associatedJiraGroups": null } ], "roleId": 1, "name": "Dmitry Test", "oboardUser": true, "userName": "5bfef3333c48883c86379fd3" } ]

Objectives

Get a list of objectives DEPRECATED

Please use /rest/oboard/1.0/api/v1/elements below

GET /rest/oboard/1.0/api/v1/objectives returns all objectives for a given workspace.

Request

1 GET https://jirainstanceurl/rest/oboard/1.0/api/v1/objectives?workspaceIds={{put_here_id}}

Example

1 GET https://jirainstanceurl/rest/oboard/1.0/api/v1/objectives?workspaceIds=141&typeIds=3&groupIds=1276&userIds=333fef7de6c48883c86379fd3&userIds=3337594642daa474bc92c19e&hasParent=true&maxGrade=50

 

Get a list of elements NEW

GET /rest/oboard/1.0/api/v1/elements returns all objectives for a given workspace.

Request

1 GET https://jirainstanceurl/rest/oboard/1.0/api/v1/elements?workspaceIds={{put_here_id}}

Example

1 GET https://jirainstanceurl/rest/oboard/1.0/api/v1/elements?workspaceIds=141&typeIds=1

Field

Required?

Description

Field

Required?

Description

workspaceId [array]

Yes

The ID of workspace.

⚠️Here and for other “array“ parameters you need to send 2 get-parameters in the request with the same name.
Example:

1 workspaceId=111&workspaceId=222

groupIds [array]

No

Array of a group ids.

userIds [array]

No

Array of a owner ids.

typeIds [array]

Yes

Type of the objective

1 2 1 - Objective 4 - KR

levelIds [array]

Yes

The id of Objective level (e.g. Company-level) use /rest/oboard/1.0/api/v1/levels to get the id of level for a given WS

hasParent

No

Flag to check if an objective has a parent obj.

intervalId

No

ID of the Interval

minGrade

No

Filter objectives with a grade above this value.
⚠️Can be used with the maxGrade only

maxGrade

No

Filter objectives with up to %value% grade.

limit

No (default 50)

A number of objectives returned in the response.

1 2 Max number is 100. Default is 50.

startAt

No

Offset for the request. Default = 0.


Create an objective

POST /rest/oboard/1.0/api/v1/objectives – create an objective.

Request

1 POST https://jirainstanceurl/rest/oboard/1.0/api/v1/objectives

Example

1 2 3 4 5 6 7 8 9 10 11 12 13 POST https://jirainstanceurl/rest/oboard/1.0/api/v1/objectives { "groupId": 1303, "name": "Company Objective not contribute owner description", "workspaceId": 164, "intervalId":2022, "typeId":3, "ownerId":"33fef7de6c48883c86379fd3", "contribute":false, "description":"Company Objective not contribute owner description", "parentObjectiveId":"4537" }

Field

Required

Description

Field

Required

Description

workspaceId

Yes

The ID of workspace.

intervalId

Yes

The ID of interval in the workspace.

groupId

Yes

Group to be assigned for this objective.

ownerId

No (yes if typeid=1)

User ID (in the plugin).
⚠️The parameter is required for “personal“ objectives.

typeId Jun 10, 2021 updated

Yes

Type of the objective to create 

1 2 1 - Objective 4 - KR

levelId Jun 10, 2021 New

Yes

Type of the OKR
should be taken for the request

GET /rest/oboard/1.0/api/v1/levels

parentObjectiveId

No

Put here the id of the objective if you want to set a parent objective.

contribute

No

If OKR is contributing or not to parent objective (if exists).

description

No (up to 1024 symbols)

Description for the OKR

name

Yes (up to 512 symbols)

Title for the OKR

Response

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 { "workspaceId": 164, "id": 6601, "name": "Company Objective not contribute owner description", "description": "Company Objective not contribute owner description", "ownerId": "33fef7de6c48883c86379fd3", "typeId": 3, "statusId": 1, "createDate": "2020-11-18T10:07:06.000Z", "lastUpdateDate": "2020-11-18T10:07:06.000Z", "contribute": false, "innerId": 1016, "parentObjectiveId": 4537, "intervalId": 2022, "groupId": 1303 }

Update Objective

PUT /rest/oboard/1.0/api/v1/objectives – update an objective.

If you want to delete non-required fields you need:
Put ““ for string values, and null for non-sting.
e.g. "description":"", "ownerId":null

Request

1 PUT https://jirainstanceurl/rest/oboard/1.0/api/v1/objectives

Example

1 2 3 4 5 6 7 8 9 10 PUT https://jirainstanceurl/rest/oboard/1.0/api/v1/objectives { "objectiveId":123, "groupId": 1302, "name": "Company Objective", "workspaceId": 164, "intervalId":2023, "typeId":2 }

Field

Required

Description

Field

Required

Description

objectiveId

Yes

Objective ID that has to be changed.

workspaceId

Yes

The ID of workspace.

⚠️The WS cannot be changed, it’s needed only for validation purposes.

groupId

No

Group to be assigned for this objective.

ownerId

No (yes if typeid=1)

User ID (in the plugin).
⚠️The parameter is required for “personal“ objectives.

typeId Jun 10, 2021 updated

Yes

Type of the objective to create 

1 2 1 - Objective 4 - KR

levelId Jun 10, 2021 New

Yes

Type of the OKR
should be taken for the request

GET /rest/oboard/1.0/api/v1/levels

parentObjectiveId

No

Put here the id of the objective if you want to set a parent objective.

contribute

No

If OKR is contributing or not to parent objective (if exists).

description

No

Description for the OKR

name

Yes

The title of OKR

Interval ID (coming soon)

Yes

The ID of interval in the workspace.

Response

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 { "workspaceId": 164, "id": 6602, "name": "Company Objective Wednesday, November 18, 2020 11:24 AM", "description": "", "ownerId": null, "typeId": 2, "statusId": 1, "createDate": "2020-11-18T10:24:11.000Z", "lastUpdateDate": "2020-11-18T10:24:11.000Z", "contribute": true, "innerId": 1017, "parentObjectiveId": null, "intervalId": 2023, "groupId": 1302 }

Remove Objective From Workspace

Delete /rest/oboard/1.0/api/v1/objectives – remove objective and all the nested items

Request

1 DELETE https://jirainstanceurl/rest/oboard/1.0/api/v1/objectives

Example

1 2 3 4 5 DELETE https://jirainstanceurl/rest/oboard/1.0/api/v1/objectives { "objectiveId":1111, "workspaceId":164 }

Field

Required

Description

Field

Required

Description

objectiveId

Yes

Objective ID that has to be changed.

workspaceId

Yes

The ID of workspace.

removeNestedItems* coming soon

No

The flag if the nested items need to be removed.

Response

1 Objective was successfully removed

Get Nested Items for an Objective DEPRECATED

Get /rest/oboard/1.0/api/v1/objectives/children – returns only the nested items for the given objective

Please use /rest/oboard/1.0/api/v1/elements/nested

Request

1 GET https://jirainstanceurl/rest/oboard/1.0/api/v1/objectives/children?parentId={{objectiveid}}&workspaceIds={{workspaced}}

Example

1 GET https://jirainstanceurl/rest/oboard/1.0/api/v1/objectives/children?parentId=2239&workspaceIds=222

Get Nested Items for an item NEW

Get /rest/oboard/1.0/api/v1/elements/nested – returns only the nested items for the given objective

Request

1 GET https://backend.okr-api.com/rest/oboard/1.0/api/v1/elements/nested?parentId={{objectiveid}}&workspaceIds={{workspaced}}

Example

1 GET https://backend.okr-api.com/rest/oboard/1.0/api/v1/elements/nested?parentId=2239&workspaceIds=222

Field

Required?

Description

Field

Required?

Description

parentId

Yes

Id of the objective to be deleted.

workspaceId

Yes

The ID of the workspace where the objective is located.


Key Results

Get a list of Key Results

We re-use method GET /rest/oboard/1.0/api/v1/objectives for now, but the type_id=4.

GET /rest/oboard/1.0/api/v1/objectives returns all objectives for a given workspace.

Request

1 GET https://jirainstanceurl/rest/oboard/1.0/api/v1/objectives?typeIds=4&workspaceIds={{put_here_id}}

Example

1 GET https://jirainstanceurl/rest/oboard/1.0/api/v1/objectives?workspaceIds=141&typeIds=4&groupIds=1276&userIds=333fef7de6c48883c86379fd3&userIds=3337594642daa474bc92c19e&hasParent=true&maxGrade=50

Fields are the same as for getting objective (above).

Response

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 [ { "type": "KR", "objective": { "workspaceId": 163, "id": 6570, "parentObjectiveId": 6567, "parentTypeId": null, "name": "KR &&&@@@Tuesday, November 17, 2020 8:40 AM", "description": "", "ownerId": "557058-904f8904e553", "ownerDisplayName": "Vladyslav Test", "ownerName": "557058-904f8904e553", "typeId": 4, "statusId": 1, "createDate": "2020-11-17T07:40:49.000Z", "lastUpdateDate": "2020-11-17T07:40:49.000Z", "grade": 0, "gradeColor": "grade-red", "innerId": 7, "childCount": 0, "expanded": false, "tasks": [], "keyResults": [], "childObjectives": [], "parentObjectives": [], "level": 0, "contribute": true, "existContributeChildren": false, "originalValue": 20.0, "currentValue": 20.0, "targetValue": 40.0, "intervalId": 2022, "weight": null, "weightMultiplier": null, "fieldTypeId": 1, "groupId": 1300, "groupName": "df", "displayId": "GG-KR-7" } }]

Update Key Result

If the parameter is NOT SET in the body, then it will be set to NULL

PUT /rest/oboard/1.0/api/v1/key-results – update key result

Request

1 PUT https://jirainstanceurl/rest/oboard/1.0/api/v1/key-results

Example

1 2 3 4 5 6 7 8 9 10 11 12 13 14 PUT https://jirainstanceurl/rest/oboard/1.0/api/v1/key-results { "keyResultId":3442, "groupId": 1302, "name": "Changed KR", "workspaceId": 164, "objectiveId":2938, "ownerId":"ccc356c363cbaa729c4c4f88", "fieldTypeId":3, "originalValue":60, "currentValue": 100, "targetValue":90 }

Field

Required

Description

Field

Required

Description

keyResultId

Yes

The id of a key result to update

workspaceId

Yes

The ID of the workspace where the KR is located.

groupId

Yes

Assigned group

ownerId

Yes

Assignee

fieldTypeId

No

Type of the KR result.

1 2 3 1 - Metric 2 - Percent 3 - Binary

currentValue

Yes

Current Value for the KR

⚠️Pls note the for a binary KR you should use either 0 or 1

originalValue

Yes

Starting value for the KR

⚠️Pls note the for a binary KR you should use 0

targetValue

Yes

Filter By Target Value

⚠️Pls note the for a binary KR you should use 1

name

Yes

Name of a KR

description

No

Description of a KR


Create Key Result

If the parameter is NOT SET in the body, then it will be set to NULL

POST /rest/oboard/1.0/api/v1/key-results – update key result

Request

1 POST https://jirainstanceurl/rest/oboard/1.0/api/v1/key-results

Example

1 2 3 4 5 6 7 8 9 10 11 12 13 POST https://jirainstanceurl/rest/oboard/1.0/api/v1/key-results { "groupId": 1302, "name": "Changed KR", "workspaceId": 164, "objectiveId":2938, "ownerId":"ccc356c363cbaa729c4c4f88", "fieldTypeId":3, "originalValue":60, "currentValue": 100, "targetValue":90 }

Field

Required

Description

Field

Required

Description

keyResultId

Yes

The id of a key result to update

workspaceId

Yes

The ID of the workspace where the KR is located.

groupId

Yes

Assigned group

ownerId

Yes

Assignee

fieldTypeId

No

Type of the KR result.

1 2 3 1 - Metric 2 - Percent 3 - Binary

originalValue

Yes

Starting value for the KR

⚠️Pls note the for a binary KR you should use 0

targetValue

Yes

Filter By Target Value

⚠️Pls note the for a binary KR you should use 1

name

Yes

Name of a KR

description

No

Description of a KR

Response

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 { "workspaceId": 164, "workspaceKey": "CR", "workspaceName": "WS for Tests", "id": 6612, "parentObjectiveId": 6611, "parentTypeId": null, "name": "NEW KR c6917a98-c796-4f62-809a-e2e7eb761ee5", "description": "", "ownerId": "5bfef7de6c48883c86379fd3", "ownerIcon": "https://secure.gravatar.com/avatar/ae81713d22489934bded5afee1b332a4?d=https%3A%2F%2Favatar-management--avatars.us-west-2.prod.public.atl-paas.net%2Finitials%2FDZ-0.png", "ownerDisplayName": "Dmitry Test", "ownerName": "5bfef7de6c48883c86379fd3", "typeId": 4, "statusId": 1, "createDate": "2020-11-18T16:28:33.000Z", "lastUpdateDate": "2020-11-18T16:28:33.000Z", "grade": 0, "gradeColor": "", "innerId": 309, "childCount": 0, "expanded": false, "tasks": [], "keyResults": [], "childObjectives": [], "parentObjectives": [], "permissions": [], "level": 0, "contribute": true, "existContributeChildren": false, "originalValue": 20.0, "currentValue": 20.0, "targetValue": 40.0, "intervalId": 2022, "intervalName": "Q4 2020", "orderValue": 0.0, "weight": null, "weightMultiplier": null, "fieldTypeId": 1, "groupId": 1303, "groupName": "Group2", "displayId": null, "dueDate": "2020-12-31T00:00:00.000Z" }

Remove Objective From Workspace

Delete /rest/oboard/1.0/api/v1/key-results – remove objective and all the nested items

Request

1 DELETE https://jirainstanceurl/rest/oboard/1.0/api/v1/key-results

Example

1 2 3 4 5 DELETE https://jirainstanceurl/rest/oboard/1.0/api/v1/objectives { "keyResultId":12345, "workspaceId":164 }

Field

Required?

Description

Field

Required?

Description

keyResultId

Yes

The id of a key result to update

workspaceId

Yes

The ID of the workspace where the KR is located.

Response

1 KeyResult was successfully removed