GGUS:GGUS Interfaces FAQ

GGUS wiki / GGUS FAQ / GGUS Documentation / GGUS Helpdesk

---

GGUS interfaces

Updated

2011-10-12

Purpose

This document provides a technical description of the requirements for interfacing any system with GGUS. It describes the various fields needed as well as the necessary workflows. It does not give a description of the things to be done on management level before implementing an interface to GGUS. As the things to be done on management level are currently not documented please submit a [ticket] or add your request for interfacing GGUS system to the GGUS shopping list at https://rt.egi.eu/rt/Dashboards/2636/GGUS-Requirements. The GGUS shopping list is a RT queue for collecting and discussing change requests for GGUS system.

Interfaces

In the past many interfaces of GGUS to other systems have been implemented. Each of them was unique in its kind. They can be classified into three different groups:

• Interfaces based on email for both communication directions, from GGUS to the remote system and from the remote system to GGUS.
• Interfaces based on email for communication from GGUS to the remote system and on web services for communications from the remote system to GGUS
• Interfaces based on web services for both communication directions, from GGUS to the remote system and from the remote system to GGUS.

The goal of GGUS is to reduce the number of different interfaces for reducing complexity and maintenance effort in the system. There are two types of interfaces that will be provided and maintained by GGUS in future: SOAP web services and Grid Messaging. They are described in the following chapters.

Grid Messaging

The Grid Messaging interface is available but never made it into production yet. Documentation on GridMessaging is available at GGUS:GridMessaging_Interface_FAQ.

SOAP web services

Web service interfaces are very reliable. The interfaced systems are synchronized permanently. Failing web services throw an error message at once. So the user gets notified about it. An example of a wsdl file for GGUS web services is available on the [training system]. GGUS provides a training and testing system which is a copy of the production system. For developing and testing access to this system can be given. Please contact GGUS for getting more information. There are already implementations of local ticketing systems providing SOAP web service interfaces too. Please see GGUS:Ticketing_System_Recommendation_FAQ for further information.

Fields in GGUS web services

When implementing a help desk system that should be interfaced with GGUS system a set of fields is necessary for exchanging structured data. They can be divided into mandatory fields and optional fields.

Mandatory fields

This is a basic set of fields to be implemented in a local ticketing system for interfacing with GGUS.

Label	Data type	Max. length	Comments
GGUS ID	Char	15	ID of the ticket in GGUS system. This field is used as primary key in GGUS.
Responsible Unit	Char	50	Name of the support unit in charge of the ticket. A list of support units implemented in GGUS system is available here.
Status	Char	50	The status of a ticket. Status values are listed here.
Subject	Char	255	Short description of problem e.g. for specifying some keywords.
Description	Char	4000	Detailed description of problem.
Type Of Problem	Char	50	Grouping for the problem. See the list of problem types for further information.
Priority	Char	20	Specifies the urgency of a ticket. GGUS system uses four priority classes. They are: less urgent, urgent, very urgent, top priority.
Affected VO	Char	30	Name of the VO affected by the problem. The list of VOs in this field is equal to the VOs providing a specific VO support within GGUS. They are listed here.
Notified Site	Char	50	Name of site which should be notified about the problem. Possible values for this field are the sites registered in GOC DB and the sites supporting USATLAS and USCMS from OIM. As the list of sites is changing permanently the site names have to be retrieved on demand.
VO specific	Char		Flag indicating whether a problem is VO specific or not. Possible values are “No” and “Yes”. The default is “No”.
Solution	Char	4000	Solution of the problem.
Last Modifier	Char	60	Name of supporter who modified the ticket
Origin SG	Char	20	Abbreviation of the system the tickets was originally submitted in. For GGUS system the abbreviation is “GGUS”.

Optional fields

Optional fields can provide additional information in dedicated fields. GGUS system has a lot of fields besides the mandatory ones.

Label	Data type	Max. length	Comments
Internal Diary	Char	4000	Field for internal comments that are not shown to the user.
Public Diary	Char	4000	Field for public comments. In GGUS system every update of the public diary triggers an email notification to the ticket submitter if the ticket was submitted in GGUS originally.
Last Login	Char	30	The account of the local ticketing system used for logging into GGUS.
Date/Time Of Problem	Char	50	Often the ticket is not submitted right after the problem occurred. In such cases it could be helpful to specify date and time the problem occurred. Content in this field should be ISO formatted (YYYY-MM-DD HH:MM:SS).
Related Issue	Char	125	Used for adding URLs related to the GGUS ticket. They can be URLs to web pages, wikis, other systems….
Ticket Category	Char	20	Field for classifying a ticket. Possible values are Incident, Change Request, Documentation, Spam Tickets in category “Spam” are deleted automatically.
Ticket Type	Char	20	GGUS system has several types of tickets as USER, TEAM, ALARM. The most common one is “USER” which is the default type. Tickets of type “TEAM” and “ALARM” require specific rights in the GGUS user database.
MoU Area	Char	100	This field is related to the “TEAM” and “ALARM” tickets. The possible values of this field are taken from the MoU document. This field requires specific rights in the GGUS user database too.

Workflows

Besides the fields and the interface itself there are some requirements on workflows for interfacing with GGUS system. The synchronization between the local ticketing system and the GGUS system and the communication with the user are fundamental workflows and have to be implemented carefully.

Synchronization with GGUS system

Synchronization should be done in “real time” if possible. As the synchronization process of the two systems is relying on the kind of interface used there may be technical limitations that avoid synchronization in real time. However the time slot of the two systems not being synchronized should be as small as possible. During the synchronization process only fields that have really changed should be pushed to GGUS. Pushing the complete ticket data to GGUS should be avoided. If GGUS and the local ticketing system are synchronized well it does not matter in which system a supporter updates a ticket.

Communication with users

One basic assumption in GGUS system is that the user should communicate with that system he submitted his ticket in. So GGUS system only sends mails to users if the ticket was submitted in GGUS originally. For all other tickets GGUS system only routes the updates to the origin ticketing system. This leads to two different use cases for the user communication:

• Ticket submitted in GGUS and routed to a local ticketing system,
• Ticket submitted in a local ticketing system and routed to GGUS system.

Tickets submitted in GGUS and routed to a local system

Getting in touch with the user The easiest way for getting in touch with the user is to push the message for the user to the public diary in GGUS. The user will receive an email notification about the update. He can reply to the email notification using the “Reply” function of his mail client. The reply will be parsed by the GGUS mail parsing tool and added to the “Internal Diary” of the related GGUS ticket. GGUS system then pushes the update to the local ticketing system. Ticket solution In case of ticket solution or ticket solution update the solution text has to be pushed into the GGUS solution field. GGUS system the sends a solution mail or a solution update mail to the user. Classifying a ticket as “solved” requires the status to be set to “solved”. This is also true for “unsolved” tickets.

Tickets submitted in a local system and routed to GGUS

Getting in touch with the user GGUS system pushes the message from the public diary to the local ticketing system. The local ticketing system then has to make sure that the user gets notified about this message. The user reply has to be pushed back to GGUS system. Ticket solution The ticket solution is pushed from GGUS system to the local system. The local ticketing system then has to make sure that the user gets notified about this message. This process should also work for updates on the ticket solution. Updates on the GGUS Internal Diary Updates on the GGUS “Internal Diary” are not visible to the user. The local ticketing system has to make sure that such updates are only visible for supporters either by using an “internal” field or by an appropriate workflow.

What if I have questions which are not dealt with by this FAQ?

Open a GGUS ticket

indicating that it should be directed at the GGUS team.

Search

• Please use this link to search inside the GGUS FAQ