CAD file check-in via REST API fails with invalid metadata error in CAD integration module

PLM Windchill
, , , , , , , ,
1

Our automated CAD check-in process using Windchill 11.1 M030 REST API is failing with “invalid metadata” errors. The check-in works perfectly through Creo View and Workgroup Manager, but our REST API integration consistently rejects the same files.

Error response from API:


400 Bad Request
{"error": "Invalid metadata: required field missing",
 "field": "CADDocumentMaster"}

We’re sending CAD files (STEP format) with basic metadata - name, number, folder location. The API payload validation seems stricter than the UI workflow. What are the required metadata fields for CAD check-in via REST API? The documentation doesn’t clearly specify which fields are mandatory versus optional for the CAD integration process.

2

Beyond the required fields, verify your API user has appropriate CAD integration permissions. The REST API enforces stricter access control than UI workflows. Your service account needs ‘Create CAD Document’ privilege and access to the target product/library context. Also check if your Windchill instance has CAD integration enabled for REST API endpoints - some organizations disable this for security reasons. Review your methodserver logs for more detailed error information about which specific validation is failing.

3

Don’t forget about the file format registry. STEP files need to be registered in Windchill’s format mapping configuration. Even if you provide correct metadata, the API will reject files with unrecognized formats. Check Site > Utilities > Preference Management > File Format Mapping to ensure STEP is properly configured with appropriate viewer and application associations. This is separate from the metadata validation but causes similar error messages.

4

Thanks for the insights. I’ve added CADType and AuthoringApplication fields, but still getting validation errors. Is there a way to see the complete required schema for CAD document creation via REST API? Trial and error is proving inefficient.

5

I’ve dealt with this exact issue. The problem is that REST API payload validation is more explicit than UI-based check-ins. When you check in through Creo or Workgroup Manager, those clients automatically populate CAD-specific attributes. With REST API, you must manually include: CADName, CADType, AuthoringApplication, ApplicationVersion, and FileFormat. Also ensure your content type header is set correctly for multipart/form-data when uploading the file binary along with JSON metadata.

6

Use the REST API’s metadata discovery endpoint: GET /Windchill/servlet/odata/v6/$metadata. This returns the complete OData schema including all entity types and their required properties. Look for the CADDocument entity definition - it lists all mandatory fields with their data types and constraints. You can also use OPTIONS request on the CADDocuments endpoint to see allowed operations and field requirements. This is much more reliable than documentation which often lags behind actual implementation.

7

Here’s the complete solution for CAD file check-in via REST API, addressing all three focus areas:

Required Metadata Fields: The REST API requires explicit CAD-specific fields that UI workflows populate automatically. Your payload must include:

{
  "Name": "Assembly_001",
  "Number": "CAD-12345",
  "CADName": "Assembly_001.stp",
  "CADType": "STEP",
  "AuthoringApplication": "Creo",
  "ApplicationVersion": "7.0"
}

API Payload Validation Requirements:

  1. CAD Document Structure: Create the CAD document with proper type specification:

    • Use @odata.type: "PTC.CADDocument" in your JSON payload
    • Include both standard WTPart fields (Name, Number) and CAD-specific fields
    • Link to appropriate CADDocumentMaster if updating existing document

  2. File Upload Process: Use multipart/form-data for combined metadata and file upload:

    • Part 1: JSON metadata with Content-Type: application/json
    • Part 2: Binary file content with Content-Type: application/octet-stream
    • Set proper Content-Disposition headers for each part

  3. Format Registration: Verify STEP format is registered in Windchill:

    • Navigate to Site > Utilities > Preference Management
    • Check File Format Mapping for STEP extension
    • Ensure format has viewer association (Creo View)
    • Confirm application mapping to appropriate CAD system

CAD Integration Process Best Practices:

  1. Folder Context: Specify target folder using full path or OID reference. CAD documents require valid Product or Library context - root folder assignments will fail validation.

  2. Lifecycle State: Include initial lifecycle state in payload. Default state assignment may not work for CAD documents depending on your lifecycle configuration.

  3. Permissions: Ensure API service account has:

    • Create CAD Document permission in target context
    • Appropriate role (minimum: Contributor) in the product/library
    • Access to CAD integration features (check license entitlements)

  4. Validation Sequence: The API validates in this order:

    • Authentication and authorization
    • Required field presence and data types
    • CAD-specific field validation (format, application compatibility)
    • File format registry lookup
    • Context and permission checks
    • Business rule validation

Common Validation Failures:

  • Missing CADDocumentMaster: When updating existing documents, include master reference
  • Invalid CADType: Must match registered format identifiers (case-sensitive)
  • AuthoringApplication mismatch: Must align with configured CAD systems
  • Format not registered: File extension must exist in format mapping table

Debugging Approach:

  1. Enable detailed REST API logging in methodserver logs
  2. Use $metadata endpoint to verify exact schema requirements
  3. Test with minimal payload first, add fields incrementally
  4. Compare successful UI check-in logs with API attempts
  5. Verify file format registration before attempting upload

Working Payload Example: Successful STEP file check-in requires this complete structure with all mandatory CAD integration fields properly populated. Test with this template and adjust based on your specific Windchill configuration and CAD system setup.

This comprehensive approach addresses required metadata fields through explicit specification, handles API payload validation via proper structure and format registration, and integrates with the CAD integration process by following Windchill’s validation sequence and permission model.

8

The REST API requires explicit CAD-specific metadata that the UI workflows handle automatically. You need to include CADDocumentMaster reference, CAD system identifier, and application format. These fields establish the CAD integration linkage. Check your payload structure - it should include a nested CADDocument object with these properties. The error indicates you’re missing the master reference that links the CAD file to Windchill’s CAD data model.