Essential Open OS context for products

Open OS is a modular and extensible multitenant solution that manages various workspaces—each with unique roles, permissions, workflows, and other pertinent data—and fosters a dynamic environment to integrate different product types seamlessly.

The key to this integration is the OsContext object. It encapsulates workspace-specific data, which Open OS passes to native products at launch and makes available to embedded products on request.

From the context, app developers can extract needed information to understand what a specific app is currently working on. Using context isn't required, but app developers can rely on this Open OS option to find information about:

Hierarchy (Details of the hierarchy level the application was launched in).
Project (Details of the project the application was launched from).
Application instance (Details about the application version which was launched).
Custom configuration (Application specific config details added via DevHub when registering the product).
Permissions (Granted rights and privileges that can be important for the application's business logic).

OS Context: Key values explanation

Key	Short Description
baseUrl	Route within the OS where the application instance is launched.
workspace (deprecated)	Similar to hierarchy, except it doesn’t include the Tenant level hierarchy information.
hierarchy	Provides information about the hierarchy context in which the application was launched.
Project	Provides the identifier of the project and the specific project item associated with the application.
permissions	Contains the permission codes the user has been granted on the organisation account in AlphaZulu.
tenant	Provides details of the tenant (workspace) settings, including the key AlphaZulu account ids.
navigationTree	Provides details of the user’s navigation items.
userDetails	Provides information about the user. Key details include firstname, lastname, and email.
theme	Contains the JSON definition of the custom theme of the current workspace.
taxonomy	Workspace specific overrides of key terms used in the OS.
appInstance	Configuration information from DevHub about the app and the specific app instance which has been launched.
appCustomConfig	Contains any custom config key-value pairs configured for the app via DevHub.
additional	Provides additional project app launch context information.
activePage	Currently opened page by the user on OS.

baseUrl

application/0c71fdcb-f94d-476b-9987-d3df8adb0ad7/view-context-embed

workspace(deprecated)

Similar to hierarchy, except it doesn’t include the Tenant level hierarchy information. It is null if launched in a project not associated with a project or in the tenant hierarchy level.

hierarchy

{
  "hierarchy": [
    {
      "azId": "8ab649d7-26f3-48eb-8f58-688c3c158f88",
      "mapping": {
        "azId": "8ddc2220-92ef-4262-95f5-24395f5ba8de",
        "name": "Choreograph Organisations",
        "type": "TENANT",
        "customTypeName": null,
        "parentAzId": "ea35bf45-0773-4dbd-a93b-a3e3e2ad9b08"
      }
    },
    {
      "azId": "ea35bf45-0773-4dbd-a93b-a3e3e2ad9b08",
      "name": "Paws & Tails Co",
      "type": "CLIENT",
      "customTypeName": null,
      "parentAzId": "8ddc2220-92ef-4262-95f5-24395f5ba8de"
    },
    {
      "azId": "70e4ba44-d2ea-49ee-9ddd-48456c58fe1e",
      "name": "United Kingdom of Great Britain and Northern Ireland",
      "type": "MARKET",
      "customTypeName": null,
      "parentAzId": "ea35bf45-0773-4dbd-a93b-a3e3e2ad9b08"
    },
    {
      "azId": "8ab649d7-26f3-48eb-8f58-688c3c158f88",
      "name": "Paws & Tails Dog Snacks",
      "type": "BRAND",
      "customTypeName": null,
      "parentAzId": "70e4ba44-d2ea-49ee-9ddd-48456c58fe1e"
    }
  ]
}

Provides information about the hierarchy context in which the application was launched. Workspaces are configured with one or more hierarchy levels. The azId is the key that identifies the specific level of hierarchy where the app instance operates. It also includes details about parent accounts.

In the provided example, the app was launched from the Brand hierarchy level named ‘Paws & Tails Dog Snacks’. This brand level is under the UK market level, which is part of the "Paws & Tails Co" client account.

project

{
  "project": {
    "azId": "e05e6879-43ae-4127-bb8d-d888ce5dbcee"
    "id": "375a2ef0-2fba-4f7d-9395-51b6002be772",
    "name": "ABC Project test",
    "type": "CAMPAIGN",
    "itemId": "0f4f6195-3a75-4f6d-b83f-1dec5930d225",
    "itemCompleteState": "TO_DO"
  }
}

Provides the identifier of the project and the specific project item associated with the application instance. Project is null if the app is not launched from inside a project.

permissions

{
  "permissions": [
    {
      "account_id": "8ddc2220-92ef-4262-95f5-24395f5ba8de",
      "permissions": [
        "OS_USERDETAILS_USERS_MANAGE",
        "AZ_ACCOUNT_RELATIONSHIPS_CREATE",
        "WPP_OPEN_DEVHUB_SELF_PRODUCTS_DELETE",
        "APP_PROFILE_81b3977b-85fe-4674-a2ce-5e1876f9777a::WOWZ_CAMPAIGNS_APP_ACCESS",
        "AZ_ROLES_VIEW",
        "WOWZ_JUNIOR_APP_ACCESS"
      ]
    }
  ]
}

Contains the permission codes the user has been granted on the organisation account in AlphaZulu.

tenant

{
  "tenant": {
    "id": "294421e1-16ea-4b81-a37e-72bb0792815b",
    "name": "Choreograph",
    "title": "Welcome to Choreograph Platform",
    "description": "A SaaS-based solution to enable WPP organisation’s users",
    "azId": "9595f2cc-9c63-49f2-9eba-80c42d0d2476",
    "azMeta": {
      "applicationsId": "b668cf55-3a82-4b40-96f5-77142a82016f",
      "organizationsId": "8ddc2220-92ef-4262-95f5-24395f5ba8de",
      "hubsId": "af7a2ecf-a107-4b17-9b4e-adb43d579294",
      "projectsId": "cbe69fff-0e5d-4fe9-88fc-28b284e3e997",
      "groups": {
        "8 props"
      }
    },
    "subdomain": "ch",
    "homeUrl": "https://ch.wpp-stage.os-dev.io/"
  }
}

Provides details of the workspace settings, highlighting the key AlphaZulu account IDs:

applicationsId: The root AZ account for any application registered in DevHub on the workspace.

organizationsId: The root AZ account for the hierarchy levels configured on the workspace.

hubsId: The root AZ account for any hubs created in the workspace.

projectsId: The root AZ account for projects created in the workspace.

These accounts are for OS use only.

navigationTree

{
  "navigationTree": {
    "rootId": "8ddc2220-92ef-4262-95f5-24395f5ba8de",
    "mapping": {
      "411 props"
    },
    "projectsMapping": {
      "5 props"
    }
  }
}

Provides details of the user’s navigation items.

userDetails

{
  "userDetails": {
    "id": "5f3a180e-465e-4d07-b3db-c06f3759b2da",
    "sourceId": "b8885222-ca49-5ab5-95db-5677811d610c",
    "sourceType": "Manual",
    "firstname": "Alex",
    "lastname": "Garcia",
    "email": "[email protected]",
    "active": true,
    "agency": "wpp",
    "country": "United States of America",
    "countryAlpha2Code": "US",
    "department": null,
    "avatarUrl": null,
    "avatarOriginal": null,
    "avatarThumbnail": null,
    "jobTitle": null
  }
}

Provides key user details, including their first name, last name, email, and avatar URL. It also includes locale information based on the user's OS profile, such as display language, date locale, and number locale. Apps should adjust date and number formats according to the user's configured locale.

theme

{
  "theme": {
    "font": {
      "1 prop"
    },
    "icon": {
      "1 prop"
    },
    "text": {
      "1 prop"
    },
    "color": {
      "9 props"
    },
    "border": {
      "2 props"
    },
    "overlay": {
      "1 prop"
    },
    "surface": {
      "1 prop"
    },
    "boxShadow": {
      "5 props"
    },
    "typography": {
      "10 props"
    }
  }
}

Contains the JSON definition of the custom theme for the current workspace. It can be used by embedded code or embedded link apps to match the look and feel of the workspace.

taxonomy

{
  "taxonomy": {
    "app": "app",
    "apps": "apps",
    "brand": "brand",
    "brands": "brands",
    "client": "client",
    "clients": "clients",
    "project": "project",
    "projects": "projects",
    "application": "application",
    "applications": "applications"
  }
}

Workspace-specific overrides for key terms used in the OS.

appInstance

{
  "appInstance": {
    "id": "0c71fdcb-f94d-476b-9987-d3df8adb0ad7",
    "devhubAppId": "0a1c060c-8c67-145e-818c-6904b1ea001c",
    "devhubAppVersionId": "64390955-7f69-4a5c-b636-d9b377917431",
    "assignmentId": "375a2ef0-2fba-4f7d-9395-51b6002be772",
    "assignmentType": "PROJECT",
    "status": "ACTIVE",
    "context": {
      "12 props"
    },
    "devhubMetadata": {
      "11 props"
    },
    "osRoute": null,
    "name": "View Context (embed)",
    "description": null,
    "tenantId": "294421e1-16ea-4b81-a37e-72bb0792815b",
    "position": 12,
    "group": null,
    "subgroup": null,
    "createdAt": "2024-06-25T09:35:55.790603Z",
    "createdBy": "[email protected]",
    "updatedAt": null,
    "updatedBy": null,
    "logoThumbnail": null,
    "logoOriginal": null,
    "flags": {
      "2 props"
    }
  }
}

Provides configuration information from DevHub about the app and the specific app instance that has been launched.

appCustomConfig

appCustomConfig: {}

Contains any custom config key-value pairs configured for the native or no-code app via DevHub.

additional

{
  "additional": {
    "appId": "0f4f6195-3a75-4f6d-b83f-1dec5930d225",
    "appName": null,
    "phaseId": "4690b7ee-8fdc-47b1-948e-2c228e5553fd",
    "miroOwner": null,
    "projectId": "375a2ef0-2fba-4f7d-9395-51b6002be772",
    "activityId": null,
    "projectAzId": "6b5d892c-7910-47ed-9c4f-464f64986b22",
    "projectName": "ABC Project test",
    "projectType": "CAMPAIGN",
    "workspaceId": "8ab649d7-20f3-48eb-8f58-688c3c158f08",
    "originAppName": "View Context (embed)",
    "taskIsCompleted": false
  }
}

Provides additional context information for a project app launch:

projectAzId: The AlphaZulu account ID used to verify user permissions within the project.
projectId / phaseId / activityId: These are the IDs for the specific project, phase, and activity associated with the launched app instance. Apps can use these IDs to understand the user's context within the project.

activePage

activePage: "HUBS_PAGE"

Currently opened page by user on OS.

Handling Open OS context in native products

Open OS runs native products as micro-frontends with single-spa. This includes handling product registration, managing base routing, and overseeing the mounting and unmounting of micro-apps. Native products receive the essential context by default and do not require specific codebase changes.

info

Micro-frontends, the front-end counterpart to microservices, compartmentalize products into smaller, maintainable units. This promotes independent development and gives teams full ownership of their product's components, from the database to the UI.

Currently, we support products written with React, Angular, and Vue. Accessing the Open OS context differs based on your framework of choice:

For React, you can access the context through the OsProvider component and useOs hook.
For Angular, you can access the context by using the OsService utility.
For Vue, you can access the context through the product-level OsProvider provider.

Handling Open OS context in embedded products

Embedded products belong to the no-code product types, and Open OS displays them within an iframe:

Embedded code is for products that generate embed codes, similar to the following snippet.

<iframe
  width="560"
  height="315"
  src="https://www.youtube.com/embed/dx0ksJZjZic?si=etMwTJTXZOzy2uCo"
  title="YouTube video player"
  frameborder="0"
  allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
  allowfullscreen
></iframe>

Embedded link is for products capable of being rendered as an iframe from a link.
```
https://www.youtube.com/embed/dx0ksJZjZic?si=etMwTJTXZOzy2uCo
```

When Open OS runs an embedded product, it waits for that product to request a connection. Refer to the following code snippet to implement the connection request and ensure the received context is always up-to-date.

import { FramedAppMethods, FramedAppParentMethods } from '@wppopen/core'
import { connectToParent, Methods } from 'penpal'

...

const methods: Methods = {
  // Method for receiving product launch context updates
  receiveOsContext: osContext => {
    console.log('osContext', osContext)
  },
} satisfies FramedAppMethods
 
// Method for receiving product launch context from Open OS
const connection = connectToParent<FramedAppParentMethods>({
  parentOrigin: '*',
  methods,
  debug: isDevelopment,
})
 
connection.promise.then(({ osApi }) => {
  console.log('osApi', osApi)
})
 
connection.promise.catch(error => {
  console.error('Penpal child context error:', error)
})

Once your embedded product connects to Open OS, it can access the OsContext object.

OS Context: Key values explanation​

Handling Open OS context in native products​

Handling Open OS context in embedded products​

OS Context: Key values explanation

Handling Open OS context in native products

Handling Open OS context in embedded products