Add Concerto Model Registration Guide

.github/workflows/deploy-register-concerto.yml

@@ -0,0 +1,67 @@
+name: Deploy Register-concerto to GitHub Pages
+
+on:
+  push:
+    branches: [main]
+    paths: ['Register-concerto/**']
+  pull_request:
+    branches: [main]
+    paths: ['Register-concerto/**']
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+defaults:
+  run:
+    working-directory: Register-concerto
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+          cache-dependency-path: Register-concerto/package-lock.json
+
+      - run: npm ci
+      - run: npx tsc -b
+      - run: npm run build
+
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: Register-concerto/dist
+
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+          cache-dependency-path: Register-concerto/package-lock.json
+
+      - run: npm ci
+      - run: npx vitest run
+
+  deploy:
+    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
+    needs: [build, test]
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

Register-concerto/.gitignore

@@ -0,0 +1,24 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+node_modules
+dist
+dist-ssr
+*.local
+
+# Editor directories and files
+.vscode/*
+!.vscode/extensions.json
+.idea
+.DS_Store
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?

Register-concerto/.oxlintrc.json

@@ -0,0 +1,8 @@
+{
+  "$schema": "./node_modules/oxlint/configuration_schema.json",
+  "plugins": ["react", "typescript", "oxc"],
+  "rules": {
+    "react/rules-of-hooks": "error",
+    "react/only-export-components": ["warn", { "allowConstantExport": true }]
+  }
+}

Register-concerto/README.md

@@ -0,0 +1,99 @@
+# Docusign Concerto Model Registration Guide
+
+A static instructional website that guides users through manually registering a Concerto data model in their Docusign account for use with Maestro workflows.
+
+**This tool does not log users in and does not register models automatically. It generates step-by-step instructions and commands that users execute manually using their own approved Docusign authentication.**
+
+## What It Does
+
+- Explains what Concerto model registration is and why it's needed
+- Helps users create and customize a `.cto` model file
+- Provides a JSON metamodel template for the registration API
+- Generates personalized Postman, cURL, and VS Code instructions based on the user's environment and account ID
+- Includes downloadable files (model, JSON payload, Postman collection)
+- Covers troubleshooting for common API error codes
+
+## What It Does NOT Do
+
+- Log users in or collect credentials
+- Make any API calls from the browser
+- Store tokens, secrets, or private keys
+- Execute model registration automatically
+- Collect analytics on user input
+
+## Run Locally
+
+```bash
+npm install
+npm run dev
+```
+
+Open [http://localhost:5173/Register-concerto/](http://localhost:5173/Register-concerto/)
+
+## Build
+
+```bash
+npm run build
+```
+
+Output is in `dist/`.
+
+## Test
+
+```bash
+npx vitest run
+```
+
+## Type Check
+
+```bash
+npx tsc -b
+```
+
+## Deploy to GitHub Pages
+
+1. Push to the `main` branch of a GitHub repository named `Register-concerto`.
+2. Enable GitHub Pages in the repository settings (Source: GitHub Actions).
+3. The `.github/workflows/deploy.yml` workflow will build, test, and deploy automatically.
+
+The site will be available at `https://<org>.github.io/Register-concerto/`.
+
+## Tech Stack
+
+- Vite + React + TypeScript
+- DSIndigo font (Docusign brand)
+- Vitest + Testing Library
+- GitHub Actions for CI/CD
+
+## Endpoint Assumptions
+
+The default registration endpoint used is:
+
+```
+POST /v1/accounts/{accountId}/workflows/models
+```
+
+Environment base URLs:
+- **Demo:** `https://demo.services.docusign.net`
+- **Stage:** `https://stage.services.docusign.net`
+- **Production:** `https://services.docusign.net`
+
+### Items Requiring Confirmation
+
+- Verify the registration endpoint path (`/v1/accounts/{accountId}/workflows/models`) is correct for all environments.
+- Confirm whether a `/declarations` endpoint variant exists and under what conditions it should be used.
+- Validate the Concerto metamodel JSON structure against the current API schema.
+- Confirm the Concerto CLI compile command produces the exact format expected by the API.
+
+## Documentation
+
+See the `docs/` directory:
+
+- [Overview](docs/overview.md)
+- [Prerequisites](docs/prerequisites.md)
+- [Model Registration](docs/model-registration.md)
+- [Postman Guide](docs/postman.md)
+- [cURL Guide](docs/curl.md)
+- [VS Code Guide](docs/vscode.md)
+- [Troubleshooting](docs/troubleshooting.md)
+- [Security](docs/security.md)

Register-concerto/docs/curl.md

@@ -0,0 +1,47 @@
+# cURL Guide
+
+## Set the Access Token
+
+### macOS / Linux
+
+```bash
+export DOCUSIGN_ACCESS_TOKEN="paste-token-in-terminal-only"
+```
+
+### Windows PowerShell
+
+```powershell
+$env:DOCUSIGN_ACCESS_TOKEN = "paste-token-in-terminal-only"
+```
+
+## Run the Registration Command
+
+```bash
+curl --request POST \
+  --url "{baseUrl}/v1/accounts/{accountId}/workflows/models" \
+  --header "Authorization: Bearer ${DOCUSIGN_ACCESS_TOKEN}" \
+  --header "Accept: application/json" \
+  --header "Content-Type: application/json" \
+  --data @model-registration.json
+```
+
+## Clean Up
+
+### macOS / Linux
+
+```bash
+unset DOCUSIGN_ACCESS_TOKEN
+```
+
+### Windows PowerShell
+
+```powershell
+Remove-Item Env:DOCUSIGN_ACCESS_TOKEN
+```
+
+## Token Safety
+
+- Do not put the token in the URL.
+- Do not commit the token to source control.
+- Do not save the token in your repository.
+- Remove the environment variable after use.

Register-concerto/docs/model-registration.md

@@ -0,0 +1,71 @@
+# Model Registration
+
+## Creating the Model
+
+A Concerto model (`.cto` file) defines the fields that a Maestro workflow sends to CLM.
+
+### Sample Model
+
+```cto
+namespace DataToCLM@1.0.0
+
+concept DataToCLM {
+  o String EnvelopeId
+}
+```
+
+### Common Field Types
+
+- `String` — text values
+- `Integer` — whole numbers
+- `DateTime` — date and time values
+- `Boolean` — true/false values
+- `Double` — decimal numbers
+
+## Converting to JSON
+
+The API accepts Concerto metamodel JSON, not raw `.cto` syntax.
+
+### Option A: Concerto CLI
+
+```bash
+npx @accordproject/concerto-cli compile --model model.cto --target JSONSchema
+```
+
+### Option B: JSON Template
+
+```json
+{
+  "payload": {
+    "$class": "concerto.metamodel@1.0.0.Model",
+    "decorators": [],
+    "namespace": "DataToCLM@1.0.0",
+    "imports": [],
+    "declarations": [
+      {
+        "$class": "concerto.metamodel@1.0.0.ConceptDeclaration",
+        "name": "DataToCLM",
+        "isAbstract": false,
+        "properties": [
+          {
+            "$class": "concerto.metamodel@1.0.0.StringProperty",
+            "name": "EnvelopeId",
+            "isArray": false,
+            "isOptional": false
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Validate this template against your actual model before submitting.
+
+## API Endpoint
+
+```
+POST /v1/accounts/{accountId}/workflows/models
+```
+
+An older or internal registration form may use a `/declarations` endpoint. Confirm which endpoint your environment expects.

Register-concerto/docs/overview.md

@@ -0,0 +1,20 @@
+# Overview
+
+Concerto model registration is the process of making a data model available to the Maestro "Send Data to CLM" workflow step.
+
+## What Registration Involves
+
+1. **Define a Concerto data model** — describe the fields your workflow will send to CLM.
+2. **Convert the `.cto` model to Concerto metamodel JSON** — the API accepts the metamodel format.
+3. **Submit the JSON to the account-scoped Maestro API endpoint** — a manual POST request.
+4. **Use the registered model in Maestro** — select it in the "Send Data to CLM" step.
+
+## What Registration Does NOT Do
+
+- Create a Docusign account
+- Enable IAM or configure authentication
+- Create a Maestro workflow
+- Map fields between systems
+- Populate data in CLM
+
+Registration only makes the model available as a schema that Maestro can reference.

Register-concerto/docs/postman.md

@@ -0,0 +1,31 @@
+# Postman Guide
+
+## Steps
+
+1. Obtain an OAuth access token through your organization's approved process.
+2. Open Postman.
+3. Create a new POST request.
+4. Set the URL: `{baseUrl}/v1/accounts/{accountId}/workflows/models`
+5. Add headers:
+   - `Authorization: Bearer <ACCESS_TOKEN>`
+   - `Accept: application/json`
+   - `Content-Type: application/json`
+6. Select Body → raw → JSON.
+7. Paste the model registration JSON.
+8. Send the request.
+9. Review the response (expect 2xx).
+10. Verify the model in Maestro.
+
+## Postman Collection
+
+The website generates a downloadable Postman collection with:
+
+- `{{baseUrl}}` variable
+- `{{accountId}}` variable
+- `{{accessToken}}` variable (placeholder only)
+- The registration request pre-configured
+- A basic response test
+
+## Security
+
+Do not commit or share your Postman environment file if it contains a real access token. Use Postman environment variables and keep token values local.

Register-concerto/docs/prerequisites.md

@@ -0,0 +1,17 @@
+# Prerequisites
+
+Before registering a Concerto model, ensure you have:
+
+1. **A Docusign account** with access to Maestro and CLM.
+2. **An OAuth access token** obtained through your organization's approved process.
+3. **Your account ID** found in the Docusign admin console.
+4. **A Concerto model file** (`.cto`) describing the fields to send to CLM.
+5. **A tool for making API requests:** Postman, cURL, or VS Code with terminal.
+
+## Account ID
+
+The account ID identifies the target Docusign account. It is not a login credential. It is a UUID visible in the Docusign admin console URL.
+
+## Access Token
+
+This guide does not ask for or collect access tokens. You must obtain a valid OAuth token through your organization's approved process before making the registration API call.