Interfejs REST API AMAGE - zlecenia pracy

Wstęp/Kontekst

Kontekst dla operacji na obiektach modułu zleceń pracy (Work Orders) w systemie AMAGE, którą należy w zapytaniu rozszerzyć o odpowiednią metodę.

  • rest/amage/v1/work-orders

Struktury danych

Struktury i typy danych wykorzystywane w zapytaniach i odpowiedziach.

Rezultat:

W polach ID/UUID znajduje się identyfikator nowo utworzonego lub edytowanego obiektu. W przypadku poprawnego wykonania operacji pole success jest ustawiane na true. W przypadku wystąpienia błędu pole success jest ustawiane na false, a w polu message znajduje się opis błędu. Kod błędu zawiera wtedy kod HTTP typu NOT_FOUND lub BAD_REQUEST. Zwracany w zapytaniu wtedy jest również kod BAD_REQUEST. W zależności od typu błędu podczas przetwarzania zapytania kod błędu może być różny niż zwracany główny kod zapytania. Kod zapytania będzie BAD_REQUEST, a kod wewnętrzny będzie ustawiony na NOT_FOUND w przypadku takim, gdy zapytanie będzie ustawiało właściwość obiektu na inny obiekt w systemie. Parametr JSON będzie poprawny (UUID rekordu), ale takiego rekordu nie będzie w systemie. W związku z tym w polu errorCode pojawi się kod NOT_FOUND. W polu opisowym message komunikat informujący jakiego rekordu nie znaleziono, a główny kod błędu zapytania będzie wynosił 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

  • Metoda: POST

  • Ścieżka: /add

  • Generuje: application/json

  • Wymaga: application/json

  • Autoryzacja: podpis API (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
}

Zapytanie

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

Odpowiedź

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

Edycja zlecenia pracy

  • Metoda: POST

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

  • Generuje: application/json

  • Wymaga: application/json

  • Autoryzacja: podpis API (device-uuid, api-key, api-sign)

Parametry:

  • UUID - identyfikator zlecenia pracy

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.

Zapytanie

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

Odpowiedź

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

Historia zlecenia pracy

Zapisanie historii do istniejącego zlecenia pracy

  • Metoda: POST

  • Ścieżka: /add-history/{uuid}

  • Generuje: application/json

  • Wymaga: application/json

  • Autoryzacja: podpis API (device-uuid, api-key, api-sign)

Parametry:

  • UUID - identyfikator zlecenia pracy

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

{
    "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"
        }
    ]
}

Zapytanie

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

Odpowiedź

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

Edycja historii zlecenia pracy

  • Metoda: POST

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

  • Generuje: application/json

  • Wymaga: application/json

  • Autoryzacja: podpis API (device-uuid, api-key, api-sign)

Parametry:

  • UUID - identyfikator wpisu historii

W treści zapytania (body) należy zamieścić obiekt JSON z danymi historii zlecenia pracy. Obiekt ma strukturę j/n. W przypadku podania listy użytkowników, istniejąca lista zostanie wyczyszczona i zastąpiona podaną. Tak samo w przypadku zużycia.

{
    "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"
        }
    ]
}

Zapytanie

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

Odpowiedź

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

Usunięcie historii zlecenia pracy

  • Metoda: DELETE

  • Ścieżka: /delete-history/{uuid}

  • Generuje: application/json

  • Wymaga: application/json

  • Autoryzacja: podpis API (device-uuid, api-key, api-sign)

Parametry:

  • UUID - identyfikator wpisu historii

Treść zapytania (body) pusta.

Zapytanie

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

Odpowiedź

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

Plan materiałowy zlecenia pracy

Zapisanie planu materiałowego do istniejącego zlecenia pracy

  • Metoda: POST

  • Ścieżka: /add-workorder-elementtype-plan/{uuid}

  • Generuje: application/json

  • Wymaga: application/json

  • Autoryzacja: podpis API (device-uuid, api-key, api-sign)

Parametry:

  • UUID - identyfikator zlecenia pracy

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

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

Zapytanie

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

Odpowiedź

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

Edycja planu materiałowego dla zlecenia pracy

  • Metoda: POST

  • Ścieżka: /edit-workorder-elementtype-plan/{uuid}

  • Generuje: application/json

  • Wymaga: application/json

  • Autoryzacja: podpis API (device-uuid, api-key, api-sign)

Parametry:

  • UUID - identyfikator wpisu planu materiałowego

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

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

Zapytanie

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

Odpowiedź

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

Usunięcie planu materiałowego zlecenia pracy

  • Metoda: DELETE

  • Ścieżka: /delete-workorder-elementtype-plan/{uuid}

  • Generuje: application/json

  • Wymaga: application/json

  • Autoryzacja: podpis API (device-uuid, api-key, api-sign)

Parametry:

  • UUID - identyfikator planu materiałowego

Treść zapytania (body) pusta.

Zapytanie

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

Odpowiedź

{
    "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

  • Metoda: POST

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

  • Generuje: application/json

  • Wymaga: application/json, text/plain

  • Autoryzacja: podpis API (device-uuid, api-key, api-sign)

Parametry:

  • 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

  • Metoda: POST

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

  • Generuje: application/json

  • Wymaga: application/json, text/plain

  • Autoryzacja: podpis API (device-uuid, api-key, api-sign)

Parametry:

  • 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.

  • Metoda: POST

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

  • Generuje: application/json

  • Wymaga: application/json, text/plain

  • Autoryzacja: podpis API (device-uuid, api-key, api-sign)

Parametry:

Parametry:

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