Working with Ticket-Ticket Relations

Introduction

Relations between tickets can help to model your business processes in a very efficient way.

ConSol CM offers three types of relations:

• Simple ticket relations
  Non-hierarchical, simple reference. Each ticket can have any number of references.
  A simple ticket relation can be built by an engineer using the Web Client or by a programmer using the ConSol CM programming interface.
  In both cases, a reference can only be established between two existing tickets.
• Master-Slave relations
  Hierarchical. A master ticket can have several slave tickets. A slave ticket always has exactly one master ticket.
  This construct can be built by an engineer using the Web Client or by a programmer using the ConSol CM programming interface.
  A Master-Slave relation can only be established between two existing tickets, i.e. the tickets both have to exist first, then a Master-Slave relation can be built to connect them.
• Parent-Child relations
  Hierarchical. A parent ticket can have several child tickets. A child ticket always has exactly one parent ticket.
  This construct can only be built and manipulated using the ConSol CM programming interface.
  A Parent-Child relation can be built between existing tickets. Also a new child ticket can be created during the process.

Figure 144: ConSol CM relation types

In this section, we will not explain how to set-up ticket relations using the Web Client, this is explained in detail in the ConSol CM User Manual. In the current section, we will show you how to establish relations using the programming interface, namely workflow scripts.

In the ConSol CM Workflow API, the reference type is represented by the class (enum) com.consol.cmas.common.model.ticket.TicketRelationType. This offers three values:

• REFERENCE
• MASTER_SLAVE
• PARENT_CHILD

Simple Ticket Relation without a Hierarchy

This relation type can be helpful when you want to create references which help to find the tickets related to one ticket easier than using the search function.

Example use cases are:

• When a new ticket is created you want to see if there are any other open tickets from the same customer. If yes, you create a relation between the tickets. In this way, an engineer can easily jump from one open ticket of the customer to the next.
• When a new ticket is created for a certain hardware category, you want to establish references to all other tickets with the same hardware type.

This relation type can be built and manipulated using either the Web Client or the programming interface. Thus, a relation of type REFERENCE can be built within a workflow script and can then be manipulated by an engineer using the Web Client, provided he/she has the required access rights.

Example: Creating a Simple Relation between Two Tickets

workflowApi.addRelation(TicketRelationType.REFERENCE, "This is a very important relation", pSourceTicketId, pTargetTicketId)

Code example 65: Creating a ticket relation of type REFERENCE using workflowAPI

Syntax: Find all Referenced Tickets

ConSol CM versions 6.10.4.0 and up

List<Ticket> mytickets = workflowApi.getReferencedTickets()

Master-Slave Relations

This relation type can be helpful when you want to create a hierarchy between a certain number of existing tickets. Remember that this relation type can be established using either the Web Client or using the programming interface. However, here, only the programming approach will be explained.

Example use cases are:

• In a company, there are several projects, each represented by a ticket. When the decision has been made to integrate one of the projects in an overall program (also represented by a ticket), the project manager uses the workflow activity Integrate into Program. There, the correct program has to be selected (e.g. using an ACF). In the script of the workflow activity Integrate into Program, the program ticket is set as Master ticket of the current project ticket.
• In a service team, tickets for several different products are managed. For each product, there is one product ticket. When a new service ticket has been opened, the engineer uses the activity Set product where he can select the related product from a drop-down menu. In the workflow script of the activity Set product, the service ticket is automatically set as Slave of the product ticket.

A Master-Slave relation can be built and manipulated using either the Web Client or the programming interface. Thus, a relation of type MASTER_SLAVE can be built within a workflow script and can then be manipulated by an engineer using the Web Client, provided the engineer has the required access rights. Use the Parent-Child construct when you want to make sure that no engineer can manipulate the ticket hierarchy.

Example: Creating a Master-Slave Relation between Two Tickets

Code example 66: Creating a ticket relation of type MASTER_SLAVE using workflowAPI

Syntax: Finding All Slave Tickets

ConSol CM versions 6.10.3.x and below

Code example 67: Version A: Finding all target tickets (here: all slave tickets)

Code example 68: Version B: Finding all target tickets (here: all slave tickets)

ConSol CM versions 6.10.4.0 and up

List<Ticket> mytickets = workflowApi.getSlaveTickets()

Code example 69: Finding all slave tickets of the current ticket

Syntax: Finding the Master Ticket

ConSol CM versions 6.10.4.0 and up

def mticket = workflowApi.getMasterTicket()

Code example 70: Finding the master ticket of the current ticket

Parent-Child Relations

This relation type can be helpful when you want to create a hierarchy between a certain number of tickets which should not be manipulated manually.

Example use cases are:

• A project should be managed by the project management ticket which becomes the parent. All tasks within the project are represented as child tickets. This structure is automatically created by a workflow script during set-up of the project ticket.
• A system migration is planned using one parent ticket. For each single component which has to be migrated a child ticket is built. This structure is automatically created by a workflow script during set-up of the project ticket.

The relation type PARENT_CHILD can only be built and manipulated using the programming interface. Thus, a relation of this type can be built within a workflow script and can then only be manipulated by other scripts.

Example 1: Creating a New Child Ticket as Child of Current Ticket

Code example 71: Creating a child ticket

Example 2: Finding the Parent Ticket of a Ticket

def my_parent = workflowAPI.getParentTicket()

Code example 72: Finding the parent ticket of a ticket

Example 3: Finding All Child Tickets of a Ticket

Code example 73: Finding all child tickets of a ticket

Example 4: Finding All Brother Tickets (Other Child Tickets) of the Same Parent Ticket

Code example 74: Finding all brother tickets of a (child) ticket

Important Methods for the Work with Ticket Relations

Note the following rules for the work with ticket relations:

• In MASTER_SLAVE relations, the master is always the source.
• In PARENT_CHILD relations, the parent is always the source.
• In simple REFERENCE relations the source is the ticket from which the relation has been created.

WorkflowApi Methods

The following methods are methods of the class WorkflowContextService which is implicitly available as workflowApi object in workflow scripts.

Method of workflowApi (workflowContextService)	Explanation
Ticket createChildTicket(Ticket pTicket, String pTicketText, Unit pCustomer)	Creates a new child ticket. Queue and ticket fields have to be set correctly.
List<Ticket> getChildTickets()	IntSet containing the ticket objects of the child tickets of the current ticket.
List<Ticket> getBrotherTickets()	IntSet containing the ticket objects of the brother tickets of the current ticket.
Ticket getParentTicket()	Ticket object of the parent ticket or null if the current ticket does not have a parent ticket.
List<Ticket> getTargetTickets(TicketRelationType pType)	Get list of ticket objects that current ticket has relations of certain type to. For those relations, the current ticket is the source ticket.
List<Ticket> getTargetTickets(long pTicketId, TicketRelationType pType)	Get list of ticket objects that current ticket has relations of certain type to. For those relations, the ticket given with pTicketId is the source ticket.
List<Ticket> getSourceTickets(TicketRelationType pType)	Get list of ticket objects that current ticket has relations of certain type from. For those relations, the current ticket is the destination ticket.
List<Ticket> getSourceTickets(long pTicketId, TicketRelationType pType)	Get list of ticket objects that current ticket has relations of certain type from. For those relations, the given ticket is the destination ticket.
boolean hasTargetTickets(TicketRelationType pType)	Check if ticket has target tickets. Check if relations exist that have this ticket as source ticket.
boolean hasTargetTickets(long pTicketId, TicketRelationType pType)	Check if given ticket has target tickets. Check if relations exist that have this ticket as source ticket.
boolean hasSourceTickets(TicketRelationType pType)	Check if ticket has source tickets. Check if relations exist that have this ticket as target ticket.
boolean hasSourceTickets(long pTicketId, TicketRelationType pType)	Check if given ticket has source tickets. Check if relations exist that have this ticket as target ticket.
void changeSourceTickets(TicketRelationType pType, long pTargetTicketId, List<Long> pSourceTicketIds)	For the target ticket (e.g. a child ticket) the relations of a given type (e.g. PARENT_CHILD) are removed. For the same relation type a new relation is created with the provided source tickets.
void changeTargetTickets(TicketRelationType pType, long pSourceTicketId, List<Long> pTargetTicketsIds)	For the given source ticket all relations of the given type are removed. For the list of provided target tickets new relations of the given type are created.
void removeRelation(TicketRelationType pType, long pSourceTicketId, long pTargetTicketId)	Remove ticket relation between two tickets with specified type.
void addRelation(TicketRelationType pType, String pComment, long pSourceTicketId, long pTargetTicketId)	Add relation of the specified type between ticket sourceTicketId and targetTicketId.
Ticket getMasterTicket()	Available starting with CM version 6.10.4.0 Return the master ticket of the current ticket.
List<Ticket> getSlaveTickets()	Available starting with CM version 6.10.4.0 Returns a list of all slave tickets of the current ticket
List<Ticket> getReferencedTickets()	Available starting with CM version 6.10.4.0 Returns a list of all tickets which have a simple reference to the current ticket.

Table 1: Important methods of workflowApi for the work with ticket relations

TicketRelationService Methods

If you work with scripts in the Admin Tool (which are then called from a workflow script), the workflowApi is not available. You can use methods of the class TicketRelationService which is available as singleton ticketRelationService.

Method of ticketRelationService	Explanation
List<TicketRelation> getByTicket(Ticket pTicket, TicketRelationDirection pTicketRelationEnd, TicketRelationType... pRelationType)	Get a list of all ticket relations for a given ticket constrained by the relation direction (ANY|SOURCE|TARGET) and the relation type (MASTER_SLAVE|PARENT_CHILD|REFERENCE )
Set<TicketRelation> getByTickets(Set<Ticket> pTickets, TicketRelationDirection pTicketRelationEnd, TicketRelationType... pRelationType)	Get set of all tickets relations for a given set of tickets constrained by the relation direction (ANY|SOURCE|TARGET) and the relation type (MASTER_SLAVE|PARENT_CHILD|REFERENCE )

Table 2: Important methods of TicketRelationService for the work with ticket relations

Example with workflowApi and ticketRelationService Methods

Code example 75: Example Script, display IDs and names of slave tickets workflow version

Code example 76: Example Script, display IDs and names of slave tickets Admin Tool script version

scriptExecutionService.execute("DisplaySlaveTickets.groovy")

Code example 77: Calling previous AT script from workflow activity