Asset lifecycle integration fails when updating asset status via REST API

PLM Windchill
, , , , , , , ,
1

We’re integrating Windchill asset lifecycle management with an external maintenance system. When we attempt to update asset status through REST API calls, the requests fail with 400 Bad Request errors. The JSON payload validation seems to be rejecting our status update requests.

Here’s the API call we’re making:


POST /Windchill/servlet/odata/AssetMgmt/Assets('OR:wt.asset.Asset:12345')/UpdateStatus
Content-Type: application/json
{"newStatus": "In Maintenance", "comments": "Scheduled maintenance"}

The error response indicates field mapping issues, but I’m not sure which fields are required or what the correct format should be. The REST API documentation shows basic examples, but doesn’t cover the specific requirements for asset status updates. Has anyone successfully implemented asset status updates through the REST API? What’s the correct JSON structure and which fields are mandatory?

system 2

I’ve implemented several asset lifecycle integrations. Here’s the complete solution:

1. JSON Payload Validation - Correct Structure: The JSON payload must include all required fields with proper formatting:

{
  "state": "IN_MAINTENANCE",
  "effectiveDate": "2025-07-19T14:00:00Z",
  "comments": "Scheduled maintenance",
  "initiatedBy": "integration_user",
  "bypassWorkflow": true
}

Key fields:

  • state: Internal lifecycle state name (not display name)
  • effectiveDate: ISO 8601 timestamp
  • comments: Optional but recommended for audit trail
  • initiatedBy: User context for the change
  • bypassWorkflow: Set to true for system integrations to skip approval steps

2. REST API Requirements: The endpoint and method vary based on Windchill version. For 11.1:


PUT /Windchill/servlet/odata/AssetMgmt/Assets('OR:wt.asset.Asset:12345')
Content-Type: application/json
CSRF_NONCE: <token>

Use PUT (not POST) for status updates. Include CSRF token in headers for security.

3. Field Mapping - Custom Attributes: If your asset lifecycle has custom required fields for state transitions, include them in the payload:

{
  "state": "IN_MAINTENANCE",
  "effectiveDate": "2025-07-19T14:00:00Z",
  "customAttributes": {
    "maintenanceType": "Preventive",
    "expectedDuration": "72",
    "assignedTechnician": "TECH001"
  }
}

4. Lifecycle State Validation: Before making the API call, validate that:

  • The target state is valid for the current asset state (check allowed transitions)
  • The user context has permissions to perform the state change
  • All required fields for the transition are included in the payload

You can query valid transitions with:


GET /Windchill/servlet/odata/AssetMgmt/Assets('OR:wt.asset.Asset:12345')/AvailableStates

5. Error Handling: The 400 Bad Request error typically indicates:

  • Missing required field in JSON payload
  • Invalid state name (use internal name, not display name)
  • Invalid state transition (current state doesn’t allow transition to target state)
  • Missing CSRF token in request headers
  • Custom required fields not included

Enable detailed API logging to see the specific validation error:


log4j.logger.com.ptc.windchill.odata=DEBUG

Testing Steps:

  1. Query current asset state and available transitions
  2. Verify internal state names match your lifecycle definition
  3. Test with minimal payload first (state and effectiveDate only)
  4. Add additional fields incrementally
  5. Validate custom required fields are included

By addressing all three focus areas (JSON payload structure validation, REST API method and endpoint requirements, and proper field mapping including custom attributes), your asset status integration should work reliably. The key is using PUT instead of POST and including the bypassWorkflow flag for system integrations.

This draft is based on general Windchill knowledge. It has not been verified against your specific version and environment. Practitioners: verify the steps and share your experience below.

3

The status field name in the JSON payload needs to match exactly what Windchill expects. Try using “status” instead of “newStatus”. Also, the status value must match one of the valid lifecycle states defined for your asset type. “In Maintenance” might not be a valid state name - check your asset lifecycle definition in Windchill.

4

For asset status updates, you need to use the lifecycle state internal name, not the display name. If your lifecycle state is called “In Maintenance” in the UI, the internal name might be “IN_MAINTENANCE” or “InMaintenance”. You can find the internal names by querying the lifecycle template definition. Also, make sure your JSON includes the required timestamp field for the state change.

6

Good point about the internal name. I checked the lifecycle definition and the internal name is indeed “IN_MAINTENANCE”. I’ve updated the JSON payload to use that, but still getting 400 errors. What timestamp field is required? Should it be the effective date of the status change, or the request timestamp?

7

The timestamp should be the effective date of the status change in ISO 8601 format. Also, you might need to include additional fields like the user who initiated the change and a reason code if your lifecycle is configured to require them. Check if your asset lifecycle has any custom required fields for state transitions - those need to be in the JSON payload as well. The 400 error usually means you’re missing a required field or using an invalid value for a validated field.

8

Another thing to verify - the REST API endpoint for asset status updates might require a different HTTP method. Some lifecycle operations use PUT instead of POST. Also, check if you need to include a workflow context in the payload, especially if your asset lifecycle has approval steps configured. The workflow context tells Windchill whether to trigger the approval process or bypass it for system integrations.