GGUS:SOAP Interface FAQ

From EGIWiki
Jump to: navigation, search
GGUS-logo.jpg


GGUS wiki / GGUS FAQ / GGUS Documentation / GGUS Helpdesk


FAQ for the GGUS SOAP interface


Purpose

This document describes the generic SOAP interfaces provided by GGUS for synchronizing remote ticketing systems with GGUS and reading the GGUS ticket history.
The interface is providing dedicated SOAP web services for ticket submission, updating and reading.
For information on VO TEAM ticket feature please see the documentation on Team ticket web services.
Before starting using the SOAP interface please get in touch with the GGUS developers submitting a GGUS ticket.

SOAP web services

GGUS provides different SOAP web services. One web service for submitting and updating tickets and one web service for reading the history of GGUS tickets.

Web service for submitting and updating tickets

The SOAP web service for submitting and updating tickets in GGUS is described in a wsdl file. This wsdl file is mapped to the GGUS test instance. For getting the wsdl file of GGUS production instance please contact the GGUS administrators.
5 SOAP operations are provided with the web service:

  • OpCreate
  • TicketCreate
  • OpCreateChild
  • OpModify
  • OpGet
  • OpGetList


OpCreate

This operation is being used for submitting tickets. It will return a ticket ID in case of success. In case of any problem an error message will occur.
Possible input values and their meaning are listed in the table below.
NOTE: not all fields marked as mandatory in the table are mandatory for the SOAP operation. However for not breaking the ticket work flow it is recommended to provide field values as described in the table.

Input values

XML element Type Max Length Mode Comments
GHD_E-Mail string 255 Mandatory Mail address of ticket submitter.
GHD_Loginname string 128 Mandatory DN string of user's certificate.
GHD_Last_Login string 30 Mandatory Account used by the SOAP client.
GHD_Last_Modifier string 50 Mandatory Name of the person who did the last ticket update.
GHD_Short_Description string 255 Mandatory Ticket subject.
GHD_Origin_ID string 15 Mandatory Ticket ID in remote system.
GHD_Origin_SG string 20 Mandatory Abbreviation for remote system. Please ask the GGUS developers which value should be used.
GHD_Affected_Site string 50 Optional Site affected by the problem. Possible values are site names from GOCDB and OIMDB.
GHD_Affected_VO string 30 Optional VO affected by the problem. See the list of supported VOs for further information.
GHD_CarbonCopy string 255 Optional Add mail addresses for notifying people on this ticket. Please use semi-colon as delimiter.
GHD_Date_Time_Of_Problem string 50 Optional Date and time the problem occurred. Please use format YYYY-MM-DD hh:mm:ss. Defaults to the submit time.
GHD_Description string 4000 Optional Detailed description of the problem. Length is up to 4000 chars.
GHD_Internal_Diary string 4000 Optional Text field for adding internal comments. Length is up to 4000 chars.
GHD_Responsible_Unit string 50 Optional Please set to "TPM".
GHD_Status string 50 Optional Please set to "new".
GHD_Name string 80 Optional Name of ticket submitter.
GHD_Phone string 50 Optional Phone number of ticket submitter.
GHD_Priority selection Optional Ticket priority level. Possible values are "less urgent", "urgent", "very urgent" and "top priority". Defaults to "less urgent".
GHD_Type_Of_Problem string 50 Optional Possible values are listed in the FAQ. Defaults to "Other".
GHD_Related_Issue string 255 Optional Space for adding URLs to other tickets etc.

Output values In case of success this operation will return a ticket ID in the format "GHD_Request_ID = 99999".

TicketCreate

This operation is similar to OpCreate but with field GHD_E-Mail replaced by GHD_Submitter_Mail. This operation is useful for clients that do not allow hyphens in the field labels.

OpCreateChild

This operation is being used for submitting child tickets to an already existing ticket. This already existing ticket will be marked as parent. It will return a ticket ID in case of success. In case of any problem an error message will occur.
Possible input values and their meaning are listed in the table below.
NOTE: not all fields marked as mandatory in the table are mandatory for the SOAP operation. However for not breaking the ticket work flow it is recommended to provide field values as described in the table.
More information on child tickets and parent-child relations is available in the GGUS support staff guide.

Input values

XML element Type Max Length Mode Comments
GHD_E-Mail string 255 Mandatory Mail address of ticket submitter.
GHD_Loginname string 128 Mandatory DN string of user's certificate.
GHD_Last_Login string 30 Mandatory Account used by the SOAP client.
GHD_Last_Modifier string 50 Mandatory Name of the person who did the last ticket update.
GHD_Short_Description string 255 Mandatory Ticket subject.
GHD_Parent_ID string 15 Mandatory Ticket ID of related parent ticket.
GHD_Parent_Child_Relation selection Mandatory Must be set to "Child".
GHD_Affected_Site string 50 Optional Site affected by the problem. Possible values are site names from GOCDB and OIMDB.
GHD_Affected_VO string 30 Optional VO affected by the problem. Please set to "biomed".
GHD_Date_Time_Of_Problem string 50 Optional Date and time the problem occurred. Please use format YYYY-MM-DD hh:mm:ss. Defaults to the submit time.
GHD_Description string 4000 Optional Detailed description of the problem. Length is up to 4000 chars.
GHD_Internal_Diary string 4000 Optional Text field for adding internal comments. Length is up to 4000 chars.
GHD_Responsible_Unit string 50 Optional Please set to "TPM".
GHD_Status string 50 Optional Please set to "new".
GHD_Name string 80 Optional Name of ticket submitter.
GHD_Phone string 50 Optional Phone number of ticket submitter.
GHD_Priority selection Optional Ticket priority level. Possible values are "less urgent", "urgent", "very urgent" and "top priority". Defaults to "less urgent".
GHD_Type_Of_Problem string 50 Optional Possible values are listed in the FAQ. Defaults to "Other Services".

Output values In case of success this operation will return a ticket ID in the format "GHD_Request_ID = 99999".

TicketModify

This operation is being used for modifying tickets. It will return a ticket ID in case of success. In case of any problem an error message will occur.
Available fields and their meaning are listed in the table below.

Input values

XML element Type Max Length Mode Comments
GHD_Last_Login string 30 Mandatory Account used by the SOAP client.
GHD_Last_Modifier string 50 Mandatory Name of the person who did the last ticket update.
GHD_Request_ID string 15 Mandatory GGUS ticket ID.
GHD_Affected_Site string 50 Optional Site affected by the problem. Possible values are site names from GOCDB and OIMDB.
GHD_Affected_VO string 30 Optional VO affected by the problem. See the list of supported VOs for further information.
GHD_Responsible_Unit string 50 Optional Support unit in charge of the ticket. GGUS support units are listed at here.
GHD_Assign_To string 255 Optional Add mail address for assigning a ticket to a dedicated person.
GHD_Carbon_Copy string 255 Optional Add mail addresses for notifying people on this ticket. Please use semi-colon as delimiter.
GHD_Experiment_Specific_Problem selection Optional Flag indicating whether a problem is specific to a given VO or not. Possible values are "Yes" and "No". Defaults to "No".
GHD_Priority selection Optional Ticket priority level. Possible values are "less urgent", "urgent", "very urgent" and "top priority". Defaults to "less urgent".
GHD_Short_Description string 255 Optional Ticket subject.
GHD_Type_Of_Problem string 50 Optional Possible values are listed in the FAQ.
GHD_Detailed_Solution string 4000 Optional Solution text required if changing status to "solved" or "unsolved".
GHD_Public_Diary string 4000 Optional Public comment that will trigger a notification to the ticket submitter.
GHD_Internal_Diary string 4000 Optional Internal comment for support staffs only.
GHD_Status string 50 Optional Ticket status. See the FAQ on status values for details.
GHD_Ticket_Category selection Optional Category of GGUS ticket. Defaults to "Incident". Possible values are "Incident", "Change Request", "Documentation", "Test" and "Spam".
GHD_Target_ID string 50 Optional ID of ticket in remote system.
GHD_Incident_ID string 30 Optional ID of incident in remote system.
GHD_Related_Issue string 255 Optional Space for adding URLs to other tickets etc.

Output values In case of success this operation will return the ticket ID used for calling the TicketModify operation.


TicketGet

This operation is being used for getting the data of one dedicated ticket searching by ticket ID. The result gives the fields like listed below.

Input values

  • GHD_Request_ID

Output values

  • GHD_Affected_Site
  • GHD_Affected_VO
  • GHD_Carbon_Copy
  • GHD_Assign_To
  • GHD_Date_Of_Change
  • GHD_Date_Of_Creation
  • GHD_Detailed_Solution
  • GHD_Description
  • GHD_Public_Diary
  • GHD_Internal_Diary
  • GHD_Status
  • GHD_Experiment_Specific_Problem
  • GHD_Last_Login
  • GHD_Last_Modifier
  • GHD_Priority
  • GHD_Short_Description
  • GHD_Type_Of_Problem
  • GHD_Request_ID
  • GHD_Responsible_Unit
  • GHD_Product_Name
  • GHD_Product_Version
  • GHD_E-Mail
  • GHD_Loginname
  • GHD_Name
  • GHD_Phone
  • GHD_Ticket_Type
  • GHD_ETA

TicketGetList

This operation is being used for getting a bundle of records searching by any criteria. It requires using the field labels in GGUS DB instead of XML labels like the other SOAP operations. Please contact the GGUS team for help before using this operation.

Input values A qualification may look like this: $client->TicketGetList(array(Qualification => "'GHD_Meta Status'=\"Open\" AND 'GHD_Ticket Type'=\"USER\"" ));

Output values The result gives the same fields as operation TicketGet. The maximum number of records returned is limited to 500.

Web service for reading the ticket history

The SOAP web service for reading the ticket history in GGUS is described in a wsdl file. This wsdl file is mapped to the GGUS test instance. For getting the wsdl file of GGUS production instance please contact the GGUS administrators.
3 SOAP operations are provided with the web service:

  • OpGetTicketHist
  • OpGetOpsTicketHist
  • OpGetTeamTicketHist

The maximum amount of returned entries is limited to 1000 for all these operations.

OpGetTicketHist

Input values

  • GHD_Request_ID

Output values

  • GHD_Affected_Site
  • GHD_Affected_VO
  • GHD_VO_Specific
  • GHD_Assigned_To
  • GHD_Modified_Date
  • GHD_Solution
  • GHD_Description
  • GHD_Change_Diary
  • GHD_Public_Diary
  • GHD_Internal_Diary
  • GHD_Involve
  • GHD_Status
  • GHD_Last_Modifier
  • GHD_Priority
  • GHD_Type_Of_Problem
  • GHD_Responsible_Unit
  • GHD_Related_Issue
  • GHD_Remind_On

OpGetOpsTicketHist

This operation only returns data for tickets of type OPS.

Input values

  • GHD_Request_ID

Output values

  • GHD_Affected_Site
  • GHD_Affected_VO
  • GHD_VO_Specific
  • GHD_Assigned_To
  • GHD_Modified_Date
  • GHD_Solution
  • GHD_Description
  • GHD_Public_Diary
  • GHD_Change_Diary
  • GHD_Internal_Diary
  • GHD_Involve
  • GHD_Status
  • GHD_Last_Modifier
  • GHD_Priority
  • GHD_Problem_Type
  • GHD_Responsible_Unit
  • GHD_Related_Issue
  • GHD_Remind_On
  • GHD_Ticket_Type
  • GHD_Soap_Client_Data

OpGetTeamTicketHist

This operation only returns data for tickets of type TEAM.

Input values

  • GHD_Request_ID

Output values

  • GHD_Affected_Site
  • GHD_Affected_VO
  • GHD_VO_Specific
  • GHD_Assigned_To
  • GHD_Modified_Date
  • GHD_Solution
  • GHD_Description
  • GHD_Public_Diary
  • GHD_Change_Diary
  • GHD_Internal_Diary
  • GHD_Involve
  • GHD_Status
  • GHD_Last_Modifier
  • GHD_Priority
  • GHD_Problem_Type
  • GHD_Responsible_Unit
  • GHD_Related_Issue
  • GHD_Remind_On
  • GHD_Soap_Client_Data

Web service for adding and downloading attachments

The SOAP web service for adding and downloading attachments in GGUS is described in a wsdl file. This wsdl file is mapped to the GGUS test instance. For getting the wsdl file of GGUS production instance please contact the GGUS administrators.
2 SOAP operations are provided with the web service:

  • AddAttachment
  • GetAttachments

AddAttachment

This operation is being used for adding attachments to an existing GGUS ticket. It will return an attachment ID in case of success. In case of any problem an error message will occur.
Possible input values and their meaning are listed in the table below.
Input values

XML element Type Max Length Mode Comments
GAT_Attachment_Name string 255 Mandatory File name of attachmetn.
GAT_Attachment_Data base64Binary 2MB Mandatory Attachment content in base64Binary format. The maximum attachment size in GGUS is 2MB.
GAT_Attachment_Orig_Size int Mandatory Size of the attachment.
GAT_Last_Login string 30 Mandatory Account used by the SOAP client.
GAT_Last_Modifier string 50 Mandatory Name of the person who did the last ticket update.
GAT_Request_ID string 15 Mandatory ID of the GGUS ticket.


Output values
In case of success this operation will return an attachment ID in format "GAT_Attachment_ID = ATT99999".

GetAttachments

This operation is being used for downloading attachments from an existing GGUS ticket. It will return the attachment and some meta data in case of success. In case of any problem an error message will occur.
Input values

XML element Type Max Length Mode Comments
GAT_Request_ID string 15 Mandatory ID of the GGUS ticket.


Output values

XML element Type Max Length Comments
GAT_Attachment_Name string 255 File name of attachmetn.
GAT_Attachment_Data base64Binary 2MB Attachment content in base64Binary format.
GAT_Attachment_Orig_Size int Size of the attachment.
GAT_Attachment_ID string 15 ID of the attachment in GGUS.
GAT_Last_Modifier string 50 Name of the person who did the last ticket update.


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