@bettsnation/paperclip-plugin-servicenow 0.1.0

package/README.md

@@ -0,0 +1,63 @@
+# @bettsnation/paperclip-plugin-servicenow
+
+Paperclip plugin for bidirectional ServiceNow incident sync.
+
+## Inbound (SN → Paperclip)
+- SN Business Rule fires webhook on incident creation
+- Plugin creates Paperclip issue assigned to target agent
+- Sets correlation_id on SN incident for back-reference
+
+## Outbound (Paperclip → SN)
+- Issue completed → auto-resolve SN incident
+- Issue status changes → SN work notes
+- Agent comments → SN work notes
+
+## Install
+
+```
+npm install @bettsnation/paperclip-plugin-servicenow
+```
+
+Or: Instance Settings → Plugins → Install Plugin → `@bettsnation/paperclip-plugin-servicenow`
+
+## Configuration
+
+| Setting | Required | Description |
+|---------|----------|-------------|
+| `snInstanceUrl` | Yes | e.g. `https://dev199497.service-now.com` |
+| `snUsernameRef` | Yes | Secret ref for SN username |
+| `snPasswordRef` | Yes | Secret ref for SN password |
+| `snWebhookSecretRef` | Yes | Secret ref for inbound webhook verification |
+| `targetCompanyId` | Yes | Paperclip company for new issues |
+| `targetAgentId` | Yes | Agent to assign new issues to |
+| `targetProjectId` | Yes | Project for new issues |
+| `autoResolve` | No | Auto-resolve SN incidents (default: true) |
+| `syncWorkNotes` | No | Sync comments to SN (default: true) |
+
+## SN Business Rule
+
+Create on `incident` table, after insert:
+```javascript
+(function executeRule(current, previous) {
+    var rm = new sn_ws.RESTMessageV2();
+    rm.setEndpoint('<PLUGIN_WEBHOOK_URL>');
+    rm.setHttpMethod('POST');
+    rm.setRequestHeader('Content-Type', 'application/json');
+    rm.setRequestHeader('X-SN-Webhook-Secret', gs.getProperty('x_pc.webhook_secret'));
+    rm.setRequestBody(JSON.stringify({
+        number: current.getValue('number'),
+        sys_id: current.getValue('sys_id'),
+        short_description: current.getValue('short_description'),
+        description: current.getValue('description'),
+        priority: current.getValue('priority'),
+        caller_id: current.getDisplayValue('caller_id'),
+        assignment_group: current.getDisplayValue('assignment_group'),
+        category: current.getValue('category'),
+        subcategory: current.getValue('subcategory')
+    }));
+    rm.executeAsync();
+})(current, previous);
+```
+
+## License
+MIT

package/dist/manifest.d.ts

@@ -0,0 +1,3 @@
+import type { PaperclipPluginManifestV1 } from "@paperclipai/plugin-sdk";
+declare const manifest: PaperclipPluginManifestV1;
+export default manifest;

package/dist/manifest.js

@@ -0,0 +1,83 @@
+const manifest = {
+    id: "bettsnation.servicenow",
+    apiVersion: 1,
+    version: "0.1.0",
+    displayName: "ServiceNow Integration",
+    description: "Bidirectional ServiceNow incident sync. Receives SN webhooks to create Paperclip issues, auto-updates SN incidents as issues progress.",
+    author: "BettsNation",
+    categories: ["connector"],
+    capabilities: [
+        "events.subscribe",
+        "webhooks.receive",
+        "issues.create",
+        "issues.read",
+        "http.outbound",
+        "secrets.read-ref",
+    ],
+    entrypoints: {
+        worker: "./dist/worker.js",
+    },
+    webhooks: [
+        {
+            endpointKey: "servicenow-incident",
+            displayName: "ServiceNow Incident Webhook",
+            description: "Receives incident create/update webhooks from ServiceNow Business Rules",
+        },
+    ],
+    instanceConfigSchema: {
+        type: "object",
+        properties: {
+            snInstanceUrl: {
+                type: "string",
+                title: "ServiceNow Instance URL",
+                description: "e.g. https://dev199497.service-now.com",
+            },
+            snUsernameRef: {
+                type: "string",
+                title: "SN Username (Secret Ref)",
+            },
+            snPasswordRef: {
+                type: "string",
+                title: "SN Password (Secret Ref)",
+            },
+            snWebhookSecretRef: {
+                type: "string",
+                title: "Inbound Webhook Secret (Secret Ref)",
+            },
+            targetCompanyId: {
+                type: "string",
+                title: "Target Company ID",
+                description: "Paperclip company to create issues in",
+            },
+            targetAgentId: {
+                type: "string",
+                title: "Target Agent ID",
+                description: "Agent to assign new issues to",
+            },
+            targetProjectId: {
+                type: "string",
+                title: "Target Project ID",
+            },
+            autoResolve: {
+                type: "boolean",
+                title: "Auto-resolve SN incidents on issue completion",
+                default: true,
+            },
+            syncWorkNotes: {
+                type: "boolean",
+                title: "Sync agent comments to SN work notes",
+                default: true,
+            },
+        },
+        required: [
+            "snInstanceUrl",
+            "snUsernameRef",
+            "snPasswordRef",
+            "snWebhookSecretRef",
+            "targetCompanyId",
+            "targetAgentId",
+            "targetProjectId",
+        ],
+    },
+};
+export default manifest;

package/dist/worker.d.ts

@@ -0,0 +1,2 @@
+declare const plugin: import("@paperclipai/plugin-sdk").PaperclipPlugin;
+export default plugin;

package/dist/worker.js

@@ -0,0 +1,168 @@
+import { definePlugin, runWorker, } from "@paperclipai/plugin-sdk";
+const PRIORITY_MAP = {
+    "1": "critical",
+    "2": "high",
+    "3": "medium",
+    "4": "low",
+};
+async function snRequest(ctx, config, method, path, body) {
+    const username = await ctx.secrets.resolve(config.snUsernameRef);
+    const password = await ctx.secrets.resolve(config.snPasswordRef);
+    const auth = Buffer.from(`${username}:${password}`).toString("base64");
+    return ctx.http.fetch(`${config.snInstanceUrl}${path}`, {
+        method,
+        headers: {
+            "Content-Type": "application/json",
+            Accept: "application/json",
+            Authorization: `Basic ${auth}`,
+        },
+        body: body ? JSON.stringify(body) : undefined,
+    });
+}
+function isSNSysId(value) {
+    return typeof value === "string" && /^[a-f0-9]{32}$/.test(value);
+}
+let _config = null;
+let _ctx = null;
+const plugin = definePlugin({
+    async setup(ctx) {
+        const config = (await ctx.config.get());
+        _config = config;
+        _ctx = ctx;
+        // =========================================================
+        // OUTBOUND: Paperclip events → update SN incident
+        // =========================================================
+        if (config.autoResolve !== false) {
+            // Auto-resolve SN incident when Paperclip issue completes
+            ctx.events.on("issue.updated", async (event) => {
+                const payload = event.payload;
+                const changes = payload?.changes;
+                const statusChange = changes?.status;
+                const newStatus = statusChange?.to ?? payload?.status;
+                if (newStatus !== "done")
+                    return;
+                const originId = payload?.originId;
+                if (!isSNSysId(originId))
+                    return;
+                const agentName = payload?.assigneeAgentName ?? "Paperclip agent";
+                const issueTag = payload?.issueTag ?? event.entityId;
+                const response = await snRequest(ctx, config, "PATCH", `/api/now/table/incident/${originId}`, {
+                    state: "6",
+                    close_code: "Solved (Permanently)",
+                    close_notes: `Resolved by ${agentName}. Issue: ${issueTag}`,
+                });
+                if (response.ok) {
+                    ctx.logger.info(`Resolved SN incident for ${issueTag}`);
+                }
+                else {
+                    ctx.logger.error(`Failed to resolve SN incident: ${response.status}`);
+                }
+            });
+            // Sync status changes to SN work notes
+            ctx.events.on("issue.updated", async (event) => {
+                const payload = event.payload;
+                const changes = payload?.changes;
+                const statusChange = changes?.status;
+                const newStatus = statusChange?.to;
+                if (!newStatus || newStatus === "done")
+                    return;
+                const originId = payload?.originId;
+                if (!isSNSysId(originId))
+                    return;
+                const issueTag = payload?.issueTag ?? event.entityId;
+                const agentName = payload?.assigneeAgentName ?? "Agent";
+                const messages = {
+                    in_progress: `${agentName} is working on this. Issue: ${issueTag}`,
+                    in_review: `Code review in progress. Issue: ${issueTag}`,
+                    blocked: `Issue ${issueTag} is blocked — awaiting board approval.`,
+                    cancelled: `Issue ${issueTag} was cancelled.`,
+                };
+                const message = messages[newStatus];
+                if (!message)
+                    return;
+                await snRequest(ctx, config, "PATCH", `/api/now/table/incident/${originId}`, {
+                    work_notes: `[Paperclip] ${message}`,
+                });
+            });
+        }
+        // Sync agent comments to SN work notes
+        if (config.syncWorkNotes !== false) {
+            ctx.events.on("issue.comment.created", async (event) => {
+                const payload = event.payload;
+                const issue = payload?.issue;
+                const originId = issue?.originId;
+                if (!isSNSysId(originId))
+                    return;
+                const agentName = payload?.authorAgentName ?? payload?.authorName ?? "Board";
+                const body = payload?.body ?? "";
+                const truncated = body.length > 3500 ? body.slice(0, 3500) + "\n\n[truncated]" : body;
+                await snRequest(ctx, config, "PATCH", `/api/now/table/incident/${originId}`, {
+                    work_notes: `[Paperclip — ${agentName}] ${truncated}`,
+                });
+            });
+        }
+        ctx.logger.info("ServiceNow plugin initialized (outbound events active)");
+    },
+    // =========================================================
+    // INBOUND: SN webhook → create Paperclip issue
+    // =========================================================
+    async onWebhook(input) {
+        if (input.endpointKey !== "servicenow-incident")
+            return;
+        const ctx = _ctx;
+        const config = _config;
+        // Verify webhook secret
+        const providedSecret = Array.isArray(input.headers["x-sn-webhook-secret"])
+            ? input.headers["x-sn-webhook-secret"][0]
+            : input.headers["x-sn-webhook-secret"];
+        const expectedSecret = await ctx.secrets.resolve(config.snWebhookSecretRef);
+        if (providedSecret !== expectedSecret) {
+            ctx.logger.warn("SN webhook rejected: invalid secret");
+            return;
+        }
+        const incident = input.parsedBody;
+        if (!incident?.number || !incident?.sys_id) {
+            ctx.logger.warn("SN webhook missing required fields");
+            return;
+        }
+        // Create Paperclip issue
+        const description = [
+            `## ServiceNow Incident`,
+            ``,
+            `**Number:** ${incident.number}`,
+            `**Priority:** ${incident.priority ?? "unknown"}`,
+            `**Category:** ${incident.category ?? ""}${incident.subcategory ? ` / ${incident.subcategory}` : ""}`,
+            `**Caller:** ${incident.caller_id ?? "unknown"}`,
+            `**Group:** ${incident.assignment_group ?? ""}`,
+            ``,
+            `### Description`,
+            incident.description || "_No description provided_",
+            ``,
+            `---`,
+            `_SN sys_id: ${incident.sys_id}_`,
+        ].join("\n");
+        const issue = await ctx.issues.create({
+            companyId: config.targetCompanyId,
+            title: `[${incident.number}] ${incident.short_description}`,
+            description,
+            status: "todo",
+            priority: PRIORITY_MAP[incident.priority ?? "3"] ?? "medium",
+            assigneeAgentId: config.targetAgentId,
+            projectId: config.targetProjectId,
+        });
+        // Set correlation_id on SN incident
+        await snRequest(ctx, config, "PATCH", `/api/now/table/incident/${incident.sys_id}`, {
+            correlation_id: issue.id ?? "",
+        });
+        ctx.logger.info(`Created issue for ${incident.number}`);
+    },
+    async onHealth() {
+        return { status: "ok" };
+    },
+    async onShutdown() {
+        _config = null;
+        _ctx = null;
+    },
+});
+export default plugin;
+runWorker(plugin, import.meta.url);

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@bettsnation/paperclip-plugin-servicenow",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Paperclip plugin for bidirectional ServiceNow incident sync — webhook intake and auto-resolve",
+  "paperclipPlugin": {
+    "manifest": "./dist/manifest.js",
+    "worker": "./dist/worker.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "@paperclipai/plugin-sdk": ">=0.1.0"
+  },
+  "devDependencies": {
+    "@paperclipai/plugin-sdk": "^2026.403.0",
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0"
+  },
+  "files": [
+    "dist/",
+    "README.md"
+  ],
+  "license": "MIT",
+  "author": "BettsNation",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/bettsnation/paperclip-plugin-servicenow.git"
+  }
+}