update_engagement
Modify engagement details in DefectDojo, including name, target dates, status, description, and tags, using the engagement ID for identification.
Instructions
Update an existing engagement
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| branch_tag | No | ||
| build_id | No | ||
| commit_hash | No | ||
| deduplication_on_engagement | No | ||
| description | No | ||
| engagement_id | Yes | ||
| engagement_type | No | ||
| lead_id | No | ||
| name | No | ||
| status | No | ||
| tags | No | ||
| target_end | No | ||
| target_start | No | ||
| version | No |
Implementation Reference
- The primary handler for the 'update_engagement' MCP tool. Validates inputs, constructs PATCH data from optional parameters, invokes the DefectDojo client API call, and formats the response.async def update_engagement(engagement_id: int, name: Optional[str] = None, target_start: Optional[str] = None, # Renamed from start_date target_end: Optional[str] = None, # Renamed from end_date status: Optional[str] = None, description: Optional[str] = None, # Add other updatable fields from API schema if needed lead_id: Optional[int] = None, version: Optional[str] = None, build_id: Optional[str] = None, commit_hash: Optional[str] = None, branch_tag: Optional[str] = None, engagement_type: Optional[str] = None, deduplication_on_engagement: Optional[bool] = None, tags: Optional[list] = None ) -> Dict[str, Any]: """Update an existing engagement. Only provided fields are updated. Args: engagement_id: ID of the engagement to update. name: Optional new name. target_start: Optional new start date (YYYY-MM-DD). target_end: Optional new end date (YYYY-MM-DD). status: Optional new status ('Not Started', 'Blocked', 'Cancelled', 'Completed', 'In Progress', 'On Hold', 'Waiting for Resource'). description: Optional new description. lead_id: Optional new lead ID. version: Optional new version. build_id: Optional new build ID. commit_hash: Optional new commit hash. branch_tag: Optional new branch/tag. engagement_type: Optional new engagement type ('Interactive', 'CI/CD'). deduplication_on_engagement: Optional new deduplication setting. tags: Optional new list of tags (will replace existing tags). Returns: Dictionary with status and data/error. """ # Validate status if provided if status: valid_statuses = ["Not Started", "Blocked", "Cancelled", "Completed", "In Progress", "On Hold", "Waiting for Resource"] if status not in valid_statuses: return {"status": "error", "error": f"Invalid status '{status}'. Must be one of: {', '.join(valid_statuses)}"} # Validate engagement_type if provided if engagement_type and engagement_type not in ["Interactive", "CI/CD"]: return {"status": "error", "error": f"Invalid engagement_type '{engagement_type}'. Must be 'Interactive' or 'CI/CD'."} # Prepare data payload with only provided fields data = {} if name is not None: data["name"] = name if target_start is not None: data["target_start"] = target_start if target_end is not None: data["target_end"] = target_end if status is not None: data["status"] = status # Send as is after validation if description is not None: data["description"] = description if lead_id is not None: data["lead"] = lead_id if version is not None: data["version"] = version if build_id is not None: data["build_id"] = build_id if commit_hash is not None: data["commit_hash"] = commit_hash if branch_tag is not None: data["branch_tag"] = branch_tag if engagement_type is not None: data["engagement_type"] = engagement_type if deduplication_on_engagement is not None: data["deduplication_on_engagement"] = deduplication_on_engagement if tags is not None: data["tags"] = tags # PATCH usually replaces arrays # If no fields were provided, return an error if not data: return {"status": "error", "error": "At least one field must be provided for update"} client = get_client() result = await client.update_engagement(engagement_id, data) if "error" in result: return {"status": "error", "error": result["error"], "details": result.get("details", "")} return {"status": "success", "data": result}
- src/defectdojo/tools.py:80-83 (registration)Registration of the update_engagement tool handler using the FastMCP decorator in the central tools.py module, which aggregates all tools.mcp.tool( name="update_engagement", description="Update an existing engagement" )(update_engagement)
- src/defectdojo/engagements_tools.py:232-232 (registration)Modular registration of the tool within the engagements_tools.py module's register_tools function.mcp.tool(name="update_engagement", description="Update an existing engagement")(update_engagement)
- src/defectdojo/client.py:82-84 (helper)Underlying DefectDojoClient method that executes the HTTP PATCH request to the DefectDojo API for updating an engagement.async def update_engagement(self, engagement_id: int, data: Dict[str, Any]) -> Dict[str, Any]: """Update an existing engagement.""" return await self._request("PATCH", f"/api/v2/engagements/{engagement_id}/", json=data)