Configuration of the Graph Display of Relations
Introduction to Configuration of the Graph Display of Relations
The graph display of relations is based on vis.js, namely on the Network library. Refer to the vis.js Network detailed documentation to get to know all available configuration parameters. In the following sections, the most important parameters will be explained using some examples.
As explained in section Attributes for Page Customization of Standard Relations Graph View, either a JSON statement or a script can be used to define the layout of the graph.
Configuring the Graph Display of Relations Using JSON Statements
Introduction
There are two ways of providing a JSON statement for configuring a relation graph:
- as value of a page customization attribute:
provide the statement as value of the page customization attribute graphConfiguration, see section Attributes for Page Customization of Standard Relations Graph View -
in a graphScript
provide the statement as JSON string which is then used by the class.method RelationCriteria.parseJson(JSONstring)
The first case is the common way of configuring standard relation graphs. The second can be used in special cases, however, usually other methods would be better in this case.
Please note that only the scope can be defined in a JSON statement! If you want to modify the graph layout (e.g., color of edges, font style), you have to work with scripts, see section Configuring the Graph Display of Relations Using Scripts.
Syntax for the Configuration of the Graph Display
In the JSON statement, the scope of the graph can be defined.
For tickets, you can define the following parameters:
- For ticket-ticket relations:
- reference
ticket references the current ticket - parent
ticket is parent ticket - child
ticket is child ticket - master
ticket is - slave
ticket is
"ticketTickets" : {
"maximumStepsFromRoot" : 2,
"relations" : [ "reference", "parent", "child", "master", "slave" ],
"includedQueues" : [ "queue1", "queue2" ],
"excludedQueues" :[ "queue1", "queue2" ]
}
Use either includedQueues or excludedQueues!
The following relation types are possible:
- For ticket-customer relations:
- main
customer is the main customer of the ticket - default
customer is an additional customer without role - the name of a customer role
"ticketCustomers" : {
"maximumStepsFromRoot" : 2,
"relations" : [ "main", "default", "contactTicketRoleName" ],
"includedCustomerGroups" : [ "customerGroup1", "customerGroup2" ],
"excludedCustomerGroups" : [ "customerGroup1", "customerGroup2" ]
}
Use either includedCustomerGroups or excludedCustomerGroups!
The following relation types are possible:
- For ticket-resource relations:
"ticketResources" : {
"maximumStepsFromRoot" : 2,
"relations" : [ "related", "resourceRelationDefinition" ],
"includedResourceTypes" : [ "resourceType1", "resourceType2" ],
"excludedResourceTypes" : [ "resourceType1", "resourceType2" ]
}
For customers = units (i.e., contacts and companies), you can define the following parameters:
- For customer-ticket relations:
- main
the customer is the main customer of the ticket - default
customer is an additional customer without role) - the name of a customer role
"customerTickets" : {
"maximumStepsFromRoot" : 2,
"relations" : [ "main", "default", "contactTicketRoleName" ],
"includedQueues" : [ "queue1", "queue2" ],
"excludedQueues" : [ "queue1", "queue2" ]
}
The following relation types are possible:
- For unit-unit relations:
"unitUnits" : {
"maximumStepsFromRoot" : 2,
"relations" : [ "unitRelationDefinition1", "unitRelationDefinition2" ],
"includedCustomerGroups" : [ "customerGroup1", "customerGroup2" ],
"excludedCustomerGroups" : [ "customerGroup1", "customerGroup2" ]
}
Use either includedCustomerGroups or excludedCustomerGroups!
For directional unit-unit relations, it is possible to specify the direction, i.e., whether the objects linked in the graph should be source or target of the relation. The syntax is as follows.
Case 1. The linked customers are the source of the relation and the root node is the target:
"relations" : [ "unitRelationDefinition:source"]
Case 2. The linked customers are the target of the relation and the root node is the source:
"relations" : ["unitRelationDefinition:target"]
- For contact-company relations:
"contactCompany" : {
"maximumStepsFromRoot" : 2
}
- For company-contact relations:
"companyContacts" : {
"maximumStepsFromRoot" : 2
}
- For unit-resource relations:
"unitResources" : {
"maximumStepsFromRoot" : 2,
"relations" : [ "related", "resourceRelationDefinition" ],
"includedResourceTypes" : [ "resourceType1", "resourceType2" ],
"excludedResourceTypes" : [ "resourceType1", "resourceType2" ]
}
Use either includedResourceTypes or excludedResourceTypes!
For resources, you can define the following parameters:
- For resource-resource relations:
"resourceResources" : {
"maximumStepsFromRoot" : 2,
"relations" : [ "related", "resourceRelationDefinition" ],
"includedResourceTypes" : [ "resourceType1","resourceType2" ],
"excludedResourceTypes" : [ "resourceType1", "resourceType2" ]
}
Use either includedResourceTypes or excludedResourceTypes!
For directional resource-resource relations, it is possible to specify the direction, i.e., whether the objects linked in the graph should be source or target of the relation. The syntax is as follows:
Case 1. The linked resources are the source of the relation and the root node is the target:
"relations" : ["resourceRelationDefinition:source"]
Case 2. The linked resources are the target of the relation and the root node is the source:
"relations" : ["resourceRelationDefinition:target"]
- For resource-unit relations:
resourceUnits" : {
"maximumStepsFromRoot" : 2,
"relations" : [ "related", "resourceRelationDefinition" ],
"includedCustomerGroups" : [ "customerGroup1", "customerGroup2" ],
"excludedCustomerGroups" : [ "customerGroup1", "customerGroup2" ]
}
Use either includedCustomerGroups or excludedCustomerGroups!
Configuring the Graph Display of Relations Using Scripts
Scripts might be used in two locations to define graph displays of relations:
- in the standard display mode as value of the graphScriptName attribute
- in the customized expert display mode as value of the graphScriptName attribute
Please note that in a script, every relation can be included into the display! So the person who implements the script is responsible for the graph display! Please make sure the correct relations are displayed, especially for scripts in the standard sections. For example, it might not make much sense to display ticket-resource relations in a customer section of a ticket, even if it is technically possible. If complex networks of relations of different types should be displayed, we recommend to place those in a customized / expert relations graph and set an informative header for this section!
A script which defines the graph display of relations
- has to be of type Relation graph
- has to return an object of class RelationGraph
- can define
- the scope of the graph
- the layout of the graph
- can make use of the following objects which are implicitly present in the script, depending on the location of the script
ticketId (in ticket pages)
- unitId (in unit pages)
- resourceId (in resource pages)
In order to define the scope of a relation graph in a script, use the class RelationCriteria and the static classes which represent the different flavors of RelationCriteria, e.g., RelationCriteria.ResourceTickets (see ConSol CM API documentation!)
Example script:
import com.consol.cmas.common.model.relation.*
//create criteria using java api
def relationCriteria = new RelationCriteria()
.withResourceTickets(new RelationCriteria.ResourceTickets()
.withMaximumStepsFromRoot(2))
.withResourceUnits(new RelationCriteria.ResourceUnits()
.withMaximumStepsFromRoot(2))
.withResourceResources(new RelationCriteria.ResourceResources()
.withMaximumStepsFromRoot(2));
def resource = resourceService.getById(resourceId)
def relationGraph = relationService.load(resource, relationCriteria);
return relationGraph;
Display:
Figure 309: ConSol CM Web Client - Resource page: Graph display
In order to define the layout of the graph, use RelationNode and RelationEdge objects.
Example script (script as above, extended with layout configuration):
import com.consol.cmas.common.model.relation.*
//create criteria using java api
def relationCriteria = new RelationCriteria()
.withResourceTickets(new RelationCriteria.ResourceTickets()
.withMaximumStepsFromRoot(2))
.withResourceUnits(new RelationCriteria.ResourceUnits()
.withMaximumStepsFromRoot(2))
.withResourceResources(new RelationCriteria.ResourceResources()
.withMaximumStepsFromRoot(2));
def resource = resourceService.getById(resourceId)
def relationGraph = relationService.load(resource, relationCriteria);
//define layout:
for (RelationNode node : relationGraph.getNodes()) {
node.withProperty("font", [size:12,color:"blue"]) //change default property
.withProperty("image", null) //remove default property
.withProperty("shape", "diamond") //remove default property
.withProperty("margin", 5); //add property
}
for (RelationEdge edge : relationGraph.getEdges()) {
edge.withProperty("arrows", null) //remove default property
.withProperty("font", [size:16, color:"red"]); //change default property
}
relationGraph.withProperty("layout", [hierarchical:[direction:"UD"]])
return relationGraph;
Display:
Figure 310: ConSol CM Web Client - Resource page: Graph display with modified layout options
The font size has been set to 12 pt, the font color has been changed to blue, the shape has been changed to diamond, and the layout has been changed to a hierarchical display.
This example gives an impression of how the layout of relation graphs can be modified. Use this principle (with the help of the vis.js Network documentation to adapt the relation graphs in your CM system to your company's requirements.