[Server] API Methods for OKR board

Change log here.

1 Get all Workspaces
- 1.1 Request
- 1.2 Response
2 Get List of Intervals for a Workspace
- 2.1 Request
- 2.2 Response
3 Get List of Groups
- 3.1 Request
- 3.2 Response
4 Get List of Users from Workspace
- 4.1 Request
- 4.2 Response
5 Objectives
- 5.1 Get a list of objectives DEPRECATED
  - 5.1.1 Request
- 5.2 Get a list of elements NEW
  - 5.2.1 Request
- 5.3 Create an objective
  - 5.3.1 Request
  - 5.3.2 Response
- 5.4 Update Objective
  - 5.4.1 Request
- 5.5 Remove Objective From Workspace
  - 5.5.1 Request
  - 5.5.2 Response
- 5.6 Get Nested Items for an Objective DEPRECATED
- 5.7 Get Nested Items for an item NEW
  - 5.7.1 Request
6 Key Results
- 6.1 Get a list of Key Results
  - 6.1.1 Request
  - 6.1.2 Response
- 6.2 Update Key Result
  - 6.2.1 Request
- 6.3 Create Key Result
  - 6.3.1 Request
  - 6.3.2 Response
- 6.4 Remove Objective From Workspace
  - 6.4.1 Delete /rest/oboard/1.0/api/v1/key-results – remove objective and all the nested itemsRequest
  - 6.4.2 Response

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

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

Example

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

No parameters

Response

[
    {
        "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

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

Example

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

[
    {
        "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

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

Example

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

[
    {
        "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

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

Example

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

[
    {
        "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

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

Example

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

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

Example

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: `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 - 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. `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

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

Example

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 - 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

{
    "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

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

Example

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 - 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

{
    "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

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

Example

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

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

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

Example

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/v2/elements/nested – returns only the nested items for the given objective

Request

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

Example

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

Field	Required?	Description

Field	Required?	Description
parentId	Yes	Id of the objective.
workspaceId	Yes	The ID of the workspace where the objective is located.
searchType=1	Yes	First-level nested items
searchType=2	Yes	Full structure

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

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

Example

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

[
    {
        "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

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

Example

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 - 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

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

Example

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 - 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

{
    "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

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

Example

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

KeyResult was successfully removed

[Server] API Methods for OKR board

Get all Workspaces

Request

Response

Get List of Intervals for a Workspace

Request

Response

Get List of Groups

Request

Response

Get List of Users from Workspace

Request

Response

Objectives

Get a list of objectives DEPRECATED

Request

Get a list of elements NEW

Request

Create an objective

Request

Response

Update Objective

Request

Remove Objective From Workspace

Request

Response

Get Nested Items for an Objective DEPRECATED

Get Nested Items for an item NEW

Request

Key Results

Get a list of Key Results

Request

Response

Update Key Result

Request

Create Key Result

Request

Response

Remove Objective From Workspace

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

Response

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

Request