DSDebug

Visual tooling for building and debugging DocuSign CLM workflows.

At Bitwise Industries, tracing a variable through a large workflow meant reading a dense exported JSON definition by hand. DSDebug parses those exports and renders the workflow as an interactive graph, reducing an afternoon of manual inspection to minutes of visual tracing.

Live application · Portfolio case study · Original 2022 tracer

What it does

• Imports exported DocuSign CLM workflow definitions.
• Renders steps, phases, decisions, success paths, and failure paths with React Flow.
• Traces typed variables through the steps that read and update them.
• Supports drag-and-drop authoring from a palette of CLM step types.
• Includes reusable workflow templates and an embedded inspection console.
• Keeps parsing and graph interaction client-side for immediate feedback.

Project history

The 2022 version was an internal productivity tool focused on variable tracing. This 2023 rebuild retained that tracer and added the visual editor, template library, and console, turning the focused debugging aid into a workflow workbench. Both versions remain available above.

Stack

Next.js 16 · React 19 · React Flow 12 (@xyflow/react) · Chakra UI 3 · native HTML Drag and Drop API

Run locally

Requires Node.js 24 LTS and npm.

npm ci
npm run dev

Open http://localhost:3000, load a bundled template, or upload an exported workflow definition.

Create a production build with:

npm run build

Audit settings-pane coverage against the bundled fresh-step and exported template data with:

npm run report:field-parity
npm run report:editor-contract-parity

The report checks fresh-step definitions, bundled templates, and every workflow export under data/. It reports exported JSON wrapper evidence separately from the authenticated Workflow Designer presentation contract. The editor-contract report checks all captured activity properties, control types, modal fields, visibility rules, and rich-text fields. A presentation contract proves editor behavior, but does not override the serialized wrapper captured by a fresh drag or import. Those serialization variants are reported separately. Activities unavailable under the connected tenant's licenses remain marked needs-fresh-drag-export; activity names and wrappers are never inferred from display labels.

The official Docusign University lesson for Use AI Data Insights also confirms that its Document input selects the agreement to process and that its Output stores the extraction result in a new or existing XML variable. The parity report records this as editor-behavior evidence only; it still requires a fresh-drag export before adding an activity name or serialized wrappers to StepData.js.

Verify additional workflow exports without uploading or modifying them:

npm run verify:clm-export -- /path/to/workflow.json

The verifier reports activity names, property names, and wrapper types only; it does not print field values. Exact fields, expression variants, imported wrapper variants, managed fields, and fallback fields are reported separately. Imported wrappers always take precedence. Neither command rewrites StepData.js, templateData.js, or imported workflow data.

Capture the authenticated designer catalog safely

An authorized CLM user can capture the activity models loaded by Workflow Designer without sharing credentials or tenant data:

1. Open browser developer tools and select the Network panel.
2. Filter for getDesignerPresentation, then reload Workflow Designer.
3. Select the request and use Copy response. Save only that JSON response to a local file. Do not export a HAR; HAR files can contain cookies, authorization headers, and unrelated tenant traffic.
4. Inspect the response locally without writing another file:

npm run capture:clm-catalog -- /path/to/getDesignerPresentation.json

The command locates encoded response wrappers, extracts only each activity's presentation contract, matches unresolved licensed display labels, and reports field names and wrapper types without printing field values. It does not contact the tenant or modify StepData.js.

After reviewing the report, write the minimal lossless capture to a new file:

npm run capture:clm-catalog -- \
  /path/to/getDesignerPresentation.json \
  --output /path/to/designer-presentation.capture.json

The output uses exclusive creation and will not overwrite an existing file. If credential-like keys, email addresses, or URLs containing query values are detected inside the retained models, output is blocked and only their JSON paths are reported. Remove those values from the source capture when possible. --allow-sensitive exists only for an explicitly reviewed, local-only capture.

Optional CLM tenant catalog

The editor works without tenant access. Imported forms, templates, metadata, documents, folders, and workflow references are preserved and can be reused.

To enable explicit Search Tenant actions, configure a server-side catalog bridge:

cp .env.example .env.local

Set DSDEBUG_CLM_CATALOG_URL to an HTTPS endpoint and optionally set DSDEBUG_CLM_CATALOG_TOKEN. The token is read only by the Next.js API route and is never sent to the browser.

The bridge receives:

GET {DSDEBUG_CLM_CATALOG_URL}?kind=form&query=contract
Authorization: Bearer {DSDEBUG_CLM_CATALOG_TOKEN}

Supported kind values are document, folder, form, documentAttribute, metadataGroup, esignatureTemplate, workflow, participant, taskGroup, and group. It must return the exact reference object expected inside the corresponding exported SpringCM field:

{
  "items": [
    {
      "label": "Contract Intake",
      "reference": {
        "type": "Guid",
        "value": "tenant-provided-reference"
      }
    }
  ]
}

DSDebug does not translate or synthesize reference; it inserts a cloned copy unchanged. This lets an account-specific CLM adapter handle OAuth, site domains, permissions, paging, and the tenant's actual serialized reference shape.

Workflow Designer's web-service control can use either the authenticated tenant endpoints or a server-side bridge. The bridge supports listing WSDLs, loading their methods, and consuming a new WSDL while preserving CLM's exact wsdlId, methodName, and methodParameters structure. Configuration is documented in .env.example; credentials remain server-side.

Authenticated contract and runner probes

The local probes use an already-authenticated Chromium debugging session. They do not accept passwords or authentication tokens. Admin probes retain field names, control types, route shapes, and endpoint query-key names while discarding field values:

npm run probe:clm-admin-contracts

The parity runner is restricted to published workflows whose names begin with DSDebug Parity. Scenarios must explicitly declare safe: true, and the runner can inspect the Start contract, execute a scenario, and normalize the resulting CLM instance:

npm run clm:parity-runner -- list
npm run clm:parity-runner -- inspect --definition <definition-uid>
npm run clm:parity-runner -- run --scenario <scenario.json>

The runner compares an optional expect.status and exits unsuccessfully when the observed terminal status differs. It does not execute arbitrary tenant workflows.

CLM expression compiler

DocuSign CLM expressions are C# and Workflow Designer validates them with a server-side compiler before saving. DSDebug includes a .NET 10/Roslyn compiler in services/clm-expression-compiler. Start it with a local .NET 10 SDK:

npm run compiler:run

Or run it in a container:

docker compose -f compose.compiler.yml up --build

DSDEBUG_CLM_EXPRESSION_URL defaults in .env.example to the local compiler. The editor posts the exact expression value:

{
  "code": "return GetVariableValue(\"ContractName\");",
  "returnType": "System.Object",
  "additionalCode": ""
}

The compiler recreates CLM's expression host shape, including GetVariableValue(string), C# 14 syntax and CLM's restricted namespace list. It returns Roslyn diagnostics using expression-relative line and column numbers. It performs compilation only; it never loads or executes the emitted code.

The same API contract can point to an authorized tenant compiler when exact tenant-version validation is required. A bearer token can be provided with DSDEBUG_CLM_EXPRESSION_TOKEN. Direct tenant connections may instead use the server-only DSDEBUG_CLM_EXPRESSION_COOKIE and DSDEBUG_CLM_EXPRESSION_CSRF_TOKEN settings. None of these values are exposed through client-side environment variables. If no compiler is reachable, the Expression Builder does not silently save unvalidated C#.

Scope

This repository is a workflow visualization and authoring tool, not a hosted DocuSign CLM service. Workflow definitions remain client-side by default. The optional tenant catalog, web-service, and expression compiler routes proxy only explicit requests and keep their credentials server-side. Authenticated probe and runner scripts operate only through a browser session opened by the user and do not store credentials.