feat(windchill): add update common properties

Name, Number, and Organization are rejected by the PATCH-based update
operation, and the rejection message told users to reach for Windchill's
UpdateCommonProperties action that the integration did not expose. Add it.

PTC documents UpdateCommonProperties as a bound DocMgmt action taking an
Updates wrapper, available when hasCommonProperties is set on the Documents
entity, and refused while the document is checked out. The subblock and param
descriptions carry that constraint, and the rejection message now names the
operation that does the job.

Author: waleedlatif1

apps/docs/content/docs/en/integrations/windchill.mdx

@@ -16,7 +16,7 @@ import { BlockInfoCard } from "@/components/ui/block-info-card"
 This integration talks to Windchill REST Services (WRS) 2.7 over OData — the query protocol Windchill exposes its data through — using a Basic-authenticated service account. Point it at a complete versioned service root — `https://your-host/Windchill/servlet/odata/v6` — and your agents can:
 
 - **Find and read documents**: list documents with an OData filter, sort order, field selection, page size, and a latest-version-only switch; fetch a single document by its object identifier (OID); and walk a document's structure through its usage links to see child documents with their versions and states.
-- **Create and update**: create one document or a batch of them in a container and optional folder, and patch editable attributes on one or many documents. Name, Number, and Organization are deliberately rejected — Windchill requires its own `UpdateCommonProperties` action for those.
+- **Create and update**: create one document or a batch of them in a container and optional folder, and patch editable attributes on one or many documents. Name, Number, and Organization are rejected here and have their own operation, because Windchill changes those through a separate action and refuses it while a document is checked out.
 - **Run the version and lifecycle cycle**: check documents out and back in with notes, undo a checkout, revise to the next revision, read the lifecycle states a document is actually allowed to move to, and transition it to one of them.
 - **Move files**: download a document's primary content, or a specific attachment by its OID, into a Sim file — and upload files as primary content or attachments. Sim handles Windchill's CSRF token and its multi-step upload handshake for you.
 
@@ -347,7 +347,43 @@ Update one document's editable attributes
 | `username` | string | Yes | Windchill service-account username |
 | `password` | string | Yes | Windchill service-account password |
 | `documentOid` | string | Yes | WT.Document OID, for example OR:wt.doc.WTDocument:48796581 |
-| `attributes` | json | Yes | Editable attributes as a JSON object. Name, Number, and Organization require Windchill UpdateCommonProperties and are not supported here. |
+| `attributes` | json | Yes | Editable attributes as a JSON object. Name, Number, and Organization require the Update Common Properties operation and are not supported here. |
+
+#### Output
+
+| Parameter | Type | Description |
+| --------- | ---- | ----------- |
+| `operation` | string | Windchill operation that was executed |
+| `affectedIds` | array | Document identifiers affected by the operation |
+| `document` | object | Document returned by Windchill when the operation returns one |
+|   ↳ `id` | string | Windchill object identifier |
+|   ↳ `name` | string | Document name |
+|   ↳ `number` | string | Document number |
+|   ↳ `title` | string | Document title |
+|   ↳ `description` | string | Document description |
+|   ↳ `state` | string | Internal life cycle state value |
+|   ↳ `stateDisplay` | string | Displayed life cycle state value |
+|   ↳ `versionId` | string | Version identifier |
+|   ↳ `revision` | string | Revision identifier |
+|   ↳ `version` | string | Version and iteration |
+|   ↳ `latest` | boolean | Whether this is the latest version |
+|   ↳ `checkoutState` | string | Checkout state |
+|   ↳ `folderName` | string | Folder name |
+|   ↳ `folderLocation` | string | Folder path |
+
+### Windchill Update Common Properties
+
+Update a document's Name, Number, and other common properties
+
+#### Input
+
+| Parameter | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `baseUrl` | string | Yes | Complete WRS 2.7 versioned service root using Basic authentication, for example https://host/Windchill/servlet/odata/v6 |
+| `username` | string | Yes | Windchill service-account username |
+| `password` | string | Yes | Windchill service-account password |
+| `documentOid` | string | Yes | WT.Document OID, for example OR:wt.doc.WTDocument:48796581. The document must not be checked out. |
+| `commonProperties` | json | Yes | Common properties as a JSON object, for example \{"Name":"New name","Number":"NEW-001"\}. Enumerated properties take a value/display pair. |
 
 #### Output
 

apps/sim/app/api/tools/windchill/route.test.ts

@@ -137,6 +137,12 @@ const MUTATION_CASES = [
     url: '/DocMgmt/UpdateDocuments',
     method: 'POST',
   },
+  {
+    operation: 'windchill_update_common_properties',
+    input: { documentOid: DOCUMENT_OID, commonProperties: { Name: 'Renamed' } },
+    url: '/PTC.DocMgmt.UpdateCommonProperties',
+    method: 'POST',
+  },
   {
     operation: 'windchill_delete_document',
     input: { documentOid: DOCUMENT_OID },
@@ -238,6 +244,14 @@ const MUTATION_PAYLOAD_CASES = [
     input: { documentOid: DOCUMENT_OID, versionId: 'B' },
     body: { VersionId: 'B' },
   },
+  {
+    operation: 'windchill_update_common_properties',
+    input: {
+      documentOid: DOCUMENT_OID,
+      commonProperties: { Name: 'Renamed', Number: 'DOC-001' },
+    },
+    body: { Updates: { Name: 'Renamed', Number: 'DOC-001' } },
+  },
   {
     operation: 'windchill_revise_documents',
     input: { documentOids: [DOCUMENT_OID] },

apps/sim/app/api/tools/windchill/route.ts

@@ -225,6 +225,17 @@ async function executeMutation(
       })
       return mutationOutput(body.operation, data, [body.documentOid])
     }
+    case 'windchill_update_common_properties': {
+      const data = await windchillMutationRequest({
+        params: body,
+        session,
+        url: `${windchillDocumentUrl(root, body.documentOid)}/PTC.DocMgmt.UpdateCommonProperties`,
+        method: 'POST',
+        body: { Updates: body.commonProperties },
+        signal,
+      })
+      return mutationOutput(body.operation, data, [body.documentOid])
+    }
     case 'windchill_update_documents': {
       const data = await windchillMutationRequest({
         params: body,

apps/sim/blocks/blocks/windchill.ts

@@ -12,6 +12,7 @@ const SINGLE_DOCUMENT_OPERATIONS = [
   'windchill_get_primary_content',
   'windchill_list_attachments',
   'windchill_update_document',
+  'windchill_update_common_properties',
   'windchill_delete_document',
   'windchill_check_out_document',
   'windchill_check_in_document',
@@ -46,6 +47,7 @@ const DOWNLOAD_OPERATIONS = ['windchill_download_primary_content', 'windchill_do
 const SINGLE_MUTATION_OPERATIONS = [
   'windchill_create_document',
   'windchill_update_document',
+  'windchill_update_common_properties',
   'windchill_check_out_document',
   'windchill_check_in_document',
   'windchill_undo_check_out_document',
@@ -163,6 +165,9 @@ export const WindchillBlock: BlockConfig<WindchillResponse> = {
           { text: 'Update document', field: 'documentOid', core: true },
           { text: 'with', field: 'attributes' },
         ],
+        windchill_update_common_properties: [
+          { text: 'Update common properties on', field: 'documentOid', core: true },
+        ],
         windchill_update_documents: [{ text: 'Update', field: 'documents', core: true }],
         windchill_delete_document: [{ text: 'Delete document', field: 'documentOid', core: true }],
         windchill_delete_documents: [{ text: 'Delete', field: 'documentOids', core: true }],
@@ -258,6 +263,11 @@ export const WindchillBlock: BlockConfig<WindchillResponse> = {
           id: 'windchill_update_document',
           description: "Update a document's editable attributes",
         },
+        {
+          label: 'Update Common Properties',
+          id: 'windchill_update_common_properties',
+          description: "Update a document's Name, Number, and other common properties",
+        },
         {
           label: 'Update Documents',
           id: 'windchill_update_documents',
@@ -456,7 +466,18 @@ export const WindchillBlock: BlockConfig<WindchillResponse> = {
       },
       required: { field: 'operation', value: 'windchill_update_document' },
       description:
-        'Installed JSON attributes supported by PATCH. Name, Number, and Organization require Windchill UpdateCommonProperties and are rejected here.',
+        'Editable attributes as JSON. Name, Number, and Organization require the Update Common Properties operation and are rejected here.',
+    },
+    {
+      id: 'commonProperties',
+      title: 'Common Properties',
+      type: 'code',
+      language: 'json',
+      placeholder: '{"Name":"Updated name","Number":"DOC-001"}',
+      condition: { field: 'operation', value: 'windchill_update_common_properties' },
+      required: true,
+      description:
+        'Common properties as a JSON object. This is the only operation that can change Name, Number, and Organization, and Windchill rejects it while the document is checked out.',
     },
     {
       id: 'documents',
@@ -713,6 +734,7 @@ export const WindchillBlock: BlockConfig<WindchillResponse> = {
       'windchill_create_document',
       'windchill_create_documents',
       'windchill_update_document',
+      'windchill_update_common_properties',
       'windchill_update_documents',
       'windchill_delete_document',
       'windchill_delete_documents',
@@ -738,6 +760,7 @@ export const WindchillBlock: BlockConfig<WindchillResponse> = {
           operation,
           documents,
           attributes,
+          commonProperties,
           documentOids,
           securityLabelUpdates,
           primaryFile,
@@ -759,6 +782,11 @@ export const WindchillBlock: BlockConfig<WindchillResponse> = {
           ...(attributes === undefined || attributes === ''
             ? {}
             : { attributes: parseJsonField(attributes, 'attributes', 'object') }),
+          ...(commonProperties === undefined || commonProperties === ''
+            ? {}
+            : {
+                commonProperties: parseJsonField(commonProperties, 'commonProperties', 'object'),
+              }),
           ...(documentOids === undefined || documentOids === ''
             ? {}
             : { documentOids: parseJsonField(documentOids, 'documentOids', 'array') }),
@@ -800,6 +828,7 @@ export const WindchillBlock: BlockConfig<WindchillResponse> = {
     containerOid: { type: 'string', description: 'Container OID' },
     folderOid: { type: 'string', description: 'Folder OID' },
     attributes: { type: 'json', description: 'Document attributes' },
+    commonProperties: { type: 'json', description: 'Common document properties' },
     documents: { type: 'array', description: 'Bulk document inputs' },
     checkOutNote: { type: 'string', description: 'Checkout note' },
     checkInNote: { type: 'string', description: 'Check-in note' },

apps/sim/lib/api/contracts/tools/windchill.ts

@@ -130,9 +130,14 @@ const patchAttributesSchema = attributesSchema
   })
   .refine(
     (attributes) => !Object.keys(attributes).some((key) => COMMON_DOCUMENT_PROPERTIES.has(key)),
-    'Name, Number, and Organization must be changed with Windchill UpdateCommonProperties and are not supported by this operation'
+    'Name, Number, and Organization must be changed with the Update Common Properties operation and are not supported here'
   )
 
+const commonPropertiesSchema = attributesSchema.refine(
+  (properties) => Object.keys(properties).length > 0,
+  { message: 'At least one common property is required' }
+)
+
 const credentialsSchema = z.object({
   baseUrl: baseUrlSchema,
   username: credentialSchema,
@@ -183,6 +188,11 @@ const commonMutationShapes = {
     documentOid: oidSchema,
     attributes: patchAttributesSchema,
   }),
+  updateCommonProperties: credentialsSchema.extend({
+    operation: z.literal('windchill_update_common_properties'),
+    documentOid: oidSchema,
+    commonProperties: commonPropertiesSchema,
+  }),
   updateDocuments: credentialsSchema.extend({
     operation: z.literal('windchill_update_documents'),
     documents: z
@@ -298,6 +308,7 @@ export const windchillOperationBodySchema = z.discriminatedUnion('operation', [
   commonMutationShapes.createDocument,
   commonMutationShapes.createDocuments,
   commonMutationShapes.updateDocument,
+  commonMutationShapes.updateCommonProperties,
   commonMutationShapes.updateDocuments,
   commonMutationShapes.deleteDocument,
   commonMutationShapes.deleteDocuments,
@@ -346,6 +357,7 @@ const affectedIdsSchema = z.array(returnedOidSchema)
 const singleMutationOperationSchema = z.enum([
   'windchill_create_document',
   'windchill_update_document',
+  'windchill_update_common_properties',
   'windchill_check_out_document',
   'windchill_check_in_document',
   'windchill_undo_check_out_document',

apps/sim/lib/integrations/integrations.json

@@ -21986,6 +21986,10 @@
           "name": "Update Document",
           "description": "Update one document's editable attributes"
         },
+        {
+          "name": "Update Common Properties",
+          "description": "Update a document's Name, Number, and other common properties"
+        },
         {
           "name": "Update Documents",
           "description": "Update several documents' editable attributes in one atomic request"
@@ -22055,7 +22059,7 @@
           "description": "Upload one or more files as document attachments"
         }
       ],
-      "operationCount": 26,
+      "operationCount": 27,
       "triggers": [],
       "triggerCount": 0,
       "authType": "api-key",

apps/sim/tools/generated/tool-ids.ts

@@ -4790,6 +4790,7 @@ import {
   windchillSetLifecycleStateTool,
   windchillUndoCheckOutDocumentsTool,
   windchillUndoCheckOutDocumentTool,
+  windchillUpdateCommonPropertiesTool,
   windchillUpdateDocumentSecurityLabelsTool,
   windchillUpdateDocumentsTool,
   windchillUpdateDocumentTool,
@@ -8682,6 +8683,7 @@ export const tools: Record<string, ToolConfig> = {
   windchill_set_lifecycle_state: windchillSetLifecycleStateTool,
   windchill_undo_check_out_document: windchillUndoCheckOutDocumentTool,
   windchill_undo_check_out_documents: windchillUndoCheckOutDocumentsTool,
+  windchill_update_common_properties: windchillUpdateCommonPropertiesTool,
   windchill_update_document: windchillUpdateDocumentTool,
   windchill_update_document_security_labels: windchillUpdateDocumentSecurityLabelsTool,
   windchill_update_documents: windchillUpdateDocumentsTool,