Views Menu V1 Reference

General information

View Menu V1 is considered obsolete. Please look at View Menu V2 for a new version which supports nested groups

Views menu is a tree-like structure which represents a set of "views" available for the user.
Each menu item is either a view (e.g. board, report, dashboard, or even an entity) or a group of views.
Note that entity views are not supported at the moment and nested groups are supported only in View Menu V2.

Storage

Menu items are stored in Client Storage, which brings several implications:

  • Each menu item consists of public data and user data storages,
  • Menu items can't be queried or manipulated like regular resources.

Public/user data

Each menu item can be represented as a set of key-value pairs, stored in two dictionaries.

The first one is a "Public data" which contains the fields specified by the item's owner(s), e.g. board's name or cells definition. These fields are considered shared between users and they represent the core essence of the menu item itself.
Public fields have a checked mark in "Is public" column of the types table below.

However, non-owner users can override some of the public data fields, e.g. a user may not be happy with the zoom level set by board owner and he may want to change it. These user overrides are stored in a "user data".
When a user retrieves a menu item, API service first constructs a public data dictionary and then overrides its values with the values found in user data dictionary.
Not every field can belong to a user data, but those who can have a checked mark in "User can override" column of the types table.

Some fields are always user-specific and can't belong to the public data at all.
These fields have "User can override" mark but don't have "Is public" mark.

There are also special cases – when item owner or admin modifies his menu item, he may want to apply the changes of some fields to all users.
Such special fields have a checked mark in "Public for owner or admin" column of the types table.

Data formats

It is assumed that every field is stored in a client storage as a proper JSON value.
For example, the board name Hello, world is stored as "Hello, world".
API service will try to compensate for the incorrect encodings, but it's better to ensure that you store the proper values when working with Client Storage directly.

The "Type" column of the types table lists the data types of specific fields.
JSON means that there is no explicit knowledge of the underlying type of this field and that it can accept any dynamic JSON-value.
[TYPE_NAME] means "collection of TYPE_NAME".

Menu items

BoardDto

Field name Type Is public User can override Public for owner or admin Description
Acid String       "Application context ID", representing saved teams and projects to be used as a context for the view
AggregationsOnAxesSettings JSON       Aggregations on axes settings
CardSettings JSON       Card customization settings for this view, describes a structure of card units for each selected cell entity.
CellPaging JSON      
Cells BoardSpaceDefinition       Data definition for slice cells
Collapse JSON       Expansion state of view lanes
ColorSettings ColorSettings       Color settings for cards on lists, boards, timelines and details view
ColumnSizes JSON       Sizes of view lanes – how much cards can be placed on a single row inside a column cell
CreatedAt String       View creation date
CustomSharedData MenuItemCustomSharingState       Team-/project-sharing settings
DefaultUserFilters UserFilters       Defines compiled default filters used by ViewContext services
DisableInnerLevels Boolean       Defines whether inner levels in lists (4th level) should be hidden
DynamicProperties [KeyValuePair`2]      
Edit Boolean      
Focus JSON       High-level board lane focusing settings
HideEmptyLanes Boolean       User-specific setting to hide empty lanes (i.e. lanes where all cells are empty) on view in "Board" or "Timeline" modes
HierarchyMode String      
IsFavorite Boolean       True if user marked item as favorite. False otherwise.
IsShared Boolean       Menu item access level. True if item is public or team-/project-shared
ItemType MenuItemType      
Key String       Unique menu item identifier
LastOpenedAt String       Date and time when particular view was opened last time. Serialized according to ISO 8601
Limits JSON      
ListUserSettings JSON       Custom user settings for the list view mode
MenuGroupKey String       Id of the menu group this item belongs to
MenuIsVisible Boolean       True if item is visible in the user's menu, False if user decided to hide it
MenuNumericPriority Double       Numeric value determining the absolute position of the item in the menu. First menu items have lower values than the last ones
MilestonesOnCardsSettings JSON       Milestone on cards settings
Name String      
OwnerIds [Int32]       List of view menu item owner IDs
Page PageSettings       Current view paging settings
PossibleViewModes JSON      
Prioritization JSON       Card prioritization settings for the given view – JSON value with "mode" property, which can be true, false or "shift" to enable card prioritization, disable it or enable when SHIFT key is pressed
SelectedMarks JSON       Focused board lanes
TimelineGlobalDateRange String      
TimelineIsCustomGlobalDateRange Boolean      
TimelineLocalDateRange String      
TimelineSettings TimelineSettings       Timeline-specific view settings
User JSON       User-specific view settings, like custom filter
UserAcid String       User-specific "Application context ID"
UserFilters UserFilters       Defines compiled filters overrides per user used by ViewContext services
ViewMode String       Current view mode
X BoardSpaceDefinition       Data definition for the first slice dimension
XGrouping JSON      
XGroupingStatus String      
Y BoardSpaceDefinition       Data definition for the second slice dimension
YGrouping JSON      
YGroupingStatus String      
ZoomLevel ZoomLevel       Current size of the cards on the view, stored per view mode

CustomReportDto

Field name Type Is public User can override Public for owner or admin Description
Acid String       "Application context ID", representing saved teams and projects to be used as a context for the view
CustomSharedData MenuItemCustomSharingState       Team-/project-sharing settings
DynamicProperties [KeyValuePair`2]      
Edit Boolean      
IsExternal Boolean      
IsFavorite Boolean       True if user marked item as favorite. False otherwise.
IsShared Boolean       Menu item access level. True if item is public or team-/project-shared
ItemType MenuItemType      
Key String       Unique menu item identifier
LastOpenedAt String       Date and time when particular view was opened last time. Serialized according to ISO 8601
Link String      
MenuGroupKey String       Id of the menu group this item belongs to
MenuIsVisible Boolean       True if item is visible in the user's menu, False if user decided to hide it
MenuNumericPriority Double       Numeric value determining the absolute position of the item in the menu. First menu items have lower values than the last ones
Name String      
OwnerIds [Int32]       List of view menu item owner IDs
ReportSettings ReportSettings      
UserAcid String       User-specific "Application context ID"

DashboardDto

Field name Type Is public User can override Public for owner or admin Description
Acid String       "Application context ID", representing saved teams and projects to be used as a context for the view
CustomSharedData MenuItemCustomSharingState       Team-/project-sharing settings
DynamicProperties [KeyValuePair`2]      
Edit Boolean      
IsFavorite Boolean       True if user marked item as favorite. False otherwise.
IsShared Boolean       Menu item access level. True if item is public or team-/project-shared
ItemType MenuItemType      
Key String       Unique menu item identifier
LastOpenedAt String       Date and time when particular view was opened last time. Serialized according to ISO 8601
Layout JSON      
MenuGroupKey String       Id of the menu group this item belongs to
MenuIsVisible Boolean       True if item is visible in the user's menu, False if user decided to hide it
MenuNumericPriority Double       Numeric value determining the absolute position of the item in the menu. First menu items have lower values than the last ones
Name String      
OwnerIds [Int32]       List of view menu item owner IDs
UserAcid String       User-specific "Application context ID"

MiroBoardDto

Field name Type Is public User can override Public for owner or admin Description
Acid String       "Application context ID", representing saved teams and projects to be used as a context for the view
CustomSharedData MenuItemCustomSharingState       Team-/project-sharing settings
DynamicProperties [KeyValuePair`2]      
Edit Boolean      
IsFavorite Boolean       True if user marked item as favorite. False otherwise.
IsShared Boolean       Menu item access level. True if item is public or team-/project-shared
ItemType MenuItemType      
Key String       Unique menu item identifier
LastOpenedAt String       Date and time when particular view was opened last time. Serialized according to ISO 8601
MenuGroupKey String       Id of the menu group this item belongs to
MenuIsVisible Boolean       True if item is visible in the user's menu, False if user decided to hide it
MenuNumericPriority Double       Numeric value determining the absolute position of the item in the menu. First menu items have lower values than the last ones
MiroBoardData JSON      
Name String      
OwnerIds [Int32]       List of view menu item owner IDs
UserAcid String       User-specific "Application context ID"
Field name Type Is public User can override Public for owner or admin Description
CanAcceptItems Boolean       True if the user has access to move the views to the group
CustomSharedData MenuItemCustomSharingState       Team-/project-sharing settings
DynamicProperties [KeyValuePair`2]      
IsExpanded Boolean       True if group is visually expanded in all section, and the user sees its items
IsExpandedInFavorites Boolean       True if group is visually expanded in favorites section, and the user sees its items
IsFavorite Boolean       True if user marked item as favorite. False otherwise.
IsShared Boolean       Menu item access level. True if item is public or team-/project-shared
ItemType MenuItemType      
Key String       Unique menu item identifier
MenuGroupKey String       Id of the menu group this item belongs to
MenuIsVisible Boolean       True if item is visible in the user's menu, False if user decided to hide it
MenuNumericPriority Double       Numeric value determining the absolute position of the item in the menu. First menu items have lower values than the last ones
Name String      
OwnerIds [Int32]       List of view menu item owner IDs

ViewStatistics

Field name Type Is public User can override Public for owner or admin Description
Key String       Unique menu item identifier
LastOpenedByAnotherUser String       Date and time when the view was open last time by any user other than the current one. The format is ISO 8601.

Data types

Represents possible types of view menu items
Property Type Description
Unknown MenuItemType
Board MenuItemType
Group MenuItemType
Section MenuItemType
Dashboard MenuItemType
CustomReport MenuItemType
MiroBoard MenuItemType
Describes custom sharing (team- or project-sharing) settings of menu item
Property Type Description
IsActive Boolean On/off toggle for custom sharing. If this toggle is off, but the item.IsShared is true, then the item is publicly shared
ProjectIds [Int32] Collection of project IDs this item is shared to
TeamIds [Int32] Collection of team IDs this item is shared to
UserIds [Int32] Collection of user IDs this item is shared to

BoardSpaceDefinition

Describes a single dimension of multi-dimensional board, like lanes or cells, and the corresponding data request format acceptable by Slice API
Property Type Description
Types [String] Collection of entity types on this slice level, e.g. a type board entity lane or types represented by cards on a board
AxisGroup String Name of the group which axis type belongs to (Basic, Custom fields, Extendable Domain, etc.)
FilterDisplay String A string representing a where-like data filter for this slice level. This is filter that is edited by user. It then transformed and copied to Filter field.
Filter String A string representing a where-like data filter for this slice level. This is filter that is used in slice calls. See FilterDisplay.
UseFilter Boolean A toggle enabling or disabling data filtering for the request
Ordering OrderingDefinition Description the ordering applied to entity set

OrderingDefinition

Property Type Description
Name String Name of the the property the entity is ordered by
DisplayName String Display Name of the property the entity is ordered by
Direction OrderingDirection Ascending or descending ordering direction
IsDefault Boolean Default ordering for resource

OrderingDirection

Property Type Description
Asc OrderingDirection
Desc OrderingDirection

TimelineSettings

Property Type Description
ShowPlannedInPast Boolean
ShowForecast Boolean
ShowMilestones Boolean
ShowPeriodLanes Boolean

PageSettings

Property Type Description
X Int32
Y Int32

ZoomLevel

Describes stored zoom levels (sizes of the cards displayed on a view) for various view modes
Property Type Description
Board Int32 Zoom level on the "View" mode
List Int32 Zoom level on the "One by one" mode
Newlist Int32 Zoom level on the "List" mode
Timeline Int32 Zoom level on the "Timeline" mode

Menu structure

When getting a menu structure for a user with GetMenuTreeForCurrentUser action, the response is returned in a tree-like structure represented by a collection of MenuSection items.
Each item has ItemType property, determining its type, e.g. board or group, and ItemData property containing the item data itself.
Additionaly, sections contain their groups and groups contain their item collections.

Here is the sample response of the menu structure API: 

{
  "items": [
    {
      "itemType": "section",
      "itemData": {
        "sectionType": "other"
      },
      "children": [
        {
          "itemType": "group",
          "itemData": {
            "key": "Ungrouped",
            "itemType": "group"
          },
          "children": [
            {
              "itemType": "board",
              "itemData": {
                "key": "13",
                "name": "Office library",
                "itemType": "board"
              }
            },
            {
              "itemType": "board",
              "itemData": {
                "key": "14",
                "name": "Roadmap",
                "itemType": "board"
              }
            }
          ]
        }
      ]
    }
  ]
}

Operations

Here is a list of available API endpoints.

Description Parameters Returns
CreateMenuGroup
POST, PUT api/views/v1/group

Creates a new menu group using the posted data and assigns it a semi-randomly generated ID.
CreateView
POST, PUT api/views/v1/view

Creates a new view using the posted data and assigns it a semi-randomly generated ID.
  • view (ViewDto)
ViewDto
GetMenuTreeForCurrentUser
GET api/views/v1

Constructs an entire view menu structure with sections and groups for the currently logged in user. Applies visibility and access rights filters. Use this method to get a visual representation of the menu user sees in the application.
Not specified
GetViewsForGroup
GET api/views/v1/view/forGroup/{groupId}

Retrieves the collection of views in group with the specified ID.
  • groupId (String)
Not specified
Collection of views in group
MenuGroup
GET api/views/v1/group/{id}

Retrieves the information about the menu group with the specified ID. Fails if the current user doesn't have access to the group or the group doesn't exist.
  • id (String)
MenuGroup
POST api/views/v1/group/{id}

Updates the existing menu group if the current user has permissions to do that. Creates a new one with the given ID if the group doesn't exist. Can be used to restore the removed group data.
Not specified
MenuGroup
DELETE api/views/v1/group/{id}

Deletes the menu group with the specified ID. Doesn't fail if the group doesn't exist. Fails if the current user doesn't have access to it.
  • id (String)
Not specified
PrioritizeMenuGroup
POST api/views/v1/prioritize/group

Changes the priority of the specified menu group, placing it before or after another one by modifying its priority value.
  • itemId (String)
    ID of a group to prioritize
  • targetItemId (String)
    ID of a target group which is used as prioritization anchor
  • placeAfter (Boolean)
    True if item should be placed after target
Not specified
Collection of menu groups affected by prioritization
PrioritizeView
POST api/views/v1/prioritize/view

Changes the priority of the specified view, placing it before or after another one by modifying its priority value.
  • itemId (String)
    ID of a views to prioritize
  • targetItemId (String)
    ID of a target views which is used as prioritization anchor
  • placeAfter (Boolean)
    True if item should be placed after target
Not specified
Collection of views affected by prioritization
View
GET api/views/v1/view/{id}

Retrieves the information about the view with the specified ID. Fails if the current user doesn't have access to the view or the view doesn't exist.
  • id (String)
ViewDto
View
POST api/views/v1/view/{id}

Updates the existing view if the current user has permissions to do that. Creates a new one with the given ID if view doesn't exist. Can be used to restore the removed view data.
  • id (String)
  • definition (ViewDto)
ViewDto
View
DELETE api/views/v1/view/{id}

Deletes the view with the specified ID. Doesn't fail if the view doesn't exist. Fails if the current user doesn't have access to it.
  • id (String)
Not specified

Remarks

Data update operations support partial data requests, which means only the fields explicitly specified in the request body are updated by the service.
For example, the following request will only update name and isFavorite fields but won't change cells field or anything else. 

{
    name: "New name",
    isFavorite: false
}

It also means that primitive values, like boolean or numeric, are actually stored as nullable values, so it's absolutely legal to post isFavorite: null, API will treat it as the 'absence of value' and won't change the field.
Similarly, if you receive a null value in the response, it means that the field doesn't have any value yet.