Crowd Dispatch API

1.1 Overview

The Dispatch API enables customers with external systems to manage and dispatch assignments to Crowd-based service partner technicians.

For more information on the SAP Field Service Management Crowd platform, please refer to the following documentation:

Crowd


1.1.1 Request Methods

The following methods are supported by the Dispatch API:

  Note Section
1.1.0.1 POST one or more activities that have been accepted by the technician/s. 1.3
1.1.0.2 POST one or more activities that have been cancelled. 1.4
1.1.0.3 POST request to iniiate activity crowding. 1.5
1.1.0.4 POST activities that failed to be crowded; i.e. could not be planned. 1.6
1.1.0.5 POST one or more activities to the Dispatch Queue to be planned. 1.7
1.1.0.6 POST activity that has been rejected by the assigned technician. 1.8
1.1.0.7 POST activities that were successfully crwoded; i.e. automatically planned. 1.9
1.1.0.8 POST activitiy that has been unassigned. 1.10

1.2 Access

The Dispatch API uses Oauth 2.0 for authentication. This token is then used in the Authorization header as the bearer.

Attention: In order to receive an access token, you must have ADMINISTRATOR or SUPERUSER privileges.

1.2.1 Get Access Token

The following example shows how to get the access token for a Cloud Account or a Company User:


Cloud Account


The following example is an example of authentication for a Coresystems Cloud account with access to all companies within the account:


POST https://auth.coresuite.com/api/oauth2/v1/token HTTP/1.1

Host et.dev.coresuite.com
Authorization Basic dGVzdDpzZWNyZXQ=
Content-Type application/x-www-form-urlencoded

grant_type=password&username=cym&password=passwordExample123


Company User


The following example of authentication for a company user, with access to companies controlled by existing subscription and permission settings:


POST https://auth.coresuite.com/api/oauth2/v1/token HTTP/1.1

Host et.dev.coresuite.com
Authorization Basic dGVzdDpzZWNyZXQ=
Content-Type application/x-www-form-urlencoded

grant_type=password&username=cym/manager&password=passwordExample123


1.2.2 Response

The following is an example of a typical response:

{
  "access_token": "77cf4834-a347-4849-839b-4518823a739e",
  "token_type": "bearer",
  "expires_in": 43199,
  "scope": "general",
  "cluster_url": "https://et.dev.coresuite.com",
  "account": "testaccount",
  "account_id" : 284,
  "user": "manager",
  "user_email": "test@coresystems.ch",
  "companies": [
    {
      "id": 957,
      "name": "SBODemoCH",
      "description": "OEC Computers (Schweiz)"
    }
  ],
 }
 

1.2.3 Error Response

{
  "error": "invalid_grant",
  "error_description": "Bad credentials"
}

1.2.4 Supported Clusters

Depending on the location of the account, requests will be made to one of the following server clusters:

  • EU
  • DE
  • US

Attention: please note that the CN (China) cluster is currently NOT supported.

Account information, including cluster assignment, are obtained from the Directory API.

This information is passed into requests made to the Dispatch API as follows:

https://{cluster}.coresuite.com/dc/api/crowd/v1/dispatch/


1.3 POST Activity Acceptance

Accept activity by technician.

1.3.1 Request

Method URL
POST https://{cluster}.coresuite.com/dc/api/crowd/v1/dispatch/accept

1.3.2 Headers

Header Description Required
x-client-id The alphanumerical ID associated with the client. Required
x-version The version number associated with the client. Required

1.3.3 Body

Value Description Type Required
activityId The ID of the Crowd-based activity. String Required
technicianId The ID of the external, Crowd-based technician who has accepted the activity. String Required

The following is an example of a posted ACCEPT request sent to the Dispatch API:

{
  "activityId": "string",
  "technicianId": "string"
}

1.3.4 Response

Status Response
201 Created
202 Accepted
400 Bad Request
409 Conflict
500 Internal Server Error

1.3.5 Example Response

{
  "body": {},
  "statusCode": "100",
  "statusCodeValue": 0
}

1.4 POST Activity Cancellation

Mark Crowd-based activity status as cancelled.

1.4.1 Request

Method URL
POST https://{cluster}.coresuite.com/dc/api/crowd/v1/dispatch/cancel

1.4.2 Headers

Header Description Required
x-client-id The alphanumerical ID associated with the client. Required
x-version The version number associated with the client. Required

1.4.3 Body

Value Description Type Required
activityId The ID of the Crowd-based activity you wish to cancel. String Required
{
  "activityId": "string"
}

1.4.4 Response

Status Response
201 Created
202 Accepted
400 Bad Request
409 Conflict
500 Internal Server Error

1.5 POST Crowding Request Initializiation

Initiating an activity crowding event. When this POST request is submitted, all activities that are in the queue will be planned and assigned.

1.5.1 Request

Method URL
POST https://{cluster}.coresuite.com/dc/api/crowd/v1/dispatch/crowding

1.5.2 Headers

Header Description Required
x-client-id The alphanumerical ID associated with the client. Required
x-version The version number associated with the client. Required

1.5.3 Body

{
  "activityIds": [
    null
  ]
}

1.5.4 Response

Status Response
201 Created
202 Accepted
400 Bad Request
409 Conflict
500 Internal Server Error

1.6 Post Activity Crowding Failures

Mark Crowd-based activity status as failed.

1.6.1 Request

Method URL
POST https://{cluster}.coresuite.com/dc/api/crowd/v1/dispatch/failure

1.6.2 Headers

Header Description Required
x-client-id The alphanumerical ID associated with the client. Required
x-version The version number associated with the client. Required

1.6.3 Body

Value   Description Type Required
Items   Array of failed Crowd-based activities. Array Required
  activityId The ID of the Crowd-based activity that could not be crowded. String Required
  reason The reason the activity could not be crowded. String Required

1.6.4 Body Example

{
  "items": [
    {
      "activityId": "string",
      "reason": "string"
    }
  ]
}

1.6.5 Response

Status Response
201 Created
202 Accepted
400 Bad Request
409 Conflict
500 Internal Server Error

1.7 POST Activities to Dispatch Queue

Add one or more activities to the Dispatch Queue.

1.7.1 Request

Method URL
POST https://{cluster}.coresuite.com/dc/api/crowd/v1/dispatch/queue

1.7.2 Headers

Header Description Required
x-client-id The alphanumerical ID associated with the client. Required
x-version The version number associated with the client. Required

1.7.3 Body

Value Description Type Required
activityIds The IDs of the Crowd-based activity you wish to add to the queue. Array Required
selectedBusinessPartnerIds The IDs of the selected business partners to whom the activities may be assigned. Array Required

1.7.4 Example Body

{
  "activityIds": [
    null
  ],
  "selectedBusinessPartnerIds": [
    null
  ]
}

1.7.5 Response

Status Response
201 Created
202 Accepted
400 Bad Request
409 Conflict
500 Internal Server Error

1.8 POST Activity Rejection

Mark crowd-based activity as rejected by the technician.

1.8.1 Request

Method URL
POST https://{cluster}.coresuite.com/dc/api/crowd/v1/dispatch/reject

1.8.2 Headers

Header Description Required
x-client-id The alphanumerical ID associated with the client. Required
x-version The version number associated with the client. Required

1.8.3 Body

Value Description Type Required
activityId The ID of the Crowd-based activity rejected by the technician. String Required
technicianId The ID of the technician who rejected the Crowd-based activity. String Required

1.8.4 Example Body

{
  "activityId": "string",
  "technicianId": "string"
}

1.8.5 Response

Status Response
201 Created
202 Accepted
400 Bad Request
409 Conflict
500 Internal Server Error

1.8.6 Example Response

{
  "body": {},
  "statusCode": "100",
  "statusCodeValue": 0
}

1.9 POST Successfully Crowded Activities

Mark crowded activities as success, i.e. successfully planned and assigned.

1.9.1 Request

Method URL
POST https://{cluster}.coresuite.com/dc/api/crowd/v1/dispatch/success

1.9.2 Headers

Header Description Required
x-client-id The alphanumerical ID associated with the client. Required
x-version The version number associated with the client. Required

1.9.3 Body

Value   Description Type Required
Items Array of successfully crowded activities. See below values. Array Required  
  activityId The ID of the Crowd-based activity you wish to cancel. String Required
  drivingTimeFrom The estimated driving time from the current activity to the next scheduled one. Integer Required
  drivingTimeTo The estimated driving time to the scheduled activitiy. Integer Required
  endDate The planned end date of the activity. dateTime Required
  startDate The planned start date of the activity. dateTime Required
  technicianId The ID of the technician assigned to the activity. String Required

1.9.4 Example Body

{
  "items": [
    {
      "activityId": "string",
      "drivingTimeFrom": 0,
      "drivingTimeTo": 0,
      "endDate": "2019-07-16T08:11:44.181Z",
      "startDate": "2019-07-16T08:11:44.181Z",
      "technicianId": "string"
    }
  ]
}

1.9.5 Response

Status Response
201 Created
202 Accepted
400 Bad Request
409 Conflict
500 Internal Server Error

1.10 POST Activity Unassignment

Unassign Crowd-based activity.

1.10.1 Request

Method URL
POST https://{cluster}.coresuite.com/dc/api/crowd/v1/dispatch/unassign

1.10.2 Headers

Header Description Required
x-client-id The alphanumerical ID associated with the client. Required
x-version The version number associated with the client. Required

1.10.3 Body

Value Description Type Required
activityId The ID of the Crowd-based activity you wish to unassign. String Required

1.10.4 Response

Status Response
201 Created
202 Accepted
400 Bad Request
409 Conflict
500 Internal Server Error