PlanningRoom Panel API

This endpoint exposes several actions needed to configure panels in a Planning Room. This endpoint helps you to install a panel, remove a panel, retrieve information about installed panels, and available panels.

Get all available panels

Endpoint

/api/planningroom/panels?roomContext=PlanningRoom:1317

Method

GET

Description

This API endpoint retrieves all available panels in a PlanningRoom.

Parameters

• room Context - Specifies the planning room token.

Response

• HTTP Status Code: 200 (OK)
• Headers:
  • Content-Type: application/json

JSON Response

[

{

"name": "EpicTree",

"type": "epic-tree",

"description": "The panel displays a Portfolio Item tree defined by the room settings.",

"canConfigure": false,

"canInstallAnother": false,

"alreadyInstalled": true

},

// other available panels

]

• "name": The name of the panel
• "type": The type of the panel
• "description": A brief description of the panel's functionality
• "canConfigure": A boolean indicating whether the panel can be configured.
• "canInstallAnother": A boolean indicating whether another instance of the panel can be installed.
• "alreadyInstalled": A boolean indicating whether the panel is already installed.

Get all installed panels

Endpoint

/api/planningroom/ installedpanels?roomContext=PlanningRoom:1317

Method

GET

Description

This API endpoint retrieves all the installed panels from the PlanningRoom.

Parameters

• room Context - Specifies the planning room token.

Response

• HTTP Status Code: 200 (OK)
• Headers:
  • Content-Type: application/json

JSON Response

[

{

"id": "c2a77134-63ab-4282-85ca-94ebe2aa013d",

"title": "Epicboard 2",

"type": "epic-board",

"description": "The panel displays a Portfolio Kanban configurable by panel-specific settings.",

"canInstallAnother": true,

"canConfigure": true,

"useRoomPerspective": false,

"perspective": {

"project": "Scope:1068",

"program": "ScopeLabel:1069",

"schedule": "Schedule:1064"

},

"isSingleLevel": false,

"epicType": null,

"url": null

},

// other installed panels

]

• "id": Unique identifier for the panel instance.
• "title": The title or name of the panel instance.
• "type": The type of the panel instance.
• "description": A brief description of the panel instance's functionality.
• "canInstallAnother": A boolean indicating whether another instance of this panel can be installed.
• "canConfigure": A boolean indicating whether this panel instance can be configured.
• "useRoomPerspective": A boolean indicating whether the room perspective (Project, Program and Schedule) is used for this panel instance or panel specific perspective.
• "perspective": An object containing panel specific perspective (Project, Program and Schedule).
• "isSingleLevel": A Boolean value indicating to exclude items that belong to child projects of mentioned project from panel level perspective when panel specific perspective is used.
• "epicType": The type of epic (Epic Category) used to narrow down the Portfolio Items to the specified type.
• "url": The URL associated with the web panel instance, not needed for other panels.

Install a panel

Endpoint

/api/teamroom/installpanel?roomcontext=TeamRoom:1314&type=issues

Method

POST

Description

This API endpoint installs a panel in a Planning Room.

Parameters

• room Context - Specifies the planning room token.
• type - The type of panel that needs to be installed. This value can be obtained from the available panels' response.

This endpoint accepts an optional json payload. If provided, it uses the provided panel configuration instead of the default room perspective.

Optional JSON Payload:

{

title: "Epicboard 2",

perspective : {

project: "Scope:1068",

program: "ScopeLabel:1069",

schedule: "Schedule:1064"

},

epicType: "EpicCategory:246",

isSingleLevel: false,

useRoomDefaults: true,

url: ""

}

• "title": The title or name of the panel.
• "useRoomPerspective": A boolean indicating whether the room perspective (Project, Program and Schedule) is used for this panel, this value overrides the panel perspective if present. It defaults to false.
• "perspective": An object containing panel specific perspective (Project, Program and Schedule) where Program and Schedule are optional.
• "isSingleLevel": A boolean value indicating to exclude items that belong to child projects of mentioned project from panel level perspective when panel specific perspective is used. It defaults to false.
• "epicType": It's optional, the type of epic (Epic Category) used to narrow down the Portfolio Items to the specified type. By default all epic type is shown.
• "url": Only needed for web panel.

Response

• HTTP Status Code: 201 (Created)
• Headers:
  • Content-Type: application/json

JSON Response:

{

"id": "c2a77134-63ab-4282-85ca-94ebe2aa013d",

"title": "Epicboard 2",

"type": "epic-board",

"description": "The panel displays a Portfolio Kanban configurable by panel-specific settings.",

"canInstallAnother": true,

"canConfigure": true,

"useRoomPerspective": false,

"perspective": {

"project": "Scope:1068",

"program": "ScopeLabel:1069",

"schedule": "Schedule:1064"

},

"isSingleLevel": false,

"epicType": null,

"url": null

}

• "id": Unique identifier for the panel instance.
• "title": The title or name of the panel instance.
• "type": The type of the panel instance.
• "description": A brief description of the panel instance's functionality.
• "canInstallAnother": A boolean indicating whether another instance of this panel can be installed.
• "canConfigure": A boolean indicating whether this panel instance can be configured.
• "useRoomPerspective": A boolean indicating whether the room perspective (Project, Program and Schedule) is used for this panel instance or panel specific perspective.
• "perspective": An object containing panel specific perspective (Project, Program and Schedule).
• "isSingleLevel": A Boolean value indicating to exclude items that belong to child projects of mentioned project from panel level perspective when panel specific perspective is used.
• "epicType": The type of epic (Epic Category) used to narrow down the Portfolio Items to the specified type.
• "url": The URL associated with the web panel instance, not needed for other panels.

Update a panel

Endpoint

/api/planningroom/updatepanel?roomContext=PlanningRoom:1317&panelId=c2a77134-63ab-4282-85ca-94ebe2aa013d

Method

POST

Description

This API endpoint updates a panel in the Planning Room.

Parameters

• room Context - Specifies the planning room token.
• panelId - Unique identifier of a panel, this value can be obtained from get all installed panels API endpoint.

JSON Payload:

{

title: "Epicboard",

perspective : {

project: "Scope:1068",

program: "ScopeLabel:1069",

schedule: "Schedule:1064"

},

epicType: "EpicCategory:246",

isSingleLevel: false,

useRoomDefaults: true,

url: ""

}

• "title": The title or name of the panel.
• "useRoomPerspective": A boolean indicating whether the room perspective (Project, Program and Schedule) is used for this panel, this value overrides the panel perspective if present. It defaults to false.
• "perspective": An object containing panel specific perspective (Project, Program and Schedule) where Program and Schedule are optional.
• "isSingleLevel": A boolean value indicating to exclude items that belong to child projects of mentioned project from panel level perspective when panel specific perspective is used. It defaults to false.
• "epicType": It's optional, the type of epic (Epic Category) used to narrow down the Portfolio Items to the specified type. By default all epic type will be shown.
• "url": Only needed for web panel.

Response

• HTTP Status Code: 201 (Created)
• Headers:
  • Content-Type: application/json

JSON Response:

{

"id": "c2a77134-63ab-4282-85ca-94ebe2aa013d",

"title": "Epicboard 2",

"type": "epic-board",

"description": "The panel displays a Portfolio Kanban configurable by panel-specific settings.",

"canInstallAnother": true,

"canConfigure": true,

"useRoomPerspective": false,

"perspective": {

"project": "Scope:1068",

"program": "ScopeLabel:1069",

"schedule": "Schedule:1064"

},

"isSingleLevel": false,

"epicType": null,

"url": null

}

• "id": Unique identifier for the panel instance.
• "title": The title or name of the panel instance.
• "type": The type of the panel instance.
• "description": A brief description of the panel instance's functionality.
• "canInstallAnother": A boolean indicating whether another instance of this panel can be installed.
• "canConfigure": A boolean indicating whether this panel instance can be configured.
• "useRoomPerspective": A boolean indicating whether the room perspective (Project, Program and Schedule) is used for this panel instance or panel specific perspective.
• "perspective": An object containing panel specific perspective (Project, Program and Schedule).
• "isSingleLevel": A Boolean value indicating to exclude items that belong to child projects of mentioned project from panel level perspective when panel specific perspective is used.
• "epicType": The type of epic (Epic Category) used to narrow down the Portfolio Items to the specified type
• "url": The URL associated with the web panel instance, not needed for other panels.

Remove a panel

Endpoint

/api/planningroom/removepanel?roomContext=PlanningRoom:1317&panelId=c291e7cf-cb94-4208-b6bb-90a6edff039

Method

POST

Description

This API endpoint removes a panel from the Planning Room.

Parameters

• room Context - Specifies the planning room token.
• panelId - Unique identifier of a panel, this value can be obtained from get all installed panels API endpoint.

Response

• HTTP Status Code: 204 (No Content)