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