12 Service API

Source: This article refers to 12 Service API

12.1 Overview

The Service API enables customers with external systems to:

  • CREATE a new service call and an activity for it,
  • or UPDATE an existing service call.

The requests are posted from a third-party application to SAP Field Service Management, where they can be planned and released to technicians.


12.1.1 Request Methods

Please note the following:

  Note
12.1.1.1 The DELETE method is currently not supported.
12.1.1.2 UPDATE requests only impact the service call. Activities and/or addresses will not be updated.

12.1.2 API Mapping

The Service API uses the following mapping schema between the serviceCall DTO and Activity DTO:

Field in API Required Field in serviceCall Field in Activity
serviceCall.address NO Address will be created for serviceCall but not for Activity  
serviceCall.businessPartner YES SC.businessPartner A.businessPartner
serviceCall.contact NO SC.contact A.contact
serviceCall.createPerson YES SC.createPerson no mapping
serviceCall.dueDateTime YES SC.dueDateTime A.dueDateTime
serviceCall.durationInMinutes NO (15 min by default) SC.durationInMinutes A.durationInMinutes
serviceCall.equipments[] YES but list can be empty SC.equipments[] If here is only one E → A.Equipmentotherwise A.Equipment is empty
serviceCall.idserviceCall.erpIdserviceCall.externalId NO SC.idSC.codeSC.externalId no mapping
serviceCall.lastChanged NO    
serviceCall.status YES SC.statusCode not applicable
serviceCall.origin YES SC.originCode not applicable
serviceCall.problemType YES SC.problemTypeCode not applicable
serviceCall.priority YES SC.priority not applicable
serviceCall.remarks NO SC.remarks A.remarks
serviceCall.resolution NO SC.resolution not applicable
serviceCall.responsibles[] YES SC.responsibles A.responsibles
serviceCall.earliestStartDateTime YES SC.startDateTime A.startDateTime
serviceCall.subject YES SC.subject A.subject

12.1.3 Service API in Swagger

To preview Service API functionality, you may use the SAP Service API Swagger implementation.


12.2 Access

The Service 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.

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


12.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)" } ], } 

12.2.3 Error Response

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

12.2.4 Supported Clusters

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

  • EU
  • DE
  • US
  • CN

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

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

https://{cluster}.coresuite.com

Please note that the example requests contained in this document use the DE cluster. This should be replaced with the cluster associated with your account.


12.3 Create / Update Service Call

Create a serviceCall with Activity or update it, if the serviceCall already exits.

The following diagram depicts the logic for how various IDs are interpreted (Id, erpId, externalId) when creating a service Call:




12.3.1 Request

Method URL
POST de.coresuite.com/api/service-management/v1/ServiceCallWithActivities

12.3.1.1 URL Parameters

Parameter Description Type Required
account The name of the account for which the request is being made. String Required
company The name of the company. The user will be updated for the specified company. String Required

12.3.2 Headers

Header Query Parameter Description Required
X-Request-ID requestId Request identifier Required
X-Client-Version clientVersion The client version Required
Authorization bearer OAuth 2.0 token Required

12.3.3 Body

The following is an example of the body of a PUT request made to the Service API:

{ "serviceCall": { "address": { "city": "string", "country": "string", "state": "string", "street": "string", "streetNumber": "string", "zipCode": "string" }, "businessPartner": {}, "contact": {}, "createPerson": {}, "dueDateTime": "2018-11-21T11:15:02.505Z", "durationInMinutes": 0, "earliestStartDateTime": "2018-11-21T11:15:02.505Z", "equipments": [ {} ], "erpId": "string", "externalId": "string", "id": "string", "lastChanged": 0, "origin": "string", "priority": "string", "problemType": "string", "remarks": "string", "resolution": "string", "responsibles": [ {} ], "status": "string", "subject": "string" } }
Value     Description Type Required
serviceCall       String  
  address     String Required
    city The city associated with the serviceCall address. String  
    country The country associated with the serviceCall address. String  
    state The state associated with the serviceCall address. String  
    street The street associated with the serviceCall address. String  
    streetNumber The street number associated with the serviceCall address String  
    zipCode The zip code associated with the serviceCall address. String  
businessPartner     Business partner to which this serviceCall belongs. String Required
contact     The contact for the business partner. String  
createPerson     The person responsible for creating serviceCall. String Required
dueDateTime     Due date until when this servicecall has to be completed/closed. Datetime Required
durationInMinutes     The expected duration in minutes of the serviceCall or Activity. Integer Default 15 minutes
earliestStartDateTime     The earliest start date/time. Datetime Required
equipments     Equipments which are related to this service call. String Optional
erpId     The ID of the Enterprise Resource Planning (ERP) system. String Optional if creating new serviceCall. Required when updating existing serviceCall
externalId     The externalId of the serviceCall assigned by the ERP. String Optional if creating new serviceCall. Required when updating existing serviceCall
id     The serviceCall ID assigned by Field Service Management. String Optional if creating new serviceCall. Required when updating existing serviceCall
lastChanged     The date/time on which the serviceCall was last changed. Datetime  
origin     The origin of the serviceCall (example: phone, email, etc.). String Required
priority     The priority of the serviceCall. String Required
problemType     The problem type associated with the serviceCall or Activity. String Required
remarks     The remarks associated with the serviceCall or Activity. String  
resolution     The resolution status of the serviceCall or Activity. String  
responsibles     List of person objects (of type erpUsers) which are responsible for this activity. This list is considered by the permission system whenever read/write permission is set to OWN. String  
status     The current status of the serviceCall or Activity. String Required
subject     The subject of the serviceCall or Activity. This is used as the name of the serviceCall or Activity in the Field Service Management application. String Required

12.3.4 Response

Status Response
200 OK
400 Email must be unique!
400 User account not found
400 Bad Request “The [account] parameter is invalid”
400 Bad request - “The [company] parameter is invalid”
401 Unauthorized
403 Forbidden
404 Not found
409 Conflict “Person(s) with username [{0}] could not be created nor updated for the companies {1}”

12.3.5 Example Response

{ "companies": [ { "companyId": 0, "groupId": 0 } ], "created": "2018-06-25T07:07:01.312Z", "email": "string", "firstName": "string", "id": 0, "name": "string", "lastChanged": "2018-06-25T07:07:01.312Z", "lastName": "string", "phone": "string" }

12.7 DELETE Service Call

Note: The DELETE method is currently NOT supported.


Appendix

Relevant Data Transfer Objects

InlinedAddress DTO

{ city string country string state string street string streetNumber string zipCode string }

ServiceRequest DTO

address InlinedAddressDTO{ city string country string state string street string streetNumber string zipCode string } businessPartner UnifiedIdentifier{ erpId string readOnly: true externalId string readOnly: true id string readOnly: true } contact UnifiedIdentifier{ erpId string readOnly: true externalId string readOnly: true id string readOnly: true } createPerson UnifiedIdentifier{ erpId string readOnly: true externalId string readOnly: true id string readOnly: true } dueDateTime string($date-time) durationInMinutes integer($int32) earliestStartDateTime string($date-time) equipments [UnifiedIdentifier{ erpId string readOnly: true externalId string readOnly: true id string readOnly: true }] erpId string externalId string id string lastChanged integer($int64) origin string priority string problemType string remarks string resolution string responsibles [ uniqueItems: true UnifiedIdentifier{ erpId string readOnly: true externalId string readOnly: true id string readOnly: true }] status string subject string }

UnifiedIdentifier DTO

{ erpId string readOnly: true externalId string readOnly: true id string readOnly: true }

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request

Comments

0 comments

Article is closed for comments.