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.

Rezultat:

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":""
}

Typ stanu zlecenia pracy:

NEW,
SCHEDULED,
IN_PROGRESS,
ON_HOLD,
FINISHED,
VOID

Priorytet zlecenia pracy:

LOW,
NORMAL,
HIGH

Zlecenie pracy

Dodanie nowego zlecenia pracy

  • Method: POST

  • Ścieżka: /add

  • Generates: application/json

  • Requires: application/json

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

W treści zapytania (body) należy zamieścić obiekt JSON z danymi zlecenia pracy. Obiekt ma strukturę:

{
    "uuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "name": "Nazwa zlecenia",
    "description": "Opis zlecenia",
    "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": "metry",
    "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":""
}

Edycja zlecenia pracy

  • Method: POST

  • Ścieżka: /edit/{uuid}

  • Generates: application/json

  • Requires: application/json

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

Parameters:

  • UUID - work order identifier

W treści zapytania (body) należy zamieścić obiekt JSON z danymi zlecenia pracy. Obiekt ma strukturę taką jak dla przypadku dodania zlecenia pracy. Pola niepuste zostaną zaktualizowane w zleceniu pracy.

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":""
}

Plan zasobów zlecenia pracy

Plan zasobów zlecenia pracy pozwala na operacje na liście zasobów przypisanych do danego zlecenia pracy.

Połączenie istniejącego zasobu do zlecenia pracy

  • Method: POST

  • Ścieżka: /asset-plan/{work-order-uuid}/join-asset-to-plan-by-uuid/{uuid}

  • Generates: application/json

  • Wymaga: application/json, text/plain

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

Parameters:

  • work-order-uuid - UUID zlecenia pracy

  • uuid - identyfikator zasobu

Zwracane dane to obiekt JSON ze strukturą zawierającą ID/UUID nowo utworzonego rekordu planu zasobów zlecenia pracy.

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

Usunięcie zasobu z planu zlecenia pracy

  • Method: POST

  • Ścieżka: /asset-plan/{work-order-uuid}/remove-asset-from-plan-by-uuid/{uuid}

  • Generates: application/json

  • Wymaga: application/json, text/plain

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

Parameters:

  • work-order-uuid - UUID zlecenia pracy

  • uuid - identyfikator zasobu

Zwracane dane to obiekt JSON ze strukturą zawierającą ID/UUID usuniętego rekordu planu zasobów zlecenia pracy.

{
    "id": 123456,
    "uuid":"f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "success":true,
    "errorCode":0,
    "message":""
}
Jeśli zasób będzie dodany wielokrotnie do danego zlecenia pracy, to zapytanie zwróci błąd. Należy skorzystać z metody jawnie wskazującej identyfikator rekordu planu zasobu dla zlecenia pracy.

Usunięcie elementu planu zasobu związanego ze zleceniem pracy

Ta metoda w polu UUID wymaga podania konkretnego identyfikatora rekordu planu zasobów zlecenia pracy.

  • Method: POST

  • Ścieżka: /asset-plan/{work-order-uuid}/remove-asset-plan-by-uuid/{uuid}

  • Generates: application/json

  • Wymaga: application/json, text/plain

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

Parameters:

Parameters:

  • work-order-uuid - UUID zlecenia pracy

  • uuid - identyfikator wpisu w planie zasobów dla zleenia pracy

Zwracane dane to obiekt JSON ze strukturą zawierającą ID/UUID usuniętego rekordu planu zasobów zlecenia pracy.

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