Supportworks Version 7 · 2009-02-05 · Introduction to Supportworks System Customisation 1 The Supportworks Data Dictionary 3 ... Resizing Controls.....29 Docking/Floating Controls

SupportworksVersion 7.3

System Customisation Guide

Copyright © 2007 Hornbill Systems Ltd. All rights reserved.

Information in this document is subject to change without notice, and should not be construed as a commitment by Hornbill Systems Ltd. Hornbill Systems Ltd assumes no responsibility or liability for any errors or inaccuracies that may appear in this document.

Except as permitted by the Licence Agreement pertaining to the software described in this document, no part of the document may be reproduced, stored in a retrieval system, or transmitted in any form or by any means, whether electronic, mechanical or otherwise, without the prior written permission of Hornbill Systems Ltd.

Supportworks is a registered trademark of Hornbill Systems Ltd. Acrobat is a registered trademark of Adobe Systems, Inc. Microsoft, Outlook, Windows, Windows NT and Windows XP are registered trademarks of Microsoft Corporation.

Contents of System Customisation GuideIntroduction to Supportworks System Customisation 1

The Supportworks Data Dictionary 3What Is the Data Dictionary? ..............................................................................3

Multiple Data Dictionaries............................................................................5How Data Dictionaries are Stored and Distributed.......................................5Data Dictionary Locking ..............................................................................6

Elements of the Data Dictionary .........................................................................6Data Dictionary Rights ......................................................................................10Creating New Data Dictionaries........................................................................11Switching Data Dictionaries..............................................................................12Giving an Analyst Data Dictionary Access.......................................................13Interfaces to the Data Dictionary.......................................................................14The Data Dictionary Editor ...............................................................................16

Using the Data Dictionary Editor ...............................................................17Creating and Deleting Data Dictionary Items.............................................18

Form Configuration Tools.................................................................................19Accessing a Form Configuration Tool and Applying Changes ..................20

The Form Designer............................................................................................22Starting the Form Designer and Applying Changes ...................................23The Form Designer Workspace ..................................................................25

The Layout Area...................................................................................25The Object Inspector Area ...................................................................26The Field Chooser Area .......................................................................28

Managing the Form Designer Workspace ..................................................29Show/Hide Controls .............................................................................29Resizing Controls .................................................................................29Docking/Floating Controls ...................................................................30

Functions Available for the Layout Area....................................................30Automatic Positioning and Sizing Functions .......................................30Insertion Functions ...............................................................................31Duplication Functions ..........................................................................34

Stacking Functions ...............................................................................34Grid Functions......................................................................................35Tab Order .............................................................................................35Object Search .......................................................................................36Object Conversion................................................................................36

Repositioning Ordered Items ............................................................................36Customisable Attributes ....................................................................................37

The Supportworks Database 39Attributes Viewable in the Data Dictionary Editor ...........................................41

Table-Level Attributes................................................................................41Column-Level Attributes ............................................................................43

Creating and Integrating New Tables................................................................46The Table Creation and Integration Procedure in Detail ............................47

Stage (a): Preparation ...........................................................................47Stage (b): Creating the New Table and Creating Extra Columns in the Open/Closed Call Table .......................................................................47Stage (c): Creating Standard Forms .....................................................48Stage (d): Setting Up the Table Schema Basics...................................48Stage (e): Creating Browser and Search Displays ...............................49Stage (f): Creating “Manage” Commands ...........................................50Stage (g): Creating a Pick-List Window ..............................................50Stage (h): Integrating the New Table into Call Forms.........................50Stage (i): Creating New Field Bindings in Call Forms ........................51

Log Call Forms 53Attributes Handled in the Log Call Form Configuration ..................................54

Attributes In the Settings Tab for Log Call Forms .....................................55Attributes in the Associated Tables Tab for Log Call Forms.....................58

Using and Managing the Associated Tables Pick-List ........................58Table Properties: Miscellaneous ..........................................................59Table Properties: Data Assignments to Table(s)..................................61

Attributes in the ‘Show Me’ Items Tab for Log Call Forms ......................63Using and Managing the ‘Show Me’ Items Pick-List..........................63“Tree Browser Form” Action...............................................................65“Pick List” Action ................................................................................65Menu Separator “Action”.....................................................................66

“Record Properties” Action..................................................................66“Inventory Details” Action...................................................................67“SQL Query” Action ............................................................................68“Script” Action .....................................................................................68“Run External Program” Action ..........................................................69“Send E-Mail” Action ..........................................................................69“Open URL” Action.............................................................................69“Record Reset” Action .........................................................................70“Information Browser” Action.............................................................70

Attributes Handled in the Form Designer .........................................................71Form-Level Attributes ................................................................................72Object-Level Attributes ..............................................................................73

Data ......................................................................................................75General .................................................................................................78Group....................................................................................................80Object Placement: Position ..................................................................81Object Placement: Resize/Scaling........................................................82Appearance...........................................................................................83Field-Specific Properties (and also Label-Specific Properties) ...........89

Call and Form Types and Call Classes............................................................101Managing Call Classes..............................................................................103

Form Structure in Memory..............................................................................107Creating New Call Form Types.......................................................................109Copying Call Form Types ...............................................................................110

Call Details Forms 113Attributes Handled in the Call Details Form Configuration ...........................114

Attributes In the Settings Tab for Call Details Forms ..............................115Attributes In the Associated Tables Tab for Call Details Forms..............118

Attributes Specific to the Call Details Form ......................................119Attributes In the ‘Show Me’ Items Tab for Call Details Forms ...............120

Attributes Handled in the Form Designer .......................................................121Creating and Copying Call Details Forms ......................................................121

Standard Forms 123Standard Management Forms..........................................................................123Standard Call-Action Forms............................................................................124

Attributes Handled in the Standard Form Configuration ................................125Attributes In the Settings Tab for Standard Forms ...................................126Attributes in the Associated Tables Tab for Standard Forms...................128

Using and Managing the Associated Tables Pick-List ......................128Table Properties: Miscellaneous ........................................................129Table Properties: Data Assignments to Table(s)................................130

Attributes in the Action Items Tab for Standard Forms ...........................131Attributes Handled in the Form Designer .......................................................131Creating and Integrating New Standard Form Types......................................133

To Create a New Form .............................................................................133To Create a Non-Tabbed Form ..........................................................134To Create a Tabbed Form ..................................................................139To Complete the Form Configuration and Design.............................144

To Integrate the New Form(s) into the System ........................................145

Table Browsers 147Attributes Relevant to Table Browsers in the Standard Form Configuration .148Attributes Relevant to Table Browsers in the Form Designer ........................148Creating and Integrating New Table Browsers ...............................................148

To Create a New Table Browser ..............................................................149To Integrate a New Table Browser into the System.................................154

SQL Tree Browser Forms 155Attributes Relevant to the Entire Dialogue Box and the Search Tab..............156Attributes Relevant to the Browse Tab ...........................................................159Creating and Integrating New SQL Tree Browser Forms...............................159

To Create a New SQL Tree Browser Form ..............................................159To Integrate a New SQL Tree Browser Form into the System ................160

SQL Tree Browsers 161Attributes Relevant to the Browser Tier .........................................................161Attributes Relevant to the Group Tier.............................................................162Creating and Integrating New SQL Tree Browsers ........................................164

To Create a New SQL Tree Browser........................................................165To Integrate a New SQL Tree Browser into a Database Entity View......166To Integrate a New SQL Tree Browser into an SQL Tree Browser Form166

Pick Lists 167Attributes Relevant to Pick Lists.....................................................................167Creating and Integrating New Pick Lists ........................................................169

To Create a New Pick List ........................................................................170To Integrate a New Pick List into the System ..........................................170

“Manage” Commands 173Attributes Relevant to “Manage” Commands .................................................173Creating New “Manage” Commands ..............................................................175

Managing Global Parameters 177Modifying Global Parameter Values...............................................................178Creating New Folders and Parameters ............................................................179

Creating a New Folder Based on an Existing Folder................................181Deleting Folders and Parameters.....................................................................181Using Standard Context Variables in Filters ...................................................182

Defining Active Pages 183

Customising the Workspace Views 185Web-Style Views (“Supportworks Today”)....................................................187Helpdesk Views...............................................................................................188

Changing Generic Characteristics of the View.........................................190Changing the Characteristics of a Call List ..............................................191

Creating User-Selectable Filters (Optional) .......................................194Changing the Characteristics of a Work-Item List ...................................195Changing the Characteristics of an Issue List...........................................197Changing the Characteristics of the Watched Calls List ..........................198

The Calendar View..........................................................................................200The E-Mail View.............................................................................................201Database Entity Views ....................................................................................202

Common Aspects of Database Entity Views ............................................203Attributes Relevant to Individual Database Entity Views ........................203Creating New Database Entity Views.......................................................207

Call-Search Views ...........................................................................................208The Database Searches View ..........................................................................210The My Library View......................................................................................212

The KnowledgeBase View..............................................................................213Report Views...................................................................................................214

Filtering Call Commands 217Filtering Calls Viewed By Reference..............................................................217Filtering Call Searches ....................................................................................218

Customising Aspects of Call Profiles 221Renaming Call Profile Attributes ....................................................................222Renaming Call Profile Categories (Optional) .................................................222Filtering Problem Profiles (Optional) .............................................................223Filtering Resolution Profiles ...........................................................................226

Customising Form Functionality 229Mapping Forms to Call Actions ......................................................................229

Mapping Forms to Call Actions by Call Class (Optional) .......................230Enabling Remote Form Access (Optional) .....................................................232

Enabling Customisation of New Call Confirmations 233

Controlling Global Call Escalation (Optional) 235

Controlling Work-Item Completion (Optional) 237

Customising Operational Aspects of Issues (Optional) 239Filtering Call Selection for Issues ...................................................................239Defining an Alternative Customer Browser to Use with Issues......................240

Filtering the Contents of Support-Team Trees 243Filtering the Helpdesk-View Support-Team Tree...........................................243Filtering Support-Team Trees Used for Selection ..........................................245

Renaming Support-Group Attributes 249

Filtering Skills (Optional) 251Filtering the Display of Skills in a Tree Browser............................................251Filtering the Selection of Skills on Call Assignment ......................................252

Introducing Features Relating to E-Mail (Optional) 255Automatically Filing Received E-Mail ...........................................................255Automatically Generating an E-Mail Audit Trail ...........................................257Defining E-Mail Integration Functionality......................................................258

Filtering the Display of Client/Server Connections (Optional) 261

Defining Third Party SLA Functionality (Optional) 263

CTI Customer Look-Up (Optional) 265

Application-Specific Customisation 267Customising the Visual Configuration Manager (Optional) ...........................267

Remote Queries 269Viewing the Components of a Remote Query.................................................270

The Individual Elements of Remote Query Components .........................272Modifying a Remote Query.............................................................................273

To Modify the Elements of a Query Component .....................................274To Create a New Query Component.........................................................274To Delete a Query Component .................................................................275To Preview the Results of a Remote Query..............................................275

Creating and Deleting Remote Queries...........................................................276Considerations Relating Specifically to Bulk Mail ..................................277

Components for Querying Regional Settings..................................................277

Server-Side Event Scripting 281How Server-Side Scripting Works ..................................................................283Creating a Script File.......................................................................................286

Testing Your Script...................................................................................288API Functions Specific to Supportworks..................................................289

The Functions and their Descriptions.................................................289List of Supplied APIs................................................................................292

Visual Process Management 295Process-Triggering Events ..............................................................................296Starting and Using the Visual Process Manager .............................................296

General Controls in the VPM Workspace ................................................298Show/Hide Controls ...........................................................................298Resizing Controls ...............................................................................298Docking/Floating Controls.................................................................298

The VPM Workspace Areas............................................................................299The Processes Pane...................................................................................299

Creating a New Process .....................................................................300Selecting an Existing Process.............................................................302Deleting an Existing Process..............................................................302

The Process Design Tab ...........................................................................303What You Can Do in the Process Design Tab ...................................305

The Input Parameters Tab.........................................................................307Adding an Input Parameter to the List ...............................................308Modifying the Properties of an Input Parameter................................309Deleting an Input Parameter...............................................................310Reorganising a List of Input Parameters ............................................310

The Test/Invoke Tab.................................................................................311Creating a Test for a Process..............................................................312Testing a Process................................................................................313Managing Existing Tests....................................................................314

The Properties Pane ..................................................................................314The Design Tools Pane.............................................................................316

Process-Validation Errors ..................................................................316Node-Validation Errors ......................................................................316

The Process-Attribute Categories In Detail ....................................................317Process-Level Attribute Categories ..........................................................317

Process Properties ..............................................................................317Common Node-Level Attribute Categories..............................................318

Node Properties ..................................................................................318Flow Properties ..................................................................................318

Type-Specific Node-Level Attribute Categories ......................................318Node Parameters ................................................................................318

Functional Scripting 319Programming a Show Me Item “Script” Action .............................................319

Conventions Used in the Method Reference ............................................320JavaScript Method Reference ...................................................................320

Customising Dashboard Charts .......................................................................340Modifying an Existing Dashboard Query .................................................340

To Modify the SQL and Display Name for a Query..........................340To Modify the Query Interval ............................................................341

To Create a New Dashboard Query ..........................................................341To Delete an Existing Dashboard Query ..................................................343

Customising Ticker Bar Feeds ........................................................................344Modifying Ticker Bar Configuration Defaults .........................................344Customising Ticker Bar Queries for Supportworks Feeds .......................345

To Modify the Query Interval for Supportworks Feeds.....................345To Modify an Existing Query for a Supportworks Feed....................345To Create a New Query for a Supportworks Feed .............................346To Delete an Existing Query for a Supportworks Feed .....................347To Modify the Characteristics of Separators for Supportworks Feed Items ...................................................................................................347

Customising Code for Web-Sourced Ticker Bar News-Feeds .................348To Modify the Download Interval for Web-Sourced News-Feeds ....349To Modify the Characteristics of Separators for Web-Sourced Feed Items ...................................................................................................349Adding News-Feeds from Other Websites.........................................349

Customising the Help Menu............................................................................350Customising New Call Confirmations ............................................................352Customising Analyst Portal Notifications .......................................................354

Appendix A Default Customisable Table Specifications 357Charge Centre Table........................................................................................357Asset Table ......................................................................................................358Generic Type Table .........................................................................................360Manufacturer Table .........................................................................................361Open/Closed Call Table ..................................................................................361Site Table.........................................................................................................365Supplier Table .................................................................................................366Support Analyst Table.....................................................................................366Support Group Table .......................................................................................368Issue Table.......................................................................................................369Call Diary Table ..............................................................................................370Customer Table ...............................................................................................371

Problem Profile Table .....................................................................................373Resolution Profile Table..................................................................................374

Appendix B Standard Context Variables 375

Appendix C Shortcut-Bar Icons and their Identifiers 377

Appendix D Global Parameter Summary 381

Introduction to Supportworks System Customisation

1


In Supportworks, the dividing line between the terms “configuration” and “customisation” (as used in the documentation) can sometimes seem quite blurred, as both types of activity are concerned with making the system function or present itself precisely in accordance with your team’s requirements and preferences. Generally, though, we can say that customisation facilities allow you, at least potentially, to introduce completely new functionality or visual elements to Supportworks, whereas configuration functions merely allow you to toggle or qualify existing functionality. However, even within the context of customisation, you may still be “configuring” functionality in certain cases.

Customisation tends to be closely related to the Supportworks database. It sometimes requires at least a basic knowledge of SQL. It always involves changing the look-and-feel, content or functionality of a given type of Supportworks display or generated output, perhaps by alteration of existing entities or by the creation of new ones. Where functionality can be made to differ between one data dictionary and another, the modifications required to do that would always be regarded as customisation.

The four main groups of customisation activities, as covered in this Guide, are as follows:

• Data-dictionary-based customisation (including form design and configuration)

• Database schema customisation (in systems other than Supportworks Essentials)

• Feature-specific customisation, comprising:

– Customisation of remote queries (for data merging)

– Creation of server-side scripts to run event-triggered processes both within and outside of Supportworks

– Creation, using a visual editor, of XML files to dictate the running of event-triggered processes


2

• Functional scripting, involving the development of PHP or JavaScript code to alter or enhance existing Supportworks functionality or to create new functionality

Most of the above activities are performed from within the Supportworks client, while others require either separate utilities supplied (and installed) with the server or generally available text/script editors.

All of the customisation activities in these groups and sub-groups are covered in their respective chapters within this Guide.

The Supportworks Data Dictionary

3


What Is the Data Dictionary?To provide you with a powerful and flexible means of customising almost all aspects of Supportworks, Hornbill has written the application in accordance with the principles of adaptive server technology, and has introduced a data dictionary mechanism between the application and the SQL database. Adaptive server technology allows the application’s internal data structures to adapt to the schema of the underlying database at run time. This underlying schema is basically the definition of each table in terms of the following:

The table’s nameThe data source nameWhich column is the primary keyThe table’s ownerRemarks about the tableEach column’s nameThe maximum data size defined for each columnThe general data type, and the SQL data type, defined for each columnWhether or not a column is auto-incrementingWhether or not a column is case-sensitiveWhether or not a column allows null valuesWhether or not a column accepts negative numerical dataWhether or not a column defines its data as currencyWhether or not a column is searchable

Thus, if you were to change, say, the maximum size for data in a given column (using an appropriate SQL statement), the input validation on a client form for all data fields associated with that column would change correspondingly.

The database itself will allow only attributes such as those mentioned above to be defined. However, any helpdesk application with enhanced functionality would require considerably more information about a column in order to comprehensively control and display user input for a corresponding field. The database on its own is able to provide enough information to limit a field’s input


4

to, say, an alphanumeric string of the maximum size allowable, but an additional mechanism needs to be linked to the database tables to allow further field attributes to be defined. For example, we may want to limit the input to all numeric characters, and perhaps allow only hyphens at specific character positions within the field. Or, we may want the field to be read-only for some users, but read/write for other users. We may want to provide customised help for the field, or mark it as a link to a Web URL.

To be able to offer such enhancements to the basic column/table configuration, Supportworks makes use of data dictionaries. A data dictionary effectively augments the attribute information held against each column in each table, allowing many more column-related parameters to be configured, particularly in relation to form fields that are bound to (that is, associated with) those table columns. The Supportworks server dynamically merges the basic database schema from the SQL database with the enhanced database/form schema in the data dictionary. The enhanced elements are then made available for customisation by suitably authorised users via the Supportworks client. Those enhanced database attributes that are bound to form fields would define and control the behaviour of the fields when the user is viewing, inputting or searching for data.

The database/form attributes discussed above are by no means the only kinds of customisable elements that you will find in the data dictionary. There are a large number of additional characteristics of client behaviour and appearance defined in the data dictionary that administrative users can modify, including, for example, the layouts and components of multiple forms. All the available categories of customisable attributes are outlined in Elements of the Data Dictionary on page 6. Customisation of such stored attributes is performed by means of several different types of GUI interface to the data dictionary, which provide read and write access to the attributes.

Note In the data dictionary, you can modify only the enhanced database/form schema elements. If you wish to modify the basic database schema elements (that is, the actual SQL-defined structure of a database table), you must use a utility such as the Database Schema Editor. All Supportworks systems other than Essentials support basic database schema modification.


5

Multiple Data Dictionaries

It is possible to have more than one data dictionary in any given system (except in a Supportworks Essentials system, which is restricted to one), and to assign these dictionaries to different users. In effect, you could have very different client behaviour and appearance between different users on the same system, depending on the organisational requirements pertaining specifically to each of them. With multiple data dictionaries in your system, you could generate a different set of client forms within each of them, corresponding to the different support requirements that may exist in your organisation. To cater for analysts with multiple responsibilities, more than one data dictionary can be assigned to such individuals.

A typical example of using multiple data dictionaries in practice would be the provision of displayed field names and help text in different languages. Another example would be the ability to configure different support groups with different levels of access to individual data items, so that the representations of certain preselected columns on the client interface (that is, form fields) would be visible to some analysts, but not to others.

How Data Dictionaries are Stored and Distributed

As data dictionaries are shared among analysts, they have to be made centrally available, and are therefore stored on the server. Whenever a user logs into the system, the data dictionary designated as their default one is automatically loaded into memory on the client. This also happens when a user refreshes the current data dictionary. Similarly, when a user switches data dictionaries (assuming they have the rights to do so), the new data dictionary loads into memory and becomes the current one. It is always the current data dictionary that governs the customisable aspects of the appearance and behaviour of the client into which it has been loaded.

If you have rights to edit the current data dictionary, you would be able to make changes to it (initially in local memory) using any of the interfaces available on the client (see Interfaces to the Data Dictionary on page 14). As such changes would apply immediately to the client running on your computer, you can make numerous adjustments by trial and error, and look instantly at the results in each case, before making a final decision to keep and distribute the new configuration.


6

When you finally save the current data dictionary, by means of the relevant command in the client’s Administration menu or when invited to do so on exit from the client, what happens is that you actually update its master copy on the server. Once you have thus saved a data dictionary, the new copy is available for loading into any client instance, either automatically on login, or manually by means of the Refresh Data Dictionary command (or the Switch Data Dictionary command) in the client’s Tools menu.

Data Dictionary Locking

Supportworks has a locking mechanism that prevents changes to a data dictionary being lost in a situation where two or more users are editing it at the same time and they then separately proceed to save it to the server.

When any data dictionary is opened for editing on any client (by means of the Data Dictionary Editor, the relevant Form Configuration tool, the Form Designer, or the Form wizard), its copy in memory on every other client logged into the same system is immediately locked for further editing. If another analyst then tries to open their own copy of that data dictionary, they will be informed that it is currently locked by the first analyst, and they will not be able to display the requested editing tool. Once the data dictionary has been saved to the server from the first client, any other analyst who now attempts to open their older copy of it for editing will be informed that their data dictionary is out of date and that they cannot proceed until they have refreshed it. This ensures that only the latest version can be opened.

Elements of the Data DictionaryAs indicated above, a data dictionary offers extended attributes to table columns, largely via the forms defined within it, where fields on those forms are bound to the columns concerned. Although this adds considerable functionality to a purely static schema system, this functionality alone would still be somewhat limiting for a modern business application.

Hornbill has therefore included a number of additional attributes within the data dictionary that further enhance the customisation capabilities of Supportworks. The extra attributes offer the possibility of modifying, for your own


7

organisation’s purposes, key visual and functional aspects of the various forms, sub-menus, lists and icons that make up the client user interface. You will also be able to create completely new elements (such as forms) for the user interface. You would use the Data Dictionary Editor, or a combination of the Form Designer, the Form wizard and the relevant Form Configuration tool, to make such modifications or additions.

Customisable attributes are divided into a number of categories:

• Database The items in this category form a representation of the basic Supportworks database schema (including the underlying schema). Included here are augmented table-column attributes whose values must be consistent when referenced from any form, or whose values make up the initial defaults for certain attributes belonging to form fields. All the items in this category are clearly displayed in the Data Dictionary Editor. For the underlying database-schema items, the settings and values shown here would be read-only.

• Forms Each item in this category provides the definition of a “standard” form that allows analysts to view existing data from managed tables either in fields or in scrollable lists, or to create new records in those tables. A standard form’s fields may be associated with just one managed table, or perhaps with a main table as well as a number of related tables.

The default Supportworks installation comes with fairly simple kinds of form. For example, the Manufacturer Properties form is one whose fields correspond fully and exactly with the columns of the single database table to which it relates, and all of it is contained on a single page. By convention, the name of such a form would begin with the prefix “Ef”, which stands for “easy form”. Another example, the Customer Properties form, contains not only fields associated with the relevant table, but also those associated with a table that is related to the main table. These relational fields appear, in this case, on a separate tab on the form. In fact, the total amount of data to be displayed on this form is large enough to warrant several tabs. By convention, the name of such a form would begin with the prefix “Tf”, which stands for “tabbed form”. A third example, the Browse Manufacturers window, is not a field-based form at all, but one that allows analysts to browse a table by scrolling through a list of records. With such a table browser, it is possible to create and apply an SQL filter as part of the form definition, so as to exclude certain


8

records from the display. By convention, the name of a table browser would begin with the prefix “Tb”, which stands for “table browser”.

You access the attributes relating to a standard form by means of the standard Form Configuration tool, the Form Designer and the Form wizard. Together, these tools allow you to define most of the operational and visual characteristics of the form, and any system functionality that is to apply whenever the form is active.

• Log Call Forms Each item in this category provides the definition of a specific type of Log Call form. Two Log Call form types (Helpdesk Call and Software Call) are defined, for example, in the Default data dictionary. In the case of a specialist system such as Supportworks ITSM, there would be a number of Log Call form types defined in an appropriate data dictionary (for example, those relating to Incidents, Problems and Change Requests, respectively). You access the attributes relating to such a form type by means of the Log Call Form Configuration tool and the Form Designer. Together, these tools allow you to define most of the operational and visual characteristics of the selected form type, and any system functionality that is to apply whenever such a form is active.

• Call Detail Forms Each item in this category provides the definition of a specific type of Call Details form. Two Call Details form types (Helpdesk Call and Software Call) are defined, for example, in the Default data dictionary. In the case of a specialist system such as Supportworks ITSM, there would be a number of Call Details form types defined in an appropriate data dictionary (for example, those relating to Incidents, Problems, Known Errors and Change Requests, respectively). You access the attributes relating to such a form type by means of the Call Details Form Configuration tool and the Form Designer. Together, these tools allow you to define most of the operational and visual characteristics of the selected form type, and any system functionality that is to apply whenever such a form is active.

• Pick Lists Each item in this category provides the definition of a client pick-list window (for example, the Choose Customer window) that allows analysts to select the desired record from a list of possible records when attempting to populate the Customer Details area and the Asset Details area (if any) of a Log Call form. A pick-list window has a similar appearance to a Table Browser type of window. Again, it is possible, for purposes of exclusion, to create and apply an SQL filter as part of the definition.


9

• Managed Entities Each item in this category provides the definition of a Manage command, together with its “children”, in the main client window’s File menu. The definition covers the names of the menu command and sub-commands, and also the type of form or browser to be invoked by each sub-command.

• Global Parameters This category includes configurable items relating to a variety of areas within the client:

– The locations of the active pages

– The My Calls tab in the Helpdesk view (optionally including custom filters that allow specific subsets of calls to be viewed)

– The Search For Calls view

– The Resolve/Close Call dialogue box

– Filtration of the Support Team tree browser in the Helpdesk view

– The My Work Items tab in the Helpdesk view

– The names of the custom attributes associated with call profiles

– The names of the custom attributes associated with support groups

– Optionally, the definitions of mail folders into which e-mail messages that have given rise to call actions by analyst demand are to be moved automatically by the system

– Optionally, a second My Calls tab in the Helpdesk view, next to My Issues (with an alternative filter applied to allow a different subset of calls to be viewed)

• SQL Tree Browsers The items in this category provide the definitions of the structure and appearance of the tree browser in (a) the Customers and Assets (or Configuration Items) views in browse mode, and (b) the Browse tab in the Find Customer and (where applicable) the Find Asset dialogue boxes. Each of the top-level categories in such a tree browser is separately definable. It is possible to create and apply an SQL filter as part of the definition for any top-level category, so as to exclude certain records from the tree display. This means that you can create totally new categories below which records corresponding to almost any conceivable criteria could be displayed.

• SQL Tree Browser Forms The items in this category provide the definitions of (a) the overall structure of the Find Customer and (where applicable) the Find Asset dialogue boxes, and (b) certain aspects of their respective Search tabs.


10

The Find Customer/Asset dialogue box, which consists (by default) of both a Search tab and a Browse tab, is invoked when an analyst selects Manage Customers/Assets and then Browse from the File menu in the main client window, or selects the Change Customer/Asset command from the Show Me menu on the Log Call or Call Details form. It is possible to create and apply an SQL filter as part of the definition, so as to exclude certain records from the search result.

• Database Entity Views The items in this category provide the definitions of the structure and certain other aspects of the Customers and Assets (or Configuration Items) views. For the search mode in such a view, it is possible to create and apply an SQL filter as part of the definition, so as to exclude certain records from the search result.

• Image Lists Each item in this category is a repository of icons that are available for use in certain parts of the client, such as the tree browser found in the Customers view and (if applicable) the Assets view when switched to browse mode. For example, an icon of a house could represent Customers by Site in the Customers view, while an icon of a PC could represent a PC hardware asset, as displayed in the Assets view. The icons are applied to tree browsers by reference from the appropriate sections of the data dictionary.

• Pictures Each item in this category represents a colour, texture or other “wallpaper” motif that you can apply to a Log Call form or Call Details form using the Form Designer. You can examine the available motifs and add new ones using the Data Dictionary Editor.

For detailed descriptions of all the elements within each category of customisation, see the relevant chapters of this guide.

Data Dictionary RightsAfter first-time installation of the Supportworks system, you should, as System Administrator, by default have the rights necessary to manage data dictionaries. If these rights have been disabled and you wish to reinstate them, or if you wish to grant all or some of the rights to another user, you should follow the instructions given here:

1. Log into the Supportworks client as a user assigned the System Administrator or Group Manager role, and display the Helpdesk view.


11

2. In the tree browser showing your support team, select Properties from the right-click menu applicable to yourself or the user concerned.

3. In the Support Analyst Properties dialogue box, select the System Privileges tab and scroll down the Permissions list until you see Data Dictionary Rights.

4. If you want all the relevant rights to be granted, click the checkbox to the left of the Data Dictionary Rights item so that the cross changes to a tick. If you wish to grant only certain rights, click the checkboxes that relate specifically to these.

5. Click OK.

You, or the user concerned, now have the necessary rights.

Creating New Data Dictionaries

Note This section does not apply to Supportworks Essentials systems, as these have only one data dictionary.

If you wish to build customised helpdesk applications additional to the one(s) supplied, you must create at least one new data dictionary, on which you may then carry out the required customisation. Any new data dictionary you create will always start off as an exact copy of an existing one. On a non-customised (evaluation) system, your very first new data dictionary will be based on the Default data dictionary. The Default data dictionary itself is not modifiable in any permanent sense and should not be used as anything other than a template.

To create a new data dictionary for your Supportworks system, follow the instructions given here:

1. Select Create New Data Dictionary from the Administration menu. You are prompted to select an existing data dictionary on which to base the new dictionary. Initially, only the supplied data dictionaries will be available (including the Default template). Note, too, that the JavaScript files to be associated with the new data dictionary will be copies of those associated with the source data dictionary.


12

2. Select the dictionary required as the basis for the new one, and click OK. You are prompted to enter the name of the new dictionary.

3. Type in the name by which you will want to identify the data dictionary you are creating, and click OK. You are informed that the dictionary has now been created, and you are invited to switch over to it.

4. If you wish to make the new data dictionary the current one, click Yes. You are now free to modify the attributes in that dictionary, and you can observe, immediately afterwards, the effects of those changes on the client.

5. If the Analyst Portal is used by anyone in the support team, stop and restart SwServerService to allow calls to be progessed from within the Analyst Portal.

The new data dictionary you have created and configured is potentially available to any support analyst in your team.

Switching Data Dictionaries


Data dictionaries are the entities that give client instances their respective application profiles. Only one data dictionary can be active on a client session at any given time: the default one that is assigned to the analyst by the system administrator, or the one that is set as “current” by the user. The name of the data dictionary in current use is displayed in the title bar of the client window.

As the Default data dictionary and all subsequently created dictionaries are held in a common area of the Supportworks server, they are potentially available to any support analyst, subject to permissions. There are various kinds of permissions that you can grant to analysts for the purpose of accessing data dictionaries. For example, you can give an analyst the general right to switch to other data dictionaries. You can also specify which data dictionaries the analyst can use. See the next section, entitled Giving an Analyst Data Dictionary Access on page 13 for details.


13

To switch data dictionaries – that is, to make another data dictionary the current one for your own client instance – follow the instructions given here:

1. Select Switch Data Dictionary from the Tools menu. You are prompted to select the data dictionary you wish to switch to. Unless your role is System Administrator, the selection list will be restricted to those data dictionaries to which you have been granted access.

2. Select the required data dictionary, and click OK. Notice that the dictionary name in the client’s title bar has changed appropriately.

If an analyst does not have the right to switch to other data dictionaries, the Switch Data Dictionary item in their client instance would be greyed out, and they would be restricted to the data dictionary assigned to them.

Giving an Analyst Data Dictionary Access


In your support organisation, there may be a variety of analyst groups or individuals, all with different responsibilities, or in different worldwide locations. It may be desirable, in such a scenario, to tailor the appearance and/or functionality of the client in accordance with specific user-related organisational requirements.

The way to deal with such requirements is to first create a number of distinct data dictionaries, each customised in a different way, and to then assign a default data dictionary and perhaps grant rights to switch to other data dictionaries (which may each have application-specific rights that you can enable), to every analyst in turn.

To give an analyst access to one or more data dictionaries and to specify what they can do with them and what they can do when using the applications concerned, follow the instructions given here:

1. Ensure that you are logged into the Supportworks client as the system administrator, and display the Helpdesk view.


14

2. In the tree browser showing your support team, select Properties from the right-click menu applicable to the analyst concerned.

3. In the Support Analyst Properties dialogue box, select the System Privileges tab.

4. In the Data Dictionary field, select the data dictionary you wish to assign to the analyst as the default.

5. Initially, users have no data dictionary rights – that is, they do not have permission to create new dictionaries, edit the current dictionary, switch to other dictionaries, or delete dictionaries. If you wish to give the analyst any or all of these rights, you should scroll down to the bottom of the Permissions list to bring Data Dictionary Rights into view, and click the appropriate checkbox(es).

6. Select the Application Rights tab.

7. In the Data Dictionaries pane, check each box relating to a data dictionary that the analyst will be expected to use. In the Application Permissions pane, for each checked data dictionary that has application-specific rights associated with it, enable the rights appropriate to the analyst by clicking on the relevant red crosses.

8. Click OK.

The analyst can now use, and possibly manage, the prescribed data dictionaries. The one you have assigned as the default will automatically be invoked as the current one every time the analyst logs into Supportworks.

Interfaces to the Data DictionaryAs mentioned previously, for the purposes of system customisation, there are several distinct means of user access to a data dictionary, all of which are available within the Supportworks client:

• The Data Dictionary Editor

• Appropriate Form Configuration tools

• The Form Designer

• The Form wizard


15

Customisation of attributes under the Database, Pick Lists, Managed Entities, Global Parameters, SQL Tree Browsers, SQL Tree Browser Forms, Database Entity Views, Image Lists and Pictures categories is possible only via the Data Dictionary Editor. Customisation of Log Call forms, Call Details forms, standard forms (including table browsers) is carried out using the relevant Form Configuration tool and the Form Designer. These forms are essentially dialogue boxes that are designed as fully customisable entities.

The way in which a data dictionary relates to the client as a whole can be likened to the way in which the Windows registry relates to Windows. In fact, you will find that the Data Dictionary Editor has a similar look-and-feel to the Microsoft Registry Editor. Just like the Registry Editor, the Data Dictionary Editor provides a low-level view of many of the system’s functional elements, and allows you to make changes to these.

A Form Configuration tool provides facilities for customising the data dictionary with respect to the forms defined within it. The tool allows you to modify those properties and functional aspects of a form that are unrelated to the form’s individual layout elements. Several separate (but similar-looking) Form Configuration tools actually exist, each specific to a given variety of form. By means of such a tool, you can enable and disable certain functional elements of the form concerned, and (in the case of a call form) create and modify custom menu commands on the form. Just as importantly, the tool allows you to configure the form’s table associations.

The Form Designer, with its functional resemblance to certain components of Microsoft Visual Basic, also provides form-customisation facilities, but in relation to the individual GUI elements within the form. It allows you to modify the layout of a form, and to configure the behaviour and appearance of each object on the form.


16

Note Since the attribute settings and values in a data dictionary affect the system at a basic level, it is essential that you exercise the utmost care when making changes to them. Certain illogical combinations of settings or values in a data dictionary can cause all Supportworks client instances using that dictionary to behave in an unexpected fashion, and may even cause the client sessions to crash. You are strongly advised to back up any data dictionary that you wish to modify before actually making (or at least saving) the changes. The data dictionary files have the extension .ddf, and are located in Program Files \ Hornbill \ Supportworks Server \ data \ _dd_data on the server.

The Form wizard is used purely to create new standard forms. A form generated by the wizard contains only the most essential parts of its configuration and layout. Thus, having created a form using the wizard, you would still need to customise it exactly to your requirements by employing the Form Configuration tool and the Form Designer.

Irrespective of the data-dictionary interface you use to customise your Supportworks system, when you save the current data dictionary to the server, your changes will become available to all clients that have access to the same data dictionary. The new configuration will not actually come into force on another client until the analyst using that client has selected Refresh Data Dictionary, or Switch Data Dictionary (to the relevant one), in the Tools menu. In the case of form customisation, only forms opened after the refresh would be affected by the new configuration.

The Data Dictionary EditorThe Data Dictionary Editor gives you customisation control over certain aspects of the operation and look-and-feel of the application. The editor allows you to view particular elements of the existing configuration (which are displayed under the relevant customisation categories), to modify many of these elements, and to create new ones.

Using the editor, you can create and modify specific functional elements of any given data dictionary according to the requirements of your support organisation. Furthermore, if you create a number of separate data dictionaries


17

(as described in Creating New Data Dictionaries on page 11), each with a distinct set of functional elements, you can allocate these to different analysts.

You can also launch certain Form Configuration tools (those relating to call forms) from within the Data Dictionary Editor.

All of the attributes accessible via the editor and other data-dictionary interfaces are described in the relevant chapters of this guide.

Using the Data Dictionary Editor

You access the Data Dictionary Editor from within the Supportworks client. From the Administration menu, select Edit Current Data Dictionary. The editor window is displayed, as follows:

The editor displays customisation categories from the currently invoked data dictionary. This will be the Default data dictionary if no others have been created. You will find that, although you can edit the Default data dictionary in memory, you will not be allowed to save it, which ensures that you will always be able to return to a guaranteed working system.


18

The left-hand pane of the data-dictionary window shows all the customisation categories that are available in the editor. To expand any item in this pane down to the next level, click the relevant + sign, as in any other tree browser. If you select, at any level, an item that has configuration parameters (attributes) associated with it, these will be displayed in the right-hand pane. The parameters are generally presented in two columns, the left-hand one containing the parameter names, and the right-hand one containing the respective parameter values.

You can change any parameter value that is not greyed-out. A parameter-value field may be of the text-entry, drop-down-list or checkbox type. When you click in a drop-down-list field, a relevant button appears, allowing you to make your selection by clicking it. Alternatively, with some data dictionary items whose parameters are not editable within the fields themselves, you would normally be able to edit these by double-clicking the name, whereupon a separate edit window would open.

As soon as you have made at least one change within the editor, you will notice that the OK button becomes a Save button. If you click this button (or select the Save command in the File menu) at any time, all changes to the data dictionary you have made up to that point during the current client session (including those made within the Form Designer and Form Configuration) will be saved to the server.

If you click the Close button, the Data Dictionary Editor will apply your changes in memory only. However, you will still have the opportunity to save them to the server by selecting Save Current Data Dictionary from the Administration menu. Failing that, if you subsequently switch data dictionaries or when you finally exit from the client, you will be prompted to state whether or not you wish to save those changes. If you click No at that point, your changes will be lost.

Creating and Deleting Data Dictionary Items

All customisation categories, together with their subordinate items, are displayed in the left-hand pane of the editor. You can create additional subordinate items within all the categories except for Database and Image Lists. Also, you can delete items from any section other than Database.


19

To create a new item, select File > New, followed by the required item. In many cases, you are simply prompted to enter a name. Type in an appropriate name and click OK, whereupon the new item and its default attributes become visible in the editor. In other cases, you are presented with a dialogue box appropriate to the item concerned, containing various other parameters to enter or select. Details of these are given in the chapters covering the respective customisation categories. Once you have created a new item, you can go ahead and customise it.

To delete an item, first select it in the left-hand pane of the Data Dictionary Editor window, and then select Edit > Delete. If you are deleting a Log Call form for which Quick-Log and Scheduled calls based on it still exist, a confirmation prompt would be displayed, warning you about the consequences should you elect to proceed with the deletion. In all other cases, the item would simply be deleted without confirmation.

You can then apply or save the new configuration incorporating your creations or deletions just as if you had simply made an attribute change in the right-hand pane.

Form Configuration ToolsA Form Configuration tool is a multi-tab dialogue that displays, and allows you to modify, in accordance with the requirements of your support organisation, functional attributes of the most fundamental kind relating to forms (including table browsers). Such attributes might dictate whether or not certain top-level tabbed sections or toolbar/menu functions are to appear on the type of form concerned, what tables are to be associated with that form type, and (in the case of a call form) how data from those tables should be assigned to achieve the required form and report functionality. As some of the Form Configuration attributes are major form elements that you build on when using the Form Designer, it invariably makes sense to define these first when creating a new form.

When you modify the Form Configuration attributes for a given form, you are actually configuring part of the template on which all forms of that type are based (for example, the forms named “Helpdesk Call”). All the attributes of that


20

template would be stored in the current data dictionary. It is possible to store any number of form templates in a given data dictionary.

If you wish, you can create multiple data dictionaries (as described in Creating New Data Dictionaries on page 11), each with a distinct form template (or set of form templates). You can allocate these data dictionaries to different kinds of analysts. If necessary, you can conveniently copy form templates between data dictionaries by means of the Copy Form To command, as described in Copying Call Form Types on page 110.

There are a number of Form Configuration tools available, each specific to a variety of form defined in Supportworks. Although all the Form Configuration tools are presented in broadly similar dialogue boxes, the individual attributes shown will differ from form to form, and certain tabs that appear in the configuration dialogue box for some varieties of form may not exist for others.

All of the attributes customisable via form configuration are described in the chapters of this guide that relate to forms and table browsers.

Accessing a Form Configuration Tool and Applying Changes

You access the required Form Configuration tool from within the Supportworks client. The procedure is as follows:

1. Ensure that you are switched to a data dictionary that contains a form (or table browser) of the type you wish to customise. An example of such a form type might be the Log Call form named “Helpdesk Call”.

2. Display an instance of that form in an appropriate way. For example, to display a “Helpdesk Call” type of Log Call form, simply initiate the logging of such a call.

3. On the displayed form, either select Configure this Form from the Tools menu, or click the corresponding button on the toolbar (if available). If both the menu bar and the toolbar are disabled, right-click anywhere in the title bar and select Configure this Form from the menu that appears.


21

Hint You can access certain kinds of Form Configuration tool from the Data Dictionary Editor as well. In the left-hand pane of the editor, first expand the relevant form category to reveal the various form types within it, and then double-click the required form type. Note that this only works for Log Call and Call Details forms.

The relevant Form Configuration dialogue box is displayed. In the case of the Log Call Form category, for example, this would be the Log Call Form Configuration dialogue box, as follows:

You can now make the required changes in each tab, as necessary.

To apply these changes, click the OK button. The dialogue box closes. If you then display a new form of the relevant type, you should immediately be able to see (or otherwise determine) the effects of your changes. Note that applying changes merely submits these to the current data dictionary in memory, and does


22

not save them to the server. To save the changes to the server, you must update the data dictionary as a whole by selecting Save Current Data Dictionary from the Administration menu on the main client window (or by clicking Save in the Data Dictionary Editor).

The Form DesignerThe Supportworks Form Designer allows you to modify the functionality and appearance of the layouts of existing or newly created forms (including table browsers) used in the client, in accordance with the requirements of your support organisation. The Form Designer employs a highly intuitive object-based user interface to facilitate the redesign of any form or form tab, complete with easy-to-use object-generation tools and drag-and-drop positioning.

A call form is made up of completely separate top-level tabs, not all of which are modifiable. A basic type of call form, such as the default Log Call form, might have just one modifiable tab (named “Details”, for example) and possibly one or more non-modifiable tabs. As the existence of each tab additional to the first modifiable one is determined by the form configuration, you will not be able to perform any design work in such an extra tab until you have enabled it using the relevant Form Configuration tool. When you run the Form Designer to work on a call form, you will be handling one top-level tab at a time. If you wish to modify or create the layout of multiple tabs, you will have to deal with these in separate Form Designer sessions.

In contrast to call forms, other kinds of form (including table browsers), are not composed of top-level tabs. Therefore, these can always be dealt with in a single Form Designer session.

When you work on a form or form tab in the Form Designer window, you are actually configuring part of the template on which all forms of that type are based (for example, the forms named “Helpdesk Call”). All the attributes of that template would be stored in the current data dictionary. It is possible to store any number of templates in a given data dictionary.

If you wish, you can create multiple data dictionaries (as described in Creating New Data Dictionaries on page 11), each with a distinct set of form templates. You can then allocate these data dictionaries to different kinds of analysts. Should it be necessary for certain kinds of analysts to use some of the same form


23

designs as other kinds of analysts, you can conveniently copy the relevant templates (which also include the associated form configurations) between data dictionaries by means of the Copy Form To command in the Tools menu of the forms concerned.

When customising a form using the Form Designer, you can generate (by means of a drag-and-drop mechanism) fields on the form that would be associated with columns from appropriate database tables, and you can position these fields anywhere on the form. Each field on a form, when first created, will inherit the default attributes that are defined for the associated table column in the Database section of the current data dictionary. So, for fields that appear on more than one form, a consistent input and display operation will be achieved. Thus, the textual content of a field’s label, for example, will be the same wherever the field appears, and if a column is designated as mandatory, this will be reflected in all fields associated with that column. If you wish, however, you can override the inherited attribute settings and values in any given form by simply reconfiguring them for that particular form within the Form Designer.

The configurability possible within the Form Designer is not limited to modification of the inherited attributes of fields, or to changing their positions on the form. When you select a field, a number of extra configurable attributes become visible along with the inherited ones. These include the field’s text properties, its visual properties and its dimensions.

Furthermore, you will find that objects on the form other than fields and labels have configurable attributes as well. Also, there will be attributes associated with the form as a whole. All of the attributes configurable via the Form Designer are described in the chapters of this guide that relate to forms and table browsers.

Starting the Form Designer and Applying Changes

You access the Form Designer from within the Supportworks client. The procedure is as follows:

1. Ensure that you are switched to a data dictionary that contains a form (or table browser) template of the type you wish to customise. An example of such a template might be the Log Call form named “Helpdesk Call”.


24

2. Display an instance of that form in an appropriate way. For example, to display a “Helpdesk Call” type of Log Call form, simply initiate the logging of such a call.

3. If the form has more than one customisable tab, ensure that the one you want to customise is being displayed.

4. On the displayed form, either select Design Form Layout from the Tools menu, or click the corresponding button on the toolbar (if available). If both the menu bar and the toolbar are disabled, right-click anywhere in the title bar and select Design Form Layout from the menu that appears.

The Form Designer window is displayed. In the case of the Details tab in the “Helpdesk Call” type of Log Call form, for example, the window might be as follows:

In this window, you are presented with the required tab-layout part of the template that relates to the type of form you have chosen. You are free to change


25

any of the form tab’s displayed attributes, using mainly mouse-drag operations for the layout, and text entry or item selection for the other aspects.

To apply any of your changes as you proceed with the form design, select Save from the File menu. In many cases, you should then be able to see the effects of these changes immediately on the actual form being displayed beneath the Form Designer window. In other cases, you may have to open a new form before you can see the effects.

Note that the Save function in the Form Designer only “saves” the changes to the current data dictionary in memory, and does not save them to the server. To save the changes to the server, you must update the data dictionary as a whole by selecting Save Current Data Dictionary from the Administration menu on the main client window.

The workspace of the Form Designer window is divided into various different areas. Each of these is described in separate parts of the following section.

The Form Designer Workspace

In the Form Designer window, there are three separate areas below the menu bar and toolbar that make up the workspace: the Layout area, the Object Inspector area and the Field Chooser area.

The Layout Area

This area on the left, occupying the bulk of the workspace, contains a copy of the actual form (or browser) from whose window you invoked the Form Designer. More specifically, in the case of a call form, the Layout area would contain a copy of the top-level form tab that you were displaying. The copy of the form includes the contents (if any) of the original form so as to let you see clearly the effects of certain kinds of changes you may make.

In the Layout area, you can select individual objects such as fields and labels by clicking on them. You can select multiple objects by holding down the Ctrl key while clicking on each additional object, or by clicking on an unselectable point and dragging the resulting “lassoo” over the objects concerned.

When you select a single object, its attributes and their current settings and values are displayed in the Object Inspector area. You can then modify any of


26

these settings or values, as described in The Object Inspector Area below. With regard to the actual layout, you can move the object to any point on the form by dragging with the mouse, or by means of the arrow keys. You can perform vertical and horizontal centring on the object by means of the appropriate toolbar buttons or menu commands. You can also resize the object by dragging any of the small square “handles” that appear when the object is selected, or by holding down the Shift key and pressing an arrow key.

When you have more than one object selected, all the attributes that they have in common will be displayed in the Object Inspector area. Additionally, you will still have available the entire range of positional and dimensional alignment functions, accessible via the toolbar and the menu bar. You will also be able to move the selected group of objects as a single entity to any position on the form.

If you wish to add new objects to the form, you can use the object-insertion buttons on the the toolbar, or the equivalent Insert menu commands. Alternatively, in the case of fields that have to be associated with database table columns, you can add these objects by means of the Field Chooser.

You can also generate copies of existing objects by using the standard Copy/Paste commands. With this functionality (and also with move functionality, for that matter), all aspects of an object are considered. Firstly, a name based on the source object will be generated for a copy (while the original name will be retained for an object moved to another location on the form). Secondly, any JavaScript events associated with an object will be copied/moved along with the object. Thirdly, when you copy a group of selected objects between which event-based JavaScript functionality exists, all the naming is done in a coordinated way, so as to keep the functionality intact.

It is possible to copy objects not only to other locations on the same form, but also to other forms.

You can delete objects on the form by selecting them (either individually or in groups) and then pressing the Delete key.

The Object Inspector Area

This area occupies the lower portion of the workspace’s right-hand pane. It contains a list of the attributes pertaining to the displayed form. Whenever you open the Form Designer, or whenever you click the form background (or any


27

empty part of the Layout area outside the form), the attributes displayed will be those relating to the form as a whole (or to the top-level form tab, if relevant)). As soon as you select an individual object on the form, the Object Inspector area will switch to display the attributes specific to that object.

You can view the attributes in either of two formats: categorised or uncategorised. In the categorised format, which is the initial default view, the attributes are grouped into categories and (for position and size attributes only) subcategories. You can selectively collapse or expand these as in a tree browser. In the uncategorised format, the attributes are simply listed in alphabetical order (except for position and size attributes, which are kept together). To switch between formats, use the pair of buttons located immediately above the attribute list.

In both formats, the attributes are listed in two columns, the left-hand one containing their names, and the right-hand one containing their respective settings and values. To change a setting or value, you have to use the method appropriate to that particular attribute. The method may be text entry, selection from a drop-down list, selection via a standard dialogue (as would be the case for a colour or a font), or multi-item selection via a specialist dialogue (for form flags and certain kinds of pick items). With some attributes, you have the option of using either drop-down list selection or text entry.

For an attribute value that is modifiable by text entry, a text cursor appears in the value field when you click in it, allowing you to edit its contents. For a setting you can modify by selection from a drop-down list, clicking in the field would result in the appearance of a drop-down list control, which, when clicked, would open a list of items you could then choose from. For a setting that is modifiable by selection via a dialogue, clicking in the field would cause a browse button to appear on the right-hand side of the field, which, when clicked, would open an appropriate dialogue box that would allow you to make the required selection.

Each object in a form can be identified by its name, as given by the value of the Object Name attribute. Specification of a name is optional, unless required by a JavaScript-based control. In a large or complex form, there may be quite a number of named objects and, if you are unable to find a specific one to click on, you can use the Form Designer’s selection-by-name facility instead. You would make your selection using the drop-down list in the field immediately beneath


28

the Object Inspector title bar. This method is particularly useful when you are trying to display the attributes of an object that is hidden by another object.

The Field Chooser Area

This area occupies the upper portion of the workspace’s right-hand pane. Its purpose is to allow you to conveniently create new labelled form fields that will be associated with selected table columns in the underlying database. You could create these also by using the insertion functions available on the toolbar and then entering the relevant data binding in the Object Inspector area, but use of the Field Chooser is much quicker. It also provides consistency of field labelling across different forms defined in the same data dictionary.

The field at the top of the Object Inspector area shows the table currently selected, and below that, there is a scrollable list of all the columns belonging to that table. The name of each column, as it appears on the list, is determined by the Display Name value for that column in the Database section of the data dictionary.

To create a new field on the form, together with its label, you first have to select (using the drop-down list) the table that contains the column you wish to associate with the intended field. You then look for the relevant column on the scrollable list, and when found, drag it to the required point on the form.

You will then have created two objects: a data field and a label for that field, with the text of the label reflecting exactly the associated column’s display name. Both objects would be bound to the selected table column, and will have inherited the column’s basic database schema settings. You should be able to see the data binding in the Data section of the Object Inspector.

Note In order to be able to select tables in the Field Chooser (or enter valid data bindings in the Object Inspector), those tables must exist and must already have been defined in the Associated Tables tab of the relevant Form Configuration tool. Also, for correct functionality, any data assignments that have to apply should have been stated in the same tab. See the appropriate sections in the form-related chapters of this guide for more information.

You can use the same drag-and-drop method to bind an existing, unbound field or label to a table column, or to change the binding of a previously bound field


29

or label. As you drag a column from the Field Chooser over the form, the border of any field or label that is capable of being bound is highlighted in red. If you release the mouse button over such an object, it will immediately be bound to the column concerned. Releasing the button anywhere else on the form would simply create a new, appropriately bound object, as mentioned above.

Note that label objects are of two types: one that can be bound to columns, and one that cannot. A label of either type will be highlighted in red when you drag a column from the Field Chooser over it. However, only a label object of the bindable type will be re-bound when you release the mouse button. With the non-bindable type, what will simply happen is that the label’s text will be overwritten by the dragged table column’s display name.

Managing the Form Designer Workspace

Various functions exist in the Form Designer that allow you to control visual and operational aspects of its workspace.

Show/Hide Controls

It is possible to show or hide any of the following elements in the Form Designer window:

• The Object Inspector area

• The Field Chooser area

• The object-insertion buttons on the toolbar

• The layout buttons on the toolbar

• The status bar at the bottom of the window

To show or hide any of these, right-click anywhere in the toolbar area and make the appropriate selection from the menu displayed.

Resizing Controls

You can expand the Object Inspector or Field Chooser area within the right-hand pane to its maximum size by clicking the small upward-pointing triangular symbol situated at the top right-hand corner of the area concerned. When you do that, the other area in the right-hand pane contracts to its minimum size, leaving only its title bar visible. You will notice that the expanded area’s triangular


30

control is now downward-pointing, and if you then click it, the area reverts to its normal size.

You can change the relative sizes of the two areas in a more controllable way by dragging the dividing line between them up or down to the exact position you want.

By similar use of the mouse, you can shift the boundaries of any other elements, although, in such cases, overlapping may occur due to boundaries being separate and independent.

Docking/Floating Controls

If you wish to move the Object Inspector or Field Chooser area to a different docked position within the workspace, or to a floating position outside the workspace, you can do so by dragging it by its title bar to that position.

Functions Available for the Layout Area

Various types of functions, accessible via toolbar buttons and menu commands, are available for use in the Layout area.

Automatic Positioning and Sizing Functions

Most of these functions are designed for the purpose of “tidying up” the form design, to achieve spatial consistency across multiple objects. Other functions allow you to reverse the arrangement of objects, and also to achieve accurate object centring. Except where stated, the functions are meaningful only if more than one object is selected.

Align Left/Right/Top/Bottom When you execute any of these functions, all the selected objects become aligned to the relevant edge of the first object you selected.

Centre in Window Vertically/Horizontally When you execute either of these functions, the selected objects are positioned, along the relevant dimension, to the exact centre of the form. These functions will operate on a single object as well.


31

Space Evenly Across/Down When you execute either of these functions, all the selected objects are arranged evenly relative to each other along the relevant dimension, with the two furthermost ones remaining where they are.

Make Same Width/Height/Both When you execute any of these functions, all the selected objects acquire the same size as the first object you selected, along the relevant dimension(s).

Flip Horizontally/Vertically When you execute either of these functions, both the order and the relative spacings of all the selected objects become reversed along the relevant dimension. Note that these functions do not produce mirror images of the individual objects themselves.

Insertion Functions

These functions allow you to create new objects on the form. When you execute a typical insertion function, you are switched to an edit mode in which the mouse pointer turns into a crosshair. You would then move the crosshair to the position where you want the relevant object to appear, and click and drag to achieve the required object size. If you wish to create multiple objects of the same type, there is no need to execute the insertion function for each of them: all you have to do is execute it once and then hold down the Ctrl key while you click and drag the required number of times. In this case, the edit mode will persist until you press Esc or the right mouse button, or place an object without Ctrl.

Some objects, such as tab controls and SQL lists, can have subsidiary objects inserted into them (or come with such objects built in). As these subsidiary objects do not need to be precisely positioned or sized within the main object, no further action is required after selecting the insertion function. Note that, in order to select an existing subsidiary object, you first have to deselect (if currently selected) the main object in which it resides.

Insert Label This creates a general-purpose text label that you can use, for example, to indicate the name of a field or the title of a section. Note that you will not be able to bind such a label to a table column. (Contrast this with the kind of label created, along with its associated field, by dragging from the Field Chooser.)


32

Insert Field This creates a standard field that is designed to be associated with a specific table column. The association would be specified by the field’s Data Binding attribute value (which would be an expression in SQL notation). Any full or partial data that users enter into such a field would be used to match against the table column given by the Data Binding value. When the record is resolved, all fields (including this one) that are associated with columns in the same table would be auto-populated.

Insert Formula Field This creates a read-only field that will display data relating to one or more table columns, which would be specified by the field’s Data Binding attribute value. The relevant record from which the data would be taken will have been resolved from data entered elsewhere on the form.

Insert Dual Search Field This creates a field that will accept entered data, which would then be used to match against the two table columns given by its Data Binding attribute value. The results of resolving a record would be displayed in the same way as for a standard field.

Insert Tab Control This creates a tabbed area at the design level, consisting (initially) of three separate tabs. You should not confuse this type of tabbed area with the more permanent, top-level tabbing used in call forms.

Insert Tab Item This function is available when you select a tab control or right-click one. It creates a new tab within the tabbed area. You can have up to 128 tab items in a tab control.

Insert Command Button This creates a button whose function is determined by the underlying JavaScript code. On a call form, it can alternatively be determined by the specific Show Me menu command to which you can map it. This mapping is done by simply typing the name of the relevant Show Me command into the button’s Object Name attribute field.

Insert Menu Button This creates a button whose function is to display a customisable menu of commands defined in the underlying JavaScript code. On a call form, the command names can map to those in the Show Me menu. You create the menu items by specifying them in the button’s Commands attribute field. See the subsection entitled Data on page 75 for details.

Insert Ellipse This creates an elliptical or circular shape.

Insert Line This creates a horizontal or vertical line.


33

Insert Rectangle This creates a rectangular or square shape.

Insert Single-Set Chart This creates a “snapshot” chart of statistical data obtained from the Supportworks database by a single SQL query. The query to be used is chosen from those predefined in the drop-down list belonging to the object’s Chart Query attribute.

Insert Multi-Set Chart This creates a “snapshot” chart of statistical data obtained from the Supportworks database by multiple SQL queries. The queries to be used are chosen by means of the query-selection dialogue box that is displayed when you click the browse button belonging to the object’s Chart Query attribute.

Insert Simple Table This is reserved for future use.

Insert File List This creates a scrollable list of the files located in a specified shared folder on your network. If a user subsequently double-clicks one of these files as presented on the form, the file will run (if executable) or will open (in the case of a document or graphic). A file list is always created with three default columns, provisionally named File, Size and Last Modified, any of which you can make invisible. You can also hide the file list’s header if you wish. You can change the width of a column by dragging its header section’s separator lines.

Insert SQL List This creates a scrollable list of the records held in a specified table in the Supportworks database. You can specify which of the table’s columns are to be shown on the list (see below), and you can filter the records if necessary. If a user subsequently double-clicks one of these listed records, the relevant Properties form opens, allowing the record to be scrutinised in full or perhaps updated. Note that this will work only if you have specified a suitable type of form to display by selecting it in the Edit Record Form attribute field.

Insert SQL List Column This function is available when you select an SQL list object or right-click one. It adds a new column to the record list from the underlying database table. Note that you will not be able to select the source column (or set any of the other column attributes) until you have set the Show Header attribute of the table object itself to True. You can change the width of the displayed column by dragging its header section’s separator lines.

Insert Image This creates a place-holder into which you can insert a bit-mapped graphic by specifying a suitable name or URL as the value for the object’s Image attribute.


34

Insert URL Link This creates a place-holder in which you can include a textual hyperlink to any Web page. If a user subsequently clicks such a link on the form, their Web browser is opened displaying the page concerned.

Insert Caption Panel This creates either a caption bar on its own, or a caption bar with the addition of a freely resizable bordered area below it. The caption bar is the equivalent of a rectangle, a label and an image combined. In the case of the composite panel, the bordered area can be populated with any number of other objects (including other caption panels). To create a caption bar only, just left-click the mouse after selecting the insertion function. To create a composite panel, left-click and drag to the rectangular size you want, ensuring that the height is greater than 23 pixels. Note that, for a caption bar, all four corners are rounded by default whereas, for a composite panel, only the top two corners are rounded. If you have created a caption bar, you will find that it changes into a composite panel if you drag its bottom edge down far enough (and the reverse is also true).

Duplication Functions

As well as being able to use the standard Copy and Paste functions for making manually positioned copies of a form object, you can employ the Duplicate Objects facility (also available from the Edit menu) to create a duplicate of a selected object or group of objects a short, fixed vertical or horizontal distance away from the original in either direction. All new objects created in this way will be allocated unique names based on those of the original objects.

Unlike the Paste function, a Duplicate Objects function will set the position of the created object within the tab order intelligently, based on the tab position of the original. The tab position of the new object will precede that of the original if you have duplicated Up or Left, or will follow that of the original if you have duplicated Down or Right.

Any JavaScript code associated with the object being duplicated will also be duplicated and, equally, any references to that object from other JavaScript code will be updated to give the newly allocated object name.

Stacking Functions

In any form you may be designing, there are likely to be places where two or more objects overlap each other, or where certain objects completely cover


35

others. You can control such stacking by bringing objects to the front or sending them to the back of the other objects.

To place an object into either the front or back stacking position, first select the object concerned and then select Bring to Front or Send to Back from either the Layout menu or the menu that appears when you right-click the object.

Grid Functions

The Form Designer provides you with a dotted background grid to facilitate the positioning and aligning of objects on the form. If enabled, it will only be visible in the Form Designer, and will never appear in the generated form itself.

There are three functions available that relate to the grid. You can change all of them via the dialogue box that opens when you select Grid > Settings from the Layout menu. You can also change the first two more directly by selecting Layout > Grid and then the function. The three functions are as follows:

Show/Hide Grid This switches the grid on and off in a visual sense. It does not affect snap functionality.

Snap to Grid When enabled, this allows you to place objects only into positions defined by the grid. When you release the mouse button after dragging an object, the object snaps into place following the handle in the top left-hand corner of its selection box, which is “attracted” to the midpoint of the nearest group of four adjacent grid dots. The Snap to Grid function will work irrespective of whether the grid is visible or not.

Grid Size This allows you to select the snap resolution of the grid in terms of the size, in pixels, of the space between the dots (whether the grid is visible or not). The default is 10 pixels.

Tab Order

A user in the process of completing a form may wish to move the cursor from one field to the next by means of the Tab key, rather than with the mouse. It is therefore important, when designing a form, to take into consideration the order in which the cursor should move through the fields.

You can view the currently set tab order by selecting Tab Order from the Layout menu. You should then see a highlighted number displayed against each data


36

field, starting with 1 for the first field in the sequence, 2 for the second, and so on. If you are not satisfied with the given tab order, you can change it while the form is in this mode. First decide on the order you want, and then click your way through the fields in that order. The first field you click after switching to the Tab Order mode will be numbered 1, and the number of each successive field you click after that will increment by one every time. If you make a mistake at any point, you can exit from this mode and then re-enter it by selecting Tab Order twice. You will then be able to start the ordering process again from the beginning.

Object Search

You can use the Form Designer’s object-search facility to locate an object that you are unable to find visually.

To access the search facility, select Find Object from the Edit menu (or click the Find Object toolbar button). At the prompt that is then displayed, enter the name of the object you wish to search for and click OK. The system highlights the object when found, thus displaying its attributes.

Note that this method has been superseded by the much quicker selection-by-name facility available in the Object Inspector (as described in The Object Inspector Area on page 26).

Object Conversion

When you select one or more objects on the form and then press and hold the Ctrl key while selecting a form object from the toolbar or the Insert menu, each of the objects you had selected on the form is replaced with one of the type you just selected from the toolbar or menu. The tab order applying to the original objects will have been maintained, as will the Resize/Scaling attributes.

Repositioning Ordered ItemsCertain groups of command items in the client that are displayable in a certain order are customisable using the data-dictionary interfaces. These include items such as those found in customer and asset tree browsers (represented under SQL Tree Browsers in the Data Dictionary Editor), the shortcut icons relating to


37

workspace views in the main client window (represented under Global Parameters/Views and also under Database Entity Views in the Data Dictionary Editor), the “Show Me” menu items in call forms (represented in the form configuration), and the pick items found in the drop-down lists belonging to form fields (represented in the Form Designer).

Part of the customisation capability for such items consists of a mechanism that allows you to change their precise ordering by repositioning their representations in the relevant data-dictionary interface. To reposition an item, highlight the item on the relevant list and click the Move Up or Move Down button, as appropriate. The item is shifted up or down by one position within the group. You can repeat this operation as many times as necessary with any of the items.

In the Global Parameters section of the Data Dictionary Editor specifically, you can change the order of parameters and their values, as listed in the right-hand pane, by using drag-and-drop. This is really only useful for user-selectable filters associated with call lists in Helpdesk-type views, where the viewed order in the filter-selection drop-down list is determined by the order of the parameter/value items as displayed in the Filters folder.

Your re-ordering changes will come into effect within the client once you have applied the changes (or, in the case of the shortcut icons, once you have saved the changes and closed the editor).

Customisable AttributesIn the following chapters, you are given detailed descriptions of all the customisable attributes that relate to the various data-dictionary categories.

The initial chapter starts off with an overview of the Supportworks database, and goes on to describe the main database attributes that can be seen from the Data Dictionary Editor. Almost all of the attributes featured here are those of the underlying database, or those that are used internally by the system. As these are non-customisable except via a database manager, this section of the editor is provided mainly for viewing purposes. The chapter finally covers the creation and integration of new tables.


38

The subsequent chapters deal mainly with the attributes of forms and browsers, and also give instructions on how to create new form types and how to copy form types between data dictionaries. Form attributes can be divided roughly into three types:

• Those relating to the form’s basic functionality and appearance, such as the specification of associated tables, of certain menu-based command functions and perhaps of top-level tabs, together with their configuration where relevant

• Those relating to the overall visual characteristics of the form (or of each top-level tab of the form)

• Those relating to the visual and functional characteristics of the individual objects that make up each form

Attributes of the first type are customised using a Form Configuration tool, whereas those of the second and third types are customised using the Form Designer. New call form types are created using the Data Dictionary Editor, whereas new standard form types are created via the Form wizard. Form types are copied from one data dictionary to another from the individual forms themselves.

In each of the form-related chapters that follow, attributes of all three types are discussed in detail for the form category concerned.

The Supportworks Database

39


Supportworks creates and uses a number of SQL database tables whose purpose is to hold call-related, and other, data. The selectable database platform for maintaining these tables may be the Supportworks SQL Server provided in the Hornbill Core Services installation, or it may be a combination of that and some other compatible database system that your organisation has chosen. In the case of a combination system, the tables reserved for internal (cache) working would remain under the control of the Supportworks SQL Server, while all the rest (used for external working) would belong to the chosen platform. Irrespective of the database system selected for external working, Supportworks will connect to that system using ODBC. With a relational database-management system (RDBMS), the Supportworks server acts as a client to the database server.

All relationships between tables are handled by Supportworks, and, in the case of relational databases, there is no dependency on the underlying management system to enforce these relationships. This ensures maximum compatibility between all the database platforms that Supportworks supports.

Each Supportworks product comes with a unique database configuration whose specification is itself held in a database. When the Supportworks server is installed or upgraded, it builds or suitably modifies the database tables according to that specification using a dynamic SQL process. It places the tables belonging to the Supportworks SQL Server in various sub-folders under C:\Program Files \Hornbill \Core Services \SwSqlServer \data on the computer running that server, where each sub-folder would constitute a separate database within the system. The names of all the databases located in the above folder would always correspond to the respective sub-folder names. Those tables, managed by the Supportworks SQL Server, that are suitable for user customisation are stored in the sub-folder swdata, which would therefore be recognised as the database called swdata. Note that this sub-folder would be absent in a combination system, as the corresponding database would then be stored in a manner, and in a location, determined by the chosen platform.

The sub-folder sw_systemdb in the \data location is an internal cache database that is used to boost performance on searches. The cache database holds exact copies of those tables in the customisable database that store data relating


40

directly or indirectly to currently open calls, and it also holds copies of the currently existing data dictionaries. For extra speed, the Supportworks server connects to the cache database directly rather than via ODBC.

Other tables used internally by the system are held in the remaining sub-folders at the above location.

Internally, Supportworks uses only three data formats:

• Numeric (corresponding to “integer” in SQL terms)

• Alphanumeric (corresponding to “varchar” in SQL terms)

• Long alphanumeric (corresponding to “longvarchar” in SQL terms)

Ideally, the database system should use the corresponding SQL data types indicated in parentheses above. However, even if it uses data types other than these, any relevant data passing between the database and Supportworks will be reformatted to “fit”. For example, numerical data coming from a table column defined as “float” will be rounded to an integer. Implementation in this manner again ensures maximum compatibility between RDBMS systems.

The contents of date/time columns (fields) are always stored as alphanumeric text, in the format dd/mm/yyyy hh:mm:ss. To optimise the performance of searches based on certain kinds of date/time, a number of tables store such content as numeric epoch values as well. The epoch value would be the number of seconds that have elapsed since January 1, 1970.

The indexing and column sizing defined by default (or by our consultants according to your requirements) in the Supportworks installation for the database tables should be suitable, in the first instance, in most cases. However, if your initial requirements should subsequently change (and you do not have a Supportworks Essentials system), you are free to modify the database specification and execute the changes on the actual database system itself. Not only will you be able to edit the existing customisable tables, but you will also be able to create completely new tables and incorporate them into Supportworks.

The tool you would use for such “foundation-level” customisation is the Supportworks Database Schema Editor, in conjunction with the Database Configuration Tool. These stand-alone utilities are described in the Hornbill Core Services Guide.


41

You can view the existing database schema by means of the Data Dictionary Editor, which additionally allows you to modify a limited number of attributes that are not actually part of the underlying schema and whose values and settings can change from one data dictionary to another.

As a further aid to your customisation efforts, we have provided descriptive information on the columns of all tables you may wish to modify. See Appendix A: Default Customisable Table Specifications on page 357, and also the Solution Specification document relating to your own particular system. For customisation purposes, you should ignore any tables you see listed in the Database Schema Editor or the Data Dictionary Editor that are not described in the documentation.

Attributes Viewable in the Data Dictionary EditorThe Data Dictionary Editor allows you to examine the underlying database schema, together with some other basic attributes, at both table and column level. The underlying schema attributes are read-only as they are not data-dictionary-specific, but most of the others are customisable and can have different values in different data dictionaries. For example, at table level, you can specify a default form to use for creating new records in the table, and for updating existing records in it. At column level, you can, in all cases, specify the display name for the column as it would appear in the Field Chooser area of the Form Designer.

Table-Level Attributes

The Database section is the first item displayed in the left-hand pane of the Data Dictionary Editor. If you expand this item, you should be able to see the names of all the tables used by Supportworks (and also Assetworks, formerly known as PC Audit). If you then select one of the tables, its attributes would immediately appear in the right-hand pane, as follows:


42

The greyed-out settings are part of the underlying database schema (or are used by the system purely for internal purposes), so you cannot modify them. However, the remaining attributes, described below, are available for customisation.

Display Name For a table whose structure is described in the Appendix, this is the alternative, more user-friendly, name by which the table is known. For any other table, it would (by default) be a copy of the more cryptic Table Name, and you may wish to change it to a similarly user-friendly alternative. Currently, the Display Name (if different to the Table Name) is used only in the System Privileges tab of the Support Analyst Properties dialogue box.

Add Record Form This identifies a customisable standard form by which you can create new records in the table. The form specified here is a system-wide default that applies initially to all situations where a record-creation function is available (except when the function is selected explicitly from the File menu). The choice of forms available to you in the drop-down list would be those, defined under the Forms category of the data dictionary, that are associated with this table. Thus, for example, the entry Form.TfCustomer would refer to the form type named “TfCustomer”, which (unless overriden by a more specific setting) would in fact be displayed in the client as the Add New (Customer


43

Details) form whenever an analyst has responded positively to a Quick-Add prompt, for instance. By the default convention, the prefix “Tf” indicates a standard form made up of tabbed sections at the design level, whereas “Ef” would indicate a standard form with no design-level tabs.

Edit Record Form This identifies a customisable standard form by which you can modify existing records in the table. The form specified here is a system-wide default that applies initially to all situations where a record-update function is available. It would normally be the same as the record-creation form (as specified in Add Record Form above), unless you have a specific requirement for the two forms to be differentiated. The choice of forms available to you in the drop-down list would be those, defined under the Forms category of the data dictionary, that are associated with this table. For example, the entry Form.TfCustomer would refer to the form type named “TfCustomer”, which (unless overriden by a more specific setting) would be displayed in the client as the Customer Properties (Customer Details) form whenever an analyst has, for instance, double-clicked a customer-search result. By the default convention, the prefix “Tf” indicates a standard form made up of tabbed sections at the design level, whereas “Ef” would indicate a standard form with no design-level tabs.

Description In this attribute field, you can enter your own notes concerning the table. This text will not be displayed anywhere on the client except here in the Data Dictionary Editor.

Column-Level Attributes

If, in the left-hand pane of the Data Dictionary Editor, you expand a table item under the Database category, you should be able to see the names of all the columns in that table. If you then select one of the columns, its attributes would appear in the right-hand pane, as follows:


44

The greyed-out settings and values shown here form the column-related aspects of the underlying database schema (or are used by the system purely for internal purposes), so you cannot modify them on a per-data-dictionary basis. The remaining attribute settings and values, however, are actually modifiable, and the majority of these can provide initial defaults for the equivalent attributes of column-bound form fields that you can, if necessary, more specifically modify in the Form Designer. In other words, for any given table column in the database, the settings and values of nearly all of its modifiable attributes apply initially to any field, on any form, to which the column may be bound, but these can subsequently be overridden by each field instance’s own attribute settings and values. As we shall see in later chapters, a form field is said to be “bound” to a table column when it is designed to reference that column for displaying and/or entering record data.

If you want a given attribute of every instance of a proposed form field to remain the same on all forms, you simply specify the attribute’s required value against the table column, and you can then create each individual field from that column, binding the field to the column in the process. The value you specified for the column attribute would be inherited by the corresponding field attribute. An example would be the Input Mask attribute of the callref column in the


45

opencall table, which defines the format of the call reference. This format has to be identical in all places where a call reference is displayable or specifiable. Another example would be the more general requirement that a field label such as “SLA” be displayed exactly as that (rather than as “Priority” or “Level”, for example). This kind of consistency would be an important consideration with regard to usability when you are designing a form.

However, it is not necessary to stick with the inherited default for any given attribute. Rather, you may need to define attributes, using the Form Designer, purely on the basis of individual form-field instances. This would be particularly appropriate when the terminology (or the language) used is different on every form.

The attributes that you define against table columns generally have similar names and exactly the same meanings as those of the respective attributes you define against instances of the form fields to which the columns are bound. They are described in the subsection Object-Level Attributes on page 73, in the Log Call Forms chapter of this Guide. Nearly all of them are to be found in the Field-Specific Properties (and also Label-Specific Properties) subsection below that.

For most of the attributes, values are inherited from the database on a purely temporary basis, and are not maintained subsequent to field creation if you change the “parent” value. However, the situation is different with attributes such as Pick Items (associated with Pick List controls). With these, you have to explicitly indicate whether the value to be used for a given form field should be the one set in the Data Dictionary Editor or the one set in the Form Designer. You indicate this, in the Form Designer, by setting that field’s Use Data Dictionary Pick List attribute to True (for the Editor) or False (for the Designer).

The following column attributes also need a special mention:

Display Name This is the user-friendly name by which the column would be identified in the Field Chooser area of the Form Designer. It would also provide the text for the bound field’s label if this is created by dragging from the Field Chooser.

Control Type This is the equivalent of Field Mode for a form field instance. The possible options in this drop-down list control constitute a sub-set of those available for Field Mode. In a similar fashion to Field Mode, different options


46

selected for Control Type will give rise to different sets of options being displayed below that attribute.

Control Options These are a set of individual attributes that are grouped together purely because they have simple on/off settings. Note that the attribute Auto-Update on Select is now obsolete and has no effect at all.

Creating and Integrating New TablesYou can create any number of additional tables to form part of the swdata database, and can then integrate these (on a per-data-dictionary basis) into the functionality of Supportworks itself. To achieve this, you will need to employ various facilities provided by both Windows and the Supportworks installation. The main stages of the recommended procedure (for a new managed table similar in function to the Customer table) are as follows:

(a) Preparation, including a backup of your system

(b) Creation of the required table and its index, and (if needed for reporting purposes) creation of any extra columns in the Open/Closed Call table to hold, in call records, data acquired from the new table

(c) Creation of a standard form to be used for adding records to the new table, and one (if not the same) to be used for viewing and updating existing records

(d) Setting up of the table schema basics, specifying the required initial and system-wide defaults for certain attributes of the new table

(e) Creation of the required types of browser and search displays to be used for finding records in the new table

(f) Creation of Manage commands in the main client window’s File menu, to be used for displaying the new record-creation form and browser window

(g) Creation of a pick-list window to be used for selecting a required record from the new table during any attempt to populate a call form with data from that record

(h) Integration of the new table into any call forms that may require access to it, allowing (a) fields in call forms to be bound to columns in the new table, (b)


47

form fields and call records to be populated with data acquired from the new table, and (c) records to be created in the table using call-form-specific standard forms

(i) Creation, in call forms, of new fields bound to columns in the new table, or, if the table is a direct replacement of an existing table, appropriate modification of the existing bindings

See the next subsection for the relevant instructions in detail.

The Table Creation and Integration Procedure in Detail

The detailed procedure for creating a new table and incorporating it into a given Supportworks data dictionary is as follows:

Stage (a): Preparation

1. Ensure that all Supportworks clients are logged off.

2. On the computer where the Supportworks server is installed, run the Server Configuration program by selecting Start > Programs > Supportworks > Supportworks Server Configuration.

3. In the Server tab under Installed Services, stop all the services one by one, starting from the top.

4. In Explorer, find the root folder in which the Supportworks server is installed (C:\Program Files \Hornbill \Supportworks Server\ by default). Copy this folder and all of its contents to a backup location.

Stage (b): Creating the New Table and Creating Extra Columns in the Open/Closed Call Table

5. On the computer where the Supportworks server is installed, run the Database Schema Editor by selecting Start > Programs > Supportworks > Supportworks Database Schema Editor. (For a full description of this editor, see the Hornbill Core Services Guide.)

6. Using the Database Schema Editor, give a specification of the table you require, including definitions of its columns and indexes. Note that it is up to you to decide which columns (if any) are to be indexed in the proposed table.


48

For a single-column index, it is common for the index name to be the same as the corresponding column name.

7. In the Database Schema Editor, invoke the Apply Specification to Database function from the Database menu and select SwServerService as the application that is to primarily own the proposed table. Also select the database (normally swdata) to which the table is to belong. Then click Apply, whereupon the new table is built within the database according to your specification.

8. Using the Server Configuration program, restart all the services. Your new table will then be available from within Supportworks, and will therefore be visible in the Data Dictionary Editor.

9. Ensure that you are switched to the first (or only) data dictionary into which you wish to integrate the new table.

Stage (c): Creating Standard Forms

10. Using the appropriate client facilities described in Creating and Integrating New Standard Form Types on page 133, generate and customise a standard form suitable for creating new records in the table you have just created, and another form for viewing and updating existing records. If you wish, you can create just one form for carrying out both functions.

Stage (d): Setting Up the Table Schema Basics

11. Run an instance of the Supportworks client, and launch the Data Dictionary Editor by selecting Edit Current Data Dictionary from the Administration menu.

12. In the left-hand pane of the Data Dictionary Editor, expand the Database section and highlight the name of the table you have just created.

13. In the right-hand pane of the Data Dictionary Editor, enter values for the following attributes, as described in Attributes Viewable in the Data Dictionary Editor on page 41:

• Display Name (overwriting the default with a suitable user-friendly one)

• Add Record Form

• Edit Record Form


49

14. Back in the left-hand pane, expand the table item to reveal the table’s columns and, for each column in turn, decide on a suitable user-friendly name and enter this in its Display Name field (overwriting the default).

15. Click Save, and then close the Data Dictionary Editor.

Stage (e): Creating Browser and Search Displays

16. Decide on what types of browser and search displays will be required for locating records in the table you have just created. For windowed displays, you can opt for either a table browser with a list-based browsing facility, or an SQL tree browser form with search fields and/or an embedded tree browser. For an integrated display, you can create a completely new database entity view with the usual search and browse modes (containing search fields and a tree browser, respectively). The new view, as all existing views, would be selectable from the shortcut bar, and would be used to search and browse for records in the new table and to display the chosen one within the view itself.

When choosing between a table browser and an SQL tree browser form, the simpler option would be the table browser, which is appropriate when the number of records to be listed is fairly small. A typical example of this is the default Charge Centre browser. An SQL tree browser form, on the other hand, would be the better option when the potential number of records is large, not only because it is faster, but also because you can include a field-based search facility in it. The default Customer browser is a good example of an SQL tree browser form. Note that a database entity view can incorporate a tree browser, but not a table browser.

17. If tree-based browsing facilities are required for the new table, proceed to generate and customise an SQL tree browser, as described in To Create a New SQL Tree Browser on page 165. Such a browser can be displayed by an SQL tree browser form or a database entity view once these have been created (see below).

18. If tree-based browsing, and/or field-based searching, facilities are required for the new table, displayable in a separate window, proceed to generate and customise an SQL tree browser form. See To Create a New SQL Tree Browser Form on page 159 for details. Such a form can be invoked by the


50

relevant Manage command, or by an appropriate Show Me command on a call form, once these entities have been created (see below).

19. If tree-based browsing, and field-based searching, facilities are required for the new table, displayable in the main client window, proceed to create a suitable database entity view. See Creating New Database Entity Views on page 207 for details.

20. If list-based browsing facilities are required for the new table, displayable in a separate window, proceed to generate and customise a table browser. See To Create a New Table Browser on page 149 for details. Such a browser can be invoked by the relevant Manage command once this entity has been created (see below).

Stage (f): Creating “Manage” Commands

21. Using the appropriate Data Dictionary Editor facilities described in Creating New “Manage” Commands on page 175, generate and customise a Manage command hierarchy suitable for invoking the record-creation form and the table browser or SQL tree browser form you have just created.

Stage (g): Creating a Pick-List Window

22. Using the appropriate Data Dictionary Editor facilities described in To Create a New Pick List on page 170, generate and customise a pick-list window suitable for selecting a record from the new table for the purpose of populating a call form, either when ambiguous data has been entered on the form or when an appropriate Show Me command has been selected.

Stage (h): Integrating the New Table into Call Forms

23. Using the appropriate Form Configuration facilities described in Attributes in the Associated Tables Tab for Log Call Forms on page 58, and (if relevant) in Attributes In the Associated Tables Tab for Call Details Forms on page 118, add the new table as a Related Table to the pick-list in the Associated Tables tab for the first (or only) call form that requires an association with this table.

24. With the Related Table highlighted in the list, suitably configure the table properties so that the pick-list window and record-creation form you have


51

created will be displayed as and when necessary. The latter is required only if the system-wide default form needs to be overriden by one that is specific to the call form being configured.

25. In the Data Assignments to Table(s) area, add a new entry for each column of the new table that is expected to provide call records with data for reporting purposes.

26. In the ‘Show Me’ Items tab for the call form being configured, check to see whether there are any existing Show Me menu commands that will now be required to display the pick-list window or SQL tree browser form you have created. Also (or alternatively), you may need to add completely new Show Me commands that will be expected to invoke this window or form. In either case, you must suitably configure the menu item properties so that the correct window or browser form will be displayed.

27. Repeat the above steps in this stage for each additional call form into which you wish to integrate the new table.

Stage (i): Creating New Field Bindings in Call Forms

28. If you are directly replacing an existing table with the one you have just created, you need to change, using the Form Designer, the bindings of all relevant fields on each affected call form so that they now point to columns in the new table, rather than to columns in the old table. For each form field (and its label) currently bound to the old table, you would merely have to edit its Data Binding attribute, overtyping the existing table name with the new table name. See the subsection entitled Object-Level Attributes on page 73 for detailed information about this attribute.

29. If the table you have created is an addition to the existing set of tables (rather than a replacement for one of them), you will have to create extra fields for displaying resolved data from that table on each call form where the table is configured as a Related Table, and then bind these fields to the required columns in the table. See Object-Level Attributes on page 73 for information about data binding, and The Field Chooser Area on page 28 for details of how to create labelled fields on a call form.

Repeat the above procedure from Stage (c) onwards for each additional data dictionary into which you wish to integrate the table you have created.


52

Log Call Forms

53

Log Call Forms

A Log Call form is a dialogue box that analysts are presented with when they have elected to log a call against a customer or some other administrative entity. By means of the Log Call Form Configuration tool and/or the Form Designer, you can modify any of the major visual or operational attributes of such a form. For example, you can:

• Specify which optional top-level tabs (including their underlying functions) are to exist in the Log Call form type concerned, which call-submission commands are to be enabled, whether or not the information bar at the bottom of the form is to be available, and whether or not the e-mail “Received” date is to be treated as the call-log date (where a call is logged via e-mail)

• If the Workflow tab is enabled, specify the workflow template that is to be preloaded into all instances of the Log Call form type concerned

• Configure the relevant details of a custom HTML tab (if enabled), which would display within it a Web page of your choice, perhaps one that is relevant to the call, customer or asset concerned

• Specify the call class (see below) for the Log Call form type concerned

• Configure a filter for the Choose Profile dialogue invoked from the Log Call form type concerned

• Specify the tables with which the relevant Log Call form type is to be associated, and configure certain aspects of these that relate to the functionality of the form

• Specify which database functions and reports are to be selectable from the Show Me menu in the Log Call form type concerned, and configure the behaviour and menu position of each of them

• Specify, for each customisable top-level tab, its dimensions, its default colour scheme and its default font characteristics, and also set the attributes of each individual object on each tab

• Reposition objects on the form, and create new objects

Log Call Forms

54

You would perform the actions described in all of the above points except the last two by means of the Log Call Form Configuration tool, and you would perform those described in the last two points by means of the Form Designer.

It is not necessary (or, indeed, advisable) to use the Data Dictionary Editor for Log Call form customisation, even though an appropriate Log Call Forms category is viewable from within it. However, the editor is needed for actually creating new form types and deleting unwanted ones.

Attributes Handled in the Log Call Form ConfigurationThe attributes available for customisation using the Log Call Form Configuration tool would relate to a given Log Call form type, and would apply to the form dialogue box as a whole. For a newly created Log Call form, the initial default settings of these attributes would be determined by the call class to which the form was assigned.

The attributes are divided into three sections, which are displayed in the dialogue box as three separate tabs: Settings, Associated Tables and ‘Show Me’ Items.

Log Call Forms

55

Attributes In the Settings Tab for Log Call Forms

In this tab, you can see the following attributes:

Form Name This is the name given to the selected Log Call form type. It is used for reference, both within the Data Dictionary Editor, and in the selection list, presented to analysts when requesting a call log, that allows them to choose the required form.

Call Class This specifies the class of the calls to be logged using this form. The class will have been assigned to this form when the form was created. See Call and Form Types and Call Classes on page 101 for information on how you make use of, and manage, call classes. You would not normally switch to a different call class here, but if you do, you have to be aware that its table-association attributes will not be applied to the form automatically.

Form Title This specifies the title of the form, as displayed in the title bar of its window.

Log Call Forms

56

Profile Filter In this field, you can enter, for example, an SQL expression specifying the problem profiles that are (or are not) to be available for selection in the Choose Profile dialogue box, which is displayed when an analyst clicks in the problem-profile field on the Log Call form. Thus, entry of code != ‘hrdw’ (where code is the name of the column in the probcode table that holds all of the system’s problem-profile codes) would have the effect of making all profiles under the Hardware category invisible. You can also enter an SQL expression to re-order or re-group the available profiles, or indeed to control a number of other aspects of what analysts will see in the Choose Profile dialogue box. In the expression, you can refer to any of the first four columns of the probcode table.

Log Call Form Options The attribute settings here specify which major optional elements are to exist on the form (both visually and functionally), and what operational options are to apply in relation to the use of the form. The attributes are as follows:

Show information bar If you want the information bar at the bottom of the form to be visible, so that it may be used to notify analysts of any customer- or asset-related matter of which they need to be aware, you should ensure that this option is enabled.

Allow ‘Log Call’ This enables the Log Call command on the form.

Allow ‘Log & Assign Call’ This enables the Log & Assign Call command on the form.

Allow ‘Log & Take Call’ This enables the Log & Take Call command on the form.

Allow ‘Log & Accept Call’ This enables the Log & Accept Call command on the form.

Allow ‘Log & Resolve/Close Call’ This enables the Log & Resolve/Close Call command on the form.

Allow file attachments If you want analysts to be able to attach files to the form, and to be able to display the File Attachments tab for viewing and managing them, you should ensure that this option is enabled.

Show extended-details tab If you need to place more fields or other objects on the Log Call form using the Form Designer, but have run out of room in the main Details tab (and have no wish to extend its size), you can ask the system

Log Call Forms

57

to provide a suitable extended-details tab that would contain the additional objects by enabling this option. An extra tab like this would be particularly useful if you wanted to create a new table that would be an extension of the Open/Closed Call table (opencall). To obtain the same behaviour from this extended-details table as from opencall, you simply have to ensure that its primary key is similarly a column named callref. In the Associated Tables tab (see below), you would then add it to the list of tables and configure it in a similar way to opencall. To create the new table in the first place, you would use the Database Schema Editor to first add this to the existing schema specification and then apply the specification to your database system. Please refer to the Hornbill Core Services Guide for details. You could typically create different tables (and hence different additional tabs) for different classes of call.

Show Resolve/Close Details tab If you want the system to provide a Resolve/Close Details tab on the Log Call form (instead of, or as well as, providing such a facility as a form in a separate window) in which analysts can add resolution or closure details, you should enable this option.

Treat e-mail ‘Received’ time as log-call time By default, whenever an analyst in your support team has logged a call from an e-mail window, the date/time logged for that call would be the moment when the Log Call form was submitted to the system. If, however, you would prefer the system to record the log date/time as the date and time when the e-mail message was received, you should enable this option.

Hide toolbar If you do not want the toolbar at the top of the form window to be visible, you should ensure that this option is enabled.

Hide menu bar If you do not want the menu bar at the top of the form window to be visible, you should ensure that this option is enabled.

Allow workflow If you want to include helpdesk workflow in the functionality of the Log Call form, you should ensure that this option is enabled. Also, if you want the system to automatically apply a specific workflow template to every instance of the form, you should specify it in the Template field.

Show custom HTML tab If you want the system to provide on the form an HTML tab that displays a specified Web page, you should enable this option. If you enable this option, you must specify, in the fields below it, the display

Log Call Forms

58

name that the HTML tab is to have, and also the URL that defines the Web page to be displayed.

Attributes in the Associated Tables Tab for Log Call Forms

The attributes in this tab are divided into two main sections: at the top, a pick-list containing the database tables that are (or can be) associated with the Log Call form concerned, and below that, a Table Properties area containing association settings and assignments relating to the table currently selected in the pick-list. The screenshot above shows the Customer table (userdb) selected.

Using and Managing the Associated Tables Pick-List

To select a table in the pick-list, just click the relevant entry. Its attributes are immediately displayed in the Table Properties area.

To add a new table to the pick-list, first click the Add button next to the list, which displays the Add Associated Table dialogue box. In that dialogue box,

Log Call Forms

59

select an appropriate table type (see below) for the proposed table, and specify the name of the table. Note that the table must already exist. Finally, click OK.

At any time, you can use the Remove key to remove a table entry from the pick-list.

In the pick-list, the headers have the following meanings:

Table Name Each item under this would be the shorthand name of a table in the list, which is the name by which you would identify the table in various Supportworks drop-down lists.

Table Type Each item under this would indicate the table type assigned to a table in the list. There are four possible table types:

Related Table For a Log Call form, this would be a look-up table of (usually) customer or asset data that is searched for the required record when an analyst enters appropriate identifying data in a form field, ultimately resulting in resolution of that record, with all fields bound to columns within the same table being auto-filled. The data filling each of these fields is chiefly for the analyst’s own information, and will not be passed to the call record unless it has been assigned to a corresponding column in one of the call tables, as described in Table Properties: Data Assignments to Table(s) on page 61.

Main Details Table This would be the Open/Closed Call table (opencall).

Diary Updates Table This would be the Call Diary table (updatedb).

Extended Details Table This would be any table that has been created as an extension of the Open/Closed Call table, with a primary key of callref.

Table Description Each item under this would reflect the descriptive name of a table in the list. For an Extended Details Table, the description would also be the title of the extended-details tab on the form.

Table Properties: Miscellaneous

In the top half of the Table Properties area, the following attributes are available for you to modify:

Table Description This is a free-text field used for your own reference to describe the currently selected table. It generates the text you see under the Table Description header in the pick-list above.

Log Call Forms

60

Main Details Column This would apply to a Related Table or Extended Details Table only. It is the name of a column in the Open/Closed Call table (opencall) by which that table can link to the currently selected Related Table or Extended Details Table. It defines the relationship between the two tables, indicating which column in the Open/Closed Call table is to act as the primary key for the selected table, and thus allowing the relevant record to be resolved when the Call Details form of the same class is opened.

On installations where the call-logging methodology is asset-centric (and the supplied Asset table is used), the specified primary key can be employed in a particularly useful way. In such a case, if the selected table is the Customer table (userdb), and when the “Auto-resolve” option (see below) is set, this attribute setting would allow the owner of an asset to be resolved automatically when the asset itself is resolved (provided that the data in the owner column of the Asset table has been assigned to cust_id in the Open/Closed Call table).

Record Pick List This would apply to a Related Table only. It defines the pick-list (for example, the Choose Customer dialogue) that will be displayed when multiple records are available for selection during attempts made by analysts to enter relevant data in the Log Call form.

Add Record Form This would apply to a Related Table only. It can define the standard form (for example, Add New) that will be displayed when an analyst opts to create a new record after Quick-Add fails to find a match for their attempted entry in a suitably associated field on the Log Call form. The form specified here would be the default that would apply initially to all such associated fields within the form being configured. It would override the system-wide default defined in the Database section of the data dictionary for the same table (see Table-Level Attributes on page 41).

Edit Record Form This attribute is reserved for future (JavaScript) use.

Mandatory This checkbox option would apply to a Related Table only. If this option is enabled, analysts will not be allowed to log a call without first having filled those fields, in the Log Call form, that accept resolved-record data from the table concerned.

Auto-resolve This checkbox option would apply to a Related Table only (specifically, the Customer table), and its function is restricted to situations where (a) the call-logging methodology is asset-centric, (b) each asset has a sole owner and (c) the supplied Asset table is used. If this option is enabled, and two

Log Call Forms

61

other conditions are met, any action by an analyst of populating the asset section of the Log Call form will automatically result in the customer section being populated as well. The two conditions are that (a) a data assignment for the Asset table must exist that links this table’s owner column with the Open/Closed Call table’s cust_id column, and that (b) the Main Details Column field for the Customer table is set to the default of cust_id.

Repeatedly auto-resolve This checkbox option is applicable only if “Auto-resolve” is enabled. In such a case, if “Repeatedly auto-resolve” is not enabled, auto-population of the Log Call form’s customer section would occur only the first time the analyst populates the asset section. If “Repeatedly auto-resolve” is enabled, auto-population would occur every time.

Table Properties: Data Assignments to Table(s)

The bottom half of the Table Properties area contains a list of data items, given by valid SQL expressions (such as the name of a column in the Related Table currently selected), whose values are to be assigned to the indicated columns of (usually) the Open/Closed Call table or the extended-details table. The effect of such assignments is that, when an analyst submits a call, the data items determined by the expressions shown on the left are passed to the call-table columns named on the right, which means that they are stored in the call record created at that moment. This would allow calls containing the assigned data to be subsequently searched and reported on in terms of those named columns.

In addition, where a value assignment is that of key data (such as a customer ID) from the column defined in the Main Details Column field, the data concerned would allow any required Related Table record to be found from a call record and displayed on the Call Details form of the same class. Any further data-assignment entries would be superfluous for the purpose of referencing data for the Call Details form, but may be necessary for call-based searching and reporting.

The data assignments in this list are not, however, concerned solely with post-call-logging operations. On installations where the supplied Asset table is used, if (as described in the previous section) you are going to enable the “Auto-resolve” option relating to the Customer table (userdb), you must select the Asset table (equipmnt) and add a special assignment that links this table’s owner column with the Open/Closed Call table’s cust_id column. If this condition is

Log Call Forms

62

not met, or cust_id is not selected as the Main Details Column, auto-population of customer details through entry of asset details will not work.

To add a new entry to the list of data assignments, first click the Add button next to the list, which displays the Data Assignment Properties dialogue box:

In the Expression field, type an SQL expression for the data that you wish to assign to a column of the Open/Closed Call table or extended-details table. This would normally comprise the name of a column (or a combination of columns) in the Related Table currently selected. In the Target Table field, ensure that the required table is selected. In the Target Column field, select the required column within that table. Finally, click OK, and observe that your new entry has appeared on the list.

At any time, you can use the Properties key to edit a data assignment, or the Remove key to remove a data assignment from the list.

Log Call Forms

63

Attributes in the ‘Show Me’ Items Tab for Log Call Forms

You use this tab to configure the availability and operation of specific search functions, report requests and other commands selectable from the Show Me menu on the Log Call form.

The attributes in this tab are divided into two main sections: to the left, a pick-list depicting all the menu items (and their separators) that currently exist in the Log Call form’s Show Me menu, and to the right of that, a Menu Item Properties area containing various settings and values for the item currently selected in the pick-list. In the screenshot above, the Change Customer menu item is shown as the one selected.

Using and Managing the ‘Show Me’ Items Pick-List

To select a menu item in the pick-list, just click the relevant entry. Its attributes are immediately displayed in the Menu Item Properties area.

Log Call Forms

64

The set of attributes displayed will vary according to the type of action the menu component is configured to invoke when analysts select it. You can specify the action required by selecting it from the drop-down list in the Action field relating to that menu component. The Action field is always the second one from the top in the Menu Item Properties area.

The possible types of action are as follows:

• Tree Browser Form

• Pick List

• Menu Separator

• Record Properties

• Inventory Details

• SQL Query

• Script

• Run External Program

• Send E-Mail

• Open URL

• Record Reset

• Information Browser

Some of these are used in the default data dictionary, but you may use any of them for your own organisation’s purposes.

The various action types are explained in the subsections that follow, which also contain descriptions of the different attributes that are available for a Show Me menu component with respect to each different type of action configured.

To add a new item to the pick-list (and hence create a new command in the actual Show Me menu), first click Add. At the prompt that appears, type a suitable name for the menu command and click OK. The new command should now be visible at the bottom of the list. With the new item highlighted, select a suitable action type in the Action field, depending on the kind of command you want it to be. Then enter the required values and settings for the command, with reference to the information given in the relevant subsection below.

To remove an item from the list (and the menu), click Remove. The item is deleted without any confirmation prompt being given.

Log Call Forms

65

“Tree Browser Form” Action

The Tree Browser Form type of action is one that displays an SQL tree browser form (such as the Find Customer or Find Asset dialogue box) when analysts select the Show Me menu item concerned on the Log Call form.

With Tree Browser Form set as the Action attribute for a Show Me menu component (such as Change Customer or Change Asset), the Menu Item Properties area displays a set of attributes appropriate to that action:

Name This is the name given to the selected menu component. It is used as the displayed label for the item in the Show Me menu.

Browser This specifies the variant of the dialogue box (Find Customer or Find Asset) that will be displayed on selection of the Show Me menu item. Such variants are predefined in the SQL Tree Browser Forms section of the data dictionary. In the Default data dictionary, the choices available from the drop-down list are Customer and Asset.

Filter This specifies, in SQL script, the criteria to be applied for the inclusion or exclusion of certain records from any search or browse done via the Find Customer (or Find Asset) dialogue box. If the filter is used, the where keyword would already be implied. A null entry here would mean that the filter criteria defined for the relevant browser or browser form itself would be applied.

“Pick List” Action

The Pick List type of action is one that displays a pick list (such as the Choose Customer or Select Product record-selection window) when analysts select the Show Me menu item concerned.

With Pick List set as the Action attribute for a Show Me menu component (such as All Customers Assets on systems where the supplied Asset table is used), the Menu Item Properties area displays a set of attributes appropriate to that action:


Pick List This specifies the variant of the record-selection window (Choose Customer, Select Product or whatever) that will be displayed on invoking the Show Me menu item. Such variants are predefined in the Pick Lists section of the data dictionary. In the Default data dictionary, the choices available are

Log Call Forms

66

Customer, Asset, Charge Centre or Site. Although all of these are predefined, only the first two are actually used, as they have a direct association with the Customer Details and Asset Details areas, respectively. However, you may use any of the variants as and when appropriate.

Filter This specifies, in SQL script, the criteria to be applied to the display of records on the list presented in the invoked window. For example, the effect of the default criteria specified for All Customers Assets is to display, in the record-selection window, only those assets that belong to the currently entered customer. If the filter is used, the where keyword would already be implied. A null entry here would mean that all of the records are to be displayed.

Menu Separator “Action”

The Menu Separator type of action is not really an action as such, but is, rather, an aspect of the structural design of the Show Me menu. A Show Me item designated as a menu separator will appear in the relevant Show Me menu, not as a selectable item, but as a line separating items from each other. In the pick-list, it is depicted as an item whose display name is made up of a series of dashes.

With Menu Separator set as the Action attribute for a Show Me menu component, the Menu Item Properties area displays no attributes apart from Action. No other configuration is required.

“Record Properties” Action

The Record Properties type of action is one that displays a specific record’s details, using an appropriate standard form, when analysts select the Show Me menu item concerned. The record displayed would normally be the one actually relating to the customer or asset (or any other database entity) currently entered in the Log Call form, although you could configure it to be a record from a separate, but linked, database table. By default, the record will be displayed using the Customer Properties (or Asset Properties) standard form.

With Record Properties set as the Action attribute for a Show Me menu component (such as Customer Properties), the Menu Item Properties area displays a set of attributes appropriate to that action:

Log Call Forms

67


Form This specifies the type of standard form that will be displayed on selection of the Show Me menu item. The form types are those visible in the Forms section of the data dictionary. The choices available consist of all the available entry forms, which, in this field’s drop-down list, are expressed in terms of the form’s category and type. Any form you select here will override the default one defined in the Database section of the data dictionary for the table concerned.

Key Value At the very least, this specifies the search key that allows the Show Me menu command to identify the database record relating to the customer or asset entered in the Log Call form. You enter the key using a macro whose format is &[table.column], which gives the name of the table in which to search for the record, and the name of the column in that table by which to search. In the default data dictionary, the table specified is the Customer table (or the Asset table). If you specify a table that is different to any of the ones from which the customer, asset or similar data in the the Log Call form is derived, you must ensure that it at least links appropriately to that table.

Beyond this basic usage, you can specify, in the Value field, an SQL expression that would add any required limiting criteria to the search so as to prevent the resolution of certain records. The where keyword is already implied in the filter.

“Inventory Details” Action

The Inventory Details type of action is one that displays the PC Audit Inventory Details window when analysts select the Show Me menu item concerned. The Inventory Details window would contain data relating to the asset (or Configuration Item) being shown in the asset-details area of the Log Call form at the time, and would only be displayed if PC Audit is installed on your system. Note that, if you have the newer Assetworks product installed, you should use the Information Browser type of action instead, as described in the relevant subsection below.

With Inventory Details set as the Action attribute for a Show Me menu component, the Menu Item Properties area displays a set of attributes appropriate to that action:

Log Call Forms

68


Asset ID This identifies the database record relating to the asset (or Configuration Item) entered in the Log Call form, so that the system can then find the corresponding asset record in the PC Audit database. You enter the ID using a macro whose format is &[table.column], which specifies the relevant Supportworks asset table and the column used as the key to search it.

“SQL Query” Action

The SQL Query type of action is one that displays, in the Search Results area of the Database Searches view, all calls meeting given criteria when analysts select the Show Me menu item concerned. The calls would relate to the customer or other database entity entered in the Log Call form at the time when the Show Me menu item is selected.

With SQL Query set as the Action attribute for a Show Me menu component (such as All Open Calls for this Customer), the Menu Item Properties area displays a set of attributes appropriate to that action:


SQL Statement This specifies the call table and criteria for the search, expressed as a full SQL statement.

“Script” Action

The Script type of action is one that performs any action programmable using JavaScript when analysts select the Show Me menu item concerned.

With Script set as the Action attribute for a new Show Me menu component, the Menu Item Properties area displays a set of attributes appropriate to that action:


Script This would contain the JavaScript instructions to perform the desired action. See Programming a Show Me Item “Script” Action on page 319 for details of the JavaScript methods that are available to you.

Log Call Forms

69

“Run External Program” Action

The Run External Program type of action is one that executes a specified program when analysts select the Show Me menu item concerned.

With Run External Program set as the Action attribute for a new Show Me menu component, the Menu Item Properties area displays a set of attributes appropriate to that action:


Program This is the filename of the external program that will be executed.

Arguments These would be any arguments that the program supports, entered exactly as on a command line.

“Send E-Mail” Action

The Send E-mail type of action displays a Compose New Message window when analysts select the Show Me menu item concerned. The contents of the window would be based on the mail template specified.

With Send E-mail set as the Action attribute for a new Show Me menu component, the Menu Item Properties area displays a set of attributes appropriate to that action:


To This would be the intended recipient of the e-mail message.

Cc This would be any other recipient who is to receive a copy of the message.

Subject This would be the subject of the message.

Template This would be the name of the e-mail template on which the message is to be based.

“Open URL” Action

The Open URL type of action is one that opens the default browser at a specified website when analysts select the Show Me menu item concerned.

Log Call Forms

70

With Open URL set as the Action attribute for a new Show Me menu component, the Menu Item Properties area displays a set of attributes appropriate to that action:


Website This specifies the address of the required website. You must enter the URL in full.

“Record Reset” Action

The Record Reset type of action is one that clears the Customer Details or Asset Details (or equivalent) fields of the Log Call form, depending on the Related Table specified, when analysts select the Show Me menu item concerned. The record in the table itself is unaffected.

With Record Reset set as the Action attribute for a new Show Me menu component, the Menu Item Properties area displays a set of attributes appropriate to that action:


Table This specifies the Related Table whose associated form fields are to be cleared by the menu command.

“Information Browser” Action

The Information Browser type of action is one that displays the Hornbill Information Browser window when analysts select the Show Me menu item concerned. The Information Browser would contain data relating to the asset (or Configuration Item) being shown (or being highlighted) in the asset-details area of the Log Call form at the time, and would only be displayed if Assetworks or a supported third-party asset-discovery product is installed on your system.

With Information Browser set as the Action attribute for a Show Me menu component, the Menu Item Properties area displays a set of attributes appropriate to that action:


Log Call Forms

71

URL This points to the location of the Information Browser’s configuration file and, in the case of Assetworks, should be as follows:

http://<Assetworks server name>:<port>/aw/html/viewer4

where <Assetworks server name> is the name of the computer on which the Assetworks server is installed. Use of the extension :<port> is necessary only if the port to be used is anything other than 80.

If your asset data is sourced from a third-party system, you can find out the URL to use by referring to the relevant integration document.

Variables This is an argument that allows the system to find the relevant asset record in the other product’s database from the record resolved on the form. It should be as follows:

-var compname="&[<table>.<column>]"

where <table> specifies the relevant Supportworks asset table, and <column> specifies the column used as the key to search it. Typically, the table might be equipmnt and the key column equipid.

Attributes Handled in the Form DesignerThe Form Designer makes available, for customisation, all attributes of the Details tab or the extended-details tab of a given call-form type. The representation of the tab and its constituent objects is displayed in the Layout area, while the attribute settings and values are listed in the Object Inspector area. The specific set of attributes shown relate to whatever (if anything) is currently selected within the tab. These could be the attributes relating to the tab as a whole, or to a particular object in it.

The method used to change the setting or value of a given attribute will be one of the following, depending on the attribute:

• Text entry. The cursor becomes visible when you click the attribute.

• Selection of an item via a drop-down list. The list appears when you click the attribute to reveal a list button and then click that button.

• Selection of a colour via a standard Colours dialogue. This pops up when you click the attribute to reveal a browse button and then click that button.

Log Call Forms

72

• Selection of a text font via a standard Font dialogue. This pops up when you click the attribute to reveal a browse button and then click that button.

• Selection of multiple items via a list dialogue. This pops up when you click the attribute to reveal a browse button and then click that button.

Form-Level Attributes

The form-level attributes of a Log Call form specify the overall dimensions, colour scheme and font characteristics of its Details or extended-details tab. These are the attributes that are displayed whenever there is no single specific object selected on the layout.

The attributes are displayed in the Object Inspector area as follows:

Descriptions of the attributes are given below. Note that the values/settings of some of these form-level attributes (identified by the word “Initial” in their names) apply globally, as initial defaults, to individual form objects. Such attributes will have object-level counterparts whose values will individually override the respective form-level values.

Size This defines the minimum width and height of the form tab. You can click the expansion control to the left of the attribute name to display the dimensions as a list of individually named items.

Fill Colour This defines the overall background colour of the form tab.

Log Call Forms

73

Wallpaper Image If you want a wallpaper image to be displayed on the form background, you can define it using this attribute. There are three possible ways of defining the image:

• By entering its name as listed in the Pictures category of the data dictionary

• By entering its network pathname (if located in a shared folder)

• By entering its URL

Image Mode If you have specified a form wallpaper image (see above), you can use this attribute to specify whether the image is displayed in its actual size, or whether it should stretch to fit the form background area. The corresponding drop-down list options are Exact Size and Stretch to Fit.

Object Fill Colour (Initial) This defines the initial default background colour of all the fields and other defined areas within the form tab.

Object Text Colour (Initial) This defines the initial default colour of all the text and other foreground elements of defined areas within the form tab.

Object Text Font (Initial) This defines the initial default typographical characteristics of all the text used in defined areas within the form tab. Note that you will not be able to change the global font colour by using the standard Font dialogue invoked from here: you must use the standard Colours dialogue invoked from the Object Text Colour (Initial) attribute instead.

Object-Level Attributes

As soon as you select a single individual object on the currently displayed Log Call form layout in the Form Designer, the Object Inspector area switches to a display of the attributes relating to that particular object. The precise combination of attributes displayed under Object Inspector will depend not only on the type of object selected, but also, in the case of standard fields, on the particular field mode configured.

The following example of attributes displayed in the Object Inspector area is for a standard field set to Text Edit mode:

Log Call Forms

74

Although a few attributes are common to nearly all types of object, there are many more that are common to several, and there are some that are actually unique to one type. As with form-level attributes, those at the object level are divided into a number of separate categories and subcategories. For a given type of object, certain attribute categories may exist, while others may not.

When you create/bind a new field object on a form, a number of its attributes, virtually all of which are in the Field-Specific Properties category, take their initial values from the overall defaults defined in the Data Dictionary Editor against the table column to which the object is bound, as described in the subsection entitled Column-Level Attributes on page 43. You can subsequently

Log Call Forms

75

redefine any of these attributes in the Form Designer, so that the values you specify will be valid just for that particular field.

All the possible attributes, for all possible object types and field modes, are described below, headed by the categories and subcategories under which you would find them.

Data

Object Name This identifies the selected object so that it can be selected from the list in the Object Inspector, and also so that it can be referenced by the underlying JavaScript code (if any). For some objects, certain object names have specific meanings and effects. For example, in the case of an action button, if the object name corresponds to the name of a Show Me command, that command would be executed when the user clicks the button.

Data Binding This is applicable to standard fields, to dual search fields, to formula fields and to labels whose text is taken from table columns. What data binding essentially means is that the selected field or label is associated with a specific table column, or perhaps with two table columns.

In the case of a writeable field that is bound to a column in a call table, the result of such an association when a call has been logged is that the data the analyst will have entered into the field would end up in that table column in the new call record. If, however, the field is bound to a column in a Related Table, it will act instead like a combined search and result field. Any attempt at entering data into it would immediately invoke a search of that table, ultimately resulting in the resolution of the required record and the auto-filling of the other fields bound to the same table. Note that, in this case, the data entered would end up in the new call record only if that data has been assigned (within the Form configuration) to a column in a call table.

When a label is bound to a table column, its text is determined by the Display Name value for the table column concerned (as defined under the Database category of the data dictionary). In contrast to this, the text of a non-bound type of label is determined by the Text attribute (see below).

For standard fields and text labels, the Data Binding attribute specifies a single associated table column in SQL dot-notation. When you use the Field Chooser to create such a field, the necessary SQL expression for data binding appears

Log Call Forms

76

here automatically. Otherwise, if you have created a field manually, you would enter the expression by actually typing it in. The expression must be in the format table.column.

For dual search fields, the Data Binding attribute value would be made up of a proprietary expression to join together the contents of two table columns (separated by a space). It is this combination that would then be associated with the field. Just as for a standard field, analysts would be able to enter data into the field to resolve the required record, and again data derived from a record resolved by a search from another field can be displayed here. The Data Binding expression for a dual search field must be in the format <table>.<column1>!<column2>.

Formula fields share the characteristics of both standard and dual search fields, except that they are read-only. In other words, the data displayed in such a field can only be derived from a Related Table record resolved by searching from another field. The Data Binding expression for reading a single column from a record must be in the format &[<table>.<column>]. For two columns, the format would be &[<table>.<column1>]&[<table>.<column2>].

Text This is applicable to text labels not associated with table columns, to command buttons, to menu buttons and also to URL links. It specifies the text of the label, the text inscribed on the button, or the hyperlink text.

Protected This specifies whether or not the object is to be protected from accidental deletion within the Form Designer. The True setting is useful when an object has more than a minimal amount of JavaScript underlying it.

Commands This is applicable to menu buttons only. It defines the commands of which the menu generated by the button is composed. To create or edit the menu of commands, first click in the attribute’s content field to reveal its browse button, and click that button. The following dialogue box is displayed:

Log Call Forms

77

The list shown is a representation of the button’s menu. If a menu already exists for this button, the names of its constituent commands would be shown under Item Name, and their respective reference numbers under Value. To add a new command to the menu, you would click Add. To edit an existing command, you would select it and then click Properties. In either case, the Item Properties dialogue box would be displayed, allowing you to name or rename the command and to enter or edit its reference number. The name may be that of a Show Me command, or it may be one referenced from the underlying JavaScript code. The reference number can be any whole number of your choice, provided that it is unique, and can also be referenced from JavaScript. On clicking OK, you would see that the command list is updated. If you wish to remove a command from the menu, just select it and click Remove. You can reposition individual commands on the menu by selecting any of them and using the Move Up or Move Down button.

When you have the menu you require, click OK to close the dialogue box. Notice how the list is represented in the attribute’s content field, with special characters separating the items.

URL This is applicable to URL links and images only. It specifies the URL of the Web page that is to be displayed on the user’s browser when they click the hyperlink text defined by the Text attribute (see above) on the form, or when they click the image.

Path This is applicable to file lists only. It specifies the path, on the network, of the folder that contains the files that are to be displayed on the file list.

Log Call Forms

78

Data Source Name This is applicable to SQL lists only. It specifies the ODBC data source from which the displayed table entries are to be derived. If the data to be displayed is call records and you want the cache database to be the source, you should select “syscache” from the drop-down list. If, for any kind of data, you want the main database to be the source, you should select “sysdata”.

Table This is applicable to SQL lists only. It specifies the actual database table from which the data displayable in the object is to be taken.

Filter This is applicable to SQL lists and dual-search fields only. It specifies, in the form of an SQL expression, the criteria governing which displayable records are to make up, or be excluded from, the table or field object on the form. If you want all records to appear in the object, you should leave Filter blank.

Auto Load This is applicable to file lists and SQL lists. It specifies whether or not the contents of the object are to be displayed without manual intervention. Normally, you would ensure that it is set to True. However, if JavaScript code is employed to display the contents on the occurrence of certain form events, you have to enable such manual operation by setting the attribute to False.

Manual Add This is applicable to file lists only. It specifies whether or not files are to be added manually to the list. When set to True, this manual mechanism will override any automatic sourcing provided by the Path attribute (see above).

Add Record Form This is applicable to SQL lists only. It specifies the standard form (for example, Add New) that will open when an analyst opts to create, using a JavaScript-based control on the form, a new record in the database table from which the data displayed in the object is to be taken.

Edit Record Form This is applicable to SQL lists only. It specifies the form (for example, Add New or Call Details) that will open when an analyst double-clicks an entry displayed in the table object.

General

Visible This specifies whether or not the object is to be visible. Normally, all objects should be visible, which is achieved with a setting of True. However, if JavaScript code is employed to switch on an object’s visibility on the occurrence of certain form events, you can manually specify an initial invisible state here by setting the attribute to False.

Log Call Forms

79

Mouse Over Cursor This specifies the type of cursor that the mouse pointer changes to as it is moved over the object concerned when an instance of the form is being displayed. Note that only the appearance of the cursor will be affected: there are no functionality aspects associated with this attribute.

Enabled This specifies whether or not the object is to be enabled. Normally, all interactive objects should be enabled, which is achieved with a setting of True. However, if JavaScript code is employed to enable an object only on the occurrence of certain form events, you can manually specify an initial disabled state here by setting the attribute to False. Note that, for non-interactive objects, it is irrelevant whether or not the object is enabled.

Tab Stop This is applicable to all fields. It specifies whether or not the cursor is to skip this field when an analyst is tabbing through the form. A setting of True will allow the cursor to stop in this field, whereas False will force the cursor to skip it.

Icon This is applicable to command buttons only. It specifies the graphic (if any) that is to be used as the icon on the button. The graphic can be a predefined image used elsewhere in Supportworks, or it can be an image sourced from a Web page. To specify or change an icon, first click in the attribute’s content field to reveal its browse button, and click that button. The following dialogue box is displayed:

Log Call Forms

80

If you do not want an icon on the button, ensure that No Icon is selected. If you want the icon to be an image currently displayed on a Web page, enter the URL of the image file concerned and, if you want a certain colour within the image to be transparent, enter its hash code in the Transparent Colour field. If you want the icon to be an image from a Supportworks image list, select that list in the relevant field and select the required item from among the set of images now displayed. Click OK to apply your choice to the attribute.

Icon Position This is applicable to command buttons only. It specifies the position of the icon defined by the Icon attribute (see above) relative to the button’s text inscription.

No Macro Expansion This is applicable to standard fields. It specifies whether or not macro variables entered by the analyst into the field are to be computed. As such a computation fixes the value on future entries into the same field, you may wish to set this attribute to True in order to avoid that.

Group

Form Group This specifies the tab control, and the particular tab within that area, to which the object belongs. If an object belongs to such a grouping, it will

Log Call Forms

81

always move along with the tab whenever the tab is dragged within the Form Designer layout. A grouped object can be located inside or outside its tab. There are two ways in which an object can become grouped to a tab: either by selecting the required tab within the control as a whole and dragging the object into that, or by entering the relevant tab specification in the Form Group field. When you drag the object into the tab, the tab specification is created automatically. The tab specification is in two parts, separated from each other by a colon (:). The first part consists of the tab control’s object name, and the second is a number identifying the selected tab within it. The number denoting the first tab would be 0, the one denoting the second would be 1, and so on.

Control Group This will allow JavaScript code in a form to access a number of objects simultaneously as a group. To set up a group, you just need to decide on a suitable group name and then enter that as the value of each member object’s Control Group attribute. If you have specified any such objects as belonging to a given group then, whenever an instance of the form is displayed, a new JavaScript class, of type ControlGroup, is created as a property of the form. This new class can then be used to enable/disable or show/hide all objects within the group, or to access the controls array representing the objects that are members of that group.

For example, to toggle the enable state of all objects that belong to the "grpCustomer" control group, you would use the following line of code:

grpCustomer.enable = !grpCustomer.enable;

To hide all objects that belong to the same control group, you can use the following code:

grpCustomer.visible = false;

Object Placement: Position

The attribute values in this subsection will change correspondingly as you drag the object over the form or resize it. Conversely, the object’s position or size will change to match the values as you edit them. Also, if you edit a position value, the relevant dimension value will be automatically recalculated, and vice versa. All positioning attributes are measured against the minimum dimensions of the form tab, as specified at form level, and therefore define the minimum dimensions of the individual object.

Log Call Forms

82

Left This specifies the horizontal positioning of the left-hand side of the selected object on the form. It indicates the distance, in pixels, between the left-hand edge of the form and the left-hand side of the object.

Top This specifies the vertical positioning of the top of the selected object on the form. It indicates the distance, in pixels, between the top of the form and the top of the object.

Right This specifies the horizontal positioning of the right-hand side of the selected object on the form. It indicates the distance, in pixels, between the left-hand edge of the form and the right-hand side of the object.

Bottom This specifies the vertical positioning of the bottom of the selected object on the form. It indicates the distance, in pixels, between the top of the form and the bottom of the object.

Width, Height These specify, in pixels, the respective dimensions of the object.

Object Placement: Resize/Scaling

The attribute values in this subsection control the corresponding rescaling of an individual object when the form as a whole is resized by an analyst.

Left This specifies the degree to which the left-hand side of the selected object will move relative to the changing width of the form tab as the form window is resized horizontally. It is expressed as a percentage of the form-width shift.

Top This specifies the degree to which the top of the selected object will move relative to the changing height of the form tab as the form window is resized vertically. It is expressed as a percentage of the form-height shift.

Right This specifies the degree to which the right-hand side of the selected object will move relative to the changing width of the form tab as the form window is resized horizontally. It is expressed as a percentage of the form-width shift. Note that, if Left and Right are equal for a given object, the width of the object will remain constant as the form is stretched, although its horizontal position will change by the designated proportion.

Bottom This specifies the degree to which the bottom of the selected object will move relative to the changing height of the form tab as the form window is resized vertically. It is expressed as a percentage of the form-height shift. Note that, if Top and Bottom are equal for a given object, the height of the object will

Log Call Forms

83

remain constant as the form is stretched, although its vertical position will change by the designated proportion.

Appearance

Text Colour This is applicable to most objects that contain built-in text, or into which text can be entered. It specifies the colour of that text.

Fill Colour This is applicable to all objects except lines. It specifies the background colour that fills the object (or the place-holder in the case of an image).

Disabled Fill Colour This is applicable to standard fields only. It specifies the background colour of the field if its function is disabled on the form.

Font This is applicable to all objects that contain built-in text, or into which text can be entered. It specifies the typographical characteristics of that text. Note that you will not be able to change the font colour by using the standard Font dialogue invoked from here: you must use the standard Colours dialogue invoked from the Text Colour attribute instead.

Border Style This is applicable to nearly all objects. It specifies the style of the object’s border (if any). The options available are None, Rectangle, 3D Sunken, 3D Raised, 3D Etched Sunken and 3D Etched Raised.

Border Colour This is applicable to nearly all objects. It specifies the colour of the object’s border (if one exists).

Colour This is applicable to lines and ellipses only. It specifies the colour of the line or outline.

Transparency This is applicable to buttons, rectangles, ellipses, SQL lists, file lists and form-flag fields. It specifies whether or not the object is to be transparent. When you make an object transparent, its fill colour is removed, which means that any object to the back of it will show through.

Fill Style This is applicable to rectangles only. It specifies the colour style in which the object’s background is to be painted. The options available are Solid, Horizontal Gradient and Vertical Gradient. The Solid setting would give a single colour specified by Fill Colour 1 (see below). A gradient setting would give a smooth gradation, in the relevant direction, between two colours, specified by Fill Colour 1 and Fill Colour 2 (see below), respectively.

Log Call Forms

84

Fill Colour 1 This is applicable to rectangles only. If Fill Style (see above) is set to Solid, it would specify the background colour that fills the object. If Fill Style is set to a gradient, it would specify the left-most or top-most colour of the gradient.

Fill Colour 2 This is applicable to rectangles only. If Fill Style (see above) is set to Solid, it would have no meaning. If Fill Style is set to a gradient, it would specify the right-most or bottom-most colour of the gradient.

Shadow Effect This specifies whether or not the object is to have a shadow effect around its borders.

Selected Colour This is applicable to file lists and SQL lists. It specifies the background fill colour of list or table entries for whenever they are selected.

Selected Text Colour This is applicable to file lists and SQL lists. It specifies the colour of the text on list or table entries for whenever they are selected.

Header Height This is applicable to file lists and SQL lists. It specifies the height, in pixels, of the object’s displayable header.

Row Height This is applicable to file lists and SQL lists. It specifies the height, in pixels, of each entry displayed in the object.

Sort Column Index This attribute is applicable to file lists and SQL lists. It numerically identifies the column, within the list or table, by which the displayed entries are to be sorted. The identifier would be 0 for the first column, 1 for the second, and so on.

Sort Order Descending This attribute is applicable to file lists and SQL lists. It specifies whether or not the sort order is to be descending (that is, starting with the highest alphanumeric value and ending with the lowest). Thus, the setting of False would indicate ascending order, which is the default.

Show Header This is applicable to file lists and SQL lists. It specifies whether or not the object’s header is to be displayed. Even if you do not want the header to be visible, you must set this attribute to True (temporarily) in order to be able to select and therefore configure the individual displayed columns.

Vertical Grid Lines This is applicable to file lists and SQL lists. It specifies whether or not the separating lines between columns within the object are to be displayed.

Log Call Forms

85

Horizontal Grid Lines This is applicable to file lists and SQL lists. It specifies whether or not the separating lines between entries within the object are to be displayed.

Checkbox This is applicable to file lists and SQL lists. It specifies whether or not each list entry is to have a checkbox to the left of it. The check states would be determined and acted upon by JavaScript code.

Alignment This is applicable to text labels and URL links only. It specifies the positioning of the label text within the label area, or of the hyperlink text within the link’s place-holder. The options available are Left, Centre and Right.

Toolbar Button This is applicable to command buttons only. It specifies whether or not the button is to have the characteristics of an in-form toolbar button. Such a toolbar button has no outline and no colour fill.

Image This is applicable to images only. It specifies the actual graphic residing within the image place-holder. There are three possible ways of defining the image:



• By entering its URL, which should begin with &[app.webroot]/ (representing the path to the html folder on the server where Supportworks is installed)

No-image Image This is applicable to images only. It specifies the default graphic that would appear within the image place-holder when no Image attribute is defined, or (if defined) the graphic does not exist.

Image Mode At the object level, this is applicable to images only. It specifies the behaviour of the image placement, indicating whether the place-holder should match the size of the image, or whether the image should stretch to fit the place-holder. The options available are Exact Size and Stretch to Fit. Only in the latter mode would you be able to resize the image. If you try to resize the image in Exact Size mode, only the place-holder would be affected.

Horizontal Alignment This is applicable to images only. When Exact Size is selected as the image mode, you can make the place-holder larger than the image itself. In such circumstances, the Horizontal Alignment attribute would specify the horizontal positioning of the image within the place-holder. The options available are Left, Centre and Right.

Log Call Forms

86

Vertical Alignment This is applicable to images only. When Exact Size is selected as the image mode, you can make the place-holder larger than the image itself. In such circumstances, the Vertical Alignment attribute would specify the vertical positioning of the image within the place-holder. The options available are Top, Centre and Bottom.

Transparent Colour This is applicable to images only. It specifies the colour, within the image, that is to be transparent. Any part of the image having this colour would then allow any objects at the back of it to show through.

Background Mode This is applicable to images and tab items only. For an image, it specifies whether colours within the image will all be opaque or whether a certain colour (specified by the Transparent Colour attribute) will be transparent. For a tab item where the style of the overall tab control is set to Coloured, it specifies whether the tab is to have a solid colour or just a coloured border.

Link Colour This is applicable to URL links only. It specifies the initial colour of the hyperlink text when the URL concerned is still unvisited.

Visited Link Colour This is applicable to URL links only. It specifies the colour of the hyperlink text once the URL concerned has been visited.

Link Visited This is applicable to URL links only. It specifies whether or not the URL link is to be regarded as “visited” right from the start. The normal setting is False, which allows users to see (by virtue of the link changing colour) if they have already visited the URL. A setting of True, on the other hand, would keep the hypertext permanently at the Visited Link Colour.

Disabled Link Colour This is applicable to URL links only. It specifies the colour of the hyperlink text while the link is disabled.

Link Behaviour This is applicable to URL links only. It specifies the kind of situation in which the hyperlink text is to be underlined. A setting of Hover Underline would cause the text to be underlined whenever the mouse pointer is moved over it. The other two possible options are Always Underline and Never Underline.

Tab Height This is applicable only to tab controls. It specifies the height, in pixels, of the actual tabs at the top of the tabbed area.

Tab Style This is applicable only to tab controls. It specifies whether the tabbed area is to have a coloured style or a monochrome (Standard) style.

Log Call Forms

87

Tab Spacing This attribute is reserved for future use.

Left Slope This attribute is reserved for future use.

Right Slope This is applicable only to tab controls. It specifies the extent, in pixels, of the gradient section at the right-hand corner of each tab.

Left Margin This is applicable only to tab controls. It specifies the amount, in pixels, by which the tabs are indented from the left-hand edge of the tabbed area.

Height Offset This specifies the amount, in pixels, by which the height of unselected tabs is reduced relative to that of the selected tab.

Active Text Colour This is applicable only to tab controls and tab items. It specifies the colour of the label text on one or all tabs for whenever a tab is selected.

Inactive Text Colour This is applicable only to tab controls and tab items. It specifies the colour of the label text on one or all tabs for whenever a tab is not selected.

Active Tab Colour This is applicable only to tab controls. It specifies the background fill colour of a tab for whenever the tab is selected.

Inactive Tab Colour This is applicable only to tab controls. It specifies the background fill colour of tabs for whenever the tabs are not selected.

Active Tab Font This is applicable only to tab controls. It specifies the typographical characteristics of the label text on a tab for whenever the tab is selected. Note that you will not be able to change the font colour by using the standard Font dialogue: you must use the standard Colours dialogue associated with the Active Text Colour attribute instead.

Inactive Tab Font This is applicable only to tab controls. It specifies the typographical characteristics of the label text on tabs for whenever the tabs are not selected. Note that you will not be able to change the font colour by using the standard Font dialogue: you must use the standard Colours dialogue associated with the Inactive Text Colour attribute instead.

Tab Colour This is applicable only to tab items. It specifies the colour of the individual tab item.

Selection Mode This attribute is applicable to file lists and SQL lists. It specifies whether analysts should be able to select more than one item, just one item, or

Log Call Forms

88

no items on the list or table. The last option disables selection highlighting, and would only highlight items temporarily as you mouse over them; it would be used in situations where item selection is not appropriate.

Images This is applicable only to the header sections of objects such as file lists and SQL lists. It specifies the respective images the system can optionally display to the left of the defined values that can appear in the list’s rows below the header concerned. To create or edit the set of image definitions, first click in the attribute’s content field to reveal its browse button, and click that button. The following dialogue box is displayed:

If a set of definitions already exists, this would be shown on the list. There would be one definition per file/SQL list-item value, identifying the image associated with it. For example, under a Status header in an SQL list, you could have one image for the value “Active” and another for the value “Inactive”.

To edit a definition, you would select its entry on the list and then click Properties. To add a new definition to the list, you would click Add. In either case, the Item Properties dialogue box would be displayed, allowing you to specify the image in the Name field and the item value in the Value field. There are three possible ways of specifying the image:



• By entering its URL, which should begin with &[app.webroot]/ (representing the path to the html folder on the server where Supportworks is installed).

Log Call Forms

89

On clicking OK in the Item Properties dialogue box, you would see that the list is updated. If you wish to remove a definition from the list, just select it and click Remove. You can reposition individual definitions on the list by selecting any of them and using the Move Up or Move Down button.

When you have the list you require, click OK to close the dialogue box. Notice how the list is represented in the attribute’s content field, with a circumflex (^) separating each Name from its Value and single vertical-bar characters (|) separating the definitions.

Field-Specific Properties (and also Label-Specific Properties)

The Field-Specific Properties category relates to standard fields only. The Label-Specific Properties category relates to non-bound labels (including tab and object-header labels).

Field Mode This specifies the mode in which the field will work, thus determining its behavioural characteristics, the kind of data it will deal with, and the method(s) of data entry it will accept. Depending on which field mode you select, there will be a different set of attributes displayed below it. The possible field modes are as follows:

Text Edit A field in this mode will allow analysts to enter and edit text by typing only.

Pick List This field mode will allow data entry via a drop-down list. The individual constituents of the list are defined by the Pick Items attribute (see below). Unless the Pick List Only attribute is set to True (see below), text entry would also be allowed. The text-entry facility here would always have the auto-complete function activated.

Pick List (Numeric Mode) This field mode will allow data entry via a drop-down list, in which the items, although presented as text strings, actually have underlying numerical values when stored in the appropriate database record. This makes it possible to edit, from time to time, list items as they appear to the user without affecting the system’s interpretation of them. The Pick Items attribute (see below) defines the individual items of which the list is composed, as well as the mapping between the numerical values and their string representations. Unless the Pick List Only attribute is set to True (see

Log Call Forms

90

below), text entry would also be allowed. The text-entry facility here would always have the auto-complete function activated.

Pick List (Image Mode) This field mode is reserved for future use.

Pick List (XML Source) This field mode will allow data entry via a drop-down list, in which the items are derived from a website-based XML file. If the contents of the XML file can be arranged to reflect those of a remote database, you have a means of populating the drop-down list from a data source located anywhere in the world. The system will request the selection items via the URL that points to the XML file. The URL is given by the value of the URL attribute (see below). The XML file contents must be structured as follows:

<list> <item>Selection Item 1</item> <item>Selection Item 2</item> <item>Selection Item 3</item> <item>Selection Item 4</item> etc</list>

Each piece of text delineated by an <item> tag will be placed in the drop-down list as a separate item.

Distinct Pick List This field mode will allow data entry via a drop-down list, in which the items are derived from an appropriate database table column. The table/column concerned is defined by the Distinct Table and Distinct Column attributes (see below). The column chosen must have no duplicate data across the records in the table. Unless the Pick List Only attribute is set to True (see below), text entry would also be allowed. The text-entry facility here would always have the auto-complete function activated.

Distinct Pick List (Local) This field mode is the same as Distinct Pick List, except that the database used would be one installed on the client computer. A field in this mode therefore has attributes that allow the specification of the relevant data source, a user ID and a password.

Form Flags This field mode will allow data entry by selection of checkbox options. The options to be displayed in the field (and their underlying bitwise mappings) are determined by the contents of the Flags attribute (see below). If initial checkbox settings are required, these would be defined by the contents of the Default Value attribute.

Log Call Forms

91

Password A field in this mode will allow analysts to enter and edit text such as a password by typing, the text being displayed as asterisks (*).

Date/Time Control A field in this mode will display the current date and/or time when clicked or, if a specific date/time is currently held in the table column to which the field is bound, the field will display that, and will then allow it to be adjusted as necessary. The particular combination of date and/or time that is to be displayed is governed by the setting of the Format attribute (see below). The precise format of the date and/or time is determined by the relevant regional setting in the record of the analyst displaying the form, or by the contents of the Custom Format attribute (see below).

E-mail Address From the viewpoint of a user, this field mode acts in the same way as Text Edit. However, when this mode is selected in the Object Inspector, you will notice that field-specific properties not pertinent to e-mail addresses are absent.

Minute Time Period A field in this mode will allow analysts to enter a time period in hours and minutes, and (although unlikely on a Log Call form) will allow a time period to be displayed in such a format from a database record.

Second Time Period A field in this mode will allow analysts to enter a time period in hours, minutes and seconds, and (although unlikely on a Log Call form) will allow a time period to be displayed in such a format from a database record.

Read Only This specifies whether or not analysts will be allowed to enter data into the field or modify data displayed in it. The options available are True and False.

Mandatory This specifies whether or not analysts will be obliged to enter data (directly or indirectly) into the field before submitting the form. The options available are True and False. A True setting will cause a small red triangle to be displayed in the top left-hand corner of the field to indicate that it is a mandatory field. The system will not allow the record to be created if such a field remains empty. If a non-mandatory field is in Pick List or Distinct Pick List mode and its Pick List Only attribute is set to True, then the first entry in the field’s drop-down list will be a blank one in order to allow the field to be emptied. However, if such a field’s Mandatory attribute is changed to True, there will be no blank entry available in the list, thus ensuring that a null value cannot be selected.

Log Call Forms

92

Allow Null Values This attribute has a similar effect to Mandatory, but with the True/False logic reversed. In other words, a mandatory field would effectively be the same as one that does not allow null values, except that, in the latter case, there would be no red triangle shown in the top left-hand corner of the field.

Multi-Line Text This is applicable to standard fields in Text Edit mode, to text labels that are not associated with table columns, and also to URL links. If a field is multi-line, any text typed into it will wrap around to the next line as it reaches the right-hand edge. In addition, if the data type of the column to which the field is bound is “Longvarchar” (long alphanumeric), or if the field is not bound to any column at all, it will respond as expected to presses of the Return key. If a label or URL link is multi-line, it means that it would be possible to extend its text over more than one line when that text is generated using JavaScript code. The options available for multi-line text are True and False.

Auto Complete This is applicable only to fields in Text Edit mode. If a field is set to Auto Complete, the first character typed into it will be validated against record data in the column to which the field is bound. If this validation finds a match, the entry is automatically completed. Should this entry not be the one sought, it is possible to carry on typing to trigger successive validations until the required entry is auto-completed. The options available for auto-completion are True and False.

Format This is applicable only to fields in Text Edit or Date/Time Control mode. It specifies the format of text or dates/times (as appropriate) entered into the field or output to it from a record. In Text Edit mode, the possible format options are as follows:

Text This specifies normal text, without any formatting.

Upper Case Text This specifies upper-case lettering only, so that any letter typed into the field or output to it will be forced into capitals.

Lower Case Text This specifies lower-case lettering only, so that any letter typed into the field or output to it will be forced into lower-case.

Numeric This specifies a numeric-integer field, so that, with the field bound to a table column of data type “Integer”, anything other than a whole number cannot be typed into the field or output to it.

Log Call Forms

93

Currency This specifies a currency format, where the character used as the decimal symbol would depend on what is defined in the analyst’s regional settings.

Decimal This specifies a decimal-number field, so that, with the field bound to a table column of data type “Decimal”, anything other than a decimal number cannot be typed into the field or output to it. The character used as the decimal symbol would depend on what is defined in the analyst’s regional settings.

In Date/Time Control mode, the choices are as follows:

Date/Time This allows the field to accept and display both a date and a time in the format defined by the analyst’s regional settings.

Date This allows the field to accept and display a date in the format defined by the analyst’s regional settings.

Time This allows the field to accept and display a time in the format defined by the analyst’s regional settings.

Custom This allows the field to accept and display a date and/or a time in the format defined by the Custom Format attribute (see below).

Custom Format This is applicable only to fields in Date/Time Control mode. It specifies, for the field, a fully editable date and/or time format – one which is therefore not defined by the analyst’s regional settings. It becomes available when the Custom option for the Format attribute (see above) is selected. When you specify a custom format, there are a number of coded elements you can use, and they are the same as those given in the Support Analyst Table Management section of the chapter in the Supportworks Administrator Guide that covers the management of analyst-related data and settings.

Input Mask This is applicable only to fields in Text Edit mode. It allows data entry in the field to be restricted to a uniquely defined, character-based format, and forces data to be output to the field in the same format. This makes it possible to stipulate, for example, a telephone-number field that must consist of numeric digits only, and that must have delimiters such as parentheses (round brackets) and hyphens located at specific places within the number string.

The input mask would comprise a string of characters, each acting (a) as a place-holder of a particular type for the actual character to be typed in or output, (b) as a literal character that would always appear in the defined position within the

Log Call Forms

94

field on both entry and output, or (c) as a region-dependent formatting character that would appear as itself in the same way as a literal. The characters you can use in an input mask are as follows:

Pick List Only This is applicable to fields that have a drop-down list. Normally, analysts are able to type text into such a field as an alternative to selecting an

Character Description

# Numeric digit place-holder (0-9).

. Decimal point. The actual character used in the field would be the one specified as the decimal symbol in the analyst’s regional settings.

, Thousands separator. The actual character used in the field would be the one specified as the digit-grouping symbol in the analyst’s regional settings.

: Time separator. The actual character used in the field would be the one specified as the time separator in the analyst’s regional settings.

/ Date separator. The actual character used in the field would be the one specified as the date separator in the analyst’s regional settings.

A Alphanumeric character place-holder (0-9 and a-Z).

& Character place-holder. Any printable character would be valid.

? Alphabetic character place-holder (a-Z).

> Alphabetic character place-holder, upper-case only (A-Z).

< Alphabetic character place-holder, lower-case only (a-z).

\ A command that treats the next character in the mask as a literal. This allows you to include any of the above characters in the mask.

Literal Any other character included in the mask would be displayed as a literal, which means that it would appear as itself.

Log Call Forms

95

item via the list. This functionality is achieved with a setting of False. However, if you want to force analysts to enter data by means of the drop-down list, you should set Pick List Only to True.

Use Data Dictionary Pick List This is applicable only to fields in Pick List mode or Pick List (Numeric Mode) mode. It allows you to specify whether the set of drop-down-list items for the field should be the overall default set provided by the Pick Items attribute of the table column to which the field is bound, or be the form-specific set provided by the Pick Items attribute below. To use the default set, select True as the value for the Use Data Dictionary Pick List attribute, whereas to use the form-specific set, select False.

Pick Items This is applicable only to fields in Pick List mode or Pick List (Numeric Mode) mode, and where Use Data Dictionary Pick List has been set to False. It specifies the items that are to constitute the field’s drop-down list. For a field in Pick List (Numeric Mode) mode, it also specifies the underlying numeric equivalent of each list item. To create or edit the list of items, first click in the attribute’s content field to reveal its browse button, and click that button. In Pick List mode, the following dialogue box is displayed:

If a list of items already exists, this would be shown under Item Name.

In Pick List (Numeric Mode) mode, the following dialogue box would be displayed:

Log Call Forms

96

Again, if a list of items already exists, this would be shown under Item Name. This time, though, there is an additional heading entitled Value, under which the items’ equivalent numbers would be shown.

To edit an item in either type of list, you would select the item and then click Properties. To add a new item to either type of list, you would click Add. In either case, the Item Properties dialogue box would be displayed, allowing you to name or rename the item. In the case of a numeric-mode pick-list, you would also be expected to enter the underlying numerical value of the item, and this (instead of the name string) is what would be placed into the bound table column when an analyst selects it on the form.

On clicking OK in the Item Properties dialogue box, you would see that the list is updated. If you wish to remove an item from the list, just select it and click Remove. You can reposition individual items on the list by selecting any of them and using the Move Up or Move Down button.

When you have the list you require, click OK to close the dialogue box. Notice how the list is represented in the attribute’s content field, with single vertical-bar characters (|) separating the items.

Quick-Add This is applicable to fields in Distinct Pick List mode only (but has no effect in the local version of this mode). When enabled (that is, when its setting is True), it will allow an analyst with appropriate database rights to create, on-the-fly, a new record in the relevant Distinct Table whenever they discover, on the form they are completing, that the record they are trying to resolve is currently unknown. The standard form that Quick-Add will display for the purpose of allowing a new record to be created is specified by the Add

Log Call Forms

97

Record Form attribute, which exists at field, form and table level (see below). Note that Quick-Add is always (implicitly) enabled for fields in Text Edit mode.

Order List Descending This is applicable to fields in Distinct Pick List mode only. If it is enabled (that is, when its setting is True), the database items in the field’s drop-down list will be shown in reverse alphabetical order

Distinct Table This is applicable to fields in Distinct Pick List mode only. It specifies the name of the table whose columns will provide the data that goes to make up the field’s drop-down list. The options available are all the known tables.

Distinct Column This is applicable to fields in Distinct Pick List mode only. It specifies the name of the column in the Distinct Table that will provide the data items selectable from the field’s drop-down list. The options available are all the columns of the Distinct Table.

Display Column This is applicable to fields in Distinct Pick List mode only. It specifies the name of an additional column in the Distinct Table that will be queried in order to be able to display these items in the drop-down list instead of those in the Distinct Column. The analyst’s selection from the list, as stored in the database, will still be the value taken from the Distinct Column. If nothing is specified for the Display Column attribute, the Distinct Column items would be displayed in the drop-down list by default.

Add Record Form This is applicable to fields in Distinct Pick List mode only (but not in the local version of this mode). It specifies the Add New form that will be displayed on a positive response to the Quick-Add prompt, inviting the analyst to create a new record in the Distinct Table (unless the field is bound to a Related Table, in which case it would be the Related Table’s Add New form that is displayed initially). The form specified here would apply to the selected field only, and would override both the system-wide default defined in the Database section of the data dictionary for that Distinct Table (see Table-Level Attributes on page 41) and the form-level default defined in the Form Configuration (see Table Properties: Miscellaneous on page 59). The options available for selection here depend on which standard forms actually exist for the Distinct Table concerned.

List Filter This is applicable to fields in Distinct Pick List mode only. It specifies, in the form of an SQL expression, the criteria governing which record items in the Distinct Table are to make up, or are to be excluded from, the field’s

Log Call Forms

98

drop-down list. If you want all record items to appear on the list, you should leave List Filter blank.

Extra Items This is applicable to fields in Distinct Pick List mode only. It specifies, in the form of proprietary expressions, any extra items that you may wish to add to the field’s drop-down list. An extra item could simply be a named entity that does nothing other than display itself (or its expressed string value) in the field when selected from the list, or a named entity that acts as a pointer to an appropriate column in a table that is related to the Distinct Table via that column. If an extra item of this latter type is selected in a field, its computed value would be displayed when a record from the related table is resolved on the form. In drop-down lists on the client, such resolvable items are displayed as character strings enclosed in square brackets. They would typically be found in drop-down lists belonging to fields such as SLA and Charge Centre.

Each resolvable item represented in the Extra Items attribute must be in the format <list item>=&[<table>.<column>], where <list item> is the string that appears in the drop-down list, and the table and column specified point to the source of the item’s computed value in any resolved record. For a “do nothing” item, the format would just be <list item>=<string value>, where <string value> is what would be literally displayed in the field. Successive expressions within the attribute are separated from each other by means of a circumflex (^). They will appear in the same order down the list as the order in which you enter them here, and will always appear below the Distinct Table/Column items.

Image List This is applicable to fields in Pick List (Image Mode) mode only. It specifies, by name, any one of the lists of images defined in the Image Lists section of the data dictionary. These images would then constitute the field’s drop-down list.

Colour Indicator This is applicable to fields in Date/Time Control mode only. When enabled (that is, set to True), it will give a visual indication in the field of whether or not the date/time stipulated in it has passed. If the date/time has not yet been reached, the field’s background would be coloured green. If the date/time has been exceeded, the colour would be red.

Flags This is applicable to fields in Form Flags mode only. It specifies the checkbox options that will be available within the field’s area on the form, together with their respective bitwise numerical equivalents as held in the database. To create or edit the options, first click in the attribute’s content field

Log Call Forms

99

to reveal its browse button, and click that button. The following dialogue box is displayed:

If a list of options already exists (as in this screenshot), these would be shown under Flag Name, and the corresponding bit flags would be shown under Bit. To edit an option, you would select it and then click Properties. To add a new option to the list, you would click Add. In either case, the Item Properties dialogue box would be displayed, allowing you to name or rename the option and to select the relevant bit-equivalent for it. On clicking OK, you would see that the list is updated. If you wish to remove an option from the list, just select it and click Remove. You can reposition individual options on the list by selecting any of them and using the Move Up or Move Down button.

When you have the list of options you require, click OK to close the dialogue box. Notice how the list is represented in the attribute’s content field, with a special character separating the options from their bit equivalents, and another character separating the options from each other.

Default Value This specifies the default content of the field, if any is required, that would be displayed whenever an analyst opens a new form. Depending on the field mode, you would specify the required default either as literal text or as an appropriate numerical representation. Form flags values, for example, would be represented by the binary sum of the bit equivalents of the options that you want checked. Note that if you were to specify hint text as well (see below), the default value would override that.

Log Call Forms

100

Hint Text This specifies any help text that you may want displayed in the field whenever an analyst opens a new form. To distinguish between this text and actual data, the hint text would be displayed in a grey font.

Precision This is applicable only to fields in Text Edit mode, with Format set to Decimal. It specifies the number of digits of which the number entered/displayed in the field is to be made up.

Scale This is applicable only to fields in Text Edit mode, with Format set to Decimal. It specifies the number of decimal points to which the number entered/displayed in the field is to go.

Button Type This is applicable to fields in Distinct Pick List mode only. It specifies the style of button that is to be used for the field’s drop-down-list control. You have a choice between the “down-arrow” style (Standard) and the “triple-dot” style (Ellipsis).

Data Source Name This is applicable to fields in Distinct Pick List mode only. It specifies the ODBC data source from which the displayed list items are to be derived. If the items to be listed are from call records and you want the cache database (sw_systemdb) to be the source, you should select “syscache” from the drop-down list. If, for any kind of record, you want the main database to be the source, you should select “sysdata”. If the field is set to the local version of Distinct Pick List mode, there are no such predefined choices available. Instead, you would have to type in the name of the relevant client-based data source.

User ID This is applicable specifically to the Distinct Pick List (Local) field mode. It specifies a valid user ID that the Supportworks client can use to log into the local database.

Password This is applicable specifically to the Distinct Pick List (Local) field mode. It specifies the password relating to the user ID that the Supportworks client can use to log into the local database.

Tab Label This is applicable to tab items only. It specifies the text with which the tab item is to be labelled.

Name This is applicable only to the header sections of objects (such as file lists). It specifies the text with which the selected part of an object header (relating to a particular displayed column) is to be labelled.

Log Call Forms

101

Text Colour This is applicable only to the header sections of objects (such as file lists). It specifies the colour of the selected header section’s text labelling.

Fill Colour This is applicable only to the header sections of objects (such as file lists), and is reserved for future use.

Column This is applicable to displayed columns in SQL list objects only, and will only be visible if you have specified a data source name and a table for the parent SQL list. It specifies the database table column that is to provide the data that will be displayed in the object column belonging to the selected header section.

Allow Sort This is applicable to displayed columns in SQL list objects only. It specifies whether or not the mouse-click sorting mechanism relating to the selected header section will be active. If the attribute is set to True, each successive mouse-click by an analyst on that header section will cause a reversal of the sort order within the displayed column to which it belongs. If the attribute is set to False, clicking on that header section will have no effect on the sort order.

Visible This is applicable only to the header sections of objects (such as file lists). It specifies whether or not the displayed column to which the selected header section belongs is to be visible within the object on the form.

Allow Resize This is applicable only to the header sections of objects (such as file lists). It specifies whether or not analysts are to be allowed to drag, on the form, the header section’s right-hand separator line in order to change its width.

Cache Image This is applicable to images only. It specifies whether or not the image should be cached locally for speedier display (rather than fetched from its actual location every time).

XML Data Source URL This is applicable to fields in Pick List (XML Source) mode only. It specifies the URL that points to the XML file from which the displayed list items are to be derived.

Call and Form Types and Call ClassesFor a given data dictionary, you can create and separately configure any number of Log Call forms, each corresponding to a particular type of call that may arise.

Log Call Forms

102

For example, certain details may be required when logging a “hardware” call, while other details may be required when logging a “software” call. On any system where multiple Log Call forms are set up, analysts will always be presented with a choice of which form type they wish to use whenever they try to log a call. The type of form chosen will reflect the type of call that has to be logged. A form type is essentially a template on which all call forms of that particular style are based, and would be identified by the form name.

A multiplicity of Log Call forms of course requires a corresponding set of Call Details forms, which you can similarly create and separately configure. However, in order for the system to know automatically which Call Details form to open for viewing a call of a given type, there has to be some kind of connecting factor between that form and the original Log Call form. This is where the idea of call class comes in. Call class essentially defines the type of call concerned. When you create either a Log Call form or a Call Details form, you must specify the class of call to which it should belong. To properly classify calls over the entire call life-cycle, you would have to ensure that, for each Log Call form type of a particular class, there exists a Call Details form type of the same class.

The class of a call might, for example, be Internal, External, Hardware, Complaint, Software, New Sale, or whatever you wish. A complaint call, for instance, would need a user-interface format (when logged or viewed) that is very different to that of a PC hardware call. There would normally be a one-to-one relationship between a call-form type and its class. Although it is theoretically possible to assign the same class to more than one Log Call (or Call Details) form type, this should preferably be avoided, as the whole purpose of call class is to allow you to define separate pairs of user interfaces for different kinds of call. Nevertheless, there is no reason why you could not create two or more stylistic variants of a call form of any given class.

Proper specification of call classes in a multiple-call-type environment means that analysts will be able to view any call in a format that is automatically decided as being appropriate to its class. The class of a call is stored in the Open/Closed Call table against that call, so when an analyst views the call, the application knows exactly which form it must use in order to display the call details. If an analyst attempts to view a call that is of a class for which more than one Call Details form exists, they would be given a choice of all such forms within that class to select from.

Log Call Forms

103

As well as facilitating the logical link between a pair of call forms, a call class provides certain default configuration settings for any new form you may wish to create. The settings concerned would be those relating to the database tables that are associated with the form, as indicated in the section Attributes in the Associated Tables Tab for Log Call Forms on page 58. As most of the associated-table settings required to configure a new form are provided by reference to a call class, you only need to set these up once for each class. Thus, when you subsequently create and configure a Log Call form and its corresponding Call Details form, specification of the same class in both cases will automatically apply the same initial defaults to both form configurations. If you require a variant of a form within a given call class, you can create a standard one of that class and then make appropriate adjustments to its default settings by means of the relevant Form Configuration tool, together with any necessary adjustments to its layout using the Form Designer.

By using a number of different data dictionaries on your system, you could define separate sets of call classes for separate groups of analysts, where each set would be available to a particular group responsible for specific types of call. Thus, analysts would have access only to those call forms that their group actually needs.

Managing Call Classes

Facilities are available on the client by which you can create, edit and delete call classes, provided that you have the necessary rights. When you create a call class, you will primarily be defining a set of default table associations for any new form to which that class is to be assigned. You will be able to define these associations either from scratch or starting from those defined in an existing class.

To invoke the management dialogue via which you will be able to access these facilities, select Manage Call Classes from the Administration menu. The following dialogue box is displayed:

Log Call Forms

104

To create a new call class, first click Add. The following dialogue box is displayed:

Enter an appropriate name for the new class you are creating and ensure that your preferred default option is selected. You can start off with either a blank set of associated-table properties or a set of properties inherited from a specified class that already exists. When you click OK, the following dialogue box is displayed:

Log Call Forms

105

In the relevant field, enter a suitable description for the new call class, and then select the Associated Tables tab. The display changes to the following:

Log Call Forms

106

In this tab, you can modify the list of associated tables that should apply to this class, and you can change settings and add or delete value assignments for each of those tables. Notice that the tab is very similar in appearance to the tab of the same name in the Log Call Form Configuration dialogue box. In fact, the controls and attributes available in the tab are identical in functionality and meaning to those described in Attributes in the Associated Tables Tab for Log Call Forms on page 58.

When you have completed all required activities in this tab, click Apply. Click OK to close the Call Class Properties dialogue box.

If you wish to change the properties of an existing call class, select it from the Manage Call Classes list and click Edit. This opens the Call Class Properties dialogue box, in whose tabs you can make the necessary changes.

If you wish to delete a call class, select it from the Manage Call Classes list and click Delete. The entry is removed immediately.

To exit from the call-class management dialogue, click Close.

Log Call Forms

107

Form Structure in MemoryIn order to be able to make better sense of the concept of data bindings, for example, it helps to be aware of how Log Call and Call Details forms and their associated tables are represented in memory.

When an analyst invokes a new Log Call form, a hierarchical structure for that form is created in memory as follows:

You can see that most of the form’s structure comprises representations of the form at various levels. These representations are fairly straightforward, as it is easy to see the correspondences between the conceptual model and the actual displayed form. However, there is one area, interfacing as it does with the database, that requires more explanation: the database record buffer area. This is the place where data entered from, or displayed in, form fields is held temporarily, within separate record buffers, while the form is open. The buffer

Log Call form representation

Databaserecord buffers

Details tab representation

Extended-details tab representation

Information bar representation

Form object representations

Form object representations

From database

Log Call Forms

108

composition during that time is determined by the list of associated tables configured for the call class concerned.

The form’s memory representation as a whole is constructed by reference to its attribute settings and values in the current data dictionary. This includes the record buffers, each of which would relate to one of the associated tables defined in the relevant Form configuration. A record buffer assumes the column structure of the table to which it relates, and would be able to hold a single record’s worth of data.

Initially, while the form is blank, the record buffers consist of empty virtual records. Then, as the analyst proceeds to enter the customer’s details on the form and the relevant customer record is resolved, the buffer relating to the Customer table is loaded with the data from the database record, and all suitably bound customer fields on the form are populated. A similar process occurs with asset data (if the supplied Asset table is in use). In the case of call settings and options, the data entered in such fields is placed directly into the buffer relating to the Open/Closed Call table. In the same way, problem-description text is placed directly into the buffer relating to the Call Diary table.

For any given call class allocated to the form, data assignments from the Customer table (and/or from the Asset table where relevant) to the Open/Closed Call table or extended-details table will have been defined to allow the required customer/asset data to be saved in the call record, and hence to be displayed in the corresponding Call Details form, and/or to be reported on. While the Log Call form is open, this data is actually assigned from the record buffer(s) relating to the Customer/Asset table(s) to the record buffer relating to the Open/Closed Call table or extended-details table.

A Call Details form would have the same kind of hierarchical memory structure, complete with record buffers. In this case, as the form is opened, the data from the relevant records in the Open/Closed Call table and the Call Diary table is loaded into the respective record buffers. Then, by reference to the primary-key data in the Open/Closed Call table buffer, the relevant records from the Customer and Asset tables are resolved, and the data from these is loaded into the appropriate buffers. As soon as the record buffers are filled, all fields on the form that are bound to columns of the tables concerned are correspondingly populated.

Log Call Forms

109

From the above, it is evident that data bindings defined for form fields, and also data assignments defined for Related Tables, in the data dictionary are, strictly speaking, applied to the record buffers rather than to the corresponding table columns in the database. In the case of a Log Call form, it is not until the form is submitted that the contents of the record buffers are saved in the corresponding database records. It just happens that, for convenience, the virtual tables and columns have been designed to be identified by the same names as the real ones.

Creating New Call Form TypesIf there is a requirement for the system to support a number of additional classes of call, or variants of an existing class of call, you will need to create extra Log Call and Call Details form types, and to then customise these appropriately. When you create a new call form type, you have to specify an existing form on which to base its layout, and also the call class to which you want it assigned.

The procedure to create a new call form type is as follows:

1. Ensure that you are switched to the data dictionary that contains a form of the type you wish to base the new form on. An example of such a form type might be the Log Call form named “Helpdesk Call”.

2. Run the Data Dictionary Editor.

3. From the File menu, select New, and then the category of form that you wish to create (for example, Log Call Form). The following dialogue box is displayed:

Log Call Forms

110

4. Select the form type (template) on which the new form type is to be based. This selected form type will supply the default tab layouts for the new form type. You will subsequently be able to adjust these defaults using the Form Designer.

5. Observe that the displayed call class changes automatically to reflect that of the chosen form type. If you want to create just a variant of that form type, you should keep the default Call Class setting. However, if you wish to create a form type that is to be used in a completely different kind of call situation, for which a suitable call class has already been created, you should select that call class. Remember that any call class specified here will supply the default table-association attributes for the new form type. You will subsequently be able to adjust these using the Form Configuration tool.

6. Enter a suitable name for the new form type. This is the name by which the form type will be identified, and it will be added to the selection menu of form types displayed when an analyst logs a call. Note that periods (.), slashes (\ or /) and question marks (?) are not allowed in the form name.

7. Click OK, and notice that, in the left-hand pane of the editor, the new form is added to the existing items under the Log Call Forms or Call Detail Forms category, as appropriate.

8. Click Close to commit your changes just to memory, or Save to update the copy of the data dictionary on the server.

9. If the Analyst Portal is used by anyone in the support team, stop and restart SwServerService to allow calls to be progessed from within the Analyst Portal.

Note that if you wish to create a new form type based on one existing in another data dictionary, you can use the copy procedure described in the next section to make it available in the current data dictionary.

Copying Call Form TypesIf you are using multiple data dictionaries in your helpdesk system, you may wish to duplicate, in any data dictionary, certain Log Call or Call Details form types that already exist in other data dictionaries. Equally, you may wish to create a variant of a form type in the current data dictionary. You can accomplish

Log Call Forms

111

either of these tasks quickly and easily by means of a copy facility available on any displayed call form, or in the Browse Forms dialogue box. Once you have the duplicate copy in the relevant data dictionary, you can use it immediately as is, or perhaps you may wish to use it as the basis for one or more new forms.

The procedure to copy a call form from one data dictionary to another is as follows:

1. Ensure that you are switched to the data dictionary that contains a form of the type you wish to copy. An example of such a form type might be the Log Call form named “Helpdesk Call”.

2. Display an instance of that form in an appropriate way. For example, to display a “Helpdesk Call” type of Log Call form, simply initiate the logging of such a call. Alternatively, go to the Administration menu on the main client window and select Forms > Browse Forms.

3. If you are displaying a form, go to the Tools menu and select Copy Form To. Alternatively, if you are displaying the Browse Forms dialogue box, click Copy. The following dialogue box is displayed:

4. Ensure that the data dictionary to which you want to copy the form type is selected.

5. Enter a suitable name for the duplicate form. This is the name by which the form type will be identified in the target data dictionary, and it will be added to the selection menu of form types displayed when an analyst to whom that data dictionary has been assigned logs a call. Note that periods (.), slashes (\ or /) and question marks (?) are not allowed in the form name.

6. Click OK to create the duplicate in the selected data dictionary.

You can now, if you wish, switch to the relevant data dictionary and confirm that the new form type is available.

Log Call Forms

112

Call Details Forms

113

Call Details Forms

A Call Details form is a dialogue box that opens when an analyst double-clicks a previously logged call to view its details. As most of a Call Details form’s visual and operational attributes are of the same, or of a similar, type to those of a Log Call form, a large part of the process to customise it is almost identical. Again, by means of the appropriate configuration tool (called the Call Details Form Configuration tool in this case) and/or the Form Designer, you can modify any of the major attributes of such a form. For example, you can:

• Specify which optional top-level tabs (including their underlying functions) are to exist in the Call Details form type concerned, and whether or not the information bar at the bottom of the form is to be available

• Configure the relevant details of a custom HTML tab (if enabled), which would display within it a Web page of your choice, perhaps one that is relevant to the call, customer or asset concerned

• Specify the call class for the Call Details form, ensuring that this matches the class of the corresponding Log Call form you would have already configured

• Configure an SQL filter for the Change Problem Profile dialogue invoked from the Call Details form concerned

• Specify the name and location of the template that the system will use when printing Call Details forms of the type concerned

• Specify the tables with which the relevant Call Details form type is to be associated, and configure certain aspects of these that relate to the functionality of the form

• Specify which database functions and reports are to be selectable from the Show Me menu in the Call Details form concerned, and configure the behaviour and menu position of each of them

• Specify, for each customisable top-level tab on the form, its dimensions, its default colour scheme and its default font characteristics, and also set the attributes of each individual object on each tab


Call Details Forms

114

You would perform the actions described in all of the above points except the last two by means of the Call Details Form Configuration tool, and you would perform those described in the last two points by means of the Form Designer.

It is not necessary (or, indeed, advisable) to use the Data Dictionary Editor for Call Details form customisation, even though an appropriate Call Detail Forms category is viewable from within it. However, the editor is needed for actually creating new form types and deleting unwanted ones.

Attributes Handled in the Call Details Form ConfigurationThe attributes available for customisation using the Call Details Form Configuration tool would relate to a given Call Details form type, and would apply to the form dialogue box as a whole. Just as for a Log Call form, the attributes are divided into three sections, displayed in the dialogue box as three separate tabs: Settings, Associated Tables and ‘Show Me’ Items.

Call Details Forms

115

Attributes In the Settings Tab for Call Details Forms


Form Name This is the name given to the selected Call Details form type. It is used for reference, both within the Data Dictionary Editor, and in the selection list, presented to analysts when viewing a call that is of a class for which more than one Call Details form exists, that allows them to choose the required form.

Call Class This specifies the class of the calls to be viewed using this form. It must be the same as the class specified in the corresponding Log Call form.

Form Title This specifies the title of the Call Details form, as displayed in the title bar of its window. If you wish, you can include (as in the default configuration) the macro &[opencall.callref], which will generate the relevant call reference in the title.

Profile Filter In this field, you can enter, for example, an SQL expression specifying the problem profiles that are (or are not) to be available for selection

Call Details Forms

116

in the Change Problem Profile dialogue box, which is displayed when an analyst clicks in the problem-profile field on the Call Details form. Thus, entry of code!=”hrdw” would have the effect of making all profiles under the Hardware category invisible. You can also enter an SQL expression to re-order or re-group the available profiles, or indeed to control a number of other aspects of what analysts will see in the Change Problem Profile dialogue box. In the expression, you can refer to any of the first four columns of the probcode table.

Print Template This specifies the URL of the PHP-based template that the client uses to produce a printout of the call details on request. By default, the pathname of the template within the HTTP server would be displayed as &[app.webroot]/clisupp/details/swcall.php, where &[app.webroot] is an environment variable that allows the system to resolve the HTTP server and port dynamically. For passing the necessary call reference to the template, the variable assignment ?callref=&[opencall.callref] would be added to the end of the pathname.

Call Details Form Options The settings here specify which major optional elements are to exist on the form, both visually and functionally. Most of the attributes here correspond to ones that also appear in the Log Call Form Configuration, and you would normally set these pairs to match each other. The options are as follows:

Show Call Diary tab If you want the system to include the Call Diary tab on the Call Details form, you should ensure that this option is enabled.

Allow file attachments If you want analysts to be able to attach files to the form, and to be able to display the File Attachments tab for viewing and managing both new and existing attachments, you should ensure that this option is enabled.

Show extended-details tab If you have enabled the corresponding extended-details option for a Log Call form of the same class, and you want analysts to be able to see or modify any of the extended details on the Call Details form, you should enable this option. If you enable this option, you must ensure that the extended-details table exists on the Associated Tables tab for this form and is configured identically to the way it is for the Log Call form (see below). Alternatively, you may have created a separate (although probably related) table and added this to the Associated Tables tab, in which case it is not necessary for it to have the same configuration.

Call Details Forms

117

Allow workflow If you have enabled the workflow option for a Log Call form of the same class, you should ensure that this option is enabled here as well.

Show custom HTML tab If you want the system to provide, on the Call Details form, an HTML tab that displays a specified Web page, you should enable this option. If you enable this option, you must specify, in the fields below it, the display name that the HTML tab is to have, and also the URL that defines the Web page to be displayed.

Show information bar If you want the information bar at the bottom of the form to be visible, so that it may be used to continue notifying analysts of any customer- or asset-related matter of which they need to be aware, you should ensure that this option is enabled.

Hide toolbar If you do not want the toolbar at the top of the form window to be visible, you should ensure that this option is enabled.

Hide menu bar If you do not want the menu bar at the top of the form window to be visible, you should ensure that this option is enabled.

Call Details Forms

118

Attributes In the Associated Tables Tab for Call Details Forms

Most of the attributes in this tab reflect those found in the Associated Tables tab of the Log Call Form Configuration dialogue box. It is important to ensure that, for any given form, all the common associated-table settings and values in the Call Details Form Configuration exactly match their counterparts defined for the corresponding Log Call form.

Just as in the Log Call Form Configuration dialogue box, the attributes here are divided into two main sections: at the top, a pick-list containing the database tables that are (or can be) associated with the Call Details form, and below that, a Table Properties area containing association settings and assignments relating to the table currently selected in the pick-list. All the buttons available in this tab are functionally identical to those in the Log Call Form Configuration dialogue box.

The meanings of the table types displayed in the pick-list are the same as for a Log Call form, with the exception of “Related Table”. From the perspective of a

Call Details Forms

119

Call Details form, a Related Table would be any table that is searched for a matching record, by reference to the key data held against the call, when an analyst opens the form, resulting in resolution of the record and its display in the relevant bound fields on the form.

Two of the modifiable attributes that are common to the Table Properties area of both the Call Details Form Configuration and the Log Call Form Configuration are actually fairly meaningless in the context of the Call Details form. These are as follows:

Record Pick List This would apply to a Related Table only. It defines the pick-list (for example, the Choose Customer dialogue) that will be displayed when multiple records are available for selection during attempts made by analysts to enter relevant data in the Call Details form. In practice, however, most Call Details forms will not have any customer- or asset-related fields configured for searchable data entry, so any setting that exists for this attribute would normally be ignored.

Add Record Form This would apply to a Related Table only. It can define the standard form (for example, Add New) that will be displayed when analysts opt to create a new record after no match is found for their attempted entry in the Call Details form. In practice, however, most Call Details forms will not have any customer- or asset-related fields configured for searchable data entry, so any setting that exists for this attribute would normally be ignored.

Attributes Specific to the Call Details Form

There are several modifiable attributes shown in the Table Properties area of the Call Details Form Configuration that do not appear in the Log Call Form Configuration, as they apply specifically to the Call Details form. We provide information on these attributes below:

Call-Action Specifier This would apply to a Related Table only. It defines the action specifier that the system should pass to a server-side script to indicate that a call has had a record from that Related Table changed.

Can edit This checkbox option would apply to a Related Table or to an Extended Details Table. If enabled, it would allow analysts to change the contents of any fields on the Call Details form (except for key and dual search fields) that are bound to columns in the table concerned. Such an action would, in fact, change

Call Details Forms

120

the data in the table record itself, provided that the analyst has the rights to do so for that table.

Can change This checkbox option would apply to a Related Table only. If enabled, it would allow analysts to use the Change Customer, Change Asset or equivalent command in the Call Detail form’s Show Me menu. In other words, they would be able to change, for example, the customer against which the call was logged.

Attributes In the ‘Show Me’ Items Tab for Call Details Forms

You use this tab to configure the operation and availability of specific search functions and reports selectable from the Show Me menu on the Call Details form. The configuration attributes that are available for each of these items are exactly the same as for a Log Call form. See Attributes in the ‘Show Me’ Items Tab for Log Call Forms on page 63 for details.

Call Details Forms

121

Attributes Handled in the Form DesignerJust as for a Log Call form, the attributes available for customisation using the Form Designer in relation to a Call Details form would relate to either the main-details tab or the extended-details tab of the form. The objects available, and all attributes, both at the form level and at the object level, are exactly the same as for a Log Call form. For details of what the attributes are and what settings and values they can have, see Attributes Handled in the Form Designer on page 71. All references in that section to a Log Call form apply equally to a Call Details form.

However, some attributes need to be interpreted somewhat differently in the context of Call Details forms. They are as follows:

Data Binding As Call Details forms are normally not designed to allow analysts to directly enter, into any field, data that will resolve a record, the idea of “data binding” in the Call Details form configuration is slightly more straightforward. It would simply mean that, when such a form is opened, whatever data item exists in a given column of a table record will be displayed in the form field bound to that column. The table record concerned can be either the call record or a Related Table record. For a Call Details form, wherever a Related Table record needs to be resolved, that would be done, not by the analyst’s data entry, but by the automatic application of relational key data held in the call record.

For a dual search field, the binding would just indicate its association with the two table columns that ultimately provide the data to be displayed.

For labels and formula fields, with their inherent read-only characteristics, binding would have exactly the same meaning here as in a Log Call form layout. The comments concerning label names are also equally valid here.

Mandatory This attribute has no effect at all on fields in a Call Details form.

Creating and Copying Call Details FormsYou create and copy Call Details forms by exactly the same means as you create and copy Log Call forms. The relevant instructions are given in Creating New Call Form Types on page 109 and in Copying Call Form Types on page 110, respectively.

Call Details Forms

122

Standard Forms

123

Standard Forms

There are two types of standard form:

• A standard management form

• A standard call-action form

From a customisation point of view, both types are dealt with identically; it is only their contrasting usages within Supportworks that make them fall into different categories.

Standard Management FormsA standard management form is an Add New or Properties dialogue box that allows you to create new records, or view and update existing ones, in any of the following Supportworks managed tables:

• The Charge Centre table

• The Customer table

• The Asset table (if used)

• The Manufacturer table

• The Generic Type table (if used)

• The Supplier table

• The Site table

• A custom-built table additional to the above

• A custom-built table replacing any of the above

Standard management forms are divided into two functional categories: record-creation forms and record-viewing/updating forms. These are invoked in different ways on the client and, for a given table, they can have exactly the same design or somewhat different designs.

A record-creation form would be displayed in all situations where the analyst has asked to add a new record to a table. For example, they may have selected, via an appropriate “Manage” command in the main client window’s File menu,

Standard Forms

124

the “Add New” type of sub-command below it. Alternatively, they may have responded positively to a Quick-Add prompt.

A record-viewing/updating form would be displayed in all situations where the analyst has located an existing record by some means and has then asked to display it in full. For example, they may have selected, via an appropriate “Manage” command in the File menu, the “Browse” type of sub-command below it, and then clicked the Properties button on the table browser or tree browser thus displayed. Equally, they may have conducted a search in a database entity view and then double-clicked a record listed in the search results.

You can customise either type of standard management form by means of the same kinds of tools as used for a Log Call form or a Call Details form. The main changes you can make to a form are as follows:

• Specify which utility bars are to be visible on the form

• Specify whether or not analysts will be able to resize the form

• Specify the tables (if any) with which the form is to be associated, and configure certain aspects of these that relate to the functionality of the form

• Specify the form’s dimensions, default colour scheme and default font characteristics, and also set the attributes of each individual object on the form


You would perform the actions described in the first three of the above points by means of the standard Form Configuration tool, and you would perform those described in the last two points by means of the Form Designer.

It is not possible to use the Data Dictionary Editor for standard-form customisation, even though an appropriate Forms category is viewable from within it. You can, however, use the editor to see which standard forms are available in the current data dictionary.

Standard Call-Action FormsA standard call-action form is a dialogue box that allows you to perform a given kind of progress action on a call that has already been logged, or on a work item or issue. Each of the following actions has a form associated with it:

• Complete a work item

Standard Forms

125

• Accept a call

• Update a call

• Place a call on hold

• Resolve or close a call previously logged

• Resolve or close a call currently being logged

• Cancel a call

• Create or update an issue

The comments made in the above section on standard management forms concerning customisation tools and the kinds of changes you can make to a form apply equally to standard call-action forms.

As always, you can use the Data Dictionary Editor to see which forms are available in the current data dictionary. In addition, there is a “Call Action Forms” category available in Global Parameters that defines the form to be used for each of the above call actions, as described in Mapping Forms to Call Actions on page 229.

Attributes Handled in the Standard Form ConfigurationThe attributes available for customisation using the standard Form Configuration tool are the same for all types of standard form (such as Customer Properties and, where relevant, Asset Properties), and would apply to the form dialogue box as a whole. Just as for a Log Call form and Call Details form, the attributes are divided into sections, displayed in the dialogue box as separate tabs. For standard forms, however, there is no concept of class.

Standard Forms

126

Attributes In the Settings Tab for Standard Forms


Form Name This is the name given to the selected standard form type. It is used for reference, both within the Data Dictionary Editor, and in the selection list presented to you when browsing forms. In the Form Configuration screenshot above, the selected form happened to be of the type used for managing the Customer table.

Title This specifies the title of the standard form, as displayed in the title bar of its window.

If you are creating a title for a new form, bear in mind that it should be concise and user-friendly. You should be aware that, whenever an analyst is going to be displaying the form to create records, the system will automatically prefix your title text with “Add New”.

Standard Forms

127

If you are creating a title for a new table browser, again bear in mind that it should be concise and user-friendly. In keeping with Supportworks convention, you may wish to start the title text with the word “Browse”, followed by an indication of the entities to be browsed. An example would be “Browse Manufacturers”.

Print Template The selection here identifies the PHP-based template that will be used for printing form data. Strictly speaking, the data printed will not actually be from the form, but from records in tables associated with the form. The template’s PHP script defines both the layout and the content of the printouts generated, using SQL queries to obtain the content. It is assumed that one or more template files have already been created, so that you can select one in this field.

To add new templates to the drop-down list, or to edit the URLs of existing ones, use the management dialogue box that opens when you click the Manage button. The Url field specifies the URL of the print template. At the beginning of the URL, you can use the environment variable &[app.webroot] to allow the system to resolve the HTTP server and port dynamically. To pass, to the template, a value that would identify the record from which data is to be printed, you would add the variable assignment ?<variable name>=&[<table>.<column>] to the end of the URL. You can pass as many variables as you wish in the URL, bearing in mind any character limit imposed by Web browsers.

Form Options The attribute settings here specify which major optional characteristics of the form (both visual and functional) are to be enabled. The attributes are as follows:

Show menu bar This makes the form’s menu bar visible.

Show toolbar This makes the form’s toolbar visible.

Show information bar This makes the form’s information bar visible.

Allow resize This allows the form to be resized (by dragging an edge or a corner).

Standard Forms

128

Attributes in the Associated Tables Tab for Standard Forms

This tab is very similar to the Associated Tables tab in the Log Call Form Configuration dialogue box. The attributes in this tab are again divided into two main sections: at the top, a pick-list containing the database tables that are (or can be) associated with the standard form concerned, and below that, a Table Properties area containing association settings and assignments relating to the table currently selected in the pick-list. Note that, in this case, the assignments area is not used. The screenshot above shows the Site table (site) selected, where the form being configured is the Customer Properties form.

Using and Managing the Associated Tables Pick-List

To select a table in the pick-list, just click the relevant entry. Its attributes are immediately displayed in the Table Properties area.

To add a new table to the pick-list, first click the Add button next to the list, which displays the Add Associated Table dialogue box. In that dialogue box,

Standard Forms

129

select an appropriate table type (see below) for the proposed table, and specify the name of the table. Note that the table must already exist. Finally, click OK.

At any time, you can use the Remove key to remove a table entry from the pick-list.

In the pick-list, the headers have the following meanings:

Table Name Each item under this would be the shorthand name of a table in the pick-list, which is the name by which you would identify the table in various Supportworks drop-down lists.

Table Type Each item under this would indicate the table type assigned to a table in the list. There are two possible table types:

Related Table For a standard form, this would be any managed look-up table that supplies the Main Details Table with relational data displayable on the form along with the main data. When an analyst enters data in a form field, bound to a Main Details Table column that acts as the primary key for the Related Table, this would ultimately result in the resolution of the required relational record and the auto-filling, with that data, of all the fields on the form that are bound to columns within the Related Table. Thus, in the case of the default Customer Properties form, which is configured with the Customer table as the Main Details Table and the Site table as the Related Table, selecting a site name in the Main tab would fill all the fields in the Site Details tab with the relevant relational site data.

Main Details Table This would be the table for which the form concerned provides record-creation or record-viewing/updating facilities. For example, in the case of the Customer Properties form, it would be the Customer table (userdb).

Table Description Each item under this would reflect the descriptive name of a table in the list.

Table Properties: Miscellaneous

In the top half of the Table Properties area, the following attributes are available for you to modify:

Standard Forms

130

Table Description This is a free-text field used for your own reference to describe the currently selected table. It generates the text you see under the Table Description header in the pick-list above.

Main Details Column This would apply to a Related Table only. It is the name of a column in the Main Details Table by which that table can link to the currently selected Related Table. It defines the relationship between the two tables, indicating which column in the Main Details Table is to act as the primary key for the selected table, and thus allowing the relational record to be resolved whenever the main record contains a value in that column, or whenever valid data is entered into the form field bound to that column.

Record Pick List This should be ignored.

Add Record Form This would apply to a Related Table only. It can define the standard form, for the Related Table, that will be displayed when an analyst opts to create a new record after Quick-Add fails to find one from the primary-key data entered in the standard form for the Main Details Table. The form specified here would be the default that would apply initially to those fields, within the form being configured, that can give rise to operational situations where a relational record-creation function is invoked. It would override the system-wide default defined in the Database section of the data dictionary for the same table (see Table-Level Attributes on page 41).

Edit Record Form This attribute is reserved for future (JavaScript) use.

Mandatory This checkbox option would apply to a Related Table only. If this option is enabled, analysts will not be allowed to save a Main Details Table record displayed on the form without first entering, in that form, the primary-key data necessary for resolving a relational record held in the Related Table.

Table Properties: Data Assignments to Table(s)

You should ignore this area, as data assignments do not apply in the case of standard forms.

Standard Forms

131

Attributes in the Action Items Tab for Standard Forms

Instead of a Show Me menu, there is an Actions menu on a standard form. Therefore, the form configuration contains a corresponding Action Items tab. The purpose of this tab is exactly the same as the ‘Show Me’ Items tab for a call form.

The Asset Details form, for example, provided with the Default data dictionary comes preconfigured with an Actions command named “Inventory”. This is functionally linked with the Inventory button provided on the form by virtue of the button’s object name being “Inventory” as well.

Attributes Handled in the Form DesignerFor a standard form, the objects available in the Form Designer, and all customisable attributes, both at the form level and at the object level, are exactly the same as for a Log Call form. For details of what the attributes are and what

Standard Forms

132

settings and values they can have, see Attributes Handled in the Form Designer on page 71. All references in that section to a Log Call form apply equally to a standard form.

However, some attributes need to be interpreted somewhat differently in the context of standard forms, and there is one attribute that applies only to standard forms. These attributes are as follows:

Data Binding As standard forms possess both the data-entry characteristics of a Log Call form and the viewing characteristics of a Call Details form, the idea of “data binding” in standard form customisation becomes one that reflects the characteristics of both forms.

In the case of a writeable form field that is bound to a column in the Main Details Table, the result of such an association when a new or updated record has been saved is that the data item the analyst will have entered into the field would end up in that table column in the record. Conversely, when a form is opened, whatever data item exists in a given column of a table record will be displayed in the form field bound to that column; this would apply to both Main Details Table and Related Table records.

If a field is bound to a column in a Related Table, it will not be writeable and can only act like a result field on resolution of a record from that table. Resolution can occur both on entering key data into the form during the process of creating a new record in the Main Details Table, and on opening the form to display an existing record. The column containing the primary key data that will resolve the Related Table record is defined in the Main Details Column field in the Associated Tables tab of the form configuration.

For the various different kinds of form objects that can be bound to table columns, the allowed Data Binding formats and their meanings would be exactly the same here as in a Log Call form layout. The comments concerning label names are also equally valid here.

Mandatory This specifies whether or not analysts will be obliged to enter data (directly or indirectly) into the field before saving the contents of the form. A True setting will not allow the displayed data to be saved if the field remains empty.

Standard Forms

133

Actions Menu Item This is applicable to command buttons on a standard form only. Any text you enter here will have the effect of creating a corresponding command with that name in the Actions menu of the form.

Creating and Integrating New Standard Form TypesIf there is a requirement to be able to create and update records in existing managed tables using forms with a different configuration or design, all you would probably have to do is customise the existing forms. However, if you have created completely new tables that now require forms for creating and updating their records, you will need to create additional standard form types, and to then customise these appropriately.

When you create a new standard form type in a given data dictionary, you basically give it a name by which the system can recognise it. Initially, the new form will just have the essential requirements configured, and will contain the chosen fields in arbitrary positions and with default attributes, so you will have to further configure the options, and further design the layout you actually want. Once you have the form that you require, you must integrate it into the Supportworks system so as to allow analysts to use it.

To Create a New Form

A standard form type can be one that does not have tabs or one that does. You use the Form wizard to create either variant.

Before you start, you must ensure that the client is switched to the data dictionary in which you wish to create the new form.

To start the Form wizard, select, from the Administration menu of the main client window, Forms > New Form. Alternatively, you could select Forms > Browse Forms and then click New. Either way, the first page of the wizard is displayed.

Standard Forms

134

Select either Non-Tabbed Form or Tabbed Form, depending on whether you want to create a form without tabs or with tabs. The two separate creation procedures are described in the subsections To Create a Non-Tabbed Form below and To Create a Tabbed Form on page 139, respectively.

To Create a Non-Tabbed Form

The procedure, using the Form wizard, for creating a standard form type without tabs is as follows:

1. Once you have selected Non-Tabbed Form on the first page of the wizard, click Next.

Standard Forms

135

2. In the Main Details Table field, select the main database table that is to be associated with the form.

3. If you want relational data in other tables to be resolved by the form as well, you must specify these in the Related Tables area. To specify a Related Table, click Add and, in the Add Associated Table dialogue box, select that table by name and click OK.

Having created a list of Related Tables, you must then highlight each of these in turn and select the particular column in the Main Details Table that is to act as the primary key for that Related Table.

4. Click Next.

Standard Forms

136

5. In the Table field, select each associated table in turn and, in the Columns to be Represented field, enable each table column that is to be represented on the form as a field. These fields (together with the corresponding Display Name labels) will be placed automatically on to the form layout, as you will discover later. Note that you will still be able to use the Field Chooser in the Form Designer to subsequently add any extra fields.

6. Click the Form Layout field to display the Layout Scheme dialogue box.

Standard Forms

137

7. In this dialogue box, you can define the overall structure of the form. Firstly, ensure that the Form Element Type selected is Data Fields, which defines a standard form style with fields, rather than a table-browser style with listed records.

Secondly, if you want the form to contain a place-holder for an (as yet unspecified) illustrative image, enable the first checkbox option and select a suitable position for that image.

Thirdly, if (as yet unspecified) command buttons are required on the form, enable the second checkbox option, select a suitable position for the buttons, and indicate how many of them there should be.

8. Click OK to close the Layout Scheme dialogue box.

9. Click Next.

Standard Forms

138

10. In the Form Name field, type a unique identifying name for the new form. If you wish, you can continue with the existing naming convention of using the prefix “Ef” for non-tabbed forms. Note that periods (.), slashes (\ or /) and question marks (?) are not allowed in the form name.

11. In the Description field, type an appropriate description for the new form, indicating its purpose. It will be visible in the Browse Forms dialogue box.

12. If you do not wish to preview the form right now, disable the checkbox option.

13. Click Finish. If the relevant checkbox option was enabled, a brand new form is displayed, with the overall layout and specific fields you have chosen.

14. In all probability, you will now (or at a subsequent time) need to make further adjustments to the form’s settings and layout. Please refer to the subsection To Complete the Form Configuration and Design on page 144.

15. Close the form and save the current data dictionary.

Once the new form is complete, it is ready to be integrated into the system for use by authorised members of the support team, as described in To Integrate the New Form(s) into the System on page 145.

Standard Forms

139

If the form for creating records is required to be different to the one for viewing/updating records, you have to carry out the above procedure twice – once for each version of the form.

To Create a Tabbed Form

The procedure, using the Form wizard, for creating a standard form type with tabs is as follows:

1. Once you have selected Tabbed Form on the first page of the wizard, click Next.

2. In the first field, specify the number of tab pages that the form should have.

3. Below that, specify whether the tabs should be of a standard (plain) or coloured style.

4. Click Next.

Standard Forms

140

5. In the Main Details Table field, select the main database table that is to be associated with the form.

6. If you want relational data in other tables to be resolved by the form as well, you must specify these in the Related Tables area. To specify a Related Table, click Add and, in the Add Associated Table dialogue box, select that table by name and click OK.

Having created a list of Related Tables, you must then highlight each of these in turn and select the particular column in the Main Details Table that is to act as the primary key for that Related Table.

7. Click Next.

Standard Forms

141

8. With the first tab of the proposed form selected, define its label by typing suitable text in the Tab Label field.

9. In the Table field, select each associated table in turn (as appropriate to the tab concerned) and, in the Columns to be Represented field, enable each table column that is to be represented on the tab as a field. These fields (together with the corresponding Display Name labels) will be placed automatically on to the tab’s layout, as you will discover later. Note that you will still be able to use the Field Chooser in the Form Designer to subsequently add any extra fields to the tab.

10. Click the Tab Layout field to display the Layout Scheme dialogue box.

Standard Forms

142

11. In this dialogue box, you can define the overall structure of the tab. Firstly, in the Form Element Type field, select either Data Fields, which defines a standard form style with fields, or SQL List, which defines a table-browser style with listed records.

Secondly, if you want the tab to contain a place-holder for an (as yet unspecified) illustrative image, enable the first checkbox option and select a suitable position for that image.

Thirdly, if (as yet unspecified) command buttons are required on the tab, enable the second checkbox option, select a suitable position for the buttons, and indicate how many of them there should be.

12. Click OK to close the Layout Scheme dialogue box.

13. Repeat step 8 to step 12 for each of the tabs in turn.

14. Click Next.

Standard Forms

143

15. In the Form Name field, type a unique identifying name for the new form. If you wish, you can continue with the existing naming convention of using the prefix “Tf” for tabbed forms. Note that periods (.), slashes (\ or /) and question marks (?) are not allowed in the form name.

16. In the Description field, type an appropriate description for the new form, indicating its purpose. It will be visible in the Browse Forms dialogue box.

17. If you do not wish to now preview the form, disable the checkbox option.

18. Click Finish. If the relevant checkbox option was enabled, a brand new form is displayed, with the overall layout and specific fields you have chosen.

19. In all probability, you will now (or at a subsequent time) need to make further adjustments to the form’s settings and layout. Please refer to the subsection To Complete the Form Configuration and Design below.


Once the new form is complete, it is ready to be integrated into the system for use by authorised members of the support team, as described in To Integrate the New Form(s) into the System on page 145.

Standard Forms

144

If the form for creating records is required to be different to the one for viewing/updating records, you have to carry out the above procedure twice – once for each version of the form.

To Complete the Form Configuration and Design

The form type you have generated by means of the Form wizard will almost certainly require additional configuration and further design modification. The following procedure covers what may be broadly necessary:

1. If you are still displaying the previewed form, go directly to the next step. Otherwise, first select Administration > Forms > Browse Forms in the main client window to display the following dialogue box:

Highlight the name of the required form and click Open Form (or just double-click the name). The following dialogue box is displayed:

Standard Forms

145

Normally, you would want the option to open a blank form to remain selected. However, if the associated tables already contain records, you may wish to display the form complete with data values. In that case, you would select the option to open a form with a key value, and then enter the actual key value that would select the required record.

If you have been undertaking JavaScript development on a form and you find that you have broken the code to such an extent that you cannot even open the form, you can click the checkbox in the dialogue box to disable JavaScript execution.

Click OK to open the form.

2. Click the Configure This Form button on the form’s toolbar (or right-click anywhere in the title bar and select Configure This Form from the menu that appears).

3. Use the Form Configuration tool to enable the form options you require, and to complete the configuration of the tables you have associated with the form. For details, see the section entitled Attributes Handled in the Standard Form Configuration on page 125. Note that, for a new form, it is essential that you enable the toolbar or the menu bar in order to allow records to be saved.

4. Click Apply, and then OK to close the Form Configuration tool.

5. Click the Design Form Layout button on the toolbar (or right-click anywhere in the title bar of the form and select Design Form Layout from the menu).

6. In the Form Designer, drag the automatically generated objects to their required positions, and insert any others you may require into the form. Then customise the attributes of objects as necessary. For details, see the section entitled Attributes Handled in the Form Designer on page 131.


To Integrate the New Form(s) into the System

Any new form you may have created will be useless until it is integrated into the system so as to be accessible by authorised analysts. An essential part of such integration involves creating a new hierarchy of Manage commands in the main client window’s File menu that analysts will be able to use for displaying the

Standard Forms

146

new record-creation form, and for displaying the browser from which the new record-viewing/updating form will be launched. For details of how to create and customise Manage commands, please see the “Manage” Commands chapter.

To support a record-creation function, a Manage parent command needs to have an “Add New” type of child command below it. As indicated in Attributes Relevant to “Manage” Commands on page 173, this is achieved by giving the child command a suitable name in the New Record Menu Text attribute field of the relevant Managed Entities item in the Data Dictionary Editor, and selecting the identifier of the new record-creation form in the Add Record Form field.

For a “Manage” parent command to ultimately support a record-viewing/updating function, there is first a pre-requisite that the records intended for viewing or updating may actually be located, which means that a browser of a suitable type, configured to invoke the relevant record-viewing/updating form, must exist. For details of how to create and customise browsers, please refer to the chapters Table Browsers, SQL Tree Browser Forms and SQL Tree Browsers. Secondly, the parent command needs to have a “Browse” type of child command below it to invoke that browser. As indicated in Attributes Relevant to “Manage” Commands on page 173, this is achieved by giving the child command a suitable name in the Browse Menu Text attribute field of the relevant Managed Entities item in the Data Dictionary Editor, and selecting the identifier of the relevant browser in the Browse Form field.

If you want a form you have created to open in all other situations where record creation and/or viewing/updating is called for, you must suitably customise the relevant table in the Database section of the Data Dictionary Editor. As indicated in Table-Level Attributes on page 41, you would simply select the relevant form identifier in the Add Record Form and/or Edit Record Form attribute field(s) for the table item concerned. If you have created a single form for both functions, you would select the identifier of that form for each of these two fields.

Once you have integrated a new form into the system, analysts will be able to display it in all relevant situations.

Table Browsers

147

Table Browsers

A table browser is a “Browse entities” dialogue box that lists the records from a given managed table and allows you to select one for display in a standard (Properties) form. In fact, a table browser is simply a standard form containing an SQL list and appropriate buttons. Table browsers, like record-creation forms, are accessible via the Manage commands (in the main client window’s File menu) that relate to the relevant managed tables. For browsers, the relevant sub-command below Manage would be “Browse” or something similar.

Of the two kinds of record browser available to you, the table browser is the preferred choice in any case where the number of records in the table is not too large, and there is no requirement to browse by various different categories and/or to conduct table searches. In the Default data dictionary, table browsers exist for the following tables:

• The Charge Centre table

• The Customer table

• The Asset table (if used)

• The Manufacturer table

• The Generic Type table (if used)

• The Supplier table

• The Site table

You can customise table browsers by means of the same kinds of tools as for standard forms: the standard Form Configuration tool, and the Form Designer. As a table browser is actually a special kind of form, the changes you can make in both cases are identical, although certain kinds of attributes may be appropriate to one and not the other. The Forms category viewable in the Data Dictionary Editor does, in fact, show table browsers as well as forms.

In corresponding fashion, it is not possible to use the Data Dictionary Editor for table-browser customisation, but you can use it to see which table browsers are available in the current data dictionary.

Table Browsers

148

An alternative way of finding and selecting managed-table records is via a tree browser, or via a search mechanism. Customisation of these kinds of mechanisms is covered in the chapter SQL Tree Browser Forms on page 155.

Attributes Relevant to Table Browsers in the Standard Form ConfigurationAll the attributes available in the Settings tab of the standard Form Configuration dialogue box have exactly the same meanings for a table browser as they do for a true form. See Attributes In the Settings Tab for Standard Forms on page 126 for details. However, you should ignore the Associated Tables tab completely for a table browser, as none of the attributes there are relevant. The table associated with a table browser would, in fact, be defined by the Table attribute of the SQL List object contained in the browser.

Attributes Relevant to Table Browsers in the Form DesignerAlthough you could theoretically insert any kind of form object into a table browser, in practice you would probably only wish to have an SQL list and the relevant buttons. See Attributes Handled in the Form Designer on page 71 for descriptions of the attributes of all possible form and table-browser objects.

Creating and Integrating New Table BrowsersIf there is a requirement to be able to find records in existing managed tables using new designs of table browser, all you would have to do is customise the existing browsers. However, if you have created completely new tables that now require their own table browsers for the purpose of looking for records, you will need to create additional table browsers and then customise these appropriately.

When you create a new table browser in a given data dictionary, you basically give it a name by which the system can recognise it. Initially, the new table browser will contain an SQL list with the chosen columns and a standard

Table Browsers

149

selection of buttons, all in default positions and with default attributes. If this is not acceptable, you will have to further configure the required options, and further design the required layout, appropriately. Once you have the browser that you want, you must integrate it into the Supportworks system so as to allow analysts to display it.

To Create a New Table Browser

The procedure to create a new table browser is much the same as the procedure for creating a new standard form. Again, you would use the Form wizard, as follows:

1. Ensure that the client is switched to the data dictionary in which you wish to create the new table browser.

2. From the Administration menu of the main client window, select Forms > New Form. Alternatively, you could select Forms > Browse Forms and then click Add. Either way, the first page of the wizard is displayed.

3. Select the Table Browser option and click Next.

Table Browsers

150

4. In the New Record Form field, select the name of the form that is to be displayed when the user clicks the New button on the table browser.

5. In the Edit Record Form field, select the name of the form that is to be displayed when the user highlights a record and clicks the Properties button (or double-clicks a record) on the table browser.

6. Click Next.

Table Browsers

151

7. In the Main Details Table field, select the database table from which the records to be displayed on the browser list are to be taken.

8. Click Next.

Table Browsers

152

9. In the Columns to be Represented field, enable the table columns that are to be visible on the browser’s SQL list.

10. Click Next.

Table Browsers

153

11. In the Form Name field, type a unique identifying name for the new table browser. If you wish, you can continue with the existing naming convention of using the prefix “Tb”. Note that periods (.), slashes (\ or /) and question marks (?) are not allowed in the browser name.

12. In the Description field, type an appropriate description for the new table browser, indicating its purpose. It will be visible in the Browse Forms dialogue box.

13. If you do not wish to preview the table browser right now, disable the checkbox option.

14. Click Finish. If the relevant checkbox option was enabled, a brand new table browser is displayed, complete with an SQL list containing the columns you have chosen and four standard buttons.

15. In all probability, you will not need to make any further adjustments to this default browser’s settings or layout, in which case you should go directly to step 18. However, if you are dissatisfied with the default browser in some way, you should proceed to the next step.

Table Browsers

154

16. If your dissatisfaction lies in the form configuration, first right-click anywhere in the title bar and select Configure This Form from the menu that appears.

Use the Settings tab of the Form Configuration tool to enable the browser options you require. For details, see the section entitled Attributes In the Settings Tab for Standard Forms on page 126.

17. If you wish to change certain elements of the browser’s design, right-click anywhere in the title bar and select Design Form Layout from the menu.

Use the Form Designer to reposition objects in the browser, to insert any additional objects and to customise object attributes as necessary. For details, see the section entitled Attributes Relevant to Table Browsers in the Form Designer on page 148.

18. Close the table browser and save the current data dictionary.

The new table browser is now ready to be integrated into the system for use by authorised members of the support team, as described in the subsection below.

To Integrate a New Table Browser into the System

Integration of a table browser into the system is simply a matter of specifying the browser against the relevant Manage command hierarchy in the File menu. As indicated in the section entitled Attributes Relevant to “Manage” Commands on page 173, you would select the browser in the Browse Form attribute field of the appropriate Managed Entities item in the Data Dictionary Editor.

SQL Tree Browser Forms

155


An SQL tree browser form is a “Find entity” dialogue box containing (by default) a Browse tab and a Search tab, each of which has facilities allowing you to find records in a specific table by a distinct means. SQL tree browser forms, like table browsers (which could alternatively be used), are accessible via the Manage commands, in the main client window’s File menu, that relate to the relevant managed tables. Once again, the relevant sub-command below Manage would be “Browse” or something similar.

In addition, an SQL tree browser form would be displayed when you select any command (such as Change Customer or, where relevant, Change Asset), from the Show Me menu on the Log Call or Call Details form, whose action type is configured as Tree Browser Form. In this case, there would be no table-browser alternative available.

The Browse tab within a form displays a tree browser that lists the records from a given managed table in a categorised, hierarchical manner and allows you to select one for display in a standard (Properties) form. The Search tab allows you to conduct searches for records by specific criteria and, from the results, select one for display in the same kind of form.

In contrast to table browsers (covered in the previous chapter), SQL tree browser forms invoked via Manage commands are normally used in those cases where there are large numbers of records in the tables concerned, and where records need to be selected from categories and/or from the results of searches. If, for example, your Customer table is browsed using a table browser and, over time, you find that it has grown to such an extent as to make simple browsing unwieldy, you can create a suitable SQL tree browser form and switch to using that one.

You would customise SQL tree browser forms, or create new ones, by using the Data Dictionary Editor. The customisation is in two parts, the first of which defines the overall structure of the dialogue box and the attributes of the Search tab, and the second of which defines the attributes of the Browse tab specifically. The first part would be performed in the SQL Tree Browser Forms section of the


156

editor, while the second (described in the next chapter) would be carried out in the SQL Tree Browsers section.

Attributes Relevant to the Entire Dialogue Box and the Search TabWithin the SQL Tree Browser Forms section of the data dictionary, you can view and modify the structural attributes of any “Find entity” dialogue box used for locating records in a specific table, as well as the attributes of its Search tab. The structural attributes include the dialogue box’s title, its size, its tab specification and an indication of the tree browser to use. The search-related attributes include a search filter, an indication of the table to be searched and definitions of the required search fields and result columns.

When you expand the SQL Tree Browser Forms category in the left-hand pane of the Data Dictionary Editor, all the items representing the existing “Find entity” dialogue boxes are revealed. For the Default data dictionary, the dialogue boxes concerned would be the two entitled “Find Customer” and “Find Asset”, respectively. Select the required item to show its attributes in the right-hand pane.


157

All items have the same set of attributes that you can individually customise. Their meanings are as follows:

Name This is the name of the selected item, as displayed in the left-hand pane. It is used only within the Data Dictionary Editor.

Title This is the title of the dialogue box represented by the selected item.

Width, Height This specifies the dimensions of the dialogue box.

Search Type This determines the combination of tabs to be shown in the dialogue box. You have a choice of either the Browse tab or the Search tab on its own, or of both tabs in either order (left to right, with the left-hand tab always the one displayed by default).

Search Criteria This specifies, in the form of an SQL expression, which records are to be included in, or excluded from, any search conducted from the dialogue box’s Search tab. A null entry here means that all records are to be included.

Table This specifies the table to be searched in any search conducted from the dialogue box’s Search tab.


158

Tree Browser This identifies the tree browser to be displayed in the dialogue box’s Browse tab. Creation and customisation of tree browsers are covered in the chapter entitled SQL Tree Browsers.

Search Fields A, B The items here define the two blocks of fields by which records in the table can be searched. The fields are specified as names of columns in the table. Search Fields A relates to the left-hand block of fields in the Search tab, while Search Fields B relates to the right-hand block. For either of these attributes, when you click anywhere in its field, a button appears on the right. Clicking this button displays the following dialogue box:

In this dialogue box, you can specify which search fields are to be included in the block concerned. To add fields to the block, make a suitable selection in the Available Columns list and click Add. To remove fields from the block, select these in the Included Columns list and click Remove. In both cases, you can use the Control and Shift keys in the usual way to appropriately extend your selection. Note that the top-down order of the items in the Included Columns list determines exactly the order in which the search fields are displayed in the block. Once the required fields are in place, click OK.

Result Columns The items here define the table columns that are to be displayed in the Search Results area of the Search tab. When you click anywhere in this attribute field, a button appears on the right. Clicking this button displays the same dialogue box as the button in Search Fields A and Search Fields B, this time allowing you to specify the table columns to be included in the search results.


159

Attributes Relevant to the Browse TabThe Browse tab in an SQL tree browser form contains the actual tree browser (which is shared with the relevant database entity view). To view and modify the attributes of the Browse tab, you will need to go into the SQL Tree Browsers section of the Data Dictionary Editor. See the chapter entitled SQL Tree Browsers for details.

Creating and Integrating New SQL Tree Browser FormsIf there is a requirement to be able to find records in existing managed tables using new designs of SQL tree browser forms, all you would probably have to do is customise the existing SQL tree browser forms. However, if you have created completely new tables that now require their own SQL tree browser forms for the purpose of looking for records, you will need to create additional SQL tree browser forms and then customise these appropriately.

When you create a new SQL tree browser form in a given data dictionary, you basically give it a name by which the system can recognise it. Initially, the new tree browser form will be devoid of all characteristics, so you will have to configure the required options, and design the required layout, from scratch. Once you have the form that you want, you must integrate it into the Supportworks system so as to allow analysts to display it.

To Create a New SQL Tree Browser Form

The procedure to create a new SQL tree browser form is as follows:

1. Ensure that the client is switched to the data dictionary in which you wish to create the new SQL tree browser form.

2. Run the Data Dictionary Editor and select File > New > SQL Tree Browser Form.

3. At the displayed prompt, type a suitable name for the new SQL tree browser form and click OK. Notice that a new item of that name has appeared under the SQL Tree Browser Forms category.


160

4. With the new form item highlighted, proceed to customise it with the aid of the information given in Attributes Relevant to the Entire Dialogue Box and the Search Tab on page 156.

5. Save the customised attributes and close the Data Dictionary Editor.

The new SQL tree browser form is now ready to be integrated into the system for use by authorised members of the support team.

To Integrate a New SQL Tree Browser Form into the System

When you are ready to integrate an SQL tree browser form into the system, there are two aspects to consider, reflecting the two separate usages of such a form.

Firstly, there is the integration of the form into the relevant Manage command hierarchy in the client’s File menu. As indicated in the section entitled Attributes Relevant to “Manage” Commands on page 173, you would select the SQL tree browser form in the Browse Form attribute field of the appropriate Managed Entities item in the Data Dictionary Editor. Thus, if you currently have a table browser selected here and you want to switch to a suitable SQL tree browser form you have created, all you have to do is select it.

Secondly, there is the creation, on each call form where the requirement exists, of new Show Me menu commands to invoke the SQL tree browser form. This integration is carried out in the Log Call and Call Details form configuration. As indicated in the section entitled Attributes in the ‘Show Me’ Items Tab for Log Call Forms on page 63, you would first use the Add button to generate a new Show Me item. You would then customise this by selecting Tree Browser Form as the action type, selecting the SQL tree browser form in the Browser field, and defining a suitable filter if required.

SQL Tree Browsers

161

SQL Tree Browsers

An SQL tree browser is a user-interface element that lists the records from a given managed table in the form of hierarchical categories, and allows you to select one, typically, for display of its details in a standard (Properties) form or on an active page. It is found in three different kinds of places on the client:

• In the Browse tabs of SQL tree browser forms

• In all database entity views (such as the Customers view) that have a Browse mode

• When you are editing an issue and you invoke the command to log a call automatically for another customer and add it to the issue

The hierarchical structure of an SQL tree browser lends itself naturally to the display of multiple groupings, at ever-decreasing levels, of the entities whose records are held in the table. This makes it easier, if analysts are aware of the groupings to which entities belong, for them to find a particular record from among a large number and, in such circumstances, gives the tree browser a distinct speed advantage over the table browser (which simply lists all the records consecutively). For example, with customer records, it is possible to group the entities by site, by charge centre, and/or by any other meaningful elements that exist as columns in the Customer table.

You would use the Data Dictionary Editor to customise an SQL tree browser or create a new one. When you customise a tree browser, you can, for example, modify the set of sub-groupings under any main grouping, and you can also add new groupings and delete existing ones. The attributes you can customise are actually on two tiers: the browser tier and the group tier.

Attributes Relevant to the Browser TierThe customisable attributes on the browser tier of an SQL tree browser relate to the browser as a whole.

When you expand the SQL Tree Browsers category in the left-hand pane of the Data Dictionary Editor, all the items representing the existing tree browsers are

SQL Tree Browsers

162

revealed. For the Default data dictionary, the tree browsers concerned would be the two entitled “Customers” and “Assets”, respectively. Select the required item to show its attributes in the right-hand pane.



Table This attribute is currently not used.

Visible Columns This attribute is currently not used.

Image List This identifies the image list from which the icons used to distinguish between the main groupings within the selected browser are to be taken. The list would be any of those available in the Image Lists section of the data dictionary.

Attributes Relevant to the Group TierThe customisable attributes on the group tier of an SQL tree browser relate to the displayed groupings under which records may be browsed.

SQL Tree Browsers

163

When you expand one of the browser items (such as “Customers”) in the SQL Tree Browsers section of the Data Dictionary Editor, all the main browse groupings that exist in the browser are revealed. In a default installation, the groupings concerned would be the three entitled “Entire Customer Database”, “Customers by Site” and “Customers by Charge Centre”, respectively. Select the required item to show its attributes in the right-hand pane.

Name This is the name of the selected grouping, as displayed in the left-hand pane. It identifies this grouping within the browser, where it would be shown as the topmost item in the tree.

Table This specifies the managed table whose records are to be displayed under the selected grouping.

Columns This defines the browse hierarchy that is contained within the selected grouping. It is specified in terms of the relevant columns from the managed table, arranged in the required order. The leftmost column here corresponds to the uppermost level within the main grouping as displayed in the browser, with successive columns corresponding to successively lower levels. When you click anywhere in this attribute field, a button appears on the right. Clicking this button displays the following dialogue box:

SQL Tree Browsers

164

In this dialogue box, you can specify which hierarchical levels are to be included in the grouping concerned. To add levels to the grouping, make a suitable selection in the Available Columns list and click Add. To remove levels from the grouping, select these in the Included Columns list and click Remove. In both cases, you can use the Control and Shift keys in the usual way to appropriately extend your selection. However, to maintain a particular order, you would generally have to add the levels one by one. The top-down order of the items in the Included Columns list determines exactly the hierarchical order as displayed in the browser. It is up to you to ensure that the uppermost level relates sensibly to the main grouping as a whole, and that successive levels below this represent ever narrower sub-groupings. Once the required levels are in place, click OK.

Criteria This specifies, in the form of an SQL expression, which records are to be included in, or excluded from, the selected grouping. A null entry here means that all records are to be included.

Image This specifies the icon to be displayed next to the name of each level of the selected grouping. The icon should ideally illustrate the meaning of that grouping.

Creating and Integrating New SQL Tree BrowsersIf there is a requirement to be able to browse through existing managed tables using new designs of SQL tree browser, all you would probably have to do is customise the existing SQL tree browsers. However, if you have created completely new tables that now require their own SQL tree browsers for the

SQL Tree Browsers

165

purpose of looking for records, you will need to create additional SQL tree browsers and then customise these appropriately.

When you create a new tree browser, you basically give it a name by which the system can recognise it. Initially, the new tree browser will be devoid of all characteristics, so you will have to configure the required attributes from scratch. Once you have the browser that you want, you must integrate it into the relevant database entity view and/or SQL tree browser form.

To Create a New SQL Tree Browser

The procedure to create a new SQL tree browser is as follows:

1. Ensure that the client is switched to the data dictionary in which you wish to create the new SQL tree browser.

2. Run the Data Dictionary Editor and select File > New > SQL Tree Browser.

3. At the displayed prompt, type a suitable name for the new SQL tree browser and click OK. Notice that a new item of that name has appeared under the SQL Tree Browsers category.

4. With the new browser item highlighted, proceed to customise it with the aid of the information given in Attributes Relevant to the Browser Tier on page 161.

5. You now need to create one or more suitable groupings within the browser. With the new browser item still highlighted, select File > New > SQL Tree Browser Root Group Item.

6. At the displayed prompt, type a suitable name for the required grouping and click OK. Notice that a new item of that name has appeared under the browser item.

7. With the new grouping item highlighted, proceed to customise it with the aid of the information given in Attributes Relevant to the Group Tier on page 162.

8. If you wish to create more groupings within the same browser, repeat step 5 to step 7 an appropriate number of times.


SQL Tree Browsers

166

The new SQL tree browser is now ready to be integrated into the database entity view and/or SQL tree browser form of your choice.

To Integrate a New SQL Tree Browser into a Database Entity View

Integration of an SQL tree browser into a database entity view is part of the process of customising the view that is to use this browser, and is simply a matter of specifying the browser against that view. As indicated in the section entitled Attributes Relevant to Individual Database Entity Views on page 203, you would select the browser in the Tree Browser attribute field of the appropriate Database Entity Views item in the Data Dictionary Editor.

To Integrate a New SQL Tree Browser into an SQL Tree Browser Form

Integration of an SQL tree browser into an SQL tree browser form is part of the process of customising the SQL tree browser form that is to use this browser, and is simply a matter of specifying the browser against that form. As indicated in the section entitled Attributes Relevant to the Entire Dialogue Box and the Search Tab on page 156, you would select the browser in the Tree Browser attribute of the appropriate SQL Tree Browser Forms item in the Data Dictionary Editor.

Pick Lists

167

Pick Lists

A pick list is a dialogue box, similar in appearance to a table browser, that is displayed whenever you have entered ambiguous data into a customer field or (where relevant) an asset field on the Log Call or Call Details form. It allows you to select exactly the table record you want from among the narrowed-down possibilities, following which the relevant details area on the form is auto-populated with data from that record.

A pick list can be displayed also when you select any command, from the Show Me menu on the Log Call or Call Details form, whose action type is configured as Pick List. In this case, too, the pick list would allow you to select a record, from the displayed subset, whose data would then auto-populate the designated customer-details or (if relevant) asset-details area on the call form.

You would use the Data Dictionary Editor to customise a pick list or create a new one.

Attributes Relevant to Pick ListsWithin the Pick Lists section of the data dictionary, you can view and modify the attributes of any pick list used for locating records in a specific table. The attributes include the dialogue box’s title, its size, an indication of the table that is to provide the records, a filter specification for these, and definitions of the columns to display. There is also an indication of the respective forms to use for looking at any of the listed records in detail, and for creating new records in the table.

When you expand the Pick Lists category in the left-hand pane of the Data Dictionary Editor, all the items representing the existing pick-list dialogue boxes are revealed. For the Default data dictionary, the dialogue boxes concerned would be the two entitled “Choose Customer” and “Select Product”, as well as two unused ones relating to charge centres and sites, respectively. Select the required item to show its attributes in the right-hand pane.

Pick Lists

168

All pick-list items have the same set of attributes that you can individually customise. Their meanings are as follows:


Title This is the title of the pick-list dialogue box represented by the selected item.

Table This specifies the managed table from which records are to be displayed on the pick list.

Properties Form This specifies the standard form that is to be displayed when the analyst clicks the Properties button on the pick list to view a record from the table in more detail (or to update it) before deciding to choose it.

Add Record Form This identifies the standard form that is to be displayed when the analyst clicks the New button on the pick list to add a new record to the table before choosing it.

Visible Columns This defines the table columns that are to be shown in the display of records on the pick list. When you click anywhere in this attribute

Pick Lists

169

field, a button appears on the right. Clicking this button displays the following dialogue box:

In this dialogue box, you can specify which columns are to be included in the pick list. To add columns to the pick list, make a suitable selection in the Available Columns list and click Add. To remove columns from the pick list, select these in the Included Columns list and click Remove. In both cases, you can use the Control and Shift keys in the usual way to appropriately extend your selection. Once the required columns are in place, click OK.

Filter This specifies, in the form of an SQL expression, which records are to be included in, or excluded from, any display of records on the pick list. A null entry here means that all records are to be included.

Width, Height This specifies the dimensions of the pick-list dialogue box.

Creating and Integrating New Pick ListsIf, for any data dictionary, there is a requirement to use different variants of pick lists in different contexts, perhaps because a newly created table now has to provide data for auto-populating a certain part of a particular call form, you will need to create additional pick lists, and to then customise these appropriately.

When you create a new pick list, you basically give it a name by which the system can recognise it. Initially, the new pick list will be almost totally devoid of any characteristics, so you will have to configure the required attributes from scratch. Once you have the pick list that you want, you must integrate it into the

Pick Lists

170

Supportworks system so that it will be displayed wherever and whenever it is needed.

To Create a New Pick List

The procedure to create a new pick list is as follows:

1. Ensure that the client is switched to the data dictionary in which you wish to create the new pick list.

2. Run the Data Dictionary Editor and select File > New > Pick List.

3. At the displayed prompt, type a suitable name for the new pick list and click OK. Notice that a new item of that name has appeared under the Pick Lists category.

4. With the new pick-list item highlighted, proceed to customise it with the aid of the information given in Attributes Relevant to Pick Lists on page 167.


The new pick list is now ready to be integrated into the system for display, as necessary, in the Supportworks client.

To Integrate a New Pick List into the System

When you are ready to integrate a pick list into the system, there are two aspects to consider, reflecting the two separate usages of such a list.

Firstly, there is the integration of the pick list into each call form that is expected to display it on ambiguous data entry. This is part of the process of customising the attributes of a Related Table in the call form configuration. As indicated in Table Properties: Miscellaneous on page 59, it is simply a matter of specifying, within the Associated Tables tab, the pick list in the Record Pick List field for the Related Table concerned.

Secondly, there is the creation, on each call form where the requirement exists, of new Show Me menu commands to invoke the pick list. As indicated in the section entitled Attributes in the ‘Show Me’ Items Tab for Log Call Forms on page 63, you would first use the Add button to generate a new Show Me item. You would then customise this by selecting Pick List as the action type,

Pick Lists

171

selecting the pick list in the Pick List field, and defining a suitable filter if required.

Pick Lists

172

“Manage” Commands

173


“Manage” commands on the Supportworks client are those via which the display of record-creation forms and record-location browsers can be invoked. They are to be found in the File menu of the main client window, and each is arranged hierarchically as a “parent” item with two “children”. The parent command is normally in the format “Manage <entities>”, where <entities> would be something like Customers, reflecting the database entities to be managed. The child commands would typically be named “Add New” and “Browse”, signifying their form- and browser-opening functions, respectively. For some Supportworks customisations, however, certain child commands will not conform to this kind of functionality.

You would use the Data Dictionary Editor to customise a Manage command hierarchy or create a new one. Within the editor, these hierarchies are known as “Managed Entities”.

Attributes Relevant to “Manage” CommandsWithin the Managed Entities section of the data dictionary, you can view and modify the attributes of any Manage command hierarchy used for invoking the form and browser relating to a specific table. The attributes consist of the relevant command text and indications of the form and browser to invoke.

When you expand the Managed Entities category in the left-hand pane of the Data Dictionary Editor, all the items representing the existing Manage command hierarchies are revealed. For the Default data dictionary, the hierarchies concerned would be:

• Charge Centres

• Customers

• Assets

• Manufacturers

• Generic Types

• Suppliers


174

• Sites

Select the required item to show its attributes in the right-hand pane.

All Managed Entity items have the same set of attributes that you can individually customise. Their meanings are as follows:

Name This is the name of the selected item, as displayed in the left-hand pane. It is incorporated in the name of the parent command.

New Record Menu Text This defines the name of the child command that is to invoke the record-creation form (or, for certain customisations, some other form). By the default convention, it would be Add New for record creation.

Browse Menu Text This defines the name of the child command that is to invoke the record-location browser (or, for certain customisations, some other entity). By the default convention, it would be Browse for record location.

Add Record Form This identifies the record-creation (or other) form to be invoked whenever an analyst selects the relevant “Add New” (or some other) type of child command.


175

Browse Form This identifies the table browser, SQL tree browser or other form to be invoked whenever an analyst selects the relevant “Browse” (or some other) type of child command.

Creating New “Manage” CommandsIf you have created a new managed table for your Supportworks system, together with standard forms with which to create and update records in that table, and a table browser or SQL tree browser form with which to find records in the table, you will need to add, to the client’s File menu, a new Manage command hierarchy by which you can invoke the required form or browser.

When you create a new Manage command hierarchy, you basically give it a name that becomes part of the parent command as seen in the File menu. Initially, the child commands and their functions in the new hierarchy will be undefined, so you will have to configure these attributes from scratch.

The procedure to create a new Manage command hierarchy is as follows:

1. Ensure that the client is switched to the data dictionary in which you wish to create the new Manage command hierarchy.

2. Run the Data Dictionary Editor and select File > New > Managed Entity.

3. At the displayed prompt, type a suitable name for the new Manage command hierarchy. Supportworks convention dictates that this should be in the plural (for example, “Customers”), indicating the kinds of entities to be accessed using the invoked form and browser. The name will be automatically appended to the “Manage” part of the parent command.

4. Click OK. Notice that a new item having the name you typed has appeared under the Managed Entities category.

5. With the new hierarchy item highlighted, proceed to customise it with the aid of the information given in Attributes Relevant to “Manage” Commands on page 173.

6. Save the new Manage command hierarchy and its customised attributes and close the Data Dictionary Editor.


176

You should now be able to see the new Manage command in the File menu of the main client window.

Managing Global Parameters

177


The Global Parameters section of the data dictionary holds customisable parameters relating to a number of different areas of the Supportworks client. Using the Data Dictionary Editor, you can view and modify any of these parameters, and you can also add new entities that will enable certain optional features on the client.

When you expand the Global Parameters folder in the left-hand pane of the editor, all the existing customisable areas of the client are revealed as lower-level folders, some of which can contain further sub-folders.

On selecting a specific folder, you will see that the parameters pertaining to it are displayed in the right-hand pane. The name of each parameter is shown, followed by its value. To customise the operation of the client, you would have to modify the relevant parameter values. In some cases, you may need to add extra parameters with prescribed names and specify values for these.


178

You can enable an optional feature on the client by creating a totally new folder that has the prescribed name. You would create this either within the root Global Parameters folder or within a lower-level folder, depending on whether or not the feature belongs to an area that is already customisable. You would then add prescribed parameters to the new folder one by one, giving each of them the required value.

The generic mechanisms available for managing Global Parameters folders and the parameters held within them are described in the following sections of this chapter. These sections cover the specific controls available to you within Global Parameters when customising any functional area of the Supportworks client or enabling optional features in it, and also provide reference information on the variables you can specify within the SQL filters used in Global Parameters.

Subsequent chapters then describe the specific areas of client functionality that you can customise, and the optional features or controllability you can introduce, using Global Parameters.

Modifying Global Parameter ValuesAlthough the parameters belonging to a given folder may be totally different in nature to those belonging to another folder, the method of modifying them is the same in each case.

The procedure to change the value of a parameter is as follows:

1. With Global Parameters expanded, select the folder or sub-folder corresponding to the client area that has the parameter you wish to modify.

2. In the right-hand pane, double-click the parameter concerned. The following kind of dialogue box is displayed:


179

3. Edit the contents of the Value field as necessary.

4. Click OK. The parameter is updated in memory.

5. If you wish to change any more parameters, just repeat the above actions.

6. Select File > Save to update the data dictionary file on the server.

You can now display the part of the client user interface whose functionality you have modified to check that the new functionality is exactly as you intended. If you were already displaying that part of the interface, you must refresh it in an appropriate way so as to apply the new functionality.

Creating New Folders and ParametersIf you wish to enable certain supported features on the client that are optional, you have to create corresponding folders within Global Parameters, and then create, within each of these, the parameters that the feature requires. For other optional features, you would merely need to create the parameters within an existing folder. When supplying the name for a new folder or parameter, it is important that you type it exactly as prescribed for the feature concerned. (The actual names to use are defined in the chapters that describe the specific optional features.)

The general procedure to enable a feature by adding the necessary folder and parameters (or just the parameters) is as follows:

1. If enabling the required feature just entails the addition of parameters to an existing folder or sub-folder within Global Parameters, select that folder and go directly to step 6.

2. With Global Parameters expanded or otherwise (as appropriate), select the folder that is to contain the one you are about to create. If the new feature is going to reflect a completely new customisable area of the client, the folder to select would be Global Parameters itself. If, on the other hand, the new feature belongs to an existing customisable area, you would select the sub-folder relating to that.

3. Select File > New > Folder from the menu bar.


180

4. At the New Folder prompt that is then displayed, type the prescribed name for the folder.

5. Click OK, and observe the new folder appearing in the appropriate place in the left-hand pane.

6. With the folder highlighted, click in the right-hand pane and press the Insert button. Alternatively, you could select File > New > String Value (or Numeric Value, as required). The Add New Value dialogue box is displayed, allowing you to add a parameter and its value to the folder.

7. In the Name field, enter the prescribed name for the first parameter that is to be included in the folder.

8. In the Value field, enter the required string or number value for the parameter. The format in which you enter this value should be appropriate to the type of parameter concerned.

9. In the Type field, ensure that the relevant value type is selected, depending on whether the value you entered was a string or a number. (If you had invoked this dialogue by selecting String Value or Numeric Value, the Type field would already be set appropriately.)

10. Click OK, and observe the new parameter appearing in the right-hand pane.

11. Repeat step 6 to step 10 for each further parameter required.

12. Click the Save button (or select File > Save) to update the data dictionary file on the server.

You can now display the part of the client user interface where you have introduced the new feature. If you were already displaying that part of the interface, you must refresh it in an appropriate way so as to apply the new functionality.


181

Creating a New Folder Based on an Existing Folder

Instead of creating a blank folder as described in step 2 to step 5 above, you can create a copy of an existing folder at the same level as that folder. This is useful if you need to add simply a variant of a specific folder to Global Parameters, particularly where the new folder is to represent an additional workspace view of a given type (or an additional tab in a Helpdesk type of view). The copy will contain exactly the same parameters and values as the original folder, and also the same sub-folders if any exist. You can then modify the folder’s contents to any desired degree.

The procedure for creating a copy of an existing folder is as follows:

1. Expand Global Parameters to show the folder on which you wish to base the new folder and select it.

2. Select File > New > Copy of Selected Folder.

3. At the displayed prompt, think of a suitable name for the new folder and enter it.

4. Click OK, and observe the new folder appearing in the appropriate place in the left-hand pane.

5. In the new folder, make the parameter or value changes you require.

6. Click the Save button (or select File > Save) to update the data dictionary file on the server.

Deleting Folders and ParametersTo delete a folder within Global Parameters, highlight the folder and select Edit > Delete. The deletion is immediate, without any confirmation being requested.

Similarly, to delete a parameter within a folder, highlight the parameter and select Edit > Delete. Alternatively, you could highlight the parameter and press the Delete button on the keyboard. Again, the deletion is immediate, without any confirmation being requested.


182

Using Standard Context Variables in FiltersMany of the folders in Global Parameters can contain a certain kind of parameter known as a “filter”. Filters allow you to specify SQL criteria to limit the visibility of database content to what is required by client sessions using the data dictionary concerned. If you wish, you can use any of the Supportworks standard context variables, listed in Appendix B: Standard Context Variables on page 375, within the SQL expression for a filter.

Defining Active Pages

183


Active pages are those areas of the Supportworks client that display information as in a Web browser. The default pages are generated by PHP scripts residing in the Supportworks server. In the “Active Folder Pages” folder within Global Parameters, there are named parameters representing these scripts, as shown in the following screenshot:

It is these parameters that make the scripts known to the system. Each parameter contains a string value giving the URL of the PHP script that generates the page concerned. By editing such a value so that the URL points to another script, you can make the client display a different page within the given area. This page might be one that you have constructed yourself, or that has been constructed by a consultant. The script can reside on any Web server.

There are two kinds of active-page script that are represented here. The first is one that displays information from the Supportworks database without any record-selection key being required, and the second is one that displays a record selected by a predefinable key. The former type is represented by a parameter


184

whose name begins with an underscore. The chief example of this type is “_default”, which specifies the default error page to use when the requested page is unavailable.

The second type of active page is represented by a parameter whose name consists of the database table column that defines the record-selection key. For example, the parameter named “opencall.callref” represents the active page that displays a selected call record from the opencall table. Another example is provided by the parameter “userdb.site”, which represents the page that displays a site record selected by reference from the userdb table. Active pages of the second type are all displayed in database entity views (Search or Browse mode). A given page would appear when the analyst selects a result entry, an appropriate SQL tree-browser item, or a link on another displayed page.

To make a new browser-selectable active page known to Supportworks, you would need to do the following:

1. Ensure that a new script has been created, and that it resides at a known URL (typically, in the same location as the default scripts – see step 3 below).

2. Create a new browse grouping (or modify an existing grouping) in an appropriate SQL tree browser so as to include a browse hierarchy that contains a level which, when selected by an analyst, would display the page concerned. See the chapter entitled SQL Tree Browsers on page 161 for details.

3. Using the generic method described in Creating New Folders and Parameters on page 179, create a new string parameter in the “Active Folder Pages” folder. Its name should be in the format table.column, where table would be the main table that will be accessed by the database entity view concerned, and column would be the column that contains the key to the records in a related table that will be displayed on the new active page. This column would be the one defining the required level in the relevant browse hierarchy.

If the new script is to run in the Supportworks Web server environment, you can use the macro variable &[app.webroot] at the beginning of the URL to automatically identify the server and the port it uses. Note that clisupp/details is the alias of the following path on the Supportworks main server: C:\Program Files\Hornbill\Supportworks Server\html\clisupp\details. This is where the default scripts are held.

Customising the Workspace Views

185


Workspace views on the client are those that are selected by means of the icons in the shortcut bar. You can customise various aspects of many of these views (including their shortcut icons) by means of facilities provided in the Data Dictionary Editor. You can also create any number of extra instances of any workspace view (complete with shortcut icon) except E-Mail, of which there can only be one.

Views are categorised by type. The respective types and their identifiers are as follows:

Nearly all view customisation is performed wholly within the Global Parameters section of the Data Dictionary Editor, in the “Views” folder. The one exception is database entity views, whose customisation is carried out, for the most part, in

View Type Description View Type Identifier

Views containing an embedded Web page, such as Supportworks Today

webpage

Helpdesk views helpdesk

Calendar views calendar

The E-Mail view mail

Database entity views autodbev

Search For Calls views callsearch

Database Searches views dbsearch

My Library views library

KnowledgeBase views knowledgebase

Management Information and Reporting views

reports


186

the Database Entity Views section of the Data Dictionary Editor, as described later on in this chapter.

When you expand the Global Parameters “Views” folder, you will see that it contains one sub-folder for each view that currently exists. The order in which these sub-folders are arranged determines the order in which the views’ shortcut icons are displayed in the shortcut bar.

On a default installation, the “Views” configuration would be as follows:

Note that the following parameter is supported at the “Views” level:

StartupView The string value of this parameter determines the view to be displayed on starting up the client, on switching data dictionaries, or on refreshing the current data dictionary. This value must be the name of the sub-folder, under “Views”, that relates to the view concerned. If it is left blank, the client will open the view relating to the topmost sub-folder.

Below the “Views” level, each sub-folder corresponding to a view has its own set of parameters whose individual values you can change. These are described in the following sections of this chapter.


187

For general instructions on inserting parameter values and new folders into Global Parameters, see the chapter entitled Managing Global Parameters on page 177. You will find the section entitled Creating a New Folder Based on an Existing Folder on page 181 within that chapter particularly useful if you wish to create a copy of an existing view to provide the starting point for a new view.

Web-Style Views (“Supportworks Today”)

Within Global Parameters/Views, there can be folders (of which the initial default is named “Supportworks Today”) that contain parameters whose values represent various modifiable characteristics of the Web style of view. You can create a new view of this type by creating such a folder and inserting the relevant set of parameters.

The parameters available are as follows:

Type For this kind of view, the string value of this parameter should be the view’s identifier, “webpage”.

IconTitle The string value of this parameter gives the text with which the view’s shortcut icon is labelled.


188

ViewTitle The string value of this parameter gives the textual title of the view, although this is currently not displayed.

Icon The numerical value of this parameter is an index number that determines the image to be used for the view’s shortcut icon. See Appendix C: Shortcut-Bar Icons and their Identifiers on page 377 to find out what images are available and what their respective index numbers are. For “Supportworks Today”, the default value is 9.

Visible The string value of this parameter determines whether or not the view’s shortcut icon is to be displayed in the shortcut bar, and therefore whether or not the view will be accessible to analysts by that means. The value can be either Yes or No.

Url This parameter has a string value giving the URL of the PHP script that generates the Web page to be embedded in the view. By editing such a value so that the URL points to another script, you can make the client display a different Web page. This page might be one that you have constructed yourself, or that has been constructed by a consultant. The script can reside on any Web server.

Helpdesk ViewsWithin Global Parameters/Views, there would be folders (of which the initial default is named “Helpdesk View”), and further sub-folders within those, that contain parameters whose values represent various modifiable characteristics of the Helpdesk type of view. You can create a new view of this type by creating such a folder, together with its requisite sub-folders, and inserting the relevant sets of parameters. Better still, you could create the view by copying an existing one of the same type and simply making the adjustments needed, as described in Creating a New Folder Based on an Existing Folder on page 181.

Customisation of this type of view can involve the modification of both generic and specific aspects of the view. The generic aspects, represented by parameters in the view’s main folder, are those concerned with switching the view on and off, with the title of the view, with the shortcut-bar icon relating to the view, with the icon’s text label, and with the bar chart showing a summary of call statuses. These aspects are covered in the first subsection below.


189

The more specific aspects of customisation, represented by parameters in the view’s lowest-level sub-folders, are those pertaining to particular sections of the view (other than the bar chart). Thus, firstly, you can check and modify various important parameters governing what analysts should be able to see in their lists of calls, work items, issues and watched calls in the corresponding tabs of the view. You can also create any number of additional tabs for listing calls (in both the top and the bottom pane), work items (in the top pane only) or issues (in the bottom pane only), whose parameters you can separately define. As mentioned above for a complete view, the quickest way of creating an extra tab would usually be by basing it on an existing tab.

The tabs in a given instance of the Helpdesk type of view are represented by the following sub-folders below the main folder (which, for the initial default, would be Global Parameters/Views/Helpdesk View):

• For a call list, this would be a sub-folder in “Top” or “Bottom” (such as “My Calls View”) of type CallList

• For a work-item list, this would be a sub-folder in “Top” (such as “My Tasks View”) of type TaskList

• For an issue list, this would be a sub-folder in “Bottom” (such as “Issues View”) of type IssuesList

• For the Watched Calls list, this would be a sub-folder in “Bottom” (normally named “Watched Calls View”) of type WatchedCallsList

Customisation of the above tabs is covered in the respective subsections below. Note that, if there is more than one sub-folder in “Top” or “Bottom”, their order (starting from the top) would dictate the order in which the tabs are displayed (starting from the left).

Another specific aspect of the Helpdesk kind of view that you can customise is the support-team tree browser. However, customisation of all such browsers is covered in the chapter entitled Filtering the Contents of Support-Team Trees on page 243.


190

Changing Generic Characteristics of the View

A top-level folder under “Views” (such as “Helpdesk View”) representing an instance of the Helpdesk type of view allows you to check and modify the following generic characteristics relating to that view:

Type For this kind of view, the string value of this parameter should be the view’s identifier, “helpdesk”.

IconTitle The string value of this parameter gives the text with which the shortcut icon relating to the view is labelled.

ViewTitle The string value of this parameter gives the non-contextual part of the view’s title (that is, the portion preceding the hyphen).

Icon The numerical value of this parameter is an index number that determines the image to be used for the shortcut icon relating to the view. See Appendix C: Shortcut-Bar Icons and their Identifiers on page 377 to find out what images are available and what their respective index numbers are. For “Helpdesk View”, the default value is 3.

Visible The string value of this parameter determines whether or not the view’s shortcut icon is to be displayed in the shortcut bar, and therefore whether or not


191

the view will be accessible to analysts by that means. The value can be either Yes or No.

CallStatusGraphFilter The string value of this parameter is an SQL expression that stipulates the criteria governing which calls are (or are not) to be included in the Active Call Status bar chart that is displayed in the view. A suitable criterion might involve call status, call ownership, or any other factor represented as a column in the opencall table. The default filter, for example, restricts calls to those that are still open (that is, not closed or cancelled). Note that status number 7 is one reserved for future use.

Changing the Characteristics of a Call List

A sub-folder (such as “My Calls View”) under “Top” or “Bottom” would represent a call-list tab located correspondingly in the top-right or bottom-right pane of the relevant Helpdesk type view. You can have as many call-list tabs as you require, the characteristics of each being determined by the parameter values defined within such a sub-folder.



192

AvailableColumns The string value of this parameter is a comma-separated list identifying the opencall table columns from which data is to be displayed in the tab. For each table column identified, there would be a corresponding headed column visible in the tab. The labelling of these columns is taken from the display names of the table columns concerned, as defined in the Database section of the data dictionary. Note that the Problem Text and Solution Text columns will always be displayed along with those explicitly specified here. In the absence of this parameter, the displayed columns default to a fixed set.

Filter The string value of this parameter is an SQL expression that stipulates the criteria governing which calls are (or are not) to be displayed in the tab. A suitable criterion might involve call status, call ownership, or any other factor represented as a column in the opencall table. The default filter, for example, restricts calls to those that are still open (that is, not closed or cancelled). Note that status number 7 is one reserved for future use.

TabName The string value of this parameter determines the text to display on the label of the tab when the Supportworks Helpdesk context (showing all helpdesk calls) is selected. The default value is All Viewable Calls.

TabNameCalls The string value of this parameter determines the text to display on the label of the tab when another analyst’s context (showing that analyst’s calls) is selected. You can use any one or more of the following run-time variables within the string to indicate the specific context:

%1 The analyst’s full name%2 The group’s name%3 The analyst ID%4 The group ID%5 The number of calls displayed in the tab

The default value is %1’s Calls.

TabNameGroup The string value of this parameter determines the text to display on the label of the tab when another group’s context (showing that group’s calls) is selected. You can use the same run-time variables within the string as for TabNameCalls to indicate the specific context. The default value is %2’s Calls.

TabNameMyCalls The string value of this parameter determines the text to display on the label of the tab when the analyst’s own context (showing their


193

own calls) is selected. You can use the same run-time variables within the string as for TabNameCalls to indicate that context. The default value is My Calls.

TabNameMyGroup The string value of this parameter determines the text to display on the label of the tab when the context of the analyst’s own group (showing that group’s calls) is selected. You can use the same run-time variables within the string as for TabNameCalls to indicate that context. The default value is My Group’s Calls.

TabNameShowFilter The string value of this parameter determines whether or not the name of the currently applied user-selectable filter is to be displayed as part of the large-text title that appears on the tab when filter controls are enabled. The value can be either Yes or No.

Type For this kind of tab, the string value of this parameter should be CallList.

Visible The string value of this parameter determines whether or not the tab is to be displayed in the view. The value can be either Yes or No.

ScriptName The string value of this parameter gives the name of the JavaScript file to associate with the tab. In this file, it is possible, for example, to enable/disable commands in the menus that pop up when the analyst right-clicks within the tab. The default value is “mycalls”, corresponding to a file called mycalls.js, which may be found (by default) in C:\Program Files\Hornbill\Supportworks Server\html\clisupp\js or in any sub-folder under that.

ApplyContextFilter The string value of this parameter determines whether or not the list of calls on the tab is to be automatically filtered in accordance with the context selected. The value can be either Yes or No. If it is set to Yes, the list will be subject to context-based filtering. If it is set to No, all helpdesk calls will be displayed in any of the contexts.

ApplyContextTabNames The string value of this parameter determines whether the text displayed on the tab’s label will reflect the context selected (Yes), or will be the currently defined string value of TabName (No). It is relevant only when ApplyContextFilter is set to Yes.

FilterLabel The string value of this parameter defines the text of the user-selectable filter control’s label, which will be visible only if the control itself is visible. The default value is Filter:.


194

Creating User-Selectable Filters (Optional)

Optionally, you can add a feature to the client that will provide a number of different named filters for analysts to select from on a call-list tab. This would allow analysts to view, say, escalated calls only, at any time when they wish to focus their attention on those.

To enable this feature on a given call-list tab, you must first create a sub-folder named “Filters” within the folder (such as “My Calls View”) representing that tab. In the “Filters” folder, you must then create a parameter for each filter you wish to make available. Each parameter would be similar to Filter in the folder representing the tab, but with a name of your choice and with an SQL expression that reflects the specific filtering function required. For example, you could have a filter that restricts the call display to unassigned calls, and one that blocks everything except escalated calls. In such a case, the two parameter values would be as shown below:

Once you have created a selectable-filter scheme containing at least one filter, you would see that a filter control has appeared at the top of the relevant call-list tab. The drop-down list would allow you to select the filter that you want


195

applied. Notice how the filter names correspond exactly to the names you had chosen for the parameters.

If, subsequently, you were to add another filter to the scheme, this would also be added as an item to the drop-down list.

You can change the order of the filters in the drop-down list by reordering the corresponding parameter items here using drag-and-drop.

Changing the Characteristics of a Work-Item List

If workflow is required on your system, you would have at least one sub-folder (such as “My Tasks View”) under “Top” that would represent a work-item list tab in the relevant Helpdesk type view. You can have as many work-item list tabs as you want in a given view, but these can only be located in the top right-hand pane. The characteristics of a tab are determined by the parameter values defined within its sub-folder.


VisibleColumns The string value of this parameter is a comma-separated list identifying the calltasks and opencall table columns from which data is to be


196

displayed in the work-item list tab. For each table column identified, there would be a corresponding headed column visible in the tab. The labelling of these columns is taken from the display names of the table columns concerned, as defined in the Database section of the data dictionary.

Each listed column in the parameter is specified either by its name, or, if the name is common to both tables, by its full table.column specification.

Filter If you wish to configure a filter to stipulate what can or cannot be displayed in the work-item list tab, you can do so here. The string value of this parameter should be an SQL expression that states the relevant criteria. For example, an expression designed to restrict the display to just those work items that have been assigned to the General Support group might be as follows:

groupid = ‘SUPPORT’

where groupid is the name of the column in the calltasks table that contains the IDs of all groups to which work items have been assigned.

By default, Filter has a null value, meaning that work items relating to all groups are visible.

TabName The string value of this parameter determines the text to display on the label of the tab when the Supportworks Helpdesk context (showing all helpdesk calls) is selected. The default value is All Viewable Work Items.

TabNameTasks The string value of this parameter determines the text to display on the label of the tab when another analyst’s context (showing that analyst’s work items) is selected. You can use any one or more of the following run-time variables within the string to indicate the specific context:

%1 The analyst’s full name%2 The group’s name%3 The analyst ID%4 The group ID

The default value is %1’s Work Items.

TabNameGroup The string value of this parameter determines the text to display on the label of the tab when another group’s context (showing that group’s work items) is selected. You can use the same run-time variables within the string as for TabNameTasks to indicate the specific context. The default value is %2’s Work Items.


197

TabNameMyTasks The string value of this parameter determines the text to display on the label of the tab when the analyst’s own context (showing their own work items) is selected. You can use the same run-time variables within the string as for TabNameTasks to indicate that context. The default value is My Work Items.

TabNameMyGroup The string value of this parameter determines the text to display on the label of the tab when the context of the analyst’s own group (showing that group’s work items) is selected. You can use the same run-time variables within the string as for TabNameTasks to indicate that context. The default value is My Group’s Work Items.

Type For this kind of tab, the string value of this parameter should be TaskList.


Changing the Characteristics of an Issue List

A sub-folder (such as “Issues View”) under “Bottom” would represent an issue-list tab located in the bottom-right pane of the relevant Helpdesk type view. You


198

can have as many issue-list tabs as you require, but they must be located in the bottom right-hand pane. The characteristics of a tab are determined by the parameter values defined within such a sub-folder.

The relevant parameters are as follows:

TabName This parameter’s string value determines the text to display on the tab’s label. In the absence of this parameter, the text defaults to “Issues”.

Type For this kind of tab, the string value of this parameter should be IssuesList.


Filter The string value of this optional parameter is an SQL expression that stipulates the criteria governing which issues are (or are not) to be displayed in the issue-list tab. A suitable criterion might involve the data-dictionary name, for example.

Changing the Characteristics of the Watched Calls List


199

If call-watching is required on your system, you would have a sub-folder (such as “Watched Calls View”) under “Bottom” that would represent the Watched Calls tab in the relevant Helpdesk type view. You can have only one Watched Calls tab in a given view, and this must be located in the bottom right-hand pane. The characteristics of the tab are determined by the parameter values defined within its sub-folder.


TabName The string value of this parameter determines the text to display on the tab’s label.

Type For this kind of tab, the string value of this parameter should be WatchedCallsList.


AvailableColumns The string value of this parameter is a comma-separated list identifying the opencall table columns from which data is to be displayed in the tab. For each table column identified, there would be a corresponding headed column visible in the tab. The labelling of these columns is taken from the display names of the table columns concerned, as defined in the Database section of the data dictionary. Note that the Problem Text and Solution Text columns will always be displayed along with those explicitly specified here. In the absence of this parameter, the displayed columns default to a fixed set.


200

The Calendar View

Within Global Parameters/Views, there is normally a folder (named “Calendar View” by default) that contains parameters whose values represent various modifiable characteristics of the Calendar type of view.

The parameters available for customising this kind of view are as follows:

Type For this kind of view, the string value of this parameter should be the view’s identifier, “calendar”.


ViewTitle The string value of this parameter gives the part of the view’s title that precedes the hyphen separating it from the time-zone indication.

Icon The numerical value of this parameter is an index number that determines the image to be used for the view’s shortcut icon. See Appendix C: Shortcut-Bar Icons and their Identifiers on page 377 to find out what images are available and what their respective index numbers are. The default value is 12.


201


The E-Mail View

Within Global Parameters/Views, there is a folder named “E-Mail” that contains parameters whose values represent various modifiable characteristics of the E-Mail view. There can be only one view of this type.

The parameters available in this folder are as follows:

Type For this view, the string value of this parameter should be the view’s identifier, “mail”.


Icon The numerical value of this parameter is an index number that determines the image to be used for the view’s shortcut icon. See Appendix C: Shortcut-Bar


202

Icons and their Identifiers on page 377 to find out what images are available and what their respective index numbers are. The default value is 2.


InitialMailbox The string value of this parameter determines the mailbox to be displayed initially whenever an analyst selects the view. In the absence of a value, the analyst’s personal mailbox will be displayed by default.

Database Entity ViewsA database entity view is a view, displayed in the main client window when you click a shortcut icon, that contains facilities for searching and browsing through a specific managed table, complete with an area for displaying the contents of the record chosen. A typical database entity view would be the Customers (or Contacts) view.

You need to consider two distinct sections of the Data Dictionary Editor when customising database entity views. The first of these relates to the common aspects of such views, and the second relates to their individual attributes.


203

Common Aspects of Database Entity Views

Within Global Parameters/Views in the data dictionary, there is a folder called “Database Entity Views” that contains two parameters representing the common aspects of database entity views. These parameters are as follows:

Type For database entity views as a whole, the string value of this parameter should be the overall identifier, “autodbev”.

Visible The string value of this parameter determines whether or not the views’ shortcut icons are to be displayed in the shortcut bar, and therefore whether or not the view will be accessible to analysts by that means. The value can be either Yes or No.

Attributes Relevant to Individual Database Entity Views

Within the Database Entity Views section of the data dictionary, you can examine and modify the attributes of any database entity view used for finding and displaying records pertinent to a specific table. The attributes include an indication of the table concerned and the tree browser to be used, the composition of the search panel and its default settings, the structure of the


204

search results, the record-display type, the icon to be shown on the shortcut bar, and a filter specification for the searches.

When you expand the Database Entity Views category in the left-hand pane of the Data Dictionary Editor, all the items representing the existing entity views are revealed. For the Default data dictionary, the views concerned would be the two called “Customers” and “Assets”. You can change the relative vertical positioning of the views’ shortcut icons by means of the Move Up and Move Down buttons.

Select the required item to show its attributes in the right-hand pane.


Name This is the name of the selected view item, as displayed in the left-hand pane. It is used as the name of the shortcut icon and as the title of the view.

Table This specifies the table to be searched or browsed within the view.

Tree Browser This identifies the tree browser to be displayed in the view’s browse mode. Creation and customisation of tree browsers are covered in the chapter entitled SQL Tree Browsers.


205

Search Title This defines the title of the search panel, visible when the view is in search mode.

Search Columns The items here define the fields by which records in the table can be searched. The fields are specified as names of columns in the table. When you click anywhere in the Search Columns field, a button appears on the right. Clicking this button displays the following dialogue box:

In this dialogue box, you can specify which search fields are to be included on the search panel. To add fields to the panel, make a suitable selection in the Available Columns list and click Add. To remove fields from the panel, select these in the Included Columns list and click Remove. In both cases, you can use the Control and Shift keys in the usual way to appropriately extend your selection. Note that the top-down order of the items in the Included Columns list determines exactly the order in which the search fields are displayed on the panel. Once the required fields are in place, click OK.

Search Result Columns The items here define the table columns that are to be displayed in the Search Results area of the database entity view. When you click anywhere in this attribute field, a button appears on the right. Clicking this button displays the same dialogue box as the button in Search Columns, this time allowing you to specify the table columns to be included in the search results.

Form Type This specifies the format in which the details of a found entity record will be displayed. You have a choice of two settings. The default setting is HTML View, which displays an interactive version of the record’s details on an active page, and also lists all outstanding calls associated with the entity. The


206

alternative setting is Form View, which simply displays the details in an embedded standard form, complete with toolbar.

If you select HTML View, you will see, on each of the active pages, links to related records that can themselves be set to display as either active pages or embedded forms. Setting these to one or the other is a rather more involved process. First of all, you have to open the file called global.settings.php in a text editor. This file can be found at the location C:\ Program Files\ Hornbill\ Supportworks Server\ html\ clisupp\ details\ ITHD (or the equivalent using the install path of your particular system, if different). Within the file, you will see a value assignment for the variable $boolUseFormsInActivePageLinks, which you can specify as either true or false. A true value will display related records as embedded forms, while a false value will display them as active pages. You are free to edit the value as appropriate, but you must be careful to leave the rest of the script intact.

Form If the Form Type attribute is set to Form View, this identifies the standard form to be used.

Shortcut Bar Icon This specifies, by means of an index number, the image to be used for the icon, on the shortcut bar, with which the view is selected. To change to a different image, enter any number from 0 to 18, inclusive. See Appendix C: Shortcut-Bar Icons and their Identifiers on page 377 to find out what images are available and what their respective index numbers are. Note that you must click Save and then exit from the Data Dictionary Editor to retain the new icon setting for all users, although the change will not actually be visible on an individual’s shortcut bar until they have logged out of the client and back in again.

Default Max Search Results This specifies the default search limit that is to apply to the view’s search mode, as displayed in the Search Options area. It is expressed as a number giving the maximum number of records to be listed in the Search Results area.

Default Search Option This specifies the default search-logic option that is to apply to the view’s search mode. You have a choice of two settings, each corresponding to one of the two available in the relevant field of the Search Options area.

Search Filter This specifies, in the form of an SQL expression, which records are to be included in, or excluded from, any search conducted in the view’s search mode. A null entry here means that all records are to be included.


207

Creating New Database Entity Views

If you have created a new managed table for your Supportworks system, you may wish to add a new view, complete with its own shortcut icon, by which you can search and browse through that table and perhaps update its records.

When you create a new view, you basically give it a name by which analysts can recognise it. Initially, the new view will be lacking in its most vital features, so you will have to configure many of the required attributes from scratch.

The procedure to create a new view is as follows:

1. Ensure that the client is switched to the data dictionary in which you wish to create the new view.

2. Run the Data Dictionary Editor and select File > New > Database Entity View.

3. At the displayed prompt, type a suitable name for the new view. Supportworks convention dictates that this should be in the plural (for example, “Customers”), indicating the kinds of entities to be viewed.

4. Click OK. Notice that a new item having the name you typed has appeared under the Database Entity Views category.

5. With the new view item highlighted, proceed to customise it with the aid of the information given in Attributes Relevant to Individual Database Entity Views on page 203.

6. Save the new view and its customised attributes and close the Data Dictionary Editor.

You should now be able to see the new view icon in the shortcut bar.


208

Call-Search Views

Within Global Parameters/Views, there can be folders (of which the initial default might be named “Search For Calls View”) that contain parameters whose values represent various modifiable characteristics of the call-search type of view. You can create a new view of this type by creating such a folder and inserting the relevant set of parameters.


SearchColumns The string value of this parameter is a comma-separated list identifying the columns of the call table (given by the TableName parameter) that are to be searchable. For each searchable column, there would be a corresponding search field visible in the left-hand pane of the view when displayed in the field-based search mode. The labels of the search fields are taken from the display names of the columns concerned, as defined in the Database section of the data dictionary.

ResultColumns The string value of this parameter is a comma-separated list identifying the columns of the call table (given by the TableName parameter) from which data is to be displayed in the Search Results pane of the view. For


209

each table column identified, there would be a corresponding headed column visible in that pane. The labelling of these columns is taken from the display names of the table columns concerned, as defined in the Database section of the data dictionary.

TableName The string value of this parameter gives the name of the table whose columns are listed as values of the SearchColumns and ResultColumns parameters.

DefSearchOptions The string value of this parameter specifies the default “match” option that is to apply to the search pane. A value of 0 would set the option “Any of the above must match” as the default, while 1 (or any other non-zero value) would select “All of the above can match”.

DefMaxSearchResults The numerical value of this parameter specifies the default limit for the number of search results displayable that is to apply to the search pane.

Type For this kind of view, the string value of this parameter should be the view’s identifier, “callsearch”.


ViewTitle The string value of this parameter gives the title of the view.

Icon The numerical value of this parameter is an index number that determines the image to be used for the view’s shortcut icon. See Appendix C: Shortcut-Bar Icons and their Identifiers on page 377 to find out what images are available and what their respective index numbers are. For “Search For Calls View”, the default value is 10.


Filter This parameter is optional. Its string value is an SQL expression that stipulates the criteria governing which calls can (or cannot) be searched for. A suitable criterion might involve call class, for example.


210

The Database Searches View

Within Global Parameters/Views, there is a folder, normally named “Database Search View”, that contains parameters whose values represent various modifiable characteristics of the Database Searches view. Although it is possible to create additional views of this type, their usefulness would be limited, as the same custom searches would be visible within each of them.

The parameters available for this view are as follows:

Type For this kind of view, the string value of this parameter should be the view’s identifier, “dbsearch”.



Icon The numerical value of this parameter is an index number that determines the image to be used for the view’s shortcut icon. See Appendix C: Shortcut-Bar Icons and their Identifiers on page 377 to find out what images are available and


211

what their respective index numbers are. For “Database Search View”, the default value is 6.


Filter This filter applies when an analyst has selected a database-search type of view directly, via either the shortcut icon or the menu command. The string value of this parameter must be an SQL expression that gives the criteria that govern which calls or other kinds of records can (or cannot) be searched for in the view. A suitable criterion for calls might involve call class, for instance. This is what is used in the following example:

callclass = ‘Helpdesk’

Realistically, in order to make use of this filter, all the custom searches created in the view would have to be restricted to the table to which the filter applies, otherwise SQL errors would be generated.


212

The My Library View

Within Global Parameters/Views, there is a folder, normally named “My Library View”, that contain parameters whose values represent various modifiable characteristics of the My Library view. Although it is possible to create additional views of this type, they would be of no use whatsoever, as exactly the same content would be visible within each of them.


Type For this kind of view, the string value of this parameter should be the view’s identifier, “library”.


ViewTitle The string value of this parameter gives the part of the view’s title that precedes the hyphen separating it from the server name (or IP address).

Icon The numerical value of this parameter is an index number that determines the image to be used for the view’s shortcut icon. See Appendix C: Shortcut-Bar


213

Icons and their Identifiers on page 377 to find out what images are available and what their respective index numbers are. The default value is 15.


The KnowledgeBase View

Within Global Parameters/Views, there is a folder, named “KnowledgeBase View”, that contains parameters whose values represent various modifiable characteristics of the KnowledgeBase view. Although it is possible to create additional views of this type, they would be of no use whatsoever, as exactly the same content would be visible within each of them.


Type For this kind of view, the string value of this parameter should be the view’s identifier, “knowledgebase”.


214



Icon The numerical value of this parameter is an index number that determines the image to be used for the view’s shortcut icon. See Appendix C: Shortcut-Bar Icons and their Identifiers on page 377 to find out what images are available and what their respective index numbers are. The default value is 4.


Report Views

Within Global Parameters/Views, there can be folders (of which the initial default is named “Report View”) that contain parameters whose values represent various modifiable characteristics of report views. You can create a new view of this type by creating such a folder and inserting the relevant set of parameters.


215


Type For this kind of view, the string value of this parameter should be the view’s identifier, “reports”.



Icon The numerical value of this parameter is an index number that determines the image to be used for the view’s shortcut icon. See Appendix C: Shortcut-Bar Icons and their Identifiers on page 377 to find out what images are available and what their respective index numbers are. For “Report View”, the default value is 5.


Filter The string value of this parameter would be an SQL expression that stipulates the criteria governing which reports are to be visible by an analyst using the currently loaded data dictionary. The allowed reports would be specified in terms of the data dictionaries they have had allocated to them, as described in the Management Information and Reporting chapter of the Administrator Guide. Therefore, the operand in each clause (or the only clause) within the SQL expression would be the name of a data dictionary. To make those reports visible that have had all data dictionaries allocated to them, you must include a clause that has ‘All’ as the operand. The column, in the queried table, that identifies a data dictionary (or all data dictionaries) is named datadic.

The following example filter value would cause only those reports that have had the “itsm” data dictionary, or all data dictionaries, allocated to them to be visible:

datadic = ‘itsm’ OR datadic = ‘All’

If no filter value is defined, you would have the initial default situation of all reports being visible. This would be the same as having a single-clause filter with the operand ‘All’.


216

Filtering Call Commands

217


In the Global Parameters section of the Data Dictionary Editor, you will find a folder called “Global Call Settings”. This folder contains parameters that allow you to filter the results generated by two types of client menu command relating to calls. These parameters are described in the following sections.

For general instructions on inserting parameter values into Global Parameters, see the chapter entitled Managing Global Parameters on page 177.

Filtering Calls Viewed By ReferenceThe value of the first parameter in the “Global Call Settings” folder governs what calls analysts should be able to view by means of the View Call Details by Reference command in the Helpdesk menu.

The name of this parameter is “GetCallByReferenceFilter”. Normally, it would have a null value, meaning that analysts can view any call by reference. However, you can enter, as a string value for this parameter, an SQL expression that stipulates the criteria governing which calls can (or cannot) be viewed by that means. A suitable criterion might involve call class, for example. In the following screenshot, you can see that a filter has been created that will allow only calls of the Software class to be viewed using the View Call Details by Reference command.


218

Filtering Call SearchesThe value of the second parameter in the “Global Call Settings” folder governs what calls analysts should be able to view by means of the Find Calls Logged/Resolved/Closed function in the Search menu.

The name of this parameter is “FindCallsFilter”. Normally, it would have a null value, meaning that there is no restriction on what calls can appear in the search results. However, you can enter, as a string value for this parameter, an SQL expression that stipulates the criteria governing which calls can (or cannot) appear in the results. A suitable criterion might involve call class, for instance, or any other factor represented as a column in the opencall table. Call class is what is used in the following example:


219


220

Customising Aspects of Call Profiles

221


You can check and modify various parameters that define call-profile attribute labels and resolution-profile filtering criteria. Also, you can create parameters that define problem-profile filtering criteria, and those that define the name to be used for the top-level call-profile categories. Such customisation is achieved within the following Global Parameters folders:

• For call-profile attribute labels, this would be “Call Profile Editor”

• For call-profile category names, this would be “Configurable Text”

• For problem-profile filtering criteria, this would be “DD Filters”

• For resolution-profile filtering criteria, this would be “Close Call Form”

Customisation of the above aspects of call profiles is covered in the respective sections below.


222

Renaming Call Profile Attributes

The “Call Profile Editor” folder allows you to customise the labels of the attribute fields that are associated with call profiles. These field labels are visible in the Attributes tab of the Call Profile Manager. The text of each label is defined by the string value of the corresponding parameter, and you can edit these strings in accordance with your requirements.

Renaming Call Profile Categories (Optional)Call-profile categories are the names by which the two types of call profile are known and are displayed throughout the Supportworks client user interface. By default, these categories are “Problem Profiles” and “Resolution Profiles”. If your organisation uses terms other than these for hierarchically characterising call registration and call completion, you can easily substitute the names you require. All call-profile trees will then display the alternative categories you have defined.


223

To set up such alternative categorisations, you must first create the folder, within Global Parameters, in which they are to be held (unless one has already been created). The name of that folder must be “Configurable Text”. In that folder, you can then create either (or both) of the following parameters:

ProblemProfile The string value of this parameter would be the category relating to a call as initially logged. In the absence of this parameter, the default categorisation would be “Problem Profiles”.

ResolutionProfile The string value of this parameter would be the category relating to a call when completed. In the absence of this parameter, the default categorisation would be “Resolution Profiles”.

In the following example, “Incident Profiles” has replaced “Problem Profiles”, and “Completion Profiles” has replaced “Resolution Profiles”:

Filtering Problem Profiles (Optional)Depending on the operational context, analysts can select a problem profile in one of two basic ways:


224

• In a tree browser – when logging calls or changing call records, when searching for calls, and when composing/editing documents in the Knowledgebase

• In drop-down list – when using the Find Calls Logged/Resolved/Closed functions available from the Search menu

For either of these selection mechanisms, you can create a filter to limit the selection of items available, in accordance with the required criteria. You can also specify criteria to control other aspects of what might be visible in such a browser/list.

If you wish to set up either of the filters, you must first create the folder, within Global Parameters, in which they are to be held (unless one has already been created). The name of that folder must be “DD Filters”. In that folder, you can then create either (or both) of the following filter parameters:

ProfileCodeFilter The string value of this parameter would be an SQL expression that stipulates the criteria governing the display of problem profiles in their prescribed tree browsers.

Thus, entry of code != ‘hrdw’ (where code is the name of the column in the probcode table that holds all of the system’s problem-profile codes) would have the effect of making all profiles under the Hardware category invisible. You can also enter an SQL expression to re-order or re-group the available profiles, or indeed to control a number of other aspects of what analysts will see in the problem-profile tree browser. In the expression, you can refer to any of the first four columns of the probcode table.

FindCallsFilter The string value of this parameter would be an SQL expression that stipulates the criteria governing the display of problem profiles on the top-level problem-profile drop-down list found in the Call Type field of any of the “Find calls logged/resolved/closed...” dialogue boxes that are invoked via a command in the main client window’s Search menu. Just as for the “ProfileCodeFilter” parameter, there are various criteria possibilities available.

In the following example, all Hardware-category profiles have been filtered out:


225


226

Filtering Resolution Profiles

The “Close Call Form” folder allows you to check and modify the display of resolution profiles as they are presented when an analyst is in the process of resolving or closing a call. Within this folder, two filter parameters are available – one relating to call closure and the other to call resolution. They are as follows:

CloseProfileFilter This parameter relates to call closure only. Its main function would be to filter the availability of resolution profiles in the Choose Profile tree browser, as invoked from the Resolve/Close Call form. You can stipulate which profiles are to be available or unavailable for selection in that tree browser by means of a suitable SQL expression entered as a string value for the parameter. For example, to exclude all hardware-related resolution profiles, you could specify the filter value as follows:

code != ‘HRDW’

where code is the name of the column in the fixcode table that holds all of the system’s resolution-profile codes. In a basic expression such as the above, you can only specify a code at the top level. If you wish to specify a lower-level code, you must add a level specification as follows:


227

OR levelx = 1 code != ‘PRNT’

where the number equated to levelx represents the required level (in this case, 1, which is the next level below the top one).

You could also enter an SQL expression to re-order or re-group the available profiles, or indeed to control a number of other aspects of what analysts will see in the Choose Profile tree browser. In the expression, you can refer to any of the four columns that make up the fixcode table.

By default, “CloseProfileFilter” has a null value, meaning that all resolution profiles are available, and that they are arranged in the default order.

ResolveProfileFilter This parameter is exactly the same as “CloseProfileFilter”, except that it applies only when the analyst is marking the call as resolved.


228

Customising Form Functionality

229


This chapter tells you how forms are mapped to call actions, and also how remote form loading is enabled.

Mapping Forms to Call Actions

The “Call Action Forms” folder that you can see in the Global Parameters section of the Data Dictionary Editor maps standard call-action form types to call, issue and work-item actions, allowing the system to know which form to display for a given action. If you were to create, in a particular data dictionary, an alternative version of a form for the system to use (say, for testing purposes), you would then need to change the name of the form here.

UpdateCallForm The string value of this parameter gives the name of the form that is invoked when the analyst elects to update a call.


230

HoldCallForm The string value of this parameter gives the name of the form that is invoked when the analyst elects to place a call on hold.

ResolveCloseCallForm The string value of this parameter gives the name of the form that is invoked when the analyst elects to resolve or close a call that has already been logged. Note that you can use a separate parameter for naming the resolution/closure template to be applied to the Log Call form if you need a different design for this (see LogResolveCloseCallForm below).

CancelCallForm The string value of this parameter gives the name of the form that is invoked when the analyst elects to cancel a call.

IssueForm The string value of this parameter gives the name of the form that is invoked when the analyst elects to create or view/update an issue.

AcceptCallForm The string value of this parameter gives the name of the form that is invoked when the analyst elects to accept a call.

CompleteWorkItemForm The string value of this parameter gives the name of the form that is invoked when the analyst elects to complete a work item.

LogResolveCloseCallForm The string value of this parameter gives the name of the form whose design is used in the Resolve/Close Details tab of the Log Call form. This may be the same as the form specified for ResolveCloseCallForm, or you could specify a different one if, say, a simpler variant of the Resolve/Close Call form is required for when the analyst needs to resolve or close a call while logging it.

Mapping Forms to Call Actions by Call Class (Optional)

Instead of having the system use, for any given call action, the same form irrespective of call class, you could create a different version of that form for each of your call classes, and set the system up to use the appropriate version as and when necessary.

You set up the required mapping for a particular call class by first creating, within the Global Parameters section of the Data Dictionary Editor under “Call Action Forms”, a folder whose name must be that of the call class concerned. In this folder, you would then create any of the following parameters, depending on which call-action forms you want to associate with that call class:


231

UpdateCallFormHoldCallFormResolveCloseCallFormCancelCallFormAcceptCallForm

The string value you would then enter for such a parameter should give the name of the form that has to be invoked when the analyst elects to perform the call action relating to that parameter, just as in the case of the default mappings located directly in the “Call Action Forms” folder.

Note that the default mappings can coexist with the call-class-specific mappings, as you may want to use a single generic form for some call actions. When a call-action form needs to be displayed, the system will first look for a valid call-class-specific mapping and, if one is not found, it will use the form defined in the default mapping.

In the following example, all five parameters are specified for the “Helpdesk” call class, allowing dedicated forms with names such as “EfUpdateHelpdeskCallForm” to be defined as their respective string values:


232

Enabling Remote Form Access (Optional)You can allow the client to load forms remotely by first creating (if it does not already exist) a folder named “Form Control Options” within the Global Parameters section of the Data Dictionary Editor. In this folder, you would then create a parameter named “EnableRemoteFormAccess”. The string value of this parameter would determine whether or not forms defined outside of the current data dictionary can be loaded. If the parameter value is set to “true”, the option would be enabled.

In the following example, the option has been enabled:

Enabling Customisation of New Call Confirmations

233


By default, the five possible variants of the New Call Confirmation pop-up message displayed on logging a call are hard-coded in the system. For any specific data dictionary, you can make these messages customisable by means of a specially structured XML file whose contents would replace the hard-coded text as the source of the messages. The five-part structure of such a file is described in the section entitled Customising New Call Confirmations on page 352. The files would normally be located in the /html/clisupp/ folder, where they would be accessible via given URLs.

For the system to use an XML file instead of the hard code, there must be a parameter called “LogCallConfirmMsg” in the Global Call Settings folder within the Global Parameters section of the data dictionary concerned. The string value of this parameter should be the URL of the XML file. It is convenient to employ the usual &[app.webroot] environment variable at the beginning of the URL.

In the following example, which reflects the default data dictionary, the XML file being specified is named CallConfirm.xml:


234

Controlling Global Call Escalation (Optional)

235


For specific data dictionaries, you can disable or enable the option, found on the Supportworks client, to escalate calls, on a status change, to all support analysts.

You do this by first creating (if it does not already exist) a folder named “Disable Functionality” within the Global Parameters section of the Data Dictionary Editor. In this folder, you would then create a parameter named “DisableEscalateToAll”. The string value of this parameter would determine whether or not analysts will be able to select the “Escalate to all support analysts” option in the Escalation Trigger Event dialogue box, which is part of the SLA management facility in the client. If the parameter value is set to “true”, the option would be disabled.

In the following example, the option has been disabled:


236

Controlling Work-Item Completion (Optional)

237


For specific data dictionaries, you can disable or enable the option to allow work items to be completed by any support analyst (other than the assignee or their group).

You do this by first creating (if it does not already exist) a folder named “Disable Functionality” within the Global Parameters section of the Data Dictionary Editor. In this folder, you would then create a parameter named “DisableCompleteWorkItemByAny”. The string value of this parameter would determine whether or not users will be able to select, in the Create New Work Item or Work Item Properties dialogue box, the drop-down list option for a work item to be completed by any support analyst. If the parameter value is set to “true”, the option would be disabled.

In the following example, the option has been disabled:


238

Customising Operational Aspects of Issues (Optional)

239


You can create parameters that define call-selection filtering criteria for issues and an alternative customer browser for issues. Such customisation is achieved within the following Global Parameters folders in the Data Dictionary Editor:

• For call-selection filtering criteria, this would be “DD Filters”

• For an alternative customer-browser definition, this would be “Issue View”

Customisation of the above aspects of issues is covered in the respective sections below.

Filtering Call Selection for IssuesYou can create a filter to limit the selection of calls available to add to issues, in accordance with specified criteria.

To set up such a filter, you must first create (if it does not already exist) a folder named “DD Filters” within Global Parameters. In that folder, you would then create a parameter named “AddCallToIssueFilter”. The string value of this parameter would be an SQL expression that stipulates the criteria governing which calls are (or are not) to be available for selection from the Add Calls To Issue list, which is displayed when an analyst clicks the relevant toolbar button in the View/Edit Issue form. A suitable criterion would involve any factor represented as a column in the opencall table.

In the following example, the filter will exclude calls of all classes other than “Software”:


240

Defining an Alternative Customer Browser to Use with IssuesNormally, the Log Call and Add function in the View/Edit Issue dialogue box looks for an SQL tree browser form called “Customer” to display for selection of a customer. However, if you have created and wish to use an SQL tree browser form with another name, you must create an appropriate entry in Global Parameters that specifies the name concerned.

Within Global Parameters, you first have to create a folder called “Issue View”. In that folder, you would then create the required parameter, which must be named “PickCustomerForm”. The value of that parameter would be a string corresponding to the name of the SQL tree browser form.

An example would be as follows:


241


242

Filtering the Contents of Support-Team Trees

243


Broadly, there are two different contexts in which support-team tree browsers can appear in the Supportworks client:

• In the Support Team pane of a Helpdesk view

• In any dialogue window used for selecting a support-team entity for some purpose (such as for assigning calls)

You can separately filter the contents of the trees displayed in either of these cases, as described in the respective subsections below.

Filtering the Helpdesk-View Support-Team Tree


244

The “Team View” sub-folder that you can see under any folder representing a Helpdesk type of view in the Global Parameters section of the Data Dictionary Editor allows you to filter the visibility of analysts, groups, third-party suppliers and third-party contracts in the Support Team tree browser found in the relevant pane of that Helpdesk view.

Filtering is done by means of values given to any of the filter parameters available in the “Team View” sub-folder. These parameters are as follows:

AnalystFilter You can stipulate which support analysts are to be visible or invisible in the support-team tree browser by means of a suitable SQL expression entered here as a string value. For example, to exclude the administrator from the tree browser, you could specify the value as:

analystid != ‘ADMIN’

where analystid is the name of the column in the swanalysts table that contains unique analyst IDs.

By default, “AnalystFilter” has a null value, meaning that all analysts are visible.

GroupFilter You can stipulate which support groups are to be visible or invisible in the support-team tree browser by means of a suitable SQL expression entered here as a string value. For example, to exclude the General Support group from the tree browser, you could specify the value as:

id != ‘SUPPORT’

where id is the name of the column in the swgroups table that contains unique group IDs.

By default, GroupFilter has a null value, meaning that all groups are visible.

TpmFilter You can stipulate which third-party suppliers are to be visible or invisible in the support-team tree browser by means of a suitable SQL expression entered here as a string value. For example, to include only UK suppliers in the tree browser (assuming that the region is always to be found in the supplier’s ID), you could specify the value as:

analystid LIKE ‘%UK%’

where analystid is the name of the column in the swanalysts table that contains unique third-party supplier IDs (as well as analyst IDs).


245

TpmContractFilter You can stipulate which third-party SLA contracts are to be visible or invisible in the support-team tree browser by means of a suitable SQL expression entered here as a string value. For example, to include only those contracts whose numbers begin with “9”, you could specify the value as:

tpcontract LIKE ‘9%’

where tpcontract is the name of the column in the swanalysts table that contains unique third-party SLA contract numbers.

Filtering Support-Team Trees Used for Selection

The “Assignment Tree” folder that you can see in the Global Parameters section of the Data Dictionary Editor contains parameters used for filtering the visibility of analysts, groups, third-party suppliers and third-party contracts in those support-team tree browsers and drop-down lists that are used to select a support-team entity for a particular purpose. An example would be the browser found in the Organisation tab of the Assign Call window.



246

AnalystFilter You can stipulate which support analysts are to be visible or invisible in support-team tree browsers used for selection by means of a suitable SQL expression entered here as a string value. For example, if you want to prevent analysts from assigning calls to the administrator, you could specify the value as:

analystid != ‘ADMIN’

where analystid is the name of the column in the swanalysts table that contains unique analyst IDs.

Note that AnalystFilter also affects the content of the analyst-selection list in the Skills tab of the Assign Call and similar dialogue boxes.

By default, AnalystFilter has a null value, meaning that all analysts are visible.

GroupFilter You can stipulate which support groups are to be visible or invisible in support-team tree browsers used for selection by means of a suitable SQL expression entered here as a string value. For example, if you want to prevent analysts from assigning calls to the General Support group, you could specify the value as:

id != ‘SUPPORT’

where id is the name of the column in the swgroups table that contains unique group IDs.

Note that “GroupFilter” also affects the content of the Support Group drop-down list in the Skills tab of the Assign Call and similar dialogue boxes. In addition, “GroupFilter” defines the content of the Home Group drop-down list in the Details tab of the Analyst Properties dialogue box, as well as that of the Group Selection tree in the Group Membership tab of Analyst Properties.

TpmFilter You can stipulate which third-party suppliers are to be visible or invisible in support-team tree browsers used for selection by means of a suitable SQL expression entered here as a string value. For example, if you want analysts to be able to assign calls to UK suppliers only (assuming that the region is always to be found in the supplier’s ID), you could specify the value as:

analystid LIKE ‘%UK%’

where analystid is the name of the column in the swanalysts table that contains unique third-party supplier IDs (as well as analyst IDs).


247

TpmContractFilter You can stipulate which third-party SLA contracts are to be visible or invisible in support-team tree browsers used for selection by means of a suitable SQL expression entered here as a string value. For example, if you want analysts to be able to assign calls only to contracts whose numbers begin with “9”, you could specify the value as:

tpcontract LIKE ‘9%’

where tpcontract is the name of the column in the swanalysts table that contains unique third-party SLA contract numbers.


248

Renaming Support-Group Attributes

249


The “Group Properties” folder that you can see in the Global Parameters section of the Data Dictionary Editor allows you to customise the labels of the attribute fields that are associated with support groups. These attribute fields are represented in the folder as the parameters “Attribute1” to “Attribute6”. The text of each label is defined by the string value of the corresponding parameter, and you can edit these strings in accordance with your requirements.


250

Filtering Skills (Optional)

251


In the Global Parameters section of the Data Dictionary Editor, you can filter lists of skills in different areas of the Supportworks client user interface.

Filtering the Display of Skills in a Tree BrowserThe Manage Skills administration facility and the mechanism for defining skills against a support analyst both display a tree-browser window that would normally list all the analyst skills that are currently set up on the Supportworks server. However, it is possible to create a filter that limits the skills shown in these windows to those that conform to specified criteria.

If you wish to set up such a filter, you must first create the folder, within Global Parameters, in which it is to be held. The name of that folder must be “Skills Dialog”. In that folder, you would then create the required filter parameter, which must be named “Filter”. The string value of this parameter would be an SQL expression that stipulates the criteria governing which skills are (or are not) to be listed in the Manage Skills window, and therefore in any drop-down list from which a skill can be selected. A suitable criterion would involve any factor represented as a column in the swskills table (which is in the sw_systemdb database). The columns concerned are as follows:

Column Name Description

skill Analyst skills

skillgroup Skill categories

description Skill descriptions

dd Data dictionaries (each allocated to a record automatically on creation of that record


252

For example, if you wanted the system to display only those skills whose records were created when “itsm” was the current data dictionary, you would create the following filter:

Filtering the Selection of Skills on Call AssignmentIn the Skills tab of the dialogue box used to assign a call, there is an Analyst Skills field whose drop-down list would normally contain all the support-analyst skills that are currently set up on the Supportworks server. However, it is possible to create a filter that limits the skills shown in this list to those that conform to specified criteria.

If you wish to set up such a filter, you must first create the folder, within Global Parameters, in which it is to be held. The name of that folder must be “Assign Call Dialog”. In that folder, you would then create the required filter parameter, which must be named “Filter”. The string value of this parameter would be an SQL expression that stipulates the criteria governing which skills are (or are not) to be available in the Analyst Skills drop-down list. A suitable criterion would


253

involve any factor represented as a column in the swskills table (which is in the sw_systemdb database). The columns concerned are as given in the section Filtering the Display of Skills in a Tree Browser above.

For example, if you wanted only those skills that fall under the “Hardware” caegory to be selectable when choosing a suitable analyst to whom to assign a call, you would create the following filter:


254

Introducing Features Relating to E-Mail (Optional)

255


Using the Data Dictionary Editor, you can create parameters that enable and control various mail-related features. Such customisation is achieved within the following Global Parameters folders:

• For auto-filing received e-mail, this would be “Mail Move Folders”

• For auto-generating an e-mail audit trail, this would be “Email Audit Trail”

• For defining e-mail integration functionality, this would be “Email Integration”

Customisation of the above aspects of e-mail is covered in the respective sections below.

Automatically Filing Received E-MailWhen an analyst acts on an e-mail message received from a customer by initiating a call action via one of the functions available in the message window, the responsibility for subsequently filing the message away would normally rest with them. However, there is an optional feature available that allows the system to perform such filing automatically. What would happen is that, once the analyst has carried out the call action, the message window would automatically close and the message would move itself into a predefined folder in the relevant mail view. When setting up these mail folders, you can opt to reserve a separate one for each type of call action, or you can arrange for all the messages to be moved to the same folder.

To enable this feature, you must first create a new folder called “Mail Move Folders” within Global Parameters. In that folder, you may create up to four different parameters, each corresponding to a mail folder that will accept automatically moved messages from which a specific type of call action has been invoked. The parameters must be named precisely as follows:


256

LogCallMailFolder (for messages resulting in calls being logged)HoldCallMailFolder (for messages resulting in calls being placed on hold)UpdateCallMailFolder (for messages resulting in call updates)CloseCallMailFolder (for messages resulting in call resolutions and closures)

The string value of such a parameter would be the intended folder path as seen in the mail view. Typical paths are shown in the following example:

Once you have set up a suitable scheme in Global Parameters, you and other members of the support team must complete the process by going into each of the relevant mail views and actually creating the folder paths that you have already specified as parameter values. The folder paths must match their respective parameter-value specifications exactly.

If you want all relevant mail to be moved to the same folder, just make all parameter values identical.


257

Automatically Generating an E-Mail Audit Trail

By default, the system is set up to generate an e-mail audit trail automatically. With this mechanism enabled, copies of all customer notifications of call actions and all messages from whose windows call actions are initiated would be appended by the system as attachments to the call actions concerned.

To disable/enable and reconfigure this mechanism, you must first ensure that a folder called “Email Audit Trail” exists within Global Parameters. In that folder, you should see the following three parameters, of which the first two are initially set by default:

StoreEmailAuditTrail A non-zero numeric value for this parameter will enable automatic e-mail audit-trail generation.

IncludeAttachmentsInMessage A non-zero numeric value for this parameter will keep any message attachments within their respective messages when these messages themselves are appended to calls. The same attachments would continue to be copied directly to the calls, just as they normally are with e-mail audit-trail generation not enabled.


258

MoveToDeletedItems A non-zero numeric value for this parameter will cause every e-mail message from whose window a call action is initiated to be automatically deleted (that is, moved to the Deleted Items folder). You should not use this parameter if there is any likelihood of individual messages being attached to more than one call action. Note that this setting will be overridden if you have specified particular mail folders to which messages are to be moved (as described in Automatically Filing Received E-Mail on page 255).

Defining E-Mail Integration FunctionalityIf your team provides information services and support for unregistered customers, no records would exist for these customers in the Supportworks database. Therefore, when an analyst logs a call from an e-mail window, there would normally be no way in which the customer’s details, including their e-mail address, could be resolved and placed into the call. Without an e-mail address, the system would be unable to recognise the customer responsible for the call and would therefore be totally unaware of any outstanding calls they might have.

To solve this problem, there is a feature available that allows Supportworks to copy the message sender’s e-mail address from the displayed message header (rather than from a customer record) to the call being logged. Outstanding calls would subsequently be recognised by matching the incoming e-mail address directly with those held in the call records. You enable this feature by first creating a new folder called “Email Integration” within Global Parameters. In that folder, you would then create the first of the following three parameters and, optionally, the second and/or third one as well:

EmailTargetField The value of this parameter should indicate the column, normally in the Open/Closed Call table, into which the message sender’s e-mail address is to be placed. Typically, this string value would be opencall.email (or just email is enough if the table you are using is opencall).

RemoteQuery The value of this parameter should specify the name of the Remote Query to be used in the merging of e-mail data into the outbound customer-notification e-mail messages that the system generates whenever analysts perform relevant call actions. If you omit this parameter, the name of the Remote Query defaults to Call.


259

Note Before using the RemoteQuery parameter in any given data dictionary, you must ensure that all call classes defined in that data dictionary have the same remote query selected. If you actually need to have a different Remote Query for each call class, you have to accept that you cannot use this feature.

DontResolveCustomers The value of this parameter determines whether or not the system will attempt to resolve a customer from an incoming e-mail message whenever the message is displayed. As this will be an unnecessary overhead if you do not have a customer table, you should set the value to a string value of True or a numeric value of 1.

In the following example, all three parameters are used:


260

Filtering the Display of Client/Server Connections (Optional)

261


The Manage Server Connections administration facility on the client displays a window that normally lists all the current client connections on the Supportworks server. However, it is possible to create a filter that limits the client/server connections shown in this window to those that conform to specified criteria. This is done using the Data Dictionary Editor.

If you wish to set up such a filter, you must first create the folder, within Global Parameters, in which it is to be held. The name of that folder must be “Server Connection Dialog”. In that folder, you would then create the required filter parameter, which must be named “Filter”. The string value of this parameter would be an SQL expression that stipulates the criteria governing which client connections are (or are not) to be listed in the Manage Server Connections window. A suitable criterion would involve any factor represented as a column in the swsessions table (which is in the sw_systemdb database).

For example, if you wanted to restrict the visibility of client connections to those using the data dictionary called “Standard”, you would create the following filter:


262

Defining Third Party SLA Functionality (Optional)

263


If your support team outsources hardware maintenance or any other kind of specialist support to third-party suppliers, you may need to have not only the main Service Level Agreements with your customers, but also third-party SLAs with the outsource organisations concerned.

To allow a given data dictionary to support this extra SLA scheme, you must first create, using the Data Dictionary Editor, a new folder called “Third Party SLAs” within Global Parameters. In that folder, you should create the first of the following three parameters and, optionally, the second and/or third one as well:

Enable The value of this parameter determines whether or not the third-party SLA functionality is enabled. A string value of True, or a numeric value of 1, will enable the feature.

DisplayHoldOption The value of this parameter determines whether or not an Update Call dialogue is displayed whenever an analyst assigns a call to a third-party SLA. This dialogue gives the analyst the option to place the call on hold and to enter an update description for the call diary. A string value of True, or a numeric value of 1, will force the display of this dialogue, and the default “on hold” option setting on the dialogue will reflect the corresponding option as set for the SLA concerned.

SecondsBeforeFixTimeToComeOffHold The numeric value of this parameter determines the latest time that calls assigned to a third-party SLA should come off hold. It is a specification of how long (in seconds), before expiry of the target third-party-SLA fix time, a call must (at least in theory) come off hold. As well as defining the latest off-hold point for calls that are placed on hold automatically, this parameter is also used to calculate the default date/time to which the “Place call on hold until” value in the Update Call dialogue is set initially. If this parameter is omitted, the period is 0 seconds by default, which means that calls would be due to come off hold precisely when the fix time expires.

In the following example, all three parameters are used:


264

CTI Customer Look-Up (Optional)

265


If your Supportworks system has CTI enabled, the Customer table used for looking up the record of an incoming caller will be userdb by default. The system will expect to find the table’s primary key (the customer ID) in the keysearch column. It will expect to find the customer’s telephone number in the telext column, their first name in the firstname column, and their last name in the surname column.

However, if your system uses a different Customer table, and/or uses a different set of columns, you will have to impart this information to it. You do this by first creating, using the Data Dictionary Editor, a new folder called “CTI” within Global Parameters. In that folder, you should create any of the following parameters, as required:

CtiLookupTableName The value of this parameter gives the name of the Customer table being used. If this parameter is omitted, the default table will be assumed.

CtiLookupCustomerID The value of this parameter gives the name of the column being used as the primary key for locating the customer’s record within the table concerned. If this parameter is omitted, the default column will be assumed.

CtiLookupTelephone The value of this parameter gives the name of the column, within the table concerned, that holds the customer’s telephone number. If this parameter is omitted, the default column will be assumed.

CtiLookupFirstName The value of this parameter gives the name of the column, within the table concerned, that holds the customer’s first name. If this parameter is omitted, the default column will be assumed.

CtiLookupLastName The value of this parameter gives the name of the column, within the table concerned, that holds the customer’s surname. If this parameter is omitted, the default column will be assumed.

In the following example, all five parameters are specified (with the default values shown):


266

Application-Specific Customisation

267


Certain areas of customisation or configuration will apply only to specific Supportworks applications. The set of Global Parameters relating to a given application will be found only in the data dictionary that is supplied with it, or (in the case of optional parameters) they can be created in that data dictionary. In the Data Dictionary Editor, these parameters would be visible in the root of the “Application Settings” folder and in the sub-folders belonging to it. The VCM module, which is common to more than one application, has its own parameter folder, and this must be created at the top level of Global Parameters.

Only the VCM settings are documented in this chapter. All other application-specific settings are covered in the respective template-specific Administrator Guides.

Customising the Visual Configuration Manager (Optional)The Visual Configuration Manager (VCM) is applicable to the Supportworks ITSM and Supportworks Customer Support applications. If you wish to alter certain aspects of how the VCM displays information in its window, you can do so by means of appropriate Global Parameter settings.

Within Global Parameters, you first have to create a folder called “VCM”. In that folder, you can then create either (or both) of the following parameters, as required:

NodeWidth The numeric value of this parameter specifies the default spacing, in pixels, to the right of each icon displayed in a View tab, including the width of the icon itself (which is 40 pixels). This effectively determines the horizontal spacing between adjacent icons. In the absence of this parameter, the value defaults to 50, giving an actual spacing of 10 pixels.

NodeHeight The numeric value of this parameter specifies the default spacing, in pixels, below each icon displayed in a View tab, including the height of the icon itself (which is 40 pixels). This effectively determines the vertical spacing


268

between adjacent icons. In the absence of this parameter, the value defaults to 60, giving an actual spacing of 20 pixels.

In the following example, the actual inter-icon spacings have been increased to 60 and 80 pixels, respectively:

Remote Queries

269

Remote Queries

A Remote Query is a process that is run by the Supportworks server following an action (such as a call update) that requires the automatic generation of one or more outgoing e-mail messages. The results of the process are used to specify the necessary outbound e-mail address(es), and are also used to resolve the macro variables in the e-mail template on which the generated mail is based. The process involves submitting SQL statements to gather the values of some of the variables from appropriate table columns and, if necessary, passing data from the client to make up the values of the remaining variables. The process can also involve the acquisition of customer-specific regional settings, which would then be made available to all variables whose contents need to be localised. (Note that current-date, current-time and analyst-related variables are resolved directly by the system, and no Remote Query process would be involved with these, except in relation to regional-setting look-up.)

Each Remote Query is stored on the server as a named entity, and its components are displayable on the client via an administrative command. By creating extra components for a Remote Query, you can make new variables available to the relevant e-mail templates (including regional-setting variables). On a newly installed system, only one Remote Query is configured; it is named Call, and is the one relating to call actions.

When a call is logged or updated, the server runs the Call query, which, in accordance with its configuration, gathers data from the appropriate records of various Supportworks tables, and also accepts data passed from the client. The server places all this data into a temporary table accessible by the mechanism that generates customer-notification e-mail messages. This table would then contain the e-mail address of the customer concerned, as well as the current values of all the possible macro variables that are available to the e-mail template used to generate the customer notification. It may also contain values of any regional-setting variables that are referenced by localisable macro variables. Once the analyst has selected an appropriate template, the client takes the e-mail address and the values of the template’s constituent variables from the temporary table and merges these respectively into the message header and the message text, and then displays the resolved message in a window on the

Remote Queries

270

analyst’s desktop, ready to be sent to the customer. If regional-setting components are defined in the Remote Query, their values will have been used to translate, for example, default date/time values to their localised equivalents, presented in a format appropriate to the customer concerned.

The system also supports other kinds of client-based actions that generate e-mail messages automatically, such as bulk-mailshot requests. For each action of this kind, you have to create a new Remote Query and a new e-mail template of the appropriate category. The processes associated with such queries will be much the same as for the Call-query process described above, although they may be initiated by a dedicated menu-command action, rather than by an action that is part of another process.

When you display the components of a particular Remote Query, you will be able to see all the elements that are used to build the required SQL statements, and those that define the names of the variables. You will be able to modify any of these elements for a given component, delete any component and add new components, all without needing to have extensive knowledge of SQL syntax.

Viewing the Components of a Remote QueryAs the first step to being able to modify the “pool” of macro variables for a set of e-mail templates, you have to display the existing variables within the relevant Remote Query. To view these components, first select Manage Remote Queries from the Administration. The following dialogue box is displayed:

In the list of queries, ensure that the one you wish to view is highlighted, and click Properties. The following dialogue box is displayed:

Remote Queries

271

The lower half of this dialogue box consists of a tabulated list of query components, each of which represents a template variable and indicates the parameters of the method by which the system obtains a value for it. A method can be either the submission of an SQL statement that fetches the value from a specified table column, or the act of passing the value to the server via an argument in the program code.

A component that you are certain to find in every Remote Query is one concerned with e-mail addressing, as such addressing is necessary for sending the generated mail to its required destination(s). This component therefore serves the dual purpose of address and macro-variable provision. If a Remote Query also contains components relating to a first name and a last name, the system will display this pair of values in the To field of the message window, otherwise the e-mail addressing itself is displayed.

The upper half of the Remote Query Properties dialogue box comprises a number of parameter fields relating to the Remote Query as a whole. The topmost field, labelled Query Name, defines the name of the Remote Query. This is the name by which analysts would select the query from the Remote Query field’s drop-down list in the Manage E-Mail Templates dialogue box.

Remote Queries

272

Certain SQL statements in a Remote Query such as the Call query are designed to look for records relationally, as the client is able to submit only a single key (for example, one or more call references) with which to start searching through multiple tables. The table queried using that initial key is known as the Primary Table, which, in the case of the Call query, would be the opencall table. The common parameters used in each Primary Table query statement are defined in the remaining fields at the top of the Remote Query Properties dialogue box. Their meanings are as follows:

Source Database This is the name of the database in which the Primary Table is to be found. It is repeated, under the Source heading, for each query component in the tabulated list that relates solely to the Primary Table.

Primary Table This is the name of the Primary Table. It is repeated, under the Table heading, for each query component in the tabulated list that relates solely to the Primary Table.

Primary Criteria This is an expression that picks out the required record(s) in the Primary Table for all statements in the query, using an appropriate column in that table as the key. The value set to be matched against is given by the IN(%1) function, which is a short-hand way of specifying a multiple-ORed equality, with %1 representing the key value (or set of key values) passed from the client.

The Individual Elements of Remote Query Components

The headings of the tabulated list of query components in the Remote Query Properties dialogue box have the following meanings:

Field Name The items here are the names of the columns of the temporary table, created by the query, into which the collected values are placed. They represent the macro variables that are made available to the set of e-mail templates with which the query is associated. Thus, for example, the field name callref would translate into the variable $callref!.

Display Name These items define the user-friendly names of the variables, as displayed in the drop-down list used in the Manage E-Mail Templates dialogue box for selecting variables to be inserted into a template.

Remote Queries

273

Source These items specify, by name, the databases in which the respective tables are to be found. The database names are used in the USE clauses of the SQL statements that are built and executed whenever the query is invoked.

Table These items specify, by name, the tables from which the respective query statements take the variable values. The table names are used in the FROM clauses of the SQL statements that are built and executed whenever the query is invoked.

Expression These items specify, by name, the columns, within the indicated tables, from which the respective query statements take the variable values, or they specify the intermediate program-code variables into which the values passed from the client are placed. Expressions that specify table columns are used in the SELECT clauses of the SQL statements that are built and executed whenever the query is invoked.

Criteria For statements that query, and take variable values from, tables related to the Primary Table, these are expressions that pick out the required records in those tables, using an appropriate column in each table as the key. The syntax within the quotes (of the form &[<table>.<column>]) specifies the column in the Primary Table that relationally points to the targeted table. The criteria expressions, once relationally resolved, are used in the WHERE clauses of the SQL statements that are built and executed whenever the query is invoked.

Modifying a Remote QueryFrom within the Remote Query Properties dialogue box, you can modify any of the individual elements of a selected query component (for example, the display name of a variable), you can create new components (if you want new macro variables to be made available in the relevant set of e-mail templates), and you can delete components (if you no longer need certain variables in those templates).

Once you have made your changes, you should click OK to save them and close the dialogue box. Alternatively, you could invoke a function that allows you to quickly preview the results generated by the Remote Query before trying to execute a proper client action.

Remote Queries

274

To Modify the Elements of a Query Component

If you wish to alter the name or display name of an existing template variable, or change any of the parameters of the SQL statement used to find values for the variable, first select the relevant query component from the tabulated list in the Remote Query Properties dialogue box and click Properties. The following dialogue box is displayed:

The meanings of the fields are the same as those of the headings described in The Individual Elements of Remote Query Components on page 272. Make the changes you require and click OK.

Note that, for a query component designed to handle variable values passed from the client, only the Field Name, Display Name and Expression fields are meaningful. You should avoid changing the contents of the Expression field in such a component, as values will then not be handled correctly.

To Create a New Query Component

If you wish to add a new macro variable to the pool of available variables, first click New in the Remote Query Properties dialogue box. The same dialogue box is displayed as when you elect to modify the elements of an existing query component. Again, the meanings of the fields are the same as those of the headings described in The Individual Elements of Remote Query Components on page 272. The kind of additional query component you would create must be one that is designed to generate an SQL statement. Type suitable text and select suitable items in the fields, and click OK.

Remote Queries

275

You will notice that the new component has been added to the bottom of the tabulated list. It is best to then move the component up the list, using the Move Up button, in order to group it with other components having the same table specified. The components will be processed in the order in which they appear on the list. Those components that have the Primary Table specified must always be at the top.

Note that it is not meaningful to create any additional query components that are designed to handle variable values passed from the client (unless you are reinstating ones previously deleted), as these will not be recognised by the program code.

To Delete a Query Component

If you wish to delete a macro variable from the pool of available variables, just ensure that it is highlighted on the tabulated list in the Remote Query Properties dialogue box, and click Delete. No confirmation prompt is given.

To Preview the Results of a Remote Query

The Remote Query process places the values obtained from database tables into a temporary table, where they can be accessed by the appropriate mail-generation mechanism. These results are held in the table as a series of customer records. The columns of this table correspond to the respective components of the Remote Query concerned, and also include an internally used ID column.

To preview the records in the temporary table, click the Preview Results button in the Remote Query Properties dialogue box. The Query Results window is displayed, showing all the generated records. In the case of a Remote Query with two components, for example, the results might be as follows:

Remote Queries

276

Notice that all customer records are shown, including those without an e-mail address. You should be aware that the resulting e-mail messages will be generated only for customers whose records contain an e-mail address. It is up to the support team to ensure that the original database records are complete.

Creating and Deleting Remote QueriesYou would need to create a Remote Query for any client action that invokes the creation of one or more template-based e-mail messages, assuming that the action is one that depends on a Remote Query process to resolve the macro variables in the e-mail templates concerned. A bulk-mailshot request would be an example of such a client action. Currently, a bulk-mailshot request is the only kind of client action that can make use of Remote Queries you create yourself.

To create a Remote Query, first select Manage Remote Queries from the Administration menu, thus causing the Manage Remote Queries dialogue box to be displayed. In that dialogue box, click New to display an empty version of the Remote Query Properties dialogue box. You can now proceed to fill in the details of the new Remote Query and to create its required components, as described in Viewing the Components of a Remote Query on page 270, and in Modifying a Remote Query on page 273.

You will always need to construct at least one query component for any new Remote Query you wish to create. This component must be designed to gather

Remote Queries

277

the required e-mail addressing from a database table that contains such information. The usual table of customers (for example, userdb) in the swdata database would normally be the most appropriate.

If you wish to merge data from Supportworks tables into the generated mail arising from a Remote Query, you will also need to create one query component for each and every other macro variable that you want to make available to the mail template(s) relating to that Remote Query.

To delete a Remote Query, highlight it on the list of queries in the Manage Remote Queries dialogue box and click Delete. Click Yes at the confirmation prompt.

Considerations Relating Specifically to Bulk Mail

When constructing a Remote Query for bulk mail, it is possible that you will not want any components in it other than the mandatory one relating to e-mail addresses. However, if you want the customer’s name to appear in each generated mail message (either in the text or in the To field), you should also create a component relating to first names and another relating to last names.

In the Expression field for the e-mail addressing component, you must enter the name of the column that relates to e-mail addresses. If the table of customers is userdb, the required column name would be email. For each name component (if any), you would enter, in the Expression field, the name of the column relating to first names or to last names, as appropriate. With userdb as the table, the required column names would be firstname and surname, respectively.

You should leave all criteria fields blank, as bulk-mailshot requests do not require key values to be passed from the client.

Note that the table containing the e-mail addresses (and also the first and last names) would be regarded as the Primary Table.

Components for Querying Regional SettingsIf you want localised data to be merged into outbound e-mail messages, you first of all have to add, to the Customer table, extra columns in which to store the

Remote Queries

278

required regional settings, which the Remote Query will then be able to access via SQL. Regional settings are made up of the following attributes:

• Time zone

• Date format

• Time format

• Date/time format

• Currency symbol

You will need to create a Customer table column for each one of these attributes that you want localised. You can give such a column any name you wish. It should be of data type VARCHAR, with a maximum data size of 64.

Once you have created the required columns, you will have to add corresponding fields to the customer form, bound to the columns concerned. It is via these fields that analysts will be entering the regional data for each customer record. Date and time formats will be typed into text fields using the same syntax as in all other regional-settings areas of Supportworks, while the time zone will be entered by selection from the relevant field’s drop-down list.

Time zones are stored in the system_timezones table, which is in the sw_systemdb database. In this table, there are two columns that hold data identifying each time zone: name and description. The contents of name are what must end up in the Customer table, but it is the contents of description that are displayed elsewhere in Supportworks. Therefore, when you create the time zone field on the customer form, you have to ensure that the following field attributes are set to the values shown:

Field Mode Distinct Pick ListData Source Name syscacheDistinct Table system_timezonesDistinct Column nameDisplay Column description

You can now create a new Remote Query component for each of the regional-setting attributes. In the Query Result Field Properties dialogue box, fill in the fields as follows:

Field Name This must be one of the following, depending on the attribute to be associated with the query component:

Remote Queries

279

timezonedateformattimeformatdatetimeformatcurrencysymbol

You must ensure that you spell the field name exactly as above.

Display Name This can be anything you want, to be used for your own reference. It will be displayed in the Manage E-Mail Templates dialogue box, along with all the other user-friendly variable names (although you would not normally want to actually display its value in an e-mail message).

Source This must be swdata.

Source Table This must be the name of the Customer table, normally userdb.

Expression This must be the name of the column, in the Customer table, that holds the regional-setting attribute concerned.

Criteria This must be an expression that resolves the key for the record, in the Customer table, that contains the relevant customer’s regional settings. It would normally be keysearch = ‘&[opencall.cust_id]’.

Once you have set up the database, the customer form and the Remote Query as described above, and analysts have entered the regional-setting information for each customer, all outbound e-mail messages will be localised.

Remote Queries

280

Server-Side Event Scripting

281


Server-side event scripting is a methodology that allows people with appropriate skills to define extensions to Supportworks processes, which would be triggered by Supportworks events and executed via scripts. A built-in mechanism allows Supportworks to monitor operations carried out on its database tables by users and, on the occurrence of specific operations, to perform a specified action or series of actions via a user-written script. The actions may be performed on the Supportworks database tables themselves, using functions built into the script language, or they may be performed on any other database, on any application, or on the operating system, assuming that the necessary APIs are installed. Scripts may be written in any script language, although PHP is strongly recommended.

As far as its most basic capabilities are concerned, server-side event scripting can be likened to the database-trigger/stored-procedure mechanism available on most commercial SQL servers. A database trigger specifies a stored procedure that is to be invoked when a particular database event occurs. The procedure would consist of one or more SQL statements executable on that same database. This kind of mechanism effectively allows the database to be truly relational, which means that the database can be set up so that when a user makes certain changes in the database, appropriate changes to related data will automatically be made at the same time.

However, server-side scripting on Supportworks offers much more than this. Its advantages, in comparison with the trigger/procedure mechanism, are as follows:

• There is no database dependency. Whereas triggers/procedures are vendor-specific database extensions that will not work on other databases, server-side scripts are totally independent of the database on which the scripted actions are performed.

• Actions are not limited to database operations. Because actions are defined in a general-purpose scripting language, and there is a rich set of API support available (especially for PHP), it is possible for server-side scripts to invoke a variety of operating-system functions, as well as functions in other


282

applications. Even for database operations, a scripting language is able to provide far more powerful and highly structured logic than SQL on its own in a stored procedure.

• More precise database events can be recognised. Conventional database triggers can only refer to generalised events (that is, add, update and delete), as the SQL database is unable to comprehend the precise meanings ascribed to such events by the application using the database. However, Supportworks is able to pass exact information to a call-related script on the operation that was being carried out when the script was invoked.

With server-side scripting enabled on the Supportworks server, the system will monitor add, update and delete operations on all database tables, and, when it detects such an event, will look (in a designated folder) for a script file whose name contains the name of the table concerned and also an indicator of the operation detected. On finding such a script filename, the system invokes the designated script interpreter (passing all the required data), which executes the script itself.

It is your responsibility to create (or arrange for others to create) the contents of your script files, depending on what exactly you want to make happen as a result of specific database operations occurring. For example, you may wish to automate the creation of new Windows NT accounts, triggered by suitable support calls from departmental managers, or by the addition of new internal customers to the Customer database. Or, you may wish to maintain a database of customers for another department, running separately but parallel to the Supportworks Customer database, so that every change made to the latter will be automatically reflected in the former. All such requirements can be accommodated using server-side scripting.

Your scripts can be written in any scripting language you or your assignees are familiar with, and the appropriate interpreter should be installed on the same computer as the one on which the Supportworks server resides. Typical examples of popular scripting languages include PHP and Perl. A recent version of PHP is supplied with Supportworks, installed in c:\Winnt\system32. A comprehensive collection of APIs for the PHP environment is also provided.


283

How Server-Side Scripting WorksWhen the Supportworks server detects the occurrence of a database operation, it first tries to establish the existence of a script file relating to the particular database table and kind of operation that it just detected. The folder that the server looks in is C:\Program Files \Hornbill \Supportworks Server \scripts by default. The server actually looks for script files whose name formats correspond to those shown below, reflecting the three types of general database operation monitored:

Once the server has located a script file with a name in such a format, containing the relevant table name and operation type, it runs the script interpreter (for example, php.exe), passing the pathname of the script via an argument variable %s. Also, data associated with the monitored database operation is passed, in the form of preset variables, to the interpreter’s global name space for use by the script itself. Included in this data will be the whole of the database record affected by that operation (both “before” and “after” versions in the case of an update). The following conditions determine exactly what data is passed and how the variables representing that data are named:

• For an “on_<table name>_add” script, the value in each column of the relevant database record is passed as a variable whose name is of the form:new_<table name>_<column name>.

• For an “on_<table name>_update” script, both the original version and the updated version of the relevant record are passed. With respect to the original version, the value in each column of the database record is passed as a variable whose name is of the form:old_<table name>_<column name>.With respect to the updated version, the value in each column is passed as a

Monitored Database Operation Script Filename

A new record being added to any table on_<table name>_add

An existing record in any table being updated on_<table name>_update

An existing record in any table being deleted on_<table name>_delete


284

variable whose name is of the form:new_<table name>_<column name>.

• For an “on_<table name>_delete” script, the value in each column of the deleted database record is passed as a variable whose name is of the form:old_<table name>_<column name>.

• For a specifically call-related “on_opencall_add” script, the data passed will be as described in the first bullet point above. In addition, for such a script, an appropriate call-action specifier is passed as a variable named CallAction. The call-action specifier can be either of the following:

• For a specifically call-related “on_opencall_update” script, the data passed will be as described in the second bullet point above. In addition, for such a script, an appropriate call-action specifier is passed as a variable named CallAction. The call-action specifier can be any of the following:

Call-Action Specifier Meaning

newcall A new call has been logged

callreactivated A call has been logged by reactivation


logincomingcall A call with Incoming status, previously submitted for logging via the SelfService application, has now been logged on the client

logdeferredcall A deferred call has been logged by the system

acceptcall The call has been accepted by an analyst

changeprobprofile The call has had its problem profile changed

changefixprofile The call has had its resolution profile changed

calllinkedtoissue The call has been linked to a Hot/Known Issue

callunlinkedfromissue The call has been unlinked from a Hot/Known Issue


285

As the script executes, your programming instructions are carried out. In the script, any instruction that includes variables relating to specific columns in the monitored table may serve to make the data available to the triggered action, or may serve to establish whether the main part of the script is to be executed. In a

callclasschanged The call has had its class changed

customerchanged The call has had its related customer record changed (if associated with the Customer table, userdb)

contactchanged The call has had its related contact record changed (if associated with the Contact table, contact)

assetchanged The call has had its related asset record changed (if associated with the Asset table, equipmnt)

componentchanged The call has had its related component record changed (if associated with the Component table, component)

<update action> This can be any specifier, defined in the data dictionary for a given Call Details form under Associated Tables, whose meaning would be that the call has had a record (relating to a particular custom table) changed

cancelcall The call has been cancelled

assigncall The call has been assigned to an analyst

escalatecall The call has been escalated

updatecall The call has been updated

callonhold The call has been placed on hold

calloffhold The call has been taken off hold manually

syscalloffhold The call has been taken off hold by the timer

resolvecall The call has been resolved

closecall The call has been closed



286

call-related script, a statement including the CallAction variable would similarly serve the purpose of determining whether the remainder of the script should be executed.

Creating a Script FileBefore writing or commissioning a script, you have to decide what language it is to be written in, exactly what task it is to perform, what monitored database operation should initially trigger its execution, and what precise conditions (if any are required) should allow its execution to proceed. During the process of deciding on all this, the exact items of data, relating to the monitored operation on a database record, that will need to be passed (by means of variables) to the triggered action in the script will become apparent. This data will be the contents of one or more appropriate columns in any of the Supportworks database tables.

The monitored database operation will be an addition, update or deletion of a record in the table concerned. If you require a more precise set of conditions for proceeding with the task to be performed (perhaps based on the specific value of a table column), you can write a suitable conditional statement at the beginning of your script. If performance of the main task in the script is to be dependent on a specific call action, you can make the script determine whether that action has occurred by stipulating the necessary contents of the CallAction variable at the beginning of the script, which similarly sets the condition for proceeding with the script’s execution.

If you decide to use a scripting language other than PHP, you must change the command that Supportworks invokes to run the scripts, so that this will reflect the requirements of your chosen language. By default, the script command line is set up to run PHP scripts. To change the command line, please refer to the chapter on server-side scripts in the Server Configuration Guide.

Having decided on a scripting language, as well as on a suitable monitored operation and appropriate conditions for carrying out the required task, you should be able to see from the first table above what the name of your intended script file will have to be. You must name the file exactly as indicated, although you are free to use either upper- or lower-case for any letter. For the <table name> part of the filename, you should substitute the actual name of the database table on which the monitored operation will occur. The actual names


287

(along with the user-friendly names) of the default Supportworks database tables are given in the appendix at the end of this Guide. In the case of a call-related operation, the table name will always be that of the Open/Closed Call Table (opencall). You can use any extension for the script filename, preferably one that is appropriate to the script language you have chosen (for example, .php).

Once you have written, if required, the preliminary conditional code in your script, you can start writing the code that will perform the triggered task. What code you write is entirely up to you and the task in question. If the task is merely to perform a series of relational actions on the Supportworks database, you may only need to specify the built-in function calls that create an ODBC connection to the database and execute the required SQL statements (which may themselves include any required conditions).

If the task is intended to include operations on the Supportworks application itself, you are free to use the Supportworks-specific API functions provided. They are designed to work with PHP only, and come pre-installed in the system’s PHP environment. See API Functions Specific to Supportworks on page 289 for a description of these functions.

If the task to be performed consists of operations on external databases, other applications, or the operating system somewhere on your network, you can make use of the large selection of API functions that are available from vendors and various sources on the Web. A substantial number of these (intended for PHP) are provided with Supportworks, again pre-installed in the system’s PHP environment. See List of Supplied APIs on page 292 for a list of the APIs installed.

In summary, the script you produce will have to contain the following elements:

(a) A conditional test right at the start that would positively identify the exact database conditions required for the task to be carried out, and therefore allow the remainder of the script (containing the actual task instructions themselves) to be executed. This test would typically specify sought values for any of the variables available in the global name space.

(b) Instructions to perform the required task on the chosen column data, referring (where necessary) to the variables concerned. Use of certain API functions may be appropriate here.


288

(c) Alternatively, one or more function calls to create the ODBC connection and to execute SQL statements on the Supportworks database. These statements would constitute the required task. The SQL statements would include conditional tests to identify the data that must be used in performing the task.

During the process of coding a script, it is important to be aware that, once the script is triggered by a database operation arising from, say, the act of logging a call, control will not return to the client until the script has finished running. This means that you should write reasonably efficient code if you want the delay to be relatively imperceptible.

Once your script is complete, you should place it in C:\Program Files \Hornbill \Supportworks Server \scripts, or whatever other folder you wish to use for such scripts. If you want to change the script path, you must specify the new path in the server configuration (see the chapter on server-side scripts in the Server Configuration Guide).

Finally, you must remember to enable server-side scripting. You do this in the server configuration as well, as described in the chapter on server-side scripts in the Server Configuration Guide.

Testing Your Script

The following two interrelated facilities are provided to help you with debugging:

• A utility program known as the Script Debug Output Monitor, which displays all screen output generated by suitable code in your script. Its filename is swdbgmon.exe, and it is located in C:\Program Files \Hornbill \Supportworks Server \bin.

• A Supportworks-specific API function called swdebug_print, which you can use to generate any desired marker text on the Script Debug Output Monitor. See The Functions and their Descriptions in the section below, entitled API Functions Specific to Supportworks, for details of the required syntax.

To debug a script, first enter trace code by calling the swdebug_print function at strategic points within the script, and then save it. Ensure that the script file is located in the correct folder, and then run the Output Monitor. Once you have enabled server-side scripting, carry out an operation on the Supportworks client that should trigger the script. Observe the trace marker text appearing on the


289

Output Monitor as the script runs. If any of the markers fail to appear, you should investigate your code appropriately.

API Functions Specific to Supportworks

In this section, you will find the formal definition (or “prototype”) of each function available for PHP programmers in the Supportworks API, together with a description of the action it performs. The purpose of these functions is to provide access points into the Supportworks application from server-side scripts written in PHP.

Each function prototype is presented in the following format:

<return_type> <function> (<argument_type> <argument>)

where:

<return_type> defines the type of value returned by the function;<function> is the name of the function;<argument_type> defines the type of argument that is input to the function;<argument> is the argument that is input to the function.

The types of return and argument can be any of the following:

long – a 32-bit numberstring – an alphanumeric stringbool – a logical value of 1 (for “true”) or 0 (for “false”)

Some functions specify more than one possible argument-type/argument pair, in which case a comma is used to separate the pairs.

The Functions and their Descriptions

long swtime (string period_limit)

The swtime function takes a string indicating the start or end of a given period of time, and returns the appropriate epoch time (UTC).

The possible period limits are:

STARTOFTODAYENDOFTODAY


290

STARTOFWEEK ENDOFWEEKSTARTOFMONTHENDOFMONTHSTARTOFQUARTERENDOFQUARTERSTARTOFYEARENDOFYEARSTARTOFYESTERDAYENDOFYESTERDAYSTARTOFLASTWEEKENDOFLASTWEEKSTARTOFLASTMONTHENDOFLASTMONTHSTARTOFLASTQUARTERENDOFLASTQUARTERSTARTOFLASTYEARENDOFLASTYEAR

The above strings are not case-sensitive. A string with a START prefix would return an epoch time corresponding to 00:00:00 on the first day of the period indicated (or on the actual day), and a string with an END prefix would return an epoch time corresponding to 23:59:59 on the last day of that period (or on the actual day).

string swstatus_str (long status)

The swstatus_str function takes a numeric call-status value (as obtained from the database), and returns the call status as a user-friendly string (for example, Pending, Unassigned, and so on).

string swstatus_color (long status)

The swstatus_color function takes a numeric call-status value (as obtained from the database), and returns the corresponding call-status colour in the format “#rrggbb”.


291

string swwostatus_str (long status)

The swwostatus_str function takes a numeric work-item-status value (as obtained from the database), and returns the work-item status as a user-friendly string (for example, Pending, Complete, and so on).

string swwostatus_color (long status)

The swwostatus_color function takes a numeric work-item-status value (as obtained from the database), and returns the corresponding work-item-status colour in the format “#rrggbb”.

string swcallref_str (long call_ref)

The swcallref_str function takes a purely numeric call reference number (as obtained from the database), and returns the call reference number as a string representation in the format “Fnnnnnnn”.

string swdsn

The swdsn function returns the name of the ODBC data source in use by the Supportworks server.

string swuid

The swuid function returns the user ID associated with the ODBC data source in use by the Supportworks server.

string swpwd

The swpwd function returns the password associated with the ODBC data source in use by the Supportworks server.

bool swdti_load (string data_dictionary_name)

The swdti_load function loads the named data dictionary into the context of the current PHP session. This function should always be called before any attempt is made to access customisable data from the database. If the function call is successful, the function returns “true”, otherwise it returns “false”.


292

string swdti_getcoldispname (string table.column)

The swdti_getcoldispname function returns the display name of the column specified, within the table specified. In order for this function to work correctly, a successful call to the swdti_load function must have been made first.

bool sw_createdir (string folder_name)

The sw_createdir function creates the folder specified. The folder name can be specified in the form of a local path or a UNC path. If the function call is successful, the function returns “true”, otherwise it returns “false”.

bool sw_deletedir (string folder_name)

The sw_deletedir function deletes the folder specified. The folder name can be specified in the form of a local path or a UNC path. If the function call is successful, the function returns “true”, otherwise it returns “false”.

bool sw_renamedir (string old_name, string new_name)

The sw_renamedir function changes the specified folder’s name to the new one. The folder names can be in the form of a local path or a UNC path. If the function call is successful, the function returns “true”, otherwise it returns “false”.

bool swdebug_print (string text)

The swdebug_print function outputs the specified marker text to the Supportworks Script Debug Output Monitor window. If the function call is successful, the function returns “true”, otherwise it returns “false”.

List of Supplied APIs

The following is a list of all the APIs supplied with Supportworks for use with server-side scripts written in PHP. Each API comprises a number of related functions that a PHP script can call. If you wish to obtain information on these functions, a good starting point would be the Function Reference chapter of the PHP manual at http://www.php.net/docs.php.


293

BCMath arbitrary precision mathematics functionsBzip2 compression functionsCalendar functionsCOM support functions for WindowsClibPDF functionsCybercash payment functionsCrédit Mutuel CyberMUT functionsDate and time functionsdBase functionsDOM XML functionsFrontBase functionsfilePro functionsFTP functionsHTTP functionsImage manipulation functionsIMAP, POP3 and NNTP functionsInformix functionsInterBase functionsIngres II functionsIRC Gateway functionsJavaLDAP functionsMail functionsMathematical functionsMCAL functionsMcrypt encryption functionsMicrosoft SQL Server functionsMing functions for FlashmSQL functionsMySQL functionsNetwork functionsODBC functionsOracle 8 functionsOpenSSL functionsPDF functionsVerisign Payflow Pro functionsPostgreSQL functions


294

Program execution functionsPrinter functionsRegular expression functions (Perl-compatible)Satellite CORBA client extensionSESAM database functionsShockwave Flash functionsSNMP functionsSocket functionsString functionsSupportworks-specific functionsSybase functionsXML parser functionsZip file functions (read-only access)Zlib compression functions

Visual Process Management

295


Note Visual Process Management is not available in Supportworks Essentials.

This separately licensable feature allows you to define automated business processes to support the operational business practices of departments throughout the organisation, where the processes would run as event-driven extensions of standard Supportworks activity. You define the business processes in the form of functional flowcharts that you create using the easy-to-use Supportworks Visual Process Manager (VPM). The components of each flowchart, representing the individual process actions and the process flow, are built up by simple drag-and-drop methods, and are configured using a context-sensitive Properties panel. Once complete, this process information is saved as an XML script file. The Supportworks Visual Process Management Engine (VPME) would then run that script and thus perform the required actions whenever it detects a Supportworks event of the type that is supposed to trigger the process, or whenever it receives instructions from another script to do so.

This feature can be regarded as a user-friendly version of server-side event scripting, with the added bonus of vastly improved performance and increased flexibility. Again, the triggering event for a process can be an operation occurring on a specified database table or the occurrence of a specific call action, and the resulting process can include actions on Supportworks itself, on the Supportworks database, or on the operating system. However, VPME processes can be triggered by other events as well, as described in the section Process-Triggering Events below.

A typical scenario in which the Visual Process Management feature could provide a solution might be as follows. The Legal department has a requirement to create, in parallel with the Supportworks database system, a defined folder structure for holding data and correspondence relating to each supported customer. Whenever a new customer record is added to, or removed from, the Supportworks database, a folder hierarchy for that customer should be automatically created at a given network location or deleted from there. Furthermore, forms in Supportworks should include controls that allow analysts


296

to forward any received data or correspondence to the relevant parts of the folder structure.

Process-Triggering EventsAny of the following types of event can trigger an appropriately configured VPME process:

• An application-related event, which would typically relate to Supportworks calls.

• A database table-related event, which could be any SQL query that adds, updates or deletes a record.

• A user-defined event such as:

– The execution of a suitable JavaScript function, which makes it possible to run VPME processes from Supportworks forms

– The running of the swvpmeinvoke.exe command, which provides scope for scheduling processes

– The submission of an Auto Responder command, which makes it possible for customers to run authorised processes via e-mail

Note that all user-defined events would be designed to pass appropriate sets of predefined parameters to the VPME processes they are expected to trigger.

Starting and Using the Visual Process ManagerTo invoke the Visual Process Manager, run the Supportworks client and select Administration > Manage VPME Processes.


297

In this window, you will be able to create any number of processes by drawing the flowcharts that represent them, each typically identified by the Supportworks event that triggers it. You will also be able to create flowcharts for sub-processes that are not directly triggered by events. These sub-processes would be called by processes that are event-triggered, thus making it possible to run more than one functional process (sequentially) from a single event.

You build a flowchart by first creating, in the tree browser in the Processes pane, an item that identifies the process concerned (typically by its triggering event). With that item highlighted, you would then proceed to add, in the Process Design tab, the required nodes and flow lines. Finally, you would define, in the Properties pane, the precise function that each node has to perform.

Once you have created flowcharts, you can use the Visual Process Manager again to view and edit them. You would select an event/process identifier from


298

the Processes tree browser, and the relevant process flowchart would be displayed in the Process Design tab.

To apply your changes to the currently displayed flowchart, either select File > Save, or select another item in the tree browser and click Yes at the confirmation prompt that appears.

The four separate areas of the Visual Process Manager workspace are described in the section entitled The VPM Workspace Areas on page 299.

General Controls in the VPM Workspace

Various functions exist in the Visual Process Manager that allow you to control the panes and other elements that make up its workspace.

Show/Hide Controls

It is possible to show or hide any of the following elements in the VPM window:

• The Properties pane

• The Processes pane

• The Design Tools pane

• The toolbar and its buttons

• The status bar at the bottom of the window

To show or hide any of these, right-click anywhere in the toolbar area and make the appropriate selection from the menu displayed. These functions are also available in the View menu.

Resizing Controls

You can change the relative widths of two adjacent panes in the VPM window by dragging the dividing line between them to the exact position you want.

Docking/Floating Controls

If you wish to move the Processes, Properties or Design Tools pane to a different docked position within the workspace, or to a floating position outside the workspace, you can do so by dragging it by its title bar to that position.


299

The VPM Workspace AreasIn the Visual Process Manager window, there are six distinct areas of workspace below the toolbar, which are described in the subsections below.

The Processes Pane

This pane on the left contains a tree browser that allows you to initiate the creation of a process, to select an existing process for viewing and editing, and to delete a process. Process entities are created within appropriate folders in the tree browser.

All but one of the top-level folders in the tree browser represent each of the data dictionaries that you have on your system. The exception, called All Data Dictionaries, represents all data dictionaries. Creating a process in a specific data-dictionary folder is useful if your system supports multiple data dictionaries, where each is related to an entirely different set of operational and administrative procedures, and you need to have two or more independent processes directly triggered at different times by the same event. If you only require one process (or one set of sequential sub-processes) per event, you would create each process within the All Data Dictionaries folder.

Every top-level folder divides down into two sub-folders: User and System. You would create all of your processes in User folders. The System folders, on the other hand, are read-only and are reserved for processes created by Hornbill.


300

Once at least one process has been created in a User or System folder, further sub-levels will appear below that folder. The first of these would be a category named Application Events, the second would be one named Database Table Events and the third would be one named User Defined Events. Below Application Based Processes would be a sub-category named Call Action Events, while below Database Table Events would be sub-categories identifying the tables for which events have been selected.

At the lowest levels of the folder structure, you would find the identifiers of the processes created so far. These are of two types: directly event-driven or indirectly event-driven. A directly event-driven process will be triggered directly by the event after which it was named. An indirectly event-driven process (which is always a sub-process) will still, ultimately, be triggered by an event, but this event will be either a user-defined event, or the one that triggers the directly event-driven process from which the indirectly event-driven process is called. The two types of process are instantly distinguishable from each other by their different icons, as displayed immediately to the left of their respective identifiers.

Creating a New Process

To create a default process entity within the VPM tree, follow the procedure given here:

1. In the tree browser, highlight any level of the folder structure representing the data dictionary to which the process should apply, or (if it is to be applicable to all data dictionaries) any level of the All Data Dictionaries folder structure.

2. Select File > New Process, or right-click the chosen level and select New Process from the menu that pops up.


301

3. Ensure that the correct data-dictionary selection is shown in the top field of the dialogue box. Change the selection if necessary using the drop-down list control.

4. If the process is to be triggered (directly or indirectly) by an analyst-session event, first expand the System Events folder and then the Session Events folder. Then, if you are creating a directly event-driven process, select the required event, or, for a process that is to be driven by another process, select <Sub-Process>.

If the process is to be triggered (directly or indirectly) by a call-related event, first expand the Application Events folder and then the Call Action Events folder. Then, if you are creating a directly event-driven process, select the required event, or, for a process that is to be driven by another process, select <Sub-Process>.

If the process is to be triggered (directly or indirectly) by a table-related event, first expand the Database Table Events folder and then the folder named after the required table. Then, for a directly event-driven process, select the required event, or, for a process that is to be driven by another process, select <Sub-Process>.


302

Note that, in either of the above cases, there may be two versions of any given directly event-driven process to choose from. With the “present tense” version (for example, OnLogNewCall), the event will not complete until the triggered process has completed successfully. With the “past tense” version (for example, OnNewCallLogged), the event will complete regardless of the outcome of the process.

5. If the process is to be triggered by a user-defined event, select the “User defined process” option as the type of process to create.

6. At the bottom of the dialogue box, type in a suitable name for the new process and click OK. Notice that the relevant process identifier now appears in the appropriate part of the tree in the Visual Process Manager, automatically highlighted, with the process’ initial components displayed in the Process Design tab.

Selecting an Existing Process

To select a process for viewing, editing or management, just keep expanding the folders within the chosen hierarchy in the VPM tree until you can see the identifier of the process you want, and then highlight it. The components of the selected process are immediately displayed in the Process Design tab.

Deleting an Existing Process

To delete a process, first select it in the VPM tree, and then select Delete Process from either the File menu or the menu that pops up when you right-click the process. At the confirmation prompt that appears, click Yes.


303

The Process Design Tab

The Process Design tab is the main tab found in the large pane of the Visual Process Manager, and is always the one displayed by default whenever a procees is selected. Its function is to provide you with the space to build a flowchart representing a directly or indirectly event-driven process, or to view and edit an existing flowchart.

A flowchart will be made up of nodes and flow lines. Nodes are representations of the basic functional elements that make up a process, while flow lines depict the possible paths, between successive elements, along which the process can or will flow. A node, once inserted into a flowchart, will require you to specify or edit a number of attributes to precisely define the function it should represent, and to customise its text labelling as seen on the flowchart. The following node types are available:


304

• Flow Control. This indicates a certain kind of delimitation to the process flow, which could be a start, a stop or a divergence to another process.

• Expression. This represents a function that tests for a specific data-value condition using any of the standard SQL operators. The condition can be one of your own choosing or one predefined by Hornbill. The result of the test would be either Yes or No (or it could be one of some other pair of opposites), and the process would branch appropriately depending on that result.

• System Test. This represents a built-in Supportworks server function that tests for a specific Hornbill-defined condition. If necessary, you can modify the table and/or column whose data will be tested. The result of the test would be either Yes or No (or it could be one of any other pair of opposites), and the process would branch appropriately depending on that result.

• Switch. This represents a function that tests for one of several possible values of data in the specified table column. The column can be one of your own choosing or one predefined by Hornbill. The result of the test would be a match on one of the possible values, or it may default to a non-match, and the process would branch appropriately depending on that result.

• System Action. This represents a function that performs a specific action within the process, directed at the operating system, the mail system, a database, a Web server, or any similar entity. The outcome of an action can be success, failure or (where appropriate) no record being found, and the process would suitably branch depending on that outcome.

• Call Action. This represents a function that performs a specific call-related action within the process. There is one action available that will create a new call record using the parameter values you will have specified, while each of the remaining actions will modify an existing call record using the specified values of parameters appropriate to that action. The call parameter values can be either literals or variables presented in the usual Supportworks syntax. The outcome of an action can be success or failure, and the process would suitably branch depending on that outcome.

• Note. This does not represent any function, but simply allows you to add a textual annotation to any part of the flowchart. There are three colour variants of this node available: yellow, green and red. Clicking on the arrows at the top right-hand corner of the node will show or hide its contents. You can resize the node by dragging any of its borders.


305

A process script will be self-validating while you edit the flowchart that represents it. Every time you make a change to the flowchart, the script checks itself for any missing flows into nodes, and checks each node for missing flow-outs and the absence of mandatory parameter values. Each functional node inserted in a flowchart will be coloured red while there are validation errors associated with it. Such a node would turn green as soon as its validation is successful (except for the Start node, which will not turn green until the process is activated).

Note This kind of validation will only be able to point out the most basic shortcomings of your flowchart, as outlined above. It is not capable of detecting, for example, whether a node you have inserted is a valid one for the execution context concerned.

What You Can Do in the Process Design Tab

In the Process Design tab, you insert a node by right-clicking anywhere in the tab area and then making the required selection from the menu that pops up. The menu items for the individual nodes are grouped under the respective node types (see above). Once a node has appeared in the workspace, you can drag it to any position within that space.

You insert a flow line between two nodes by clicking the relevant flow-out control at the edge of the first node and dragging the mouse pointer to the flow-in control at the edge of the second node’s title bar. A flow-out control will exist for each possible result or outcome associated with a node. (However, on the Start node, there is only one flow-out control, situated at the edge of its title bar.) When you reposition a node that is attached to another node by a flow line, the line will suitably accommodate itself as you drag the node.

You select an individual node by clicking on it (or on a validation error relating to it), and you select a flow line by clicking anywhere along its length (including its source node’s flow-out control). You can select multiple nodes by holding down the Ctrl key while clicking on each node, or by clicking on an unselectable point and dragging the resulting “lassoo” over the nodes concerned. If you keep the Ctrl key held down as you select the final node of a multiple selection, you can drag the entire selection to another position as a single entity.


306

When you select a single node, its attributes and their current values are displayed in the Properties pane. You can then modify any of these values, as described in The Properties Pane below. Within the Process Design tab itself, you can perform the following actions on a selected node, or on multiple selected nodes:

• You can make copies of one or more nodes by means of the standard Copy/Paste functions. If necessary, you can copy (or cut) a node from one flowchart and paste it into another.

• With multiple nodes selected, you can align their horizontal or vertical edges by means of the Align Left/Right/Top/Bottom functions available on the Edit menu and on the toolbar.

• You can delete one or more nodes by using the Delete key or the Delete command available on the Edit menu and on the menu that pops up when you right-click the node. You delete a selected flow line in exactly the same way.

• You can update one or more nodes if, in any Supportworks release, those node types have been enhanced to support additional parameters. This means that you will not need to delete the node and recreate it from scratch, complete with its settings. Just right-click a node you wish to update and select Update Parameters From Template from the pop-up menu. Any extra parameters that the node now supports will then be available for you to set, and all previous parameter settings will be retained.

There is a set of commands available to reposition flow-out controls in nodes and flow-in controls in node title bars. These commands are Flip Node Position (side to side), Move Node Up and Move Node Down. You access any of these by right-clicking the control concerned and selecting the command from the menu that pops up. When you reposition a control in this way, any flow line that may be attached to it will move with it to the new position automatically.


307

The Input Parameters Tab

Each process triggered by a user-defined event needs to have parameters passed to it from that event in order for it to obtain precise details of the event and its operational context. These parameters are listed in the Input Parameters tab, which is the second possible view you can have of such a process.

This list of Input Parameters is effectively a declaration of all variables whose values are given to the process by the triggering event. Each variable can then be used by one or more of the nodes that make up the process, specified as part of an attribute under the Node Parameters category.

Normally, an input parameter would have a single value. However, it is possible for multiple values of any given parameter to be passed to a process. For example, when a number of calls are selected for updating, each of their call


308

references may be passed via the one parameter “callRef”. In such a case, the values would be held in an array, and an Array Iterator node would have to be included in the process to handle the required iterations.

Below the list of parameters on the tab are various controls you can use to manage them. The checkbox allows you to specify whether or not the process is to accept files from the event (which the process might then attach to a call or to an e-mail message). The other functions are described in the following subsections.

Adding an Input Parameter to the List

You would most likely be adding parameters when creating a new process. To add a parameter, follow the procedure given here:

1. Click the Add button. The following dialogue box is displayed:

2. Think of an appropriate name for the parameter and enter it in the Name field.


309

3. Ensure that the appropriate data type is selected. In most cases, this would be “xs:string”, but you can choose any available in the drop-down list. The list contains a sub-set of the built-in data types specified in the W3C Recommendation relating to the XML Schema language. For further details, please refer to Section 3, “Built-in datatypes” of the document you can find at http://www.w3.org/TR/xmlschema-2/.

4. In the Parameter Occurences area, make the required selection, depending on whether or not the parameter is to be mandatory (that is, “required” or “optional”) for the process concerned, and whether it is to have a single value or multiple values.

Note that the value in the Min Occurs field gives the minimum number of values to be input by an event for the parameter, and the value in the Max Occurs field gives the maximum number. For a single-value parameter, the maximum will always be 1, while, for a multi-value parameter, you can specify the maximum yourself (or set the field to zero for “unbounded”). For a required parameter, the minimum number of values will always be 1, while, for an optional parameter, the minimum will always be zero. If you have a non-standard requirement and wish to specify the minimum as well as the maximum yourself, you have to select “Custom settings”.

5. In the Description field, you can state the purpose or function of the parameter. For a non-standard parameter-passing scenario, you can also stipulate here the basis on which this rests.

6. Click OK.

The new parameter is added to the list.

Modifying the Properties of an Input Parameter

You can change the name, the data type, the occurrence scheme or the description of a parameter by highlighting its entry on the list and clicking the Properties button. A dialogue box similar to the one used when adding a new parameter is displayed, allowing you to modify any of the properties.


310

Deleting an Input Parameter

To delete a parameter, highlight its entry on the list and click the Delete button. The parameter is deleted immediately, without any confirmation being requested.

Reorganising a List of Input Parameters

You can rearrange the entries on a list of parameters by means of the Move Up and Move Down buttons. Just highlight an entry you wish to move to a different position and click the relevant button as many times as necessary. Note that you would do this purely for visual purposes, as the order of the entries on the list has no effect whatsoever on the actual execution of the process.


311

The Test/Invoke Tab

When designing a process triggered by a user-defined event, you may wish to test the process from within the Visual Process Manager, using sample parameter values supplied by yourself, rather than values obtained from the event. Furthermore, you may wish to keep a number of named tests for any given process, which you could then invoke on demand for demonstration purposes.

The Test/Invoke tab (which exists only for processes into which parameters can be input) provides facilities for setting up and performing such tests. These should make developing a process considerably easier and will allow the server-side functionality to be tested independently of the client-side application logic. To simply test a process, all you need to do is create a test containing the required parameter values and then invoke the process while still displaying the


312

tab. On seeing the results, you can easily change any of the values and immediately invoke the process again.

If you need to be able to demonstrate the process with different sets of parameter values at any subsequent time, you would have to save these as separate tests. Whenever you save a process, its associated tests are saved along with the script itself.

Creating a Test for a Process

You can create any number of tests for a given process. The procedure for creating one of these is as follows:

1. In the Test/Invoke tab, click New.

2. At the prompt you are presented with, enter a suitable name for the test and click OK. Notice that a number of fields have now become active (if there were no tests to begin with). The Input Parameters list is populated with the same set of parameters that are defined in the Input Parameters tab. The parameters shown in bold are the ones for which values are required.

3. In the Description field, give an account of what the intended test is supposed to demonstrate. You can omit this step if you just want to perform a quick test.

4. In the Input Parameters list, specify values for the parameters in the manner appropriate to the type of parameter concerned. For each single-value parameter, simply click in the Value field and enter a value. For each multi-value parameter (indicated by square brackets in the Type field and the hint “click to edit” in the Value field), click in the Value field to display the following dialogue box:


313

In this dialogue box, click New. Then enter a value and press Return. For the next value, click New again and repeat. Keep doing this until you have all the necessary values, and then click OK. Note that such multiple values are not displayed in the Input Parameters list – only their number is indicated.

For either type of parameter, you will be able to type in any value(s) you want (or even no value at all), as there is no input validation at this point. As always, the server will validate the input values when the process is invoked, so you could test error conditions in this way as well.

5. If you wish to keep this test, simply save the process in the usual way (File > Save).

You can now invoke the process using this test. (Note that the file-attachment facility is not yet supported.)

Tip Alternatively, if you wish to quickly create a variant of an existing test, simply select that test in the Test Name field of the Test/Invoke tab and click Copy. A copy of the test is created and is automatically selected. You can then edit specific values in the Input Parameters list as described above.

Testing a Process

When you wish to invoke a process using a given test, first ensure that the process is activated and that the required test is enabled in the Test Name field of the Test/Invoke tab. Then click the Invoke button. The process runs, just as though it had been triggered automatically by an event. The results, in terms of


314

success or failure, are shown in the Output tab of the Design Tools pane. You can easily check (in Supportworks or in the relevant database) that the prescribed actions have indeed been carried out.

The Output tab also displays the time taken to run the script. This includes the round-trip time of the network message as well as the server processing time.

Note If you have been editing parameter values, you will be asked, on clicking Invoke, whether you wish to save your changes. For the purposes of the test, it does not matter which answer you give, as the test will be based on whatever you currently see in the tab.

Managing Existing Tests

It is possible to modify and delete existing tests. To modify a test, select it in the Test Name field and make your changes using the same mechanisms as those employed when creating a test.

To delete a test, just select it and click Delete.

The Properties Pane

The Properties pane of the Visual Process Manager contains a context-sensitive list of the attributes of the flowcharted process being displayed. Whenever you open the Visual Process Manager, click a flowchart’s background, select a flow


315

line or select multiple nodes, the attributes displayed will be those relating to the process as a whole. As soon as you select an individual node on the Process Design tab, the contents of the Properties pane will change to show the attributes specific to that node.

Attributes are divided into the following categories:

• Process Properties

• Node Properties

• Node Parameters

• Flow Properties

You can view the attributes in either of two formats: categorised or uncategorised. In the categorised format, which is the initial default view, the attributes are grouped into categories. You can selectively collapse or expand these as in a tree browser. In the uncategorised format, the attributes are simply listed in an arbitrary order. To switch between formats, use the pair of buttons located immediately beneath the Properties title bar.

In both formats, the attributes are listed in two columns, the left-hand one containing their names, and the right-hand one containing their respective settings and values. To change a setting or value, you have to use the method appropriate to that particular attribute. The method may be single-line text entry, multi-line text entry, or multi-item selection via a specialist dialogue.

For an attribute value that is modifiable by text entry and is restricted to a single line, a text cursor appears in the value field when you click in it, allowing you to edit its contents. For an attribute value that is modifiable by text entry and can occupy multiple lines, clicking in the field would cause a browse button to appear on the right-hand side of the field, which, when clicked, would open a separate text-edit window. For a value that is modifiable by selection via a dialogue, clicking in the field would cause a browse button to appear on the right-hand side of the field, which, when clicked, would open an appropriate dialogue box that would allow you to make the required changes.

In the case of Node Parameters, all mandatory attribute names are shown in bold type.

The attribute categories are described in detail in the section entitled The Process-Attribute Categories In Detail on page 317.


316

The Design Tools Pane

This pane contains two tabs, called Design Rule Check Results and Output. The latter displays the results of any process test you may invoke, as described in the subsection entitled Testing a Process on page 313.

The Design Rule Check Results tab displays a list of any errors found by the represented script as it self-validates. Validation takes place on an overall-process basis and on a per-node basis. You can therefore consider an error as falling into either of the following categories:

• Process-validation errors

• Node-validation errors

The errors listed in the tab are context-sensitive, insofar as you will only see those that relate to the currently selected node or, if no single node is selected, to the process as a whole. Conversely, if you select an error, the node to which it relates is automatically selected on the flowchart.

Process-Validation Errors

This category consists of error messages that point out the absence of any process flow-ins into nodes. They are shown as being of the Reference Error type. Note that, although such an error would be found by validation of the process as a whole (since a node could have flow-ins from multiple nodes), it would nevertheless relate to a specific node, as stipulated in the error description.

Node-Validation Errors

This category consists of error messages that point out the absence of node parameter values in, or process flow-outs from, the node concerned. They are shown as being of the Parameter or Missing Link type, respectively.


317

The Process-Attribute Categories In DetailWhen you are designing or editing a process using the VPM, you will define the precise behaviour of each functional element in the process by specifying, in the Properties pane, appropriate values for its attributes. The particular set of attributes displayed in that pane at any given time will relate to whatever (if anything) is currently selected within the Process Design tab. You would typically see a mixture of editable and read-only attributes, divided into appropriate categories. All of the editable attributes that you can display, except one, relate to individual nodes, the exception being an activity-status flag operating at the process level.

Some node-level categories of attributes are common to a number of different node types (if not all of them), while others are specific to a type. Each of the attribute categories is described in its respective subsection below. Descriptions of individual attributes are given in the Visual Process Manager Reference Guide.

Process-Level Attribute Categories

There is only one attribute category that applies to the process as a whole, and this is described below.

Process Properties

This category contains just one attribute: an indication as to whether or not the process is active. This Active attribute is a status flag whose value will be 0 (meaning “inactive”) all the time you are building a flowchart. You will be able to change it to 1 (“active”) once all nodes (except Start) have turned green, denoting an error-free script. The VPME will attempt to run only activated processes. Therefore, activation would normally be the last thing you do when developing a process, and you can equally de-activate the process at any subsequent time.

Other indications of inactive status include the flowchart background being grey and the Start node being red.


318

Common Node-Level Attribute Categories

The attribute categories described here apply to all (or most) node types.

Node Properties

This category contains just one attribute: the name of the node as displayed in its title bar. You can change the node name by simply editing its text. For most nodes, you will probably want to change their names from the generic defaults to something more specific.

Flow Properties

With most functional node types, the values of the attributes under this category define the display names for the possible results and outcomes associated with the node concerned. The underlying names of these attributes indicate the logical state that would be returned by the script for each of these results and outcomes. In the majority of cases, every individual result/outcome is presented as a separate attribute. In other cases, the entire set of results/outcomes for the node is presented as the composite value of a single attribute, in which the individual values are managed via a multi-item selection dialogue.

Type-Specific Node-Level Attribute Categories

Any set of attributes displayed under the categories described here will be specific to the type of node selected.

Node Parameters

This category contains attributes, appropriate to the node concerned, whose values stipulate the exact behaviour of the represented function during script execution. Typically, these parameter values would define the operating factors for any required tests or system actions, or may provide data for any records that are to be manipulated by the process. Any input parameters passed to a node from a user-defined triggering event would be among the attributes found here.

For some node types, there will be certain node parameter values that are read-only. These would reflect specific hard-coded functions provided by Supportworks.

Functional Scripting

319


If you are adept at JavaScript or PHP programming, or are prepared to find your way around XML tags, you can alter or enhance certain aspects of Supportworks functionality, or create totally new functionality, wherever in the system such functionality is performed via scripts.

In this chapter, you are presented with the detailed information you will need to access the scripts concerned, and with the functions you can use to help you achieve the results you require or the coding you can enter to achieve a specific result.

Programming a Show Me Item “Script” ActionOne of the ways of defining the action to be associated with a Show Me menu item on a Supportworks form is by means of the item’s Script attribute. Having selected the Script action for the Show Me item concerned, you can enter the necessary JavaScript code in the Script field relating to it (as described in “Script” Action on page 68).

The JavaScript supported by the system is JavaScript 1.5 from Netscape, which complies with the ECMA-262 standard. However, the object model used is not related to the W3C standard for Web browsers. Instead, the system defines an application-specific object model that is more suited to the requirements of Supportworks itself.

Within the JavaScript code, you can use a number of different functions that Hornbill have created in accordance with the object model. Those of the Supportworks-provided functions that are suitable for use in the Script field are all methods (as defined by JavaScript terminology). These methods are documented in the reference subsection below. Before that, however, there is a subsection describing the conventions employed.


320

Conventions Used in the Method Reference

The conventions described here are used in the JavaScript Method Reference subsection below.

The syntax for each method shows the method’s name and those of its parameters, as well as the format in which you should enter the parameters. The prefix (followed by a space) in front of the method’s name indicates the method’s type, and the shortened version of such a prefix (without a space) in front of a parameter’s name indicates the type of that parameter. The possible prefixes and their meanings are shown in the following table:

A method’s syntax can also include option indicators, presented in the form opt[]. When a parameter is shown enclosed within such an indicator, this would mean that the parameter is optional.

JavaScript Method Reference

The JavaScript methods available for use in the Script field include the following:

OpenForm()

You can use this method to open a standard form without setting any initial or actual value for the relevant table’s primary key.

Method Prefix

Parameter Prefix

Meaning

str s String

int i Integer

num n Numeric (non-integer)

date d Date

bool b Boolean (true/false)


321

Syntax

bool OpenForm(strFormName, opt[strArgs], opt[bModal]);

Parameters

Returns

Impact and Compatibility

Example Usage

// Open the tbcustomer form, and pass it a variableapp.OpenForm(“TbCustomer”,”keysearch=freds”,true);

OpenFormForAdd()

You can use this method to open a standard form in “Add New Record” mode, and allows you to set an initial value for the relevant table’s primary key.

strFormName This is the name of the form to open. To specify a form in a data dictionary other than the current one, simply prefix the form name with the name of the data dictionary followed by a period. Thus, you would have: <data-dictionary name>.<form name>

strArgs This is a URL-style argument list of variables to pass into the form.

bModal Set this parameter to true if you want the form to be created with a modal window, or false to open the form with a frame window.

True If the form was successfully opened

False If the form was not found

On server Impact depends on the form. Certain elements of the form may contain database items.

With native client Compatible

With Analyst Portal

Not compatible


322

Syntax

bool OpenFormForAdd(strFormName, opt[strInitialKeyValue], opt[strArgs], opt[bModal]);

Parameters

Returns


Example Usage

// Open the Add New form for customer kermitf


strInitialKeyValue

This is the initial value of the primary key of the table defined as the Main Details Table for the form concerned. Note that it applies to tables in which the primary key is not an auto-incremented integer (for example, userdb).



True If the form was opened


On server No impact, unless elements on form interact with the database (for example, an SQL pick-list)


With Analyst Portal

Not compatible


323

app.OpenFormForAdd(“mydatadict.TbCustomer”,”kermitf”,”site=ChezLouie”,true);

OpenFormForEdit()

You can use this method to open a standard form in “Edit Record” mode, allowing you to set the required value for the relevant table’s primary key.

Syntax

bool OpenFormForEdit(strFormName, strKeyValue, opt[strArgs], opt[bModal]);

Parameters

Returns



strKeyValue This is the value of the primary key of the table defined as the Main Details Table for the form concerned.



True If the form was opened


On server Connects to the database and retrieves the record to be edited, as well as any other data for populating the form



324

Example Usage

// Open the Customer Properties form for customer kermitfapp.OpenFormForEdit(“mydatadict.TbCustomer”,”kermitf”,”site=ChezLouie”,true);

HttpGet()

This method is used to get the contents of a file into a string by means of the HTTP protocol and its GET command. It can be used to read a Web page or to run a server-side PHP script to perform an action on the server. The contents of the URL output that the Web server sends back will be returned in a string.

Syntax

str HttpGet(strUrl, opt[bAppendSessionInfo]);

Parameters

Returns


With Analyst Portal

Not compatible

strUrl This specifies the fully qualified URL to get.

bAppendSessionInfo This defines whether the client should or should not append Supportworks session information to the end of the URL request. It defaults to true.

String The contents of the URL output returned by the HTTP server

On server No impact, except on the HTTP server


With Analyst Portal

Compatible


325

Example Usage

// Show the text of the Hornbill home pagevar strPage = HttpGet(“http://www.hornbill.com”, false);{ MessageBox(strPage);}

MessageBeep()

This method plays a waveform sound. The system identifies the actual waveform sound to play by its entry in the Windows registry.

Syntax

bool MessageBeep(opt[nSoundType]);

Parameters

The parameter nSoundType specifies the type of sound to make and can be any one of the following values:

Note that all the values except the first are environment constants having the numerical equivalents shown. In the interests of code readability, you are advised to use the constant values rather than their numerical equivalents.

ValueNumerical Equivalent

Sound

-1 Simple beep. If the sound card is not available, the sound is generated using the speaker.

MB_ICONASTERISK 64 Windows Asterisk

MB_ICONEXCLAMATION 48 Windows Exclamation

MB_ICONHAND 16 Windows Critical Stop

MB_ICONQUESTION 32 Windows Question

MB_OK 0 Windows Default Beep


326

Returns


Example Usage

MessageBeep(MB_ICONEXCLAMATION);

MessageBox()

This method creates and displays a prompt-style dialogue box, and will respond to the actuation of its controls. The dialogue box will contain a message, and optionally a combination of a predefined icon and a predefined set of buttons.

Syntax

int MessageBox(strMessage, opt[nOptionButtons | nIconType | nDefaultButton]);

Parameters

The parameter strMessage specifies the text message to display in the dialogue box.

The parameter nOptionButtons specifies the mix of buttons to be available in the dialogue box, and can be any one of the following values:

True If the function succeeds

False If the function fails

On server No impact


With Analyst Portal

Not compatible


Buttons

MB_OK 0 OK only. This is the default.


327

Note that most of the values are environment constants having the numerical equivalents shown. In the interests of code readability, you are advised to use the constant values, rather than their numerical equivalents, whenever possible.

The parameter nIconType specifies the icon to display in the dialogue box, and can be any one of the following values:

Note that all these values are environment constants having the numerical equivalents shown. As before, you are advised to use the constant values rather than their numerical equivalents.

MB_OKCANCEL 1 OK and Cancel.

2 Abort, Retry and Ignore.

MB_YESNOCANCEL 3 Yes, No, and Cancel.

MB_YESNO 4 Yes and No.

MB_RETRYCANCEL 5 Retry and Cancel.

6 Cancel, Try Again and Continue.


Icon

MB_ICONINFORMATION 64 A lower-case letter “i” in a circle. This is the default.

MB_ICONEXCLAMATION 48 An exclamation mark.

MB_ICONQUESTION 32 A question mark.

MB_ICONSTOP 16 A stop sign.


Buttons


328

The parameter nDefaultButton specifies the button selected by default when the dialogue box opens, and can be any one of the following values:

These values, too, are environment constants. Note that only the first three are valid (where appropriate), as there is currently no configuration with four buttons.

Returns


Value Default Button

MB_DEFBUTTON1 The first button (counting from the left) is the default button. This is the default if no button is specified.

MB_DEFBUTTON2 The second button is the default button.

MB_DEFBUTTON3 The third button is the default button.

MB_DEFBUTTON4 The fourth button is the default button.

1 If the OK button was selected.

2 If the Cancel button was selected.

3 If the Abort button was selected.

4 If the Retry button was selected.

5 If the Ignore button was selected.

6 If the Yes button was selected.

7 If the No button was selected.

10 If the Try Again button was selected.

11 If the Continue button was selected.

0 If the function failed.

On server No impact


329

Example Usage

// Display the text “Hello, World” and an OK and Cancel buttonMessageBox("Hello, World", MB_OKCANCEL);OR: MessageBox("Hello, World", 1);

// Display the text “Hello, World” with an exclamation-mark icon and an OK and Cancel buttonMessageBox("Hello, World", MB_OKCANCEL|MB_ICONEXCLAMATION);OR: MessageBox("Hello, World", 1|48);

// Display the text “Hello, World” with an exclamation-mark icon and an OK and Cancel button, making the first button the defaultMessageBox("Hello, World", MB_OKCANCEL | MB_ICONEXCLAMATION | MB_DEFBUTTON1);

OpenCallDetailsView()

This method is used to open the Call Details form for the specified call.

Syntax

bool OpenCallDetailsView(nCallRef);

Parameters

Returns


With Analyst Portal Not compatible

nCallRef The call reference number of the call to open, or a comma-separated list of call references to open multiple calls

True If the form was opened successfully

False If the form was not opened successfully


330


Example Usage

// Open the Call Details form for call number F0001234OpenCallDetailsView(1234);

OpenDatabaseSearchView()

This method is used to switch the main client window into the Database Searches view, and optionally perform an SQL search.

Syntax

bool OpenDatabaseSearchView( opt[strSQL] );

Parameters

Returns


On server Connects to the database and retrieves information for the specified call


With Analyst Portal

Not compatible

strSQL Optional SQL statement to issue after switching to the Database Searches view

True If the Database Searches view opened successfully

False If the Database Searches view did not open successfully

On server Connects to the database and issues the SELECT statement



331

Example Usage

// Search for, and display, all open and deferred callsOpenDatabaseSearchView(“SELECT * FROM opencall WHERE status < 16”);

OpenEmbeddedURL()

This method is used to switch the main window into the Supportworks Today view, and optionally display an alternative URL in that view.

Syntax

bool OpenEmbeddedURL( opt[strURL] );

Parameters

Returns


With Analyst Portal

Not compatible

strURL This specifies the URL you wish to display. If you do not pass this value or you pass an empty string, the Supportworks Today page defined in the current data dictionary will be displayed. If you do specify a URL, that page will be displayed instead.If you need to display an alternative URL from the Supportworks server, you can use the following macros in the URL string instead of setting the absolute name or IP address of the server:&[app.server]&[app.httpport]For example, the URL could be:http://&[app.server]:&[app.httpport]/index.htm

True If the action has been completed successfully

False If the action has not been completed successfully

On server Sends a request to the designated HTTP server


332

Example Usage

// Display the server home pageOpenEmbeddedURL("http://&[app.server]:&[app.httpport]/");

// Display a specific page from the serverOpenEmbeddedURL("http://&[app.server]:&[app.httpport]/sw/clisupp/swtoday/index.php");

OpenVCM()

This method is used to run the Visual Configuration Manager for a specified Configuration Item on a Supportworks system (such as ITSM) that has a CMDB.

Syntax

bool OpenVCM(strConfigItemID, opt[strConfigFile], opt[nShowType], opt[nShowLevel], opt[nObjInGroup], opt[nZoom]);

Parameters



strConfigItemID This is the identifier for the required Configuration Item

strConfigFile This is the name of the configuration file used by the VCM. If no value is passed, the default is vcm_itsm_config.xml

nShowType This specifies whether the Configuration Item’s parental relationships or its child relationships are to be displayed in the VCM window. The possible values are 1 (for parental) or 0 (for child). The default is 0.

nShowLevel This specifies the maximum number of Configuration Item levels that will be displayed in the VCM window. The default is 5.

nObjInGroup This specifies the minimum number of Configuration Items of the same type that will be displayed as a group icon in the VCM window. The default is 20.


333

Returns


Example Usage

// Run the VCM for the Dell 365 and its childrenOpenVCM(“DELL365”, “vcm_config.xml”, 0, 3, 8, 50);

RunHIB()

This method is used to run an instance of the Hornbill Information Browser (HIB), which allows users to view detailed asset information collected by an application such as Assetworks.

Syntax

bool RunHIB(strURL, opt[strVar], opt[strValue]);

Parameters

nZoom This specifies the initial zoom level of the VCM display. The permissible range of levels is 50 to 400. The default is 100.

True If the VCM started successfully

False If the VCM did not start successfully

On server No impact



strURL This is the fully qualified URL where the HIB configuration file is located, as given in the client-access configuration procedure to be found in the relevant Supportworks Integration Connectors document

strVar This is the name of the variable to pass to the HIB, representing any asset whose details are to be shown


334

Returns


Example Usage

// Invoke the HIB on a LANDesk-audited computer.RunHIB(app.webroot + “/itg/landesk/viewer/”,”compname”, “devws09”);

RunProgram()

This method is used to run a program as if it were started on the Windows command line. Generally, it is better to use ShellExecute() for this, but RunProgram() is provided because it is easier to use.

Syntax

bool RunProgram(strCommand, opt[nShowOption]);

Parameters

The parameter strCommand specifies the command line to run.

strValue This is the value to which the variable strVar is to be set, identifying the specific asset

True If the HIB started successfully

False If the HIB did not start successfully

On server The HIB will connect to the relevant database and retrieve information for the specified asset


With Analyst Portal

Not compatible


335

The parameter nShowOption specifies how the program window is to be shown, and can be any one of the following values:

Note that all these values are environment constants having the numerical equivalents shown. As always, you are advised to use the constant values rather than their numerical equivalents.

Returns



Window Behaviour

SW_HIDE 0 The system hides the window and activates another window.

SW_SHOWNORMAL 1 The system activates and displays the window. This is the default value used if the nShowOption parameter is not specified.

SW_MAXIMIZE 3 The system activates and maximises the window.

SW_MINIMIZE 6 The system minimises the window and activates the next top-level window in the Z-order.

SW_FORCEMINIMIZE 11 On Windows 2000 or XP, the system minimises the window, even if the thread that owns the window is hung. This flag should only be used when minimising windows from a different thread.



On server No impact



336

Example Usage

// Runs a new instance of notepad.exe to edit AUTOEXEC.BATRunProgram(“notepad.exe c:\\autoexec.bat”);

// Runs a new instance of notepad.exe, hiddenRunProgram(“notepad.exe c:\\autoexec.bat”, 0);

ShellExecute()

This method can be used to perform various operations on files and folders. These operations are exactly the same as the commands you can select from an item’s context menu within Windows Explorer. The precise behaviour of the actions performed are determined by your Windows configuration and are subject to the system’s file associations. ShellExecute() provides the most convenient method of opening a document, since the system takes care of identifying the correct application to invoke for the type of file concerned.

Syntax

bool ShellExecute(strFile, opt[strArgs], opt[strVerb], opt[strStartFolder], opt[nShowCommand]);

Parameters


strFile This is the fully qualified pathname of the file or folder to operate on.

strArgs If the file is an executable program, this specifies any program arguments that need to be passed to it. If the parameter is omitted, the default value will be an empty string.


337

Returns


Example Usage

// Runs a new instance of notepad.exe

strVerb This is a keyword that specifies the action to be performed. The set of keywords available in a given instance depends on the particular file or folder. Generally, a keyword will be available if the corresponding command exists in the target’s context menu.The possible keywords you can use are as follows:“edit” This launches an editor and opens for editing the document specified by strFile.“explore” This opens the folder specified by strFile in a new Explorer window.“find” This initiates a search starting from the folder specified by strFile.“open” This opens or runs the item specified by strFile. The item can be an executable file, a document file, or a folder. If the parameter is omitted, this will be the default.“print” This prints the document file specified by strFile. If strFile is not a document file, the function will fail.

strStartFolder This specifies the folder in which to start the application. If the parameter is omitted, the default value will be an empty string.

nShowCommand This is currently unavailable.



On server No impact


With Analyst Portal

Not compatible


338

ShellExecute(“notepad.exe”);

// Runs a new instance of notepad.exe to edit AUTOEXEC.BATShellExecute(“notepad.exe”, “C:\\AUTOEXEC.BAT”);

// Opens the specified Word document for editingShellExecute(“c:\\My Documents\\Letter1.doc”);

// Opens the specified HTML document in the default Web browserShellExecute(“c:\\Help Files\\Help1.htm”);

// Prints the specified documentShellExecute(“c:\\My Documents\\Letter1.doc”, “”, “print”);

SqlExecute()

This method is used to issue an arbitrary SQL statement to the cache or main database.

Syntax

int SqlExecute(strDatabase, strSQL);

Parameters

Returns

strDatabase This specifies the database to which to issue the SQL statement. It can currently be one of two values:“syscache” This issues the statement to the system cache database (sw_systemdb).“swdata” This issues the statement to the main database using the ODBC connection.

strSQL This is any valid SQL statement. If you issue a statement (such as SELECT) that returns results, these will be discarded.

n If the function was successful, this will be the number of rows affected by the SQL statement

-1 If there was an error


339


Example Usage

// Reset the telephone number of every customer to blank and display an error message if this failsif (SqlExecute("swdata", “UPDATE userdb SET telext = ‘’”) < 0){ MessageBox(“Error”);}

TAPIDial()

This method is used to dial a number through the TAPI interface.

Syntax

int TAPIDial(strNumber);

Parameters

Returns


On server No impact



strNumber This is the number you want the system to dial.



On server No impact




340

Example Usage

// Dial Hornbill’s main switchboardTAPIDial(“02085828282”);

Customising Dashboard ChartsSupportworks Dashboard charts incorporate selectable, named SQL queries that provide the function of collecting the necessary call-related data from the database. If you are familiar with SQL, you can modify existing queries or, with experience of PHP as well, even create new ones for charts to use, and you can also delete existing queries.

All SQL queries used by Dashboard charts are defined in a PHP script file on the server called dash_queries.php. Within this file, you will find the blocks of code, each relating to a specific Dashboard query, that you will be able to modify, create or delete.

The default location of dash_queries.php and all other editable Dashboard files is: C:\Program Files\Hornbill\Supportworks Server\html\clisupp\dashboard.

Modifying an Existing Dashboard Query

The procedure given in this subsection applies only to minor modifications that would not require any changes in the logic needed to process the results of the query. They would consist of slight adjustments to the SQL and perhaps an appropriate edit of the query name. Equally, a minor modification may just involve changing the interval between one issue of the query and the next.

To Modify the SQL and Display Name for a Query

To modify a query’s SQL statement and display name, follow the instructions given here:

1. Open the dash_queries.php file in a suitable text editor.

2. Search for the name of the query you wish to edit, which would be the same as, or similar to, the name as given in the Query drop-down list in the Chart Properties dialogue box. You should find it on a comment line beginning with //.


341

3. Within the case section immediately beneath the query name, find the assignment for $query. Its string value will consist of the SQL SELECT statement you will need to edit.

4. Edit the statement in accordance with your requirements.

5. Save your changes and close the file.

6. If you wish to modify the query name to reflect your change in the SQL, open the querylist.xml file in a suitable text editor. It should be in the same folder as dash_queries.php.

7. Find the entry relating to the changed query by identifying its current name.

8. Suitably edit the name.


To Modify the Query Interval

You can change the interval between successive issues of a given database query by editing a number contained in the dash_queries.php script. You will find this number, which is 500 by default, in the line of code immediately below the case line in the block of code relating to the query. The relevant line is as follows:

if ((!file_exists($filename)) || (filemtime($filename) < time()-500))

The number specifies the required interval in seconds. Note that different queries can have separately defined intervals.

To Create a New Dashboard Query

Creation of a new Dashboard query firstly requires the addition of relevant code, in the dash_queries.php file, that will include not only a suitable SQL query, but also the specific logic needed to process the results of that query and then place the data into the query’s results file. This results file, whose name should always be of the form dash_*.xml, would be read by the Dashboard client after the client has requested a query.

In addition, you will have to add new code to the file (querylist.xml) in which every query’s name is defined and its results file identified.


342

To create a new query, follow the instructions given here:

1. Open the querylist.xml file in a suitable text editor.

2. Add an entry representing the new query to the contents of this file in the same format as each of the existing entries. In other words, you would add the following line:

<Query name=“The Name of Your New Query” type=“simple” url=“dash_queries.php?id=dash_*.xml”/>

where the query name within quotes would be any suitable name of your choice, and * would be the portion of the results file’s name that uniquely identifies the file. For this filename portion, you are recommended to use a shorthand version of the query name (without any spaces).


4. Open the dash_queries.php file in the text editor. Notice that the blocks of code that handle the respective queries are located within the switch ($filename){} construct. Each block begins with a // comment reflecting the query’s name.

5. Decide on an appropriate point (perhaps between two existing blocks) at which to include your own block of code relating to the new query, and proceed to design the required process and write the code. As part of the design task, you should examine some of the existing blocks to see how the query processing within those has been handled, and how much of that code you can re-use. Some of the code (or at least its format) will be mandatory in all cases. When working out how the code assembles a results file, you may wish to look at the contents of some of the existing ones so as to gain an appreciation of the required format. While examining blocks in the PHP code, you need to be aware of the following:

• A statement of the form indicated below is always needed for directing the Dashboard client’s query request to the relevant block of code:case “dash_*.xml”:

where the filename within quotes relates to the query’s results file.

• The condition below is always required, as it determines whether or not a query needs to be issued (and/or a results file needs to be created):


343

if ((!file_exists($filename)) || (filemtime($filename) < time()-T))

where T is the minimum period, in seconds, that must elapse before the query can be re-issued to refresh the results file.

• You must use the following statements to provide the prescribed header and footer, respectively, for the results file:$xml = ‘<graphdata expires=“0”>’;$xml .= ‘</graphdata>’;

• The following statements are necessary for writing the assembled query data to the results file, and for creating the file in the first place:$file = fopen ($filename, “w”);fwrite ($file, $xml);fclose ($file);

• The remaining code must build the query by means of an appropriate SELECT statement, must perform appropriate tests on the returned SQL data, and must assemble a string ($xml), from the returned data, in the format required by the results file. If the data to be charted is to be fetched from the database, the above is indeed what the remaining code should perform, which means that you could then use the same code structure as in the existing blocks. However, it is possible to write code that will fetch data from places other than a database, in which case the collected data would have to be assembled into $xml in a different way (but of course still conforming to the format expected by the results file).


To Delete an Existing Dashboard Query

To delete a query, follow the instructions given here:

1. Open the querylist.xml file in a suitable text editor.

2. Find the entry representing the query you wish to delete. Each entry will be in the following form:

<Query name=“The Name of the Query” type=“simple” url=“dash_queries.php?id=dash_*.xml”/>

3. Highlight the entry and delete it.


344


For the sake of tidiness, you could also delete the block of code relating to that query in the dash_queries.php file, but this is not necessary from a functional point of view.

Customising Ticker Bar FeedsThe Supportworks Ticker Bar can source its feeds from either the Supportworks database or the BBC website. Feeds from the former are taken using SQL queries. If you are familiar with SQL, you can modify existing queries and, with experience of PHP as well, even add new queries to the current set. You can also delete existing queries and modify the feed output appearing on the Ticker Bar.

With website feeds, however, customisation can be more of a challenge. Changing the download interval or the characteristics of the displayed Ticker Bar separators is easy enough, and requires virtually no familiarity with PHP. However, if you wish to source news-feeds from other websites, you will not only need to be adept at PHP programming, but will also need to be prepared to contact those websites to find out the format of their feed files.

Yet another kind of customisation you may wish to undertake entails modifying certain default aspects of the Ticker Bar configuration. As such changes are independent of the type of feed, and are easy to implement, you are given instructions, below, on these first. The subsequent subsections respectively cover customisation specific to the two differently sourced feed types.

In each of the subsections, references will be made to various editable Ticker Bar files. All of these files are located in the same folder, which, by default, will be: C:\Program Files\Hornbill\Supportworks Server\html\clisupp\ticker.

Modifying Ticker Bar Configuration Defaults

You can customise certain Ticker Bar configuration defaults, which are held in the <newsfeeds> section of the file ticonfig.xml. Firstly, if you want the Ticker Bar configuration dialogue box to show only a sub-set of the available news-feed categories, you can remove the unwanted categories by simply deleting the relevant newsfeed lines. You can always reinstate these at a subsequent time as necessary.


345

Secondly, if you wish to change the name of a news-feed category, as displayed in the dialogue box, you can edit the text string assigned to its name variable.

Finally, if you want a news-feed category to be initially disabled on start-up of the Ticker Bar, you can change the logical value assigned to its default variable to 0 (zero). Conversely, you can change the value to 1 if you want the category to be enabled on start-up.

Customising Ticker Bar Queries for Supportworks Feeds

All SQL queries used by the Ticker Bar to obtain data from the Supportworks database are defined in a PHP script file on the server called kpiinfo.php. Within this file, you can modify, create and delete blocks of code relating to the feed queries (perhaps including the supporting logic and the displayed output), as well as set the query interval.

To Modify the Query Interval for Supportworks Feeds

You can change the interval between successive queries of the Supportworks database by editing a number contained in the kpiinfo.php script. You will find this number, which is 500 by default, right at the top of the script, in the following line of code:

if ((!file_exists(“kpi.xml”)) || (filemtime(“kpi.xml”) < time()-500)){

The number specifies the required interval in seconds.

To Modify an Existing Query for a Supportworks Feed

The procedure given in this subsection applies only to minor modifications that would not require any changes in the logic needed to process the results of the query. The modifications would consist of slight adjustments to the SQL and perhaps an appropriate edit of the displayed Ticker Bar text for the feed item concerned.

To edit a feed query, follow the instructions given here:

1. Open the kpiinfo.php file in a suitable text editor.

2. Look at each of the comment lines beginning with // until you find one containing the name of the query you wish to edit.


346

3. On the line immediately beneath the query name, you will see an assignment for $query. Its string value will consist of the SQL SELECT statement you will need to edit.

4. Edit the statement in accordance with your requirements.

5. If you wish to modify the Ticker Bar text to reflect your change in the SQL, find (in the same block of code) the line containing the concatenated assignment for the string variable $xml. You will see, within that assignment, a number of strings defining the feed item as it should be displayed on the Ticker Bar, including its text.

6. Suitably edit the text.


To Create a New Query for a Supportworks Feed

Creation of a new feed query requires the addition of relevant code, in the kpiinfo.php file, that will include not only a suitable SQL query, but also the specific logic needed to process the results of that query and then place the data into the results file. This results file, whose name is kpi.xml, would be read by the Ticker Bar client at intervals given by the configured poll rate.

To create a new query, follow the instructions given here:

1. Open the kpiinfo.php file in a suitable text editor. Notice that each block of code that handles a particular query begins with a // comment made up of the query’s name.

2. Decide on an appropriate point within the script at which to include your own block of code relating to the new query, and proceed to design the required process and write the code. As part of the design task, you should examine some of the existing blocks to see how the query processing within those has been handled, and to see what code you can re-use. You will notice that much of the code (or at least its format) is repeated in all blocks.

Basically, the code in each block must build the query by means of an appropriate SELECT statement, must perform appropriate tests on the returned SQL data, and must assemble a string ($xml), from the returned data, in the format required by the results file. If you look at the contents of the results


347

file, you will be able to clearly see the required format, and thus gain an appreciation of how the code assembles that file.


To Delete an Existing Query for a Supportworks Feed

To delete a feed query, follow the instructions given here:

1. Open the kpiinfo.php file in a suitable text editor.

2. Look at each of the comment lines beginning with // until you find one containing the name of the query you wish to delete.

3. Carefully highlight the entire block of code relating to that query and delete it.


To Modify the Characteristics of Separators for Supportworks Feed Items

Each separator icon you can see between successive feed items on the Ticker Bar has characteristics that you can change. These are, basically, its style and its colour. As far as the Supportworks feeds are concerned, each of these icons is associated with the feed item that it immediately precedes, its characteristics being defined in the corresponding query’s $xml assignment line in kpiinfo.php. The characteristics are also defined globally in the file ticonfig.xml, but the query-specific definitions override the global one. This means that, if you wish to modify the characteristics of the separators as a whole, you will have to edit the instance of that line for every query.

There are two options open to you in this task. You can either edit each of the query-specific definitions, or edit the global definition and then simply delete the query-specific definitions.

A separator icon’s colour is defined by the value of the variable SepColor, and its style by the value of SepStyle. You can specify any one of four styles – of


348

which three are predefined and one is custom. The numerical values used to specify the respective styles are as follows:

If you specify SepStyle=“4”, you will need to add an additional value assignment SepBitmap=“pathname” either before or after it (but still on the same line of code), where pathname would be the path and name of the image file that is to be displayed as the separator.

You will probably want to mirror the change of separator characteristics with those relating to the Web news-feeds, as described in To Modify the Characteristics of Separators for Web-Sourced Feed Items on page 349.

Customising Code for Web-Sourced Ticker Bar News-Feeds

The PHP code designed to take news-feed data from the BBC website and then make it available to the Ticker Bar client is held in the file bbcnewsinfo.php. The data is made available in “story” files such as story1.xml, each of which relates to a particular category of news-feed. The story files would be read by the Ticker Bar client at intervals given by the configured poll rate. Although the PHP code will download items of all available BBC news-feed categories, only those categories that are listed in the file ticonfig.xml will be accessible by the Ticker Bar client. Each category entry within this file will contain a numerical pointer to that category’s story file (for example, “1” specifying story1.xml).

The following subsections indicate various customisations, involving one or more of the above files, that you can undertake.

Value Style

1 Circle

2 Square

3 Triangle

4 Custom bitmap file


349

To Modify the Download Interval for Web-Sourced News-Feeds

In terms of possible practical requirements, customisation of the processes contained in bbcnewsinfo.php is limited to changing the interval between successive data downloads from the BBC site. This interval is defined by the value of the string variable $period, whose assignment is located right at the top of the script.

To Modify the Characteristics of Separators for Web-Sourced Feed Items

You can change the style and colour of the icons separating successive Web-sourced news-feed items on the Ticker Bar display in a similar way to the separators relating to Supportworks-sourced feed items. The main difference is that, in this case, the SepColor and SepStyle values are defined in the bbcnewsinfo.php file, and these definitions are to be found in the line of code that contains the first concatenated value assignment for the string variable $xml_out[$y-1]. Note that this value assignment, which builds each feed item for a story file, appears just once (as it is looped). This means that you would need to edit the SepColor and SepStyle values (or delete their definitions) only in that one place.

See To Modify the Characteristics of Separators for Supportworks Feed Items on page 347 for details of the style options available.

Adding News-Feeds from Other Websites

It is actually possible to obtain news-feeds from websites other than the BBC one. To do this, you would have to create a suitably named equivalent of the bbcnewsinfo.php file, with code that is appropriate to the format of the feed data supplied by the site concerned. If you are sufficiently proficient in PHP to be able to follow the code contained in bbcnewsinfo.php, you should have no difficulty in producing the necessary code to process differently formatted source data and save it in a series of story files. It is important to ensure that your code will build/update story files in the exact format expected by the Ticker Bar client. Careful examination of existing story files will allow you to see clearly what format is required.

Once you have created the required PHP file, you will need to update ticonfig.xml with details of the extra news-feed categories that the Ticker Bar


350

should now be able to display. In other words, for every such new category, you must add a line of the following form to the <newsfeeds> section:

<newsfeed name=“Category” file=“name.php?nf=N” default=“1” />

where:

Category would be the display name of the news-feed category;name.php would be the name of the PHP file you created;N would be an integer identifying the story file that is associated with this news-feed category.

As always, you can assign a value of 0 to default if you want this category to be initially disabled in the Ticker Bar client configuration.

Customising the Help MenuThe commands in the upper sections of the client’s Help menu (above Tooltips) invoke the display of on-line help documents, the relevant Release Notes and certain Web pages. The names of these commands, the locations/names of the respective documents or pages to which they point, and the roles of the users who should be allowed to see them are all customisable. It is also possible to add extra commands that point to other documents you may wish to provide (or other websites of interest), and to add and remove menu-item separator lines.

All of these customisable elements of the Help menu are stored in a file called customhelpmenu.xml, whose default installation path is C:\Program Files \Hornbill \Supportworks Server \html \clisupp\. The default contents of this file are as follows:

<customHelpMenu>

<item name="User Guide" url="&[app.webroot]/helpdesk_docs/user/" privLevel="0"/>

<item name="System Administration Guide" url="&[app.webroot]/helpdesk_docs/administrator/" privLevel="2"/>

<item name="System Customisation Guide" url="&[app.webroot]/helpdesk_docs/sys_customisation/" privLevel="2"/>

<item type="separator" />

<item name="Client Installation Guide" url="&[app.webroot]/helpdesk_docs/client_installation/" privLevel="2"/>


351

<item name="Server Installation Guide" url="&[app.webroot]/helpdesk_docs/server_installation/" privLevel="2"/>

<item name="Server Configuration Guide" url="&[app.webroot]/helpdesk_docs/server_configuration/" privLevel="2"/>


<item name="Supportworks Release Notes" url="&[app.webroot]/relnotes.htm" privLevel="0"/>

<item name="Core Services Release Notes" url="http://&[app.server]/relnotes.htm" privLevel="2"/>


<item name="Hornbill Support Forums" url="http://forums.hornbill.com/" privLevel="0"/>

<item name="Hornbill Web Site" url="http://www.hornbill.com/" privLevel="0"/>

</customHelpMenu>

You can see that each item defined under the main <customHelpMenu> tag corresponds to one of the Help menu commands. In each case, the name= attribute gives the command name as it appears on the menu, the url= attribute defines the path, as a URL, to the document or Web page concerned, and the privLevel= attribute specifies the user roles necessary for access to that document or page. The possible values for privLevel= are as follows:

0 = Support Analyst, Group Manager or System Administrator1 = Support Analyst, Group Manager or System Administrator2 = Group Manager or System Administrator3 = System Administrator

(The default value is 0 if this attribute is omitted.)

The order in which the commands are listed on the menu is determined by the order in which the items are arranged in the XML file. Any instance of the code <item type="separator" /> signifies a separator line generated at that point among the command items.

Using a text editor, you can add menu items of your own anywhere within the <customHelpMenu> section, provided that you conform to the tagging syntax used for the default items. Of course, any document or website you refer to will have to exist at the relevant URL. You can remove any menu command or any instance of a separator line by deleting its line of code.


352

Customising New Call ConfirmationsOn logging a call, the analyst sees one of five possible variants of the New Call Confirmation pop-up message displayed, depending on how they logged the call. The default contents of these messages are essentially hard-coded in the system. However, there is an XML file available that equally defines the text of each variant, and this text is customisable. Once the XML file has been made known to the system, each text definition within it would replace the hard-coded equivalent. If you have multiple data dictionaries, you can create a number of XML files for defining the different message sets required. You can use any of the following variables in your custom text:

The text in any such XML file is defined in accordance with a prescribed structure, using suitable mark-up tags. The XML file, called CallConfirm.xml, that is supplied with Supportworks, and whose default installation path is

Variable Meaning

&[Customer] Customer’s full name

&[Callref] Call reference

&[LogDate] Date/time of the call (normally shown for deferred calls)

&[SlaRespTime] Date/time, in the server’s zone, by which a response is expected

&[SlaFixTime] Date/time, in the server’s zone, by which a fix is expected

&[AnalystRespTime] Date/time, in the analyst’s zone, by which a response is expected

&[AnalystFixTime] Date/time, in the analyst’s zone, by which a fix is expected

&[SlaTimezoneName] Server’s time zone

&[AnalystTimeZone] Analyst’s time zone


353

C:\Program Files \Hornbill \Supportworks Server \html \clisupp\, has the following contents:

<logCallConfirmMessages>

<issuesLoggedResClosedMsg><![CDATA[Issue logged and resolved/closed for &[Customer]<br>The call reference number is &[Callref]]]> </issuesLoggedResClosedMsg>

<logConfirm1Msg><![CDATA[The call for <b>&[Customer]</b> has been deferred until &[LogDate]<br>The call reference is <b>&[Callref]</b>]]> </logConfirm1Msg>

<logConfirm3Msg><![CDATA[The call logged for <b>&[Customer]</b> has been deferred until &[LogDate]<br>The call reference is <b>&[Callref]</b><br><br>No SLA was specified for this call]]> </logConfirm3Msg>

<logConfirm4Msg><![CDATA[Call logged for <b>&[Customer]</b><br>The new call reference is <b>&[Callref]</b><br><br>No SLA was started for this call]]> </logConfirm4Msg>

<logNewMsg><![CDATA[Call logged for <b>&[Customer]</b><br>The new call reference is <b>&[Callref]</b><br><br>

<b><u>SLA Local Time (&[SlaTimezoneName])</u></b><br>We expect to respond by &[SlaRespTime]<br>We expect to fix this problem by &[SlaFixTime]<br><br>

<b><u>Operator Local Time (&[AnalystTimeZone])</b></u><br>We expect to respond by &[AnalystRespTime]<br>We expect to fix this problem by &[AnalystFixTime]]]> </logNewMsg>

</logCallConfirmMessages>

This script, as it stands, emulates the hard-coded set of message variants more or less exactly. If you need to create multiple XML files for different data dictionaries, you can use this script as the template in each case. To modify the


354

script in any of the XML files to suit your display requirements, you simply use a text editor.

Each section of the script beginning with an emboldened tag corresponds to one of the five message variants, as follows:

The data in each section is encapsulated by a tagged construct of the form <![CDATA[displayed data]]>. You can modify anything within displayed data, but you must leave the surrounding structure intact.

You can give an XML file any name you wish. To make the file known to the system for a given data dictionary and thereby enable its use in place of the hard code, you must specify its URL in a global parameter, as described in Enabling Customisation of New Call Confirmations on page 233.

Customising Analyst Portal NotificationsThe Analyst Portal in PHP mode uses its own mechanism for generating and e-mailing call-progression notifications to customers, and it can also send similar messages to support analysts. Within the Analyst Portal PHP code, you

Section Tag New Call Confirmation Variant

<issuesLoggedResClosedMsg> Call logged and resolved/closed at the same time

<logConfirm1Msg> Call logging deferred to a specified date/time, with an SLA specified

<logConfirm3Msg> Call logging deferred to a specified date/time, with no SLA specified

<logConfirm4Msg> Call simply logged, with no SLA specified

<logNewMsg> Call simply logged, with an SLA specified


355

can specify values for each of the following string variables, allowing you to control the indicated aspects of these notifications:

You will find the PHP code containing these variables in the file called calldiaryupdate.addfields.php, whose default installation path is C:\Program Files \Hornbill \Supportworks Server \html \analystportal \php \xmlhttp\. To edit the values of the variables, you can use a simple text editor.

Variable Meaning

$system_mailbox The source mailbox to use for the outbound message

$customer_template The name of the customer mail template to use, as defined under Update Call Templates for the mailbox concerned in the Manage E-Mail Templates window

$analyst_template The name of the analyst mail template to use, as defined under Update Call Templates for the mailbox concerned in the Manage E-Mail Templates window

$default_from The default “From” address to use in the outbound message’s header

$default_replyto The default reply address to use in the outbound message’s header, if different to the “From” address


356

Default Customisable Table Specifications

357

Appendix A Default Customisable Table Specifications

Detailed specifications of the main customisable database tables used by Supportworks are given in this Appendix. As these specifications define the initial default structure of the tables on a pre-customised installation, you will also need to refer to the Solution Specification given to you by our consultants to obtain a complete and accurate picture of your own system.

Note You should exercise a great deal of caution if you wish to further modify any of the database tables described below. In particular, you should avoid changing any columns that are only used internally by the system. Tables that are entirely reserved for the system are not shown here at all (even though they are theoretically “customisable”), and you should certainly avoid interfering with those altogether.

Charge Centre TableThe Charge Centre table (costcent) contains one record, structured as follows, for each charge centre set up in the Supportworks system:

Column Name Type Size Description

Costcenter Alphanum 44 Unique identifier for the charge centre

Department Alphanum 64 Charge centre description

Rate Numeric 4 Chargeable rate. By default, a rate of £35 or $35, say, would be stored in this field as 3500 (pence or cents)

Priority Alphanum 30 SLA associated with the charge centre


358

Asset TableThe Asset table (equipmnt), if used, contains one record, structured as follows, for each item of hardware or software set up in a typical Supportworks system:


Equipid Alphanum 20 Unique identifier for the item

Manufactur Alphanum 40 Manufacturer of the item (see Manufacturer table)

Model Alphanum 40 Model of the item

Serialno Alphanum 20 Serial number of the item

Generic Alphanum 6 Generic code (see Generic Type table)

Owner Alphanum 20 Owner of the item, which would be a customer ID by default, or it could be a site name or charge centre ID

Owner_type Numeric 4 Type of owner (0 = user, 1 = department, 2 = storage)

Costcenter Alphanum 44 Charge centre associated with the item

Location Alphanum 40 Location of the item (for example, Comms Room)

Site Alphanum 70 Site where the item is located (see the Site Table)

Notes Long alphanum

4K-64K

Free-form text notes for the item

Wrnty_expr Alphanum 20 Date the warranty expires

Warentyprd Numeric 4 Warranty period in months

Supplier Alphanum 20 Supplier of the item (see Supplier table)

Maintcmpny Alphanum 40 Reserved – currently not used


359

Contract Alphanum 10 Reserved – currently not used

Asset_no Alphanum 20 Asset number of the item

Purch_by Alphanum 20 Reserved – currently not used

Purch_date Alphanum 20 Order date

Prch_order Alphanum 10 Purchase order number

Dliverdate Alphanum 20 Delivery date

Initcapita Numeric 4 Capital expenditure (cost of item)

Depret_typ Numeric 4 Reserved – currently not used

Num_prds Numeric 4 Reserved – currently not used

Nbv_offset Numeric 4 Reserved – currently not used

Deprtnotes Long alphanum

4K-64K

Reserved – currently not used

Priority Alphanum 30 SLA associated with the item

Attrib1 Alphanum 255 Attribute 1. May contain a command to generate pop-up message or sound when call logged for the item






360

Generic Type TableGeneric type codes, held in this table (generic), are used to categorise assets in a typical Supportworks system. There is one record, structured as follows, for each generic type set up in Supportworks:






Inst_date Alphanum 20 Installation date


Code Alphanum 6 Unique code for the generic type

Descriptn Alphanum 40 Description of the generic type

Picture Numeric 4 A numeric value that represents the icon associated with the generic type


361

Manufacturer TableThis table (manufact) holds a list of manufacturers and their details. There is one record, structured as follows, for each manufacturer set up in Supportworks:

Open/Closed Call TableThis table (opencall) holds all calls that have ever been logged, whether open or closed. There is one record, structured as follows, for every call logged on the Supportworks system:


Comp_name Alphanum 40 Manufacturer name

Address1 Alphanum 40 Address line 1



Postcode Alphanum 20 Postal/zip code

Country Alphanum 30 Country

Telephone Alphanum 20 Telephone number

Altphone Alphanum 20 Alternate telephone number

Contact Alphanum 40 Contact name

Fax Alphanum 20 Fax number


Callref Numeric 4 Unique reference number for the call

Status Numeric 4 Current status of the call

Priority Alphanum 30 Current SLA for the call


362

Suppgroup Alphanum 160 Current owner’s group

Owner Alphanum 64 Current owner

Cust_id Alphanum 20 ID of the customer for whom the call was logged

Cust_name Alphanum 61 Name of the customer for whom the call was logged

Loggedby Alphanum 64 ID of the support analyst who logged the call

Logdate Alphanum 20 Date/time the call was “officially” logged

Assigndate Alphanum 20 Date/time the call was first assigned

Closedby Alphanum 64 ID of the support analyst who resolved the call

Closedate Alphanum 20 Date/time the call was resolved, or at which the call is due to come off hold

Equipmnt Alphanum 20 Identifier of the asset (if any) associated with the call

Slaresp Numeric 4 Date/time the call was responded to

Slafix Numeric 4 Date/time the call was fixed

Rate Numeric 4 Chargeable rate at the time of the call

Costcenter Alphanum 44 Charge centre associated with the call

Probcode Alphanum 16 Problem profile code

Fixcode Alphanum 16 Resolution profile code

Respondby Alphanum 20 Date/time to respond by

Fixby Alphanum 20 Date/time to resolve by

Resp_time Numeric 4 Response time achieved

Fix_time Numeric 4 Resolution time achieved


363

Withinresp Numeric 4 Response time met? (0 = No, 1 = Yes)

Withinfix Numeric 4 Resolution time met? (0 = No, 1 = Yes)

Totaltime Numeric 4 Total time (in seconds) spent on this problem

Assigndatx Numeric 4 Epoch version of the first call-assignment date/time

Logdatex Numeric 4 Epoch version of the “official” log date/time

Closedatex Numeric 4 Epoch version of the resolve date/time

Respondbyx Numeric 4 Epoch version of the respond-by date/time

Fixbyx Numeric 4 Epoch version of the resolve-by date/time

Completeby Alphanum 20 ID of the support analyst who closed the call

Compltdate Alphanum 20 Date/time the call was closed

Compltdatx Numeric 4 Epoch version of the close date/time

Postcode Alphanum 20 Postal/zip code of the customer associated with the call

Site Alphanum 70 Name of the site associated with the call

Contact_id Alphanum 30 ID of the customer contact (if any) for whom the call was logged

Contact Alphanum 64 Name of the customer contact (if any) for whom the call was logged

Component_id Alphanum 30 Identifier of the component (if any) associated with the call


364

Component Alphanum 64 Name of the component (if any) associated with the call

Callclass Alphanum 40 Class of the call

Extdetails Alphanum 64 Name of the table (if any) containing extended details for the call

Issueref Alphanum 20 Reference number of the issue (if any) associated with the call

Prob_text Alphanum 255 Original problem details

Last_text Alphanum 255 Resolution details

C_rating Numeric 4 Not used

A_rating Numeric 4 Not used

Origin Alphanum 64 Source of the call action (e.g. e-mail)

Stateflags Numeric 4 Not used

Assigncount Numeric 4 Number of times the call has been assigned

Commitdatex Numeric 4 Epoch version of actual log date/time

Commitdate Alphanum 20 Date/time call was actually logged

Lastaction Numeric 4 Not used

Lastactdatex Numeric 4 Not used

Lastactdate Alphanum 20 Not used

Lastactby Alphanum 20 Not used

Nextaction Numeric 4 Not used

Nextactdatex Numeric 4 Not used

Nextactdate Alphanum 20 Not used

Workitemprogress Alphanum 10 Number of work items completed out of the total in the call


365

Site TableThe site table (site) has one record, structured as follows, for every site set up in Supportworks:

Escalation Numeric 4 State of the escalation indicator, being a number from 65536 to 393222. A given state would be the sum of a colour value and a level. A level would be in the range 1 to 6, while a colour value may be any of the following:65536 (Grey)131072 (Green)196608 (Yellow)262144 (Blue)327680 (Magenta)393216 (Red)

Tpcontract Alphanum 128 Third-party SLA contract number


Site_name Alphanum 70 Name of the site

Comp_name Alphanum 45 Company name

Address Alphanum 100 Postal address of the site


Country Alphanum 40 Country

Timezone Alphanum 20 Time zone (not currently used)

Telephone Alphanum 20 Telephone number of the switchboard

Fax Alphanum 64 Main fax number


366

Supplier TableThe supplier table (supplier) has one record, structured as follows, for every supplier set up in Supportworks:

Support Analyst TableIn this table (swanalysts), resident in the database sw_systemdb, each support analyst set up in Supportworks will have a record, structured as follows:


Company_id Alphanum 40 Supplier name





Telephone Alphanum 20 Telephone number

Altphone Alphanum 20 Alternate telephone number

Contact Alphanum 40 Contact name

Fax Alphanum 20 Fax number


AnalystID Alphanum 64 ID of support analyst or third-party supplier

Name Alphanum 64 Full name of support analyst or third-party supplier

Password Alphanum 128 Login password of support analyst

SupportGroup Alphanum 64 Support group to which analyst belongs


367

ContactA Alphanum 32 Analyst’s extension number, or third-party supplier’s telephone number

ContactB Alphanum 32 Analyst’s telephone number or third-party supplier’s fax number

ContactC Alphanum 32 Analyst’s mobile telephone number

ContactD Alphanum 32 Analyst’s home telephone number

ContactE Alphanum 32 Analyst’s e-mail address

ContactF Alphanum 32 Analyst’s pager number

ContactG Alphanum 32 Definable

ContactH Alphanum 32 Definable

PriveligeLevel Numeric 4 Analyst’s role (administrator, manager or analyst)

RightsA Numeric 4 Analyst’s call-management rights A

RightsB Numeric 4 Analyst’s call-management rights B

RightsC Numeric 4 Analyst’s system-management rights

RightsD Numeric 4 Analyst’s desktop-workspace rights

RightsE Numeric 4 Analyst’s global SQL-database rights

RightsF Numeric 4 Analyst’s data-dictionary rights

RightsG Numeric 4 Reserved – currently not used

RightsH Numeric 4 Reserved – currently not used

UserDefaults Numeric 4 Analyst’s default options

MaxBackdatePeriod

Numeric 4 Maximum backdate period allowed in analyst’s call actions, or null if backdating call actions not allowed

TimeZone Alphanum 128 Analyst’s time zone


368

Support Group TableThis table (swgroups), resident in the database sw_systemdb, contains one record, structured as follows, for each support group set up in the Supportworks system:

DataDictionary Alphanum 128 Name of data dictionary assigned to analyst

AvailableStatus Numeric 4 Analyst’s current availability status (available, at lunch, training, on holiday, in a meeting, or out of office)

AvailableStatusMessage

Alphanum 128 Text of analyst’s absence message

Notes Alphanum 255 Free-form text notes relating to third-party supplier

Tpcontract Alphanum 128 Third-party SLA contract number


Id Alphanum 32 Unique identifier for the support group

Name Alphanum 128 Name of the support group

Attrib1 Alphanum 64 Definable






Notes Alphanum 255 Free-form text notes for the customer


369

Issue TableThis table (swissues), where used, holds the details of all current Known Issues, Hot Issues and user-defined issues. There is one record, structured as follows, for each issue created in Supportworks:


Issueref Alphanum 20 Reference number of the issue

Status Numeric 4 Current status of the issue

Starttime Alphanum 20 Date/time the issue was created

Starttimex Numeric 4 Epoch version of the create date/time

Resolveby Alphanum 20 Date/time the issue must be resolved by

Resolvebyx Numeric 4 Epoch version of the resolve-by date/time

Resolveed Alphanum 20 Date/time the issue was resolved

Resolveedx Numeric 4 Epoch version of the resolve date/time

Affectedusers Numeric 4 Number of calls associated with the issue

Issuetype Numeric 4 Issue type (Hot, Known or specific user-defined)

Description Long alphanum

4K-64K

Text description of issue

Mastercallref Numeric 4 Call reference of the issue’s master call

Owner Alphanum 20 Not used

Suppgroup Alphanum 20 Not used

Flags Numeric 4 Flag indicating whether the call is public or not


370

Call Diary TableThis table (updatedb) is linked with the open/closed call table. One call diary record will be created for a call when first logged and, subsequently, one record will be created for each call update. Each record is structured as follows:

Dd Alphanum 64 Name of the data dictionary in use on the client when the issue was created


Udid Numeric 4 Unique identifier for the diary record

Callref Numeric 4 Reference number of call the diary record is associated with

Updatetime Alphanum 20 Date/time the diary record was made

Updatetimex Numeric 4 Epoch version of the date/time the diary record was made

Timespent Numeric 4 Amount of time (in minutes) spent on the log or update action

Repid Alphanum 44 “Aaid as Aid” (see below)

Aaid Alphanum 64 ID of analyst who actually carried out the action

Aid Alphanum 64 ID of analyst context in which the action was carried out

Groupid Alphanum 20 Group ID of analyst who carried out the action

Udtype Numeric 4 Type of action: public or private

Udindex Numeric 4 Incremental update reference number (internal only)


371

Customer TableIn this table (userdb), each customer set up in the Supportworks system will have a record, structured as follows:

Updatetxt Long alphanum

4K-64K

Free-form problem-description, update-description and fix-description text for this action

Udsource Alphanum 64 Action source (e.g. telephone, e-mail)

Udcode Alphanum 64 Action type (e.g. called, e-mailed)


Firstname Alphanum 20 Customer’s first name

Surname Alphanum 40 Customer’s surname

Keysearch Alphanum 20 Customer’s unique identifier

Location Alphanum 20 Location of the customer within a site (for example, Accounts)

Site Alphanum 70 Site where the customer is located


Telext Alphanum 20 Telephone number of/for the customer. If CTI is enabled on the client, this may match their expected CLI, or it may match the unique number you have given them for calls to the helpdesk (which would be submitted as the Called ID, or Station ID, in all such calls), depending on what is specified in the settings of a given client

Costcenter Alphanum 44 Charge centre associated with the customer


372

User1 Alphanum 50 Definable



User4 Alphanum 200 Definable. May contain a command to generate pop-up message or sound when call logged for the customer

Notes Long alphanum

4K-64K

Free-form text notes for the customer

Priority Alphanum 30 SLA associated with the customer

Email Alphanum 100 Customer’s e-mail address

Password Alphanum 64 Customer’s SelfService password

Webflag Numeric 4 Permissions flags for the customer’s SelfService and e-mail access (as set in Control tab of Customer Properties)

Faxtel Alphanum 20 Customer’s fax number

Mobiletel Alphanum 20 Customer’s mobile telephone number

Hometel Alphanum 20 Customer’s home telephone number

Pagertel Alphanum 64 Customer’s pager number

Attrib1 Alphanum 254 Attribute 1. May contain a command to generate pop-up message or sound when call logged for the customer




373

Problem Profile TableThis table (probcode) contains records that hold the basic definitions of all problem-profile elements at every hierarchical level. Each record is structured as follows:









Code Alphanum 8 Four-character profile code identifying a specific element of a created profile


374

Other tables holding problem-profile data are pcdesc and pcinfo.

Resolution Profile TableThis table (fixcode) contains records that hold the basic definitions of all resolution-profile elements at every hierarchical level. Each record is structured in exactly the same way as those in the Problem Profile table (see above).

Other tables holding resolution-profile data are rcdesc and rcinfo.

Descx Alphanum 32 User-friendly name for this profile element

Parentcode Alphanum 8 Four-character profile code identifying the profile element immediately above this one in the hierarchy. If the element is already at the highest level, the code will be ROOT

Levelx Numeric 4 Number representing the level at which the element is positioned within the profile, where 0 is the highest level, 1 is the next level down, and so on

Flags Numeric 4 Used internally by the system


Standard Context Variables

375

Appendix B Standard Context Variables

The following table lists all the standard context variables you can use wherever SQL filters (WHERE clauses) are specifiable in Supportworks. Some typical places include Global Parameters, system reports and custom database searches.

Variable Name Meaning

analystid Who the analyst is logged in as.

groupid The logged-in analyst’s support group.

session.analystid The analyst context that the client session is switched to.

session.groupid The group context that the client session is switched to.

session.currentdd The data dictionary that the client session is switched to.

startoftoday 00:00:00 hours today.

endoftoday 23:59:59 hours today.

startofweek 00:00:00 hours on the last Sunday before today.

endofweek 23:59:59 hours on the first Saturday after today.

startofmonth 00:00:00 hours on the first day of the current month.

endofmonth 23:59:59 hours on the last day of the current month.

startofquarter 00:00:00 hours on the first day of the current quarter. A quarter can start in January, April, July or October.

endofquarter 23:59:59 hours on the last day of the current quarter. A quarter can end in March, June, September or December.

startofyear 00:00:00 hours on the first day of the current year.

endofyear 23:59:59 hours on the last day of the current year.

Standard Context Variables

376

In Global Parameter and custom database search filters, you specify a variable in the standard syntax &[variablename]. In report filters, you specify it within a function, using the syntax _sw_time(variablename). For a report, only the time-related variables (such as startoftoday) can be used.

Note that the time-related variables always yield their contents in UTC epoch time, which means that you must use the epoch versions of date/time columns when making comparisons in an SQL expression. For example, you might specify the value of a filter named “Calls Logged by Me this Week” as follows:

loggedby = ‘&[session.analystid]’ AND logdatex > &[startofweek] AND logdatex < &[endofweek]

startofyesterday 00:00:00 hours yesterday

endoftoyesterday 23:59:59 hours yesterday

startoflastweek 00:00:00 hours on last week’s Sunday.

endoflastweek 23:59:59 hours on last week’s Saturday.

startoflastmonth 00:00:00 hours on the first day of last month.

endoflastmonth 23:59:59 hours on the last day of last month.

startoflastquarter 00:00:00 hours on the first day of the last quarter. A quarter can start in January, April, July or October.

endoflastquarter 23:59:59 hours on the last day of the last quarter. A quarter can end in March, June, September or December.

startoflastyear 00:00:00 hours on the first day of last year.

endoflastyear 23:59:59 hours on the last day of last year.

contacta to contacth

One of the first eight attributes of the customer or contact (held in columns attrib1 to attrib8 of the userdb table) whose call is being tested by the filter.

Variable Name Meaning

Shortcut-Bar Icons and their Identifiers

377

Appendix C Shortcut-Bar Icons and their Identifiers

This Appendix lists all available images, held in Supportworks, that can be used as shortcut-bar icons in the main client window. Against each icon in the table below, you are given the icon’s index number, which is the means by which the system identifies it. Also given are the client views corresponding to those icons that are displayed on the shortcut bar by default on a new installation.

You would need to reference the index numbers if you wished to change a view’s shortcut icon within either Global Parameters or Database Entity Views.

Shortcut Icon No. Associated View (by default)

0

1 Helpdesk Mail

2 Personal Mail

3 Helpdesk


378

4 KnowledgeBase

5 Management Information and Reporting

6 Database Searches

7 CustomersContacts

8 AssetsConfiguration Items

9 Supportworks Today

10 Search For Calls



379

11 Companies

12 Calendar

13

14

15 My Library

16

17



380

18


Global Parameter Summary

381

Appendix D Global Parameter Summary

If you would like to see at a glance what Global Parameters are available within Supportworks and to see a summary of their respective functions, you can consult the table below. Each summary of parameters relating to a given folder begins with a reference to the section of this Guide that describes these in full.

Global Parameter Folder Parameter Reference and Summary

Active Folder Pages See Defining Active Pages on page 183Parameter values pinpoint PHP scripts that generate client’s active pages.

Assignment Tree See Filtering Support-Team Trees Used for Selection on page 245AnalystFilter value filters support analysts displayed in selection trees and drop-down lists.GroupFilter value filters support groups displayed in selection trees and drop-down lists.TpmFilter value filters third-party suppliers displayed in selection trees.TpmContractFilter value filters third-party SLA contracts displayed in selection trees.


382

Call Action Forms See Mapping Forms to Call Actions on page 229UpdateCallForm value identifies form invoked on call update.HoldCallForm value identifies form invoked on call hold.ResolveCloseCallForm value identifies form invoked on resolution or closure of call already logged. (See also LogResolveCloseCallForm below.)CancelCallForm value identifies form invoked on call cancellation.IssueForm value identifies form invoked on issue creation or update.AcceptCallForm value identifies form invoked on call acceptance.CompleteWorkItemForm value identifies form invoked on work item completion.LogResolveCloseCallForm value identifies form embedded in Resolve/Close Details tab of Log Call form.

Views See Customising the Workspace Views on page 185StartupView value determines initial view to be displayed.

Views<any view>

See relevant sectionIconTitle value determines view’s shortcut-icon label.Icon value determines view’s shortcut-icon image.Visible value determines visibility or otherwise of shortcut item and hence view.



383

Views<Web-page view>

See Web-Style Views (“Supportworks Today”) on page 187Type value is “webpage”.ViewTitle value currently unused.Url value gives URL of PHP script generating view’s Web page.

Views<helpdesk view>

See Changing Generic Characteristics of the View on page 190Type value is “helpdesk”.ViewTitle value determines pre-hyphen part of view’s title.CallStatusGraphFilter value filters calls to be included in Active Call Status bar chart.


Team View

See Filtering the Helpdesk-View Support-Team Tree on page 243AnalystFilter value filters support analysts displayed in the main team tree.GroupFilter value filters support groups displayed in the main team tree.TpmFilter value filters third-party suppliers displayed in the main team tree.TpmContractFilter value filters third-party SLA contracts displayed in the main team tree.



384


Top ¦ Bottom<calls view>

See Changing the Characteristics of a Call List on page 191AvailableColumns value determines opencall table columns to be shown in tab.Filter value filters calls listed in tab.TabName value determines tab-label text when in Supportworks Helpdesk context.TabNameCalls value determines tab-label text when in another analyst’s context. Run-time variables are supported.TabNameGroup value determines tab-label text when in another group’s context. Run-time variables are supported.TabNameMyCalls value determines tab-label text when in own context. Run-time variables are supported.TabNameMyGroup value determines tab-label text when in own group’s context. Run-time variables are supported.TabNameShowFilter value determines whether or not current filter name is to appear in title.Type value is “CallList”.Visible value determines visibility or otherwise of tab.ScriptName value gives name of JavaScript file to associate with tab.ApplyContextFilter value determines whether or not calls listed in tab will be filtered according to context.ApplyContextTabNames value determines whether tab-label text will reflect current context, or will consist of TabName value.FilterLabel value determines text of filter-control label.



385


Top ¦ Bottom<calls view>

Filters

See Creating User-Selectable Filters (Optional) on page 194<filter display name> value filters calls displayed on list.


Top<tasks view>

See Changing the Characteristics of a Work-Item List on page 195VisibleColumns value determines calltasks and opencall table columns to be shown in tab.Filter value filters work items listed in tab.TabName value determines tab-label text when in Supportworks Helpdesk context.TabNameTasks value determines tab-label text when in another analyst’s context. Run-time variables are supported.TabNameGroup value determines tab-label text when in another group’s context. Run-time variables are supported.TabNameMyTasks value determines tab-label text when in own context. Run-time variables are supported.TabNameMyGroup value determines tab-label text when in own group’s context. Run-time variables are supported.Type value is “TaskList”.Visible value determines visibility or otherwise of tab.


Bottom<issues view>

See Changing the Characteristics of an Issue List on page 197TabName value determines tab-label text.Type value is “IssuesList”.Visible value determines visibility or otherwise of tab.Filter value filters issues listed in tab.



386


Bottom<watched-calls view>

See Changing the Characteristics of the Watched Calls List on page 198TabName value determines tab-label text.Type value is “WatchedCallsList”.Visible value determines visibility or otherwise of tab.AvailableColumns value determines opencall table columns to be shown in tab.

Views<Calendar-type view>

See The Calendar View on page 200Type value is “calendar”.ViewTitle value determines pre-hyphen part of view’s title.

ViewsE-Mail

See The E-Mail View on page 201Type value is “mail”.InitialMailbox value determines the initial mailbox to be displayed.

ViewsDatabase Entity Views

See Common Aspects of Database Entity Views on page 203Type value is “autodbev”.Note that IconTitle and Icon are not valid here, as equivalents are defined in Database Entity Views section of data dictionary outside of Global Parameters.



387

ViewsSearch For Calls View

See Call-Search Views on page 208SearchColumns value determines search fields to be shown in view.ResultColumns value determines result columns to be shown in view.TableName value indicates table to be searched.DefSearchOptions value specifies “match” option to be selected by default in search pane: 0 for all, or 1 for any.DefMaxSearchResults value specifies result-entry limit to be set by default in search pane.Type value is “callsearch”.ViewTitle value determines view’s title.Filter value filters calls to be searched for.

ViewsDatabase Search View

See The Database Searches View on page 210Type value is “dbsearch”.ViewTitle value determines view’s title.Filter value filters records to be searched for.

ViewsMy Library View

See The My Library View on page 212Type value is “library”.ViewTitle value determines pre-hyphen part of view’s title.

ViewsKnowledgeBase View

See The KnowledgeBase View on page 213Type value is “knowledgebase”.ViewTitle value determines view’s title.

ViewsReport View

See Report Views on page 214Type value is “reports”.ViewTitle value determines view’s title.Filter value filters reports shown in view, in respect of data-dictionary allocations.



388

Global Call Settings See Filtering Call Commands on page 217GetCallByReferenceFilter value filters calls viewable via View Call Details by Reference command.FindCallsFilter value filters calls viewable via Find Calls Logged/Resolved/Closed commands.See Enabling Customisation of New Call Confirmations on page 233LogCallConfirmMsg value is a URL pointing to an XML file that contains customisable replacements for hard-coded New Call Confirmation messages.

Group Properties See Renaming Support-Group Attributes on page 249Attribute1 to Attribute6 values determine attribute labels in support-group properties.

Call Profile Editor See Renaming Call Profile Attributes on page 222Attribute1 to Attribute6 values determine attribute labels in Call Profile Manager.

Configurable Text See Renaming Call Profile Categories (Optional) on page 222ProblemProfile value specifies the term to be substituted for “Problem Profiles”.ResolutionProfile value specifies the term to be substituted for “Resolution Profiles”.



389

DD Filters See Filtering Problem Profiles (Optional) on page 223ProfileCodeFilter value filters problem profiles in relevant tree browsers.FindCallsFilter value filters problem profiles selectable in “Find calls logged/resolved/closed” dialogues.See Filtering Call Selection for Issues on page 239AddCallToIssueFilter value filters selection of calls available to add to issues.

Close Call Form See Filtering Resolution Profiles on page 226ProfileCodeFilter value filters resolution profiles in Choose Profile tree browser during call closure.ResolveProfileFilter value filters resolution profiles in Choose Profile tree browser during call resolution.

Skills Dialog See Filtering the Display of Skills in a Tree Browser on page 251Filter value filters skill entries displayed in tree browsers used in skill management.

Assign Call Dialog See Filtering the Selection of Skills on Call Assignment on page 252Filter value filters selection of skills during call assignment.



390

Mail Move Folders See Automatically Filing Received E-Mail on page 255LogCallMailFolder value identifies mailbox folder into which received messages are to be transferred on logging calls from them.HoldCallMailFolder value identifies mailbox folder into which received messages are to be transferred on placing calls on hold from them.UpdateCallMailFolder value identifies mailbox folder into which received messages are to be transferred on updating calls from them.CloseCallMailFolder value identifies mailbox folder into which received messages are to be transferred on resolving or closing calls from them.

Email Audit Trail See Automatically Generating an E-Mail Audit Trail on page 257StoreEmailAuditTrail value determines whether or not automatic e-mail audit-trail generation is enabled.IncludeAttachmentsInMessage value determines whether or not attachments will be kept within messages (as well as being copied directly to calls) when messages themselves are added to calls.MoveToDeletedItems value determines whether or not messages from which call actions have been initiated will be deleted (unless otherwise moved to a mailbox folder).

Email Integration See Defining E-Mail Integration Functionality on page 258EmailTargetField value indicates table column into which sender’s e-mail address is to be copied from message header.RemoteQuery value identifies Remote Query to be used on outbound mail-merge.DontResolveCustomers value determines whether or not attempts will be made to resolve customers from received messages.



391

Server Connection Dialog See Filtering the Display of Client/Server Connections (Optional) on page 261Filter value filters display of client connections to server.

Third Party SLAs See Defining Third Party SLA Functionality (Optional) on page 263Enable value determines whether or not third-party SLAs are enabled.DisplayHoldOption value determines whether or not Place Call On Hold form is displayed on assignment of call to third-party SLA.SecondsBeforeFixTimeToComeOffHold value specifies latest period of time, before expiry of target third-party-SLA fix time, that call must come off hold.

Issue View See Defining an Alternative Customer Browser to Use with Issues on page 240PickCustomerForm value identifies SQL tree browser form to be used on invoking Log Call and Add function in View/Edit Issue dialogue.

Disable Functionality See Controlling Global Call Escalation (Optional) on page 235DisableEscalateToAll value determines whether or not calls can be escalated to all support analysts.DisableCompleteWorkItemByAny value determines whether or not work items can be completed by any support analyst.

Form Control Options See Enabling Remote Form Access (Optional) on page 232EnableRemoteFormAccess value determines whether or not forms from different data dictionaries can be used.



392

Application Settings The following parameters apply to the Supportworks CS template only. See the relevant part of the section on managing operational settings in the Customer Support Template Administrator Guide.autoid_companies value determines whether company IDs on CS systems will be auto-generated (1) or manually generated (0).autoid_contacts value determines whether contact IDs on CS systems will be auto-generated (1) or manually generated (0).autoid_addresses value determines whether business-address IDs on CS systems will be auto-generated (1) or manually generated (0).

VCM See Customising the Visual Configuration Manager (Optional) on page 267NodeWidth value, minus 40 pixels, determines default spacing at right of each VCM node icon.NodeHeight value, minus 40 pixels, determines default spacing below each VCM node icon.
