Project Views


A Project View is a record that configures a Navigator scene: the Menu Items that load data into it, the basemaps and terrains on offer, who can open it and what happens when an Entity is selected. You manage Project Views in Operator and open them in Navigator.

Each Project View holds a list of Bookmarks. A Bookmark is a saved state of the scene: the camera, the enabled Menu Items, the basemaps, the time and the state of individual Entities. A Bookmark can also show a Custom Dashboard, an embedded web page or a 2D diagram instead of the 3D scene. Bookmarks can be sorted into Bookmark groups.

"Slide" is an older name for a Bookmark. The API still uses it in routes and field names such as "UI.SlideGroup.ID". This article will cover how to manage Project View, Bookmark and Bookmark group records and descriptions about their settings.

Data model

Below is the core data model for a Project View. You can manage a record without populating the settings.

interface IProjectView {
    // Unique ID of the Project View. Limited to 60 characters.
    // You pick the ID when you create the record. Navigator links use it, so a short ID keeps them short.
    ID: string;
    // Human readable name. Limited to 60 characters.
    Name: string;
    // Description of what the Project View is for.
    Description?: string;
    // The application the Project View is for. Limited to 20 characters.
    // Default is "WEB_3D_NAVIGATOR".
    Type?: string;
    // Version of the settings structure.
    // Default is 2.
    DataVersion?: number;
    // The Project View settings.
    // See the settings section below for the structure.
    Settings?: IProjectViewSettings;
    // When true, this is the account's default Project View.
    // Setting it on one record clears it on every other record.
    IsDefault?: boolean;
    // When true, the record cannot be deleted until this is set back to false.
    IsDeleteDisabled?: boolean;
    // Email address that Navigator's contact dialog sends messages to. Limited to 120 characters.
    // Only returned to users who can edit the Project View.
    SupportEmail?: string;
    // Version of the application that created the record. Limited to 10 characters.
    CreatedByUIVersion?: string;
    // ID of the User who created the record, set by the API.
    "CreatedByUser.ID"?: string;
    // ISO 8601 date time strings, set by the API.
    Created?: string;
    Updated?: string;
    // How many times the record has been requested, counted by the API.
    Interactions?: number;
    // Up to 8 Bookmarks to preview the Project View with, set by the API.
    // Drafts are left out. Ordered by display order.
    Thumbnails?: {
        // Bookmark ID.
        ID: string;
        Title: string;
        "Screenshot.ClientFile.ID": string;
        // Download URL for the thumbnail.
        "Screenshot.URL"?: string;
        Interactions: number;
    }[];
    // What the requesting user can do with this record.
    // A combination of "C" (create), "R" (read), "U" (update) and "D" (delete). Eg: "RU".
    // This is returned by the API and ignored when saving.
    Permission?: string;
}

Settings

The settings hold everything Navigator needs to set up the scene. Larger parts have their own sections below, and the smaller ones are described here.

Settings are replaced as a whole on update, so send the full settings rather than only the part that changed.

interface IProjectViewSettings {
    // Who can open the Project View.
    // See the access section below.
    IsLoginRequired?: boolean;
    IsRestricted?: boolean;

    // The Menu Items users can toggle and Bookmarks can enable.
    // You can read about their structure in Project View Menu Items.
    menuItems?: IMenuItem[];

    // Basemaps and terrains pinned in Navigator's lists for users to pick from.
    // See the basemaps and terrains section below.
    imageries?: ITile[];
    terrains?: ITile[];

    // Values a Bookmark falls back to when it leaves them out.
    // See the Bookmark defaults section below.
    defaults?: {
        camera?: IBookmarkCamera;
        settings?: IBookmarkDefaultSettings;
    };

    // What happens when a user selects an Entity.
    // See the Entity selection section below.
    selection?: ISelection;

    // CSS colour string applied to selected Entities.
    // Default is yellow at 50% opacity.
    selectionColor?: string;
    // CSS colour string applied to highlighted Entities. Eg: when hovering over a row in the Scene Tree.
    // Default is "#33b1ff" at 50% opacity.
    highlightColor?: string;

    branding?: {
        // ID of a Client File image shown as a banner at the top of Navigator's left side Bookmarks and Comments panels.
        bannerFileId?: string;
    };

    // Presentation mode, which steps through the Bookmarks one after another.
    present?: {
        // Milliseconds each Bookmark is held before moving to the next.
        // Default is 5000.
        bookmarkDuration?: number;
    };

    // A contact button in Navigator's top bar that emails the record's "SupportEmail".
    // The button is hidden while a model-space Bookmark is open.
    contact?: {
        // Default is false.
        enabled: boolean;
        // Text shown in the contact dialog.
        description?: string;
        // CSS class names of a Font Awesome icon for the button.
        // Default is the Nextspace support icon.
        icon?: string;
    };

    plugins?: {
        // IDs of the UI Plugins Navigator loads for this Project View.
        enabledIds: string[];
    };
}

You can read about Menu Items in Project View Menu Items and about plugins in Navigator plugins.

Settings: Access

Two settings control who can open a Project View and its Bookmarks. They are stored as their own columns but read and written through the settings, and the API always returns both.

interface IProjectViewSettings {
    // When false, anyone with the link can open the Project View, including users who are not signed in.
    // Default is false. Operator sets it to true on new Project Views.
    IsLoginRequired?: boolean;
    // When true, only users whose User Groups have been given access to this Project View can open it.
    // Only read when "IsLoginRequired" is true.
    // Default is false.
    IsRestricted?: boolean;
}

So a Project View is either public, open to every signed in user of the account, or restricted to chosen User Groups. You grant User Groups access in Operator. Account administrators and users with access to every Project View can open them all. The list request only returns the Project Views the requesting user can open.

Editing a Project View, and managing its Bookmarks, are separate permissions from opening it. The "Permission" value on each record tells you what the requesting user can do with it.

Basemaps and terrains

A Project View lists the basemaps ("imageries") and terrains ("terrains") pinned in Navigator for users to pick from. A Bookmark then says which basemaps and which terrain are enabled. Both use the same tile reference, and a Bookmark basemap adds display values on top.

If the account has no Cesium Ion key, Navigator replaces the Bing basemaps with Mapbox ones and Cesium World Terrain with flat terrain.

// Shape of the "imageries" and "terrains" entries on a Project View, and of a Bookmark's "terrain".
interface ITile {
    // ID of the Tileset to load.
    // Either an imported Tileset, an external source you have set up, or one of the default IDs below.
    tilesetId: string;
    // Account to load the Tileset from, when it belongs to another Nextspace account you manage.
    // Leave empty for your own account and for the default IDs.
    accountId?: string;
}

// Shape of the "imagery" entries on a Bookmark.
interface IBookmarkImagery extends ITile {
    // From 0 to 1, where 1 is 100% opacity.
    // Default is 1.
    alpha?: number;
    // Default is 1.
    brightness?: number;
    // Default is 1.
    saturation?: number;
    // Default is 1.
    contrast?: number;
    // Default is 1.
    gamma?: number;
    // Default is 0.
    hue?: number;
}

/**
 * Default basemap IDs:
 * "bingmapsaerial", "bingmapsaerialwithlabels", "bingmapsroads",
 * "mapboxsatellite", "mapboxstreets", "mapboxstreetsclassic",
 * "esriworldimagery", "esriworldstreetmap", "esrinationalgeographic",
 * "openstreetmap", "linz", "stamenwatercolor", "stamentoner",
 * "thunderforestcycle", "thunderforesttransport", "thunderforestlandscape", "grid".
 *
 * Default terrain IDs:
 * "cesiumworldterrain", "flatterrain", "linz".
 */

Settings: Entity selection

The selection settings decide what happens when a user selects an Entity in Navigator. Navigator looks for a mapping with the Entity's Entity Type first, then uses the default action. Without either, the Entity opens in the Info View, our standard Entity details panel.

interface ISelection {
    // Action for Entities whose Entity Type has no mapping.
    // Default is the "INFO_VIEW" action.
    defaultAction?: ISelectionAction;
    // Actions per Entity Type. Each item must have an "entityTypeId".
    entityTypeMapping?: ISelectionAction[];
}

interface ISelectionAction {
    // The Entity Type this action applies to.
    // Leave empty on the default action.
    entityTypeId?: string;
    /**
     * INFO_VIEW = open the Info View panel.
     * CUSTOM_FORM = open a Custom Form instead.
     * PLUGIN = open a UI Plugin instead.
     * NONE = the Entity cannot be selected.
     */
    action: "INFO_VIEW" | "CUSTOM_FORM" | "PLUGIN" | "NONE";
    // Params for the action, matching its type below.
    actionParams?: IActionInfoView | IActionCustomForm | IActionPlugin;
}

interface IActionInfoView {
    // The Info View tabs to show. Leave empty to show them all.
    tabs?: ("SUMMARY" | "ATTRIBUTES" | "RELATIONSHIPS" | "FILES" | "MEDIA" | "COMMENTS" | "GRAPHICS" | "LODS")[];
    // Set to 1. Without it the "ATTRIBUTES" tab is always shown.
    dataVersion?: number;
}

interface IActionCustomForm {
    // ID of the Custom Form to show.
    formId: number;
}

interface IActionPlugin {
    // ID of the UI Plugin to show.
    pluginId: string;
}

You can read about Custom Forms in Custom Forms.

Settings: Bookmark defaults

The "defaults" setting holds a camera and any of the Bookmark settings described further down. When a Bookmark leaves a value out, Navigator uses the Project View's default, then its own default.

The settings that fall back this way are "contentType", "imagery", "terrain", "terrainWireframe", "globeColor", "globeAlpha", "globeHidden", "groundOcclusion", "hillShades", "quality", "shadows", "ambientOcclusion", "lighting", "dateTime", "timeline" and "states". The enabled Menu Items, markup, contours, weather and walkthrough are only read from the Bookmark.

The camera default is used when a Bookmark's camera has no valid latitude, longitude and altitude. Its "cameraFrustum" and "transition" are used when the Bookmark leaves those out.

Two more settings live in the defaults and apply to the whole Project View rather than to one Bookmark.

interface IBookmarkDefaultSettings extends IBookmarkSettings {
    // Search sources selected by default in Navigator's search bar.
    // Any of "GOOGLE", "CESIUM", "ENTITY", "ENTITY_ID" and "LATLON".
    // When none are set, the first available source is selected.
    searchbarOptions?: string[];

    // Settings for Ask Nextspace, the chat assistant.
    llms?: {
        // Conversation starters offered in an empty conversation, in display order.
        // Operator allows up to 8.
        starters?: string[];
        // ID of the Ontology new conversations are scoped to.
        ontologyId?: number;
    };
}

Requesting Project Views

You can request a list of Project Views or one by its ID. The list leaves out the settings unless you set "expand", and returns everything in one page unless you set a page size.

Get a list of Project Views

Response
interface IResponse {
    Items: IProjectView[];
    // Only included on the first page.
    TotalCount?: number;
}
Javascript example

Get a Project View by ID

Response
// The response is the Project View record directly.
// See the data model above for the record structure.
interface IResponse extends IProjectView {
    // Only included when "Expand" is set.
    // Drafts made by other users are left out.
    "UISlide"?: IBookmark[];
    "UISlide.Group"?: IBookmarkGroup[];
}
Javascript example

Get the Project View of a Bookmark

Response
// The response is the same as getting the Project View by its ID.
Javascript example

Check a Project View ID is available

Response
interface IResponse {
    IsAvailable: boolean;
}
Javascript example

Create and update Project Views

You create a Project View with a POST to the ID you picked, and update it with a PUT to the same route. A POST to an ID that is already in use fails with an "IDConflict" error.

An update only changes the top level fields you include. The settings are replaced as a whole.

Operator also creates a first Bookmark named "Default" for each new Project View. The API does not, so create one yourself if you want Navigator to open on a saved state.

Create a Project View

Request body
// The body is the Project View record directly.
// See the data model above for the record structure.
interface IRequest extends IProjectView {
    // Optional ID of another Project View to copy the settings from.
    "CopyFrom.UI.View.ID"?: string;
}
Response
// The response is the Project View record directly.
// See the data model above for the record structure.
Javascript example

Update a Project View

Request body
// The body is the Project View record directly.
// Only the fields you include are changed.
Response
// The response is the Project View record directly.
// See the data model above for the record structure.

Delete a Project View

We don't provide any bulk deletion but you can delete by record ID. The Project View's Bookmarks and Bookmark groups are deleted with it. A Project View with "IsDeleteDisabled" set cannot be deleted. Deleting an ID that does not exist still succeeds.

Delete a Project View

Javascript example

Send a support message

This is the request behind Navigator's contact dialog. It emails the message to the Project View's "SupportEmail", and fails with a not found error when none is set. Users who are not signed in can send one if they can open the Project View.

Send a support message

Request body
interface IRequest {
    // The message to send.
    Message: string;
    // Email address to reply to.
    ContactEmail: string;
    // Name of the person sending it.
    ContactName?: string;
}
Javascript example

Bookmark data model

Below is the core data model for a Bookmark. The camera and settings are described in the sections that follow.

interface IBookmark {
    // Unique ID of the Bookmark, generated by the API. Limited to 40 characters.
    // Exclude this value for new records.
    ID?: string;
    // ID of the Project View the Bookmark belongs to. Set by the API from the route.
    "UI.View.ID"?: string;
    // Title shown in Navigator. Limited to 200 characters.
    Title?: string;
    // Description of the Bookmark.
    Note?: string;
    // ID of the Bookmark group the Bookmark is in. 0 means ungrouped.
    // See the Bookmark groups section below.
    "UI.SlideGroup.ID"?: number;
    // Position in the Project View's Bookmark list, lowest first.
    DisplayOrder?: number;
    // Version of the settings structure.
    // Default is 2.
    DataVersion?: number;
    // When true, the Bookmark is a draft. See below.
    // Default is false.
    Draft?: boolean;
    // Camera position.
    // See the camera section below.
    Camera?: IBookmarkCamera;
    // What the Bookmark shows.
    // See the content types section below.
    Settings?: IBookmarkSettings;
    // ID of the Client File used as the thumbnail.
    // Navigator uploads a 240 by 120 JPEG with the Client File purpose "Bookmark Thumbnail".
    "Screenshot.ClientFile.ID"?: string;
    // Download URL for the thumbnail, set by the API.
    "Screenshot.URL"?: string;
    // ID of the User who created the Bookmark, set by the API.
    "CreatedBy.User.ID"?: string;
    // ISO 8601 date time strings, set by the API.
    Created?: string;
    Updated?: string;
    // How many times the record has been requested, counted by the API.
    Interactions?: number;
    // What the requesting user can do with this record.
    // A combination of "C" (create), "R" (read), "U" (update) and "D" (delete). Eg: "RU".
    // This is returned by the API and ignored when saving.
    Permission?: string;
}

A draft Bookmark is only listed to the User who created it, and Navigator marks it as "Your Draft". Anyone who can open the Project View can still get a draft by its ID, except users who are not signed in.

A User Group can be allowed to manage only their own draft Bookmarks on a Project View. Bookmarks those users create are always saved as drafts, and they can only change or delete drafts they created.

Bookmark: Camera

The camera is where Navigator flies to when the Bookmark opens. A "WEB_3D" Bookmark uses latitude, longitude and altitude, and a "WEB_3D_MODEL_SPACE" Bookmark uses x, y and z.

interface IBookmarkCamera {
    // Position for "WEB_3D" Bookmarks, in WGS84 degrees.
    latitude?: number;
    longitude?: number;
    // Metres above the WGS84 ellipsoid.
    altitude?: number;

    // Position for "WEB_3D_MODEL_SPACE" Bookmarks, in metres from the model space origin.
    x?: number;
    y?: number;
    z?: number;

    // Camera orientation in degrees.
    heading?: number;
    pitch?: number;
    roll?: number;

    // Milliseconds the camera takes to fly to this Bookmark.
    // Default is 2000.
    transition?: number;
    // 0 = perspective, 1 = orthographic, which Navigator shows as its 2D mode.
    // Default is 0.
    cameraFrustum?: 0 | 1;
}

The camera moves instantly instead of flying when the frustum changes, and when moving into or out of model space over more than 10 km. A model space Bookmark without a valid position opens 500 metres above the origin, looking straight down.

Bookmark: Content types

The "contentType" setting decides what the Bookmark shows. Navigator offers each of these when you create a Bookmark. The scene settings in the next sections only apply to "WEB_3D" and "WEB_3D_MODEL_SPACE".

interface IBookmarkSettings {
    /**
     * WEB_3D = a 3D scene on the globe. This is the default.
     * WEB_3D_MODEL_SPACE = a 3D scene without geospatial context, with no basemaps and ground occlusion off.
     * DASHBOARD = a Custom Dashboard. Camera and scene settings are ignored.
     * IFRAME = an embedded web page. Camera and scene settings are ignored.
     * DIAGRAM = a 2D diagram. See the diagram section below.
     */
    contentType?: "WEB_3D" | "WEB_3D_MODEL_SPACE" | "DASHBOARD" | "IFRAME" | "DIAGRAM";

    // ID of the Custom Dashboard to show.
    // Only read when contentType is "DASHBOARD".
    dashboardId?: number;

    // URL of the page to embed.
    // Only read when contentType is "IFRAME".
    iframeUrl?: string;

    // Markup drawn over the Bookmark.
    // See JSON: Markup for the structure.
    markup?: IMarkup;

    // The remaining settings are described in the sections below.
}

When an "iframeUrl" is on one of our embed hosts (Eg: embed.nextspace.host), Navigator substitutes these placeholders before loading it: ${ssid} and ${sessionId} with the user's session ID, and ${accountId}, ${envId}, ${viewId}, ${bookmarkId} and ${userId}. Other URLs are loaded as they are.

You can read about Dashboards in Custom Dashboards and about the markup structure in JSON: Markup.

Bookmark: Menu Items

A Bookmark enables Menu Items from its Project View by ID. Menu Items that are not listed are turned off when the Bookmark opens. Enabling a folder Menu Item enables its children too, or one of them when the folder's children act as radio buttons.

A Bookmark can also change some values of an enabled Menu Item without changing the Project View. A value the Bookmark leaves out uses the Menu Item's own value.

interface IBookmarkSettings {
    // IDs of the Project View Menu Items to enable.
    menuItemIds?: string[];

    // Changes to enabled Menu Items for this Bookmark only, keyed by Menu Item ID.
    menuItemAlternations?: { [menuItemId: string]: IMenuItemAlternation };

    // Relationship lines to draw, regardless of which Menu Items are enabled.
    renderedRelations?: {
        // Entities to draw downstream relationships for.
        entityIds: string[];
        // The Relation Type to draw.
        relationTypeId: string;
    }[];
}

interface IMenuItemAlternation {
    // Entity Type items that show individual Tags: the Tag IDs to show.
    BruceEntity?: {
        SelectedExpandLayers?: number[];
    };

    // Entities tileset items: point cloud attenuation.
    attenuation?: boolean;
    attenuationMax?: number;

    // Items with more than one Style: the Style to use, from the item's "styleIds".
    styleId?: number | string;
    // Items with zoom control rows set the Style here instead.
    CameraZoomSettings?: {
        StyleID: number | string;
    }[];
}

You can read about Menu Items, folders and their zoom control rows in Project View Menu Items.

Bookmark: Scene

These settings set up the globe, basemaps, terrain and effects. The defaults listed are used when neither the Bookmark nor the Project View defaults set a value.

interface IBookmarkSettings {
    // Enabled basemaps, bottom to top. An empty array shows no basemap.
    // See the basemaps and terrains section above for the shape.
    // Default is Mapbox Satellite. Always empty for "WEB_3D_MODEL_SPACE".
    imagery?: IBookmarkImagery[];
    // Enabled terrain. Only one terrain is enabled at a time.
    terrain?: ITile;
    // Draws the terrain as a wireframe.
    // Default is false.
    terrainWireframe?: boolean;

    // CSS colour string for the globe under the basemaps.
    // Default is "#0326BE".
    globeColor?: string;
    // Opacity of the globe, from 0 to 1, when the camera is within 400 metres of it.
    // It fades back to opaque by 800 metres. Lower it to see underground data.
    // Default is 1.
    globeAlpha?: number;
    // Hides the globe. Eg: to stop it clashing with Google photorealistic tiles.
    // Default is false.
    globeHidden?: boolean;
    // Hides Entities that are under the terrain.
    // Default is true. Always off for "WEB_3D_MODEL_SPACE".
    groundOcclusion?: boolean;
    // Lighting that makes terrain elevation apparent.
    // Default is true.
    hillShades?: boolean;

    quality?: {
        // Smooth rendering (FXAA anti-aliasing).
        // Default is true.
        fxaa: boolean;
    };

    shadows?: {
        // Default is false.
        enabled: boolean;
        // Softens shadow edges.
        soften: boolean;
        // Shadow map size, which sets the shadow quality. Kept between 2048 and 32768.
        pixelSize: number;
        // Default is 0.3.
        darkness: number;
    };

    ambientOcclusion?: {
        // Default is false.
        enabled: boolean;
        // Default is 2.
        intensity: number;
        // Default is 0.2.
        lengthCap: number;
        // Default is 0.5.
        bias: number;
        // Default is 2.
        blurStepSize: number;
        // Default is 2.
        stepSize: number;
    };

    lighting?: {
        // CSS colour string of the sun.
        // Default is white.
        color: string;
        // Default is 2.
        intensity: number;
        // Set to 2.
        lightingVer: number;
    };

    // Terrain contour lines.
    contours?: {
        // Default is false.
        enabled: boolean;
        // Metres between lines.
        // Default is 50.
        spacing: number;
        // Line width in metres.
        // Default is 2.
        width: number;
        // Default is true.
        drawLabels: boolean;
        // CSS colour string. Its alpha is ignored in favour of the alpha value.
        // Default is white.
        color: string;
        // From 0 to 1.
        // Default is 0.5.
        alpha: number;
    };

    // Ground grid. Only drawn for "WEB_3D_MODEL_SPACE".
    grid?: {
        // Default is false.
        enabled: boolean;
        // Metres between lines. Navigator uses 50 for new model space Bookmarks.
        spacing?: number;
    };

    // Weather overlays. Not drawn for "WEB_3D_MODEL_SPACE".
    weather?: {
        // Enabled layers, bottom to top.
        layers: ("rain" | "wind" | "temperature")[];
        // Opacity per layer, from 0 to 1.
        // Default is 1 for rain and wind, 0.7 for temperature.
        opacity?: {
            rain?: number;
            wind?: number;
            temperature?: number;
        };
    };

    // Keyboard walkthrough controls.
    walkthrough?: {
        // Turns walkthrough controls on when the Bookmark opens.
        // Default is false.
        enabled: boolean;
        /**
         * WALK = moves while keeping the camera's height above the ground. This is the default.
         * FLY = moves without keeping the height.
         * PAN = only rotates the camera.
         */
        moveType: "WALK" | "FLY" | "PAN";
        // Movement speed.
        // Default is 0.1.
        moveRate?: number;
    };
}

Bookmark: Time

The scene time drives historic data, lighting and anything else that changes over time.

interface IBookmarkSettings {
    // ISO 8601 date time of the scene, including its timezone.
    // Navigator saves it in UTC. Eg: "2023-11-20T23:00:00Z".
    dateTime?: string;

    timeline?: {
        // ISO 8601 date time strings for the timeline range.
        start?: string;
        end?: string;
        // Plays time forward between start and end.
        // Default is false.
        playing?: boolean;
        // 1 = one second per second.
        // Default is 1.
        speed?: number;
        // Follows the real current time. The other timeline values are not applied while live.
        // Default is false.
        live?: boolean;
        // Milliseconds of range shown either side of the current time while live.
        // Default is 1800000 (30 minutes).
        livePaddingMs?: number;
    };
}

Bookmark: Entity states

States change how individual Entities look when the Bookmark opens. When a Bookmark has states, they replace the states the scene had before.

interface IBookmarkSettings {
    states?: IEntityState[];

    // Entities Navigator requests again about every 2 seconds to show live changes.
    // Only the first 100 are refreshed, so keep the list short.
    liveEntityIds?: string[];
}

interface IEntityState {
    // The Entity this state is for.
    entityId: string;
    // Limits the state to the Entity as loaded by this Menu Item.
    // A state with a Menu Item ID wins over one without. Eg: if Entity + Menu Item is hidden and Entity alone is not, it is hidden.
    menuItemId?: string;
    // From 0 to 1, where 1 is 100% opacity.
    opacity?: number;
    hidden?: boolean;
    // Applies the selection colour and opens the selection panel.
    selected?: boolean;
    // When at least one Entity is isolated, only isolated Entities are shown.
    isolated?: boolean;
    // Draws a label from the Entity's name and its Entity Type's additional label settings.
    labelled?: boolean;
    // Applies the highlight colour. The selection colour wins over it.
    highlighted?: boolean;
}

Bookmark: Diagram

A "DIAGRAM" Bookmark draws Entities and their relationships on a flat 2D canvas instead of the globe. Navigator saves an empty camera on the record and keeps the diagram's own camera in the settings.

interface IDiagramSettings {
    contentType: "DIAGRAM";

    // Pan and zoom of the diagram.
    camera?: {
        x: number;
        y: number;
        zoom: number;
    };

    // When left out, a grid on "#2A2A8F" is drawn.
    background?: {
        type?: "NONE" | "DOTTED" | "GRID" | "IMAGE";
        // CSS colour string behind everything.
        bgCssColor?: string;
        // Used by "GRID".
        gridColor?: string;
        gridStep?: number;
        // Used by "DOTTED".
        dotColor?: string;
        dotSize?: number;
        dotSpacing?: number;
        // Used by "IMAGE": the Client File ID of the image and its scale.
        imageFileId?: string;
        imageScale?: number;
        // Draws a cross at the centre.
        // Default is true.
        drawCenter?: boolean;
    };

    // Entities placed on the diagram.
    entities?: {
        entityId: string;
        x: number;
        y: number;
        // Default is "CIRCLE".
        shape?: "CIRCLE" | "BOX";
        // Circle radius.
        // Default is 10.
        size?: number;
        // Box width and height.
        // Default is twice the size.
        width?: number;
        height?: number;
        // CSS colour string.
        cssColor?: string;
        // Animates the Entity with a pulse.
        pulse?: boolean;
        // Draws the hierarchy of Entities and relationships from this Entity.
        expandRelations?: boolean;
        // Layout of the expanded hierarchy.
        expandLayout?: "FORCE_TREE" | "CLUSTER_TREE" | "CIRCLE_PACKING";
    }[];

    // Relationships drawn between the Entities.
    relationships?: {
        // The Relation Type to draw.
        typeId: string;
        // Entities to draw it between. When left out, it is drawn between all Entities on the diagram.
        entityIds?: string[];
        // Line width in pixels.
        width?: number;
        // Animates the line.
        // Default is false.
        animated?: boolean;
    }[];

    // Selected Entity IDs.
    selectedIds?: string[];

    // Markup drawn over the diagram.
    markup?: IMarkup;
}

Requesting Bookmarks

Bookmarks are returned in display order, then by title. The list leaves out drafts made by other users. Account power users can include them with "Drafts".

Get a list of Bookmarks

Response
interface IResponse {
    Items: IBookmark[];
}
Javascript example

Get a Bookmark by ID

Response
// The response is the Bookmark record directly.
// See the Bookmark data model above for the record structure.
Javascript example

Get a Bookmark by ID without its Project View

Response
// The response is the Bookmark record directly.
// See the Bookmark data model above for the record structure.
Javascript example

Create and update Bookmarks

Leave the Bookmark ID out of the route to create one, and the API generates the ID. An update only changes the fields you include, and the camera and settings are each replaced as a whole. A Bookmark cannot be moved to another Project View.

Create or update a Bookmark

Request body
// The body is the Bookmark record directly.
// See the Bookmark data model above for the record structure.
Response
// The response is the Bookmark record directly.
// See the Bookmark data model above for the record structure.
Javascript example

To reorder Bookmarks, send their IDs in the new order. Each listed Bookmark gets the next display order, starting from "DisplayOrder.Start". IDs that are not in the Project View are skipped, and Bookmarks you leave out keep their display order.

Set the order of Bookmarks

Request body
interface IRequest {
    // Display order of the first Bookmark.
    // Default is 0.
    "DisplayOrder.Start"?: number;
    // Bookmark IDs in their new order.
    "UISlide.ID": string[];
}

Delete a Bookmark

We don't provide any bulk deletion but you can delete by record ID. Comments made on the Bookmark are deleted with it.

Delete a Bookmark

Javascript example

Bookmark groups

Bookmark groups sort a Project View's Bookmarks into named folders. A group belongs to one Project View, and a Bookmark is in at most one group, set by its "UI.SlideGroup.ID". Set it to 0 to take the Bookmark out of its group.

Deleting a group moves its Bookmarks out of it rather than deleting them. Deleting a Project View deletes its groups. Groups use the same permissions as Bookmarks.

interface IBookmarkGroup {
    // Unique ID of the group, generated by the API.
    // Exclude this value, or set it to 0, for new records.
    ID?: number;
    // ID of the Project View the group belongs to. Set by the API from the route.
    "UI.View.ID"?: string;
    // Name shown in Navigator. Limited to 60 characters.
    Name: string;
    // Description of the group. Navigator does not show it.
    Description?: string;
    // Position among the Project View's groups, lowest first.
    DisplayOrder: number;
    // ISO 8601 date time strings, set by the API.
    Created?: string;
    Updated?: string;
    // What the requesting user can do with this record.
    // A combination of "C" (create), "R" (read), "U" (update) and "D" (delete). Eg: "RU".
    // This is returned by the API and ignored when saving.
    Permission?: string;
}

Navigator's Bookmarks panel lists the groups first, by display order then name, with the ungrouped Bookmarks after them. Each group is a folder the user can open and close, and it starts closed until the user opens it. Within a group, Bookmarks are sorted by display order then title. A Bookmark whose group ID matches no group is shown as ungrouped.

When a user reorders Bookmarks in Navigator, it numbers the display order of every Bookmark in one sequence: the groups' Bookmarks in group order, then the ungrouped ones. Follow the same rule if you want your order to match what Navigator writes.

Bookmark groups: Requests

Get a list of Bookmark groups

Response
interface IResponse {
    // Sorted by display order.
    Items: IBookmarkGroup[];
}
Javascript example

Get a Bookmark group by ID

Response
// The response is the Bookmark group record directly.
// See the data model above for the record structure.
Javascript example

Create or update a Bookmark group

Request body
// The body is the Bookmark group record directly.
// An update only changes the fields you include.
Response
// The response is the Bookmark group record directly.
// See the data model above for the record structure.
Javascript example

Delete a Bookmark group

Javascript example

Set the order of Bookmark groups

Request body
interface IRequest {
    // Display order of the first group.
    // Default is 0.
    "DisplayOrder.Start"?: number;
    // Group IDs in their new order.
    "UI.SlideGroup.ID": number[];
}

Opening in Navigator

Navigator opens a Project View from its "viewId" query parameter, and a Bookmark from its "bookmarkId" query parameter. Eg: "/?viewId=abc12345&bookmarkId={bookmark_id}" on your Navigator address. Without a Bookmark ID it opens the first Bookmark in the order the API returns them.

Navigator gets the Project View with "Expand=*", so the Bookmarks and groups arrive in the same request. When a Bookmark opens, any setting it leaves out comes from the Project View's Bookmark defaults, as described above.