From 5ea4dc6d797398a0989274439234679ccd79cec5 Mon Sep 17 00:00:00 2001 From: kodjomiles Date: Mon, 23 Jun 2025 00:44:52 +0000 Subject: [PATCH 1/3] Remove the "Delete a ServiceNow incident" guide and integrate its content into the "Interact with ServiceNow" guide, enhancing the latter to include instructions for deleting incidents. Update relevant descriptions and ensure consistency across documentation. --- docs/guides/all/delete-servicenow-incident.md | 192 ------------------ docs/guides/all/interact-with-servicenow.md | 161 ++++++++++++++- src/components/guides-section/consts.js | 7 - 3 files changed, 157 insertions(+), 203 deletions(-) delete mode 100644 docs/guides/all/delete-servicenow-incident.md diff --git a/docs/guides/all/delete-servicenow-incident.md b/docs/guides/all/delete-servicenow-incident.md deleted file mode 100644 index 91c5e9b85..000000000 --- a/docs/guides/all/delete-servicenow-incident.md +++ /dev/null @@ -1,192 +0,0 @@ ---- -displayed_sidebar: null -description: Learn how to delete a ServiceNow incident in Port, ensuring your catalog is clean and synchronized with your ServiceNow environment. ---- - -import ExistingSecretsCallout from '/docs/guides/templates/secrets/_existing_secrets_callout.mdx' -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; - -# Delete a ServiceNow incident - -## Overview -This guide demonstrates how to implement a self-service action in Port that deletes ServiceNow incidents directly from Port using **synced webhooks**. -By combining synced webhooks with Port's automation, you can keep your software catalog clean and synchronized with your ServiceNow environment. - - -## Prerequisites - -- Complete the [onboarding process](/getting-started/overview). -- Access to your ServiceNow account with permissions to manage incidents. -- Install Port's [ServiceNow integration](https://docs.port.io/build-your-software-catalog/sync-data-to-catalog/incident-management/servicenow). - - -## Set up data source mapping - -By default, the `identifier` of the `incident` kind is mapped to the incident number (`.number`). However, deleting records in ServiceNow via API requires the system's internal ID (`.sys_id`). To fix this: - -1. Go to the [Data Sources](https://app.getport.io/settings/data-sources) page of your portal. -2. Select the ServiceNow integration. -3. Add the following YAML block into the editor to update the incident data: - -
- Updated ServiceNow integration configuration (Click to expand) - ```yaml showLineNumbers - resources: - - kind: incident - selector: - query: 'true' - apiQueryParams: - sysparmDisplayValue: 'true' - sysparmExcludeReferenceLink: 'false' - port: - entity: - mappings: - # highlight-next-line - identifier: .sys_id - title: .short_description - blueprint: '"servicenowIncident"' - properties: - category: .category - reopenCount: .reopen_count - severity: .severity - assignedTo: .assigned_to.link - urgency: .urgency - contactType: .contact_type - createdOn: '.sys_created_on | (strptime("%Y-%m-%d %H:%M:%S") | strftime("%Y-%m-%dT%H:%M:%SZ"))' - createdBy: .sys_created_by - isActive: .active - priority: .priority - ``` -
- -4. Click `Save & Resync` to apply the mapping. - - -## Implementation - -You can delete ServiceNow incident by leveraging Port's **synced webhooks** and **secrets** to directly interact with ServiceNow's Table API. - -### Add Port secrets - -To add a secret to your portal: - -1. Click on the `...` button in the top right corner of your Port application. - -2. Click on **Credentials**. - -3. Click on the `Secrets` tab. - -4. Click on `+ Secret` and add the following secrets: - - `SERVICENOW_INSTANCE_URL` - The ServiceNow instance URL. For example https://example-id.service-now.com. - - `SERVICENOW_API_TOKEN`: A base64 encoded string of your servicenow credentials generated as: - - ```bash showLineNumbers - echo -n "your-username:your-password" | base64 - ``` - -### Set up self-service action - -1. Head to the [self-service](https://app.getport.io/self-serve) page. -2. Click on the `+ New Action` button. -3. Click on the `{...} Edit JSON` button. -4. Copy and paste the following JSON configuration into the editor. - -
- Delete ServiceNow Incident (Click to expand) - - ```json showLineNumbers - { - "identifier": "delect_servicenow_incident", - "title": "Delect ServiceNow Incident", - "icon": "Servicenow", - "description": "Deletes an incident from the ServiceNow incident table using a unique system ID", - "trigger": { - "type": "self-service", - "operation": "DELETE", - "userInputs": { - "properties": {}, - "required": [], - "order": [] - }, - "blueprintIdentifier": "servicenowIncident" - }, - "invocationMethod": { - "type": "WEBHOOK", - "url": "{{.secrets.SERVICENOW_INSTANCE_URL}}/api/now/table/incident/{{.entity.identifier}}", - "agent": false, - "synchronized": true, - "method": "DELETE", - "headers": { - "RUN_ID": "{{ .run.id }}", - "Content-Type": "application/json", - "Accept": "application/json", - "Authorization": "Basic {{.secrets.SERVICENOW_API_TOKEN}}" - }, - "body": {} - }, - "requiredApproval": false - } - ``` -
- -5. Click `Save`. - -Now you should see the `Delect ServiceNow Incident` action in the [self-service](https://app.getport.io/self-serve) page. 🎉 - -### Create an automation to remove entity from Port - -Once the incident is deleted from ServiceNow, we want to automatically remove the corresponding entity in Port. To achieve this behaviour: - -1. Head to the [automations](https://app.getport.io/settings/automations) page. - -2. Click on the `+ Automation` button. - -3. Copy and paste the following JSON configuration into the editor. - -
- Delete ServiceNow incident in Port automation (Click to expand) - - ```json showLineNumbers - { - "identifier": "servicenow_incident_delete_sync_status", - "title": "Remove Deleted Incident from Port", - "description": "Removes the deleted entity in Port when after it is deleted from ServiceNow", - "trigger": { - "type": "automation", - "event": { - "type": "RUN_UPDATED", - "actionIdentifier": "delect_servicenow_incident" - }, - "condition": { - "type": "JQ", - "expressions": [ - ".diff.after.status == \"SUCCESS\"" - ], - "combinator": "and" - } - }, - "invocationMethod": { - "type": "WEBHOOK", - "url": "https://api.port.io/v1/blueprints/{{.event.diff.after.blueprint.identifier}}/entities/{{.event.diff.after.entity.identifier}}", - "agent": false, - "synchronized": true, - "method": "DELETE", - "headers": { - "RUN_ID": "{{.event.diff.after.id}}", - "Content-Type": "application/json", - "Accept": "application/json" - }, - "body": {} - }, - "publish": true - } - ``` -
- -4. Click `Save`. - -Now, whenever a user runs the `Delete ServiceNow Incident` action: - -1. The incident is deleted directly from ServiceNow via webhook. -2. The corresponding entity in Port is automatically removed, keeping your catalog clean and consistent. diff --git a/docs/guides/all/interact-with-servicenow.md b/docs/guides/all/interact-with-servicenow.md index 450342bba..98abb61cb 100644 --- a/docs/guides/all/interact-with-servicenow.md +++ b/docs/guides/all/interact-with-servicenow.md @@ -1,6 +1,6 @@ --- displayed_sidebar: null -description: Learn how to interact with ServiceNow records using Port's self-service actions +description: Learn how to interact with ServiceNow records and delete ServiceNow incidents using Port's self-service actions --- import ExistingSecretsCallout from '/docs/guides/templates/secrets/_existing_secrets_callout.mdx' @@ -9,8 +9,8 @@ import TabItem from '@theme/TabItem'; # Interact with ServiceNow records -This guide demonstrates how to implement a self-service action that interacts with any ServiceNow record directly from Port using **synced webhooks**. -You will learn how to create, update and delete records in ServiceNow without leaving the Port UI. +This guide demonstrates how to implement a self-service action that interacts with any ServiceNow record and delete ServiceNow incidents directly from Port using **synced webhooks**. +You will learn how to create, update and delete records and delete incidents in ServiceNow without leaving the Port UI. ## Use cases - Provide developers and managers with safe, self-serve CRUD operations on ServiceNow records. @@ -22,6 +22,47 @@ You will learn how to create, update and delete records in ServiceNow without le - Complete the [onboarding process](/getting-started/overview). - Access to your ServiceNow account with permissions to manage records in relevant tables. +## Set up data source mapping + +Before we can delete a ServiceNow incident, we need to update the data source mapping for the ServiceNow incident mapping, by default, the `identifier` of the `incident` kind is mapped to the incident number (`.number`). However, deleting records in ServiceNow via API requires the system's internal ID (`.sys_id`). To fix this: + +1. Go to the [Data Sources](https://app.getport.io/settings/data-sources) page of your portal. +2. Select the ServiceNow integration. +3. Add the following YAML block into the editor to update the incident data: + +
+ Updated ServiceNow integration configuration (Click to expand) + ```yaml showLineNumbers + resources: + - kind: incident + selector: + query: 'true' + apiQueryParams: + sysparmDisplayValue: 'true' + sysparmExcludeReferenceLink: 'false' + port: + entity: + mappings: + # highlight-next-line + identifier: .sys_id + title: .short_description + blueprint: '"servicenowIncident"' + properties: + category: .category + reopenCount: .reopen_count + severity: .severity + assignedTo: .assigned_to.link + urgency: .urgency + contactType: .contact_type + createdOn: '.sys_created_on | (strptime("%Y-%m-%d %H:%M:%S") | strftime("%Y-%m-%dT%H:%M:%SZ"))' + createdBy: .sys_created_by + isActive: .active + priority: .priority + ``` +
+ +4. Click `Save & Resync` to apply the mapping. + ## Implementation @@ -30,6 +71,7 @@ To enable interaction with ServiceNow from Port, we will configure three self-se 1. Create a ServiceNow record 2. Update a ServiceNow record 3. Delete a ServiceNow record +4. Delete a ServiceNow incident These actions use Port’s **synced webhooks** to communicate with ServiceNow’s REST API and rely on Port's **secret manager** to securely store authentication credentials. @@ -260,4 +302,115 @@ Now you should see the `Update ServiceNow Record` action in the [self-service](h 5. Click `Save`. -Now you should see the `Delete ServiceNow Record` action in the [self-service](https://app.getport.io/self-serve) page. 🎉 \ No newline at end of file +Now you should see the `Delete ServiceNow Record` action in the [self-service](https://app.getport.io/self-serve) page. 🎉 + + +#### Delete a ServiceNow incident + +1. Head to the [self-service](https://app.getport.io/self-serve) page. + +2. Click on the `+ New Action` button. + +3. Click on the `{...} Edit JSON` button. + +4. Copy and paste the following JSON configuration into the editor. + +
+ Delete ServiceNow Incident (Click to expand) + + ```json showLineNumbers + { + "identifier": "delect_servicenow_incident", + "title": "Delect ServiceNow Incident", + "icon": "Servicenow", + "description": "Deletes an incident from the ServiceNow incident table using a unique system ID", + "trigger": { + "type": "self-service", + "operation": "DELETE", + "userInputs": { + "properties": {}, + "required": [], + "order": [] + }, + "blueprintIdentifier": "servicenowIncident" + }, + "invocationMethod": { + "type": "WEBHOOK", + "url": "{{.secrets.SERVICENOW_INSTANCE_URL}}/api/now/table/incident/{{.entity.identifier}}", + "agent": false, + "synchronized": true, + "method": "DELETE", + "headers": { + "RUN_ID": "{{ .run.id }}", + "Content-Type": "application/json", + "Accept": "application/json", + "Authorization": "Basic {{.secrets.SERVICENOW_API_TOKEN}}" + }, + "body": {} + }, + "requiredApproval": false + } + ``` +
+ +5. Click `Save`. + +Now you should see the `Delect ServiceNow Incident` action in the [self-service](https://app.getport.io/self-serve) page. 🎉 + +

Create an automation to remove entity from Port

+ +Once the incident is deleted from ServiceNow, we want to automatically remove the corresponding entity in Port. To achieve this behaviour: + +1. Head to the [automations](https://app.getport.io/settings/automations) page. + +2. Click on the `+ Automation` button. + +3. Copy and paste the following JSON configuration into the editor. + +
+ Delete ServiceNow incident in Port automation (Click to expand) + + ```json showLineNumbers + { + "identifier": "servicenow_incident_delete_sync_status", + "title": "Remove Deleted Incident from Port", + "description": "Removes the deleted entity in Port when after it is deleted from ServiceNow", + "trigger": { + "type": "automation", + "event": { + "type": "RUN_UPDATED", + "actionIdentifier": "delect_servicenow_incident" + }, + "condition": { + "type": "JQ", + "expressions": [ + ".diff.after.status == \"SUCCESS\"" + ], + "combinator": "and" + } + }, + "invocationMethod": { + "type": "WEBHOOK", + "url": "https://api.port.io/v1/blueprints/{{.event.diff.after.blueprint.identifier}}/entities/{{.event.diff.after.entity.identifier}}", + "agent": false, + "synchronized": true, + "method": "DELETE", + "headers": { + "RUN_ID": "{{.event.diff.after.id}}", + "Content-Type": "application/json", + "Accept": "application/json" + }, + "body": {} + }, + "publish": true + } + ``` +
+ +4. Click `Save`. + +Now, whenever a user runs the `Delete ServiceNow Incident` action: + +1. The incident is deleted directly from ServiceNow via webhook. +2. The corresponding entity in Port is automatically removed, keeping your catalog clean and consistent. + diff --git a/src/components/guides-section/consts.js b/src/components/guides-section/consts.js index 87ca45503..4e5fe706c 100644 --- a/src/components/guides-section/consts.js +++ b/src/components/guides-section/consts.js @@ -1123,13 +1123,6 @@ export const availableGuides = [ logos: ["Automations"], link: "/guides/all/automatically-set-relations-between-entities-with-automation", }, - { - title: "Delete a ServiceNow incident", - description: "Create a self-service action that deletes a ServiceNow incident", - tags: ["Incident management", "ServiceNow", "Actions", "Automations"], - logos: ["ServiceNow"], - link: "/guides/all/delete-servicenow-incident", - }, { title: "Visualize your AWS storage and security configuration", description: "Create a dashboard that visualizes your AWS storage and security configuration", From 716521d26bad17eabc1596137915ef916b2315b3 Mon Sep 17 00:00:00 2001 From: kodjomiles Date: Mon, 23 Jun 2025 00:47:42 +0000 Subject: [PATCH 2/3] Update "Interact with ServiceNow" guide to include incident deletion instructions, enhancing the title and description for clarity. --- src/components/guides-section/consts.js | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/components/guides-section/consts.js b/src/components/guides-section/consts.js index 4e5fe706c..d3ca30605 100644 --- a/src/components/guides-section/consts.js +++ b/src/components/guides-section/consts.js @@ -1131,8 +1131,8 @@ export const availableGuides = [ link: "/guides/all/visualize-your-aws-storage-configuration", }, { - title: "Interact with ServiceNow records", - description: "Create a self-service action that interacts with ServiceNow records", + title: "Interact with ServiceNow records and delete incidents", + description: "Create a self-service action that interacts with ServiceNow records and delete ServiceNow incidents", tags: ["Incident management", "ServiceNow", "Actions"], logos: ["ServiceNow"], link: "/guides/all/interact-with-servicenow", From 93e0f9d6b016dc2ff72aa2e1bde3fb9af53132e9 Mon Sep 17 00:00:00 2001 From: kodjomiles Date: Mon, 23 Jun 2025 10:05:14 +0000 Subject: [PATCH 3/3] Enhance "Interact with ServiceNow" guide by adding data source mapping instructions for incident deletion and updating the guide's tags to include "Webhook" and "Automations". --- docs/guides/all/interact-with-servicenow.md | 42 +-------------------- src/components/guides-section/consts.js | 2 +- 2 files changed, 2 insertions(+), 42 deletions(-) diff --git a/docs/guides/all/interact-with-servicenow.md b/docs/guides/all/interact-with-servicenow.md index 98abb61cb..b6369724f 100644 --- a/docs/guides/all/interact-with-servicenow.md +++ b/docs/guides/all/interact-with-servicenow.md @@ -22,51 +22,11 @@ You will learn how to create, update and delete records and delete incidents in - Complete the [onboarding process](/getting-started/overview). - Access to your ServiceNow account with permissions to manage records in relevant tables. -## Set up data source mapping - -Before we can delete a ServiceNow incident, we need to update the data source mapping for the ServiceNow incident mapping, by default, the `identifier` of the `incident` kind is mapped to the incident number (`.number`). However, deleting records in ServiceNow via API requires the system's internal ID (`.sys_id`). To fix this: - -1. Go to the [Data Sources](https://app.getport.io/settings/data-sources) page of your portal. -2. Select the ServiceNow integration. -3. Add the following YAML block into the editor to update the incident data: - -
- Updated ServiceNow integration configuration (Click to expand) - ```yaml showLineNumbers - resources: - - kind: incident - selector: - query: 'true' - apiQueryParams: - sysparmDisplayValue: 'true' - sysparmExcludeReferenceLink: 'false' - port: - entity: - mappings: - # highlight-next-line - identifier: .sys_id - title: .short_description - blueprint: '"servicenowIncident"' - properties: - category: .category - reopenCount: .reopen_count - severity: .severity - assignedTo: .assigned_to.link - urgency: .urgency - contactType: .contact_type - createdOn: '.sys_created_on | (strptime("%Y-%m-%d %H:%M:%S") | strftime("%Y-%m-%dT%H:%M:%SZ"))' - createdBy: .sys_created_by - isActive: .active - priority: .priority - ``` -
- -4. Click `Save & Resync` to apply the mapping. ## Implementation -To enable interaction with ServiceNow from Port, we will configure three self-service actions: +To enable interaction with ServiceNow from Port, we will configure four self-service actions: 1. Create a ServiceNow record 2. Update a ServiceNow record diff --git a/src/components/guides-section/consts.js b/src/components/guides-section/consts.js index d3ca30605..0c932beb0 100644 --- a/src/components/guides-section/consts.js +++ b/src/components/guides-section/consts.js @@ -1133,7 +1133,7 @@ export const availableGuides = [ { title: "Interact with ServiceNow records and delete incidents", description: "Create a self-service action that interacts with ServiceNow records and delete ServiceNow incidents", - tags: ["Incident management", "ServiceNow", "Actions"], + tags: ["Incident management", "ServiceNow", "Actions","Webhook","Automations"], logos: ["ServiceNow"], link: "/guides/all/interact-with-servicenow", },