Skip to main content
Eptura Knowledge Center

Service Request API

Warning: This is no longer a supported method of integration. Please see Rest API for a current alternative.

System Design

Summary

This is completed during the plan phase (for medium and large-sized projects using the requirements finalized and approved during the plan phase, but before substantial detail design specifications are started in the construct phase. The combination of the above requirements, plus, the finalized Computing Environment Profile (CEP) and revised technology profile comprise the system design documentation..

Proposed Solution

The proposed solution provides a universal API between the application and third-party helpdesk solutions.

 

The Service Request module, within the application, may have service tickets generated automatically, as they are created within the helpdesk ticketing system. 

Application Ticket (Service Request) Process

The following diagram outlines the process used by iOffice to manage the service requests.

Application Ticket (Service Request) Process.png

Figure: Application Ticket Process

Web Service Specification

Authentication

Security for the API is provided using basic authentication with SSL. An authorization HTTP header with the password provided by iOffice is required to make any calls or connections (including downloading the WSDL).

XML Payload

Service Request ticket information (ticket) will be communicated between helpdesk system and the application in the form of a XML document (TicketXML). Schema for this document is outlined below.

 

Element Description Optional on Submit

CustomerTicketNumber

Help desk system unique value identifying a ticket.

 

iOfficeTicketNumber

iOffice unique ID for the ticket

N/A

Asset

Complex Element - Equipment to be serviced

X

ProblemCategory

iOffice organizes the Service Requests by high-level Categories. Examples of categories include: facilities, IT, etc.

 

ProblemType

iOffice further organizes requests by Types under the category. Help desk system must establish problem types to be synchronized to iOffice.

 

Comments

Complete work log for the ticket

 

Requestor

Complesx Element - Specifies the Customer Primary Contact

 

Contact

Complex Element - Specifies the Customer Primary Contact

X

Operator

Complex Element - specifying the contact assigned to work the ticket in iOffice Connect

X

Resolution

On completion of the ticket, operators will provide a resolution for the ticket. This field will communicate that resolution.

X

Status

Current status of the ticket.

 

Possible values include:

  • Submitted

  • Dispatching

  • Assigned

  • In Progress

  • Waiting

  • On Hold

  • Rejected

  • Completed

 

Help desk system must follow specific status workflow defined by iOffice.

N/A

Cancelled

A boolean (true/false) defining if the ticket hs been cancelled.

N/A

TicketCreated

Timestamp in GMT for when the ticket is created.

X

TicketModified

Timestamp in GMT when the ticket was last modified.

X

Building (Location)

Name of Building

X

Address (Location

Building Address

X

Floor (Location)

Building Floor

X

Room (Location)

Room location

X

City (Location)

City

X

State (Location)

State

X

ZIP (Location)

Zip

X

 

Methods

Method Name

SubmitTicket

Return Value

Helpdesk to iOffice: String - CustomerTicketNumber if succesful or throw exception if not successful.

 

iOffice Connect to help desk system: String - iOfficeTicketNumber if successful, or throw exception, if not successful.

Parameters

TicketXML - XML representation of the ticket as described above with the following field requirements:

 

Required Elements:

  • Help desk to iOffice: CustomerTicketNumber

  • iOffice to help desk: iOfficeTicketNumber, ProblemCategory, ProblemType, ProblemSummary, FieldOperator, TicketCreatedTimeStamp

  • Ignored Elements: Status, Resolution, AssetLocation

Description        

This method creates a new ticket in the iOffice Connect system using the information specified in the XML document. The Status of the ticket will be set to "Submitted" and will be queued for dispatching. 

Once the ticket is successfully submitted iOffice Connect will call the help desk UpdateTicket method to provide the iOfficeTicketNumber.    

Development Considerations

Not all elements are required. See sample submit ticket payload.

Method Name

ChangeStatus

Return Value

int - 0 if successful or error codes or exception messaging

Parameters

  • CustomerTicketNumber - Unique number identifying a ticket

  • Status - One of hte valid status values listed in the XML description

  • Comment - Comment to add for the state change

  • DateTimeStamp - Status date and time stamp 

Description

This method changes the status of the ticket to one of the valid states and adds the comments to the iOffice Connect ticket. If the status parameter is an empty string, the system will simply add the comment to the work log, without changing the status of the ticket. 

Development Considerations

WARNING! This method must follow a specific status work flow defined by iOffice. 

WARNING! Status updates, including close and cancel are not relayed to Ricoh Edge.

 

Method Name

CloseTicket

Return Value

int - 0 if successful or error codes or exception messaging

Parameters

  • CustomerTicketNumber - Unique number identifying a ticket

  • Resolution - Comment describing the resolution of the ticket

  • TicketCompletedTimeStamp - Date and timestamp when ticket is closed

Description

This method closes a ticket in the iOffice Connect system and adds the specified resolution to the ticket.

Development Considerations

Warning! Status updates, including close and cancel are not relayed to Ricoh Edge.

 

Method Name

GetTicketInfo

Return Value

TicketXML - XML representation of the ticket as described above.

Parameters

CustomerTicketNumber: used to identify the ticket 

 

Note: This cannot be changed.

Description

This method provides detailed information about the ticket specified. This can be used to poll and get information about a ticket. 

Development Considerations

See sample ticket info payload.

 

Method Name

CancelTicket

Return Value

int - 0 if successful or error codes or exception messaging

Parameters

CustomerTicketNumber - Unique number identifying a ticket

Comments - Comment describing the resolution of the ticket

TicketCancelledTimeStamp - Date adn time stamp when ticket is cancelled

Description

This method closes a ticket in the iOffice Connect system and adds the comment to the ticket.

Development Considerations

WARNING! Status updates, including close and cancel are not relayed to Ricoh Edge.

 

Method Name

ArchiveTicket

Return Value

int - 0 if successful or error codes or exception messaging

Parameters

CustomTicketNumber - Unique number identifying a ticket

Description

This method archives the specified ticket in the iOffice system

 

Method Name

AddComment

Return Value

int - 0 if successful or error codes or exception messaging

Parameters

CustomerTicketNumber - Unique identifying a ticket

Comment - Comment on the ticket

Description

This method adds a comment in the iOffice system.

Development Considerations        

WARNING! Comments are not relayed to Ricoh Edge. 

 

Exception Codes and Messages

Code

Error

100

Login Information is not valid

101

TicketXML cannot be empty

102

Ticket number is required

103

Problem Category and Problem Type are required

104

Requestor Name and E-Mail are required when submitting

105

Field Operator E-Mail is required to add the field operator

106

Requestor E-Mail is required when updating tickets

107

Field Operator is required when updating

108

Cannot submit a duplicate ticket

109

Ticket in update request does not exist

110

Asset does not exist

111

Asset ID is required when submitting a ticket

113

Error parsing XML

114

Contact name and e-mail are required

115

Invalid status name

116

Customer ID is not valid

118

No maintenance center found

201

Need to assign operator to the ticket

202

Operator needs to either accept or reject the task

203

Need to re-assign the field operator

204

Operator needs to start the task

205

Ticket can be set to either hold or completed

206

Ticket is already complete

500

Unknown exception

 

Sample Submit Ticket Payload

Purple - Required

Green - Optional

 

<?xml version="1.0"?>

<Ticket>

<CustomerTicketNumber>T0000000002</CustomerTicketNumber>

<Asset>

<SerialNumber>ABCD123</SerialNumber>

</Asset>

<ProblemCategory>Copier/Printer/Fax Service Request</ProblemCategory>

<ProblemType>Cannot Print</ProblemType>

<Comments>This is a test ticket.</Comments>

<Requester>

<FirstName>Imtiyaz</FirstName>

<LastName>Momin</LastName>

<Email>donotreply@iofficecorp.com</Email>

<Phone>111-111-1111</Phone>

<Requester>

<Contact>

<FirstName>Customer</FirstName>

<LastName>Service</LastName>

<Email>fmsupport@iofficecorp.com</Email>

<Phone>111-111-1111</Email>

</Contact>

<Operators>

<Operator>

<FirstName/>

​<LastName/>   

<Email/>

<Phone/>

</Operator>

</Operators>

<Status/>

<Resolution/>

<TicketCreatedTimeStamp>07/21/2010 12:42:07<TicketCreatedTimeStamp>

</Ticket>

 

Sample Get Ticket Info Payload

<?xml version="1.0" encoding="UTF-8"?>

<Ticket>

<iOfficeTicketNumber>16</iOfficeTicketNumber>

<CustomerTicketNumber>T0000000002</CustomerTicketNumber>

<ProblemCategory>Copier/Printer/Fax Service Request</ProblemCategory>

<ProblemType>Cannot Print</ProblemType>

<Status>In Progress</Status>

<Cancelled>false</Cancelled>

<Comments></Comments>

<Resolution/>

<Asset>

<SerialNumber>ABCD123</SerialNumber>

<AssetID>123456</AssetID>

<Location>

<Building>Building1</Building>

<Address/>

<Floor>Floor 1</Floor>

<Room>Daniel's Office</Room>

<City/>

<State>TX</State>

<Zip/>

</Location>

</Asset>

<Requester>

<FirstName>Operator</FirstName>

<LastName>Operator</LastName>

<Email>donotreply@iofficecorp.com</Email>

<Phone/>

<Location>

<Building>Building1</Building>

<Address/>

<Floor>1</Floor>

<Room>1</Room>

<City/>

<State/>

<Zip/>

</Location>

</Requester>

<Contact>

<FirstName>Customer</FirstName>

<LastName>Service</LastName>

​<Email>fmsupport@iofficecorp.com</Email>

<Phone>713-526-1029</Phone>

<Location>

<Building/>

<Address/>

<Floor/>

<Room/>

<City/>

<State/>

<Zip/>

</Location>

</Contact>

<Operators>

<Operator>

<FirstName>Customer</FirstName>

<LastName>Service</LastName>

<Email/>

<Phone/>

<status>In Progress</status>

<Location>

<Building>Building1</Building>

<Address/>

<Floor>1</Floor>

<Room>1</Room>

<City/>

<State>TX</State>

<Zip/>

</Location>

</Operator>

</Operators>

<TicketCreatedTimeStamp>2010-07-21 07:42:07.0<TicketCreatedTimeStamp>

<TicketModifiedTimeStamp>2010-07-21 17:22:18.0</TicketModifiedTimeStamp

</Ticket>

 

 

Related Topics

Integration Home