FM / docs

/home/techb158/balavpn.abdallabala.com/docs/

/home/techb158/balavpn.abdallabala.com/docs

Name	Size	Mode	Actions
00-design-study.md	3678	0644	edit dl rm
01-uml-class-diagram.puml	11869	0644	edit dl rm
02-use-case-diagram.puml	3763	0644	edit dl rm
03-sequence-diagrams.puml	9732	0644	edit dl rm
04-database-entity-model.mmd	7051	0644	edit dl rm
05-database-schema.sql	13372	0644	edit dl rm
06-diagram-preview.html	5021	0644	edit dl rm
07-design-checklist.md	3256	0644	edit dl rm
08-step-2-storage-layer.md	5325	0644	edit dl rm
09-step-3-risk-crud-ui.md	3380	0644	edit dl rm
10-step-4-mitigation-workflow.md	3996	0644	edit dl rm
11-step-5-deployment-gate-workflow.md	2292	0644	edit dl rm
12-step-6-multi-pm-integration.md	3770	0644	edit dl rm
13-step-6-1-microsoft-planner-integration.md	2335	0644	edit dl rm
14-step-7-reporting-export.md	4158	0644	edit dl rm
15-step-7-1-oauth-live-connectors.md	4545	0644	edit dl rm
16-step-8-user-roles-access-control.md	3297	0644	edit dl rm
17-step-9-production-deployment-security.md	4228	0644	edit dl rm
18-step-10-final-academic-submission.md	3199	0644	edit dl rm
19-final-report-draft.md	6814	0644	edit dl rm
20-instructor-submission-checklist.md	3639	0644	edit dl rm
21-demo-script.md	3948	0644	edit dl rm
22-traceability-matrix.md	4847	0644	edit dl rm
23-testing-evidence.md	2961	0644	edit dl rm
24-evaluation-rubric-mapping.md	2910	0644	edit dl rm
25-final-deployment-runbook.md	3214	0644	edit dl rm
26-known-limitations-and-future-work.md	2632	0644	edit dl rm
27-final-qa-checklist.md	2893	0644	edit dl rm
28-demo-rehearsal-script.md	3618	0644	edit dl rm
29-submission-freeze-report.md	2769	0644	edit dl rm
30-final-known-issues.md	1876	0644	edit dl rm
31-saas-rebuild-implementation.md	2571	0644	edit dl rm
application-documentation.md	27515	0644	edit dl rm
conversation-log.md	18503	0644	edit dl rm
dashboard-spec.md	3691	0644	edit dl rm
database-guide.md	37826	0644	edit dl rm
development-summary.md	7070	0644	edit dl rm
github-architecture.svg	6288	0644	edit dl rm

Edit: /home/techb158/balavpn.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`.

cmd: