AMAGE REST API - Work Orders

Introduction/Context

Context for operations on work order module objects in the AMAGE system, which should be extended with the appropriate method in the query.

  • rest/amage/v1/work-orders

Data structures

Structures and data types used in queries and responses.

Result:

The ID/UUID fields contain the identifier of the newly created or edited object. If the operation is performed correctly, the success field is set to true. If an error occurs, the success field is set to false, and the message field contains a description of the error. The error code then contains an HTTP code of the NOT_FOUND or BAD_REQUEST type. The BAD_REQUEST code is also returned in the query. Depending on the type of error during query processing, the error code may be different than the main query code returned. The query code will be BAD_REQUEST, and the internal code will be set to NOT_FOUND in the case when the query sets an object property to another object in the system. The JSON parameter will be correct (record UUID), but there will be no such record in the system. Therefore, the NOT_FOUND code will appear in the errorCode field. In the message description field, a message informing what record was not found, and the main query error code will be BAD_REQUEST.

{
    "id": 1,
    "uuid":"f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "success":true,
    "errorCode":0,
    "message":""
}

Work Order Status Type:

NEW,
SCHEDULED,
IN_PROGRESS,
ON_HOLD,
FINISHED,
VOID

Work order priority:

 LOW,
NORMAL,
HIGH

Work order

Adding a new work order

  • Method: POST

  • Path: /add

  • Generates: application/json

  • Requires: application/json

  • Authorization: API signature (device-uuid, api-key, api-sign)

The query body should contain a JSON object with the work order data. The object has the following structure:

{
"uuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
"name": "Order name",
"description": "Order description",
"typeUuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
"stateName": "IN_PROGRESS",
"priorityName": "NORMAL",
"archived": false,
"contractUuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
"contractScopeUuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "accountUuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "created": "2021-01-01T12:00:00",
    "beginDate": "2021-01-01T12:00:00",
    "deadlineDate": "2021-01-01T12:00:00",
    "notes": "notes",
    "startDate": "2021-01-01T12:00:00",
    "finishDate": "2021-01-01T12:00:00",
    "assignedDepartmentUuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "assignedUserUuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "assignedContractorUuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "verifyUserUuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "protocolNumber": "A/23/330/2000",
    "parentUuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "customerUuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "locationUuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "placeOfWorkUuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "budget": 1000.0,
    "hoursEstimated": 10.0,
    "workAmount": 100.0,
    "workAmountUnit": "meters",
    "workUnitMinutesTotal": 150.0,
    "workUnitMinutes": 100.0,
    "workUnitPrice": 156.0
}

Query

/rest/amage/v1/work-orders/add

Response

{
    "id": 12345,
    "uuid":"f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "success":true,
    "errorCode":0,
    "message":""
}

Editing a work order

  • Method: POST

  • Path: /edit/{uuid}

  • Generates: application/json

  • Requires: application/json

  • Authorization: API signature (device-uuid, api-key, api-sign)

Parameters:

  • UUID - work order identifier

In the query body, you should include a JSON object with the work order data. The object has the same structure as in the case of adding a work order. Non-empty fields will be updated in the work order.

Query

/rest/amage/v1/work-orders/edit/f25e62ea-0100-4f4e-aad2-853cf48df2b9

Response

{
    "id": 12345,
    "uuid":"f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "success":true,
    "errorCode":0,
    "message":""
}

Work order history

Save history to an existing work order

  • Method: POST

  • Path: /add-history/{uuid}

  • Generates: application/json

  • Requires: application/json

  • Authorization: API signature (device-uuid, api-key, api-sign)

Parameters:

  • UUID - work order identifier

The query body should contain a JSON object with the work order history data. The object has the following structure:

{
    "workOrderUuid":"1c4066e6-cdd6-4903-803a-b6bffe689527",
    "reportedOn":"2021-01-01T12:00:00",
    "reportedByUuid":"1c4066e6-cdd6-4903-803a-b6bffe689527",
    "tstamp":"2021-01-01T12:00:00",
    "stateName": "IN_PROGRESS",
    "message": "message",
    "hoursReported":8.0,
    "workAmountReported":10.0,
    "participantCount":5,
    "valid":true,
    "participants":[
        {
            "uuid":"1c4066e6-cdd6-4903-803a-b6bffe689527"
        },
        {
            "uuid":"1c4066e6-cdd6-4903-803a-b6bffe689527"
        }
    ],
    "workOrderExpenditures":[
        {
            "uuid":"1c4066e6-cdd6-4903-803a-b6bffe689527",
            "tstamp":"2021-01-01T12:00:00",
            "elementTypeUuid":"1c4066e6-cdd6-4903-803a-b6bffe689527",
            "itemCount":10.0,
            "message": "message"
        }
    ]
}

Query

/rest/amage/v1/work-orders/add-history/1c4066e6-cdd6-4903-803a-b6bffe689527

Response

{
    "uuid":"f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "success":true,
    "errorCode":0,
    "message":""
}

Edit work order history

  • Method: POST

  • Path: /edit-history/{uuid}

  • Generates: application/json

  • Requires: application/json

  • Authorization: API signature (device-uuid, api-key, api-sign)

Parameters:

  • UUID - history entry identifier

In the query body, you should include a JSON object with the work order history data. The object has a j/n structure. If a list of users is provided, the existing list will be cleared and replaced with the provided one. The same for consumption.

{
    "workOrderUuid":"1c4066e6-cdd6-4903-803a-b6bffe689527",
    "reportedOn":"2021-01-01T12:00:00",
    "reportedByUuid":"1c4066e6-cdd6-4903-803a-b6bffe689527",
    "tstamp":"2021-01-01T12:00:00",
    "stateName": "IN_PROGRESS",
    "message": "message",
    "hoursReported":8.0,
    "workAmountReported":10.0,
    "participantCount":5,
    "valid":true,
    "participants":[
        {
            "uuid":"1c4066e6-cdd6-4903-803a-b6bffe689527"
        },
        {
            "uuid":"1c4066e6-cdd6-4903-803a-b6bffe689527"
        }
    ],
    "workOrderExpenditures":[
        {
            "uuid":"1c4066e6-cdd6-4903-803a-b6bffe689527",
            "tstamp":"2021-01-01T12:00:00",
            "elementTypeUuid":"1c4066e6-cdd6-4903-803a-b6bffe689527",
            "itemCount":10.0,
            "message": "message"
        }
    ]
}

Query

/rest/amage/v1/work-orders/edit-history/1c4066e6-cdd6-4903-803a-b6bffe689527

Response

{
    "uuid":"f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "success":true,
    "errorCode":0,
    "message":""
}

Delete work order history

  • Method: DELETE

  • Path: /delete-history/{uuid}

  • Generates: application/json

  • Requires: application/json

  • Authorization: API signature (device-uuid, api-key, api-sign)

Parameters:

  • UUID - history entry identifier

Query content (body) is empty.

Query

/rest/amage/v1/work-orders/delete-history/1c4066e6-cdd6-4903-803a-b6bffe689527

Response

{
    "uuid":"f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "success":true,
    "errorCode":0,
    "message":""
}

Work order material plan

Saving a material plan to an existing work order

  • Method: POST

  • Path: /add-workorder-elementtype-plan/{uuid}

  • Generates: application/json

  • Requires: application/json

  • Authorization: API signature (device-uuid, api-key, api-sign)

Parameters:

  • UUID - work order identifier

The query body should contain a JSON object with the work order material plan data. The object has the following structure:

{
    "workOrderUuid":"1c4066e6-cdd6-4903-803a-b6bffe689527",
    "elementTypeUuid":"1c4066e6-cdd6-4903-803a-b6bffe689527",
    "itemCount":10.0,
    "category":"category",
    "code":"code"
}

Query

/rest/amage/v1/work-orders/add-workorder-elementtype-plan/1c4066e6-cdd6-4903-803a-b6bffe689527

Response

{
    "uuid":"f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "success":true,
    "errorCode":0,
    "message":""
}

Editing a material plan for a work order

  • Method: POST

  • Path: /edit-workorder-elementtype-plan/{uuid}

  • Generates: application/json

  • Requires: application/json

  • Authorization: API signature (device-uuid, api-key, api-sign)

Parameters:

  • UUID - material plan entry identifier

In the body of the request (body), include a JSON object with the material plan data for the work order. The object has the structure:

{
    "workOrderUuid":"1c4066e6-cdd6-4903-803a-b6bffe689527",
    "elementTypeUuid":"1c4066e6-cdd6-4903-803a-b6bffe689527",
    "itemCount":10.0,
    "category":"category",
    "code":"code"
}

Query

/rest/amage/v1/work-orders/edit-workorder-elementtype-plan/1c4066e6-cdd6-4903-803a-b6bffe689527

Response

{
    "uuid":"f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "success":true,
    "errorCode":0,
    "message":""
}

Removal of work order material plan

  • Method: DELETE

  • Path: /delete-workorder-elementtype-plan/{uuid}

  • Generates: application/json

  • Requires: application/json

  • Authorization: API signature (device-uuid, api-key, api-sign)

Parameters:

  • UUID - Material Plan Identifier

Query content (body) is empty.

Query

/rest/amage/v1/work-orders/delete-workorder-elementtype-plan/1c4066e6-cdd6-4903-803a-b6bffe689527

Response

{
    "uuid":"f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "success":true,
    "errorCode":0,
    "message":""
}

Work Order Resource Plan

The work order resource plan allows you to operate on the list of resources assigned to a given work order.

Linking an existing resource to a work order

  • Method: POST

  • Path: /asset-plan/{work-order-uuid}/join-asset-to-plan-by-uuid/{uuid}

  • Generates: application/json

  • Requires: application/json, text/plain

  • Authorization: API signature (device-uuid, api-key, api-sign)

Parameters:

  • work-order-uuid - work order UUID

  • uuid - resource identifier

The data returned is a JSON object with a structure containing the ID/UUID of the newly created work order resource plan record.

{
    "id": 123456,
    "uuid":"f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "success":true,
    "errorCode":0,
    "message":""
}

Removing a resource from a work order plan

  • Method: POST

  • Path: /asset-plan/{work-order-uuid}/remove-asset-from-plan-by-uuid/{uuid}

  • Generates: application/json

  • Requires: application/json, text/plain

  • Authorization: API signature (device-uuid, api-key, api-sign)

Parameters:

  • work-order-uuid - work order UUID

  • uuid - resource identifier

The data returned is a JSON object with a structure containing the ID/UUID of the deleted work order resource plan record.

{
    "id": 123456,
    "uuid":"f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "success":true,
    "errorCode":0,
    "message":""
}
If a resource is added multiple times to a given work order, the query will return an error. You should use a method that explicitly specifies the resource plan record ID for the work order.

This method requires the specific work order resource plan record ID to be provided in the UUID field.

  • Method: POST

  • Path: /asset-plan/{work-order-uuid}/remove-asset-plan-by-uuid/{uuid}

  • Generates: application/json

  • Requires: application/json, text/plain

  • Authorization: API signature (device-uuid, api-key, api-sign)

Parameters:

Parameters:

  • work-order-uuid - work order UUID

  • uuid - resource plan entry identifier for the work order

The data returned is a JSON object with a structure containing the ID/UUID of the deleted work order resource plan record.

{
    "id": 123456,
    "uuid":"f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "success":true,
    "errorCode":0,
    "message":""
}