Operating manual

Admin Manual. Day-to-day operations.

Audience: Salesforce admins running FlowMason in a production org. Standard admin skills required (permsets, MDT, Lightning App Builder, Named Credentials). Apex not required.

1. Install

Install the package. AppExchange (Install for Admins Only) OR sf project deploy start --source-dir force-app --target-org <yourOrg>.

Assign the bootstrap permset to yourself:

sf org assign permset --target-org <yourOrg> --name FlowMason_Admin

Open the FlowMason Studio app from the App Launcher. If the app doesn't appear, your profile is missing the permset.

2. Configure providers

FlowMason supports Anthropic, OpenAI, Azure OpenAI, Bedrock, Google Vertex, Ollama, EdenAI, and Salesforce-native (Models API). Pick one, or wire several and let the router pick.

See Provider Configuration for per-vendor steps. Verify via Studio → Settings → Provider Health Check → expect green ✓ within 5 seconds.

3. Configure Org Chat

Walkthrough: /docs/org-chat. Operational gates:

Capability	MDT switch	Default	Effect when off
Surface availability	`orgChatSurfacesEnabled` (CSV)	All 7 surfaces on	Drop a token to disable that surface
UI v2 visual layer	`orgChatUiV2`	false	Renders v1 transcript
Per-turn introspection	`orgChatManifestEnabled`	false	Schema-only prompt
Tool-calling	`orgChatToolCallingEnabled`	false	Single-shot path
Inventory harvest	Cron `FM Org Inventory Nightly`	not scheduled	`inventory_search` tool degrades
Discovery nudges	Custom permission grant	not granted	Nudges suppressed
DML kill-switch	`orgChatDmlEnabled`	false	All DML refused
Per-user rate limit	`orgChatMaxTurnsPerMinutePerUser`	60	n/a

4. Permission map

Permset / Permission	Grants
`FlowMason_Admin`	Studio app, settings, fmConfigEditor LWC, telemetry dashboard
`FlowMason_Pipeline_Author`	Studio canvas + pipeline save/publish
`FlowMason_Pipeline_Runner`	Run pipelines via Apex/REST/Flow without authoring rights
`FlowMason_Org_Chat_User`	The chat LWC (ADR-009 gate. Required)
`FlowMason_Org_Chat_Dml_User`	Confirm DML in the two-step modal
`FlowMason_Org_Chat_Inventory_Admin`	Run + monitor the INV-2 harvester
`FlowMason_Config_Admin`	Edit `FM_Config__mdt` via fmConfigEditor
`FlowMason_Org_Chat_Discovery` (custom perm)	See discovery nudges for non-allowlisted SObjects

End users typically need FlowMason_Org_Chat_User only.

5. Day-2 monitoring

Studio → Telemetry Dashboard (fmTelemetryDashboard LWC) shows:

Per-surface turn volume + latency percentiles (p50/p95/p99)
Provider mix + provider-attempt counts (fallback chain hits)
Tool-call rate (when ADR-013 enabled)
DML apply count + audit log
Inventory harvest health (last completion, row counts)

Backed by FM_Run_Audit__c materialised from FlowMasonRun__e. For external SIEM / Tableau / Snowflake feeds, slice FlowMasonRun__e.Detail__c by JSON_VALUE(...).

6. Routine jobs

Job	Frequency	What it does
`FMExecutionRetentionBatch`	Daily 02:00 UTC	Deletes terminal `PipelineExecution__c` rows older than `executionRetentionDays` (default 90)
`FM Org Inventory Nightly`	Daily 02:00 UTC	Re-harvests `FM_Org_Inventory_Snapshot__c`
`FMCircuitDrainerQueueable`	Triggered by queue insert	Replays buffered circuit-breaker requests

7. Troubleshooting

"Page doesn't exist" / "App is invalid"

Lightning app cache. Sign out → sign back in. If still broken, verify the permset is assigned and the FlowMason Studio tab is visible in the user's profile.

Org Chat shows no UI

FlowMason_Org_Chat_User permset assigned?
Surface token in orgChatSurfacesEnabled?
SObject in FM_Org_Chat_Allowlist__mdt?
Provider configured? (Setup → Named Credentials, LLMProviderConfig__mdt)

"Provider error: 401 / 403"

Named Credential auth header wrong or vendor API key revoked. Test in Setup → Named Credentials → External Credentials.

Inventory rows not appearing

See Org Introspection § F1-F5 (FlowDefinitionView-not-Tooling, Queueable depth cap, Schedulable blocking redeploy, single-flight cache wedge).

Pipeline stuck in `Yielded`

Yield happens under governor pressure. Resume should be automatic via Queueable. If >5 min:

List<PipelineExecution__c> stuck = [
  SELECT Id, ExecutionId__c, Current_Async_Job_Id__c
  FROM PipelineExecution__c
  WHERE Status__c = 'Yielded'
    AND StartTime__c < :Datetime.now().addMinutes(-5)
];
for (PipelineExecution__c r : stuck) {
  PipelineQueueable.resume(r.ExecutionId__c);
}

If resume fails, the execution state is in PipelineExecution__c.Context__c. Preserve before any cleanup.

Telemetry dashboard empty

Trigger may be deactivated. Setup → Apex Triggers → FlowMasonRunSubscriber must be Active.

8. Upgrades

Semver. Upgrades within a major version are schema-compatible (Schema_Version__c stays = 1). Major-version bumps ship a migration runbook in docs/release-notes/.

Read the latest release notes end-to-end.
Sandbox first. Run regression: sf apex run test --target-org <sandbox> --test-level RunLocalTests.
Verify Org Chat surfaces still load (one turn each on tab + utility + record-page).
Verify telemetry pipeline still writes FM_Run_Audit__c within 30 sec of a fresh event.
Promote.

9. Compliance posture (high level)

Topic	Status
FLS + CRUD	Mandatory across all SOQL/DML via `FMSecurityUtil`
Sharing	`with sharing` default; documented exceptions only
PII redaction	`FMRedactor` value-pattern + `FM_Pii_Policy__mdt`
Prompt FLS guard	`FMPromptGuard` scrubs invisible field references
Audit trail	`Pipeline_Audit__c` (365d) + `FM_Org_Chat_Dml_Audit__c` (immutable) + `FM_Run_Audit__c`
Data residency	Provider-dependent. Salesforce-native (Models API) inherits org region
Government Cloud / FedRAMP	Pending separate certification