Crowd Partner Dispatching API

Attention: SAP Field Service Management documentation is now available at the SAP Help Portal. On 31 December 2020, docs.coresystems will no longer be available. Until that time, documentation will NOT be updated in docs.coresystems.

1.1 Overview

The crowd partner dispatching API enables crowd owner with external systems to make requests from a third-party application to SAP Field Service Management, where they can allow partner manager to manage the assignments by crowd owner.

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

Crowd


1.1.1 Supported Requests

The following requests are supported by the crowd partner dispatching API:

  Method Description Section
1.1.1.1 GET Retrieve information on assignment assigned to specific partner. 1.3.1
1.1.1.2 PUT Update the existing assignment. 1.3.2

1.1.2 Business Actions on Assignments

The following business actions can be performed on activities in the crowd partner dispatching API:

  Business Action Endpoint Section
1.1.2.1 Confirm assignment /api/partner-dispatch/v1/confirm 1.4.1
1.1.2.2 Notify assignment /api/partner-dispatch/v1/notify 1.4.2
1.1.2.3 Reject assignment /api/partner-dispatch/v1/reject 1.4.3
1.1.2.4 Accept assignment /api/partner-dispatch/v1/accept 1.4.4
1.1.2.5 Batch accept assignment /api/partner-dispatch/v1/accept/batch 1.4.5
1.1.2.6 Release assignment /api/partner-dispatch/v1/release 1.4.6

1.1.3 Crowd Partner Dispatching API in Swagger

To preview crowd partner dispatching API functionality, you may use the SAP crowd partner dispatching API Swagger implementation.


1.1.4 Postman Collection

The following file contains the supported methods and endpoints in JSON format that can be uploaded to Postman:


1.2 Access

The crowd partner dispatching 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 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 SAP 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@coresuite.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
  • CN
  • AU

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

This information is passed into requests made to the Crowd Partner Dispatching API as follows:

https://{cluster}.coresuite.net/cloud-partner-dispatch-service/


1.3 Standard Requests

1.3.1 GET assignments assigned to specific partner

Get the activities and their related resources.


1.3.1.1 Request

Method URL
GET https://{cluster}.coresuite.com/cloud-partner-dispatch-service/api/v1/assignment-details

1.3.1.2 Headers

Header Parameter Value Description Required
Authorization bearer OAuth 2.0 token Required
X-Account-ID accountId The account identifier Required
X-Account-Name accountName The name of the account Required
X-Client-ID clientId Client app identifier Required
X-Client-Version clientVersion The client version Required
X-Company-ID companyid The company identifier Required
X-Company-Name companyName The name of the company Required

1.3.1.3 Query Parameters

Query Parameter Value Description
page Max 1000 Page of data needed to be returned
partnerDispatchingStatus NOTIFIED , ACCEPTED Partner dispatching status on ServiceAssignment

1.3.1.4 Response

Status Response
200 OK
401 Unauthorized
403 Forbidden
404 Not Found

1.3.2 PUT assignment assigned to specific partner

Update the activity.

Please note:

  • Only ACCEPTED activity allows to update.
  • Only Partner manager allows to update.

1.3.2.1 Request

Method URL
PUT https://{cluster}.coresuite.com/cloud-partner-dispatch-service/api/v1/assignment-details/{activity-id}

1.3.2.2 URL Parameters

Parameter Description Type Required
Authorization The ID of the activity record created via PUT request you wish to update String Required

1.3.2.3 Headers

Header Parameter Value Description Required
Authorization bearer OAuth 2.0 token Required
X-Account-ID accountId The account identifier Required
X-Account-Name accountName The name of the account Required
X-Client-ID clientId Client app identifier Required
X-Client-Version clientVersion The client version Required
X-Company-ID companyid The company identifier Required
X-Company-Name companyName The name of the company Required

1.3.2.4 Request Body

The following are the values contained in a PUT request:

Value Description Type Required
endDateTime The activity start working date and time Datetime Required
responsible The technician who is responsible for the activity string Required
startDateTime The activity finished date and time Datetime Required

1.3.2.5 Response

Status Response
200 Assignment details updated successfully
201 Created
401 Unauthorized
403 Forbidden
404 Either requested assignment details does not exist or assigned to another partner

Business Actions

1.4.1 Confirm Assignment

The Crowd owner confirms the activity and assigns it to specific partner.

Attention: Only Crowd owner can confirm an activity.

The following conditions need to be met before Crowd owner can confirm an activity:

  • The activity is planned to partner.
  • The activity linked service assignment’s partner dispatching status is empty.

Upon the successful request, the patch request will update these fields as below in ServiceAssignment:

  • {“PartnerDispatchingStatus”, “CONFIRMED”}
  • Business event of assignment confirmation is triggered.

1.4.1.1 Request

Method URL
POST https://{cluster}.coresuite.com/cloud-partner-dispatch-service/api/partner-dispatch/v1/confirm

1.4.1.2 Headers

Header Parameter Value Description Required
Authorization bearer OAuth 2.0 token Required
X-Account-ID accountId The account identifier Required
X-Account-Name accountName The name of the account Required
X-Client-ID clientId Client app identifier Required
X-Client-Version clientVersion The client version Required
X-Company-ID companyid The company identifier Required
X-Company-Name companyName The name of the company Required

1.4.1.3 Request Body

The following are the values contained in a POST request:

Value Description Type Required
activityId The identifier of activity string Required
technicianid The technician who is responsible for the activity string Required

1.4.1.4 Response

Status Response
201 Created
202 Accepted
401 Unauthorized
403 Forbidden
404 Not Found

1.4.2 Notify Assignment

The Crowd owner notifies the specific partner after the activity is assigned.

Attention: Only Crowd owner can notify an activity.

The following conditions need to be met before Crowd owner can notify an activity:

  • The activity is planned to partner.
  • The activity linked service assignment’s partner dispatching status is CONFIRMED.

Upon the successful request, the patch request will update these fields as below in ServiceAssignment:

  • {“PartnerDispatchingStatus”, “NOTIFIED”}
  • Business event of partner notification is triggered.
  • System starts to count down the time

1.4.2.1 Request

Method URL
POST https://{cluster}.coresuite.com/cloud-partner-dispatch-service/api/partner-dispatch/v1/notify

1.4.2.2 Headers

Header Parameter Value Description Required
Authorization bearer OAuth 2.0 token Required
X-Account-ID accountId The account identifier Required
X-Account-Name accountName The name of the account Required
X-Client-ID clientId Client app identifier Required
X-Client-Version clientVersion The client version Required
X-Company-ID companyid The company identifier Required
X-Company-Name companyName The name of the company Required

1.4.2.3 Request Body

The following are the values contained in a POST request:

Value Description Type Required
activityId The identifier of activity string Required

1.4.2.4 Response

Status Response
201 Created
202 Accepted
401 Unauthorized
403 Forbidden
404 Not Found

1.4.3 Reject Assignment

The Partner manager rejects the activity assigned by Crowd owner.

Attention: Only partner manager can reject an activity.

The following conditions need to be met before partner manager can reject an activity:

  • The activity is planned to specific partner.
  • The activity linked service assignment’s partner dispatching status is NOTIFIED.
  • The activity is not timed out.

Upon the successful request, the patch request will update these fields as below in ServiceAssignment:

  • {“PartnerDispatchingStatus”, null}
  • The activity will be unassigned from the partner.
  • Business event of assignment rejection is triggered.

1.4.3.1 Request

Method URL
POST https://{cluster}.coresuite.com/cloud-partner-dispatch-service/api/partner-dispatch/v1/reject

1.4.3.2 Headers

Header Parameter Value Description Required
Authorization bearer OAuth 2.0 token Required
X-Account-ID accountId The account identifier Required
X-Account-Name accountName The name of the account Required
X-Client-ID clientId Client app identifier Required
X-Client-Version clientVersion The client version Required
X-Company-ID companyid The company identifier Required
X-Company-Name companyName The name of the company Required

1.4.3.3 Request Body

Value Description Type Required
activityId The identifier of activity string Required
technicianid The technician who is responsible for the activity string Required

1.4.3.4 Response

Status Response
201 Created
202 Accepted
401 Unauthorized
403 Forbidden
404 Not Found

1.4.4 Accept Assignment

The Partner manager accepts the activity assigned by Crowd owner.

The following conditions need to be met before partner manager can reject an activity:

  • The activity is planned to specific partner.
  • The activity linked service assignment’s partner dispatching status is NOTIFIED.
  • The activity is not timed out.

Upon the successful request, the patch request will update these fields as below in ServiceAssignment:

  • {“PartnerDispatchingStatus”, “ACCEPTED”}
  • The activity will be unassigned from the partner.
  • Business event of assignment acceptance is triggered.

1.4.4.1 Request

Method URL
POST https://{cluster}.coresuite.com/cloud-partner-dispatch-service/api/partner-dispatch/v1/accept

1.4.4.2 Headers

Header Parameter Value Description Required
Authorization bearer OAuth 2.0 token Required
X-Account-ID accountId The account identifier Required
X-Account-Name accountName The name of the account Required
X-Client-ID clientId Client app identifier Required
X-Client-Version clientVersion The client version Required
X-Company-ID companyid The company identifier Required
X-Company-Name companyName The name of the company Required

1.4.4.3 Request Body

Value Description Type Required
activityId The identifier of activity string Required
technicianid The technician who is responsible for the activity string Required

1.4.4.4 Response

Status Response
201 Created
202 Accepted
401 Unauthorized
403 Forbidden
404 Not Found

1.4.5 Batch Accept Assignment

The Partner manager accepts the activity assigned by Crowd owner.

The following conditions need to be met before partner manager can reject an activity:

  • The activity is planned to specific partner.
  • The activity linked service assignment’s partner dispatching status is NOTIFIED.
  • The activity is not timed out.

Upon the successful request, the patch request will update these fields as below in ServiceAssignment:

  • {“PartnerDispatchingStatus”, “ACCEPTED”}

    Notice: Maximum 50 activities are allowed in each batch accept assignment call.


1.4.5.1 Request

Method URL
POST https://{cluster}.coresuite.com/cloud-partner-dispatch-service/api/partner-dispatch/v1/accept/batch

1.4.5.2 Headers

Header Parameter Value Description Required
Authorization bearer OAuth 2.0 token Required
X-Account-ID accountId The account identifier Required
X-Account-Name accountName The name of the account Required
X-Client-ID clientId Client app identifier Required
X-Client-Version clientVersion The client version Required
X-Company-ID companyid The company identifier Required
X-Company-Name companyName The name of the company Required

1.4.5.3 Request Body

The following is an example body of a batch accept request:

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

1.4.5.4 Reponse

| Status | Response | |—————————|—————–|
| 201 | Created | | 207 | Multi-status:

{
  "hasErrors": true,
  "results": [
    {
      "error": {
        "detail": "string",
        "title": "string",
        "type": "string"
      },
      "resource": {
        "activityId": "string",
        "technicianId": "string"
      },
      "status": 0
    }
  ]
}
 

| | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found |


1.4.6 Release Assignment

The Partner manager releases the activity to his own technician.

The following conditions need to be met before partner manager can release an activity:

  • The activity is planned to specific partner.
  • The activity linked service assignment’s partner dispatching status is ACCEPTED.

Upon the successful request, the patch request will update these fields as below in Activity and ServiceAssignment:

  • Activity {“status”, “OPEN”} {“executionStage”, “EXECUTION”} {“checkedout”, “false”}
  • ServiceAssignment {“State”, “RELEASED”} {“released”, “TRUE”}

1.4.6.1 Request

Method URL
POST https://{cluster}.coresuite.com/cloud-partner-dispatch-service/api/partner-dispatch/v1/release

1.4.6.2 Headers

Header Parameter Value Description Required
Authorization bearer OAuth 2.0 token Required
X-Account-ID accountId The account identifier Required
X-Account-Name accountName The name of the account Required
X-Client-ID clientId Client app identifier Required
X-Client-Version clientVersion The client version Required
X-Company-ID companyid The company identifier Required
X-Company-Name companyName The name of the company Required

1.4.6.3 Request Body

Value Description Type Required
activityId The identifier of activity string Required

1.4.6.4 Response

Status Response
201 Created
202 Accepted
401 Unauthorized
403 Forbidden
404 Not Found