Scripts of the type Widget
Widget scripts are used to implement widgets which are displayed on dashboards. They implement logic to retrieve and prepare the data which is shown in the widget. A widget scripts needs to return the data in the format required by the type of widget.
Widget scripts are used for the following widget types:
The following general principles apply to widget scripts:
- If you set attribute values both in the widget script and in the page customization, the values set in the script overwrite the values entered in the page customization.
- The results of the methods which retrieve data varies depending on the context. By default, the script is executed with user permissions. If you need to use data which is not available in the user context, you need to execute the script with administrator permissions (checkbox run with admin privileges in the page customization).
Example: You want to show the number of escalated cases of all the assignees. Therefore, you need the script to retrieve all cases not only the cases which the current user is allowed to see. - The widget script is executed every time the page with the respective widget is opened. Complex scripts can decrease the system performance. If complex scripts are used, it is recommended to use tabs on the dashboard and place such widgets in a tab which is not opened directly.
The following sections describe the return values of the different widget types.
Chart widgets
Chart widgets are based on the Highcharts library. The script has to return a HashMap containing the attributes which should be set. See Chart widgets for a detailed description of the available attributes.
The following example shows the script which is used for the default chart widget showing the number of cases in the current view.
import com.consol.cmas.common.model.ticket.*;
import com.consol.cmas.common.model.ticket.view.*;
import java.util.*;
import java.util.Map.Entry;
if (viewId == -1) {
return [visible: 'false']
}
def engineerLocale = engineerService.getCurrentLocale()
def view = viewService.getById(viewId)
def viewName = localizationService.getLocalizedProperty(View.class, "name", viewId, engineerLocale)
ViewCriteria allCriteria = new ViewCriteria(view,
ViewAssignmentParameter.allTickets(),
ViewGroupParameter.allTickets(),
new ViewOrderParameter())
def allTickets = ticketService.getCountForView(allCriteria)
ViewCriteria ownCriteria = new ViewCriteria(view,
ViewAssignmentParameter.allTickets(engineerService.getCurrent()),
ViewGroupParameter.onlyOwnTickets(),
new ViewOrderParameter())
def ownTickets = ticketService.getCountForView(ownCriteria)
ViewCriteria unassignedCriteria = new ViewCriteria(view,
ViewAssignmentParameter.allUnassignedTickets(),
ViewGroupParameter.onlyUnassignedTickets(),
new ViewOrderParameter())
def unassignedTickets = ticketService.getCountForView(unassignedCriteria)
def data = []
data.add("{name: _('all'), data:[${allTickets}]}" as String)
data.add("{name: _('own'), data:[${ownTickets}]}"as String)
data.add("{name: _('unassigned'), data:[${unassignedTickets}]}"as String)
return [series: "[${data.join(',')}]" as String,
visible: 'true',
chart: "{type: 'column'}", title: "{text: '${viewName}'}" as String,
tooltip:"{headerFormat:''}" ,
localization:"de: {all:'Alle',own:'Eigene',unassigned:'Unzugewiesene'},"+ "en: {all:'All', own:'Own', unassigned: 'Unassigned'}"];
Code example 12: Script for the default chart widget ticketsInViewDataWidget.groovy
The following example shows the script of a funnel widget. Some static data is used for demo purposes.
return [title: "{text: _('title')}",
chart: "{type: 'funnel', \
marginLeft: '50', \
marginRight: '150'}",
plotOptions: "{series:{ height: '90%', \
width: '85%', \
neckWidth: '20%', \
neckHeight: '20%', \
dataLabels: {enabled:'true', \
format: '<b>{point.name}</b> ({point.y:,.0f})', \
softConnector: 'true'}}}",
visible: "true",
series: "[{name: _('users'), \
data: [[_('visits') , 15654], \
[_('downloads'), 4064], \
[_('requests') , 1987]]}]",
localization: "de: {title: 'Vertriebstrichter', \
users: 'Individuelle Benutzer', \
visits: 'Seitenaufrufe', \
downloads: 'Downloads', \
requests: 'Anfrage Preisliste'}, \
en: {title: 'Salesfunnel', \
users: 'Unique users', \
visits: 'Page visits', \
downloads: 'Downloads', \
requests: 'Requests for price list'}"
]
Code example 13: Script for a sales funnel chart with demo data
KPI widgets
KPI widgets are based on the jquery-kpiwidget library. The script has to return a HashMap containing the attributes which define the KPI representation. See KPI widgets for a detailed description of the available attributes.
import com.consol.cmas.common.model.ticket.*
import java.util.*
import com.consol.cmas.common.model.DateRange
TicketCriteria crt = new TicketCriteria()
def to_date = new Date()
def from_date = to_date - 7
def range = new DateRange(from_date,to_date)
crt.setCreationDateRange(range)
// crt.setStatus(TicketCriteria.Status.OPEN)
ticketcount = ticketService.getByCriteria(crt).size()
switch (ticketcount) {
case 0..25:
trendline = 'down'
break
case 26..50:
trendline = 'flat'
break
default:
trendline = 'up'
}
return[value: ticketcount as String, trend: trendline, visible: 'true']
Code example 14: Script for a KPI widget which counts the cases which have been opened during the last week
Table widgets
Table widgets are based on the Datatables library. The script has to return a HashMap containing the attributes which should be set. See Table widgets for a detailed description of the available attributes.
// provide some demo data for display
def rawdata = [
[firstname:'Homer' , lastname:'Simpson' , title:'Nuclear disaster' , level:'3' , hired:'25.03.1989'],
[firstname:'Zaphod' , lastname:'Beeblebrox' , title:'President of the Galaxy', level:'0' , hired:'12.09.1979'],
[firstname:'Sheldon' , lastname:'Cooper' , title:'Mad scientist' , level:'321', hired:'01.04.2006'],
[firstname:'Robin' , lastname:'Scherbatsky', title:'Anchorwoman' , level:'25' , hired:'10.09.2004'],
[firstname:'Elmer' , lastname:'Fudd' , title:'Duck hunter' , level:'1' , hired:'15.12.1962'],
[firstname:'Eric' , lastname:'Cartman' , title:'Pupil' , level:'10' , hired:'23.02.1995'],
[firstname:'Mickey' , lastname:'Mouse' , title:'Private investigator' , level:'111', hired:'04.11.1932'],
[firstname:'Wilma' , lastname:'Flintstone' , title:'Housewife' , level:'64' , hired:'07.01.1964'],
[firstname:'Charlie' , lastname:'Harper' , title:'Composer' , level:'12' , hired:'16.07.2001'],
[firstname:'Daenerys', lastname:'Targaryen' , title:'Mother of dragons' , level:'238', hired:'08.05.2010'],
[firstname:'Lara' , lastname:'Croft' , title:'Tomb Raider' , level:'239', hired:'10.12.1991'],
[firstname:'Henry' , lastname:'Jones' , title:'Archeologist' , level:'109', hired:'08.06.1942']
]
// prepare the data for display
def tabledata = []
rawdata.each { element ->
tabledata.add("""
{'firstname': '${element['firstname']}',
'lastname' : '${element['lastname']}' ,
'jobtitle' : '${element['title']}' ,
'expertise': '${element['level']}' ,
'hiredate' : '${element['hired']}' }
""")
}
// return the table information including the data
return [
"columns": """[
{title: 'First name' , data: 'firstname'},
{title: 'Last name' , data: 'lastname' },
{title: 'Job title' , data: 'jobtitle' },
{title: 'Expertise level', data: 'expertise'},
{title: 'Hire date' , data: 'hiredate' }
]""",
"options": """{
'order': []
}""",
"data": "[${tabledata.join(",")}]" as String
]
Code example 15: Script for a table widget