diff --git a/docs/content/issue_tracking/pro_integration/integrations.md b/docs/content/issue_tracking/pro_integration/integrations.md index 4be4e89b1e5..29729984db1 100644 --- a/docs/content/issue_tracking/pro_integration/integrations.md +++ b/docs/content/issue_tracking/pro_integration/integrations.md @@ -14,6 +14,7 @@ Supported Integrations: - [GitHub](/issue_tracking/pro_integration/integrations/#github) - [GitLab Boards](/issue_tracking/pro_integration/integrations/#gitlab) - [ServiceNow](/issue_tracking/pro_integration/integrations/#servicenow) +- [Zendesk](/issue_tracking/pro_integration/integrations/#zendesk) ## Opening the Integrations page @@ -72,6 +73,7 @@ For the complete list of requirements, please open the vendor specific pages bel - [GitHub](/issue_tracking/pro_integration/integrations/#github) - [GitLab Boards](/issue_tracking/pro_integration/integrations/#gitlab) - ServiceNow (Coming Soon) +- [Zendesk](/issue_tracking/pro_integration/integrations/#zendesk) ## Error Handling and Debugging diff --git a/docs/content/issue_tracking/pro_integration/integrations_toolreference.md b/docs/content/issue_tracking/pro_integration/integrations_toolreference.md index 1ed3c82bc67..d92410d0030 100644 --- a/docs/content/issue_tracking/pro_integration/integrations_toolreference.md +++ b/docs/content/issue_tracking/pro_integration/integrations_toolreference.md @@ -183,3 +183,45 @@ This maps to the ServiceNow Impact field. - **Closed Mapping**: `Closed` - **False Positive Mapping**: `Resolved` - **Risk Accepted Mapping**: `Resolved` + +## Zendesk + +The Zendesk Integration allows you to push DefectDojo Findings and Finding Groups as Zendesk tickets, assigned to a Zendesk Group of your choice. + +### Instance Setup + +- **Label** should be the label that you want to use to identify this integration. +- **Location** should be set to your Zendesk account URL, for example `https://your-subdomain.zendesk.com`. +- **Email** should be the email address of the Zendesk agent the API token belongs to. +- **API Token** should be set to a Zendesk API token. An administrator can create one in the Zendesk Admin Center under **Apps and integrations > APIs > Zendesk API** (token access must be enabled). + +### Issue Tracker Mapping + +- **Group ID** should be the numeric ID of the Zendesk Group that tickets will be assigned to. You can find it in the Admin Center under **People > Team > Groups**, or in the URL while viewing the group. + +### Severity Mapping Details + +This maps to the Zendesk ticket **Priority** field, which accepts `low`, `normal`, `high`, and `urgent`: + +- **Severity Field Name**: `Priority` +- **Info Mapping**: `low` +- **Low Mapping**: `low` +- **Medium Mapping**: `normal` +- **High Mapping**: `high` +- **Critical Mapping**: `urgent` + +### Status Mapping Details + +Zendesk tickets support the statuses `new`, `open`, `pending`, `hold`, `solved`, and `closed`. Note that `hold` must be enabled on your account before it can be used. + +- **Status Field Name**: `Status` +- **Active Mapping**: `new` +- **Closed Mapping**: `solved` +- **False Positive Mapping**: `solved` +- **Risk Accepted Mapping**: `pending` + +A few Zendesk-specific behaviors to be aware of: + +- The ticket description is the first comment in Zendesk and cannot be edited after creation, so pushing an updated Finding will sync the ticket's subject, priority, and status, but not description changes. +- Tickets are marked `solved` rather than deleted when a Finding is removed; Zendesk closes solved tickets automatically after a period of time. +- `closed` is a final status - closed tickets cannot be updated at all, and pushing a Finding whose ticket has closed will report an error.