fix(windchill): correct OData query encoding, content download, and cleared-field handling

Validated the integration end to end against PTC Windchill REST Services 2.7
documentation and fixed every divergence found.

Protocol correctness:
- Encode OData query spaces as %20 rather than the form-encoded `+` that
  URLSearchParams emits. Every multi-token $filter and $orderby reached
  Windchill as a literal `+` and could not match.
- Download content through the documented typed navigation
  `<content>/PTC.ApplicationData/Content/URL`, which returns a signed vault
  URL, instead of a `$value` segment that WRS does not implement. The
  resolved URL is pinned to the configured HTTPS origin.
- Terminate every Stage 2 CacheDescriptor_array entry with `;` to match the
  documented grammar.
- Raise the $top bound to Windchill's documented 2000 maximum, keeping 200 as
  the default page size.

Cleared-field handling:
- The executor merges raw block inputs before the block's param transform, so
  omitting a key could not clear it. A cleared numeric or boolean field
  reached the URL builder as '' and threw, and cleared optional strings failed
  contract validation. Coercions now emit an explicit undefined, and the
  internal-route body strips blanks centrally.

Robustness and contracts:
- Bound the document-structure walk to the depth actually requested.
- Loosen response schemas that re-applied request-side bounds to
  provider-returned values, which turned committed mutations into opaque
  parse failures.
- Return contract-shaped bodies for oversized, malformed, and unhandled
  request failures.
- Normalize downloaded content types and drop charset parameters.

Presentation and docs:
- Square the icon to a centred tile on white.
- Replace WT.Document and PATCH-compatible jargon with plain language.
- Fix canvas sentence noun stutters on the bulk operations.
- Correct the revision skill's unverified working-copy claim to read the OID
  back rather than assume it, and add retirement and stale-checkout skills.
- Add a manual intro section to the integration docs page.

Author: waleedlatif1

apps/docs/components/icons.tsx

@@ -2497,12 +2497,13 @@ export function DocumentIcon(props: SVGProps<SVGSVGElement>) {
 export function WindchillIcon(props: SVGProps<SVGSVGElement>) {
   return (
     <svg
-      {...props}
-      viewBox='87.3 60.2 71.1 82'
+      viewBox='79 57 88 88'
       role='img'
       aria-label='Windchill icon'
       xmlns='http://www.w3.org/2000/svg'
+      {...props}
     >
+      <rect x='79' y='57' width='88' height='88' fill='#FFFFFF' />
       <g fill='#3D4647'>
         <polygon points='137.2,86.6 137.2,68.5 122.8,60.2 107.1,69.2' />
         <polygon points='142.7,106.4 158.4,97.3 158.4,80.7 142.7,71.6' />

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

@@ -1,18 +1,34 @@
 ---
 title: Windchill
-description: Manage WT.Document objects and content in PTC Windchill
+description: Manage documents, revisions, and content in PTC Windchill
 ---
 
 import { BlockInfoCard } from "@/components/ui/block-info-card"
 
-<BlockInfoCard
+<BlockInfoCard 
   type="windchill"
   color="#FFFFFF"
 />
 
+{/* MANUAL-CONTENT-START:intro */}
+[PTC Windchill](https://www.ptc.com/en/products/windchill) is the product lifecycle management system manufacturers use as the system of record for engineering data. Documents in Windchill are controlled objects: each one carries a number, a revision and iteration, a lifecycle state, folder placement, security labels, and a checkout status that decides who is allowed to change it right now.
+
+This integration talks to Windchill REST Services (WRS) 2.7 over its OData API 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 installed attributes on one or many documents. Name, Number, and Organization are deliberately rejected — Windchill requires its own `UpdateCommonProperties` action for those.
+- **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 named attachment into a Sim file, and upload files as primary content or attachments through Windchill's three-stage vault upload.
+
+Bulk actions are atomic on Windchill's side: if the action fails for any object in the batch, the whole operation rolls back and nothing changes. Every write first fetches a CSRF nonce and replays it, matching what WRS requires of any REST client.
+
+Two limits are worth knowing before you build. Windchill identifies everything by OID (`OR:wt.doc.WTDocument:48796581`), so most operations need an OID you got from a list or get call rather than a document number. And this integration supports Basic authentication only — Windchill deployments fronted by OAuth are not currently supported.
+{/* MANUAL-CONTENT-END */}
+
+
 ## Usage Instructions
 
-Integrate PTC Windchill REST Services 2.7 document management into your workflow using Basic authentication. Read and update WT.Document metadata, perform version and lifecycle actions, and transfer primary content and attachments. Windchill OAuth deployments are not currently supported.
+Integrate PTC Windchill REST Services 2.7 document management into your workflow using Basic authentication. Read and update document metadata, perform version and lifecycle actions, and transfer primary content and attachments. Windchill OAuth deployments are not currently supported.
 
 
 
@@ -295,7 +311,7 @@ Create multiple WT.Document objects atomically
 | `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 |
-| `documents` | json | Yes | Document inputs as a JSON array; each item requires name and containerOid |
+| `documents` | array | Yes | Document inputs as a JSON array; each item requires name and containerOid |
 
 #### Output
 
@@ -366,7 +382,7 @@ Update PATCH-compatible attributes on multiple documents atomically
 | `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 |
-| `documents` | json | Yes | Document updates as a JSON array; each item requires id and bounded PATCH-compatible attributes. Name, Number, and Organization are not supported. |
+| `documents` | array | Yes | Document updates as a JSON array; each item requires id and bounded PATCH-compatible attributes. Name, Number, and Organization are not supported. |
 
 #### Output
 
@@ -767,7 +783,7 @@ Update installed security-label attributes for one or more documents
 | `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 |
-| `securityLabelUpdates` | json | Yes | Array of document IDs and installed security-label values |
+| `securityLabelUpdates` | array | Yes | Array of document IDs and installed security-label values |
 
 #### Output
 
@@ -816,7 +832,7 @@ Download primary content into a canonical UserFile
 
 ### Windchill Upload Primary Content
 
-Upload or replace a document primary-content file
+Upload a primary-content file to a document that has none
 
 #### Input
 
@@ -835,6 +851,7 @@ Upload or replace a document primary-content file
 | `operation` | string | Windchill operation that was executed |
 | `affectedIds` | array | Document identifiers affected by the upload |
 | `uploadedFileNames` | array | Names of files accepted by Windchill |
+
 ### Windchill Download Attachment
 
 Download a document attachment into a canonical UserFile
@@ -880,3 +897,5 @@ Upload one or more files as document attachments
 | `operation` | string | Windchill operation that was executed |
 | `affectedIds` | array | Document identifiers affected by the upload |
 | `uploadedFileNames` | array | Names of files accepted by Windchill |
+
+

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

@@ -16,6 +16,7 @@ const {
   mockDownloadServableFileFromStorage,
   mockDownloadWindchillContent,
   mockGetSession,
+  mockResolveWindchillContentUrl,
   mockProcessFilesToUserFiles,
   mockUploadCopilotFile,
   mockUploadExecutionFile,
@@ -42,6 +43,7 @@ const {
     mockDownloadServableFileFromStorage: vi.fn(),
     mockDownloadWindchillContent: vi.fn(),
     mockGetSession: vi.fn(),
+    mockResolveWindchillContentUrl: vi.fn(),
     mockProcessFilesToUserFiles: vi.fn(),
     mockUploadCopilotFile: vi.fn(),
     mockUploadExecutionFile: vi.fn(),
@@ -78,6 +80,7 @@ vi.mock('@/lib/uploads/contexts/execution', () => ({
 vi.mock('@/tools/windchill/utils.server', () => ({
   createWindchillSession: mockCreateWindchillSession,
   downloadWindchillContent: mockDownloadWindchillContent,
+  resolveWindchillContentUrl: mockResolveWindchillContentUrl,
   sanitizeWindchillError: (message: string) => message.replace(/https?:\/\/\S+/g, '[redacted URL]'),
   uploadWindchillContent: mockUploadWindchillContent,
   windchillDocumentUrl: (baseUrl: string, documentOid: string) =>
@@ -302,6 +305,10 @@ beforeEach(() => {
     contentType: 'application/pdf',
   })
   mockUploadWindchillContent.mockResolvedValue(['specification.pdf'])
+  mockResolveWindchillContentUrl.mockImplementation(
+    async ({ contentPath }: { contentPath: string }) =>
+      `https://windchill.example.com/Windchill/servlet/WindchillGW/download?from=${encodeURIComponent(contentPath)}`
+  )
   mockDownloadWindchillContent.mockResolvedValue({
     buffer: Buffer.from('pdf'),
     contentType: 'application/pdf',
@@ -694,9 +701,15 @@ describe('POST /api/tools/windchill', () => {
     const data = await response.json()
 
     expect(response.status).toBe(200)
+    expect(mockResolveWindchillContentUrl).toHaveBeenCalledWith(
+      expect.objectContaining({
+        contentPath: expect.stringContaining('/PrimaryContent'),
+      })
+    )
+    expect(mockResolveWindchillContentUrl.mock.calls[0][0].contentPath).not.toContain('$value')
     expect(mockDownloadWindchillContent).toHaveBeenCalledWith(
       expect.objectContaining({
-        url: expect.stringContaining('/PrimaryContent/$value'),
+        url: expect.stringContaining('/WindchillGW/download'),
       })
     )
     expect(mockUploadCopilotFile).toHaveBeenCalledWith(
@@ -722,9 +735,14 @@ describe('POST /api/tools/windchill', () => {
     )
 
     expect(response.status).toBe(200)
+    expect(mockResolveWindchillContentUrl).toHaveBeenCalledWith(
+      expect.objectContaining({
+        contentPath: expect.stringContaining("/Attachments('OR%3Awt.content.ApplicationData%3A2')"),
+      })
+    )
     expect(mockDownloadWindchillContent).toHaveBeenCalledWith(
       expect.objectContaining({
-        url: expect.stringContaining("/Attachments('OR%3Awt.content.ApplicationData%3A2')/$value"),
+        url: expect.stringContaining('/WindchillGW/download'),
       })
     )
   })

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

@@ -35,6 +35,7 @@ import {
 import {
   createWindchillSession,
   downloadWindchillContent,
+  resolveWindchillContentUrl,
   uploadWindchillContent,
   WindchillProviderError,
   type WindchillUploadFile,
@@ -116,8 +117,12 @@ function documentsById(documentOids: string[]) {
   return documentOids.map((ID) => ({ ID }))
 }
 
+/** Keeps the media type and drops any `; charset=...` parameters Windchill cannot use. */
 function safeMimeType(value: string | undefined): string {
-  if (value && /^[A-Za-z0-9!#$&^_.+-]+\/[A-Za-z0-9!#$&^_.+-]+$/.test(value)) return value
+  const mediaType = value?.split(';', 1)[0]?.trim()
+  if (mediaType && /^[A-Za-z0-9!#$&^_.+-]+\/[A-Za-z0-9!#$&^_.+-]+$/.test(mediaType)) {
+    return mediaType
+  }
   return 'application/octet-stream'
 }
 
@@ -506,10 +511,15 @@ async function executeDownload(
   signal: AbortSignal
 ): Promise<WindchillRouteOutput> {
   const documentUrl = windchillDocumentUrl(body.baseUrl, body.documentOid)
-  const contentUrl =
+  const contentPath =
     body.operation === 'windchill_download_primary_content'
-      ? `${documentUrl}/PrimaryContent/$value`
-      : `${documentUrl}/Attachments('${encodeWindchillOid(body.attachmentOid)}')/$value`
+      ? `${documentUrl}/PrimaryContent`
+      : `${documentUrl}/Attachments('${encodeWindchillOid(body.attachmentOid)}')`
+  const contentUrl = await resolveWindchillContentUrl({
+    params: body,
+    contentPath,
+    signal,
+  })
   const downloaded = await downloadWindchillContent({
     params: body,
     url: contentUrl,
@@ -523,89 +533,98 @@ async function executeDownload(
   const fileName = sanitizeFileName(
     body.fileName || contentDispositionFileName(downloaded.contentDisposition) || fallback
   )
+  const mimeType = safeMimeType(downloaded.contentType)
   const file = await storeDownloadedFile({
     principal,
     buffer: downloaded.buffer,
     fileName,
-    contentType: downloaded.contentType,
+    contentType: mimeType,
   })
   return {
     operation: body.operation,
     file: { ...file },
     fileName,
-    mimeType: downloaded.contentType,
+    mimeType,
   }
 }
 
-export const POST = withRouteHandler(async (request: NextRequest) => {
-  const requestId = generateRequestId()
-  let principal: WorkflowExecutionDelegatedPrincipal
-  try {
-    principal = await authenticateWindchillExecutor(request)
-  } catch (error) {
-    if (error instanceof InternalUnauthenticatedError) {
-      return failureResponse(error.message, 401)
+export const POST = withRouteHandler(
+  async (request: NextRequest) => {
+    const requestId = generateRequestId()
+    let principal: WorkflowExecutionDelegatedPrincipal
+    try {
+      principal = await authenticateWindchillExecutor(request)
+    } catch (error) {
+      if (error instanceof InternalUnauthenticatedError) {
+        return failureResponse(error.message, 401)
+      }
+      throw error
     }
-    throw error
-  }
 
-  const parsed = await parseRequest(
-    windchillOperationContract,
-    request,
-    {},
-    {
-      validationErrorResponse: (error) =>
-        failureResponse(getValidationErrorMessage(error, 'Invalid Windchill request'), 400),
-    }
-  )
-  if (!parsed.success) return parsed.response
-  const body = parsed.data.body
+    const parsed = await parseRequest(
+      windchillOperationContract,
+      request,
+      {},
+      {
+        validationErrorResponse: (error) =>
+          failureResponse(getValidationErrorMessage(error, 'Invalid Windchill request'), 400),
+        invalidJsonResponse: () =>
+          failureResponse('Windchill request body must be valid JSON', 400),
+        payloadTooLargeResponse: () => failureResponse('Windchill request body is too large', 413),
+      }
+    )
+    if (!parsed.success) return parsed.response
+    const body = parsed.data.body
 
-  try {
-    if (
-      body.operation === 'windchill_download_primary_content' ||
-      body.operation === 'windchill_download_attachment'
-    ) {
-      return successResponse(await executeDownload(body, principal, request.signal))
-    }
+    try {
+      if (
+        body.operation === 'windchill_download_primary_content' ||
+        body.operation === 'windchill_download_attachment'
+      ) {
+        return successResponse(await executeDownload(body, principal, request.signal))
+      }
 
-    if (
-      body.operation === 'windchill_upload_primary_content' ||
-      body.operation === 'windchill_upload_attachments'
-    ) {
-      const inputs =
-        body.operation === 'windchill_upload_primary_content'
-          ? [body.primaryFile]
-          : body.attachmentFiles
-      const files = await loadUploadFiles(inputs, principal.subjectUserId, requestId)
-      if (files instanceof NextResponse) return files
-      const uploadedFileNames = await uploadWindchillContent({
-        params: body,
-        documentOid: body.documentOid,
-        files,
-        primaryContent: body.operation === 'windchill_upload_primary_content',
-        signal: request.signal,
-      })
-      return successResponse({
+      if (
+        body.operation === 'windchill_upload_primary_content' ||
+        body.operation === 'windchill_upload_attachments'
+      ) {
+        const inputs =
+          body.operation === 'windchill_upload_primary_content'
+            ? [body.primaryFile]
+            : body.attachmentFiles
+        const files = await loadUploadFiles(inputs, principal.subjectUserId, requestId)
+        if (files instanceof NextResponse) return files
+        const uploadedFileNames = await uploadWindchillContent({
+          params: body,
+          documentOid: body.documentOid,
+          files,
+          primaryContent: body.operation === 'windchill_upload_primary_content',
+          signal: request.signal,
+        })
+        return successResponse({
+          operation: body.operation,
+          affectedIds: [body.documentOid],
+          uploadedFileNames,
+        })
+      }
+
+      return successResponse(await executeMutation(body, request.signal))
+    } catch (error) {
+      logger.error('Windchill operation failed', {
         operation: body.operation,
-        affectedIds: [body.documentOid],
-        uploadedFileNames,
+        error: sanitizeWindchillError(getErrorMessage(error, 'Windchill operation failed')),
       })
+      if (error instanceof WindchillProviderError) {
+        const status = error.status >= 400 && error.status <= 599 ? error.status : 502
+        return failureResponse(error.message, status)
+      }
+      return failureResponse(
+        getErrorMessage(error, 'Windchill operation failed'),
+        isPayloadSizeLimitError(error) ? 413 : 500
+      )
     }
-
-    return successResponse(await executeMutation(body, request.signal))
-  } catch (error) {
-    logger.error('Windchill operation failed', {
-      operation: body.operation,
-      error: sanitizeWindchillError(getErrorMessage(error, 'Windchill operation failed')),
-    })
-    if (error instanceof WindchillProviderError) {
-      const status = error.status >= 400 && error.status <= 599 ? error.status : 502
-      return failureResponse(error.message, status)
-    }
-    return failureResponse(
-      getErrorMessage(error, 'Windchill operation failed'),
-      isPayloadSizeLimitError(error) ? 413 : 500
-    )
+  },
+  {
+    unhandledErrorResponse: () => failureResponse('Windchill operation failed', 500),
   }
-})
+)