The console's kW/MW selector does not change PowerClerk capacity mapping or ownership. Project capacity remains MW in storage; partial applicant reports do not represent a utility decision.

PowerClerk IntegrationCopy Anchor Link

GridWonk is designed to act as an AI intelligence layer on top of PowerClerk — not a replacement. The current codebase includes a typed PowerClerk API client, credential storage schema, field mapping schema, SDK fields for powerclerk_sync, and application query filters for external IDs.

GridWonk keeps its own internal lifecycle as the canonical product model. PowerClerk status is stored as external provider data; the credential and field-mapping schema can carry per-program status mapping rules, but the current sync/write-back workers are still future integration work.

The 2026-08-11 retirement of the SDK's legacy requirements success path does not change this integration: PowerClerk-linked application filters and fields are unchanged. Any integration that also needs requirement reads must use queryPublishedRequirements().

That also means PowerClerk does not replace GridWonk's org model:

• GridWonk still uses one organizations table for utility, developer, consultant, and gridwonk orgs
• shared submission rows still use utility ownership plus developer applicant linkage
• PowerClerk contributes external provider state on top of that model

This page separates what is implemented today from the approved target workflow. Do not assume a utility has active PowerClerk automation unless its credentials and mapping have been explicitly configured.

Current Integration SurfaceCopy Anchor Link

Project sync workers, attachment import, and write-back workers are future Gate 8 integration work. The current /admin/integrations UI manages platform-installed chat transports and API key counts; organization admins can connect their own Slack workspace and control Slack or Teams access from the workspace Features page. It does not yet provide PowerClerk credential entry, program selection, field mapping, or sync enablement.

The separate default-disabled Salesforce connector does not change this status. Its source snapshots, authorization, and delivery path do not implement PowerClerk sync or write-back. PowerClerk credentials, mappings, and client calls remain separate.

The outbound-only Salesforce installed-app contract is also separate and hard-disabled. It adds no PowerClerk transport, credential, synchronization or write-back capability.

Protected Admin document recovery also excludes source-managed projects, including PowerClerk. It does not add a PowerClerk retry endpoint, override source ownership, or implement attachment sync/write-back. Credentials, mappings, existing client calls and activation status remain unchanged. The service-only recovery database foundation does not activate sync workers or authorize customer replay.

The optional Combined-PDF split is an internal GridWonk packet preparation step, not a PowerClerk status or attachment-sync contract. When enabled for the applicant organization (a server-side, per-organization setting), a confirmed split replaces the combined source with derived child documents only in GridWonk's current packet projections; it does not imply an external attachment upload or change PowerClerk ownership/status mapping.

Coexistence ModelCopy Anchor Link

GridWonk is designed to be invisible to the end-user's daily workflow. Utility engineers and developers stay in PowerClerk — GridWonk intelligence appears as data within their existing system.

Target Data FlowCopy Anchor Link

Step 1: Discovery (One-Time Setup)Copy Anchor Link

When a utility connects their PowerClerk instance, GridWonk can discover the program structure with implemented client calls:

• GetPrograms() — Identify the interconnection program
• GetForms() — Find which forms contain site control attachments
• GetFormSchema() — Discover attachment slots and data field IDs
• GetProjects() and project lookup by number — inspect current project records

This generates a stored field mapping configuration that translates between PowerClerk's dynamic form fields and GridWonk's standard schema.

Step 2: Incremental SyncCopy Anchor Link

Target workflow: GridWonk polls PowerClerk at configurable intervals using changed_since for efficiency:

• GetProjects(changed_since=last_sync) — Only new/modified projects
• GetProjectData() — Structured metadata (capacity, generation type, location)
• Download Attachment() — Site control PDFs (deeds, leases, easements)

Imported data maps to GridWonk's application_submissions table with external_source='powerclerk', external_id set to the PowerClerk ProjectId, and the PowerClerk status stored as external provider state. Directional status mapping belongs in the stored integration mapping configuration until a utility-specific sync worker is enabled.

Step 3: AI ScreeningCopy Anchor Link

Imported applications are utility-owned rows, so Screen Selected on the utility queue starts one whole-packet review run in the utility lane per application (the same engine that reviews a developer's packet before submission):

1. Digitization — PDF to structured text
2. Packet review — Check against utility-specific effective-analysis requirements in ix_packet_requirements; this is separate from the utility's requirement review, which controls the per-row approved/pending labeling on the public requirements reference surfaces
3. Deficiency detection — Identify missing or non-compliant elements with page citations
4. Findings — Severity, citation, and page reference per finding.

Automated review is switched on per utility; for a utility that has not yet been onboarded for automated review, Screen Selected reports that automated review is not yet available and leaves the rows unchanged.

When an eligible formal application starts a utility review, GridWonk records Screening before work is dispatched and Screened on completion. A failed start or run restores the prior status once no other utility review is active. Authorized integration starts and the console use the same transitions. They preserve existing decisions and notices; utility-owned drafts keep their package-freeze path. These are GridWonk workflow states, not PowerClerk write-back or regulatory decisions.

Results are bound to the imported document generation that produced them. If a later sync replaces the bytes, GridWonk hides the older findings and blocks notice drafting until the replacement has been screened; an approved future write-back worker must use those current-generation results.

Step 4: Push Results BackCopy Anchor Link

Target workflow: after screening, an approved integration can write current packet-review results back to PowerClerk. It must use the result's current document generation:

• SetProjectData() — Deficiency Count and other approved current-result metadata
• Upload Attachment() — Deficiency report PDF
• SetAttachmentMetadata() — Approve/Reject site control documents
• AddCommunication() — Analysis summary email
• SetProjectStatus() — Advance project status based on results

Step 5: Follow-UpCopy Anchor Link

• changed_since polling detects resubmissions — auto re-screen with delta comparison
• The developer response stage (resubmission_under_development) is internal GridWonk lifecycle state on the shared submission; it is not mapped to PowerClerk. Only the explicit write-back calls above change PowerClerk state
• Change monitoring alerts when utility requirements are updated
• Cross-application analytics identify deficiency patterns across the queue

Compatibility MatrixCopy Anchor Link

AuthenticationCopy Anchor Link

PowerClerk uses OAuth 2.0 client credentials with an additional X-ApiKey header.

GridWonk stores encrypted credentials in the integration_credentials table, scoped to each utility organization. Credentials support both sandbox (cleanpowerdemo.com) and production (powerclerk.com) environments.

GridWonk OAuth 2.0Copy Anchor Link

GridWonk also provides its own OAuth 2.0 endpoint for programmatic access:

# Exchange API key for a short-lived JWT
curl -X POST https://gridwonk.com/api/v1/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id=gw_live_a1b2c3d4&client_secret=gw_live_..."

Legacy gb_live_/gb_test_ keys are no longer accepted. Use a gw_live_... or gw_test_... key.

Response:

{
  "access_token": "eyJ...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "api:read api:write"
}

The JWT bearer token can then be used on most organization-scoped API v1 runtime endpoints. Session-only bootstrap/OpenAPI routes and the token-exchange route itself follow their separate authentication lanes.

Rate LimitsCopy Anchor Link

Setup StatusCopy Anchor Link

Today, PowerClerk setup is an implementation/admin task, not a self-service Settings flow. Utilities should coordinate credential exchange, field mapping, and sync/write-back approval with GridWonk before any automation is enabled.

SDK UsageCopy Anchor Link

PowerClerkSyncClient is an internal client for talking to PowerClerk. It is not the public @gridwonk/sdk GridWonkClient documented elsewhere in these docs, and it is unaffected by the public SDK's requirements-method deprecations. The public SDK defaults to https://gridwonk.com; the dedicated PowerClerk client still uses the configured PowerClerk sandbox or production base URL instead. The public SDK's listProjects, getProject, createProject, and updateProject methods manage GridWonk developer projects only; they do not activate a PowerClerk sync or write data back to it.

import {
  PowerClerkSyncClient,
  POWERCLERK_BASE_URLS,
} from '@/lib/integrations/powerclerk';

const client = new PowerClerkSyncClient();

await client.configureSync({
  provider: 'powerclerk',
  environment: 'sandbox',
  organizationId: 'your-org-id',
  pollIntervalSeconds: 300,
  clientId: 'your-client-id',
  clientSecret: 'your-client-secret',
  apiKey: 'your-api-key',
  agencyId: 'your-agency-id',
  programId: 'your-program-id',
  baseUrl: POWERCLERK_BASE_URLS.sandbox,
});

// Test connection
const connected = await client.testConnection();

// Discover programs
const programs = await client.getPrograms();

// Inspect projects modified in the last hour
const projects = await client.getProjects({
  changed_since: new Date(Date.now() - 60 * 60 * 1000).toISOString(),
});

Endpoint ReferenceCopy Anchor Link

The current typed client implements the subset needed for discovery and read-side project inspection:

Attachment import, status mapping, write-back, communications, and bulk sync are target workflows until their workers and utility-specific configuration are enabled.