/home/techb158/cosmic.abdallabala.com/docs
Edit: /home/techb158/cosmic.abdallabala.com/docs/12-step-6-multi-pm-integration.md (3770B)
# Step 6: Multi-Project-Management Integration Workflow
## Purpose
The instructor requirement is broader than Trello. The dashboard must support integration with project-management applications in general. Trello is one connector, not the full integration strategy.
This step adds a shared adapter layer for four project-management applications:
1. Trello
2. Jira
3. Asana
4. Microsoft Planner
## Source alignment
Source-derived direction:
- COSMIC-Risk requires a software prototype and API.
- The implementation timeline includes API architecture, risk analysis engine, and integration with project-management tools.
- The framework must support measurable organizational, technical, and human AI risk governance.
Implementation extension:
- The connector adapter interface.
- The specific Trello, Jira, Asana, and Microsoft Planner mappings.
- The local sync simulation used for the academic prototype.
- The external work-item mapping table.
## Supported application mappings
| COSMIC object | Trello | Jira | Asana | Microsoft Planner |
|---|---|---|---|---|
| Project | Board | Project | Project | Plan |
| Risk | Card | Issue | Task | Task |
| Lifecycle phase | List | Workflow status or field | Section or custom field | Bucket or progress state |
| Risk dimension | Label | Label or component | Tag or custom field | Category or task details |
| Risk score | Custom field or badge | Custom field | Custom field | Description or task details |
| Mitigation | Checklist item | Sub-task or linked issue | Subtask | Checklist item |
| Evidence | Attachment or comment | Attachment or comment | Attachment or comment | Task reference or checklist evidence |
| Owner | Member | Assignee | Assignee | Assignee |
| Due date | Card due date | Issue due date | Task due date | Task due date |
## Added backend model
| Entity | Purpose |
|---|---|
| ProjectManagementIntegration | Stores provider, workspace/project key, auth mode, sync direction, and connection status |
| ExternalWorkItemMapping | Links local COSMIC entities to external work items |
| ProjectManagementSyncRun | Records sync history for auditability |
## Added API endpoints
| Method | Endpoint | Purpose |
|---|---|---|
| GET | `/api/integration-providers` | List supported providers |
| GET | `/api/projects/{projectId}/integrations` | List project integrations |
| POST | `/api/projects/{projectId}/integrations` | Create integration configuration |
| GET | `/api/integrations/{integrationId}` | Read integration configuration |
| PATCH | `/api/integrations/{integrationId}` | Update integration configuration |
| POST | `/api/integrations/{integrationId}/sync` | Sync risks to external work-item mappings |
| POST | `/api/integrations/{integrationId}/mappings/risks/{riskId}` | Create one risk mapping |
| GET | `/api/projects/{projectId}/integration-mappings` | List external mappings |
| GET | `/api/projects/{projectId}/sync-runs` | List sync history |
## Current implementation boundary
The current prototype does not call live Trello, Jira, Asana, or Microsoft Planner APIs. It creates deterministic local mappings and sync history. This is intentional for the academic prototype because it keeps the project runnable without OAuth credentials.
The next production step would be replacing the local adapter simulation with real provider clients.
## Acceptance criteria
- The PM integrations page shows Trello, Jira, Asana, and Microsoft Planner.
- Each connector exposes provider-specific object mapping.
- The Sync risks action creates one external work-item mapping per risk.
- Re-running sync updates existing mappings instead of duplicating them.
- Sync runs are stored and visible in the UI.
- Audit events are created for sync activity.
- Tests pass with `npm test`.