The wiki is deprecated and due to be decommissioned by the end of September 2022.
The content is being migrated to other supports, new updates will be ignored and lost.
If needed you can get in touch with EGI SDIS team using operations @ egi.eu.
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:
|
| 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
Tickets in category “Spam” are deleted automatically. |
| Ticket Type | Char | 20 | GGUS system has several types of tickets as
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