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 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. Array 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 }