🔍 Contents
-
Prerequisites
-
Authentication
-
Overview of Endpoints
-
Creating a Countermeasure (POST)
-
Updating a Countermeasure (PUT)
-
Retrieving & Deleting Countermeasures
-
Managing the Description
-
Technical Notes
-
Tips & Best Practices
-
FAQ
📋 Prerequisites
-
🔐 API credentials (Username + Password for HTTP Basic Auth)
-
🌐 A request execution tool (e.g., Postman, Swagger, Python, …)
-
🧾 ID of the associated deviation (
deviationId) -
👥 Responsible person (UUID of a team member)
-
📅 Planned end date (format:
YYYY-MM-DD)
🔑 Authentication
Authentication is performed using HTTP Basic Auth.
All API activities are recorded in the change log under the user "API-USER".
🔗 Overview of Endpoints (PDCA)
| Action | Method | Endpoint |
|---|---|---|
| Retrieve countermeasures | GET | /exchange/countermeasures?team={id} |
| Retrieve single countermeasure | GET | /exchange/countermeasures/{id} |
| View status history | GET | /exchange/countermeasures/{id}/status-history |
| Create new countermeasure | POST | /exchange/countermeasures/pdca |
| Update countermeasure | PUT | /exchange/countermeasures/pdca/{id} |
| Delete countermeasure | DELETE | /exchange/countermeasures/pdca/{id} |
| Retrieve description | GET | /exchange/countermeasures/pdca/{id}/description |
| Update description | PUT | /exchange/countermeasures/pdca/{id}/description |
📸 Screenshot: Endpoints in Swagger UI
✍️ Creating a Countermeasure (POST)
POST /exchange/countermeasures/pdca
Content-Type: application/json
Example body:
{
"deviationId": "9770be21-ba1a-4b45-a21c-92fcdb62a4e3",
"endDatePlan": "2025-08-30",
"priority": true,
"progress": "PLAN",
"closeDeviation": false,
"responsiblePerson": "ffa6fda3-e10f-4e86-bd3a-6314e7e28ee6",
"responsibleTeam": "e70ebfdd-760b-4f50-b69f-6564acb4a367",
"status": 1,
"statusMessage": "In planning",
"title": "Implement countermeasure"
}
✨ Tip: The parameter "closeDeviation": true can be used to automatically close the associated deviation – but only if no open countermeasures remain.
✏️ Updating a Countermeasure (PUT)
PUT /exchange/countermeasures/pdca/{id}
Example body:
{
"progress": "DO",
"status": 2,
"statusMessage": "Countermeasure in progress",
"endDatePlan": "2025-09-10"
}
⚠️ Important: Changes to progress, status, or statusMessage should be consistent. Otherwise, validation errors may occur.
📄 Retrieving & Deleting Countermeasures
Retrieve single countermeasure:
GET /exchange/countermeasures/{id}
View status history:
GET /exchange/countermeasures/{id}/status-history
Delete countermeasure:
DELETE /exchange/countermeasures/pdca/{id}
⚠️ Deleting also removes linked content (e.g., feedback, top issue).
Tasks remain but lose their connection to the countermeasure.
📝 Managing the Description
Retrieve description:
GET /exchange/countermeasures/pdca/{id}/description
Accept: text/html
Update description:
PUT /exchange/countermeasures/pdca/{id}/description
Content-Type: text/html
Example:
<p>Countermeasure description in HTML</p>
📌 Technical Notes
-
Supported countermeasure types: PDCA only
-
Required fields:
title,responsibleTeam,responsiblePerson,deviationId,progress,status -
Status codes:
1 = open,2 = in progress,3 = completed -
Progress sequence:
PLAN → DO → CHECK → ACT -
Description must be in valid HTML format
✨ Tips & Best Practices
-
Start API tests in Swagger Editor or Postman
-
Use structured titles and status messages for better clarity
-
Avoid assigning countermeasures to closed deviations multiple times
-
Always document countermeasures with description and progress details
❓ FAQ
Can I manage A3 countermeasures via the API?
→ No – A3 countermeasures can only be read, not created or edited.
What values are allowed for progress?
→ PLAN, DO, CHECK, ACT
How can I link a countermeasure to a deviation?
→ By using the deviationId field in the POST/PUT body.
What happens when I delete a countermeasure?
→ The countermeasure is permanently removed. Linked tasks remain but lose their connection to the countermeasure.