Service API v2 1.1 Overview The Service API enables customers with external systems to make requests from a third-party application to SAP Field Service Management, where they can be planned and released to technicians. 1.1.1 Request Methods The following methods are supported: Note Section 1.1.1.1 POST (create) a new service call and activities with sub-resources for it. 1.3.1 1.1.1.2 PATCH (partially update) an existing service call and/or activities and sub-resources. 1.3.2 1.1.1.3 GET information on a specific service call and related sub-resources 1.3.3 1.1.1.4 GET information on a specific activity and related sub-resources. 1.3.4 1.1.2 Bulk Requests Note Section 1.1.2.1 POST (create) service calls and optional activities and sub-resources in bulk. 1.4.1 1.1.2.2 PATCH (partially update) existing service calls and/or activities and sub-resources in bulk. 1.4.2 1.1.3 Business Actions on Activities The following business actions can be performed on activities in the Service API: Business Action Endpoint Section 1.1.3.1 Cancel activity /v2/activities/{activity-uid}/actions/cancel 1.5.1 1.1.3.2 Close activity /v2/activities/{activity-uid}/actions/close 1.5.2 1.1.3.3. Plan activity /v2/activities/{activity-uid}/actions/plan 1.5.3 1.1.3.4 Release activity /v2/activities/{activity-uid}/actions/release 1.5.4 1.1.3.5 Replan activity /v2/activities/{activity-uid}/actions/replan 1.5.5 1.1.3.6 Unassign activity /v2/activities/{activity-uid}/actions/unassign 1.5.6 1.1.4 Service API in Swagger To preview Service API functionality, you may use the SAP Service API Swagger implementation. 1.1.5 Postman Spec The following file contains the supported methods and endpoints in JSON format which can be uploaded to Postman: 1.1.6 Activity Address Resolution Logic The Service API uses the following resolution logic for activity addresses: Attention: if address is not present then, a PATCH request will create a new one. Current Activity Address, if existing (e.g. Activity coming from ERP) Source Activity Address, if existing (e.g. if Activity is created as copy of another activity) Address of the Equipment linked to the activity, if existing Address of the first Equipment of the service call, if existing BusinessPartner Default ShipTo address type, if any BusinessPartner First ShipTo address type, if any BusinessPartner Default BillTo address type, if any BusinessPartner First BillTo address type, if any BusinessPartner default address, if any 1.1.7 Object Record Identification Logic Please note that the the Service API v2 uses the following logic to determine if an activity, service call or linked resources (business partner, create person, contact, item, equipment, reserved materials, etc) already exist: Object identifiers are resolved in the following order: Value Description 1.1.7.1 id id is used as the primary means of resolving the object identitiy. 1.1.7.2 code For objects that havecode (example: Business Partner), this will be used as a secondary means of identifying an object. 1.1.7.3 externalId externalId is used last to resolve the object identity. Object identitiy resolution is the same for all the objects. If, for example, the following were provided in a POST/PUT request payload: "createPerson": { "code": "code-1" } Or "createPerson": { "externalId": "ext-1" } Then the Service API will need to resolve the createPerson identitiy in order to use it using the resolution sequence described above. 1.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. 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 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, 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 Service API as follows: https://{cluster}.coresystems.net/api/service-management/v2/composite-tree/service-calls 1.3 Standard Requets 1.3.1 POST Service Call with Optional Activities Create a serviceCall with (optional) one or more Activity records. 1.3.1.1 Request Method URL POST https://{cluster}.coresystems.net/api/service-management/v2/composite-tree/service-calls 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-Name companyName The name of the company Required 1.3.1.3 Query Parameters Query Parameter Value Description autoCreateActivity true / false Optional. Default value = true. When true, a default activity record will be created, if no activity has been provided explicitly. 1.3.1.4 Request Body The following are the values contained in a POST request: Value Description Type Required activities If applicable, the activity record/s associated with the serviceCall. address The activity address. city The city in which the activity is located. String country The country in which the activity is located. String location The location of the address expressed in longitude and latitude. latitude The latitude of the address location. Integer longitude The longitude of the address location. Integer source The source of the activity address (BUSINESSPARTNER, EQUIPMENT, SERVICECALL). This is a temporary address that was resolved using the address resolution logic. The source field will indicate from which object the address is coming from. Enumeration. sourceId The ID associated with the activity address source. String state The state in which the activity is located. String street The street in which the activity is located. String streetNumber The streetnumber associated with the activity address. String zipCode The zip code associated with the actrivity address. String code The activity code. This value is automatically created by the system. String contact The contact associated with the activity. String id The contact ID associated with the activity. String code The code associated with the activity contact. String externalId If applicable, the external ID associated with the activity contact. String createPerson If no record for the contact exists, a new person record will be created. id The ID associated with the new person record. String code The code associated with the new person record. String externalId The external ID associated with the person responsible for creating the record. This value must be unique. String dueDateTime The date/time at which the activity is due to be completed. DateTime durationInMinutes The expected duration in minutes of the activity. Integer earliestStartDate The earlest date on which the activity can occur. DateTime equipment The equipment record associated with the activity. id The ID of the equipment record associated with the activitiy. String code The code of the equipment associated with the activity. String externalId The external ID of the equipment associated with the activity. This value must be unique. String externalId The external ID of the activity record. This value must be unique among all activity records. String lastChanged The person responsible for last changing the record. String Region If applicable, in which the activity takes place. id The ID of the region. String code The region code. String externalId The external ID of the region. String remarks The remarks associated with the activity. String requirements The activity requirements inherited Indicates whether or not the requirement was inherited from a service call. Boolean Mandatory Indicates whether the requirement is mandatory (true) or not mandatory (false) Boolean Skill The skill requirement of the activity. id The skill ID. String code The skill code. String externalId The external ID of the skill. String reservedMaterials The reserved materials associated with the activty. Array externalId The externalId of the reserved material. This value must be unique among all reservedMaterial objects. String id The ID of the reserved material. String item The reserved material item. Required id The ID assocaited with the reserved material item. String code The code associated with the reserved material item String externalId The external ID associated with the reserved material item. This value must be unique among all reservedMaterial objects. String moved The amount of reserved materials that have been moved from one warehouse to another. Integer Required (defaults to 0 if not provided) quantity The amount of reserved material items used for the activity. Integer Required serialNumber The serial number of the reserved material item. id The ID of the reserved material item managed by serial number. String code The code of the reserved material item managed by serial number. String externalId The external ID of the reserved material item managedd by serial number. This value must be unique. String shipped If applicable, the amount of reserved material item that have stated "shipped", i.e. ordered but not yet available for usage. Integer udfValues udfMeta The metadata associated with the user-defined field. id The UDF ID. String code The UDF code. String externalID The external ID of the UDF. String value The value contained in the user-defined field (UDF). String Required used The amount of reserved material item/s used during the course of the activity. Integer Required (defaults to 0 if not provided) warehouse The warehouse in which the reserved material/s are stored. A warehouse may also refer to the technician vehicle. Required id The ID of the warehouse. String code The code of the warehouse. String externalId The external ID of the warehouse. This value must be unique. String subject The subject of the activty. String Required udfValues udfMeta The metadata associated with the user-defined field. id The UDF ID. String code The UDF code. String externalID The external ID of the UDF. String value The value contained in the user-defined field (UDF). String Required address The address of the service call. city The city in which the service call is located. String country The country in which the service call is located. String location The location of the address expressed in longitude and latitude. latitude The latitude of the address location. Integer longitude The longitude of the address location. Integer source The source of the service call address (BUSINESSPARTNER, EQUIPMENT). This is a temporary address that was resolved using the address resolution logic. The source field will indicate from which object the address is coming from. Enumeration sourceId The ID associated with the service call address source. String state The state in which the service call is located. String street The street in which the service call is located. String streetNumber The street number associated with the service call street address. String zipCode The zip code associated with the service call address. String businessPartner The business partner associated with the service call. A Business Partner general refers to the customer, but may also refer to a vendor, etc. Required id The business partner ID. String code The business partner code. String externalId The external ID associated with the business partner. This value must be unique. String code The service call code. This code is generated automatically by the system. String Contact The contact associated with the service call. id The ID associated with the service call contact. String code The code associated with the service call contact. String externalId The external ID associated with the service call contact. This value must be unique. String createPerson The user responsible for creating the service call/activity. Optional id The ID associated with the creator of the record. String code The code associated with the new person record. String externalId The external ID associated with the new person record. This value must be unique. String dueDateTime The date/time at which the service call is due to be completed. DateTime durationInMinutes The duration in minutes the service call is expected to last. Integer earliestStartDateTime The earliest date/time on which the service call can be completed. DateTime equipments The equipment record associated with the service call. Optional id The ID of the equipment record associated with the service call. String code The code associated with the service call equipment. String externalId The external ID associated with the service call equipment. This value must be unique. String externalId The external ID associated wth the service call record. This value must be unique among all serviceCall objects. String lastChanged The person responsible for last changing the service call record. Integer origin The origin of the service call (i.e. phone, online, etc). String Optional priority The priority level associated with the service call (example: high, medium, low). String Required problemType The problem type associated with the service call (example: warranty, maintenance, etc.). String remarks The remarks associated with the service call. String requirements The service call requirements inherited Indicates whether or not the requirement was inherited from another service call. Boolean Mandatory Indicates whether the requirement is mandatory (true) or not mandatory (false) Boolean Skill The skill requirement of the activity. id The skill ID. String code The skill code. String externalId The external ID of the skill. String reservedMaterials The reserved materials associated with the service call. externalId The external ID associated with the reserved material item. This value must be unique among all reservedMaterial objects. String id The ID assocaited with the reserved material item. String item The reserved material item. String Required id The ID of the reserved material item. String code The code of the reserved material item. String externalId The external ID of the reserved material item. String moved The amount of reserved materials that have been moved from one warehouse to another. Integer Required (defaults to 0 if not provided) quantity The quantity of reserved material. Integer Required serialNumber If applicable, the reserved material managed by serial number. id The ID of the reserved material item managed by serial number. String code The code of the reserved material item managed by serial number. String externalId The external ID of the reserved material item managed by serial number. String shipped The amount of reserved material items with status "shipped"; i.e., ordered but not yet available for usage. Integer udfValues udfMeta The metadata associated with the user-defined field. id The UDF ID. String code The UDF code. String externalID The external ID of the UDF. String value The value contained in the user-defined field (UDF). String Required used The amount of reserved material item/s used during the course of the service call. Integer Required (defaults to 0 if not provided) warehouse The warehouse in which the reserved material/s are stored. A warehouse may also refer to the technician vehicle. Required id The ID of the warehouse. String code The code of the warehouse. String externalId The external ID of the warehouse. String resolution The resolution status of the service call. String responsibles The technician/s assigned to the service call. id The ID associated with the responsibles assigned to the service call. String code The code associated with the responsible assigned to the service call. String externalId The external ID associated with the responsible assigned to the service call. String serviceContract The service contract associated with the service call. id The ID associated with the service contract assigned to the service call. String code The code associated with the service contract assigned to the service call. String externalId The external ID associated with the service contract assigned to the service call. String status The current status of the service call. String Required subject The subject of the service call. String Required Type The type associated with the service call. String udfValues udfMeta The metadata associated with the user-defined field. id The UDF ID. String code The UDF code. String externalID The external ID of the UDF. String value The value contained in the user-defined field (UDF). String Required 1.3.1.5 Response Status Response 200 OK 401 Unauthorized 403 Forbidden 1.3.1.6 Example Response Body { "activities": [ { "address": { "city": "string", "country": "string", "location": { "latitude": 0, "longitude": 0 }, "source": "ACTIVITY", "sourceId": { "uuid": "string" }, "state": "string", "street": "string", "streetNumber": "string", "zipCode": "string" }, "attachments": [ { "category": "string", "description": "string", "fileName": "string", "id": { "uuid": "string" }, "title": "string", "type": "string" } ], "code": "string", "contact": { "id": "string", "code": "string", "externalId": "string" }, "createPerson": { "id": "string", "code": "string", "externalId": "string" }, "dueDateTime": "2019-10-22T11:07:39.256Z", "durationInMinutes": 0, "earliestStartDateTime": "2019-10-22T11:07:39.256Z", "equipment": { "id": "string", "code": "string", "externalId": "string" }, "executionStage": "string", "externalId": "string", "id": { "uuid": "string" }, "lastChanged": 0, "plannedEndDate": "2019-10-22T11:07:39.256Z", "plannedStartDate": "2019-10-22T11:07:39.256Z", "region": { "id": "string", "code": "string", "externalId": "string" }, "remarks": "string", "requirements": [ { "inherited": true, "mandatory": true, "skill": { "id": "string", "code": "string", "externalId": "string" } } ], "reservedMaterials": [ { "externalId": "string", "id": "string", "item": { "id": "string", "code": "string", "externalId": "string" }, "moved": 0, "quantity": 0, "serialNumber": { "id": "string", "code": "string", "externalId": "string" }, "shipped": 0, "udfValues": [ { "udfMeta": { "id": "string", "code": "string", "externalId": "string" }, "value": "string" } ], "used": 0, "warehouse": { "id": "string", "code": "string", "externalId": "string" } } ], "responsibles": [ { "id": "string", "code": "string", "externalId": "string" } ], "sourceActivity": { "id": "string", "code": "string", "externalId": "string" }, "status": "string", "subject": "string", "type": "string", "udfValues": [ { "udfMeta": { "id": "string", "code": "string", "externalId": "string" }, "value": "string" } ] } ], "address": { "city": "string", "country": "string", "location": { "latitude": 0, "longitude": 0 }, "source": "ACTIVITY", "sourceId": { "uuid": "string" }, "state": "string", "street": "string", "streetNumber": "string", "zipCode": "string" }, "attachments": [ { "category": "string", "description": "string", "fileName": "string", "id": { "uuid": "string" }, "title": "string", "type": "string" } ], "businessPartner": { "id": "string", "code": "string", "externalId": "string" }, "code": "string", "contact": { "id": "string", "code": "string", "externalId": "string" }, "createPerson": { "id": "string", "code": "string", "externalId": "string" }, "dueDateTime": "2019-10-22T11:07:39.256Z", "durationInMinutes": 0, "earliestStartDateTime": "2019-10-22T11:07:39.256Z", "equipments": [ { "id": "string", "code": "string", "externalId": "string" } ], "externalId": "string", "id": { "uuid": "string" }, "lastChanged": 0, "origin": "string", "priority": "string", "problemType": "string", "remarks": "string", "requirements": [ { "inherited": true, "mandatory": true, "skill": { "id": "string", "code": "string", "externalId": "string" } } ], "reservedMaterials": [ { "externalId": "string", "id": "string", "item": { "id": "string", "code": "string", "externalId": "string" }, "moved": 0, "quantity": 0, "serialNumber": { "id": "string", "code": "string", "externalId": "string" }, "shipped": 0, "udfValues": [ { "udfMeta": { "id": "string", "code": "string", "externalId": "string" }, "value": "string" } ], "used": 0, "warehouse": { "id": "string", "code": "string", "externalId": "string" } } ], "resolution": "string", "responsibles": [ { "id": "string", "code": "string", "externalId": "string" } ], "status": "string", "subject": "string", "type": "string", "udfValues": [ { "udfMeta": { "id": "string", "code": "string", "externalId": "string" }, "value": "string" } ] } 1.3.1.7 Response Values Value Description Type Required activities If applicable, the activity record/s associated with the serviceCall. address The activity address. city The city in which the activity is located. String country The country in which the activity is located. String location The location of the address expressed in longitude and latitude. latitude The latitude of the address location. Integer longitude The longitude of the address location. Integer source The source of the activity address (BUSINESSPARTNER, EQUIPMENT, SERVICECALL). This is a temporary address that was resolved using the address resolution logic. The source field will indicate from which object the address is coming from. Enumeration. sourceId The ID associated with the activity address source. String state The state in which the activity is located. String street The street in which the activity is located. String streetNumber The streetnumber associated with the activity address. String zipCode The zip code associated with the actrivity address. String code The activity code. This value is automatically created by the system. String contact The contact associated with the activity. String id The contact ID associated with the activity. String code The code associated with the activity contact. String externalId If applicable, the external ID associated with the activity contact. String createPerson If no record for the contact exists, a new person record will be created. id The ID associated with the new person record. String code The code associated with the new person record. String externalId The external ID associated with the person responsible for creating the record. This value must be unique. String dueDateTime The date/time at which the activity is due to be completed. DateTime durationInMinutes The expected duration in minutes of the activity. Integer earliestStartDate The earlest date on which the activity can occur. DateTime equipment The equipment record associated with the activity. id The ID of the equipment record associated with the activitiy. String code The code of the equipment associated with the activity. String externalId The external ID of the equipment associated with the activity. This value must be unique. String externalId The external ID of the activity record. This value must be unique among all activity records. String lastChanged The person responsible for last changing the record. String Region If applicable, in which the activity takes place. id The ID of the region. String code The region code. String externalId The external ID of the region. String remarks The remarks associated with the activity. String requirements The activity requirements inherited Indicates whether or not the requirement was inherited from a service call. Boolean Mandatory Indicates whether the requirement is mandatory (true) or not mandatory (false) Boolean Skill The skill requirement of the activity. id The skill ID. String code The skill code. String externalId The external ID of the skill. String reservedMaterials The reserved materials associated with the activty. Array externalId The externalId of the reserved material. This value must be unique among all reservedMaterial objects. String id The ID of the reserved material. String item The reserved material item. Required id The ID assocaited with the reserved material item. String code The code associated with the reserved material item String externalId The external ID associated with the reserved material item. This value must be unique among all reservedMaterial objects. String moved The amount of reserved materials that have been moved from one warehouse to another. Integer Required (defaults to 0 if not provided) quantity The amount of reserved material items used for the activity. Integer Required serialNumber The serial number of the reserved material item. id The ID of the reserved material item managed by serial number. String code The code of the reserved material item managed by serial number. String externalId The external ID of the reserved material item managedd by serial number. This value must be unique. String shipped If applicable, the amount of reserved material item that have stated "shipped", i.e. ordered but not yet available for usage. Integer udfValues udfMeta The metadata associated with the user-defined field. id The UDF ID. String code The UDF code. String externalID The external ID of the UDF. String value The value contained in the user-defined field (UDF). String Required used The amount of reserved material item/s used during the course of the activity. Integer Required (defaults to 0 if not provided) warehouse The warehouse in which the reserved material/s are stored. A warehouse may also refer to the technician vehicle. Required id The ID of the warehouse. String code The code of the warehouse. String externalId The external ID of the warehouse. This value must be unique. String subject The subject of the activty. String Required udfValues udfMeta The metadata associated with the user-defined field. id The UDF ID. String code The UDF code. String externalID The external ID of the UDF. String value The value contained in the user-defined field (UDF). String Required address The address of the service call. city The city in which the service call is located. String country The country in which the service call is located. String location The location of the address expressed in longitude and latitude. latitude The latitude of the address location. Integer longitude The longitude of the address location. Integer source The source of the service call address (BUSINESSPARTNER, EQUIPMENT). This is a temporary address that was resolved using the address resolution logic. The source field will indicate from which object the address is coming from. Enumeration sourceId The ID associated with the service call address source. String state The state in which the service call is located. String street The street in which the service call is located. String streetNumber The street number associated with the service call street address. String zipCode The zip code associated with the service call address. String businessPartner The business partner associated with the service call. A Business Partner general refers to the customer, but may also refer to a vendor, etc. Required id The business partner ID. String code The business partner code. String externalId The external ID associated with the business partner. This value must be unique. String code The service call code. This code is generated automatically by the system. String Contact The contact associated with the service call. id The ID associated with the service call contact. String code The code associated with the service call contact. String externalId The external ID associated with the service call contact. This value must be unique. String createPerson The user responsible for creating the service call/activity. Optional id The ID associated with the creator of the record. String code The code associated with the new person record. String externalId The external ID associated with the new person record. This value must be unique. String dueDateTime The date/time at which the service call is due to be completed. DateTime durationInMinutes The duration in minutes the service call is expected to last. Integer earliestStartDateTime The earliest date/time on which the service call can be completed. DateTime equipments The equipment record associated with the service call. Optional id The ID of the equipment record associated with the service call. String code The code associated with the service call equipment. String externalId The external ID associated with the service call equipment. This value must be unique. String externalId The external ID associated wth the service call record. This value must be unique among all serviceCall objects. String lastChanged The person responsible for last changing the service call record. Integer origin The origin of the service call (i.e. phone, online, etc). String Optional priority The priority level associated with the service call (example: high, medium, low). String Required problemType The problem type associated with the service call (example: warranty, maintenance, etc.). String remarks The remarks associated with the service call. String requirements The service call requirements inherited Indicates whether or not the requirement was inherited from another service call. Boolean Mandatory Indicates whether the requirement is mandatory (true) or not mandatory (false) Boolean Skill The skill requirement of the activity. id The skill ID. String code The skill code. String externalId The external ID of the skill. String reservedMaterials The reserved materials associated with the service call. externalId The external ID associated with the reserved material item. This value must be unique among all reservedMaterial objects. String id The ID assocaited with the reserved material item. String item The reserved material item. String Required id The ID of the reserved material item. String code The code of the reserved material item. String externalId The external ID of the reserved material item. String moved The amount of reserved materials that have been moved from one warehouse to another. Integer Required (defaults to 0 if not provided) quantity The quantity of reserved material. Integer Required serialNumber If applicable, the reserved material managed by serial number. id The ID of the reserved material item managed by serial number. String code The code of the reserved material item managed by serial number. String externalId The external ID of the reserved material item managed by serial number. String shipped The amount of reserved material items with status "shipped"; i.e., ordered but not yet available for usage. Integer udfValues udfMeta The metadata associated with the user-defined field. id The UDF ID. String code The UDF code. String externalID The external ID of the UDF. String value The value contained in the user-defined field (UDF). String Required used The amount of reserved material item/s used during the course of the service call. Integer Required (defaults to 0 if not provided) warehouse The warehouse in which the reserved material/s are stored. A warehouse may also refer to the technician vehicle. Required id The ID of the warehouse. String code The code of the warehouse. String externalId The external ID of the warehouse. String resolution The resolution status of the service call. String responsibles The technician/s assigned to the service call. id The ID associated with the responsibles assigned to the service call. String code The code associated with the responsible assigned to the service call. String externalId The external ID associated with the responsible assigned to the service call. String serviceContract The service contract associated with the service call. id The ID associated with the service contract assigned to the service call. String code The code associated with the service contract assigned to the service call. String externalId The external ID associated with the service contract assigned to the service call. String status The current status of the service call. String Required subject The subject of the service call. String Required Type The type associated with the service call. String udfValues udfMeta The metadata associated with the user-defined field. id The UDF ID. String code The UDF code. String externalID The external ID of the UDF. String value The value contained in the user-defined field (UDF). String Required 1.3.2 PATCH Service Call and Sub-resources Partially update the serviceCall and associated activities and reserved materials. Please note the following: Note 1.3.2.0.1 If no modification is desired, do not pass collection at all, or pass null. 1.3.2.0.2 If new elements are to be added, do not provide any kind of ID in their body or provide a non-existent ID. 1.3.2.0.3 If existing elements are to be modified, provide a valid ID along with the updated content. 1.3.2.0.4 PATCH requests use forceUpdate=true. Example Let’s assume Service Call has three Activities, and we want to update the one which has externalId = 1 and leave the rest intact: "activities": [ { "externalId": "1", "subject": "Updated subject"}, { "externalId": "2"}, { "externalId": "3"} ] 1.3.2.1 Request Method URL PATCH https://{cluster}.coresystems.net/api/service-management/v2/composite-tree/service-calls/{service-call-uid} 1.3.2.2 URL Parameters Parameter Description Type Required {service-call-uid} The ID of the service call record created via PATCH 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-Name companyName The name of the company Required 1.3.2.4 Request Body The following are the values contained in a PATCH request: Value Description Type Required activities If applicable, the activity record/s associated with the serviceCall. address The activity address. city The city in which the activity is located. String country The country in which the activity is located. String location The location of the address expressed in longitude and latitude. latitude The latitude of the address location. Integer longitude The longitude of the address location. Integer source The source of the activity address (BUSINESSPARTNER, EQUIPMENT, SERVICECALL). This is a temporary address that was resolved using the address resolution logic. The source field will indicate from which object the address is coming from. Enumeration. sourceId The ID associated with the activity address source. String state The state in which the activity is located. String street The street in which the activity is located. String streetNumber The streetnumber associated with the activity address. String zipCode The zip code associated with the actrivity address. String code The activity code. This value is automatically created by the system. String contact The contact associated with the activity. String id The contact ID associated with the activity. String code The code associated with the activity contact. String externalId If applicable, the external ID associated with the activity contact. String createPerson If no record for the contact exists, a new person record will be created. id The ID associated with the new person record. String code The code associated with the new person record. String externalId The external ID associated with the person responsible for creating the record. This value must be unique. String dueDateTime The date/time at which the activity is due to be completed. DateTime durationInMinutes The expected duration in minutes of the activity. Integer earliestStartDate The earlest date on which the activity can occur. DateTime equipment The equipment record associated with the activity. id The ID of the equipment record associated with the activitiy. String code The code of the equipment associated with the activity. String externalId The external ID of the equipment associated with the activity. This value must be unique. String externalId The external ID of the activity record. This value must be unique among all activity records. String lastChanged The person responsible for last changing the record. String Region If applicable, in which the activity takes place. id The ID of the region. String code The region code. String externalId The external ID of the region. String remarks The remarks associated with the activity. String requirements The activity requirements inherited Indicates whether or not the requirement was inherited from a service call. Boolean Mandatory Indicates whether the requirement is mandatory (true) or not mandatory (false) Boolean Skill The skill requirement of the activity. id The skill ID. String code The skill code. String externalId The external ID of the skill. String reservedMaterials The reserved materials associated with the activty. Array externalId The externalId of the reserved material. This value must be unique among all reservedMaterial objects. String id The ID of the reserved material. String item The reserved material item. Required id The ID assocaited with the reserved material item. String code The code associated with the reserved material item String externalId The external ID associated with the reserved material item. This value must be unique among all reservedMaterial objects. String moved The amount of reserved materials that have been moved from one warehouse to another. Integer Required (defaults to 0 if not provided) quantity The amount of reserved material items used for the activity. Integer Required serialNumber The serial number of the reserved material item. id The ID of the reserved material item managed by serial number. String code The code of the reserved material item managed by serial number. String externalId The external ID of the reserved material item managedd by serial number. This value must be unique. String shipped If applicable, the amount of reserved material item that have stated "shipped", i.e. ordered but not yet available for usage. Integer udfValues udfMeta The metadata associated with the user-defined field. id The UDF ID. String code The UDF code. String externalID The external ID of the UDF. String value The value contained in the user-defined field (UDF). String Required used The amount of reserved material item/s used during the course of the activity. Integer Required (defaults to 0 if not provided) warehouse The warehouse in which the reserved material/s are stored. A warehouse may also refer to the technician vehicle. Required id The ID of the warehouse. String code The code of the warehouse. String externalId The external ID of the warehouse. This value must be unique. String subject The subject of the activty. String Required udfValues udfMeta The metadata associated with the user-defined field. id The UDF ID. String code The UDF code. String externalID The external ID of the UDF. String value The value contained in the user-defined field (UDF). String Required address The address of the service call. city The city in which the service call is located. String country The country in which the service call is located. String location The location of the address expressed in longitude and latitude. latitude The latitude of the address location. Integer longitude The longitude of the address location. Integer source The source of the service call address (BUSINESSPARTNER, EQUIPMENT). This is a temporary address that was resolved using the address resolution logic. The source field will indicate from which object the address is coming from. Enumeration sourceId The ID associated with the service call address source. String state The state in which the service call is located. String street The street in which the service call is located. String streetNumber The street number associated with the service call street address. String zipCode The zip code associated with the service call address. String businessPartner The business partner associated with the service call. A Business Partner general refers to the customer, but may also refer to a vendor, etc. Required id The business partner ID. String code The business partner code. String externalId The external ID associated with the business partner. This value must be unique. String code The service call code. This code is generated automatically by the system. String Contact The contact associated with the service call. id The ID associated with the service call contact. String code The code associated with the service call contact. String externalId The external ID associated with the service call contact. This value must be unique. String createPerson The user responsible for creating the service call/activity. Optional id The ID associated with the creator of the record. String code The code associated with the new person record. String externalId The external ID associated with the new person record. This value must be unique. String dueDateTime The date/time at which the service call is due to be completed. DateTime durationInMinutes The duration in minutes the service call is expected to last. Integer earliestStartDateTime The earliest date/time on which the service call can be completed. DateTime equipments The equipment record associated with the service call. Optional id The ID of the equipment record associated with the service call. String code The code associated with the service call equipment. String externalId The external ID associated with the service call equipment. This value must be unique. String externalId The external ID associated wth the service call record. This value must be unique among all serviceCall objects. String lastChanged The person responsible for last changing the service call record. Integer origin The origin of the service call (i.e. phone, online, etc). String Optional priority The priority level associated with the service call (example: high, medium, low). String Required problemType The problem type associated with the service call (example: warranty, maintenance, etc.). String remarks The remarks associated with the service call. String requirements The service call requirements inherited Indicates whether or not the requirement was inherited from another service call. Boolean Mandatory Indicates whether the requirement is mandatory (true) or not mandatory (false) Boolean Skill The skill requirement of the activity. id The skill ID. String code The skill code. String externalId The external ID of the skill. String reservedMaterials The reserved materials associated with the service call. externalId The external ID associated with the reserved material item. This value must be unique among all reservedMaterial objects. String id The ID assocaited with the reserved material item. String item The reserved material item. String Required id The ID of the reserved material item. String code The code of the reserved material item. String externalId The external ID of the reserved material item. String moved The amount of reserved materials that have been moved from one warehouse to another. Integer Required (defaults to 0 if not provided) quantity The quantity of reserved material. Integer Required serialNumber If applicable, the reserved material managed by serial number. id The ID of the reserved material item managed by serial number. String code The code of the reserved material item managed by serial number. String externalId The external ID of the reserved material item managed by serial number. String shipped The amount of reserved material items with status "shipped"; i.e., ordered but not yet available for usage. Integer udfValues udfMeta The metadata associated with the user-defined field. id The UDF ID. String code The UDF code. String externalID The external ID of the UDF. String value The value contained in the user-defined field (UDF). String Required used The amount of reserved material item/s used during the course of the service call. Integer Required (defaults to 0 if not provided) warehouse The warehouse in which the reserved material/s are stored. A warehouse may also refer to the technician vehicle. Required id The ID of the warehouse. String code The code of the warehouse. String externalId The external ID of the warehouse. String resolution The resolution status of the service call. String responsibles The technician/s assigned to the service call. id The ID associated with the responsibles assigned to the service call. String code The code associated with the responsible assigned to the service call. String externalId The external ID associated with the responsible assigned to the service call. String serviceContract The service contract associated with the service call. id The ID associated with the service contract assigned to the service call. String code The code associated with the service contract assigned to the service call. String externalId The external ID associated with the service contract assigned to the service call. String status The current status of the service call. String Required subject The subject of the service call. String Required Type The type associated with the service call. String udfValues udfMeta The metadata associated with the user-defined field. id The UDF ID. String code The UDF code. String externalID The external ID of the UDF. String value The value contained in the user-defined field (UDF). String Required 1.3.2.5 Response Status Response 200 OK 204 No content 401 Unauthorized 403 Forbidden 1.3.2.6 Example Response Body { "activities": [ { "address": { "city": "string", "country": "string", "location": { "latitude": 0, "longitude": 0 }, "source": "ACTIVITY", "sourceId": { "uuid": "string" }, "state": "string", "street": "string", "streetNumber": "string", "zipCode": "string" }, "attachments": [ { "category": "string", "description": "string", "fileName": "string", "id": { "uuid": "string" }, "title": "string", "type": "string" } ], "code": "string", "contact": { "id": "string", "code": "string", "externalId": "string" }, "createPerson": { "id": "string", "code": "string", "externalId": "string" }, "dueDateTime": "2019-10-22T11:18:13.498Z", "durationInMinutes": 0, "earliestStartDateTime": "2019-10-22T11:18:13.498Z", "equipment": { "id": "string", "code": "string", "externalId": "string" }, "executionStage": "string", "externalId": "string", "id": { "uuid": "string" }, "lastChanged": 0, "plannedEndDate": "2019-10-22T11:18:13.498Z", "plannedStartDate": "2019-10-22T11:18:13.498Z", "region": { "id": "string", "code": "string", "externalId": "string" }, "remarks": "string", "requirements": [ { "inherited": true, "mandatory": true, "skill": { "id": "string", "code": "string", "externalId": "string" } } ], "reservedMaterials": [ { "externalId": "string", "id": "string", "item": { "id": "string", "code": "string", "externalId": "string" }, "moved": 0, "quantity": 0, "serialNumber": { "id": "string", "code": "string", "externalId": "string" }, "shipped": 0, "udfValues": [ { "udfMeta": { "id": "string", "code": "string", "externalId": "string" }, "value": "string" } ], "used": 0, "warehouse": { "id": "string", "code": "string", "externalId": "string" } } ], "responsibles": [ { "id": "string", "code": "string", "externalId": "string" } ], "sourceActivity": { "id": "string", "code": "string", "externalId": "string" }, "status": "string", "subject": "string", "type": "string", "udfValues": [ { "udfMeta": { "id": "string", "code": "string", "externalId": "string" }, "value": "string" } ] } ], "address": { "city": "string", "country": "string", "location": { "latitude": 0, "longitude": 0 }, "source": "ACTIVITY", "sourceId": { "uuid": "string" }, "state": "string", "street": "string", "streetNumber": "string", "zipCode": "string" }, "attachments": [ { "category": "string", "description": "string", "fileName": "string", "id": { "uuid": "string" }, "title": "string", "type": "string" } ], "businessPartner": { "id": "string", "code": "string", "externalId": "string" }, "code": "string", "contact": { "id": "string", "code": "string", "externalId": "string" }, "createPerson": { "id": "string", "code": "string", "externalId": "string" }, "dueDateTime": "2019-10-22T11:18:13.498Z", "durationInMinutes": 0, "earliestStartDateTime": "2019-10-22T11:18:13.498Z", "equipments": [ { "id": "string", "code": "string", "externalId": "string" } ], "externalId": "string", "id": { "uuid": "string" }, "lastChanged": 0, "origin": "string", "priority": "string", "problemType": "string", "remarks": "string", "requirements": [ { "inherited": true, "mandatory": true, "skill": { "id": "string", "code": "string", "externalId": "string" } } ], "reservedMaterials": [ { "externalId": "string", "id": "string", "item": { "id": "string", "code": "string", "externalId": "string" }, "moved": 0, "quantity": 0, "serialNumber": { "id": "string", "code": "string", "externalId": "string" }, "shipped": 0, "udfValues": [ { "udfMeta": { "id": "string", "code": "string", "externalId": "string" }, "value": "string" } ], "used": 0, "warehouse": { "id": "string", "code": "string", "externalId": "string" } } ], "resolution": "string", "responsibles": [ { "id": "string", "code": "string", "externalId": "string" } ], "status": "string", "subject": "string", "type": "string", "udfValues": [ { "udfMeta": { "id": "string", "code": "string", "externalId": "string" }, "value": "string" } ] } 1.3.2.7 Response Values Value Description Type Required activities If applicable, the activity record/s associated with the serviceCall. address The activity address. city The city in which the activity is located. String country The country in which the activity is located. String location The location of the address expressed in longitude and latitude. latitude The latitude of the address location. Integer longitude The longitude of the address location. Integer source The source of the activity address (BUSINESSPARTNER, EQUIPMENT, SERVICECALL). This is a temporary address that was resolved using the address resolution logic. The source field will indicate from which object the address is coming from. Enumeration. sourceId The ID associated with the activity address source. String state The state in which the activity is located. String street The street in which the activity is located. String streetNumber The streetnumber associated with the activity address. String zipCode The zip code associated with the actrivity address. String code The activity code. This value is automatically created by the system. String contact The contact associated with the activity. String id The contact ID associated with the activity. String code The code associated with the activity contact. String externalId If applicable, the external ID associated with the activity contact. String createPerson If no record for the contact exists, a new person record will be created. id The ID associated with the new person record. String code The code associated with the new person record. String externalId The external ID associated with the person responsible for creating the record. This value must be unique. String dueDateTime The date/time at which the activity is due to be completed. DateTime durationInMinutes The expected duration in minutes of the activity. Integer earliestStartDate The earlest date on which the activity can occur. DateTime equipment The equipment record associated with the activity. id The ID of the equipment record associated with the activitiy. String code The code of the equipment associated with the activity. String externalId The external ID of the equipment associated with the activity. This value must be unique. String externalId The external ID of the activity record. This value must be unique among all activity records. String lastChanged The person responsible for last changing the record. String Region If applicable, in which the activity takes place. id The ID of the region. String code The region code. String externalId The external ID of the region. String remarks The remarks associated with the activity. String requirements The activity requirements inherited Indicates whether or not the requirement was inherited from a service call. Boolean Mandatory Indicates whether the requirement is mandatory (true) or not mandatory (false) Boolean Skill The skill requirement of the activity. id The skill ID. String code The skill code. String externalId The external ID of the skill. String reservedMaterials The reserved materials associated with the activty. Array externalId The externalId of the reserved material. This value must be unique among all reservedMaterial objects. String id The ID of the reserved material. String item The reserved material item. Required id The ID assocaited with the reserved material item. String code The code associated with the reserved material item String externalId The external ID associated with the reserved material item. This value must be unique among all reservedMaterial objects. String moved The amount of reserved materials that have been moved from one warehouse to another. Integer Required (defaults to 0 if not provided) quantity The amount of reserved material items used for the activity. Integer Required serialNumber The serial number of the reserved material item. id The ID of the reserved material item managed by serial number. String code The code of the reserved material item managed by serial number. String externalId The external ID of the reserved material item managedd by serial number. This value must be unique. String shipped If applicable, the amount of reserved material item that have stated "shipped", i.e. ordered but not yet available for usage. Integer udfValues udfMeta The metadata associated with the user-defined field. id The UDF ID. String code The UDF code. String externalID The external ID of the UDF. String value The value contained in the user-defined field (UDF). String Required used The amount of reserved material item/s used during the course of the activity. Integer Required (defaults to 0 if not provided) warehouse The warehouse in which the reserved material/s are stored. A warehouse may also refer to the technician vehicle. Required id The ID of the warehouse. String code The code of the warehouse. String externalId The external ID of the warehouse. This value must be unique. String subject The subject of the activty. String Required udfValues udfMeta The metadata associated with the user-defined field. id The UDF ID. String code The UDF code. String externalID The external ID of the UDF. String value The value contained in the user-defined field (UDF). String Required address The address of the service call. city The city in which the service call is located. String country The country in which the service call is located. String location The location of the address expressed in longitude and latitude. latitude The latitude of the address location. Integer longitude The longitude of the address location. Integer source The source of the service call address (BUSINESSPARTNER, EQUIPMENT). This is a temporary address that was resolved using the address resolution logic. The source field will indicate from which object the address is coming from. Enumeration sourceId The ID associated with the service call address source. String state The state in which the service call is located. String street The street in which the service call is located. String streetNumber The street number associated with the service call street address. String zipCode The zip code associated with the service call address. String businessPartner The business partner associated with the service call. A Business Partner general refers to the customer, but may also refer to a vendor, etc. Required id The business partner ID. String code The business partner code. String externalId The external ID associated with the business partner. This value must be unique. String code The service call code. This code is generated automatically by the system. String Contact The contact associated with the service call. id The ID associated with the service call contact. String code The code associated with the service call contact. String externalId The external ID associated with the service call contact. This value must be unique. String createPerson The user responsible for creating the service call/activity. Optional id The ID associated with the creator of the record. String code The code associated with the new person record. String externalId The external ID associated with the new person record. This value must be unique. String dueDateTime The date/time at which the service call is due to be completed. DateTime durationInMinutes The duration in minutes the service call is expected to last. Integer earliestStartDateTime The earliest date/time on which the service call can be completed. DateTime equipments The equipment record associated with the service call. Optional id The ID of the equipment record associated with the service call. String code The code associated with the service call equipment. String externalId The external ID associated with the service call equipment. This value must be unique. String externalId The external ID associated wth the service call record. This value must be unique among all serviceCall objects. String lastChanged The person responsible for last changing the service call record. Integer origin The origin of the service call (i.e. phone, online, etc). String Optional priority The priority level associated with the service call (example: high, medium, low). String Required problemType The problem type associated with the service call (example: warranty, maintenance, etc.). String remarks The remarks associated with the service call. String requirements The service call requirements inherited Indicates whether or not the requirement was inherited from another service call. Boolean Mandatory Indicates whether the requirement is mandatory (true) or not mandatory (false) Boolean Skill The skill requirement of the activity. id The skill ID. String code The skill code. String externalId The external ID of the skill. String reservedMaterials The reserved materials associated with the service call. externalId The external ID associated with the reserved material item. This value must be unique among all reservedMaterial objects. String id The ID assocaited with the reserved material item. String item The reserved material item. String Required id The ID of the reserved material item. String code The code of the reserved material item. String externalId The external ID of the reserved material item. String moved The amount of reserved materials that have been moved from one warehouse to another. Integer Required (defaults to 0 if not provided) quantity The quantity of reserved material. Integer Required serialNumber If applicable, the reserved material managed by serial number. id The ID of the reserved material item managed by serial number. String code The code of the reserved material item managed by serial number. String externalId The external ID of the reserved material item managed by serial number. String shipped The amount of reserved material items with status "shipped"; i.e., ordered but not yet available for usage. Integer udfValues udfMeta The metadata associated with the user-defined field. id The UDF ID. String code The UDF code. String externalID The external ID of the UDF. String value The value contained in the user-defined field (UDF). String Required used The amount of reserved material item/s used during the course of the service call. Integer Required (defaults to 0 if not provided) warehouse The warehouse in which the reserved material/s are stored. A warehouse may also refer to the technician vehicle. Required id The ID of the warehouse. String code The code of the warehouse. String externalId The external ID of the warehouse. String resolution The resolution status of the service call. String responsibles The technician/s assigned to the service call. id The ID associated with the responsibles assigned to the service call. String code The code associated with the responsible assigned to the service call. String externalId The external ID associated with the responsible assigned to the service call. String serviceContract The service contract associated with the service call. id The ID associated with the service contract assigned to the service call. String code The code associated with the service contract assigned to the service call. String externalId The external ID associated with the service contract assigned to the service call. String status The current status of the service call. String Required subject The subject of the service call. String Required Type The type associated with the service call. String udfValues udfMeta The metadata associated with the user-defined field. id The UDF ID. String code The UDF code. String externalID The external ID of the UDF. String value The value contained in the user-defined field (UDF). String Required 1.3.3 GET Service Call and Sub-resources Get the service call and its sub-resources. 1.3.3.1 Request Method URL GET https://{cluster}.coresystems.net/api/service-management/v2/composite-tree/service-calls/{service-call-uid} 1.3.3.2 URL Parameters Parameter Description Type Required {service-call-uid} The unique ID of the service call record created via POST request you wish to retrieve. String Required 1.3.3.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-Name companyName The name of the company Required 1.3.3.4 Response Status Response 200 OK 401 Unauthorized 403 Forbidden 404 Not found 1.3.3.5 Example Response Body { "activities": [ { "address": { "city": "string", "country": "string", "location": { "latitude": 0, "longitude": 0 }, "source": "ACTIVITY", "sourceId": { "uuid": "string" }, "state": "string", "street": "string", "streetNumber": "string", "zipCode": "string" }, "attachments": [ { "category": "string", "description": "string", "fileName": "string", "id": { "uuid": "string" }, "title": "string", "type": "string" } ], "code": "string", "contact": { "id": "string", "code": "string", "externalId": "string" }, "createPerson": { "id": "string", "code": "string", "externalId": "string" }, "dueDateTime": "2019-10-22T11:19:04.734Z", "durationInMinutes": 0, "earliestStartDateTime": "2019-10-22T11:19:04.734Z", "equipment": { "id": "string", "code": "string", "externalId": "string" }, "executionStage": "string", "externalId": "string", "id": { "uuid": "string" }, "lastChanged": 0, "plannedEndDate": "2019-10-22T11:19:04.734Z", "plannedStartDate": "2019-10-22T11:19:04.734Z", "region": { "id": "string", "code": "string", "externalId": "string" }, "remarks": "string", "requirements": [ { "inherited": true, "mandatory": true, "skill": { "id": "string", "code": "string", "externalId": "string" } } ], "reservedMaterials": [ { "externalId": "string", "id": "string", "item": { "id": "string", "code": "string", "externalId": "string" }, "moved": 0, "quantity": 0, "serialNumber": { "id": "string", "code": "string", "externalId": "string" }, "shipped": 0, "udfValues": [ { "udfMeta": { "id": "string", "code": "string", "externalId": "string" }, "value": "string" } ], "used": 0, "warehouse": { "id": "string", "code": "string", "externalId": "string" } } ], "responsibles": [ { "id": "string", "code": "string", "externalId": "string" } ], "sourceActivity": { "id": "string", "code": "string", "externalId": "string" }, "status": "string", "subject": "string", "type": "string", "udfValues": [ { "udfMeta": { "id": "string", "code": "string", "externalId": "string" }, "value": "string" } ] } ], "address": { "city": "string", "country": "string", "location": { "latitude": 0, "longitude": 0 }, "source": "ACTIVITY", "sourceId": { "uuid": "string" }, "state": "string", "street": "string", "streetNumber": "string", "zipCode": "string" }, "attachments": [ { "category": "string", "description": "string", "fileName": "string", "id": { "uuid": "string" }, "title": "string", "type": "string" } ], "businessPartner": { "id": "string", "code": "string", "externalId": "string" }, "code": "string", "contact": { "id": "string", "code": "string", "externalId": "string" }, "createPerson": { "id": "string", "code": "string", "externalId": "string" }, "dueDateTime": "2019-10-22T11:19:04.734Z", "durationInMinutes": 0, "earliestStartDateTime": "2019-10-22T11:19:04.734Z", "equipments": [ { "id": "string", "code": "string", "externalId": "string" } ], "externalId": "string", "id": { "uuid": "string" }, "lastChanged": 0, "origin": "string", "priority": "string", "problemType": "string", "remarks": "string", "requirements": [ { "inherited": true, "mandatory": true, "skill": { "id": "string", "code": "string", "externalId": "string" } } ], "reservedMaterials": [ { "externalId": "string", "id": "string", "item": { "id": "string", "code": "string", "externalId": "string" }, "moved": 0, "quantity": 0, "serialNumber": { "id": "string", "code": "string", "externalId": "string" }, "shipped": 0, "udfValues": [ { "udfMeta": { "id": "string", "code": "string", "externalId": "string" }, "value": "string" } ], "used": 0, "warehouse": { "id": "string", "code": "string", "externalId": "string" } } ], "resolution": "string", "responsibles": [ { "id": "string", "code": "string", "externalId": "string" } ], "status": "string", "subject": "string", "type": "string", "udfValues": [ { "udfMeta": { "id": "string", "code": "string", "externalId": "string" }, "value": "string" } ] } 1.3.3.6 Response Values The following values may be included in a GET Service Call response: Value Description Type Required activities If applicable, the activity record/s associated with the serviceCall. address The activity address. city The city in which the activity is located. String country The country in which the activity is located. String Location The location of the address expressed in longitude and latitude. Latitude The latitude of the address location. Integer Longitude The longitude of the address location. Integer source The source of the activity address (BUSINESSPARTNER, EQUIPMENT, SERVICECALL). This is a temporary address that was resolved using the address resolution logic. The source field will indicate from which object the address is coming from. Enumeration. sourceId The ID associated with the activity address source. String state The state in which the activity is located. String street The street in which the activity is located. String streetNumber The streetnumber associated with the activity address. String zipCode The zip code associated with the actrivity address. String attachments category The category of the attachment. String description The description of the attachment. String fileName The file name of the attachment. String id The id of the attachment. uuid The uuid of the attachment. String title The title of the attachment. String Type The attachment type. String code The activity code. This value is automatically created by the system. String contact The contact associated with the activity. String id The contact ID associated with the activity. String code The code associated with the activity contact. String externalId If applicable, the external ID associated with the activity contact. String createPerson If no record for the contact exists, a new person record will be created. id The ID associated with the new person record. String code The code associated with the new person record. String externalId The external ID associated with the person responsible for creating the record. This value must be unique. String dueDateTime The date/time at which the activity is due to be completed. DateTime durationInMinutes The expected duration in minutes of the activity. Integer earliestStartDate The earlest date on which the activity can occur. DateTime equipment The equipment record associated with the activity. id The ID of the equipment record associated with the activitiy. String code The code of the equipment associated with the activity. String externalId The external ID of the equipment associated with the activity. This value must be unique. String externalId The external ID of the activity record. This value must be unique among all activity records. String lastChanged The person responsible for last changing the record. String plannedStartDate Read-only. The planned start date. dateTime plannedEndDate Read-only. The planned end date. dateTime Region If applicable, in which the activity takes place. id The ID of the region. String code The region code. String externalId The external ID of the region. String remarks The remarks associated with the activity. String requirements The activity requirements inherited Indicates whether or not the requirement was inherited from a service call. Boolean Mandatory Indicates whether the requirement is mandatory (true) or not mandatory (false) Boolean Skill The skill requirement of the activity. id The skill ID. String code The skill code. String externalId The external ID of the skill. String reservedMaterials The reserved materials associated with the activty. Array externalId The externalId of the reserved material. This value must be unique among all reservedMaterial objects. String id The ID of the reserved material. String item The reserved material item. Required id The ID assocaited with the reserved material item. String code The code associated with the reserved material item String externalId The external ID associated with the reserved material item. This value must be unique among all reservedMaterial objects. String moved The amount of reserved materials that have been moved from one warehouse to another. Integer Required (defaults to 0 if not provided) quantity The amount of reserved material items used for the activity. Integer Required serialNumber The serial number of the reserved material item. id The ID of the reserved material item managed by serial number. String code The code of the reserved material item managed by serial number. String externalId The external ID of the reserved material item managedd by serial number. This value must be unique. String shipped If applicable, the amount of reserved material item that have stated "shipped", i.e. ordered but not yet available for usage. Integer udfValues udfMeta The metadata associated with the user-defined field. id The UDF ID. String code The UDF code. String externalID The external ID of the UDF. String value The value contained in the user-defined field (UDF). used The amount of reserved material item/s used during the course of the activity. Integer Required (defaults to 0 if not provided) warehouse The warehouse in which the reserved material/s are stored. A warehouse may also refer to the technician vehicle. Required id The ID of the warehouse. String code The code of the warehouse. String externalId The external ID of the warehouse. This value must be unique. String subject The subject of the activty. String Required udfValues udfMeta The metadata associated with the user-defined field. id The UDF ID. String code The UDF code. String externalID The external ID of the UDF. String value The value contained in the user-defined field (UDF). address The address of the service call. city The city in which the service call is located. String country The country in which the service call is located. String location The location of the address expressed in longitude and latitude. latitude The latitude of the address location. Integer longitude The longitude of the address location. Integer source The source of the service call address (BUSINESSPARTNER, EQUIPMENT). This is a temporary address that was resolved using the address resolution logic. The source field will indicate from which object the address is coming from. Enumeration sourceId The ID associated with the service call address source. String state The state in which the service call is located. String street The street in which the service call is located. String streetNumber The street number associated with the service call street address. String zipCode The zip code associated with the service call address. String attachments category The category of the attachment. String description The description of the attachment. String fileName The file name of the attachment. String id The id of the attachment. uuid The uuid of the attachment. String title The title of the attachment. String type The attachment type. String businessPartner The business partner associated with the service call. A Business Partner general refers to the customer, but may also refer to a vendor, etc. Required id The business partner ID. String code The business partner code. String externalId The external ID associated with the business partner. This value must be unique. String code The service call code. This code is generated automatically by the system. String Contact The contact associated with the service call. id The ID associated with the service call contact. String code The code associated with the service call contact. String externalId The external ID associated with the service call contact. This value must be unique. String createPerson The user responsible for creating the service call/activity. Optional id The ID associated with the creator of the record. String code The code associated with the new person record. String externalId The external ID associated with the new person record. This value must be unique. String dueDateTime The date/time at which the service call is due to be completed. DateTime durationInMinutes The duration in minutes the service call is expected to last. Integer earliestStartDateTime The earliest date/time on which the service call can be completed. DateTime equipments The equipment record associated with the service call. Optional id The ID of the equipment record associated with the service call. String code The code associated with the service call equipment. String externalId The external ID associated with the service call equipment. This value must be unique. String externalId The external ID associated wth the service call record. This value must be unique among all serviceCall objects. String lastChanged The person responsible for last changing the service call record. Integer origin The origin of the service call (i.e. phone, online, etc). String Optional priority The priority level associated with the service call (example: high, medium, low). String Required problemType The problem type associated with the service call (example: warranty, maintenance, etc.). String remarks The remarks associated with the service call. String requirements The service call requirements inherited Indicates whether or not the requirement was inherited from another service call. Boolean mandatory Indicates whether the requirement is mandatory (true) or not mandatory (false) Boolean dkill The skill requirement of the activity. id The skill ID. String code The skill code. String externalId The external ID of the skill. String reservedMaterials The reserved materials associated with the service call. externalId The external ID associated with the reserved material item. This value must be unique among all reservedMaterial objects. String id The ID assocaited with the reserved material item. String item The reserved material item. String Required id The ID of the reserved material item. String code The code of the reserved material item. String externalId The external ID of the reserved material item. String moved The amount of reserved materials that have been moved from one warehouse to another. Integer Required (defaults to 0 if not provided) quantity The quantity of reserved material. Integer Required serialNumber If applicable, the reserved material managed by serial number. id The ID of the reserved material item managed by serial number. String code The code of the reserved material item managed by serial number. String externalId The external ID of the reserved material item managed by serial number. String shipped The amount of reserved material items with status "shipped"; i.e., ordered but not yet available for usage. Integer udfValues udfMeta The metadata associated with the user-defined field. id The UDF ID. String code The UDF code. String externalID The external ID of the UDF. String value The value of the user-defined field (UDF). String used The amount of reserved material item/s used during the course of the service call. Integer Required (defaults to 0 if not provided) warehouse The warehouse in which the reserved material/s are stored. A warehouse may also refer to the technician vehicle. Required id The ID of the warehouse. String code The code of the warehouse. String externalId The external ID of the warehouse. String resolution The resolution status of the service call. String responsibles The technician/s assigned to the service call. id The ID associated with the responsibles assigned to the service call. String code The code associated with the responsible assigned to the service call. String externalId The external ID associated with the responsible assigned to the service call. String serviceContract The service contract associated with the service call. id The ID associated with the service contract assigned to the service call. String code The code associated with the service contract assigned to the service call. String externalId The external ID associated with the service contract assigned to the service call. String status The current status of the service call. String Required subject The subject of the service call. String Required type The service call type. String udfValues udfMeta The metadata associated with the user-defined field. id The UDF ID. String code The UDF code. String externalID The external ID of the UDF. String value The value of the user-defined field (UDF). String 1.3.4 GET Service Call Activity with Sub-resources Get an activity and its sub-resources for a service call. 1.3.4.1 Request Method URL GET https://{cluster}.coresystems.net/api/service-management/v2/composite-tree/service-calls/{service-call-uid}/activities/{activiy-uid} 1.3.4.2 URL Parameters Parameter Description Type Required {service-call-uid} The unique ID of the service call record created via POST request to which the activity you wish to retrieve belongs. String Required {activity-uid} The unique ID of the activity created via POST request you wish to retrieve. String Required 1.3.4.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-Name companyName The name of the company Required 1.3.4.4 Response Status Response 200 OK 401 Unauthorized 403 Forbidden 404 Not found 1.3.4.5 Example Response Body { "address": { "city": "string", "country": "string", "location": { "latitude": 0, "longitude": 0 }, "source": "ACTIVITY", "sourceId": { "uuid": "string" }, "state": "string", "street": "string", "streetNumber": "string", "zipCode": "string" }, "attachments": [ { "category": "string", "description": "string", "fileName": "string", "id": { "uuid": "string" }, "title": "string", "type": "string" } ], "code": "string", "contact": { "id": "string", "code": "string", "externalId": "string" }, "createPerson": { "id": "string", "code": "string", "externalId": "string" }, "dueDateTime": "2019-10-22T11:20:33.458Z", "durationInMinutes": 0, "earliestStartDateTime": "2019-10-22T11:20:33.458Z", "equipment": { "id": "string", "code": "string", "externalId": "string" }, "executionStage": "string", "externalId": "string", "id": { "uuid": "string" }, "lastChanged": 0, "plannedEndDate": "2019-10-22T11:20:33.459Z", "plannedStartDate": "2019-10-22T11:20:33.459Z", "region": { "id": "string", "code": "string", "externalId": "string" }, "remarks": "string", "requirements": [ { "inherited": true, "mandatory": true, "skill": { "id": "string", "code": "string", "externalId": "string" } } ], "reservedMaterials": [ { "externalId": "string", "id": "string", "item": { "id": "string", "code": "string", "externalId": "string" }, "moved": 0, "quantity": 0, "serialNumber": { "id": "string", "code": "string", "externalId": "string" }, "shipped": 0, "udfValues": [ { "udfMeta": { "id": "string", "code": "string", "externalId": "string" }, "value": "string" } ], "used": 0, "warehouse": { "id": "string", "code": "string", "externalId": "string" } } ], "responsibles": [ { "id": "string", "code": "string", "externalId": "string" } ], "sourceActivity": { "id": "string", "code": "string", "externalId": "string" }, "status": "string", "subject": "string", "type": "string", "udfValues": [ { "udfMeta": { "id": "string", "code": "string", "externalId": "string" }, "value": "string" } ] } 1.3.3.6 Response Values Value Description Type Required activities If applicable, the activity record/s associated with the serviceCall. address The activity address. city The city in which the activity is located. String country The country in which the activity is located. String location The location of the address expressed in longitude and latitude. latitude The latitude of the address location. Integer longitude The longitude of the address location. Integer source The source of the activity address (BUSINESSPARTNER, EQUIPMENT, SERVICECALL). This is a temporary address that was resolved using the address resolution logic. The source field will indicate from which object the address is coming from. Enumeration. sourceId The ID associated with the activity address source. String state The state in which the activity is located. String street The street in which the activity is located. String streetNumber The streetnumber associated with the activity address. String zipCode The zip code associated with the actrivity address. String code The activity code. This value is automatically created by the system. String contact The contact associated with the activity. String id The contact ID associated with the activity. String code The code associated with the activity contact. String externalId If applicable, the external ID associated with the activity contact. String createPerson If no record for the contact exists, a new person record will be created. id The ID associated with the new person record. String code The code associated with the new person record. String externalId The external ID associated with the person responsible for creating the record. This value must be unique. String dueDateTime The date/time at which the activity is due to be completed. DateTime durationInMinutes The expected duration in minutes of the activity. Integer earliestStartDate The earlest date on which the activity can occur. DateTime equipment The equipment record associated with the activity. id The ID of the equipment record associated with the activitiy. String code The code of the equipment associated with the activity. String externalId The external ID of the equipment associated with the activity. This value must be unique. String externalId The external ID of the activity record. This value must be unique among all activity records. String lastChanged The person responsible for last changing the record. String Region If applicable, in which the activity takes place. id The ID of the region. String code The region code. String externalId The external ID of the region. String remarks The remarks associated with the activity. String requirements The activity requirements inherited Indicates whether or not the requirement was inherited from a service call. Boolean Mandatory Indicates whether the requirement is mandatory (true) or not mandatory (false) Boolean Skill The skill requirement of the activity. id The skill ID. String code The skill code. String externalId The external ID of the skill. String reservedMaterials The reserved materials associated with the activty. Array externalId The externalId of the reserved material. This value must be unique among all reservedMaterial objects. String id The ID of the reserved material. String item The reserved material item. Required id The ID assocaited with the reserved material item. String code The code associated with the reserved material item String externalId The external ID associated with the reserved material item. This value must be unique among all reservedMaterial objects. String moved The amount of reserved materials that have been moved from one warehouse to another. Integer Required (defaults to 0 if not provided) quantity The amount of reserved material items used for the activity. Integer Required serialNumber The serial number of the reserved material item. id The ID of the reserved material item managed by serial number. String code The code of the reserved material item managed by serial number. String externalId The external ID of the reserved material item managedd by serial number. This value must be unique. String shipped If applicable, the amount of reserved material item that have stated "shipped", i.e. ordered but not yet available for usage. Integer udfValues udfMeta The metadata associated with the user-defined field. id The UDF ID. String code The UDF code. String externalID The external ID of the UDF. String value The value contained in the user-defined field (UDF). String Required used The amount of reserved material item/s used during the course of the activity. Integer Required (defaults to 0 if not provided) warehouse The warehouse in which the reserved material/s are stored. A warehouse may also refer to the technician vehicle. Required id The ID of the warehouse. String code The code of the warehouse. String externalId The external ID of the warehouse. This value must be unique. String subject The subject of the activty. String Required udfValues udfMeta The metadata associated with the user-defined field. id The UDF ID. String code The UDF code. String externalID The external ID of the UDF. String value The value contained in the user-defined field (UDF). String Required address The address of the service call. city The city in which the service call is located. String country The country in which the service call is located. String location The location of the address expressed in longitude and latitude. latitude The latitude of the address location. Integer longitude The longitude of the address location. Integer source The source of the service call address (BUSINESSPARTNER, EQUIPMENT). This is a temporary address that was resolved using the address resolution logic. The source field will indicate from which object the address is coming from. Enumeration sourceId The ID associated with the service call address source. String state The state in which the service call is located. String street The street in which the service call is located. String streetNumber The street number associated with the service call street address. String zipCode The zip code associated with the service call address. String businessPartner The business partner associated with the service call. A Business Partner general refers to the customer, but may also refer to a vendor, etc. Required id The business partner ID. String code The business partner code. String externalId The external ID associated with the business partner. This value must be unique. String code The service call code. This code is generated automatically by the system. String Contact The contact associated with the service call. id The ID associated with the service call contact. String code The code associated with the service call contact. String externalId The external ID associated with the service call contact. This value must be unique. String createPerson The user responsible for creating the service call/activity. Optional id The ID associated with the creator of the record. String code The code associated with the new person record. String externalId The external ID associated with the new person record. This value must be unique. String dueDateTime The date/time at which the service call is due to be completed. DateTime durationInMinutes The duration in minutes the service call is expected to last. Integer earliestStartDateTime The earliest date/time on which the service call can be completed. DateTime equipments The equipment record associated with the service call. Optional id The ID of the equipment record associated with the service call. String code The code associated with the service call equipment. String externalId The external ID associated with the service call equipment. This value must be unique. String externalId The external ID associated wth the service call record. This value must be unique among all serviceCall objects. String lastChanged The person responsible for last changing the service call record. Integer origin The origin of the service call (i.e. phone, online, etc). String Optional priority The priority level associated with the service call (example: high, medium, low). String Required problemType The problem type associated with the service call (example: warranty, maintenance, etc.). String remarks The remarks associated with the service call. String requirements The service call requirements inherited Indicates whether or not the requirement was inherited from another service call. Boolean Mandatory Indicates whether the requirement is mandatory (true) or not mandatory (false) Boolean Skill The skill requirement of the activity. id The skill ID. String code The skill code. String externalId The external ID of the skill. String reservedMaterials The reserved materials associated with the service call. externalId The external ID associated with the reserved material item. This value must be unique among all reservedMaterial objects. String id The ID assocaited with the reserved material item. String item The reserved material item. String Required id The ID of the reserved material item. String code The code of the reserved material item. String externalId The external ID of the reserved material item. String moved The amount of reserved materials that have been moved from one warehouse to another. Integer Required (defaults to 0 if not provided) quantity The quantity of reserved material. Integer Required serialNumber If applicable, the reserved material managed by serial number. id The ID of the reserved material item managed by serial number. String code The code of the reserved material item managed by serial number. String externalId The external ID of the reserved material item managed by serial number. String shipped The amount of reserved material items with status "shipped"; i.e., ordered but not yet available for usage. Integer udfValues udfMeta The metadata associated with the user-defined field. id The UDF ID. String code The UDF code. String externalID The external ID of the UDF. String value The value contained in the user-defined field (UDF). String Required used The amount of reserved material item/s used during the course of the service call. Integer Required (defaults to 0 if not provided) warehouse The warehouse in which the reserved material/s are stored. A warehouse may also refer to the technician vehicle. Required id The ID of the warehouse. String code The code of the warehouse. String externalId The external ID of the warehouse. String resolution The resolution status of the service call. String responsibles The technician/s assigned to the service call. id The ID associated with the responsibles assigned to the service call. String code The code associated with the responsible assigned to the service call. String externalId The external ID associated with the responsible assigned to the service call. String serviceContract The service contract associated with the service call. id The ID associated with the service contract assigned to the service call. String code The code associated with the service contract assigned to the service call. String externalId The external ID associated with the service contract assigned to the service call. String status The current status of the service call. String Required subject The subject of the service call. String Required Type The type associated with the service call. String udfValues udfMeta The metadata associated with the user-defined field. id The UDF ID. String code The UDF code. String externalID The external ID of the UDF. String value The value contained in the user-defined field (UDF). String Required 1.4.1 Bulk Create Service Calls Bulk create service calls with optional activities. 1.4.1.1 Request Method URL POST https://{cluster}.coresystems.net/api/v2/composite-bulk/service-calls 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-Name companyName The name of the company Required 1.4.1.3 Query Parameters Query Parameter Value Description autoCreateActivity true / false Optional. Default value = true. When true, a default activity record will be created, if no activity has been provided explicitly. 1.4.1.4 Request Body A Bulk service call creation POST request contains an array of service calls. The values in a service call record contained in a bulk POST request are the same as those listed in section 1.3.4. 1.4.1.5 Response Status Response 201 Created 207 Request succeeded 401 Unauthorized 403 Forbidden 404 Not Found 1.4.1.6 Example Response Body The following is an example response for a request that returns a HTTP 207 response: { "hasErrors": true, "results": [ { // service call }, { // another service call } ] } 1.4.2 Bulk Update Service Calls Bulk update multiple serviceCall records and optional activities. Note The conditions required for a Bulk PATCH request are the same as those listed in section 1.3.2. 1.4.2.1 Request Method URL PATCH https://{cluster}.coresystems.net/api/service-management/v2/composite-bulk/service-calls 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-Name companyName The name of the company Required 1.4.2.3 Request Body The values contained in a bulk PATCH request are the same as those listed in section 1.3.2.4. 1.4.2.4 Example Request Body [{ "subject": "testing SC", "priority": "MEDIUM", "dueDateTime": "2018-11-27T18:22:57.100Z", "earliestStartDateTime": "2018-11-27T18:02:57.200Z", "status": "-2", "origin": "-3", "durationInMinutes": 10, "createPerson": { "id": "b4003ecba0354b0b89b91290f491d5c9" }, "responsibles": [], "businessPartner": {"id" : "ba1089260c7c4140ae1c90f67a825cdb"}, "resolution": "Repair", "problemType": "-1", "equipments": [ {"code" : "1"} ], "activities": [ { "code": "ZXY231", "externalId": null, "subject": "Activity subject", "contact": { "code": "blc", "externalId": null }, "remarks": "some remarks", "createPerson": { "id": "b4003ecba0354b0b89b91290f491d5c9" }, "equipment": {"code" : "1"}, "reservedMaterials": [{ "item": {"code" : "1"}, "quantity": 1, "warehouse": { "code": "-1" }, "shipped": 1, "udfValues": [ { "udfMeta": {"id": "93aa33ccc4ed4ff9ada58e2f0950a7d2"}, "value": "VALUE" } ] }], "udfValues": [ { "udfMeta": {"id": "93aa33ccc4ed4ff9ada58e2f0950a7d2"}, "value": "VALUE" } ], "requirements": [ { "skill": { "id": "0a8a053b4e0646e7b332421cb8233603" }, "mandatory": false } ] } ], "remarks": "Some remarks", "type": "-1", "requirements": [ { "skill": { "id": "325fa92e370b4559babb1b1edd020fdb" }, "mandatory": false } ], "udfValues": [ { "udfMeta": {"id": "93aa33ccc4ed4ff9ada58e2f0950a7d2"}, "value": "VALUE" }, { "udfMeta": {"externalId": "ext-1"}, "value": "VALUE" } ] }] 1.4.2.5 Response Status Response 201 Created 207 Request succeeded 401 Unauthorized 403 Forbidden 404 Not Found 1.4.2.6 Example Response Body The following is an example response for a request that returns a HTTP 207 response: { "hasErrors": true, "results": [ { // service call }, { // another service call } ] } 1.5 Business Actions 1.5.1 Cancel Activity Cancel an activity. Activity can be cancelled when its in planned or released state in the Planning & Dispatching app. The following conditions needs to be met before cancelling an activity: The status of Service Assignment should be either ‘ASSIGNED’ or ‘RELEASED’. If status of Service Assignment is ‘ASSIGNED’ , Activity can be only cancelled if its status is either ‘DRAFT’ or ‘OPEN’ and executionStage is ‘DISPATCHING’. If status of Service Assignment is ‘RELEASED’ , Activity can be only cancelled if its status is ‘OPEN’ and executionStage is ‘EXECUTION’. After successful request the patch request will update below fields in Activity and ServiceAssignment. If Service Assignment is ‘ASSIGNED’ we will update activity and Service Assignment as below: Activity ("status", "CLOSED"); ("executionStage", "CANCELLED"); ("subject", "CANCELLED - " + subject); ServiceAssignment if(Activity is released){ ("state", "CLOSED"); } ("deleted", true); 1.5.1.1 Request Method URL POST https://{cluster}.coresystems.net/v2/activities/{activity-uid}/actions/cancel 1.5.1.2 URL Parameters Parameter Description Type Required {activity-uid} The uid of the activity you wish to cancel. String Required 1.5.1.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-Name companyName The name of the company Required X-Company-ID companyId The id of the company Required 1.5.1.4 Response Status Response 200 OK 201 Created 401 Unauthorized 403 Forbidden 404 Not Found 1.5.2 Close Activity Close a specified activity. For closing an activity, the following conditions must be fulfilled: Service Assignment should be released. (State of Service Assignment should be ‘RELEASED’). Activity Should be released. (State of activity should be ‘OPEN’ and executionStage of activity should be ‘EXECUTION’). If above two conditions are met. After successful request the patch request will update below fields in Activity and ServiceAssignment: Activity ("status", "CLOSED"); ("executionStage", "CLOSED"); ("checkedOut", true); ServiceAssignment ("state", "CLOSED"); 1.5.2.2 Request Method URL POST https://{cluster}.coresystems.net/v2/activities/{activity-uid}/actions/close 1.5.2.3 URL Parameters Parameter Description Type Required {activity-uid} The uid of the activity you wish to close. String Required 1.5.2.4 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-Name companyName The name of the company Required X-Company-ID companyId The id of the company Required 1.5.2.5 Response Status Response 200 OK 201 Created 401 Unauthorized 403 Forbidden 404 Not Found 1.5.3 Plan Activity Plan the specified activity. The following conditions must be met to plan an activity: A ServiceAssignment has not been created for activity. The Activity status matches the following: DRAFT executionStage: DISPATCHING responsibles: null 1.5.3.1 Request Method URL POST https://{cluster}.coresystems.net/api/service-management/v2/activities/{activity-uid}/actions/plan 1.5.3.2 URL Parameters Parameter Description Type Required {activity-uid} The uid of the activity you wish to plan. String Required 1.5.3.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-Name companyName The name of the company Required X-Company-ID companyId The id of the company Required 1.5.3.4 Request Body Value Description Required duration The duration in seconds of the activity. Optional startDateTime The start date and time of the activity. Required technician The assigned technician. Required id The unique ID of the technician. code The code of the technician. externalId The external ID of the technician. 1.5.3.5 Example Request Body { "duration": 0, "startDateTime": "2020-01-30T08:39:02.663Z", "technician": { "id": "string", "code": "string", "externalId": "string" } } 1.5.3.6 Response Status Response 200 OK 201 Created 401 Unauthorized 403 Forbidden 404 Not Found 1.5.4 Release Activity Release specified activity. The following conditions need to be met to release an activity: If activity is in planned state, Activity can be released if its status is in ‘DRAFT’ or ‘OPEN’ and executionStage is ‘DISPATCHING’ and ServiceAssignment status is ‘ASSIGNED’. If activity is in Modified state(if it is re-planned), If while activity re-planning if only time is replanned and technician is same, Activity can released if status is ‘OPEN’ and executionStage is ‘EXECUTION’ and ServiceAssignment state is ‘MODIFIED’. If activity is in Modified state(if it is re-planned), Activity can released if status is ‘OPEN’ and executionStage is ‘EXECUTION’ and ServiceAssignment state is ‘MODIFIED’. 1.5.4.1 Request Method URL POST https://{cluster}.coresystems.net/v2/activities/{activity-uid}/actions/release 1.5.4.2 URL Parameters Parameter Description Type Required {activity-uid} The uid of the activity you wish to release. String Required 1.5.4.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-Name companyName The name of the company Required X-Company-ID companyId The id of the company Required 1.5.4.4 Respose Status Response 200 OK 201 Created 401 Unauthorized 403 Forbidden 404 Not Found 1.5.4.5 Response Body A response body will be only be returned when replanned activity is released to a different technician. In this case, a new activity will be created and the response body will contain id, code and externalId for newly-created activity. { "activity": { "id": "784BC4A2845B43959B820DBF8B68CE4D", "code": "12", "externalId": null } } 1.5.5 Replan Activity Replan specified activity with duration and either startDateTime or technician assignment. Replan can be performed after an activity has been planned or released. The following conditions must be met in order to replan an activity: The status of Service Assignment should be ‘RELEASED’. If status of Service Assignment is ‘RELEASED’ , Activity can be only cancelled if its status is ‘OPEN’ and executionStage is ‘EXECUTION’. 1.5.5.1 Request Method URL POST https://{cluster}.coresystems.net/api/service-management/v2/activities/{activity-uid}/actions/replan 1.5.5.2 URL Parameters Parameter Description Type Required {activity-uid} The uid of the activity you wish to replan. String Required 1.5.5.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-Name companyName The name of the company Required X-Company-ID companyId The id of the company Required 1.5.5.4 Request Body Value Description Required duration The duration in seconds of the activity. Optional startDateTime The start date and time of the activity. Required technician The assigned technician. Required id The unique ID of the technician. code The code of the technician. externalId The external ID of the technician. 1.5.5.5 Example Request Body { "duration": 0, "startDateTime": "2020-01-30T08:39:02.663Z", "technician": { "id": "string", "code": "string", "externalId": "string" } } 1.5.5.6 Respose Status Response 200 OK 201 Created 401 Unauthorized 403 Forbidden 404 Not Found 1.5.6 Unassign Activity Unassign specified activity. Unassign activity can be performed when the activity is either is in Released or Assigned state. The following conditions needs to be met before an activity can be unassigned: The status of Service Assignment should be either ‘ASSIGNED’ or ‘RELEASED’. If status of Service Assignment is ‘ASSIGNED’ , Activity can be only cancelled if its status is either ‘DRAFT’ or ‘OPEN’ and executionStage is ‘DISPATCHING’. If status of Service Assignment is ‘RELEASED’ , Activity can be only cancelled if its status is ‘OPEN’ and executionStage is ‘EXECUTION’. 1.5.6.1 Request Method URL POST https://{cluster}.coresystems.net/v2/activities/{activity-uid}/actions/unassign 1.5.6.2 URL Parameters Parameter Description Type Required {activity-uid} The uid of the activity you wish to unassign. String Required 1.5.6.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-Name companyName The name of the company Required X-Company-ID companyId The id of the company Required 1.5.6.4 Response Status Response 200 OK 201 Created 401 Unauthorized 403 Forbidden 404 Not Found 1.5.6.5 Response Body Response body will be only available when the following occurs: a released activity has been unassigned an activity that was replanned and released has been unassigned The response body will contain id, code and externalId for newly created activity. { "activity": { "id": "string", "code": "string", "externalId": "string" } } Appendix Relevant Data Transfer Objects ActivityResponse DTO ActivityResponse { address Address { city string country string source string Enum: Array[14] sourceId string state string street string streetNumber string zipCode string } code string contact UnifiedIdentifier { id string code string externalId string } createPerson UnifiedIdentifier { id string code string externalId string } dueDateTime string($date - time) durationInMinutes integer($int32) earliestStartDateTime string($date - time) equipment UnifiedIdentifier { id string code string externalId string } externalId string id string lastChanged integer($int64) remarks string reservedMaterials[ ReservedMaterial { externalId string id string item UnifiedIdentifier { id string code string externalId string } moved number quantity number serialNumber UnifiedIdentifier { id string code string externalId string } shipped number used number warehouse UnifiedIdentifier { id string code string externalId string } } ] responsibles[ UnifiedIdentifier { id string code string externalId string } ] status string subject string } Address DTO Address { city string country string source string Enum: Array[14] sourceId string state string street string streetNumber string zipCode string } CreateActivityRequest DTO CreateActivityRequest { address Address { city string country string source string Enum: Array[14] sourceId string state string street string streetNumber string zipCode string } code string contact UnifiedIdentifier { id string code string externalId string } createPerson UnifiedIdentifier { id string code string externalId string } dueDateTime string($date - time) durationInMinutes integer($int32) earliestStartDateTime string($date - time) equipment UnifiedIdentifier { id string code string externalId string } externalId string lastChanged integer($int64) remarks string reservedMaterials[ReservedMaterial { externalId string id string item UnifiedIdentifier { id string code string externalId string } moved number quantity number serialNumber UnifiedIdentifier { id string code string externalId string } shipped number used number warehouse UnifiedIdentifier { id string code string externalId string } }] subject string } CreateServiceCallRequest DTO CreateServiceCallRequest { activities[CreateActivityRequest { address Address { city string country string source stringEnum: [ACTIVITY, ADDRESS, BUSINESSPARTNER, CONTACT, EQUIPMENT, PERSON, SERVICECALL, SERVICECALLORIGIN, SERVICECALLSTATUS, SERVICECALLPROBLEMTYPE, RESERVEDMATERIAL, WAREHOUSE, ITEM, SERIALNUMBER] sourceId string state string street string streetNumber string zipCode string } code string contact UnifiedIdentifier { id string code string externalId string } createPerson UnifiedIdentifier { id string code string externalId string } dueDateTime string($date - time) durationInMinutes integer($int32) earliestStartDateTime string($date - time) equipment UnifiedIdentifier { id string code string externalId string } externalId string lastChanged integer($int64) remarks string reservedMaterials[ReservedMaterial { externalId string id string item UnifiedIdentifier { id string code string externalId string } moved number quantity number serialNumber UnifiedIdentifier { id string code string externalId string } shipped number used number warehouse UnifiedIdentifier { id string code string externalId string } }] subject string }] address Address { city string country string source stringEnum: [ACTIVITY, ADDRESS, BUSINESSPARTNER, CONTACT, EQUIPMENT, PERSON, SERVICECALL, SERVICECALLORIGIN, SERVICECALLSTATUS, SERVICECALLPROBLEMTYPE, RESERVEDMATERIAL, WAREHOUSE, ITEM, SERIALNUMBER] sourceId string state string street string streetNumber string zipCode string } businessPartner UnifiedIdentifier { id string code string externalId string } code string contact UnifiedIdentifier { id string code string externalId string } createPerson UnifiedIdentifier { id string code string externalId string } dueDateTime string($date - time) durationInMinutes integer($int32) earliestStartDateTime string($date - time) equipments[UnifiedIdentifier { id string code string externalId string }] externalId string lastChanged integer($int64) origin string priority string problemType string remarks string reservedMaterials[ReservedMaterial { externalId string id string item UnifiedIdentifier { id string code string externalId string } moved number quantity number serialNumber UnifiedIdentifier { id string code string externalId string } shipped number used number warehouse UnifiedIdentifier { id string code string externalId string } }] resolution string responsibles[UnifiedIdentifier { id string code string externalId string }] status string subject string } ReservedMaterial DTO ReservedMaterial { externalId string id string item UnifiedIdentifier { id string code string externalId string } moved number quantity number serialNumber UnifiedIdentifier { id string code string externalId string } shipped number used number warehouse UnifiedIdentifier { id string code string externalId string } } ResponseEntity DTO ResponseEntity { body {} status {} statusCode string Enum: [100 CONTINUE, 101 SWITCHING_PROTOCOLS, 102 PROCESSING, 103 CHECKPOINT, 200 OK, 201 CREATED, 202 ACCEPTED, 203 NON_AUTHORITATIVE_INFORMATION, 204 NO_CONTENT, 205 RESET_CONTENT, 206 PARTIAL_CONTENT, 207 MULTI_STATUS, 208 ALREADY_REPORTED, 226 IM_USED, 300 MULTIPLE_CHOICES, 301 MOVED_PERMANENTLY, 302 FOUND, 302 MOVED_TEMPORARILY, 303 SEE_OTHER, 304 NOT_MODIFIED, 305 USE_PROXY, 307 TEMPORARY_REDIRECT, 308 PERMANENT_REDIRECT, 400 BAD_REQUEST, 401 UNAUTHORIZED, 402 PAYMENT_REQUIRED, 403 FORBIDDEN, 404 NOT_FOUND, 405 METHOD_NOT_ALLOWED, 406 NOT_ACCEPTABLE, 407 PROXY_AUTHENTICATION_REQUIRED, 408 REQUEST_TIMEOUT, 409 CONFLICT, 410 GONE, 411 LENGTH_REQUIRED, 412 PRECONDITION_FAILED, 413 PAYLOAD_TOO_LARGE, 413 REQUEST_ENTITY_TOO_LARGE, 414 URI_TOO_LONG, 414 REQUEST_URI_TOO_LONG, 415 UNSUPPORTED_MEDIA_TYPE, 416 REQUESTED_RANGE_NOT_SATISFIABLE, 417 EXPECTATION_FAILED, 418 I_AM_A_TEAPOT, 419 INSUFFICIENT_SPACE_ON_RESOURCE, 420 METHOD_FAILURE, 421 DESTINATION_LOCKED, 422 UNPROCESSABLE_ENTITY, 423 LOCKED, 424 FAILED_DEPENDENCY, 426 UPGRADE_REQUIRED, 428 PRECONDITION_REQUIRED, 429 TOO_MANY_REQUESTS, 431 REQUEST_HEADER_FIELDS_TOO_LARGE, 451 UNAVAILABLE_FOR_LEGAL_REASONS, 500 INTERNAL_SERVER_ERROR, 501 NOT_IMPLEMENTED, 502 BAD_GATEWAY, 503 SERVICE_UNAVAILABLE, 504 GATEWAY_TIMEOUT, 505 HTTP_VERSION_NOT_SUPPORTED, 506 VARIANT_ALSO_NEGOTIATES, 507 INSUFFICIENT_STORAGE, 508 LOOP_DETECTED, 509 BANDWIDTH_LIMIT_EXCEEDED, 510 NOT_EXTENDED, 511 NETWORK_AUTHENTICATION_REQUIRED] statusCodeValue integer($int32) } ServiceCallResponse DTO ServiceCallResponse { activities[ActivityResponse { address Address { city string country string source stringEnum: [ACTIVITY, ADDRESS, BUSINESSPARTNER, CONTACT, EQUIPMENT, PERSON, SERVICECALL, SERVICECALLORIGIN, SERVICECALLSTATUS, SERVICECALLPROBLEMTYPE, RESERVEDMATERIAL, WAREHOUSE, ITEM, SERIALNUMBER] sourceId string state string street string streetNumber string zipCode string } code string contact UnifiedIdentifier { id string code string externalId string } createPerson UnifiedIdentifier { id string code string externalId string } dueDateTime string($date - time) durationInMinutes integer($int32) earliestStartDateTime string($date - time) equipment UnifiedIdentifier { id string code string externalId string } externalId string id string lastChanged integer($int64) remarks string reservedMaterials[ReservedMaterial { externalId string id string item UnifiedIdentifier { id string code string externalId string } moved number quantity number serialNumber UnifiedIdentifier { id string code string externalId string } shipped number used number warehouse UnifiedIdentifier { id string code string externalId string } }] responsibles[UnifiedIdentifier { id string code string externalId string }] status string subject string }] address Address { city string country string source stringEnum: [ACTIVITY, ADDRESS, BUSINESSPARTNER, CONTACT, EQUIPMENT, PERSON, SERVICECALL, SERVICECALLORIGIN, SERVICECALLSTATUS, SERVICECALLPROBLEMTYPE, RESERVEDMATERIAL, WAREHOUSE, ITEM, SERIALNUMBER] sourceId string state string street string streetNumber string zipCode string } businessPartner UnifiedIdentifier { id string code string externalId string } code string contact UnifiedIdentifier { id string code string externalId string } createPerson UnifiedIdentifier { id string code string externalId string } dueDateTime string($date - time) durationInMinutes integer($int32) earliestStartDateTime string($date - time) equipments[UnifiedIdentifier { id string code string externalId string }] externalId string id string lastChanged integer($int64) origin string priority string problemType string remarks string reservedMaterials[ReservedMaterial { externalId string id string item UnifiedIdentifier { id string code string externalId string } moved number quantity number serialNumber UnifiedIdentifier { id string code string externalId string } shipped number used number warehouse UnifiedIdentifier { id string code string externalId string } }] resolution string responsibles[UnifiedIdentifier { id string code string externalId string }] status string subject string } UnifiedIdentifier DTO UnifiedIdentifier{ id string code string externalId string }