Hoshin Kanri API
tRPC procedures for Hoshin Kanri strategy deployment — plans, objectives, X-Matrix correlations, catchball negotiation, alignment scoring, execution scorecard, and entity linking.
Hoshin Kanri API
The Hoshin Kanri API provides 44 tRPC procedures across 7 sections covering the full lifecycle of strategy deployment. All procedures require organization context and enforce multi-tenant data isolation.
All procedures use orgProcedure and filter by ctx.organizationId. Client-supplied organization IDs are never trusted — tenant identity comes from the server-side session context.
Plans (Section 34.3)
Manage Hoshin plan lifecycle: create, list, update, transition status, and delete.
hoshin.createPlan
Create a new Hoshin plan for a strategy deployment cycle.
Input:
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Plan name (e.g., “Strategy 2026”) |
year | number | Yes | Calendar or fiscal year |
description | string | No | Strategic context and intent |
workspaceId | string | No | Scope to workspace (null = org-wide) |
Returns: Created plan object with generated id.
hoshin.listPlans
List all Hoshin plans for the organization.
Input:
| Field | Type | Required | Description |
|---|---|---|---|
year | number | No | Filter by year |
status | enum | No | Filter by status (draft, active, closed) |
workspaceId | string | No | Filter by workspace scope |
Returns: Array of plan objects sorted by year descending.
hoshin.getPlan
Get a single plan by ID with its objectives, correlations, and summary statistics.
Input: { id: string }
Returns: Plan object with nested objectives, correlationCount, and snapshotCount.
hoshin.updatePlan
Update plan name, description, or year.
Input: { id: string, name?: string, description?: string, year?: number }
Returns: Updated plan object.
hoshin.transitionPlan
Move a plan through its lifecycle: draft to active to closed.
Input: { id: string, newStatus: "active" | "closed" }
Validation: Only forward transitions are allowed. closed to active is forbidden.
Returns: Updated plan with new status.
hoshin.deletePlan
Delete a plan and all cascaded data (objectives, correlations, catchball, links, snapshots).
Input: { id: string }
Returns: { success: true }
Objectives (Section 34.4)
Manage objectives across the X-Matrix quadrants and cascade levels.
hoshin.createObjective
Create a new objective within a plan.
Input:
| Field | Type | Required | Description |
|---|---|---|---|
planId | string | Yes | Parent plan |
parentId | string | No | Parent objective for cascade |
level | enum | Yes | enterprise, bu, site, team |
quadrant | enum | Yes | strategic_objective, annual_target, improvement_priority, metric |
title | string | Yes | Objective statement |
description | string | No | Extended rationale |
ownerId | string | No | Accountable person |
targetValue | string | No | Numeric target (stored as decimal) |
unit | string | No | Unit of measure |
dueDate | string | No | Target completion date |
Returns: Created objective object.
hoshin.listObjectives
List objectives for a plan with optional filters.
Input:
| Field | Type | Required | Description |
|---|---|---|---|
planId | string | Yes | Plan to query |
level | enum | No | Filter by cascade level |
quadrant | enum | No | Filter by X-Matrix quadrant |
parentId | string | No | Filter by parent objective |
status | enum | No | Filter by objective status |
Returns: Array of objectives sorted by sortOrder.
hoshin.getObjective
Get a single objective with its parent, children, correlations, catchball entries, and links.
Input: { id: string }
Returns: Full objective object with related data.
hoshin.updateObjective
Update objective fields including title, target, actual, status, and owner.
Input: { id: string, ...fields }
Returns: Updated objective.
hoshin.deleteObjective
Delete an objective and all cascaded children, correlations, catchball, and links.
Input: { id: string }
Returns: { success: true }
hoshin.reorderObjectives
Reorder objectives within a quadrant by updating sort orders.
Input: { planId: string, quadrant: enum, objectiveIds: string[] }
Returns: Updated sort orders.
hoshin.getCascadeTree
Get the full objective cascade tree for a plan, organized by level.
Input: { planId: string }
Returns: Nested tree structure: enterprise > BU > site > team.
hoshin.getGoldenThread
Trace a single objective up and down the cascade to show its full alignment path.
Input: { objectiveId: string }
Returns: Array of objectives from enterprise root to team leaves passing through the given objective.
Correlations (Section 34.5)
Manage X-Matrix intersection cells that link objectives across quadrants.
hoshin.createCorrelation
Create a correlation between two objectives.
Input:
| Field | Type | Required | Description |
|---|---|---|---|
planId | string | Yes | Plan scope |
objectiveIdNorth | string | Yes | North-axis objective |
objectiveIdEast | string | Yes | East-axis objective |
strength | enum | Yes | strong, medium, weak |
notes | string | No | Correlation rationale |
Validation: The two objectives must belong to the same plan. Duplicate pairs are rejected.
Returns: Created correlation object.
hoshin.updateCorrelation
Update correlation strength or notes.
Input: { id: string, strength?: enum, notes?: string }
Returns: Updated correlation.
hoshin.deleteCorrelation
Remove a correlation between two objectives.
Input: { id: string }
Returns: { success: true }
hoshin.listCorrelations
List all correlations for a plan.
Input: { planId: string }
Returns: Array of correlations with populated objective titles.
hoshin.getCorrelationMatrix
Get the full correlation grid for the X-Matrix view, organized by quadrant pair.
Input: { planId: string }
Returns: Matrix structure with north objectives, east objectives, and intersection cells.
hoshin.batchUpsertCorrelations
Bulk create or update correlations for efficient X-Matrix editing.
Input: { planId: string, correlations: Array<{ objectiveIdNorth, objectiveIdEast, strength, notes? }> }
Returns: Count of created and updated correlations.
Catchball (Section 34.6)
Manage the negotiation workflow for objective target alignment.
hoshin.proposeCatchball
Propose a target value for an objective to another user.
Input:
| Field | Type | Required | Description |
|---|---|---|---|
objectiveId | string | Yes | Objective being negotiated |
proposedToId | string | Yes | User receiving the proposal |
proposedValue | string | No | Proposed numeric target |
proposedUnit | string | No | Unit of the proposed value |
comment | string | No | Context or justification |
Returns: Catchball record with updated objective status.
hoshin.acceptCatchball
Accept a proposal on an objective.
Input: { objectiveId: string, comment?: string }
Returns: Catchball record with objective status moved to accepted.
hoshin.counterCatchball
Counter-propose a different target value.
Input:
| Field | Type | Required | Description |
|---|---|---|---|
objectiveId | string | Yes | Objective being negotiated |
proposedValue | string | Yes | Counter-proposed target |
proposedUnit | string | No | Unit |
comment | string | No | Justification for the counter |
Returns: Catchball record with objective status moved to negotiating.
hoshin.rejectCatchball
Reject a proposal with justification.
Input: { objectiveId: string, comment: string }
Returns: Catchball record.
hoshin.commentCatchball
Add a comment to the negotiation thread without changing proposal state.
Input: { objectiveId: string, comment: string }
Returns: Catchball record.
hoshin.getCatchballThread
Get the full negotiation history for an objective in chronological order.
Input: { objectiveId: string }
Returns: Array of catchball records ordered by createdAt.
hoshin.getCatchballInbox
Get all pending proposals directed at the current user.
Input: { status?: "pending" | "all" }
Returns: Array of objectives with pending catchball actions.
hoshin.getCatchballStats
Get catchball activity statistics for a plan.
Input: { planId: string }
Returns: { total, pending, accepted, countered, rejected } counts.
hoshin.bulkResolveCatchball
Accept or reject multiple pending catchball proposals at once.
Input: { objectiveIds: string[], action: "accept" | "reject", comment?: string }
Returns: Count of resolved proposals.
Alignment (Section 34.7)
Calculate and query strategic alignment scores.
hoshin.getAlignmentScore
Calculate the alignment score for a plan or specific objective subtree.
Input: { planId: string, rootObjectiveId?: string }
Returns: { score: number, breakdown: { correlated, uncorrelated, orphaned } }.
hoshin.getAlignmentByLevel
Get alignment statistics broken down by organizational level.
Input: { planId: string }
Returns: Per-level metrics: { level, objectiveCount, linkedCount, correlatedCount, avgProgress }.
hoshin.getOrphanedWork
Find objectives with no parent, no correlations, and no entity links.
Input: { planId: string }
Returns: Array of orphaned objectives that may need alignment attention.
hoshin.getContributionMatrix
Get the contribution weight matrix showing how entities distribute across objectives.
Input: { planId: string }
Returns: Matrix of objectives vs. linked entities with contribution weights.
Scorecard (Section 34.8)
Track execution progress with RAG dashboards, gap analysis, and trend data.
hoshin.getScorecardDashboard
Get the full execution scorecard for a plan.
Input: { planId: string, period?: string }
Returns: Dashboard data with RAG summary, top/bottom objectives, and overall progress.
hoshin.getObjectiveProgress
Get progress details for a single objective including trend data.
Input: { objectiveId: string }
Returns: { target, actual, gap, ragStatus, trend, history[] }.
hoshin.getGapAnalysis
Get gap analysis table for all objectives in a plan.
Input: { planId: string, level?: enum, ragFilter?: "red" | "amber" }
Returns: Array of { objective, target, actual, gap, trend, owner } sorted by gap size.
hoshin.getRagSummary
Get Red/Amber/Green counts for a plan.
Input: { planId: string }
Returns: { green: number, amber: number, red: number, total: number }.
hoshin.getTrendData
Get time-series data for an objective’s actual vs. target values.
Input: { objectiveId: string, fromDate?: string, toDate?: string }
Returns: Array of { date, actual, target } data points.
hoshin.exportScorecard
Export the scorecard as structured data for PDF or presentation generation.
Input: { planId: string, format: "summary" | "detailed" }
Returns: Export-ready data structure.
hoshin.updateActualValue
Update the actual value for an objective (manual data entry).
Input: { objectiveId: string, actualValue: string }
Returns: Updated objective with recalculated RAG status.
Entity Linking (Section 34.9)
Connect Hoshin objectives to operational entities (KPIs, projects, actions, boards).
hoshin.createLink
Link an entity to an objective.
Input:
| Field | Type | Required | Description |
|---|---|---|---|
objectiveId | string | Yes | Target objective |
linkedEntityType | enum | Yes | kpi, project, action, board |
linkedEntityId | string | Yes | ID of the linked entity |
contributionWeight | string | No | Weight 0.0-1.0 (default 1.0) |
notes | string | No | Link rationale |
Returns: Created link object.
hoshin.updateLink
Update link contribution weight or notes.
Input: { id: string, contributionWeight?: string, notes?: string }
Returns: Updated link.
hoshin.deleteLink
Remove an entity link from an objective.
Input: { id: string }
Returns: { success: true }
hoshin.listLinks
List all entity links for an objective or plan.
Input: { objectiveId?: string, planId?: string, entityType?: enum }
Returns: Array of links with entity metadata.
hoshin.getLinkedEntities
Get the actual entities linked to an objective, resolved with their current state.
Input: { objectiveId: string }
Returns: Array of resolved entities (KPI values, project status, action status, board info).
hoshin.findObjectivesForEntity
Reverse lookup: find all objectives linked to a given entity.
Input: { linkedEntityType: enum, linkedEntityId: string }
Returns: Array of objectives that reference the given entity.
Snapshots
Capture and compare point-in-time plan state.
hoshin.createSnapshot
Create a snapshot of the current plan state.
Input:
| Field | Type | Required | Description |
|---|---|---|---|
planId | string | Yes | Plan to snapshot |
snapshotDate | string | Yes | Date this snapshot represents |
snapshotType | enum | Yes | monthly, quarterly, annual |
Returns: Created snapshot with computed plan state data.
hoshin.listSnapshots
List all snapshots for a plan.
Input: { planId: string, type?: enum }
Returns: Array of snapshots sorted by date.
hoshin.compareSnapshots
Compare two snapshots to see what changed between them.
Input: { snapshotIdA: string, snapshotIdB: string }
Returns: Diff object with added, removed, and changed objectives, correlations, and metrics.
hoshin.deleteSnapshot
Delete a snapshot.
Input: { id: string }
Returns: { success: true }
Was this page helpful?