July 15, 2020 08:37
Updated

Summary

Requirements

All API calls require a dedicated JSON Web Token (JWT). These are created when a user with a dedicated mobile resource logs in to the application. If you are using the API for programmatic queries, it is best to create a dedicated user for the JWT as this gets reset each time the user logs in.

Endpoint

/rest/workflow/activity/addActivityByClientRef

POST

Adds an activity to a job using the client ref and client to look up the job. Changes will only impact the most recent version of a job.

If versioning is enabled and the user doesn't have the rights to create a version an error message will be returned. If versioning is not enabled the activities will be added without a version being created.

If the submitVersion flag is set to 1 the version will also be submitted (if versioning is switched on). If set to 0 the version will not be submitted. If versioning is switched off the submitVersion flag will be ignored.

File Format Spec

List of included fields

Field Name	Data Type	Mandatory?	Description
`activities`	Array	Yes	An array of activity objects
`jobClientRef`	Text (50)	Yes	The client ref of the job
`clientId`	Integer	Yes	The ID of the client
`code`	Text(20)	Yes	The code of the activity to be added
`clientRef`	Text (50)	Yes	The client reference of the activity
`description`	Text (1000)	No	The description of the activity
`completedQuantity`	Decimal	Yes	The completed quantity of the activity
`totalQuantity`	Decimal	Yes	The total quantity of the activity on the job
`submitVersion`	Boolean	No	0 - Does not submit a new version of the job 1 - Submits a new version of the job

Request Representations

Example JSON Payload

{
    "activities": [
        {
            "jobClientRef": "J023T4",
            "clientId": "28",
            "code": "REPAIR",
            "clientRef": "REPAIR",
            "description": "An activity description",
            "completedQuantity": "3",
            "totalQuantity": "3"
        }
    ],
    "submitVersion": "1"
}

Available Response Representations

HTTP Code	Description	Schema
200	Activity(ies) Posted	"result": "success"
400	Bad Request	Error
401	Unauthorized	Error
403	Forbidden	Error
404	Address Not Found	Error
405	Method Not Allowed	Error
500	Internal Server Error	Error

Example Success Response

{
    "result": "success",
    "result_msg": ""
}

Troubleshooting

401 Unauthorized

Response

401 Unauthorized

Reason

This error occurs if the OS_REST_AUTH_TOKEN has not been provided, has expired, or does not exist in the system

Resolution

Verify your OS_REST_AUTH_TOKEN with support

403 Forbidden

Response

403 Forbidden

Reason

This error indicates that something is blocking your connection to the server

Resolution

Open a ticket with the support team with details of your connection so that your access can be verfied

404 Not Found

Response

404 Not Found

Reason

This error should only occur if the endpoint has been mistyped in some way, which will lead the call to an endpoint that does not exist

Resolution

Verify the endpoint matches the value specified in this article

405 Method Not Allowed

Response

405 Method Not Allowed

Reason

This error will occur if an unacceptable method has been used in the call such as GET or DELETE

Resolution

Ensure that you are using a POST call to this endpoint

No active library activity with code found

Response

{
    "result": "fail",
    "result_msg": "REST0001",
    "result_error_msg": "No active library activity with code: <yourcode> found for client id: 28, wlt: 47"
}

Reason

This response is given if no active library activity or costs can be found for the client/work log type in question

Resolution

Ensure that the activity exists in Oneserve and has valid costs for the job in question

JSONObject is not a number

Response

{
    "result": "fail",
    "result_msg": "REST0001",
    "result_error_msg": "JSONObject[&quot;completedQuantity&quot;] is not a number."
}

Reason

This error occurs if a non-numeric value is passed to a number-only field

Resolution

Ensure that all fields are filled out account to the spec above

JSONObject ... not found

Response

{
    "result": "fail",
    "result_msg": "REST0001",
    "result_error_msg": "JSONObject[&quot;clientRef&quot;] not found."
}

Reason

This error occurs if a mandatory field is missing from the call

Resolution

Ensure that all fields are filled out per the spec above