API for Assets

Overview

The Assets APIs provides endpoints for managing assets categories, assets groups, assets tasks and sign off tasks within the MXSuite system. This API allows you to retrieve assets categories, assets groups and task sign offs, to create, update, delete and retrive assets tasks with proper authorization controls.

Last updated for MXSuite version 3.5.0

Base URL

• api/external/AssetsCategories/
• api/external/AssetsGroups/
• api/external/AssetsTasks/
• api/external/AssetsTaskSignOffs/

1. Assets Categories

Overview

Authentication

1. Get categories

Endpoint

[
  {
    "id": "b1a2c3d4-e5f6-7890-abcd-1234567890ab",
    "uniqueId": "CAT-001",
    "name": "Engine Room",
    "parentId": "c2b3a4d5-e6f7-8901-bcda-2345678901bc",
    "displayIndex": 1
  }
]

<binary data>

{
    "Comments": "When the parts are red colored in the inventory means that the stock of this part is to low and need to order.",
    "RatingPriority": 5.6,
    "DefaultCounter": "Deck"
    "IsCritical": true,
    "IsOperationalCritical": false,
    "Documents" :[
      {
        "Id": "a2934fa2-6f7e-4ac9-8210-681814ac86c4",
        "Name":"Paint specs",
        "Size":"5.2MB"
      },
      {
        "Id": "20380a36-8777-43f7-a79e-65bdb53f4621"
        "Name": "Inspection form"
        "Size": "547.45KB"
      }  
    ]
    "Properties" :[
      {
        "Name": "In use",
        "Value": "true"
      },
      {
        "Name": "Price"
        "Value": "24.45$"
      }  
    ]
}

2. Assets Groups

Authentication

Endpoints

1. Get groups

Endpoint

GET /api/external/AssetsGroups/Get?categoryId=b1a2c3d4-e5f6-7890-abcd-1234567890ab

Request

Query parameter:
•  categoryId=b1a2c3d4-e5f6-7890-abcd-1234567890ab

Response

[
  {
    "id": "d3e4f5a6-b7c8-9012-cdab-3456789012cd",
    "type": 1,
    "uniqueId": "GRP-001",
    "name": "Auxiliary Systems",
    "displayIndex":1
  }
]

Validations

• CategoryId: Required, valid GUID

Authentication

Endpoints

1. Create Maintenance Task

• User must have AddMaintenanceTask rights

Validations

• GroupId: identifies the group together with GroupType. Both are required
  
• UniqueId: Max length 50. Not required, but should be unique if provided.
• TaskName: Required, max length 128, must be unique.
• Interval: Must be greater than 0, within limits based on IntervalType.
• IntervalType, MaxIntervalType or WarningIntervalType: should contain one of these values:
  • • 1 = days
    • 2 = weeks
    • 3 = months
• DueDate: Must be between 01/01/1900 and 01/01/2100.
• TaskDescription: Required depending on how it is set in Administration > Assets > Tasks > Settings
  

  

  
  
• Ranks: Required for tasks requiring approval.
• RequiresApproval: Must be false for Silver licenses.
  
• ApproverRanks: Required only if RequiresApproval is set to true.
• Currency: when provided, it should contain the currency name as seen in Administration > Currencies

  

• When a rank is provided (e.g.: Ranks or ApproverRanks), the name from Administration > Ranks should be used:

  

• CounterName: required when IsCounterBased is set to true. The values provided should be the ones defined in Symmary > Counters
• WarningInterval + WarningIntervalType: required when IsCounterBased is set to true.

Errors

• 409 Conflict
• 404 Not Found: Task not found.
• 412 Precondition failed: Exceeding limits for intervals
• 403 Forbidden 
• 400 Bad Request: Validation errors and required fields

Response

{
  "TaskId": "1463aea5-9062-45bf-8b9c-24cc5615d467"
}

Fields details

• General task details
  

  

  
  

• Counter based tasks:

  

• Approver ranks:

  

Endpoint

Authorization Required

{
  "UniqueId": "Task-001",
  "TaskName": "Oil Change - Updated",
  "TaskId": "1463aea5-9062-45bf-8b9c-24cc5615d467",
  "GroupId":"3C160DF1-3A5C-406F-BAC6-00A4AB8C44A9",
  "GroupType":1,
  "Interval": 45,
  "IntervalType": 1,
  "DueDate": "2025-06-01T00:00:00Z",
  "IsCounterBased": false,
  "IsRemarkMandatory": true,
  "IsProject": false,
  "IsRecurrent": true,
  "IsFixedInterval": true,
  "IsAtServiceRequest": false,
  "IsDefect": false,
  "TaskDescription": "Updated description for oil change.",
  "MaxInterval": 90,
  "MaxIntervalType": 2,
  "DueCounters": 150,
  "Downtime": 3.0,
  "WarningInterval": 10,
  "WarningIntervalType": 1,
  "CounterName": "Main Engine",
  "DefaultEstimatedBudget": {
    "Amount": 600.0,
    "Currency":  "EURO"
  },
  "Ranks": ["Rank1", "Rank2"],
  "ApproverRanks": ["Approver1"],
  "RequiresApproval": true
}

Validations

• taskId: Required, must be a valid GUID.

Errors

• 404 Not Found: Task not found.
• 500 Internal Server Error: Unexpected errors.

[
    "1463aea5-9062-45bf-8b9c-24cc5615d467",
    "7b95cb8b-0cb8-4cdf-ad3e-3285a162cbea"
]

Authorization Required

{
  "GroupId": "d3e4f5a6-b7c8-9012-cdab-3456789012cd",
  "GroupType": 1
}

[
  "e4f5a6b7-c8d9-0123-dabc-4567890123de",
  "f5a6b7c8-d9e0-1234-abcd-5678901234ef"
]

{
  "TaskId": "7b95cb8b-0cb8-4cdf-ad3e-3285a162cbea",
  "NumberOfSignOffs": 5
}

{
  "Errors": [
    {
      "message": "string",
      "errorCode": number,
      "isBusinessException": false,
      "businessExceptionData": null,
      "failureServerReason": null
    }
  ]
}

{
    "errors": [
        {
            "message": "Category name is required",
            "errorCode": 9,
            "isBusinessException": false,
            "businessExceptionData": null,
            "failureServerReason": null
        }
    ]
}

Status: 409 Conflict