12 Service API v2

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


12.1.1 Request Methods

The following methods are supported:

  Note Section
12.1.0.1 POST (create) a new service call and activities with sub-resources for it. 12.3
12.1.0.2 PATCH (partially update) an existing service call and/or activities and sub-resources. 12.4
12.1.0.3 GET information on a specific service call and related sub-resources 12.5
12.1.0.4 GET information on a specific activity and related sub-resources. 12.6

12.1.2 Service API in Swagger

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


12.1.3 Postman Spec

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


12.1.4 Physical Address Logic in Activities

12.1.4.1 Explicit Address

For GET, PUT, and PATCH responses, if an explicit address was created for the activity the address object will be embedded in the activity.

Explicit Address in Response

Activity {
    ...
    Address {
        city:,
        country:,
    }
    ...
}

12.1.4.2 Referenced Address

If address in only referenced from an activity (e.g. BP address is referenced) then the address object will be embedded in the activity with additional information.

Referenced Address

Activity {
    ...
    Address {
        source: "object type" // object type from which this address is coming from
        sourceId: "UUID", // UUID of address object
        city:,
        country:,
    }
    ...
}

12.1.4.3 Without Explicit Address

If the Address object is not provided inside the activity in a PUT or PATCH JSON request, the following will occur:

  Method Scenario
12.1.3.3.1 PUT Create an activity without explicitly creating address (there will be only one referenced from resolution logic).
12.1.3.3.2 PATCH If there was an address explicitly created previously, this address will be deleted and updated with the new address.

If the address object together with source and sourceId is provided inside the activity JSON request nothing will occur, as depicted in the following example:

Activity {
    ...
    Address {
        source: "object type" // object type from which this address is coming from
        sourceId: "UUID", // UUID of address object
        city:,
        country:,
    }
    ...
}

12.1.4.4 Without source and sourceId

If the Address object is provided inside the ativity JSON request without source and sourceId, the following scenarios will obtain:

  Scenario
12.1.4.4.1 If an explicit address already exists and it is the same address, no change will occur.
12.1.4.4.2 If an explicit address already exists, but it is different from that explicitly created for the activity, it will update.
12.1.4.4.3 If no explicit address exists, and the activity is not connected to a business partner address, a new address will be created and the activity linked to it.

12.1.5 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:

  • First check id
  • if it is not provided check code
  • if it is not provided check externalId

12.2 Access

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

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

12.2.1 Get Access Token

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


Cloud Account


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


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

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

grant_type=password&username=cym&password=passwordExample123


Company User


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


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

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

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


12.2.2 Response

The following is an example of a typical response:

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

12.2.3 Error Response

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

12.2.4 Supported Clusters

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

  • EU
  • DE
  • US
  • CN

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

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

https://{cluster}.coresystems.net/api/service-management/v2/composite-tree/service-calls


12.3 POST Service Call with Optional Activities

Create a serviceCall with (optional) one or more Activity records.


12.3.1 Request

Method URL
POST https://{cluster}.coresystems.net/api/service-management/v2/composite-tree/service-calls

12.3.2 Headers

Header Parameter Value Description Required
Authorization bearer OAuth 2.0 token Required
X-Account-Name accountName The name of the account associated with ther request. 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 associated with the request. Required
X-User-Name userName The user namer. This is required only when using an OAuth token NOT associated with any user. Optional
account accountName Deprecated–will be removed soon. Use the X-Account-Name header instead. Deprecated
company companyName Deprecated, will be removed soon. Use the X-Company-Name header instead. Deprecated

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

12.3.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
source The source of the activity address (ACTIVITY, ADDRESS, BUSINESSPARTNER, CONTACT, EQUIPMENT, PERSON, SERVICECALL, SERVICECALLORIGIN, SERVICECALLSTATUS, SERVICECALLPROBLEMTYPE, RESERVEDMATERIAL, WAREHOUSE, ITEM, SERIALNUMBER) 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
remarks The  remarks associated with the activity. 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
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
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
source The source of the service call address (ACTIVITY, ADDRESS, BUSINESSPARTNER, CONTACT, EQUIPMENT, PERSON, SERVICECALL, SERVICECALLORIGIN, SERVICECALLSTATUS, SERVICECALLPROBLEMTYPE, RESERVEDMATERIAL, WAREHOUSE, ITEM, SERIALNUMBER) 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. Required
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. Required
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 Required
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
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
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
status The current status of the service call. String Required
subject The subject of the service call. String Required

12.3.5 Response

Status Response
200 OK
401 Unauthorized
403 Forbidden

12.3.6 Example Response Body

{
  "activities": [
    {
      "address": {
        "city": "string",
        "country": "string",
        "source": "ACTIVITY",
        "sourceId": "string",
        "state": "string",
        "street": "string",
        "streetNumber": "string",
        "zipCode": "string"
      },
      "code": "string",
      "contact": {
        "id": "string",
        "code": "string",
        "externalId": "string"
      },
      "createPerson": {
        "id": "string",
        "code": "string",
        "externalId": "string"
      },
      "dueDateTime": "2019-04-09T09:15:03.638Z",
      "durationInMinutes": 0,
      "earliestStartDateTime": "2019-04-09T09:15:03.638Z",
      "equipment": {
        "id": "string",
        "code": "string",
        "externalId": "string"
      },
      "externalId": "string",
      "id": "string",
      "lastChanged": 0,
      "remarks": "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,
          "used": 0,
          "warehouse": {
            "id": "string",
            "code": "string",
            "externalId": "string"
          }
        }
      ],
      "responsibles": [
        {
          "id": "string",
          "code": "string",
          "externalId": "string"
        }
      ],
      "status": "string",
      "subject": "string"
    }
  ],
  "address": {
    "city": "string",
    "country": "string",
    "source": "ACTIVITY",
    "sourceId": "string",
    "state": "string",
    "street": "string",
    "streetNumber": "string",
    "zipCode": "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-04-09T09:15:03.638Z",
  "durationInMinutes": 0,
  "earliestStartDateTime": "2019-04-09T09:15:03.638Z",
  "equipments": [
    {
      "id": "string",
      "code": "string",
      "externalId": "string"
    }
  ],
  "externalId": "string",
  "id": "string",
  "lastChanged": 0,
  "origin": "string",
  "priority": "string",
  "problemType": "string",
  "remarks": "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,
      "used": 0,
      "warehouse": {
        "id": "string",
        "code": "string",
        "externalId": "string"
      }
    }
  ],
  "resolution": "string",
  "responsibles": [
    {
      "id": "string",
      "code": "string",
      "externalId": "string"
    }
  ],
  "status": "string",
  "subject": "string"
}

12.4 PATCH Service Call and Sub-resources

Partially update the serviceCall and associated activities and reserved materials.

Warning: this endpoint allows to add/remove elements in the nested collections. It’s as easy as not providing any kind of ID (id/code/externalId) for an element in the modified collection.

Please note the following:

  Note
12.4.0.1 If no modification is desired, do not pass collection at all, or pass null.
12.4.0.2 If all elements are to be removed from the collection, provide an empty array. E.g. “activities”: []
12.4.0.3 If new elements are to be added, do not provide any kind of ID in their body or provide a non-existent ID.
12.4.0.4 If existing elements are to be modified, provide a valid ID along with the updated content.
12.4.0.5 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"}

]

12.4.1 Request

Method URL
PATCH https://{cluster}.coresystems.net/api/service-management/v2/composite-tree/service-calls/{service-call-uid}

12.4.1.1 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

12.4.2 Headers

Header Parameter Value Description Required
Authorization bearer OAuth 2.0 token Required
X-Account-Name accountName The name of the account associated with ther request. 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 associated with the request. Required
X-User-Name userName The user namer. This is required only when using an OAuth token NOT associated with any user. Optional
account accountName Deprecated–will be removed soon. Use the X-Account-Name header instead. Deprecated
company companyName Deprecated, will be removed soon. Use the X-Company-Name header instead. Deprecated

12.4.3 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
source The source of the activity address (ACTIVITY, ADDRESS, BUSINESSPARTNER, CONTACT, EQUIPMENT, PERSON, SERVICECALL, SERVICECALLORIGIN, SERVICECALLSTATUS, SERVICECALLPROBLEMTYPE, RESERVEDMATERIAL, WAREHOUSE, ITEM, SERIALNUMBER) 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
remarks The  remarks associated with the activity. 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
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
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
source The source of the service call address (ACTIVITY, ADDRESS, BUSINESSPARTNER, CONTACT, EQUIPMENT, PERSON, SERVICECALL, SERVICECALLORIGIN, SERVICECALLSTATUS, SERVICECALLPROBLEMTYPE, RESERVEDMATERIAL, WAREHOUSE, ITEM, SERIALNUMBER) 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. Required
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. Required
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 Required
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
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
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
status The current status of the service call. String Required
subject The subject of the service call. String Required

12.4.4 Response

Status Response
200 OK
204 No content
401 Unauthorized
403 Forbidden

12.4.5 Example Response Body

{
  "activities": [
    {
      "address": {
        "city": "string",
        "country": "string",
        "source": "ACTIVITY",
        "sourceId": "string",
        "state": "string",
        "street": "string",
        "streetNumber": "string",
        "zipCode": "string"
      },
      "code": "string",
      "contact": {
        "id": "string",
        "code": "string",
        "externalId": "string"
      },
      "createPerson": {
        "id": "string",
        "code": "string",
        "externalId": "string"
      },
      "dueDateTime": "2019-04-09T09:15:03.638Z",
      "durationInMinutes": 0,
      "earliestStartDateTime": "2019-04-09T09:15:03.638Z",
      "equipment": {
        "id": "string",
        "code": "string",
        "externalId": "string"
      },
      "externalId": "string",
      "id": "string",
      "lastChanged": 0,
      "remarks": "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,
          "used": 0,
          "warehouse": {
            "id": "string",
            "code": "string",
            "externalId": "string"
          }
        }
      ],
      "responsibles": [
        {
          "id": "string",
          "code": "string",
          "externalId": "string"
        }
      ],
      "status": "string",
      "subject": "string"
    }
  ],
  "address": {
    "city": "string",
    "country": "string",
    "source": "ACTIVITY",
    "sourceId": "string",
    "state": "string",
    "street": "string",
    "streetNumber": "string",
    "zipCode": "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-04-09T09:15:03.638Z",
  "durationInMinutes": 0,
  "earliestStartDateTime": "2019-04-09T09:15:03.638Z",
  "equipments": [
    {
      "id": "string",
      "code": "string",
      "externalId": "string"
    }
  ],
  "externalId": "string",
  "id": "string",
  "lastChanged": 0,
  "origin": "string",
  "priority": "string",
  "problemType": "string",
  "remarks": "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,
      "used": 0,
      "warehouse": {
        "id": "string",
        "code": "string",
        "externalId": "string"
      }
    }
  ],
  "resolution": "string",
  "responsibles": [
    {
      "id": "string",
      "code": "string",
      "externalId": "string"
    }
  ],
  "status": "string",
  "subject": "string"
}

12.5 GET Service Call and Sub-resources

Get the service call and its sub-resources.

12.5.1 Request

Method URL
GET https://{cluster}.coresystems.net/api/service-management/v2/composite-tree/service-calls/{service-call-uid}

12.5.1.1 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

12.5.2 Headers

Header Parameter Value Description Required
Authorization bearer OAuth 2.0 token Required
X-Account-Name accountName The name of the account associated with ther request. 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 associated with the request. Required
X-User-Name userName The user namer. This is required only when using an OAuth token NOT associated with any user. Optional
account accountName Deprecated–will be removed soon. Use the X-Account-Name header instead. Deprecated
company companyName Deprecated, will be removed soon. Use the X-Company-Name header instead. Deprecated

12.5.4 Response

Status Response
200 OK
401 Unauthorized
403 Forbidden
404 Not found

12.5.5 Example Response Body

{
  "activities": [
    {
      "address": {
        "city": "string",
        "country": "string",
        "source": "ACTIVITY",
        "sourceId": "string",
        "state": "string",
        "street": "string",
        "streetNumber": "string",
        "zipCode": "string"
      },
      "code": "string",
      "contact": {
        "id": "string",
        "code": "string",
        "externalId": "string"
      },
      "createPerson": {
        "id": "string",
        "code": "string",
        "externalId": "string"
      },
      "dueDateTime": "2019-04-09T09:15:03.638Z",
      "durationInMinutes": 0,
      "earliestStartDateTime": "2019-04-09T09:15:03.638Z",
      "equipment": {
        "id": "string",
        "code": "string",
        "externalId": "string"
      },
      "externalId": "string",
      "id": "string",
      "lastChanged": 0,
      "remarks": "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,
          "used": 0,
          "warehouse": {
            "id": "string",
            "code": "string",
            "externalId": "string"
          }
        }
      ],
      "responsibles": [
        {
          "id": "string",
          "code": "string",
          "externalId": "string"
        }
      ],
      "status": "string",
      "subject": "string"
    }
  ],
  "address": {
    "city": "string",
    "country": "string",
    "source": "ACTIVITY",
    "sourceId": "string",
    "state": "string",
    "street": "string",
    "streetNumber": "string",
    "zipCode": "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-04-09T09:15:03.638Z",
  "durationInMinutes": 0,
  "earliestStartDateTime": "2019-04-09T09:15:03.638Z",
  "equipments": [
    {
      "id": "string",
      "code": "string",
      "externalId": "string"
    }
  ],
  "externalId": "string",
  "id": "string",
  "lastChanged": 0,
  "origin": "string",
  "priority": "string",
  "problemType": "string",
  "remarks": "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,
      "used": 0,
      "warehouse": {
        "id": "string",
        "code": "string",
        "externalId": "string"
      }
    }
  ],
  "resolution": "string",
  "responsibles": [
    {
      "id": "string",
      "code": "string",
      "externalId": "string"
    }
  ],
  "status": "string",
  "subject": "string"
}

12.6 GET Service Call Activity with Sub-resources

Get an activity and its sub-resources for a service call.

12.6.1 Request

Method URL
GET https://{cluster}.coresystems.net/api/service-management/v2/composite-tree/service-calls/{service-call-uid}/activities/{activiy-uid}

12.6.1.1 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

12.6.2 Headers

Header Parameter Value Description Required
Authorization bearer OAuth 2.0 token Required
X-Account-Name accountName The name of the account associated with ther request. 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 associated with the request. Required
X-User-Name userName The user namer. This is required only when using an OAuth token NOT associated with any user. Optional
account accountName Deprecated–will be removed soon. Use the X-Account-Name header instead. Deprecated
company companyName Deprecated, will be removed soon. Use the X-Company-Name header instead. Deprecated

12.6.4 Response

Status Response
200 OK
401 Unauthorized
403 Forbidden
404 Not found

12.6.5 Example Response Body

{
  "activities": [
    {
      "address": {
        "city": "string",
        "country": "string",
        "source": "ACTIVITY",
        "sourceId": "string",
        "state": "string",
        "street": "string",
        "streetNumber": "string",
        "zipCode": "string"
      },
      "code": "string",
      "contact": {
        "id": "string",
        "code": "string",
        "externalId": "string"
      },
      "createPerson": {
        "id": "string",
        "code": "string",
        "externalId": "string"
      },
      "dueDateTime": "2019-04-09T09:15:03.638Z",
      "durationInMinutes": 0,
      "earliestStartDateTime": "2019-04-09T09:15:03.638Z",
      "equipment": {
        "id": "string",
        "code": "string",
        "externalId": "string"
      },
      "externalId": "string",
      "id": "string",
      "lastChanged": 0,
      "remarks": "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,
          "used": 0,
          "warehouse": {
            "id": "string",
            "code": "string",
            "externalId": "string"
          }
        }
      ],
      "responsibles": [
        {
          "id": "string",
          "code": "string",
          "externalId": "string"
        }
      ],
      "status": "string",
      "subject": "string"
    }
  ],
  "address": {
    "city": "string",
    "country": "string",
    "source": "ACTIVITY",
    "sourceId": "string",
    "state": "string",
    "street": "string",
    "streetNumber": "string",
    "zipCode": "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-04-09T09:15:03.638Z",
  "durationInMinutes": 0,
  "earliestStartDateTime": "2019-04-09T09:15:03.638Z",
  "equipments": [
    {
      "id": "string",
      "code": "string",
      "externalId": "string"
    }
  ],
  "externalId": "string",
  "id": "string",
  "lastChanged": 0,
  "origin": "string",
  "priority": "string",
  "problemType": "string",
  "remarks": "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,
      "used": 0,
      "warehouse": {
        "id": "string",
        "code": "string",
        "externalId": "string"
      }
    }
  ],
  "resolution": "string",
  "responsibles": [
    {
      "id": "string",
      "code": "string",
      "externalId": "string"
    }
  ],
  "status": "string",
  "subject": "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
}