Overview

Service tickets enable you to track customer issues and work on those issues through to resolution.

You can configure service ticket types for different types of service you provide, such as requests for repairs, request for servicing, and general inquiries.

When you create a service ticket, you can specify the relevant information, for example:

  • A short description of the customer's issue or request
  • The customer the service ticket was opened for
  • The product, the reported request or issue is related to
  • A configurable classification that allows you to further differentiate different classes of service tickets
  • A priority and desired due date

When working on the resolution of a service ticket you can use features such as:

  • Built-in status management
  • A transcript concept that allows processors of the tickets to enter additional information about the processing status
  • Automatic calculation of processing times

Note that it is recommended to use the Service Ticket Mashup service for developing applications on top of service tickets. The Service Ticket Mashup service provides additional capabilities such as consistency checks for customer and product master data when creating or updating service tickets and reading additional customer and product attributes when retrieving service tickets.


API Reference

/{tenant}/serviceTickets

Service tickets

/{tenant}/serviceTickets

get

Retrieve a collection of service tickets.

If no query is specified, all service tickets are returned in the result collection. To filter the result collection, use the query parameter q. The service ticket service uses the same query syntax as the Document service.

You can sort the result collection using the query parameter sort.

Only persisted fields can be used for querying and sorting. The following fields are transient and cannot be used for formulating queries or sorting the result collection:

  1. Type description (typeDescription)
  2. Classification description (classification.description)
  3. Priority description (priorityDescription)
  4. Status description (statusDescription)

If you would like to query or sort by those attributes, use the following persisted attributes instead:

  1. Type (type)
  2. Classification (classification)
  3. Priority (priority)
  4. Status (status)

The GET method is paged. Use the query parameters pageNumber to control which page is retrieved. Use the query parameter pageSize to control the number of service tickets per page. The maximum pageSize supported is 64.

Required scope: hybris.serviceticket_view

post

Create a new service ticket.

The id of the service ticket is automatically generated by the system. It is returned in the field id in the response body. It is also part of the response header Location.

Upon successful creation of the service ticket, the PubSub event serviceticket-created is raised.

Required scope: hybris.serviceticket_manage

/{tenant}/serviceTickets/{id}

Service ticket

get

Retrieve a service ticket.

The service ticket to be retrieved is identified by its id.

Required scope: hybris.serviceticket_view

put

Update a service ticket.

The service ticket to be updated is identified by its id.

Note that creating a service ticket with a caller-specified id is not allowed. Use the POST method at the endpoint /{tenant}/serviceTickets to create service tickets and have their ids generated by the system.

Upon successful update of the service ticket, the PubSub event serviceticket-updated is raised.

Required scope: hybris.serviceticket_manage

delete

Delete a service ticket.

The service ticket to be deleted is identified by its id.

Upon successful deletion of the service ticket, the PubSub event serviceticket-deleted is raised.

Required scope: hybris.serviceticket_delete

/{tenant}/serviceTickets/{id}/attachments

Service ticket attachments

get

Retrieve attachments information for a given service ticket.

You can use the following fields for defining query criteria via query parameter q.

  1. name
  2. size
  3. createdBy
  4. createdAt
  5. modifiedBy
  6. modifiedAt

Required scope: hybris.serviceticket_view

post

Upload an attachment for a given service ticket.

Required scope: hybris.serviceticket_manage

delete

Delete all attachments for a given service ticket.

Required scope: hybris.serviceticket_manage

/{tenant}/serviceTickets/{id}/attachments/{fileId}

Manage service ticket attachments

get

Retrieve the download link for a given attachment.

Required scope: hybris.serviceticket_view

put

Update the metadata for a given attachment.

Required scope: hybris.serviceticket_manage

delete

Delete an attachment.

Required scope: hybris.serviceticket_manage

/{tenant}/serviceTicketPriorities

Service ticket priorities

/{tenant}/serviceTicketPriorities

get

Retrieve the allowed values for the service ticket priority.

Required scope: hybris.serviceticket_configuration_view

/{tenant}/serviceTicketStatuses

Service ticket statuses

/{tenant}/serviceTicketStatuses

get

Retrieve the allowed values for the service ticket status.

Required scope: hybris.serviceticket_configuration_view

/{tenant}/serviceTicketTypes

Service ticket type configuration

/{tenant}/serviceTicketTypes

get

Retrieve the configured service ticket types.

Required scope: hybris.serviceticket_configuration_view

put

Update the service ticket type configuration.

Note that the service ticket type configuration you provide in the request body will overwrite the complete existing service ticket type configuration. If you would like to update only a subset of the configured service ticket types, use the GET method at the endpoint /{tenant}/serviceTicketTypes to retrieve the current configuration, make the desired adjustments to the result set, and use the PUT method at the endpoint /{tenant}/serviceTicketTypes to update the configuration.

Required scope: hybris.serviceticket_configuration_manage

delete

Delete the service ticket type configuration.

Note that the complete service ticket type configuration will be deleted. If you would like to delete only a subset of the configured service ticket types, use the GET method at the endpoint /{tenant}/serviceTicketTypes to retrieve the current configuration, remove the service ticket types you wish to delete from the result set, and then use the PUT method at the endpoint /{tenant}/serviceTicketTypes to update the configuration.

Required scope: hybris.serviceticket_configuration_delete

/{tenant}/serviceTicketClassifications

Service ticket classification configuration

/{tenant}/serviceTicketClassifications

get

Retrieve the configured service ticket classifications.

Required scope: hybris.serviceticket_configuration_view

put

Update the service ticket classification configuration.

Note that the service ticket classification configuration you provide in the request body will overwrite the complete existing service ticket classification configuration. If you would like to update only a subset of the configured service ticket classifications, use the GET method at the endpoint /{tenant}/serviceTicketClassifications to retrieve the current configuration, make the desired adjustments to the result set, and then use the PUT method at the endpoint /{tenant}/serviceTicketClassifications to update the configuration.

Required scope: hybris.serviceticket_configuration_manage

delete

Delete the service ticket classification configuration.

Note that the complete service ticket classification configuration will be deleted. If you would like to delete only a subset of the configured service ticket classifications, use the GET method at the endpoint /{tenant}/serviceTicketClassifications to retrieve the current configuration, remove the service ticket classifications you wish to delete from the result set, and then use the PUT method on the endpoint /{tenant}/serviceTicketClassifications to update the configuration.

Required scope: hybris.serviceticket_configuration_delete


Events

For more information about events, see the PubSub service documentation.

The topic owner client is: hybris.serviceticket

Event TypeDescriptionPayloadExample
hybris.serviceticket.serviceticket-createdService Ticket createdschemajson { "payload" : { "assignedTo" : "mandy@hybristest.com", "classification" : [ { "classification" : "BASIC_TECHNICAL_SKILLS", "description" : { "de" : "Technische Grundkenntnisse erforderlich", "en" : "Basic technical skills required" } } ], "createdBy" : "mandy@hybristest.com", "customerId" : "C0750876755", "dueAt" : "2015-06-30T23:59:59.999+0000", "id" : "580750d939fa36001d6e44c6", "metadata" : { "createdAt" : "2016-10-19T10:54:17.602+0000", "modifiedAt" : "2016-10-19T10:54:17.602+0000", "version" : 1 }, "modifiedBy" : "mandy@hybristest.com", "priority" : "HIGH", "priorityDescription" : { "de" : "Hoch", "en" : "High" }, "processingTime" : 2, "productId" : "54e60e07d26ec374ee8e769f", "shortDescription" : "Request for regular maintenance", "status" : "IN_PROCESS", "statusDescription" : { "de" : "In Bearbeitung", "en" : "In Process" }, "ticketNumber" : "J6BAQC", "type" : "SERVICE_REQUEST", "typeDescription" : { "de" : "Serviceanfrage", "en" : "Service Request" }}}
hybris.serviceticket.serviceticket-updatedService Ticket updatedschemajson{ "payload" : { "assignedTo" : "mandy@hybristest.com", "classification" : [ { "classification" : "BASIC_TECHNICAL_SKILLS", "description" : { "de" : "Technische Grundkenntnisse erforderlich", "en" : "Basic technical skills required" } } ], "createdBy" : "mandy@hybristest.com", "customerId" : "C0750876755", "dueAt" : "2015-06-30T23:59:59.999+0000", "id" : "580750d939fa36001d6e44c6", "metadata" : { "createdAt" : "2016-10-19T10:54:17.602+0000", "modifiedAt" : "2016-10-19T11:00:21.099+0000", "version" : 2 }, "modifiedBy" : "mandy@hybristest.com", "priority" : "HIGH", "priorityDescription" : { "de" : "Hoch", "en" : "High" }, "processingTime" : 365, "productId" : "54e60e07d26ec374ee8e769f", "shortDescription" : "Request for regular maintenance", "status" : "IN_PROCESS", "statusDescription" : { "de" : "In Bearbeitung", "en" : "In Process" }, "ticketNumber" : "J6BAQC", "type" : "SERVICE_REQUEST", "typeDescription" : { "de" : "Serviceanfrage", "en" : "Service Request" }}}
hybris.serviceticket.serviceticket-deletedService Ticket deletedschemajson{ "payload" : { "id" : "580750d939fa36001d6e44c6"}}


Scopes

The table shows the scopes that the Service Ticket service supports.

SCOPEDESCRIPTION
hybris.serviceticket_viewRead-only access to service tickets.
hybris.serviceticket_manageCreate and update service tickets.
hybris.serviceticket_deleteDelete service tickets.
hybris.serviceticket_configuration_viewRead-only access to service ticket configuration.
hybris.serviceticket_configuration_manageCreate and update service ticket configuration.
hybris.serviceticket_configuration_deleteDelete service ticket configuration.

For more information about scopes, authorization, and authentication procedures for YaaS services, see Scopes and Authorization


Service Ticket Creation Details

When creating a service ticket, provide all the required data as defined in the appropriate schema. You can also add optional information to the request body. This section outlines the details of the structure of the service ticket body and the information that you need to know when you create a new service ticket.

This example shows a newly-created service ticket body:

{
  "assignedTo" : "mandy@hybristest.com",
  "classification" : [{
    "classification" : "BASIC_TECHNICAL_SKILLS",
    "description" : {
     "de" : "Technische Grundkenntnisse erforderlich",
     "en" : "Basic technical skills required"
    }
   }
  ],
  "transcript": [{
    "createdBy": "mandy@hybristest.com",
    "createdAt": "2015-06-19T12:28:07.000+0000",
    "description": "Customer requested to perform regular maintenance of their FOCUS MARES bike"
   }
  ],
  "createdBy" : "mandy@hybristest.com",
  "customerId" : "C0750876755",
  "dueAt" : "2015-06-30T23:59:59.999+0000",
  "id" : "580750d939fa36001d6e44c6",
  "metadata" : {
    "createdAt" : "2016-10-19T10:54:17.602+0000",
    "modifiedAt" : "2016-10-19T10:54:17.602+0000",
    "mixins": {
      "collectors_info": "https://devportal.yaas.io/services/document/latest/download/comicCollectorValue_v1.json"
    },
    "version" : 1
  },
  "mixins" : {
    "collectors_info" : {
       "CollectorsValue": {
          "usd": 30.99,
          "eur": 23.99
       }  
    },
  },
  "modifiedBy" : "mandy@hybristest.com",
  "priority" : "HIGH",
  "priorityDescription" : {
   "de" : "Hoch",
   "en" : "High"
  },
  "processingTime" : 2,
  "productId" : "54e60e07d26ec374ee8e769f",
  "shortDescription" : "Request for regular maintenance",
  "status" : "IN_PROCESS",
  "statusDescription" : {
   "de" : "In Bearbeitung",
   "en" : "In Process"
  },
  "ticketNumber" : "J6BAQC",
  "type" : "SERVICE_REQUEST",
  "typeDescription" : {
   "de" : "Serviceanfrage",
   "en" : "Service Request"
  }
}

Basic information

  • customerId: Identifier of the customer the service ticket is opened for.
  • productId: Identifier of the product the ticket is opened for.
  • assignedTo: The processor of the service ticket.
  • status: Service ticket status, such as OPEN, IN_PROCESS, COMPLETED or CONFIRMED
  • priority: Service ticket priority, such as VERY_HIGH, HIGH, MEDIUM or LOW.
  • type: Service ticket type.
  • classification: Service ticket classification.

TicketNumber information

The property ticketNumber allows you to assign a human-readable value as an identifier for the service ticket. To assign a service ticket number externally, you must guarantee that it is unique.

If you do not provide a ticketNumber value, or if you leave the value of the property empty, as shown below, the service automatically generates a service ticket number:

{
  ...,

  "ticketNumber" : "",
  ...
}

Transcript information

This property allows the processor of the service ticket to enter additional information about the processing status.

{

    ...,
    "transcript":
    [
        {
            "createdBy": "mandy@hybristest.com",
            "createdAt": "2015-06-19T12:28:07.000+0000",
            "description": "Customer requested to perform regular maintenance of their FOCUS MARES bike"
        }
    ],
    ...

}


Extend Service Ticket Information

Each service ticket contains a set of properties that uniquely identifies and defines it. For example, the service ticket id property identifies a specified service ticket instance, and the customerId property identifies the customer that the service ticket was opened for.

The few properties that are defined by the service ticket schema are common to all items of the service ticket type. These properties are flexible and adjustable and can vary from one service ticket to the other. You can define additional properties and reuse them in different service tickets.

The service ticket mixin feature lets you define a set of reusable properties for use in different service tickets. You can assign one mixin to many service tickets, or you can use many mixins in one service ticket. This approach supports flexibility, reusability, and structural consistency among all your service tickets.

To use mixins, first create the service ticket mixin schema in the Schema service, and then apply it by referring to the URL of the schema. Another way to add mixins is to include definition of mixin schema into the service request call. For information about creating a mixin, see Mixin Schema. For information about using a mixin, see Use the Mixin Schema.

Mixin schema

To create a mixin, define the mixin within a schema using the Schema service, or you can create the mixin within the service request.

  • If you create the mixin in the Schema service, you only have to call the mixin URL and assign a value to the mixin within the request.
  • If you create the mixin directly in the request call (inline schema), enter the same properties each time you add the mixin to the service ticket.

This is an example of the mixin structure for both methods:

{

    "$schema": "http://json-schema.org/draft-04/schema#",
    "type": "object",
    "properties": {
      "instruction": {
        "type": "string"
      }
    }

}

You can use the mixin to extend the service ticket. The properties in mixin are not part of the service ticket schema, but are part of the mixin schema.

Use the mixin schema

After you create a mixin schema, you can add the mixin to the service ticket either when you create a new service ticket, or when you update an existing service ticket.

This example shows a mixin schema added to the service ticket by including definition of the mixin.

{
    ...,
    "mixins" : {
        "additionalCode" : {
            "code" : "ABC"
        }
    },
    "metadata" : {
        "mixins" : {
            "additionalCode" : {
                "$schema" : "http://json-schema.org/draft-04/schema#",
                "type" : "object",
                "properties" : {
                    "code" : {
                        "type" : "string"
                    }
                }

            }
        }
    },
    ...
} 

This example shows a mixin schema added to the service ticket by referring to the URL.

{

    ...,
    "mixins":{
      "additionalCode": {
        "code": "ABC"
      }
    },
    "metadata": {
      "mixins": {
        "additionalCode": "https://api.beta.yaas.io/hybris/schema/v1/myexampleshop/example-schema.json"
      }
    },
    ...

}

For tutorials about how to add mixins to a service ticket, see Extend Service Ticket with Mixins.


Service Ticket Attachments

You can upload files as attachments to a service ticket. Currently, PDF, MP4, JPG, PNG, and TXT file types are supported.

Use these endpoints to perform operations on attachments:

  • /{tenant}/serviceTickets/{id}/attachments: Upload an attachment, delete all attachments, or retrieve metadata for all attachments in a service ticket.
  • /{tenant}/serviceTickets/{id}/attachments/{fileId}: Update the attachment metadata, delete an attachment, or retrieve the download link for the specified attachment.


Service Ticket Priorities

The service ticket priority defines the importance or urgency of a service ticket. Use the /{tenant}/serviceTicketPriorities endpoint to retrieve a complete overview of the supported values and descriptions used to define the service ticket priority.


Service Ticket Statuses

The service ticket status represents the processing status of a service ticket. Use the /{tenant}/serviceTicketStatuses endpoint to retrieve the allowed values and descriptions for the service ticket status.


Service Ticket Types

Service ticket types represent the different types of service tickets. You can define service ticket types according to the services that you provide, such as requests for repairs, servicing, and general inquiries.

Call the endpoint /{tenant}/serviceTicketTypes to configure the service ticket types using these methods:

  • The PUT method supports both creating and updating service ticket types.
  • The DELETE method deletes all the service ticket types configuration.
  • The GET method retrieves the current service ticket types configuration.
The service only supports full update, in which the entire configuration uses the values you provide in the PUT request. When updating the service ticket types configuration, first, retrieve the current configuration from your tenant. Then, modify the data and send it, in its entirety, in the PUT request to the endpoint, even if you just want to insert a new entry or modify an existing entry.


Service Ticket Classification

You can categorize service tickets, such as basic consulting skills, basic technical skills, advanced technical skills.

Call the endpoint /{tenant}/serviceTicketClassifications to configure the service ticket classifications using these methods:

  • The PUT method supports both creating and updating service ticket classifications.
  • The DELETE method deletes all the service ticket classifications configuration.
  • The GET method retrieves the current service ticket classifications configuration.
The service only supports full update, in which the entire configuration uses the values you provide in the PUT request. When updating the service ticket classifications configuration, first, retrieve the current configuration from your tenant. Then, modify the data and send it, in its entirety, in the PUT request to the endpoint, even if you just want to insert a new entry or modify an existing entry.


Create a Service Ticket

To create a service ticket, you need:

Request

  • Method: POST
  • Request URL: https://api.beta.yaas.io/hybris/serviceticket/v1/{tenant}/serviceTickets
  • Headers
    • Authorization: This includes a valid OAuth2 access token. To access this method, the access token must be issued for the requested tenant and have the scope hybris.serviceticket_manage.
  • URI Parameters
    • {tenant}: The name of the current tenant.
  • Body:
    {
      "type" : "SERVICE_REQUEST",
      "priority" : "HIGH",
      "classification" :
      [{
              "classification" : "BASIC_TECHNICAL_SKILLS"
          }
      ],
      "status" : "IN_PROCESS",
      "dueAt" : "2015-06-30T23:59:59.999+0000",
      "customerId" : "C0750876755",
      "productId" : "54e60e07d26ec374ee8e769f",
      "shortDescription" : "Request for regular maintenance",
      "assignedTo" : "mandy@hybristest.com",
      "transcript" :
      [{
              "createdBy" : "mandy@hybristest.com",
              "createdAt" : "2015-06-19T12:28:07.000+0000",
              "description" : "Customer requested regular maintenance of their FOCUS MARES bike"
          }
      ],
      "createdBy" : "mandy@hybristest.com",
      "modifiedBy" : "mandy@hybristest.com"
    }
    

Response

The successful response returns a 201 status code. An example JSON content looks similar to the following:

{
  "id": "55473b487deefe21340ae74f",
  "link": "https://api.beta.yaas.io/hybris/serviceticket/v1/myexampleshop/serviceTickets/55473b487deefe21340ae74f"
}


Update a Service Ticket

To update a service ticket, you need:

Request

  • Method: PUT
  • Request URL: https://api.beta.yaas.io/hybris/serviceticket/v1/{tenant}/serviceTickets/{id}
  • Headers
    • Authorization: This includes a valid OAuth2 access token. To access this method, the access token must be issued for the requested tenant and have the scope hybris.serviceticket_manage.
  • URI Parameters

    • {tenant}: The name of the current tenant.
    • {id}: The identifier of the specified service ticket.
  • Body:

    {
    "id" : "55473b487deefe21340ae74f",
    "ticketNumber" : "TN0001",
    "type" : "SERVICE_REQUEST",
    "classification" :
    [{
     "classification" : "BASIC_TECHNICAL_SKILLS"
    }
    ],
    "mixins" : {
    "collectors_info" : {
     "CollectorsValue" : {
      "usd" : 51.22,
      "eur" : 23.44
     }
    }
    },
    "priority" : "HIGH",
    "status" : "IN_PROCESS",
    "customerId" : "C0750876755",
    "productId" : "54e60e07d26ec374ee8e769f",
    "shortDescription" : "Request for regular maintenance",
    "assignedTo" : "mandy@hybristest.com",
    "transcript" :
    [{
     "createdBy" : "mandy@hybristest.com",
     "createdAt" : "2015-06-19T12:28:07.000+0000",
     "description" : "Customer requested regular maintenance of their FOCUS MARES bike"
    }
    ],
    "createdBy" : "mandy@hybristest.com",
    "modifiedBy" : "mandy@hybristest.com",
    "metadata" : {
    "version" : 1,
    "mixins" : {
     "collectors_info" : "https://devportal.yaas.io/services/document/latest/download/comicCollectorValue_v1.json"
    }
    }
    }
    

Response

The successful response returns a 204 status code.

The error code 409 means the specified service ticket was updated immediately preceding your update attempt. If you receive this error code, retrieve the service ticket and update it again.


Delete a Service Ticket

To delete a service ticket, you need:

Request

  • Method: DELETE
  • Request URL: https://api.beta.yaas.io/hybris/serviceticket/v1/{tenant}/serviceTickets/{id}
  • Headers

    • Authorization: This includes a valid OAuth2 access token. To access this method, the access token must be issued for the requested tenant and have the scope hybris.serviceticket_delete.
  • URI Parameters

    • {tenant}: The name of the current tenant.
    • {id}: The identifier of the specified service ticket.

Response

The successful response returns a 204 status code.


Retrieve a Service Ticket

To retrieve a service ticket, you need:

Request

  • Method: GET
  • Request URL: https://api.beta.yaas.io/hybris/serviceticket/v1/{tenant}/serviceTickets/{id}
  • Headers
    • Authorization: This includes a valid OAuth2 access token. To access this method, the access token must be issued for the requested tenant and have the scope hybris.serviceticket_view.
  • URI Parameters
    • {tenant}: The name of the current tenant.
    • {id}: The identifier of the specified service ticket.

Response

The successful response returns a 200 status code. An example JSON content looks similar to the following:

{
    "id": "55473b487deefe21340ae74f",
    "ticketNumber": "1000000001",
    "type": "SERVICE_REQUEST",
    "typeDescription": "Service Request",
    "classification":
    [
         {
             "classification": "BASIC_TECHNICAL_SKILLS",
             "description": "Basic technical skills required"
         }
    ],
    "mixins" : 
    {
        "collectors_info" : 
        {
            "CollectorsValue": 
            {
                "usd": 30.99,
                "eur": 23.99
            }
          }  
    },
    "priority": "HIGH",
    "priorityDescription": "High",
    "status": "IN_PROCESS",
    "statusDescription": "In Process",
    "dueAt": "2015-06-30T23:59:59.999+0000",
    "processingTime": 432000,
    "customerId": "C0750876755",
    "productId" : "54e60e07d26ec374ee8e769f",
    "shortDescription" : "Request for regular maintenance",
    "assignedTo": "mandy@hybristest.com",
    "transcript":
    [
        {
            "createdBy": "mandy@hybristest.com",
            "createdAt": "2015-06-19T12:28:07.000+0000",
            "description": "Customer requested to perform regular maintenance of their FOCUS MARES bike"
        }
    ],
    "createdBy": "mandy@hybristest.com",
    "modifiedBy": "mandy@hybristest.com",
    "metadata":
    {
        "createdAt": "2015-06-19T12:28:07.000+0000",
        "modifiedAt": "2015-06-19T12:28:07.000+0000",
        "version": 1,
        "mixins" : 
        {
           "collectors_info" : "https://devportal.yaas.io/services/document/latest/download/comicCollectorValue_v1.json"
        }
    }
}


Retrieve All Service Tickets

To retrieve a collection of service tickets, you need:

Request

  • Method: GET
  • Request URL: https://api.beta.yaas.io/hybris/serviceticket/v1/{tenant}/serviceTickets
  • Headers

    • Authorization: This includes a valid OAuth2 access token. To access this method, the access token must be issued for the requested tenant and have the scope hybris.serviceticket_view.
  • URI Parameters

    • {tenant}: The name of the current tenant.

Response

The successful response returns a 200 status code. An example JSON content looks similar to the following:

{
    "id": "55473b487deefe21340ae74f",
    "ticketNumber": "1000000001",
    "type": "SERVICE_REQUEST",
    "typeDescription": "Service Request",
    "classification":
    [
         {
             "classification": "BASIC_TECHNICAL_SKILLS",
             "description": "Basic technical skills required"
         }
    ],
    "mixins" : 
    {
        "collectors_info" : 
        {
            "CollectorsValue": 
            {
                "usd": 30.99,
                "eur": 23.99
            }
          } 
    },
    "priority": "HIGH",
    "priorityDescription": "High",
    "status": "IN_PROCESS",
    "statusDescription": "In Process",
    "dueAt": "2015-06-30T23:59:59.999+0000",
    "processingTime": 432000,
    "customerId": "C0750876755",
    "productId" : "54e60e07d26ec374ee8e769f",
    "shortDescription" : "Request for regular maintenance",
    "assignedTo": "mandy@hybristest.com",
    "transcript":
    [
        {
            "createdBy": "mandy@hybristest.com",
            "createdAt": "2015-06-19T12:28:07.000+0000",
            "description": "Customer requested to perform regular maintenance of their FOCUS MARES bike"
        }
    ],
    "createdBy": "mandy@hybristest.com",
    "modifiedBy": "mandy@hybristest.com",
    "metadata":
    {
        "createdAt": "2015-06-19T12:28:07.000+0000",
        "modifiedAt": "2015-06-19T12:28:07.000+0000",
        "version": 1,
        "mixins" : 
        {
           "collectors_info" : "https://devportal.yaas.io/services/document/latest/download/comicCollectorValue_v1.json"
        }
    }
}


Extend Service Ticket with Mixins

To retrieve a collection of service tickets, you need:

Request

  • Method: GET
  • Request URL: https://api.beta.yaas.io/hybris/serviceticket/v1/{tenant}/serviceTickets
  • Headers

    • Authorization: This includes a valid OAuth2 access token. To access this method, the access token must be issued for the requested tenant and have the scope hybris.serviceticket_view.
  • URI Parameters

    • {tenant}: The name of the current tenant.

Response

The successful response returns a 200 status code. An example JSON content looks similar to the following:

{
    "id": "55473b487deefe21340ae74f",
    "ticketNumber": "1000000001",
    "type": "SERVICE_REQUEST",
    "typeDescription": "Service Request",
    "classification":
    [
         {
             "classification": "BASIC_TECHNICAL_SKILLS",
             "description": "Basic technical skills required"
         }
    ],
    "mixins" : 
    {
        "collectors_info" : 
        {
            "CollectorsValue": 
            {
                "usd": 30.99,
                "eur": 23.99
            }
          } 
    },
    "priority": "HIGH",
    "priorityDescription": "High",
    "status": "IN_PROCESS",
    "statusDescription": "In Process",
    "dueAt": "2015-06-30T23:59:59.999+0000",
    "processingTime": 432000,
    "customerId": "C0750876755",
    "productId" : "54e60e07d26ec374ee8e769f",
    "shortDescription" : "Request for regular maintenance",
    "assignedTo": "mandy@hybristest.com",
    "transcript":
    [
        {
            "createdBy": "mandy@hybristest.com",
            "createdAt": "2015-06-19T12:28:07.000+0000",
            "description": "Customer requested to perform regular maintenance of their FOCUS MARES bike"
        }
    ],
    "createdBy": "mandy@hybristest.com",
    "modifiedBy": "mandy@hybristest.com",
    "metadata":
    {
        "createdAt": "2015-06-19T12:28:07.000+0000",
        "modifiedAt": "2015-06-19T12:28:07.000+0000",
        "version": 1,
        "mixins" : 
        {
           "collectors_info" : "https://devportal.yaas.io/services/document/latest/download/comicCollectorValue_v1.json"
        }
    }
}


Update Service Ticket Status

To update the status of a service ticket, you need:

Request

  • Method: PUT
  • Request URL: https://api.beta.yaas.io/hybris/serviceticket/v1/{tenant}/serviceTickets/{id}
  • Headers

    • Authorization: This includes a valid OAuth2 access token. To access this method, the access token must be issued for the requested tenant and have the scope hybris.serviceticket_manage.
  • URI Parameters

    • {tenant}: The name of the current tenant.
    • {id}: The identifier of the specified service ticket.
  • Body:
{
    "id": "55473b487deefe21340ae74f",
    "ticketNumber": "1000000001",
    "type": "SERVICE_REQUEST",
    "classification":
    [
         {
             "classification": "BASIC_TECHNICAL_SKILLS"
         }
    ],
     "mixins" : 
    {
        "collectors_info" : 
        {
            "CollectorsValue": 
            {
                "usd": 51.22,
                "eur": 23.44
            }
          } 
    },
    "priority": "HIGH",
    "status": "IN_PROCESS",
    "customerId": "C0750876755",
    "productId" : "54e60e07d26ec374ee8e769f",
    "shortDescription" : "Request for regular maintenance",
    "assignedTo": "mandy@hybristest.com",
    "transcript":
    [
        {
            "createdBy": "mandy@hybristest.com",
            "createdAt": "2015-06-19T12:28:07.000+0000",
            "description": "Customer requested regular maintenance of their FOCUS MARES bike"
        }
    ],
    "createdBy": "mandy@hybristest.com",
    "modifiedBy": "mandy@hybristest.com",
    "metadata":
    {
        "version": 1,
        "mixins" : 
        {
            "collectors_info" : "https://devportal.yaas.io/services/document/latest/download/comicCollectorValue_v1.json"
        }
    }
}

Response

The successful response returns a 204 status code.


Add an Attachment to a Service Ticket

The example code in this section shows how to upload a file as an attachment for a service ticket. To upload attachments, use the multipart/form-data content type in the request body.

To add an attachment to a service ticket, you need

Request

  • Method: POST
  • Request URL: https://api.beta.yaas.io/hybris/serviceticket/v1/{tenant}/serviceTickets/{id}/attachments
  • Headers

    • Authorization: This includes a valid OAuth2 access token. To access this method, the access token must be issued for the requested tenant and have the scope hybris.serviceticket_manage.
  • URI Parameters

    • {tenant}: The name of the current tenant.
    • {id}: The identifier of the specified service ticket.
var file;
loadFile('filePlaceholder', 'readAsArrayBuffer', function(e) {
 file = e.target.result;
 }); 
file

var request = jQuery.ajax({
 url: requestUrl,
 type: 'POST',
 contentType: 'multipart/form-data',
 data: file,
 processData: false,
 async: false 
}).done(function(){console.log('attachment uploaded');});
request.status

Response

The successful response returns a 201 status code. An example JSON content looks similar to the following:

{
    "id": "57173ab02e9465001db61956",
    "link": "https://api.beta.yaas.io/hybris/serviceticket/v1/myexampleshop/serviceTickets/565cb63d9aae8a28f217a8b7/attachments/57173ab02e9465001db61956"
}


Delete an Attachment for a Service Ticket

To delete an attachment for a service ticket, you need:

Request

  • Method: DELETE
  • Request URL: https://api.beta.yaas.io/hybris/serviceticket/v1/{tenant}/serviceTickets/{id}/attachments/{fileId}
  • Headers
    • Authorization: This includes a valid OAuth2 access token. To access this method, the access token must be issued for the requested tenant and have the scope hybris.serviceticket_manage.
  • URI Parameters

    • {tenant}: The name of the current tenant.

    • {id}: The identifier of the specified service ticket.

    • {fileId}: The identifier of the specified attachment.

Response

The successful response returns a 204 status code.


Update the Metadata for an Attachment

To update the metadata for an attachment for a service ticket, you need:

Request

  • Method: PUT
  • Request URL: https://api.beta.yaas.io/hybris/serviceticket/v1/{tenant}/serviceTickets/{id}/attachments/{fileId}
  • Headers

    • Authorization: This includes a valid OAuth2 access token. To access this method, the access token must be issued for the requested tenant and have the scope hybris.serviceticket_manage.
  • URI Parameters

    • {tenant}: The name of the current tenant.
    • {id}: The identifier of the specified service ticket.
    • {fileId}: The identifier of the specified attachment.
  • Body: This is an example of the attachment metadata to send with your PUT request. Include the file name in the JSON-formatted property name.
{
  "name": "attachment.jpg"
}

Response

The successful response returns a 204 status code.


Retrieve the Download Link for an Attachment

To retrieve the download link for an attachment, you need:

Request

  • Method: GET
  • Request URL: https://api.beta.yaas.io/hybris/serviceticket/v1/{tenant}/serviceTickets/{id}/attachments/{fileId}
  • Headers
    • Authorization: This includes a valid OAuth2 access token. To access this method, the access token must be issued for the requested tenant and have the scope hybris.serviceticket_view.
  • URI Parameters
    • {tenant}: The name of the current tenant.
    • {id}: The identifier of the specified service ticket.
    • {fileId}: The identifier of the specified attachment.

Response

The successful response returns a 200 status code. An example JSON content looks similar to the following:

{
  "link": "https://s3.amazonaws.com/bucket/7367728b18aef6ef24a04e39?x-amz-security-token=AQoDYXdz..."
}


Retrieve all Attachments for a Service Ticket

To retrieve all attachments metadata for a service ticket, you need:

Request

  • Method: GET
  • Request URL: https://api.beta.yaas.io/hybris/serviceticket/v1/{tenant}/serviceTickets/{id}/attachments
  • Headers:
    • Authorization: This includes a valid OAuth2 access token. To access this method, the access token must be issued for the requested tenant and have the scope hybris.serviceticket_view.
  • URI Parameters:
    • {tenant}: The name of the current tenant.
    • {id}: The identifier of the specified service ticket.

Response

The successful response returns a 200 status code. An example JSON content looks similar to the following:

[
  {
    "id": "5367728b18aef6ef24a04e38",
    "metadata": {
      "name": "attachment1.jpg",
      "size": "1024000",
      "createdBy": "mandy@hybristest.com",
      "createdAt": "1459335611324",
      "modifiedBy": "mandy@hybristest.com",
      "modifiedAt": "1459335611324"
    }
  },
  {
    "id": "5367728b18aef6ef24a04e39",
    "metadata": {
      "name": "attachment1.zip",
      "size": "1024000",
      "createdBy": "mandy@hybristest.com",
      "createdAt": "1459335611324",
      "modifiedBy": "mandy@hybristest.com",
      "modifiedAt": "1459335611324"
    }
  }
]


Retrieve Help Values of Statuses

To retrieve the allowed values for the service ticket status, you need:

Request

  • Method: GET
  • Request URL: https://api.beta.yaas.io/hybris/serviceticket/v1 /{tenant}/serviceTicketStatuses
  • Headers:
    • Authorization: This includes a valid OAuth2 access token. To access this method, the access token must be issued for the requested tenant and have the scope hybris.serviceticket_configuration_view.
    • hybris-languages: Provide language identifiers to retrieve the required language version for the status descriptions from the service. The service supports multiple language identifier values. Separate multiple language identifiers with commas. If you do not provide a language identifier, the service returns all available versions of the status description. For example, if you specify the language identifier de, the service returns only the e German version of the status description.
  • URI Parameters
    • {tenant}: The name of the current tenant.

Response

The successful response returns a 200 status code. An example JSON content looks similar to the following:

[
    {
        "status": "OPEN",
        "description":
        {
            "en": "Open",
            "de": "Offen"
        }
    },
    {
        "status": "IN_PROCESS",
        "description":
        {
            "en": "In Process",
            "de": "In Bearbeitung"
        }
    },
    {
        "status": "COMPLETED",
        "description":
        {
            "en": "Completed",
            "de": "Abgeschlossen"
        }
    },
    {
        "status": "CONFIRMED",
        "description":
        {
            "en": "Confirmed",
            "de": "Bestätigt"
        }
    }
]


Retrieve Help Values of Priorities

To retrieve the allowed values for the service ticket priorities, you need:

Request

  • Method: GET
  • Request URL: https://api.beta.yaas.io/hybris/serviceticket/v1 /{tenant}/serviceTicketPriorities
  • Headers

    • Authorization: This includes a valid OAuth2 access token. To access this method, the access token must be issued for the requested tenant and have the scope hybris.serviceticket_configuration_view.
    • hybris-languages: Provide language identifiers to retrieve the required language version for the priority descriptions from the service. The service supports multiple language identifier values. Separate multiple language identifiers with commas. If you do not provide a language identifier, the service returns all available versions of the priority descriptions. For example, if you specify the language identifier de, the service returns only the German version of the priority descriptions.
  • URI Parameters

    • {tenant}: The name of the current tenant.

Response

The successful response returns a 200 status code. An example JSON content looks similar to the following:

[
    {
        "priority": "VERY_HIGH",
        "description": 
        {
            "en": "Very high",
            "de": "Sehr hoch"
        }
    },
    {
        "priority": "HIGH",
        "description": 
        {
            "en": "High",
            "de": "Hoch"
        }
    }, 
    {
        "priority": "MEDIUM",
        "description":
        {
            "en": "Medium",
            "de": "Mittel"
        }
    },
    {
        "priority": "LOW",
        "description":
        {
            "en": "Low",
            "de": "Niedrig"
        }
    }
]


Manage Service Ticket Types

To retrieve the configured service ticket types, you need:

Request

  • Method: GET
  • Request URL: https://api.beta.yaas.io/hybris/serviceticket/v1 /{tenant}/serviceTicketTypes
  • Headers
    • Authorization: This includes a valid OAuth2 access token. To access this method, the access token must be issued for the requested tenant and have the scope hybris.serviceticket_configuration_view.
  • URI Parameters
    • {tenant}: The name of the current tenant.

Response

The successful response returns a 200 status code. An example JSON content looks similar to the following:

[
    {
        "active": true,
        "type": "GENERAL_INQUIRY",
        "description":
        {
            "en": "General Inquiry",
            "de": "Allgemeine Anfrage"
        }
    },
    {
        "active": false,
        "type": "REPAIR",
        "description":
        {
            "en": "Repair",
            "de": "Reparatur"
        }
    },
    {
        "active": true,
        "type": "SERVICE_REQUEST",
        "description":
        {
            "en": "Service Request",
            "de": "Serviceanfrage"
        }
    }
]

To update the service ticket types, you need:

Request

  • Method: PUT
  • Request URL: https://api.beta.yaas.io/hybris/serviceticket/v1 /{tenant}/serviceTicketTypes
  • Headers

    • Authorization: This includes a valid OAuth2 access token. To access this method, the access token must be issued for the requested tenant and have the scope hybris.serviceticket_configuration_manage.
  • URI Parameters

    • {tenant}: The name of the current tenant.
  • Body: This is an example of a request body for service ticket types:

    [
      {
          "active": true,
          "type": "GENERAL_INQUIRY",
          "description":
          {
              "en": "General Inquiry",
              "de": "Allgemeine Anfrage"
          }
      },
      {
          "active": false,
          "type": "REPAIR",
          "description":
          {
              "en": "Repair",
              "de": "Reparatur"
          }
      },
      {
          "active": true,
          "type": "SERVICE_REQUEST",
          "description":
          {
              "en": "Service Request",
              "de": "Serviceanfrage"
          }
      }
    ]
    

Response

The successful response returns a 204 status code.

To delete the service ticket types, you need:

Request

  • Method: DELETE
  • Request URL: https://api.beta.yaas.io/hybris/serviceticket/v1 /{tenant}/serviceTicketTypes
  • Headers
    • Authorization: This includes a valid OAuth2 access token. To access this method, the access token must be issued for the requested tenant and have the scope hybris.serviceticket_configuration_delete.
  • URI Parameters
    • {tenant}: The name of the current tenant.

Response

The successful response returns a 204 status code.


Manage Service Ticket Classifications

To retrieve the configured service ticket classifications, you need:

Request

  • Method: GET
  • Request URL: https://api.beta.yaas.io/hybris/serviceticket/v1 /{tenant}/serviceTicketClassifications
  • Headers
    • Authorization: This includes a valid OAuth2 access token. To access this method, the access token must be issued for the requested tenant and have the scope hybris.serviceticket_configuration_view.
  • URI Parameters
    • {tenant}: The name of the current tenant.

Response

The successful response returns a 200 status code. An example JSON content looks similar to the following:

[
    {
        "active": false,
        "classification": "BASIC_CONSULTING_SKILLS",
        "description":
        {
            "en": "Basic consulting skills required",
            "de": "Consulting-Grundkenntnisse erforderlich"
        }
    },
    {
        "active": true,
        "classification": "BASIC_TECHNICAL_SKILLS",
        "description":
        {
            "en": "Basic technical skills required",
            "de": "Technische Grundkenntnisse erforderlich"
        }
    },
    {
        "active": true,
        "classification": "ADVANCED_TECHNICAL_SKILLS",
        "description":
        {
            "en": "Advanced technical skills required",
            "de": "Fortgeschrittene technische Kenntnisse erforderlich"
        }
    }
]

To update the service ticket classifications, you need:

Request

  • Method: PUT
  • Request URL: https://api.beta.yaas.io/hybris/serviceticket/v1/{tenant}/serviceTicketClassifications
  • Headers
    • Authorization: This includes a valid OAuth2 access token. To access this method, the access token must be issued for the requested tenant and have the scope hybris.serviceticket_configuration_manage.
  • URI Parameters
    • {tenant}: The name of the current tenant.
  • Body:
    [
      {
          "active": false,
          "classification": "BASIC_CONSULTING_SKILLS",
          "description":
          {
              "en": "Basic consulting skills required",
              "de": "Consulting-Grundkenntnisse erforderlich"
          }
      },
      {
          "active": true,
          "classification": "BASIC_TECHNICAL_SKILLS",
          "description":
          {
              "en": "Basic technical skills required",
              "de": "Technische Grundkenntnisse erforderlich"
          }
      },
      {
          "active": true,
          "classification": "ADVANCED_TECHNICAL_SKILLS",
          "description":
          {
              "en": "Advanced technical skills required",
              "de": "Fortgeschrittene technische Kenntnisse erforderlich"
          }
      }
    ]
    

Response

The successful response returns a 204 status code.

To delete the service ticket classifications, you need:

Request

  • Method: DELETE
  • Request URL: https://api.beta.yaas.io/hybris/serviceticket/v1/{tenant}/serviceTicketClassifications
  • Headers
    • Authorization: This includes a valid OAuth2 access token. To access this method, the access token must be issued for the requested tenant and have the scope hybris.serviceticket_configuration_delete.
  • URI Parameters
    • {tenant}: The name of the current tenant.

Response

The successful response returns a 204 status code.


Error Types

For information about error codes, see the API Reference.


Glossary

TermDescription
service ticket mixinCustomizable definition of additional properties for the service ticket. One service ticket definition can use many mixins, and one mixin can be used by many service ticket definitions.


  • Send feedback

    If you find any information that is unclear or incorrect, please let us know so that we can improve the Dev Portal content.

  • Get Help

    Use our private help channel. Receive updates over email and contact our specialists directly.

  • hybris Experts

    If you need more information about this topic, visit hybris Experts to post your own question and interact with our community and experts.