addActivity API

Avatar
Ciarán Ainsworth
  • Updated
Follow

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/addActivity

POST

Adds an activity to an appointment, with optional fields for site locations and activity notes.

File Format Spec

 

List of included fields
Field Name Data Type Mandatory? Description
activities Array Yes An array of activity objects
code Text (200) Yes The activity code in Oneserve
appointmentId Integer Yes The ID of the appointment
totalQuantity Decimal Yes The quantity of activities to be added
completedQuantity Decimal Yes The completed quantity of the activity
note Text (1000) No The description of the activity
siteLocationId Integer No The ID of the associated site location
activityGroupId Integer No The ID of the activity group to which the activity belongs

 

Request Representations

 

Example JSON Payload 
{
    "activities": [
        {
            "code": "REPAIR",
            "appointmentId": "42923",
            "totalQuantity": 2,
            "completedQuantity": "0",
            "note": "Some activity notes",
            "siteLocationId": "901",
            "activityGroupId": "5"
        }
    ]
}

 

Available Response Representations

HTTP Code Description Schema
200 Job(s) Posted activities [array]
activityId Int
code Text
activityVersion Int
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

{
    "activities": [
        {
            "activityId": "137128",
            "code": "REPAIR",
            "activityVersion": "0"
        }
    ],
    "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

Unable to find site location with id

Response

{
    "result": "fail",
    "result_msg": "REST0001",
    "result_error_msg": "Unable to find site location with id: 2147483647"
}

Reason

This error occurs if the ID passed in the siteLocationId does not match an existing value in the system

Resolution

Ensure that the site location ID being posted exists in the system