Ticketsystem Integration

Purpose

This document describes the messages sent by ServicePlaza to an external ticketing system. It serves as a technical reference for third parties who want to integrate their ticketing platform with ServicePlaza.

Scope

Please note that this document only covers the messages sent from ServicePlaza to the external ticketing system. It does not cover messages sent in the opposite direction. You'll find the specifications for messages sent from the external ticketing system to ServicePlaza in our API specification:

Generic Ticket Handling API: https://docs.serviceplaza.io/API Reference/07_Lobster/
Creating specific orders based on catalog API: https://docs.serviceplaza.io/API Reference/04_Catalog/

Communication Model

Communication is initiated by ServicePlaza and performed synchronously via HTTP POST to the configured endpoint of the external ticketing system. The interface is REST-based and uses JSON payloads.

ServicePlaza supports the following authentication mechanisms for integrating external ticketing systems:

Username & Password
OAuth

Summary:

Transport Protocol: HTTP(S)
Method: POST
Data Format: JSON
Successful Response: HTTP 200 OK

Each message contains a ticket transaction. The transaction type is identified by the action field.

Supported Message Types

The following message types can be sent from ServicePlaza to the external ticketing system:

Action	Description
New Customer Ticket	Create a new ticket
NewAck	Acknowledgement of an existing ticket
Update	Ticket update, status update, or comment
Ticket closed	Close a ticket
ReOpen	Reopen an existing ticket

General Integration Requirements

An external ticketing system should:

Process messages based on the action field.
Correlate tickets using customerTicketNumber and damovoTicketNumber.
Support Base64-encoded attachments.
Accept optional fields.
Receive JSON messages via HTTP POST.
Return HTTP 200 OK after successful processing.

Message: New Customer Ticket

Purpose

Creates a new ticket in the target system.

Attributes

Field	Description
action	New Customer Ticket
customerTicketNumber	Unique ticket reference from the source system
customerSiteReference	Customer site reference
damovoSiteID	Site identifier
briefDescription	Short ticket description
description	Detailed ticket description
affectedCI	Affected CI or SLA
ciName	Configuration Item name
ciIdentifier	Unique CI identifier
ciSerial	CI serial number
ciSupplier	CI supplier
contactFirstName	Reporter first name
contactName	Reporter last name
contactEmail	Reporter email address
contactPhone	Reporter phone number
locationNumber	Site number
siteCity	Site city
siteAddressline1	Site address
sitePostalCode	Postal code
ticketType	Ticket type
priority	Priority
customerIdentification	Customer identifier
cstMsgObjID	Technical message identifier
catalogIds	Referenced catalog entries
attachments	Optional file attachment

Attachment Structure

{
  "filename": "document.pdf",
  "dataBase64": "BASE64_CONTENT"
}

Example

{
  "action": "New Customer Ticket",
  "customerTicketNumber": "SPOG-12345",
  "briefDescription": "Router Failure",
  "description": "Site is unreachable",
  "priority": "3"
}

Message: NewAck

Purpose

Acknowledgement of an existing ticket.

Attributes

{
  "action": "NewAck",
  "customerTicketNumber": "SPOG-12345",
  "damovoTicketNumber": "ST-4711",
  "cstMsgObjID": "MESSAGE-ID"
}

Message: Update

Purpose

Transfers a status update, comment, or additional attachment.

Attributes

Field	Description
action	Update
customerTicketNumber	Ticket reference of the source system
damovoTicketNumber	Ticket reference of the external ticketing system
customerIdentification	Customer identifier
publicComment	Public comment or status information
attachments	Optional file attachment
cstMsgObjID	Technical message identifier

Example

{
  "action": "Update",
  "customerTicketNumber": "SPOG-12345",
  "damovoTicketNumber": "ST-4711",
  "publicComment": "Technician assigned"
}

Message: Ticket closed

Purpose

Closes an existing ticket.

Attributes

Field	Description
action	Ticket closed
customerTicketNumber	Ticket reference of the source system
damovoTicketNumber	Ticket reference of the external ticketing system
customerIdentification	Customer identifier
solutionDescription	Resolution text or closing information
cstMsgObjID	Technical message identifier

Example

{
  "action": "Ticket closed",
  "customerTicketNumber": "SPOG-12345",
  "damovoTicketNumber": "ST-4711",
  "solutionDescription": "Issue resolved"
}

Message: ReOpen

Purpose

Reopens an existing ticket.

Attributes

Field	Description
action	ReOpen
customerTicketNumber	Ticket reference of the source system
damovoTicketNumber	Ticket reference of the external ticketing system
customerIdentification	Customer identifier
publicComment	Reason for reopening
cstMsgObjID	Technical message identifier

Example

{
  "action": "ReOpen",
  "customerTicketNumber": "SPOG-12345",
  "damovoTicketNumber": "ST-4711",
  "publicComment": "Issue still persists"
}