Technical Integration Details

 

For the current version of the platform, integration with the ticket exchange platform is done via SOAP web services. This section describes the web service APIs in some detail. All web services used with ticket exchange must use SSL (HTTPS). X.509 certificates are used for authentication.

SOAP Web Service Integration

The current version (v1.0) of the Ticket Exchange Platform (TEP) supports only SOAP web services as a means of technical integration with the platform. Other options are planned for implementation in subsequent versions. Below is a listing of web service methods currently exposed on TEP and those which may be exposed by integrating partners, depending on the integration methods selected for onboarding.

Channel Security

All web services used with ticket exchange must use Secure Sockets Layer (SSL) for channel encryption. This includes web services exposed by partners which will be used for ticket exchange.

Authentication

All ticket exchange web services hosted on TEP require X.509 certificate authentication. This means that partners must obtain a certificate suitable for client authentication from a recognized certificate authority and provide Microsoft with the public key certificate.

TEP Web Service Configuration Values

The table below defines key configuration values used on the TEP web service endpoints.

Max String Length	300000

Web Service Fault Types and Codes

The table below defines service fault types and fault codes which can be returned by TEP services and ticket exchange services hosted by partners. The subset of relevant faults is provided in the detailed description of each web method.

Fault Type	Fault Type Code Range	TEP Auto Retry	FaultCode	Fault Code Name	Description	Severity	Thrown By TEP	Thrown By Partner
ServiceUnavailableFault	1000-1999	Yes	1000-1099	Unavailable	Indicates a temporary inability to process a request due to one or more unavailable system resources.	1-High	X	X
			1100	Locked	Indicates a temporary inability to process a request due to data lock(s).	1-Low	X	---
ServiceConfigurationFault	2000-2999	No	2000-2099	Configuration Error	The request could not be processed due to incompatibility between request content and system configuration.	2-Med	X	X
			2100	Authorization Failure	The request could not be processed due to authorization failure.	2-Med	X	X
ServiceValidationFault	3000-3999	No	3000-3099	Validation Failure	Indicates the message content failed validation.	2-Med	X	X
			3100	Ticket Not Found	Indicates that the ticket referenced on a ticket update message was not found in the partner IMS. (TEP will treat this as an indication that the partner has purged the ticket.)	2-Med	---	X
ServiceErrorFault	4000-4999	No	4000-4299	Processing Exception	Processing of the request failed due to a handled exception.	3-High	X	X
ServiceUnknownFault	5000	No	5000	Unhandled Exception	Processing of the request failed due to an unhandled exception.	3-High	X	X

TEP Hosted Web Service Methods

The following defines the set of web methods exposed by TEP. Detail for each is provided in the subsections below.

Ticket Service

• PostTicket() – Used by partners to send ticket messages.

• GetTicket() – Used by partners (recursive) to receive ticket messages.

• ReportTicketResult() – Used in conjunction with GetTicket() to report the result of ticket processing to TEP.

• GetReceipt() – Used by partners (recursive) to retrieve receipt messages.

Attachment Service

• PostAttachment() – Used by partners to send file attachments related to a ticket. This is done prior to the call to PostTicket(). The attachment URI(s) returned by PostAttachment() and included in the ticket message.

• GetAttachment() – Used by partners to retrieve attachments referenced in a ticket message.

TEP PostTicket() Method

Description

The PostTicket() method allows partners to send ticket messages of type new and update. Partners using explicit routing can also use this method to add an additional party to an existing ticket conversation.

Signature

The PostTicket() method accepts a Ticket object as the request and returns PostTicketResponse object as depicted in the method signature below.

PostTicketResponse PostTicket( Ticket )

TEP GetTicket() Method

Description

The GetTicket() method supports retrieval of tickets from TEP by partners using the WSG method of ticket subscription. The method is must be called recursively at a rate no greater than once every 60 seconds.

This method works in combination with the ReportTicketResult() method. A call to GetTicket() must be followed by a call to ReportTicketResult() to mark the ticket as either processed successfully, processing failed, or processing delayed due to resource availability or locking. Without this callback to ReportTicketResult(), the GetTicket() method will continue to return the same ticket object on subsequent calls.

Signature

The GetTicket() method takes no parameters, and returns a Ticket object representing the next ticket message available to the partner. A null object is returned when no ticket messages are available for delivery.

Ticket GetTicket()

TEP ReportTicketResult() Method

Description

As described above, the ReportTicketResult() method works in conjunction with the GetTicket() method. It is used to inform TEP of the result of the ticket processing.

Signature

void ReportTicketResult(TicketMessageProcessingResult)

TEP GetReceipt() Method

Description

The GetReceipt() method supports retrieval of receipt messages by partners using the WSG method of receipt subscription. The method is must be called recursively at a rate no greater than once every 60 seconds.

Signature

The method accepts an integer count, which represents the number of receipts to be returned up to a maximum of 20. The method returns a collection of Receipt objects. The number of Receipt objects returned is the lesser of the number available and the count requested, i.e., count represents the maximum number returned.

Receipt[] GetReceipt( int Count )

TEP PostAttachment() Method

Description

The PostAttachment () method supports sending of file attachments by partners using the WSP method of attachment publication. The method must be called prior to calling PostTicket() so that AttachmentUri objects returned by PostAttachment() can be included in the ticket message.

Signature

The method accepts an Attachment object and returns an AttachmentUri object as depicted in the method signature below.

AttachmentUri PostAttachment( Attachment )

TEP GetAttachment() Method

Description

The GetAttachment() method supports retrieval of file attachments by partners using the WSG method of attachment subscription. The method is called in response to a ticket message received which includes AttachmentUri objects. The partner calls GetAttachment() for each AttachmentUri included in the ticket message to facilitate downloading of the attachment.

Signature

The method accepts an AttachmentUri object and returns an Attachment object as depicted in the method signature below.

Attachment GetAttachment( AttachmentUri )

TEP Hosted REST Services

The subsections below define transactions currently supported on TEP via REST. In all cases, HTTP status codes are returned as follows in addition to any defined XML response:

• Success: HTTP 200

• Failure: HTTP 500

• Unavailable: HTTP 503

Ticket

Tenants can submit Ticket messages to the TEP REST endpoint. TEP will return XML representing PostTicketResponse in addition to HTTP status codes.

Partner Hosted Web Service Methods

The following are APIs which may be hosted by the partner to support TEP integration. There are alternatives for each of these if partners wish to avoid hosting web services. The signatures of these partner-hosted methods are exactly the same as the TEP hosted versions.

• PostTicket() – TEP uses this method to deliver ticket messages to partners. The alternative to hosting PostTicket() is to is for partner to use TEP GetTicket().

• PostReceipt() – TEP uses this method to deliver receipt messages to partners. The alternative to hosting PostReceipt() is to use the TEP GetReceipt() method.

• PostAttachment – TEP uses this method to deliver attachments to partners. This call is made prior to delivery of the related ticket message. URIs returned by partner-hosted PostAttachment() are included in the ticket message. The alternative to hosting PostAttachment() is to use the TEP GetAttachment() method.

• GetAttachment() – TEP uses this method to retrieve attachments from partners based on attachment URIs included in ticket messages sent by partners. The alternative to hosting GetAttachment() is to use the TEP PostAttachment() method.

Partner PostTicket() Method

Description

The partner PostTicket() method allows TEP to deliver ticket messages of type new and update to partners using the WSP method for ticket subscription.

Signature

The PostTicket() method accepts a Ticket object as the request and returns PartnerPostTicketResponse as depicted in the method signature below. The response object includes a property, TicketReference, which must be populated with the unique identifier of the ticket created in the partner system as a result of processing new ticket messages.

PartnerPostTicketResponse PostTicket( Ticket )

Partner PostReceipt() Method

Description

The partner PostReceipt() method allows TEP to deliver receipt messages to partners using the WSP method for receipt subscription.

Signature

The PostReceipt() method accepts a Receipt object and returns void as depicted in the method signature below.

void PostReceipt( Receipt )

Partner PostAttachment() Method

Description

The partner PostAttachment () method allows TEP to deliver file attachments to partners using the WSP method for attachment subscription. The method is called prior to calling partner PostTicket() for each attachment referenced in the ticket message. TEP uses the AttachmentUri objects returned by the partner to populate the Attachments collection of the Ticket prior to delivering the ticket.

Signature

The method accepts an Attachment object and returns an AttachmentUri object as depicted in the method signature below.

AttachmentUri PostAttachment( Attachment )

Partner GetAttachment() Method

Description

The partner GetAttachment () method allows TEP to retrieve file attachments from partners using the WSG method for attachment publication. TEP calls this method in response to a ticket message received from the partner which includes references to file attachments which are found to be required for delivery to one or more receiving partners. TEP uses the AttachmentUri object(s) included in the ticket message to call the partner GetAttachment() method and retrieve the file attachment(s).

Signature

The method accepts an AttachmentUri object and returns an Attachment object as depicted in the method signature below.

Attachment GetAttachment( AttachmentUri )

Supported Partner Hosted REST Service Transactions

The subsections below define transactions which TEP can post to a partner hosted REST service. TEP will interpret HTTP status codes returned as follows:

• Success: HTTP 200

• Failure: HTTP 500 series (except 503)

• Unavailable: HTTP 503

Sample XML is available on the Customer Extranet Site.

Ticket

TEP can send Ticket XML to a partner via REST. The format of the ticket XML posted depends on whether or not the partner response will be done synchronously or asynchronously as defined below:

• Asynchronous

  • Request – TEP sends XML representing RestfulTicketRequest

  • Async Response

    • Option 1 – REST: Partner sends XML representing TicketMessageProcessingResult to the TEP REST endpoint.

    • Option 2 – SOAP: Partner calls TEP ReportTicketResult() API.

• Synchronous

Request – TEP sends XML representing Ticket

Response

• Option 1 – Partner returns XML representing PartnerPostTicketResponse

• Option 2 – No response XML. HTTP status codes are observed to determine if delivery was successful. This option cannot be used for partners receiving new tickets from TEP.

Receipt

TEP can send Receipt XML to a partner via REST. There is no response other than standard HTTP status required in response to the receipt. Below is a sample XML for reciept

Ticket Type

The ticket object is used by a number of web service methods, including PostTicket() and GetTicket(). The class diagram below depicts the object structure. Definitions for the objects and properties are also included in the subsections below.

Ticket Type

The table below defines the properties included on the Ticket class. The required column defines requirements for partners populating a ticket object which will be sent to TEP.

Property Name	Type	Required	Description
MessageType	Enum	X	Supplied by sender. Valid values below:   New Used to initiate a new ticket conversation. Update Used to update an existing ticket conversation. Add Used to add an additional partner to an existing ticket conversation. (This option is not available for all conversation types and partners.)
RequestDateTime	Datetime	---	Supplied by TEP.
SystemTransactionID	GUID	X	New GUID which uniquely identifies the ticket message. Once a ticket message is accepted for processing by TEP, no subsequent ticket messages with the same SystemTransactionID will be accepted.
TrackingReference	String	---	Supplied by sender. This value uniquely represents the ticket message from the perspective of the sender. Receipt messages sent back to the sender will include this reference, thus allowing the sender to associate the receipt message received to the original ticket message sent.
Sender	Partner	---	The Sender property is a Partner object which identifies the sending party that originally sent the ticket message to TEP. The properties are defined directly below.
Sender.ID	Int	---	The TEP unique ID for the sending partner. Supplied by TEP.
Sender.Name	String	---	The TEP name for the sending partner. Supplied by TEP.
Sender.ConversationRoleID	Int	X	The ID for the conversation role the sending partner is using. Required only for ticket messages of type new.
Sender.TicketReference	String	X	The unique identifier for the ticket in the sending partner’s IMS.
Receiver	Partner	---	The Receiver property is a Partner object which identifies the receiving partner. The properties are defined directly below.
Receiver.ID	Int	---	The TEP unique ID for the receiving partner. This is required only on new messages by sending partners using explicit routing, otherwise supplied by TEP.
Reciever.Name	String	---	The TEP name for the receiving partner. Supplied by TEP.
Receiver.ConversationRoleID	Int	---	The ID for the conversation role the sending partner is using. This is required only on ticket messages of type new for sending partners using explicit routing only, otherwise supplied by TEP.
Reciever.TicketReference	String	---	The unique identifier for the ticket in the receiving partners IMS. This is populated by TEP for ticket messages of type update only. It is left empty for ticket messages of type new.
Collections
Details	Detail[]	---	A collection of Detail items which represent properties of the ticket. Detail requirements are defined by the conversation type. Please see the definition of the Detail type below.
Contacts	Contact[]	---	A collection of Contact items which represent individuals involved in resolution of the ticket. Contact requirements are defined by the conversation type. Please see the definition of the Contact type below.
Notes	Note[]	---	A collection of Note items. Note requirements are defined by the conversation type. Please see the definition of the Note type below.
Attachments	AttachmentUri[]	---	A collection of AttachmentUri items. These are used to reference attachments associated with the ticket. It should be noted that while the AttachmentUri represents a location of an attachment, the actual attachment is defined using an Attachment item, and these are not included in the ticket message. Attachment requirements are defined by the conversation type. Please see the definition of the AttachmentUri and Attachment types below.

Detail Type

The Detail class is used to represent a name-value pair which can be added to the following collections:

• Ticket.Details – Used to represent properties of a ticket.

• Contact.Details – Used to extend the direct properties of Contact.

• Note.Details – Used to extend the direct properties of Note.

• AttachmentUri.Details – Used to extend the direct properties of AttachmentUri.

Property Name	Type	Required	Description
Name	String	X	The name property defines the name of the pair.
Value	String	---	The value property defines the value of the pair. Generally a value is required, but this requirement is dependent on the conversation type.
Context	String	---	Can be populated by TEP to meet the specific processing needs of the receiving party.

Contact Type

The Contact class defines an individual participating in ticket resolution and/or email communications regarding the ticket. Contact objects may be included in the Ticket.Contacts collection.

Property Name	Type	Required	Description
Email	String	X	Email address of the contact. Validated for format. Used as the key to the object so cannot be duplicated within the Ticket.Contacts collection.
FirstName	String	---	First name of the contact.
LastName	String	X	Last name of the contact.
Phone Number	String	---	Phone number of the contact.
Type	String	X	Defines the type or role of a contact. These values are defined and validated as part of the conversation type.
IsPrimary	Boolean	X	Defines the primary contact for a ticket. Only one contact in the collection should be set as primary.
IsEmailEnabled	Boolean	X	Defines whether or not a contact should be copied on automated email notifications related to the ticket.
Details	Collection	---	Used for extending the direct properties of the object. These can be defined as part of the conversation type. They may also be used to support the specific integration needs of an integrated party.

Note Type

The Note class defines a freeform note related to the ticket. Note objects may be included in the Ticket.Notes collection and are considered immutable by TEP, i.e., TEP will process new notes but will ignore updates to existing notes.

Property Name	Type	Required	Description
NoteId	String	X	Represents the unique ID of the note as defined in the originating IMS, i.e., the IMS of the integrated party which mastered the note.
Type	String	---	Defines the type of note. These values are defined and validated as part of the conversation type.
Content	String	---	The text of the note.
CreatedDateTime	Datetime	---	The date and time the note was created in the originating IMS. TEP uses this value to properly order notes properly. Date Format: MM/DD/YYYY HH:MM:MM (12h) Example {5/21/2012 1:00:00 PM}
Details	Collection	---	Used for extending the direct properties of the object. These can be defined as part of the conversation type. They may also be used to support the specific integration needs of an integrated party.

AttachmentUri Type

The AttachmentUri class defines a reference to a file attachment. These objects may be included in the Ticket.Attachments collection. The object is also returned as a response by the PostAttachment() method.

Property Name	Type	Required	Description
Filename	String	X	The name of the file attachment referenced in the Uri property.
Uri	String	X	The URI referencing the file attachment. The URI will depend on the approach used for Attachment subscription and publication. It may be a URI for a file attachment within TEP, or it may reference a file attachment on an integrated IMS.
Details	Detail[]	---	Name value pairs for extensibility. Can be used to support partner specific integration needs.

Attachment Type

The Attachment class is used by PostAttachment() and GetAttachment() web service methods. The class diagram below depicts the structure.

The table below provides details on each of the Attachment properties.

Property Name	Type	Required	Description
Filename	String	X	The name of the file attachment. The filename extension is validated to be one of the following acceptable extensions: accdb,avi,bmp,cab,cap,chls,csv,doc,docx,dotx,eml,err,evt,gif,gz,htm,html,hwl,ico,jpeg,jpg,lic,log,mdb,mht,mp3,mpg,msg,msi,nfo,oft,pcap,pdf,png,potx,ppt,pptx,psf,pst,pub,rar,rtf,saz,stp,swf,text,tiff,tif,txt,uccapilog,uccp,uccplog,vcf,vsd,wdb,wks,wma,wmf,wmv,wps,wpt,xlr,xls,xlsx,xlt,xltx,xml,xps,zip
Payload	Stream	X	The byte stream containing the content of the file attachment.
SystemTransactionID	GUID	X	Uniquely identifies the attachment message.

Receipt Type

The Receipt class is used by PostReceipt() and GetReceipt() web service methods. The class diagram below depicts the class structure.

The table below provides details on each of the Receipt properties.

Property Name	Type	Description
DateTime	DateTime	The date and time the receipt was created in TEP.
Status	Enum	Defines the status of message processing and delivery. Values below:   TEP_ValidationError The message could not be processed by TEP due to failure of validation rules. The specifics of the validation issue are included in the StatusMessage property. TEP_ConfigurationError The message could not be processed by TEP due to configuration issue. The specifics of the configuration issue are included in the StatusMessage property. TEP_ProcessingError The message could not be processed by TEP due to processing error. These types of failures are not expected and will result in a troubleshooting effort to determine root cause. DeliveryFailed Delivery of the message failed due to error at the receiving partner. These types of failures are not expected and will result in a troubleshooting effort to determine root cause. DeliveryDelayed Delivery of the message was delayed due to unavailability of the receiving partner IMS or a data locking issue. TEP will continue to retry delivery. DeliveryNotRequired The message did not contain an new information that was relevant to the receiving partner, so no message was delivered. DeliverySuceeded The message was successfully delivered to the receiving partner.
StatusMessage	String	Message related to the DeliveryStatus. This is populated for some scenarios and not populated for others.
TicketSender	Partner	The Sender property is a Partner object which identifies the partner which originally sent the related ticket message to TEP. (This is the same partner that receives the Receipt message.) The property definitions are the same as for the ticket message so they are not repeated here.
TicketReceiver	Partner	The Receiver property is a Partner object which identifies the partner which is the intended receiver of the related ticket message. The property definitions are the same as for the ticket message so they are not repeated here.
TrackingReference	String	Contains the TrackingReference value provided by the sender in the related Ticket message. This allows the sending partner to relate the Receipt message to the Ticket message.
InteractionID	Long	Defines the interaction to which the receipt is related. This value is returned by TEP in the PostTicket() method response, and thus provides another mechanism (other than TrackingReference) to relate the Receipt message to the Ticket message.

Web Method Specific Types

There are a number of classes which group a collection of properties specifically for use as web service method argument or return types. These are defined in the subsections below.

PostTicketResponse Type

An object of this type is returned by the TEP PostTicket() method.

GetTicketResponse Type

An object of this type is returned as the response for the TEP GetTicket() method.

Property Name	Type	Required	Description
MessageID	long	X	Uniquely identifies the ticket message associated to the report. This is returned in the response for the TEP GetTicket() method as GetTicketResponse.MessageID.
TicketReference	String	X	The ticket reference associated with the ticket message.
ProcessingStatus	Enum	X	Defines the processing status for the related ticket message:   Success The ticket message was successfully processed. TEP will mark the ticket message delivery status as “Delivered”. Failure The ticket message was not successfully processed. TEP will mark the ticket message delivery status as “Failed” Unavailable There is a temporary inability to process the ticket message. TEP will send the sending partner a ticket receipt indicating delay of delivery, and will continue to return this ticket message on subsequent calls to GetTicket() method. NotFound This indicates to TEP that the ticket was purged from the receiving partner IMS. TEP will remove the receiving partner from the conversation.

TicketMessageProcessingResult Type

An object of this type is provided in the request for the ReportTicketResult() method.

Property Name	Type	Required	Description
MessageID	long	X	Uniquely identifies the ticket message associated to the report. This is returned in the response for the TEP GetTicket() method as GetTicketResponse.MessageID.
TicketReference	String	X	The ticket reference associated with the ticket message.
ProcessingStatus	Enum	X	Defines the processing status for the related ticket message:   Success The ticket message was successfully processed. TEP will mark the ticket message delivery status as “Delivered”. Failure The ticket message was not successfully processed. TEP will mark the ticket message delivery status as “Failed” Unavailable There is a temporary inability to process the ticket message. TEP will send the sending partner a ticket receipt indicating delay of delivery, and will continue to return this ticket message on subsequent calls to GetTicket() method. NotFound This indicates to TEP that the ticket was purged from the receiving partner IMS. TEP will remove the receiving partner from the conversation.

PartnerPostTicketResponse Type

An object of this type is returned by partner hosted PostTicket() method.

Property Name	Type	Required	Description
TicketReference	String	X	The unique identifier for the ticket on the partner system. This value must be returned to TEP for ticket messages of type NEW.

RestfulTicketRequest Type

This type is used for passing ticket messages to partners via REST when an asynchronous response will be used. It is simply a wrapper around the Ticket type which includes MessageID, a value which is required for the asynchronous response.

Property Name	Type	Required	Description
MessageID	String	X	TEP populates this with a unique ID which must be returned in the asynchronous response.
InputTicket	Ticket	X	The ticket with all of its contents.