diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ae4cb2b..09a5156 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -105,7 +105,7 @@ required fields must be present and non-empty for App Hub submission. friendly_id: "" # {folder-slug}-playbook (e.g. epic-ehr-playbook, my-crm-playbook) title: "" # Display name for the Playbook (matches ContentStack field) tag_line: "" # Short tagline for App Hub detail page (required, max 128 chars) -description: "" # 1–2 sentences, used as App Hub listing copy +description: "" # App Hub supports Markdown; use YAML | block (opening + Why + What); see Field Rules product_types: [] # Array: one or more of teams | meetings | calling | rooms | contact_center @@ -139,6 +139,17 @@ submission_date: "" # ISO date (e.g. 2025-03-01) - **tag_line** — Short tagline displayed on the App Hub detail page. Required. Max 128 characters. +- **description** — App Hub supports **Markdown**. Use a YAML block scalar + (`description: |`) with **blank lines** between sections: an opening paragraph + (**bold** key terms such as Webex product, flow, and stack), a + **Why use this playbook** heading with 3–5 outcome-focused bullets, and a + **What it does** heading with bullets for concrete behaviors and endpoints. + Stay accurate to the playbook. Do **not** use this field for canonical upstream + repository URLs, clone or package-install instructions, or “code lives + elsewhere”—document that in **README** and, for reference playbooks, in + **`src/README.md`**. Full importer checklist and example shape: + [import_playbook.md — APPHUB.yaml](docs/commands/import_playbook.md#apphubyaml). + - **product_types** — Array of one or more of: `teams`, `meetings`, `calling`, `rooms`, `contact_center`. Playbooks can span multiple products (e.g. `["meetings", "teams"]` appears on both /meetings and /messaging). diff --git a/PLAYBOOK_TEMPLATE/APPHUB.yaml b/PLAYBOOK_TEMPLATE/APPHUB.yaml index e6d5ac4..6148a83 100644 --- a/PLAYBOOK_TEMPLATE/APPHUB.yaml +++ b/PLAYBOOK_TEMPLATE/APPHUB.yaml @@ -18,12 +18,32 @@ title: "MyCRM + Webex Contact Center Integration" tag_line: "Connect MyCRM to Webex Contact Center for screen pop and customer context" # ----------------------------------------------------------------------------- -# description — 1–2 sentences, used as App Hub listing copy +# description — App Hub supports Markdown. Use a block scalar (description: |) with +# blank lines between sections: opening paragraph (bold key terms), **Why use this +# playbook** (3–5 outcome bullets), **What it does** (concrete behaviors/endpoints). +# Do not put upstream repo URLs or install-only instructions here—use README and +# src/README.md for reference playbooks. See docs/commands/import_playbook.md. # ----------------------------------------------------------------------------- description: | - This sample demonstrates how to build an integration between MyCRM and Webex Contact Center. - Agents receive customer context and screen pop when handling calls. The code includes - webhook handling, REST API calls, and Agent Desktop configuration. + A **Node.js** sample that connects **MyCRM** to **Webex Contact Center** for agent + **screen pop**: webhooks, customer lookup, and context surfaced in **Agent Desktop**. + + **Why use this playbook** + + - **Faster delivery:** Start from a working **Express** service instead of an empty + repo when you need CRM context on a call. + - **Fewer integration mistakes:** Shows the expected **REST** payloads and **Webex** + API usage so you are not guessing field names or auth order. + - **Secrets handled safely:** **Client ID**, **client secret**, and tokens load from + **environment variables**, matching how you will configure non-dev environments. + - **Easy to verify:** Local run plus simple HTTP checks so you can confirm the flow + before wiring production routing or scaling. + + **What it does** + + - Accepts **MyCRM** events over HTTP and validates incoming requests. + - Calls documented **Webex** APIs to resolve or push customer context for **WxCC**. + - Returns structured data your **Agent Desktop** or flow can display to agents. # ----------------------------------------------------------------------------- # product_types — Where this Playbook appears. Pick one or more. diff --git a/docs/commands/import_playbook.md b/docs/commands/import_playbook.md index 86f7731..861a3db 100644 --- a/docs/commands/import_playbook.md +++ b/docs/commands/import_playbook.md @@ -241,7 +241,61 @@ Use the full schema from PLAYBOOK_TEMPLATE/APPHUB.yaml. **Preserve the section c `meetings-exporter-playbook`) to reduce App Hub name collisions with actual integrations - `title` — `{ThirdPartyTool} + Webex {Product} Integration` - `tag_line` — one-line value proposition (required, max 128 chars) -- `description` — 1–2 sentences for App Hub listing +- `description` — App Hub **supports Markdown** in this field. Use a YAML block scalar + (`description: |`) and separate sections with **blank lines**. Do **not** use + `description` for canonical upstream URLs, clone or install commands, or + “source lives elsewhere”—put those in **README** (and in **`src/README.md`** for + [reference imports](import_playbook_reference.md)). Keep **`tag_line`** as the short + one-liner (max 128 characters); `description` carries the expanded detail. + + **Structure** + + - **Opening paragraph:** Short summary of what the playbook offers; use **bold** + on key terms (Webex product, integration flow, language or stack). + - **Why use this playbook:** A line `**Why use this playbook**`, then **3–5 + bullets** focused on user outcomes—for example faster delivery, fewer auth + mistakes, correct token or API usage, framework fit, a workable test path, + secrets loaded from environment variables. + - **What it does:** A line `**What it does**` (or equivalent), then bullets for + **concrete behaviors**: OAuth or callback handling, REST calls, named routes or + endpoints the sample exposes, configuration the reader can verify. + + **Importer checklist** + + - [ ] `description: |` with blank lines between the opening paragraph, Why, and What + - [ ] Opening paragraph uses **bold** on product, flow, and stack terms where helpful + - [ ] **Why use this playbook** has 3–5 outcome-oriented bullets + - [ ] **What it does** lists behaviors and endpoints that match the actual playbook + - [ ] No upstream repo links, package install lines, or pointer-only copy in + `description` + + **Example shape:** For pacing, depth, and Markdown formatting, compare + [`playbooks/wxcc-token-java-sample/APPHUB.yaml`](../../playbooks/wxcc-token-java-sample/APPHUB.yaml) + (`description`). Generic pattern (substitute your integration’s facts): + + ```yaml + description: | + A **Node.js** sample that wires **MyCRM** into **Webex Contact Center** for + agent screen pop: webhook intake, customer lookup, and Agent Desktop context. + + **Why use this playbook** + + - **Ship faster:** Reuse a minimal **Express** service pattern instead of + designing the flow from a blank editor. + - **Fewer auth mistakes:** Shows how to validate **Webex** signatures and store + tokens using **environment variables** only. + - **Right API shape:** Demonstrates the exact **REST** calls and payloads your + flow needs before you harden for production. + - **Testable path:** Includes a local run and curl-friendly checks so you can + confirm behavior before deploying. + + **What it does** + + - Receives **MyCRM**-originated events and normalizes them for **WxCC**. + - Calls documented **Webex** APIs with the scoped **access token** from your app. + - Returns structured customer context your **Agent Desktop** or flow can consume. + ``` + - `product_types` — from integration type mapping (Step 2) - `categories` — default `["productivity", "developer-tools"]`; include verticals (healthcare, financial-services, retail-ecommerce) and app categories as appropriate diff --git a/docs/commands/import_playbook_reference.md b/docs/commands/import_playbook_reference.md index ca4b76b..5dff411 100644 --- a/docs/commands/import_playbook_reference.md +++ b/docs/commands/import_playbook_reference.md @@ -160,7 +160,16 @@ items where relevant: ### APPHUB.yaml -Same rules as [import_playbook.md — APPHUB.yaml](import_playbook.md#apphubyaml). +Same rules as [import_playbook.md — APPHUB.yaml](import_playbook.md#apphubyaml), +including the structured Markdown `description` (`description: |`, **Why use this +playbook**, **What it does**). Reference-upstream playbooks use the **same** +description quality bar as standard imports. + +Do **not** use App Hub `description` to point at the canonical upstream GitHub repo, +package install commands, or “get the code from upstream”—that belongs in **README** +and in **`src/README.md`**. Keep `description` focused on outcomes and concrete +behaviors this Playbook documents, like any other playbook. + `product_url` remains `https://github.com/webex/WebexPlaybooks/tree/main/playbooks/`.