Docs for content page and CRUD operations for context

content/docs/platform/meta.json

@@ -22,6 +22,7 @@
     "workflow/step-conditions",
     "workflow/tags",
     "workflow/translations",
+    "workflow/contexts",
     "---Channels---",
     "...integrations",
     "---Account---",

content/docs/platform/workflow/contexts.mdx

@@ -0,0 +1,257 @@
+---
+pageTitle: 'Contexts'
+title: 'Contexts'
+description: 'Learn how to create and manage Contexts to reuse metadata across your notification workflows.'
+icon: 'Package'
+---
+
+Contexts are flexible, user-defined data objects that help you organize and personalize your notifications. They let you attach metadata (such as tenant, region, or app details) and enable contextual behavior to workflows, notifications, and other entities across Novu.
+
+In simple terms, a Context acts like an extended version of the payload. While the payload exists only for the duration of a single workflow execution, Contexts are persistent and can be reused across multiple workflows or API calls. This makes them ideal for multi-tenant environments, dynamic branding, and use cases where notifications depend on shared or reusable data.
+
+<Callout type='warn'>You can pass a maximum of 5 contexts per workflow trigger and the serialized `data` object for each context is limited to 64KB.</Callout>
+
+## How Context works
+
+Imagine you have a single subscriber entity, `[email protected]`, who uses two different applications you offer: "Notion Email" and "Notion Calendar". You want to send notifications specific to each application.
+
+Without Context, you might have to create two different subscribers or use workarounds with subscriber ID prefixes to differentiate the notifications.
+
+```javascript
+// Problem: How does Novu know which app is sending the notification?
+
+// Notion Email notification
+await novu.trigger('new-email-received', {
+  to: '[email protected]',
+  payload: { title: 'You have 1 new email' }
+});
+
+// Notion Calendar notification  
+await novu.trigger('new-calendar-event', {
+  to: '[email protected]',
+  payload: { title: 'You have a new meeting invite' }
+});
+```
+
+With Context, you can provide this metadata directly in the trigger. This allows you to use a single workflow and subscriber entity, while dynamically changing content or logic based on the context.
+
+```javascript
+// Solution: Pass an 'app' context to differentiate triggers.
+
+// Notion Email notification
+await novu.trigger('new-email-received', {
+  to: '[email protected]',
+  payload: { title: 'You have 1 new email' },
+  context: {
+    app: 'notion-email',
+    branding: {
+      logo: "url_for_email_logo.png"
+    }
+  }
+});
+
+// Notion Calendar notification  
+await novu.trigger('new-calendar-event', {
+  to: '[email protected]',
+  payload: { title: 'You have a new meeting invite' },
+  context: {
+    app: 'notion-calendar',
+    branding: {
+      logo: "url_for_calendar_logo.png"
+    }
+  }
+});
+```
+
+Here are some ways context can be used:
+
+- Multi-tenancy and App Routing: Use a tenant or app context to dynamically alter notification content, branding, or logic for different customers or applications from a single workflow.
+- Shared Chat Credentials: For chat providers like Slack or MS Teams, store workspace-level credentials (e.g., a bot token) in a context. This allows multiple subscribers within that workspace to receive notifications without each subscriber needing to store the shared token.
+- A/B Testing: Pass a campaign identifier in a context (for example, campaign: 'new-welcome-email-v2'). Use this in a condition step to split users into different notification paths and measure which performs better.
+- Data Residency and Compliance: Use a region context to tag notifications with their origin. This can help in applying data retention policies or filtering data for compliance audits.
+
+## How to use Contexts
+
+Once a context is created, you can access its properties anywhere variables are supported, such as in template editors or condition steps.
+
+1. Accessing Context data in templates
+
+    If a context with this data is created:
+
+    ```json
+    context: {
+      tenant: {
+        id: 'acme-corp',
+        data: {
+          name: 'Acme Corporation',
+          plan: 'enterprise'
+        }
+      }
+    }
+    ```
+
+    You can access the `name` and `plan` in your in-app email, SMS, or push template like this:
+
+    ```html
+    <p>Welcome, new user from {{context.tenant.data.name}}!</p>
+    <p>Your account is on the {{context.tenant.data.plan}} plan.</p>
+    ```
+    Or
+
+    ```text
+    Welcome, new user from {{context.tenant.data.name}}!
+    Your account is on the {{context.tenant.data.plan}} plan.
+    ```
+
+2. Using Context in Conditions
+
+    You can use context variables in the "Step conditions" tab of a workflow step to add conditional logic to your notifications. For example, only send a "Feature X is now enabled" email if `context.tenant.data.plan` is `enterprise`.
+    ![Context step conditions](/images/workflows/context-step-conditions.png)
+
+## Managing Context
+
+Novu provides two wasy to manage contexts, either through the Novu dashboard or using the API.
+
+### Create Context
+
+You can create a new Context via Novu dashboard or API, when you want to register reusable metadata. After creation, this context becomes available to all workflows and templates within your environment.
+
+#### Dashboard
+
+Use the dashboard to manually define contexts that represent key business entities.
+
+1. Log in to the Novu dashboard
+2. Click **Contexts** on the sidebar.
+3. Click **Create context**.
+4. Fill in the following fields:
+    - **Identifier**: A unique identifier within that type (for example, acme-corp).
+    - **Context type**: A category such as tenant, app, or region.
+    - **Custom data (JSON)**: An optional JSON object that contains metadata, such as branding, plan, or region details.
+  5. Click **Create context** to save the context.
+
+#### API
+
+Novu provides an API to create a context. If a context with the same `type:id` combination already exists, the request will fail.
+
+```bash
+POST /v2/contexts
+{
+  "type": "tenant",
+  "id": "acme-corp",
+  "data": {
+    "name": "Acme Corporation",
+    "plan": "enterprise"
+  }
+}
+```
+
+#### Just-in-Time
+
+Contexts can also be created automatically when you trigger a workflow that includes a new context object. If the specified `type:id` doesn’t exist, Novu automatically creates it before running the workflow.
+
+```
+await novu.trigger('welcome-email', {
+  to: '[email protected]',
+  payload: { userName: 'John' },
+  context: {
+    tenant: 'acme-corp',   // Created automatically if it doesn’t exist
+    app: 'jira'
+  }
+});
+```
+
+### Update a Context
+
+You can update a context’s data payload at any time. The context `type` and `id` remain immutable.
+
+#### Dashboard
+
+1. Log in to the Novu dashboard.
+2. Click **Contexts** on the sidebar.
+3. Click on the context you wish to edit, frrom the context list on the Context page. 
+4. Modify its data object in the UI.
+5. Click **Save changes**.
+
+#### API
+
+Novu provides an API to update an existing context. The `data` object is replaced entirely during updates (not merged). Include all fields you want to retain.
+
+```bash
+PATCH /v2/contexts/tenant/acme-corp
+{
+  "data": {
+    "plan": "premium",
+    "region": "us-east"
+  }
+}
+```
+
+### Retrieve a single Context
+
+You can retrieve a context to verify its data, confirm its creation, or inspect the metadata it holds.
+
+#### Dashboard
+
+1. Log in to the Novu dashboard
+2. Click **Contexts** on the sidebar to view the list of all existing contexts.
+3. Click any context entry to see its details.
+
+#### API
+
+Novu provides an API to retrieve a single, specific context by providing its `type` and `id` in the URL.
+
+```
+GET /v2/contexts/:type/:id
+```
+
+Here is an example:
+```
+GET /v2/contexts/tenant/acme-corp
+```
+
+### List or Search Contexts
+
+You can list all contexts in your environment or search for specific ones by context type or ID.
+
+#### Dashboard
+
+1. Log in to the Novu dashboard
+2. Click **Contexts** on the sidebar to view all contexts.
+3. Use the search bar to filter by context type or ID.
+
+#### API
+
+Novu provides an API that lists or searches available contexts. Use pagination and search parameters to retrieve subsets efficiently.
+
+```
+GET /v2/contexts
+GET /v2/contexts?search=acme
+```
+
+### Delete a Context
+
+Delete a context if it’s no longer needed. This action permanently removes the context from your Novu environment. 
+
+<Callout type='warn'>This action cannot be undone, so ensure the context is no longer required by any active or historical workflows you might need to analyze.</Callout>
+
+#### Dashboard
+
+1. Log in to the Novu dashboard.
+2. Click **Contexts** on the sidebar.
+3. Click on the **...** icon on the row of the context you want to remove.
+4. Click **Delete context**, a menu will appear.
+5. Click **Delete context**.
+
+#### API
+
+Novu provides an API that you can use to delete a context. Once deleted, the context will no longer be available for use in new workflow executions.
+
+```
+DELETE /v2/contexts/:type/:id
+```
+
+Here is an example:
+
+```
+DELETE /v2/contexts/tenant/acme-corp
+```