Skip to main content

My Integration Failed to Update a Part

This article explains how to troubleshoot issues with a MaintainX integration when it fails to update parts assigned to multiple locations. You'll learn how to update your integration to use the new locations array, reactivate the multi-location parts feature, and prevent MaintainX from deactivating it again if necessary.

Issue​

Your organization includes the multi-location parts feature. You have an integration with MaintainX that updates the parts inventory using one of the following REST API endpoints:

When the integration attempts to update the parts inventory, multi-location parts is temporarily deactivated for your organization. While it's deactivated, users can't add new locations to parts. If a user tries to add a location, they see an error message stating that multi-location parts are temporarily deactivated due to a legacy integration.

Additionally, if the integration attempts to update a part assigned to multiple locations, it fails. The REST API request returns an error message stating that the integration must update the new field.

Cause​

If the integration was created before MaintainX introduced multi-location parts, it's configured to update one or more of the following deprecated fields via the REST API.

If the integration attempts to update the deprecated fields for a part with multiple locations, it will fail. The integration fails because the deprecated fields are designed to handle single-location parts. When a part has multiple locations, these fields can't accommodate the additional data, which causes an error.

To help ensure that your integration continues to work, MaintainX triggers a "safety switch" that temporarily deactivates multi-location parts. This prevents your organization from adding multiple locations to parts until you have a chance to update the integration.

MaintainX recommends that organizations impacted by this issue update their integrations to use the updated REST API fields.

After you update your integration, you can reactivate multi-location parts from the Parts settings.

note

If updating the integration isn't feasible, you can reactivate multi-location parts and bypass the safety switch to keep it on. This approach isn't recommended unless you're certain your integration will only update parts that have one location.

Update Part Endpoint Fields​

The locations array replaces the deprecated fields in the Update part information REST API endpoint. It allows you to specify multiple locations for a part. Each location in the array includes properties such as locationId, availableQuantity, and minimumQuantity.

Here's an example of how to structure an API request payload for the Update part information endpoint using the locations array:

BEFORE:

If your integration uses the deprecated parts fields, your API request payload should look something like this:

{
  "name": "Locknut - 1/8",
  "area": "tool room",
  "unitCost": 120,
  "availableQuantity": 10,
  "minimumQuantity": 5,
  "locationId": 852,
}

AFTER:

When you update your integration to use the multi-location parts fields, your API request payload should look something like this:

{
  "name": "Locknut - 1/8",
  "locations": {
    "addedUpdated": [
      {
        "locationId": 852,
        "availableQuantity": 10,
        "minimumQuantity": 5,
        "area": "tool room"
      }
    ],
    "removedLocationIds": [
      742,
      514
    ]
  }
}
  • The addedUpdated array contains locations to add or update.
  • The removedLocationIds array is optional and contains location IDs to remove.

For more information about the deprecated fields and the new locations array, see Update part information (PATCH) in the REST API Documentation.

Update Purchase Order Endpoint Fields​

The fulfillments array replaces the deprecated fields in the Fulfill purchase order REST API endpoint. It allows you to specify multiple fulfillments for a purchase order. Each location in the array includes properties such as locationId and quantityReceived.

Here's an example of how to structure an API request payload for the Fulfill purchase order endpoint using the fulfillments array:

BEFORE:

If your integration uses the deprecated quantityReceived field in the items array, your API request payload should look something like this:

{
  "items": [
    {
      "id": 23,
      "unitCost": 125000,
      "quantityReceived": 3 
    }
  ]
}

AFTER:

When you update your integration to use the fulfillments array in the items array, your API request payload should look something like this:

{
  "items": [
    {
      "id": 23,
      "unitCost": 125000,
      "fulfillments": [
        {
          "id": 87,
          "locationId": 852,
          "quantityReceived": 3,
          "isLegacy": true
        }
      ]
    }
  ]
}

Each fulfillment in the array contains a locationID that specifies the location the order was fulfilled to, and a new fulfillments[array_of_fulfillments].quantityReceived field that specifies the number of units received at that location.

For more information about the deprecated fields and the new fulfillments array, see Fulfill Purchase Order (PATCH) in the REST API Documentation.

Reactivate Multi-Location Parts​

To reactivate multi-location parts:

  1. From the sidebar, open the Settings menu and in ORGANIZATION SETTINGS, select Features.
  2. On the Features tab, navigate to the Parts Inventory section.
  3. Select Set Preferences. The Parts Inventory settings page opens.
  4. Navigate to the Multi-Location Parts Safety Switch section.
  5. Toggle Multi-Location Parts Status on.

Alternate Solution: Bypass the Multi-Location Parts Safety Switch​

If you're not able to update the integration, you can reactivate multi-location parts and bypass the "safety switch" that deactivates it when your integration uses deprecated API fields.

In that case, MaintainX won't deactivate multi-location parts again, even if your integration fails.

warning

MaintainX advises against this approach unless you're certain that:

  • Parts in your parts inventory will never have more than one location. I.e., your organization has the multi-location parts feature, but doesn't use it.
  • Your integration will only ever update parts that have one location.

To bypass the multi-location parts safety switch:

  1. From the sidebar, open the Settings menu and in ORGANIZATION SETTINGS, select Features.
  2. On the Features tab, navigate to the Parts Inventory section.
  3. Select Set Preferences. The Parts Inventory settings page opens.
  4. Navigate to the Multi-Location Parts Safety Switch section.
  5. Toggle Multi-Location Parts Status on.
  6. The Prevent safety switch from deactivating multi-location parts setting appears. Toggle it on.

The integration will continue to work for parts that have a single location. If the integration attempts to update a part with more than one location, it will fail.

warning

The next time your integration tries to update a deprecated parts field, you'll only receive the error message returned by the REST API.

Troubleshooting Checklist​

  • Check whether your integration uses deprecated fields:

    • For the Update part information endpoint: area, availableQuantity, locationId, minimumQuantity.
    • For the Fulfill purchase order endpoint: quantityReceived in the items array.

  • Update your integration to use the new fields

    • For the Update part information endpoint: the locations array.
    • For the Fulfill purchase order endpoint: the fulfillments array.

  • Reactivate the multi-location parts feature in the Parts Inventory settings.

  • If updating the integration isn't feasible, bypass the safety switch (not recommended).

Get Help From Support​

If you need further assistance, contact MaintainX Support.

When contacting MaintainX Support, make sure to have the following information available:

  • The error message returned by the REST API.
  • Details about your integration (e.g., product you're integrating with, configuration, etc.).
  • Steps to reproduce the issue.
  • The exact API request values the integration sent, i.e., endpoint, parameters, headers, method, etc.