Create a BoardElement

This article explains how to add an element to a board using the API.

There are two possible approaches:

• Create a  DataElement on a Board as Card with new DataElement (such as an Objective, KPI, Task, etc.)

• Create a DataElement on a Board with existing Dataset Element (such as an Objective, KPI, Task, etc.)

• Create a Decorative Element (such as a Sticker or Free Text)

Prerequisites: Retrieve Required Information

Before creating a board element, you must retrieve several identifiers.

• BoardId : the target board

• RoomId: only if datasetElement need to be created

• OwnerId (optionnal): only if datasetElement need to be created

BoardId

Important: BoardId and RoomBoardId are different identifiers.

The RoomBoardId is the identifier exposed in the URL, while the BoardId is the internal identifier required by the API.

To retrieve the actual BoardId :

• Retrieve the RoomBoardId from the url : /board/c84b32be-6594-48ea-a487-928c0c6d9456

• Call the endpoint: GET /v0/room-boards/<id> and retrieve the properties board.id

RoomId

You can retrieve the RoomId in one of the following ways:

• From the url : /room/1e7e452f-ef39-4a6c-bec3-ca266bf53ed6/mural-view

• From the list of Rooms (See Search rooms or List all rooms)

OwnerId

• If the owner is yourself, use the /api/settings/v1/users/me endpoint and retrieve your id

• Otherwise, retrieve the user from the list of assignable users

Create a Board Element with a new Data Element

In this example, we will see how to create an Objective on a board with the status set to “New” and the title “This is an objective”.

Request

POST /v0/board-elements (See endpoint)

{
  "boardId": "15823da0-b962-4a79-bf3c-189c148ff117",
  "viewTypeId": "f6885b7e-6f17-4bc4-9883-ae847bc3a8f2",
  "position": {
    "x": 3653,
    "y": 1247
  },
  "width": "254",
  "height": "190",
  "datasetElement": {
    "typeId": "e2a4379d-0b7a-4b64-8fae-f7857cf1b3f7",
    "attributes": {
      "status": "status.new",
      "title": "This is an objective"
    },
    "roomId": "f2d0af20-0da4-47ee-84ef-72521bb285b3"
  },
  "zIndex": 1
}

As shown in the request payload, several additional properties are required:

• BoardId : the target board (See previous section)

• RoomId: only if datasetElement need to be created (See previous section)

• OwnerId: only if datasetElement need to be created (See previous section)

• ViewTypeId : Identifies the visual representation of the element on the board (for example, card, note, or sticker).

• TypeId: Identifies the underlying data type of the element (such as Objective, Task, KPI, etc.)

• position : Defines the element’s position on the board using x and y coordinates.

• size: Defines the dimensions of the element using width and height values.

• z-index: Z index of the element

Position on the Board

The board uses a coordinate system where the origin (0, 0) is located at the top-left corner.

All element positions are defined relative to this origin using x and y coordinates.

ViewTypeId

View types can be retrieved via GET /v0/element-view-types

Common View Types

TypeId

Below is the list of available Data Type IDs. You can also retrieve them dynamically using the API endpoint: GET /v0/element-data-types.

Create a Board Element with a existing Data Element

To add an existing Data Element to a board, you must use the dedicated endpoint and provide the DatasetElementID.

You can retrieve this identifier from :

• the Information panel of the Data Element in the editor

• or by extracting it from the response of a search request.

POST /v0/dataset-elements/<DatasetElementId>/board-elements  (See endpoint)

{
  "boardId": "15823da0-b962-4a79-bf3c-189c148ff117",
  "viewTypeId": "f6885b7e-6f17-4bc4-9883-ae847bc3a8f2",
  "position": {
    "x": 3653,
    "y": 1348
  },
  "width": "254",
  "height": "190",
  "datasetElement": {
    "typeId": "e2a4379d-0b7a-4b64-8fae-f7857cf1b3f7"
  },
  "roomId": "f2d0af20-0da4-47ee-84ef-72521bb285b3",
  "zIndex": 17
}

Add a Sticker (Decorative Element)

Example request to add a sticker to a board. Sticker go

{
  "boardId": "15823da0-b962-4a79-bf3c-189c148ff117",
  "viewTypeId": "3069e307-b259-4d0c-8ab3-19ad39a2ad22",
  "position": {
    "x": 3720,
    "y": 1725
  },
  "width": 102,
  "height": 102,
  "attributes": {
    "iconName": "go"
  },
  "datasetElement": {
    "typeId": "3459e307-b259-4d0c-8ab3-19ad39a2ad21",
    "attributes": {},
    "roomId": "f2d0af20-0da4-47ee-84ef-72521bb285b3"
  },
  "zIndex": 1
}

In this case, the attributes property is used to configure decorative elements.

For stickers, this property accepts a predefined set of values (non-exhaustive).

Additionnal informations

Size of Card

Exemple of Size of Card.

Size of Board

width : 7560

height: 3600

Custom Color

If you want to set a custom color on Card, you can send customColor in the viewType’s attributes.
The value is an hexadecimal with transparency  like (#ED4C56FF).

customColor is part of viewTypes attributes, not the datasetElement.attributes

{
  ...
  "position": {
    "x": 3653,
    "y": 1247
  },
  "viewTypeId": "f6885b7e-6f17-4bc4-9883-ae847bc3a8f2",
  "attributes": {
    "customColor": "#ED4C56FF"
  },
  ...
}

Troubleshooting

My boardelement is not displayed

If the element does not appear immediately, wait a few seconds. The data may need time to synchronize with collaborative sessions.