Improve Cancel Incident UI Action - Enhanced Documentation and Error Handling

Client-Side Components/UI Actions/Cancel Incident/README.md

@@ -1 +1,57 @@
-This is a ui action run on incident table which is client callable, run on condition current.state == '1' which means when state is new.It cancel the incident through the form.
+# Cancel Incident UI Action
+
+A UI Action in ServiceNow is a script that defines an action or button within the platform's user interface. It enables users to perform specific operations on forms and lists, such as creating, updating, or deleting records, or executing custom scripts. UI Actions enhance the user experience by providing functional buttons, links, or context menus.
+
+## Overview
+
+This UI Action allows users to cancel incidents directly from the incident form. It provides a confirmation dialog to prevent accidental cancellations and updates the incident state to "Cancelled" (state value 8) when confirmed.
+
+## Features
+
+- **Confirmation Dialog**: Uses GlideModal to display a confirmation prompt before cancelling
+- **State Management**: Updates incident state to "Cancelled" (value 8)
+- **Client-Side Validation**: Runs client-side for better user experience
+- **Conditional Display**: Only shows when incident state is "New" (state value 1)
+
+## Configuration
+
+Create a UI Action with the following field values:
+
+**Name**: Cancel Incident
+
+**Action Name**: cancel_incident
+
+**Table**: Incident [incident]
+
+**Client**: checked (true)
+
+**Onclick**: cancelIncident();
+
+**Condition**: current.state == '1'
+
+**Script**: Use the provided script.js file
+
+## Usage
+
+1. Navigate to an incident record in "New" state
+2. Click the "Cancel Incident" button
+3. Confirm the action in the modal dialog
+4. The incident state will be updated to "Cancelled"
+
+## Technical Details
+
+- **Client-Side Function**: `cancelIncident()` - Displays confirmation modal
+- **Server-Side Function**: `serverCancel()` - Updates the incident state
+- **Modal Configuration**: Uses `glide_ask_standard` modal with custom title
+- **State Value**: Sets incident state to '8' (Cancelled)
+
+## Prerequisites
+
+- User must have write access to the incident table
+- Incident must be in "New" state (state = 1) for the UI Action to be visible
+
+## Notes
+
+- This UI Action only appears on incident forms when the state is "New"
+- The confirmation dialog helps prevent accidental cancellations
+- The server-side script executes only after user confirmation

Client-Side Components/UI Actions/Cancel Incident/SETUP.md

@@ -0,0 +1,147 @@
+# Setup Instructions for Cancel Incident UI Action
+
+This document provides detailed step-by-step instructions for implementing the Cancel Incident UI Action in your ServiceNow instance.
+
+## Prerequisites
+
+- Administrative access to ServiceNow instance
+- Access to System Definition > UI Actions module
+- Understanding of ServiceNow UI Actions and client-server scripting
+
+## Step-by-Step Setup
+
+### 1. Navigate to UI Actions
+
+1. In ServiceNow, go to **System Definition > UI Actions**
+2. Click **New** to create a new UI Action
+
+### 2. Configure Basic Settings
+
+Fill in the following fields:
+
+| Field | Value | Description |
+|-------|-------|-------------|
+| **Name** | Cancel Incident | Display name for the UI Action |
+| **Table** | Incident [incident] | Target table for the UI Action |
+| **Action name** | cancel_incident | Unique identifier for the action |
+| **Active** | ✓ (checked) | Enables the UI Action |
+
+### 3. Configure Display Settings
+
+| Field | Value | Description |
+|-------|-------|-------------|
+| **Form button** | ✓ (checked) | Shows button on form view |
+| **Form link** | ☐ (unchecked) | Optional: Show as link instead |
+| **List banner button** | ☐ (unchecked) | Not needed for this action |
+| **List choice** | ☐ (unchecked) | Not needed for this action |
+
+### 4. Configure Client Settings
+
+| Field | Value | Description |
+|-------|-------|-------------|
+| **Client** | ✓ (checked) | Enables client-side execution |
+| **Onclick** | `cancelIncident();` | Client-side function to call |
+
+### 5. Configure Conditions
+
+| Field | Value | Description |
+|-------|-------|-------------|
+| **Condition** | `current.state == '1'` | Only show for "New" incidents |
+
+### 6. Add the Script
+
+Copy the entire content from `script.js` and paste it into the **Script** field of the UI Action.
+
+### 7. Configure Advanced Settings (Optional)
+
+| Field | Value | Description |
+|-------|-------|-------------|
+| **Order** | 100 | Display order (adjust as needed) |
+| **Hint** | Cancel this incident | Tooltip text |
+| **Comments** | UI Action to cancel incidents in New state | Internal documentation |
+
+## Verification Steps
+
+### 1. Test the UI Action
+
+1. Navigate to an incident in "New" state
+2. Verify the "Cancel Incident" button appears
+3. Click the button and confirm the modal appears
+4. Test both "OK" and "Cancel" in the confirmation dialog
+
+### 2. Verify State Changes
+
+1. After confirming cancellation, check that:
+   - Incident state changes to "Cancelled"
+   - Work notes are added with cancellation details
+   - Success message appears
+
+### 3. Test Edge Cases
+
+1. Try accessing the UI Action on incidents in other states (should not appear)
+2. Test with different user roles to ensure proper permissions
+3. Verify error handling works correctly
+
+## Troubleshooting
+
+### Common Issues
+
+**UI Action doesn't appear:**
+- Check that the incident is in "New" state (state = 1)
+- Verify the condition field: `current.state == '1'`
+- Ensure the UI Action is marked as Active
+
+**Script errors:**
+- Check browser console for JavaScript errors
+- Verify the script is properly copied from `script.js`
+- Ensure proper syntax and formatting
+
+**Permission issues:**
+- Verify user has write access to incident table
+- Check ACL rules for incident cancellation
+- Ensure proper role assignments
+
+### Debug Mode
+
+To enable debug logging, add this line at the beginning of the `serverCancel()` function:
+
+```javascript
+gs.info('Debug: Starting incident cancellation for ' + current.number);
+```
+
+## Security Considerations
+
+- The UI Action respects existing ACL rules
+- Only users with incident write permissions can cancel incidents
+- All cancellations are logged for audit purposes
+- Work notes provide cancellation history
+
+## Customization Options
+
+### Modify Confirmation Message
+
+Edit line 33 in the script to customize the confirmation dialog:
+
+```javascript
+gm.setPreference("question", "Your custom message here");
+```
+
+### Change Cancellation Reason
+
+Modify the work note in the `serverCancel()` function (line 79):
+
+```javascript
+var workNote = 'Custom cancellation reason: ' + gs.getUserDisplayName() + ' on ' + gs.nowDateTime();
+```
+
+### Add Additional Validations
+
+Add custom validation logic in the `cancelIncident()` function before showing the modal.
+
+## Support
+
+For issues or questions:
+1. Check ServiceNow system logs
+2. Review browser console for client-side errors
+3. Test in a development instance first
+4. Consult ServiceNow documentation for UI Actions

Client-Side Components/UI Actions/Cancel Incident/script.js

@@ -1,17 +1,101 @@
-function cancelIncident(){
-	var gm = new GlideModal("glide_ask_standard", false, 600); // glide modal to get the confirmation
-	gm.setPreference("title", "Are you sure you wanna cancel incident!!!");
-	gm.setPreference("onPromptComplete", function() {
-		gsftSubmit(null,g_form.getFormElement(),'cancel_incident');}); //calling same ui action
-	gm.render();
-
+/**
+ * Client-side function to initiate incident cancellation
+ * Displays a confirmation modal before proceeding with the cancellation
+ */
+function cancelIncident() {
+    try {
+        // Validate that we have a valid form and record
+        if (!g_form || !g_form.getUniqueValue()) {
+            alert('Error: Unable to access incident record. Please refresh the page and try again.');
+            return;
+        }
+
+        // Check if incident is in the correct state for cancellation
+        var currentState = g_form.getValue('state');
+        if (currentState !== '1') {
+            alert('Error: This incident cannot be cancelled. Only incidents in "New" state can be cancelled.');
+            return;
+        }
+
+        // Create confirmation modal with improved messaging
+        var gm = new GlideModal("glide_ask_standard", false, 600);
+        gm.setPreference("title", "Cancel Incident Confirmation");
+        gm.setPreference("warning", true);
+        gm.setPreference("onPromptComplete", function() {
+            // Show loading message
+            g_form.addInfoMessage('Cancelling incident...');
+
+            // Submit the form to trigger server-side processing
+            gsftSubmit(null, g_form.getFormElement(), 'cancel_incident');
+        });
+
+        // Set the confirmation message
+        gm.setPreference("question", "Are you sure you want to cancel this incident?\n\nThis action will change the incident state to 'Cancelled' and cannot be easily undone.");
+
+        // Render the modal
+        gm.render();
+
+    } catch (error) {
+        // Handle any unexpected errors
+        console.error('Error in cancelIncident function:', error);
+        alert('An unexpected error occurred. Please contact your system administrator.');
+    }
 }
 
-if(typeof window == 'undefined'){
-	serverCancel();
+/**
+ * Server-side execution block
+ * This code runs on the server when the UI Action is submitted
+ */
+if (typeof window == 'undefined') {
+    serverCancel();
 }
 
-function serverCancel(){
-	current.state = '8'; //setting the state to canceled
-	current.update();
+/**
+ * Server-side function to cancel the incident
+ * Updates the incident state to 'Cancelled' and adds a work note
+ */
+function serverCancel() {
+    try {
+        // Validate that we have a current record
+        if (!current || !current.isValidRecord()) {
+            gs.addErrorMessage('Error: Invalid incident record.');
+            return;
+        }
+
+        // Double-check the current state before cancelling
+        if (current.state.toString() !== '1') {
+            gs.addErrorMessage('Error: This incident cannot be cancelled. Only incidents in "New" state can be cancelled.');
+            return;
+        }
+
+        // Store original values for logging
+        var incidentNumber = current.number.toString();
+        var originalState = current.state.getDisplayValue();
+
+        // Update the incident state to 'Cancelled' (state value 8)
+        current.state = '8';
+
+        // Add a work note to document the cancellation
+        var workNote = 'Incident cancelled by ' + gs.getUserDisplayName() + ' on ' + gs.nowDateTime();
+        if (current.work_notes.nil()) {
+            current.work_notes = workNote;
+        } else {
+            current.work_notes = current.work_notes + '\n\n' + workNote;
+        }
+
+        // Update the record
+        current.update();
+
+        // Log the action for audit purposes
+        gs.info('Incident ' + incidentNumber + ' cancelled by user ' + gs.getUserName() + 
+                '. State changed from "' + originalState + '" to "Cancelled"');
+
+        // Provide user feedback
+        gs.addInfoMessage('Incident ' + incidentNumber + ' has been successfully cancelled.');
+
+    } catch (error) {
+        // Handle server-side errors
+        gs.error('Error cancelling incident: ' + error.message);
+        gs.addErrorMessage('An error occurred while cancelling the incident. Please contact your system administrator.');
+    }
 }