From e809c11fe19debb0c942a74266ee802b73477f1a Mon Sep 17 00:00:00 2001 From: Greg Anderson Date: Fri, 10 Jul 2026 16:52:29 -0600 Subject: [PATCH 1/3] docs: add Freshservice Pro integration reference Co-Authored-By: Claude Fable 5 --- .../pro_integration/integrations.md | 2 + .../integrations_toolreference.md | 43 +++++++++++++++++++ 2 files changed, 45 insertions(+) diff --git a/docs/content/issue_tracking/pro_integration/integrations.md b/docs/content/issue_tracking/pro_integration/integrations.md index 4be4e89b1e5..662b30be2c2 100644 --- a/docs/content/issue_tracking/pro_integration/integrations.md +++ b/docs/content/issue_tracking/pro_integration/integrations.md @@ -13,6 +13,7 @@ Supported Integrations: - [Azure Devops](/issue_tracking/pro_integration/integrations/#azure-devops-boards) - [GitHub](/issue_tracking/pro_integration/integrations/#github) - [GitLab Boards](/issue_tracking/pro_integration/integrations/#gitlab) +- [Freshservice](/issue_tracking/pro_integration/integrations/#freshservice) - [ServiceNow](/issue_tracking/pro_integration/integrations/#servicenow) ## Opening the Integrations page @@ -71,6 +72,7 @@ For the complete list of requirements, please open the vendor specific pages bel - [Azure Devops](/issue_tracking/pro_integration/integrations/#azure-devops-boards) - [GitHub](/issue_tracking/pro_integration/integrations/#github) - [GitLab Boards](/issue_tracking/pro_integration/integrations/#gitlab) +- [Freshservice](/issue_tracking/pro_integration/integrations/#freshservice) - ServiceNow (Coming Soon) ## 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..89e061d76ec 100644 --- a/docs/content/issue_tracking/pro_integration/integrations_toolreference.md +++ b/docs/content/issue_tracking/pro_integration/integrations_toolreference.md @@ -183,3 +183,46 @@ This maps to the ServiceNow Impact field. - **Closed Mapping**: `Closed` - **False Positive Mapping**: `Resolved` - **Risk Accepted Mapping**: `Resolved` + +## Freshservice + +The Freshservice Integration allows you to push DefectDojo Findings and Finding Groups as Freshservice tickets, assigned to an agent 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 Freshservice URL: `https://yourcompany.freshservice.com`. +- **API Key** should be a Freshservice API key. Find it by opening your agent avatar > **Profile Settings** - the key is shown next to the change password section. +- **Requester Email** should be the email address tickets are requested on behalf of. Freshservice requires a requester on every ticket, so DefectDojo creates tickets with this address as the requester. + +### Issue Tracker Mapping + +- **Group ID** should be the numeric ID of the Freshservice agent group tickets will be assigned to. Find it in the URL while viewing the group under **Admin > Agent Groups**. +- **Workspace ID** (optional) routes tickets to a specific workspace on multi-workspace accounts. Leave it empty to use the primary workspace. + +### Severity Mapping Details + +This maps to the Freshservice ticket **Priority** field, which uses numeric codes (`1` Low, `2` Medium, `3` High, `4` Urgent). The priority names are also accepted: + +- **Severity Field Name**: `Priority` +- **Info Mapping**: `1` +- **Low Mapping**: `1` +- **Medium Mapping**: `2` +- **High Mapping**: `3` +- **Critical Mapping**: `4` + +### Status Mapping Details + +This maps to the ticket **Status** field, which uses numeric codes (`2` Open, `3` Pending, `4` Resolved, `5` Closed). The status names are also accepted: + +- **Status Field Name**: `Status` +- **Active Mapping**: `2` +- **Closed Mapping**: `5` +- **False Positive Mapping**: `5` +- **Risk Accepted Mapping**: `3` + +A few Freshservice-specific behaviors to be aware of: + +- Updates sync the full ticket content - Freshservice allows the subject and description to be edited after creation. +- Tickets are closed rather than deleted when a Finding is removed; tickets already Resolved or Closed are left untouched. +- If your account enforces mandatory fields on closure, a close pushed from DefectDojo may be rejected by those rules and will appear in the Integration errors table. From fa1c4a195c0bb27d4df2a8eada45b742d0b6c22e Mon Sep 17 00:00:00 2001 From: Greg Anderson Date: Fri, 10 Jul 2026 20:55:51 -0600 Subject: [PATCH 2/3] docs: correct the Freshservice API key location Freshservice's own API-docs intro still says the key sits next to the change password section, but the current UI shows it in Profile settings below Delegate Approvals, behind a captcha. Co-Authored-By: Claude Fable 5 --- .../pro_integration/integrations_toolreference.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/issue_tracking/pro_integration/integrations_toolreference.md b/docs/content/issue_tracking/pro_integration/integrations_toolreference.md index 89e061d76ec..336f68aa4a3 100644 --- a/docs/content/issue_tracking/pro_integration/integrations_toolreference.md +++ b/docs/content/issue_tracking/pro_integration/integrations_toolreference.md @@ -192,7 +192,7 @@ The Freshservice Integration allows you to push DefectDojo Findings and Finding - **Label** should be the label that you want to use to identify this integration. - **Location** should be set to your Freshservice URL: `https://yourcompany.freshservice.com`. -- **API Key** should be a Freshservice API key. Find it by opening your agent avatar > **Profile Settings** - the key is shown next to the change password section. +- **API Key** should be a Freshservice API key. Find it by clicking your profile picture (top right) > **Profile settings** - the key appears on the right below the **Delegate Approvals** section, after you complete the captcha. If no key is shown there, API access may be disabled at the account level and an administrator has to enable it first. - **Requester Email** should be the email address tickets are requested on behalf of. Freshservice requires a requester on every ticket, so DefectDojo creates tickets with this address as the requester. ### Issue Tracker Mapping From 8a6012cd07655e17a80b7403a6e37a840f07f3b5 Mon Sep 17 00:00:00 2001 From: Greg Anderson Date: Fri, 10 Jul 2026 21:34:53 -0600 Subject: [PATCH 3/3] docs: note Freshservice resolution-note and priority-matrix behavior Both surfaced during live testing against a real Freshservice account. Co-Authored-By: Claude Fable 5 --- .../pro_integration/integrations_toolreference.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/content/issue_tracking/pro_integration/integrations_toolreference.md b/docs/content/issue_tracking/pro_integration/integrations_toolreference.md index 336f68aa4a3..e6afafed784 100644 --- a/docs/content/issue_tracking/pro_integration/integrations_toolreference.md +++ b/docs/content/issue_tracking/pro_integration/integrations_toolreference.md @@ -224,5 +224,5 @@ This maps to the ticket **Status** field, which uses numeric codes (`2` Open, `3 A few Freshservice-specific behaviors to be aware of: - Updates sync the full ticket content - Freshservice allows the subject and description to be edited after creation. -- Tickets are closed rather than deleted when a Finding is removed; tickets already Resolved or Closed are left untouched. -- If your account enforces mandatory fields on closure, a close pushed from DefectDojo may be rejected by those rules and will appear in the Integration errors table. +- Tickets are closed rather than deleted when a Finding is removed; tickets already Resolved or Closed are left untouched. A resolution note is attached automatically on closure, so accounts that require one (a common business rule) accept the close. +- Some accounts compute a ticket's priority from an Impact/Urgency matrix or a business rule and ignore the priority sent at creation. DefectDojo detects this and re-applies the mapped priority with a follow-up update, so the mapping still takes effect.