#### Base URL api/external/AssetsTasks/

#### Authentication

All endpoints require authentication and appropriate user rights. The API uses token-based authentication through the MXApiPolicyAuthorize attribute.

### Endpoints

#### 1. Create Maintenance Task

Creates a new maintenance task in the system.

##### Endpoint

POST api/external/AssetsTasks/Create

##### Authorization Required:

- 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 [![image.png](https://docs.mxsuite.nl/uploads/images/gallery/2025-07/scaled-1680-/NP5image.png)](https://docs.mxsuite.nl/uploads/images/gallery/2025-07/NP5image.png) - **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 [![image.png](https://docs.mxsuite.nl/uploads/images/gallery/2025-07/scaled-1680-/dReimage.png)](https://docs.mxsuite.nl/uploads/images/gallery/2025-07/dReimage.png) - When a **rank** is provided (e.g.: **Ranks** or **ApproverRanks**), the name from Administration > Ranks should be used: [![image.png](https://docs.mxsuite.nl/uploads/images/gallery/2025-07/scaled-1680-/FFbimage.png)](https://docs.mxsuite.nl/uploads/images/gallery/2025-07/FFbimage.png) - **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 ```json { "TaskId": "1463aea5-9062-45bf-8b9c-24cc5615d467" } ``` ##### Fields details: - General task details [![image.png](https://docs.mxsuite.nl/uploads/images/gallery/2025-07/scaled-1680-/image.png)](https://docs.mxsuite.nl/uploads/images/gallery/2025-07/image.png) - Counter based tasks: [![image.png](https://docs.mxsuite.nl/uploads/images/gallery/2025-07/scaled-1680-/MOPimage.png)](https://docs.mxsuite.nl/uploads/images/gallery/2025-07/MOPimage.png) - Approver ranks: [![image.png](https://docs.mxsuite.nl/uploads/images/gallery/2025-07/scaled-1680-/ZJximage.png)](https://docs.mxsuite.nl/uploads/images/gallery/2025-07/ZJximage.png)

#### 2. Update Maintenance Task

Updates an existing maintenance task.

##### Endpoint

PUT api/external/AssetsTasks/Update

##### Authorization Required

- User must have EditMaintenanceTask rights ```json { "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 Same as the **Create** action. ##### 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

#### 3. Delete Maintenance Task

Description: Deletes a maintenance task.

- **HTTP Method**: DELETE - There can be to types of request bodies, please see examples below

##### Authorization Required

- User must have Delete Maintenance Task rights **Request body for URL /api/external/AssetsTasks/delete?taskId={taskId}**

Response

• Status Code: 204 No Content • Body: Empty response on success.

##### Validations **• taskId:** Required, must be a valid GUID. ##### Errors • 404 Not Found: Task not found. • 500 Internal Server Error: Unexpected errors.

#### 4. Get ##### Endpoint /api/external/AssetsTasks/Get**?taskId={taskId}** ##### Validations • taskId: Required, must be a valid GUID. #### 5. Get Multiple Tasks ##### Endpoint /api/external/AssetsTasks/GetTasks ##### Request JSON ```json [ "1463aea5-9062-45bf-8b9c-24cc5615d467", "7b95cb8b-0cb8-4cdf-ad3e-3285a162cbea" ] ``` ##### Validations • taskIds: Required, must be a list of valid GUIDs. #### 6. Get Tasks Ids Retrieves the IDs of maintenance task/s.

• HTTP Method: GET • URL: /api/external/AssetsTasks/GetTasksIds

##### Authorization Required

- Location must not be read-only

##### Request body

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

Response

• Status Code: 200 OK

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

Validations

• **GroupId**: Must be GUID• **GroupType**: Must be a positive number.

Errors

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

### 4. Assets Task Sign Offs #### Overview

The Assets Task Sign Offs API provides endpoints for managing task sign offs within the MXSuite system. This API allows you to retrieve task sign offs with proper authorization controls.

#### Base URL api/external/AssetsTaskSignOffs/

#### Authentication

All endpoints require authentication and appropriate user rights. The API uses token-based authentication through the MXApiPolicyAuthorize attribute.

### Endpoints #### 1. Get Sign-Offs

Endpoint

/api/external/AssetsTaskSignOffs/Get

**Request JSON:**

```json { "TaskId": "7b95cb8b-0cb8-4cdf-ad3e-3285a162cbea", "NumberOfSignOffs": 5 } ``` ##### Validations • TaskId: Required, must be a valid GUID. • NumberOfSignOffs: Optional, must be a valid number.

Authorization

• Ensure the user has the required rights (UserRights) for each endpoint (Add task, edit task, delete task ) • The LocationIsNotReadOnly flag must be true for all operations.

### Error Responses All error responses follow this structure: ```json { "Errors": [ { "message": "string", "errorCode": number, "isBusinessException": false, "businessExceptionData": null, "failureServerReason": null } ] } ``` ```json { "errors": [ { "message": "Category name is required", "errorCode": 9, "isBusinessException": false, "businessExceptionData": null, "failureServerReason": null } ] } ```

The API may return the following error responses:

1. 400 Bad Request - When request validation fails - When required fields are missing - When field values are invalid

1. 401 Unauthorized - When authentication token is missing or invalid - When user doesn't have required rights

1. 403 Forbidden - When location is read-only - When user doesn't have sufficient permissions

1. 404 Not Found - When requested task doesn't exist - When location or category doesn't exist

1. 409 Conflict - When trying to create a duplicate task - When task name already exists in the specified location/category/group

### Validation Rules and status codes

0: **UnknownError** - A generic or unspecified error. Used as a fallback when the specific cause is not known.

Status: **400 Bad Request**

1–3: **Duplicate/Uniqueness Errors**

• 1: **TaskNameDuplicate**: The task name already exists in the system.

• 2: **UniqueIdDuplicate**: The unique identifier for a task is already in use.

• 3: **TaskNameDuplicateInGroup**: The task name is duplicated within a specific group.

Status: **409 Conflict**

4–10: **Not Found Errors**

• 4: **LocationNotFound**: The specified location does not exist.

• 5: **CategoryNotFound**: The specified category does not exist.

• 6: **GroupNotFound**: The specified group does not exist.

• 7: **TaskNotFound**: The specified task does not exist.

• 8: **RankNotFound**: The specified rank does not exist.

• 9: **ApproverRankNotFound**: The specified approver rank does not exist.

• 10: **CurrencyNotFound**: The specified currency does not exist.

Status: **404 Not Found**

11–31: **Required Field Errors**

• 11: **LocationRequired**: Location is required but missing.

• 12: **CategoryRequired**: Category is required but missing.

• 13: **GroupRequired**: Group is required but missing.

• 14: **TaskRequired**: Task is required but missing.

• 15: **TaskNameRequired**: Task name is required but missing.

• 16: **TaskDescriptionRequired**: Task description is required but missing.

• 17: **UniqueIdRequired**: Unique ID is required but missing.

• 18: **IntervalRequired**: Interval value is required but missing.

• 19: **IntervalTypeRequired**: Interval type is required but missing.

• 20: **WarningIntervalRequired**: Warning interval is required but missing.

• 21: **WarningIntervalTypeRequired**: Warning interval type is required but missing.

• 22: **MaxIntervalTypeRequired**: Max interval type is required but missing.

• 23: **ProjectRanksRequired**: Project ranks are required but missing.

• 24: **DefectRanksRequired**: Defect ranks are required but missing.

• 25: **ApproverRanksRequired**: Approver ranks are required but missing.

• 26: **RunningHoursRequired**: Running hours are required but missing.

• 27: **DueDateRequired**: Due date is required but missing.

• 28: **TaskIdRequired**: Task ID is required but missing.

• 29: **RankRequired**: Rank is required but missing.

• 30: **RanksRequired**: Ranks are required but missing.

• 31: **TaskListEmptyOrNull**: The list of tasks is empty or null.

Status: **400 Bad Request**

32–34: **Length Validation Errors**

• 32: **TaskNameTooLong**: Task name exceeds the maximum allowed length.

• 33: **LocationNameTooLong**: Location name exceeds the maximum allowed length.

• 34: **UniqueIdTooLong**: Unique ID exceeds the maximum allowed length.

Status: **400 Bad Request**

35–44: **Numeric/Value Validation Errors**

• 35: **GroupTypeGreaterThanZero**: Group type must be greater than zero.

• 36: **IntervalGreaterThanZero**: Interval must be greater than zero.

• 37: **WarningIntervalGreaterThanZero**: Warning interval must be greater than zero.

• 38: **MaxIntervalGreaterThanZero**: Max interval must be greater than zero.

• 39: **IntervalExceedsLimit**: Interval exceeds the allowed limit.

• 40: **WarningIntervalExceedsLimit**: Warning interval exceeds the allowed limit.

• 41: **MaxIntervalExceedsLimit**: Max interval exceeds the allowed limit.

• 42: **EstimatedBudgetAmountGreaterThanZero**: Estimated budget must be greater than zero.

• 43: **DueRunningHoursPositiveError**: Due running hours must be positive.

• 44: **DowntimeGreaterThanZero**: Downtime must be greater than zero. Status:

• 39–41: **412 Precondition Failed**

• Others: **400 Bad Request**

45–51: **Business Rule Validation Errors**

• 45: **ProjectCannotBeCounterBased**: Projects cannot be based on counters.

• 46: **TaskCompletionApprovalNotAllowed**: Task completion approval is not allowed.

• 47: **DefectRequiresOneTimeTask**: Defect tasks must be one-time tasks.

• 48: **ApproverRankNotAllowed**: Approver rank is not allowed.

• 49: **DowntimeNotAllowed**: Downtime is not allowed.

• 50: **AttachmentNotAllowed**: Attachments are not allowed.

• 51: **PriorityNotAllowed**: Priority is not allowed. Status:

• 45, 47: **412 Precondition Failed**

• 46, 48–51: **403 Forbidden**

54–56: **Invalid/Out-of-Range Errors**

• 54: **WarningIntervalTypeInvalid**: Warning interval type is invalid.

• 55: **IntervalTypeInvalid**: Interval type is invalid.

• 56: **MaxIntervalTypeInvalid**: Max interval type is invalid.

• 57: **InvalidRanks**: Ranks are invalid

Status: **400 Bad Request**

• 58: **UserIsNotAllowedOnLocation**: User is not allowed on the specified location (**400 Bad Request**)