# What is Keyfax? Market leading resident repair diagnostics and query management software. Keyfax developed by [Omfax Systems](https://omfax.co.uk/) offers a complete suite of software diagnostic products to help busy housing associations and local authorities, managed accommodation providers and residents alike diagnose and resolve repair or tenancy-related enquiries faster & more accurately, first time, every time. {% embed url="" %} ### Discover Keyfax


Keyfax Administrator Tools	Develop & manage intelligent scripts to help contact centre advisors or residents resolve repair and general enquiries.	/files/5Ugk7Ws1Z4uHh5zRLRo9	/pages/ySpUZgBYMEueZM8WHPvW
Keyfax Staff	Enable busy contact centre service advisors to manage a wide range of resident repair and service enquiries.	/files/byRvmsoJV9rEla9gSVL0	/pages/COTf6nxrAMob3YuDQnqP
Keyfax Self-Service	Reduce inbound enquiries by delivering a online self-service interface for residents to submit repairs or enquiries, accessible 24 hours a day.	/files/pYWvaFCmseCJ6juqSPgH	/pages/gq7kDIox4VnbjqGX0QSF
KeyNamics	Empower call centre advisors with seamless integration between Keyfax and Microsoft Dynamics.	/files/IiJyHc677ldzyQac6s4y	/pages/I8wYV3Cjky76FtDZWRwn
Keyfax Client	Legacy client application for integrations with older Housing Management Systems (HMS).	/files/LByUXHYgMS0ERmRjnQ4X	/pages/w2rVfJgEeFnewEMyrvma
Keyfax Cloud	All the benefits of Keyfax without the hassle of having to host & manage your Keyfax installation.	/files/7aHTFbjH8onoDFX7lFAz	/pages/oLtqjOdeXZIJ2yb9EaUw

### Discover Features


Script Editing	Learn how to make the most of intelligent scripting within Keyfax.	/files/vXLHLbeqizUkzVBZW7kh	/pages/GRuAusZsVUTvsATg0Ywh
Questions	Learn more about the types of questions you can add to Keyfax scripts.	/files/vXLHLbeqizUkzVBZW7kh	/pages/SnwX50eZibJYorbDuwvo
Databoxes	Learn how to use Databoxes to deliver dynamic scripting.	/files/vXLHLbeqizUkzVBZW7kh	/pages/cP0GcCubNMH2NSAz2W3r
Services & Tasks	Learn how to use Keyfax services & tasks to automate processes & schedule work.	/files/vXLHLbeqizUkzVBZW7kh	/pages/iF9JTLvI4qbBtvbsSgzW
Reports	Get insights into your repair diagnostics process through dozens of pre-built reports.	/files/vXLHLbeqizUkzVBZW7kh	/pages/D3goBBhymJBkDH6vkx92
Integrations	Keyfax integrates with many popular housing management & tenant portal solutions.	/files/vXLHLbeqizUkzVBZW7kh	/pages/yCbtHRR0SgQeqat39N4J

# Keyfax Administrator Tools Deliver intelligent scripting quickly & easily using Admin Tools The Keyfax Administrator Tools desktop application empowers contact centre administrates to develop intelligent, context aware scripts to help advisors or residents alike diagnose and resolve repair or tenancy-related enquires faster & more accurately, first time, every time.

Using Keyfax Administrator Tools contact centre administrators can quickly & easily create sophisticated visual diagnostic scripts that leverage existing company data to help both call centre advisors assist tenants or to help tenants directly via self service support. ### Discover More


Navigation	Learn the main areas of the Keyfax Administrator Tools user interface.	/files/vXLHLbeqizUkzVBZW7kh	/pages/7S88J13uYSmqhVbTPz7p
Logging In	Learn how to login & access your Keyfax Administrator Tools installation.	/files/vXLHLbeqizUkzVBZW7kh	/pages/5Nj1Bx0eOec3R2uQbhmQ
Script Editing	Learn the basics of script editing within Keyfax Administrator Tools.	/files/vXLHLbeqizUkzVBZW7kh	/pages/GRuAusZsVUTvsATg0Ywh
Script Entities	Learn about the basic entity types available within Keyfax.	/files/vXLHLbeqizUkzVBZW7kh	/pages/PZBnuKYIcbU9keYONsj1
Users	Learn how to manage script authors and other administrators via Keyfax Administrator Tools.	/files/vXLHLbeqizUkzVBZW7kh	/pages/E8pnvqLLrpJ3y1bGAsB1
Reports	Learn more about the pre-built reports available within Keyfax Administrator Tools.	/files/vXLHLbeqizUkzVBZW7kh	/pages/D3goBBhymJBkDH6vkx92

# System Requirements The Keyfax Admin Tools system requirements. Keyfax scripts and users are managed via a desktop application installed on workstations within your organisation - this application is known as the **Keyfax Admin Tools**. The Keyfax Admin Tools desktop application requires a 64 bit Windows operating system with Microsoft .NET Framework 4.8 installed. The minimum requirements to run admin tools are as follows... * Windows 7, 8, 8.1, 10 & 11 * 64bit OS * .NET Framework 4.8 ### File sizes The Keyfax Admin Tools application will require approx 350MB of hard disk space. ### Workstation specification The Keyfax Admin Tools application requires a higher specification platform than a PC running only the client Keyfax installation. As a minimum, a single Intel Pentium 4 processor, 2GB of memory and a display resolution of 1280 x 1024 is recommended. External internet access is required to benefit from our online Help pages, intelligently linked to key areas within Keyfax Admin Tools. # Installation Learn how to install Keyfax Administrator Tools. Ensure the computer you are attempting to install the Keyfax Admin Tools upon meets the [system requirements](/product-suite/admin/system-requirements). In addition please ensure all critical windows updates have been applied. You should perform the Keyfax Admin Tools installation on a computer with reliable access to your Keyfax web server. We would advise a wired network connection whenever possible. You may experience poor performance when using a wi-fi connection. Please copy all installation files or the complete installation folder locally to the target installation machine. Do not attempt to launch the admin installer over a network share or external harddrive. Once all admin installation files have been copied locally simply double click or run the Keyfax Admin x64.msi file and step through the on-screen Keyfax installation wizard. The Keyfax Admin tools installation folder contains the following files. All files should be copied locally... * **`Admin.config`** - pre-configured for your Keyfax web server * **`Keyfax Admin x64.msi`** - the main Keyfax admin tools installer * **`Setup.exe`** - an optional executable for automated installations * **`Readme.txt`** - links to Help, Support, Known issues and solutions No other files are necessary to successfully install the Keyfax Admin Tools. After installation completes you can launch the Keyfax Admin Tools via the KeyfaxAdmin.exe file within the folder **C:\Program Files\Omfax Systems\n.n.n**. (where n.n.n is the version number e.g. 4.4.1). A short cut should also be available within your Start Menu under "**Omfax**". ### Installation Check List * Copy all Keyfax Admin Tools installation files locally to the target computer * Ensure the target computer for your Keyfax Admin Tools can access your Keyfax web server via http and / or https (Admin Tools will require connectivity to your Keyfax web installation). * Double click **Keyfax Admin x64.msi** and follow the on screen instructions * Launch Keyfax Admin Tools ### Installation Location When installing Keyfax Administrator Tools as of Keyfax 4.4.0.0 the default installation location should be `C:\Program Files\Omfax Systems\Keyfax Admin\X.X.X\KeyfaxAdmin.exe` – where X.X.X is the Keyfax version number. If your installing multiple versions of Keyfax Administrator Tools later than version 4.4.0.0 the installation process will automatically install each version into its own unique, independent folder. There is no need to change the installation path during installation. For earlier versions of Keyfax Administrator Tools (before 4.4.0.0 and below) only a single instance of Keyfax Administrator Tools can be installed. This would be installed to `C:\Program Files\Omfax (Touch-Base)\InterView Admin x64\KeyfaxAdmin.exe`. ### FAQs For answers to frequently asked questions related to the installation of Keyfax Admin Tools, please refer to [Keyfax Administrator Tools](/general/keyfax-faqs/keyfax-administrator-tools) # Logging On How to login to Keyfax Administrator Tools. {% embed url="" %} After launching Keyfax Administrator Tools, you will be presented with a brief splash screen which will display the Keyfax Administrator Tools version number. For example...

Keyfax Administrator Tools Splash Screen

You will then be presented with the login dialog. ### Login Form

Keyfax Administration Tools login screen

The login form contains the following fields... * **Username / Password**\ As initially supplied or subsequently configured by your Administrator. * **Server**\ This is preset at installation. You may find you have access to single or multiple servers, e.g. Live, Test, Training & Dev or other variations. * **System**\ This is preset at installation time. You may have one of more configured 'systems' on the same server, e.g. Live & Test. * **Script Type**\ These are the supported Script Type(s) available for the chosen System (above). * **Master Web Service (MWS)**\ The Master Web Service is a URL that enables Administrator Tools to communicate with the Keyfax Web Server. This will also appear if you hover over the logo area at the top of dialogue. This URL will be a preset value but it is possible to change this to point at an alternative server, so long as that server is running a version of Keyfax that is compatible with the version of Administrator Tools you are running. Clicking the Master Web Service text itself will display this dialogue (if any error had occurred when connecting to the server, this too would be displayed):

Viewing or editing the Master Web Service URL

Master Web Service URL Error - no endpoint listening

### **Forgot password** Assuming your user details are set up with a valid email address, and you have entered your username (above), you will be sent a new temporary password. You will be prompted to change this when you first login. ### **Password Requirements** In the [User Maintenance](/product-suite/admin/user_maintenance) tab a Login Mode (‘Windows’ or ‘Keyfax’) is defined for each user. As in earlier releases, ‘Keyfax’ administrator logins require a valid password. Windows Login requires **all** administrators to be using Active Directory (AD). {% hint style="info" %} **NOTE** It is not possible for some administrators to use Windows login if any other administrator needs to login with a non Active Directory account. {% endhint %} The login screen will pre-populate the most recent User (defaulting to any previous User). No password is required for a valid Keyfax ‘Windows’ login matching the current Windows User. Windows login is only available if configured on request or by your implementor. ### Change Password Login has a **Change Password** option which is forced in these situations: * When a password is reset either from Login ‘Forgot Password’ or in Admin Tools * If the password is not changed within the configured period * For any Admins with passwords that don’t meet the minimum requirements for password strength on the first login after the upgrade. # Navigation Learn how to navigate Keyfax Admin Tools. {% embed url="" %} The terms used throughout this guide refer to the following areas of the screen:

Most menu items open a tab (or switch to an open tab). Multiple tabs can be opened at any one time; as you click on a menu item, a new tab is displayed with the appropriate display. {% hint style="warning" %} **IMPORTANT** Editing is only permitted in one tab at a time; an asterisk (\*) identifies which tab is currently being edited. {% endhint %} ### Tabs **Home** - The home tab consists of the main menu [Users](/product-suite/admin/user_maintenance) - Access user maintenance and active users [Advanced](/product-suite/admin/advanced) - Access to Base Templates, Communications Queue, Health Check. Other features may be available based on your level of permissions. ### Main Menu (Home tab)

Items and their functions are grouped in the Main menu ribbon as follows: * SCRIPTS - the level at which you would like to edit scripts * ENTITIES - where the component parts of a script are created and maintained * TEST - allows the scripts to be tested from an Operator's perspective * REPORTING - Viewer that allows Keyfax reports and Subscriptions to be run * HELP - access to online help * EXCLUSIVE - toggles the mode between exclusive and non exclusive access * EXIT - closes Admin Tools {% hint style="info" %} **NOTE** The EXCLUSIVE switch is disabled whilst editing is taking place in any tab {% endhint %} ### Navigation Pane The Navigation Pane is where the selection of items (relevant to that tab) are displayed. It will contain a list of items, often in groups and ordered alphabetically. A ‘filter’ is provided in many views allowing you to search the available options.

Navigation pane when editing a Master Script

### Menu Bar

The Menu Bar shows icons for viewing and editing items. Icons on the Menu Bar will vary depending on which items are currently being viewed and edited. Buttons include: * ADD - adds a new item * SAVE - save changes * EDIT - allows changes to be made to the selected item * RESTORE - restores the item to the last saved position * DELETE - deletes an item * TEXT - edits the text of a Message * SPELL CHECK - checks the text of a Message for any spelling errors * SCRIPT - displays the script grid * PROPERTIES - toggles between the script editing pane and properties * FLOW - displays a flow diagram illustrating the current script contents * EXPAND - expand all the script steps within a script * CLOSE ALL - closes all the script steps within a script * REFERENCES - displays a list of areas where the selected item is used * GET MASTER - update the currently selected script with the script from the master script set * SET MASTER - update the master script set with the currently selected script {% hint style="info" %} **NOTE** The DELETE button will be greyed out if you are trying to delete an entity or level of a script - (topic or category) unless you are in Exclusive mode. WARNING: Pressing Delete cannot be undone {% endhint %} ### Viewing / Editing Pane The Editing Pane is the main work space. It is where the script or entity editing takes place. The properties of the screen will change based on the type of entity you are viewing or editing. The example below displays the script grid when editing a Master Script.

### Script Type The Script Type menu enables admins to switch between different Keyfax instances based on what has been installed/purchased. For example switching between Repairs Diagnostics and Enquiries Diagnostics.

When switching, Admin Tools will close all open tabs and load the database of content for the selected Script Type. ### Search Anywhere {% embed url="" %} The search anywhere capability allows Keyfax administrators or script authors to quickly and easily locate any content within Keyfax via a simple keyword search. The new search functionality is accessible via Keyfax Administrator Tools within the title bar. Results are grouped by entity and listed alphabetically. Click an item from the list to open it in a new tab. Previous search terms will remain in the drop-down menu until closing Admin Tools.

### Status Bar This area displays environmental settings and the Exclusive mode setting (Yes/No), as well as the version of Admin Tools being used.

### Health Check An automatic health check will be run upon logging into Administration Tools to check for any errors or issues with the selected Keyfax installation. A progress bar will be displayed within the status bar:

Any issues or errors will be displayed within a pop-up dialogue box for Admins to review:

The health check can be re-run at anytime via the "Advanced" tab:

# Exclusive Mode What is it and why is it necessary? {% embed url="" %} Keyfax Admin Tools provides multiple administrators with the ability to concurrently edit scripts. Because components of a script are widely spread across multiple entities (Messages, Questions, Databoxes, Expressions etc) to maintain the integrity of the scripts, certain functions require you to have **Exclusive** control over certain actions that you wish to perform. This is particularly the case when ***deleting*** entities. Of course, most editing can be carried out *without* the need for Exclusive access. If, say, a Delete button is greyed out or disabled, this usually indicates that you need to switch to Exclusive mode.

You will need to be in Exclusive mode to Delete entities as follows: * **Script Sets** * **Categories** * **Topics** * **Questions** * **Messages** * **Markers** * **Databoxes** * **Databox values for Company data (CO)** * **Databox Expressions** * **Priorities** * **Services** * **Tasks** * **Task Templates** Further, you will need to be in Exclusive mode to: * **Move a Question between Topics** * **Unassigning Topics from a Category** In effect, by switching into Exclusive mode, you are locking out the script contents so that no other administrator can continue editing. To ensure that, when necessary, no other editing is ongoing, when attempting to switch into Exclusive mode (from the main menu) checks are made to see if other administrators are logged in. If it is found that someone else is logged in (and is using the same Script Type), you will be prompted with this message:

Warning showing other administrator(s) are logged in

The other administrator(s), in this case user 'JWATSON' will see the following messages:

# Script Levels Learn about script levels within Keyfax Administrator Tools. Keyfax provides an intelligent Scripting System, enabling staff to handle call enquiries and service requests consistently according to the individual and context. To access the Scripts, select any of the three options in the Scripts group on the Main menu.

in brief, the three buttons offer the following: **MASTER** - the ability to maintain scripts at a master level which provides the benefit of reusability across different script sets **SYSTEM** - a set of reserved and custom scripts **SET -** script sets split out by business function, e.g. day to day or out of hours, leasehold etc The structure of scripts are common across all three types as they are divided into the following: * **CATEGORY** - the grouping in which the Script Topics are held for ease of identification * **TOPIC** – the subject that the enquiry or service request relates to (for example - noisy neighbours, shared ownership, broken window, blocked waste) Each Script comprises of: * **SCRIPT STEPS** – the questions or prompts that identify the nature of the enquiry or problem * **ACTIONS** - provide messages, collate and manipulate responses, generate tasks and service orders Script Steps are linked to create a logical flow. When designing a Script, it is recommended that the script logic is defined first. Scripts are defined within Script Sets. Each Script Set comprises of a collection of individual Scripts which are in turn grouped into Categories and Topics:

Each Script Set would be designed to reflect a particular service or client group. You can therefore create multiple Scripts Sets. To assist with managing multiple Scripts, you can create: **SYSTEM SCRIPTS** – containing individual Scripts that can be either run at defined points, for example at the start of each Script; or that can be used to link repetitive Scripts to individual Scripts without having to re-create the Script each time, for example ‘How did it happen?’. **MASTER SCRIPTS** – all Categories and Topics are created at Master Level. These individual Script Categories and Topics can then be inherited for use by each Script Set. **SCRIPT SETS** – containing the Scripts that will be used by the Operators, designed to reflect a particular service or client group. These can have links to both System Scripts and Master Scripts. {% hint style="info" %} **NOTE** All Master Script Categories and Topics and their associated properties are created and held at the Master level. Any Categories used at Script Set levels are ‘inherited’ from the Master Categories so must already be set up at Master level. {% endhint %} # Master Scripts {% embed url="" %} Select Master from the Script groups menu:

The navigation pane will display all the Script **Categories** and opening any of these will reveal the related **Topics.** The Category properties are displayed in the editing pane:

{% hint style="info" %} Script Categories and Topics must be created at Master Script level to be available at Script Set level. {% endhint %} By selecting a Topic, e.g. '**Hoist**' in the **Adaptations** Category above, the script steps will be displayed:

Master script steps displayed in editing pane

To add a new Topic click on the **\** tab at the bottom of each category list (or click **Add** on the menu bar). This will open the Topic Properties pane for your new topic and will automatically take you into *Edit* mode. This Topic will be added to the Categories held at the *Master* Script level. The **Menu bar** immediately above the script grid shows the available options:

| Menu button | What it does | | -------------- | ---------------------------------------------------------------------------------------------------- | | **ADD** | Adds a new, Category, Topic or Section depending on the properties you have selected | | **SAVE** | Saves any change you've made | | **EDIT** | Switches in/out of Edit mode. This is greyed out if you are editing in another tab. | | **RESTORE** | Restore the script to the last saved point (this is not an UNDO button) | | **DELETE** | Delete a line from the script or the Category/Topic itself (you'll need to be in **Exclusive** mode) | | **PROPERTIES** | Show the Category or Topic properties | | **SCRIPT** | Show the Topic script | | **FLOW** | Show a flow diagram of the selected script | | **EXPAND** | Expand all script grid steps | | **CLOSE ALL** | Close all grid steps | | **REFERENCES** | Show where this script is used | | **READ ONLY** | Indicates if you are in Edit mode | | **HELP** | Show related Help pages | # Category Editing How to edit Category properties and Image Hotspots {% embed url="" %} Clicking the Category name (e.g. **Adaptations**) from the Master Scripts Selection, will display the properties for the selected Category:

* **Name** – the displayed name of the Category * **Sort Order** - enter a numerical value to custom / override the order of the Category * **Selectable (visible)** – if this button is checked the category is visible to the Operators * **.. Continuation (not visible)** – if this button is checked the category is not visible to Operators and would be used as a Continuation Script, linked to a Visible Script ### Sort Order Users can custom the order in which Categories appear by entering a numerical value in the Sort Order field at both Master and Set level. The value from Master is inherited at Set Level but can be edited independently. In the example below, the Category of "Other" has the value of "1", resulting in the Category being displayed as the first selectable Category. The same logic can be applied to other categories using the values of "2", "3" and so on.

### Category Images {% embed url="" %} * **Selection image** - a Selection Image can be added to the selected Category by clicking the "Selection Image" icon. The image will appear on the Keyfax Application landing page as seen below. To access this feature within the staff modules, it must be enabled within your Keyfax installation (4.4.7+) by a member of Omfax Support. * **Image text** - the name given to the image. Please note, Keyfax will display this text for the Category Image as highlighted below instead of using the Name of the Master Script Category. * Images will be inherited at Script Set level but may be overwritten if required.

Category Selection Images for Repairs Diagnostics

* Administrators can select existing images from the Keyfax database or upload new images.

* **Topic Hotspots** - Hotspots can be used with images to link to Topics within the selected Category. Images with ‘Hotspot’ areas can be added to the Script, which will be displayed to the Operator when they select a category. By selecting a Hotspot, Operators are selecting the associated Topic. Click on ‘Topic Hotspots’ which will open the Hotspot Editor in a new window * **Related images** - the facility for Operators to view additional images appropriate to the selected Category. Click on ‘Related Images’ to open the Related Images Selection in a new window. ### The Topic Hotspot editor {% embed url="" %} Clicking the Topic Hotspots button will present this dialogue: **The Hotspot Editor -** allows editing of images to be used within your scripts. To make any changes, click **Edit** on the Menu Bar.

* **Image** – identifies the image file being used – default images are **PNG** format although **GIF**, **BMP** and **JPG** can also be used. * **Display Text** – the name displayed to Operators * **Topic** – displays the Topics within the selected Category. Where a Hotspot has yet to be created, a **+** (plus) sign is shown to the right of the Topic; when you click this, a new Hotspot area will be created in the image which can be moved and resized as required over the text label (any overlapping areas will be highlighted in red). * **Text Pos.** - setting the text position of Top, Bottom, Left, Right or Centre will add a clickable call-to-action button to the image. This can be used when using an image that has no text labels. This feature provides Administrators greater flexibility to upload their own images and add their own text buttons (v4.4.7 and later only) * **Upload New Image** - when in edit mode, displays a file selection dialog box through which new images can be uploaded to the server (v4.4.7 and later only). * **Select Existing Image** - when in edit mode, displays a dialog box through which images that are already in use on this server can be selected for use as this category's hot spot image (v4.4.7 and later only). {% hint style="info" %} **NOTE** If you are in **Exclusive** mode you are able to remove the image and all related hotspots. To do so, click on Edit and then on the **Remove image and Hotspots** button. You can then save your changes. {% endhint %}

Remove image and Hotspots when in Exclusive mode

### **Editing Related Images** {% embed url="" %} Keyfax provides a facility for Operators to view additional images appropriate to the selected Category. Related images are available in the 'Images' tab:

Click on ‘**Related Images**’ to open the Related Images Selection in a new window.

To modify the list of related images click **Edit** on the Menu bar. * **Image** – identifies the file name for the selected image. To view or select another image click the Folder button * **Name** – the name for the image displayed to Operators. * **Upload New Image** - when in edit mode, displays a file selection dialog box through which new images can be uploaded to the server (v4.4.7 and later only). * **Select Existing Image** - when in edit mode, displays a dialog box through which images that are already in use on this server can be selected for use as this category's hot spot image (v4.4.7 and later only). {% hint style="info" %} **Note:** Related images must be assigned for each Category at Script Set level in-order to be visible to the end user when they click on the **images tab**. {% endhint %} # Topic Editing Editing the properties of a Script Topic {% embed url="" %} If you select a Topic (remember Topics are in effect children of Categories), clicking the **Properties** button will display the Topic details. * **Name** – the displayed name of the Topic * **Key Words** – keywords can be searched by Operators when looking for a Topic – use all words that might assist with the selection (even common misspellings if you think it will help!). Keywords can be separated with a comma or a space and are case insensitive. * **Related Image** – this is the image displayed to Operators when they select the ‘Related Images’ tab in the Keyfax Application. The drop-down list displays all images available for the Category. Any image selected will be shown as a thumbnail. * **Topic Selection Image** - From 4.4.7+ a Topic Selection Image can be assigned to the Topic. * **Selectable (visible)** – if this button is checked, the **Topic is visible** to Operators. * **.. Continuation (not visible)** – if this is checked, the **Topic is not visible** to Operators and would be used as a *continuation* Script, linked to a visible Script. Topics that have been set as Continuation (not visible) are displayed in the navigation pane with the leading ‘**..**’

### Topic Selection Image A Topic Selection Image can be added to a Topic. This will be visible when using the Keyfax Application as below:

Topic Selection Images as seen in the Keyfax Application

Admins can upload new images to the database or select from existing images previously uploaded.

**Image** - the file name of the image. **Name** - the name given to the image. This can be edited. **Upload New Image** - an option to upload a new image to the database. **Select Existing Image** - search and select an existing image from the database. **Clear Image** - clear/remove the current selected image. {% hint style="info" %} Topic images will **not** be displayed if a Hotspot Image has been assigned at Category level. {% endhint %} # Self-Service Categories Managing category images for Keyfax Online (e.g. Repairs or Enquiries Self-Service) When using Keyfax Self-Service, end users will be presented with icons to allow them to select the category that is most relevant to their (e.g.) repair or enquiry. The icons will be arranged with text captions as shown in this example (layouts may differ):

Example of Repairs Self Service category selection page

{% hint style="info" %} **TIP** The categories / images will be ordered on the landing page based on the text entered into the “**Image text**” field when editing a category within Keyfax Administrator Tools. {% endhint %} To select an image for your Category, select the category you wish to edit, and click on the **Edit** button:

Category properties for Keyfax Self Service

Click the **Selection Image** icon and either upload a new image or select an existing image. Update the **Image Text** field with the name you want displayed on the Category Selection page. Below is a sample of the default (model) images and file names.

### **Image Dimensions** Details about the format and dimensions of each supported image can be found within our [Keyfax Administrator Tools](/general/keyfax-faqs/keyfax-administrator-tools) FAQs. # System Scripts What they are and when and how to use them. System Scripts are Scripts designed to be run at selected times or to provide Scripts that can be used by other Script types – by Master Scripts or Script Sets. Select **System Scripts** from the Main Menu. The script shown below is a '**Startup**' script and can be tailored to meet your needs. This script is run every time a Keyfax script is launched. In this example, a check is made to see if the current time is between 0800 and 1800. If it falls outside this period, the Tenancy code that was imported from the host (calling) system will be overridden such that an alternative script set is used, i.e. a script set that is specifically for use in an out of hours operation:

The Navigation pane - shows two Categories of Scripts – **Reserved** and **Custom**. ### **Built-In System Scripts** {% embed url="" %} These Scripts are designed to provide preset functions and by default the following scripts are available: [**Cancel**](/product-suite/admin/script-levels/system-scripts/cancel) - a Script that runs when a script is cancelled [**Priority Justifications**](/product-suite/admin/script-levels/system-scripts/priority-justifications) – a Script that runs when a priority is over-ridden by an Operator on the Results (final) screen [**Results**](/product-suite/admin/script-levels/system-scripts/results) – a Script that runs just before the Results (the final) screen – after other Scripts have completed [**Special Instructions**](/product-suite/admin/script-levels/system-scripts/special-instructions) - a Script that identifies any special instruction and is triggered by Operators from the Special Instructions button on the Results (final) screen within the staff modules [**Startup**](/product-suite/admin/script-levels/system-scripts/startup) **-** These are Scripts that run when Keyfax is started to handle an enquiry or service request ### **Custom System Scripts** {% embed url="" %} Custom Scripts are created as required and other Scripts can link to these. For example, Scripts to check ‘How did it happen?’ – a standard question often used against many service requests; a Script to check on ‘Tenant responsibility’ for a service request. To create a new custom Script, click on **\** at the foot of the Custom Scripts list. Give the script a Name that will make it easy to identify.

# Cancel Learn more about cancellation system scripts. A Cancel System Script runs whenever a Keyfax script is cancelled. When a Keyfax script is cancelled no history is captured for the script so it's not possible to provide detailed reporting within Keyfax around script cancellations. If a script is cancelled Keyfax would typically pass back a flag to your housing management system or tenant portal to indicate the script was cancelled and no action is required. We recommend adding a Message to the script to inform the user that Keyfax is about to cancel and advise on next steps to make for a better user experience. {% hint style="info" %} **Note:** Reserved System Scripts cannot link to Master Scripts. You can only link to Custom System Scripts. {% endhint %}

# Priority Justifications Learn more about the Priority Justifications System Script. The Priorities Justifications script should consist of a single List Question as below.

Adding additional entities or actions will have no impact and therefore should not be added. Simply edit the Question to add, remove or update the override options. The Priorities Justifications Script is triggered when an Operator clicks the priority over-ride button on the Results (final) screen within the Staff modules, typically when a Service (SOR) Code has been assigned.

This will display a new window, allowing the Operator to select a reason for the override from the Priorities Justifications System Script.

A record of all priority overrides is available via the **Audit History** report within Reporting. This can be useful to help identify which Operators are overriding scripts, highlighting potential training needs or whether certain scripts need reviewing.

Admins can disable the ability to override a priority (and other settings) for individual users within [User Maintenance](/product-suite/admin/user_maintenance). Selecting this option will remove the button from the Results (final) page.

Disable service priority edits in User Maintenance

# Results Learn more about the Result System Script. The Results System Script runs just before the Results (the final) screen within the Keyfax Application – after other Scripts have completed. The Results System Script can be used to display a message advising of next steps, apply script logic or capture any final information from the advisor or tenant before Keyfax completes. {% hint style="info" %} **Note:** Reserved System Scripts cannot link to Master Scripts. You can only link to Custom System Scripts. {% endhint %}

# Special Instructions Learn more about the Special Instructions System Script. The Special Instructions System Script is linked to the Special Instructions field on the Results (final) page. It should consist of a single List Question as below. It can be left empty if not required. {% hint style="info" %} **Note:** The data entered in the Special Instructions field is typically included in the Keyfax Export XML but not all Host Systems process this. Please check your host integration uses this feature. {% endhint %}

The list will appear as below, enabling the Operator to select an option, which will record the text. The Operator may add additional notes if necessary.

Text that is stored in the Export Databox labelled "Special Instructions" can be written automatically into the Special Instructions field too. This can be in addition to using the System Script. Note, the Export Databox must be used as a [Databox - Write](/product-suite/admin/entities/databoxes/databox-write) and within a normal script, not the Special Instructions System Script.

Export Databox to update the Special Instructions field

# Startup Learn more about the Startup System Script. The Startup System Script is run every time the Keyfax Application is launched. It can be used to display Messages, ask additional Questions and include script logic to launch different Script Sets before reaching the Category Selection / landing page of Keyfax. In the example below, we have a Message warning of potential service disruption and Script logic to check the time of day. If the time of day is between 08:00 and 18:00 then Keyfax will launch the default Script Set. If outside of these times it will take the "Otherwise" route and launch the "Out of Hours" Script Set.

When displaying Messages or Questions, the Operator will see the "Start-up" title within the Keyfax Application. The Category/Topic Selection screen will appear upon completion of the Startup script, unless it it set to Cancel or Submit.

# Script Sets What they are and how to use them {% embed url="" %} {% embed url="" %} Script Sets are used to segregate functional aspects of your operation. For example, you may have built an extensive library of Master Scripts which can be 'wired into' Script Sets. Each Script Set can be limited to provide a discrete set of functions unique to the context, e.g. Out of Hours services that are distinct from office hour operation, services for Leaseholders, services for specific property types or communal areas etc. Selecting Script Sets from the main menu will open a new tab:

The Navigation Pane contains the Script Selection under the selected **Level**. **Level** – Select **Set** to view all Script Sets designed to function with their own Scripts. Select **Script Alias** to view Script Sets who have their scripts utilised by other Script Sets. {% embed url="" %} {% hint style="info" %} A bit of an explanation about **Aliases...** When Keyfax scripts are launched, a code stored in the startup data (that is sent by the calling host) is used to identify which Script Set to use. Historically, for Repairs, the code used is named '**Tenancy**'. For Enquiries, the '**Tenure\_Code**' fulfills this role. It may be that the host system can supply a variety of codes that require the *same script set* to be used. Enter **Aliases**! These are useful where one or more different Tenancy Types, with different Tenancy Codes behave in the same way and can be represented by one Script Set. One Tenancy Type is selected and a Script Set for it is created. All the other Tenancy Types with their Tenancy Codes are setup as Aliases of this, they look like normal Script Sets but they have no content (images/categories/topics) as they redirect to the Script Set they are an alias of. {% endhint %} Looking at an example use of an Alias. The screenshot below shows the Script Set '**Housing Services (Tenants)**' and its associated Categories. Note it has a code of '1'. When a tenancy (or tenure\_code) of '1' is received, this Script Set will be launched:

The next screenshot shows the Script Set '**test**' is an alias and uses the Scripts from the Script Set '**Housing Services (Tenants)**'. It is therefore displayed as subordinate to the Script Set 'Housing Services (Tenants)':

If the host were to supply a tenancy/tenure code of '**1**' or '**tst**' the Script Set '**Housing Services (Tenants)**' would always be launched. ### Editing Script Set Properties The Editing Pane displays the Properties of the selected Script Set once a Script Set in the Navigation Pane has been selected: The Script Set Properties are: **Code** – the code for the Script Set; that should be set to the tenancy/tenure code passed from the host system (in the Startup data file) **Name** – a descriptive name used for display purposes **Policy Help page** – the URL or UNC path to the Policy pages for this Script Set. This can either be a full URL or UNC path: [FILE:////servername/sharename/file1.doc](file://servername/sharename/file1.doc) **Alias for Set** – the Script Set that this set utilises. {% hint style="info" %} **NOTE** Click Edit to modify any of the settings for the Category. Amendments made at Script Set level will apply only to the Script Set. Script Sets can inherit elements from Master Scripts but display them in a unique way. {% endhint %} **Master Category Assignment** - this section provides the facility for selecting the Categories to be used for each Script Set. **Unassigned Categories** – shows the full list of Categories available for assignment. These are Categories that have been set up in the Master Scripts. **Assigned Categories** – shows those Categories already assigned to be used for this Script Set. Script Sets can therefore use a unique selection of the Categories available. ### Assigning and Unassigning Categories {% embed url="" %} {% embed url="." %} {% hint style="info" %} **NOTE** Categories must be created at Master Script Level first or they will not be available at Script Set Level. Also, you must be in **Exclusive** mode to **unassign** categories. {% endhint %} To **assign** a Category, select the required Category from the Unassigned Categories list and click the **right arrow**. To **unassign** an Assigned Category, select the required Category from the Assigned Category list and the **left arrow.** In the example below, the **Anti-social behaviour** Category is the only unassigned Category:

### Script Sets Linking to Other Script Sets Keyfax doesn’t allow jumps *between* Script Sets so there cannot be any cross-script references. ### Deleting Script Sets {% hint style="danger" %} **DANGER** Deleting a Script Set cannot be undone. The Script Set and all Script Set specific data will be permanently deleted from the Keyfax database. We would strongly recommend backing up your Keyfax database before making permeant changes. {% endhint %} To delete a Script Set you'll need [Exclusive Mode](/product-suite/admin/exclusive-mode) within Keyfax Administrator Tools. When deleting a Script Set only Script Set specific overrides for the Categories, Topics and Scripts are deleted, no Master Categories, Topics or Scripts are deleted. # Category Properties Explaining each property of your Categories. Click on any Category to show its properties:

**Name** – a descriptive name used for display purposes **Sort Order** - enter a numerical value to custom / override the order of the Category. This value is inherited from Master but can be changed independently\ \ **Master Category** - the associated Master Category name is displayed. This is to assist where the Category name has been amended at Script Set level **Selectable (visible)** – if this button is checked the Category is visible to Operators **.. Continuation (not visible)** – if this is checked the Category is not visible to Operators and would be used as a continuation Script linked to a visible Script. Categories that have been set as Continuation (not visible) are displayed in the navigation pane with the leading ‘**..’** **Test** – if this is checked the Category will appear with a yellow warning triangle in the Script Set tree structure.

These Scripts will be visible via the Test Container if the option "**Include categories/topics set to test mode**" is ticked. Categories and Topics that are set to "Test" will not be visible to Operators.

Test Container for Enquiries Diagnostics

### Category Images Category images are inherited from Master Script level and can be overridden at Set level. **Selection Image button** - clicking this will allow Admins to upload a new image, select an existing image or clear the image selection **Selection image** - the file name of the selected image **Image text** - the name given to the image. This can be edited when uploading the image **Topic Hotspots** - Admins can upload a new image or select an existing image **Related Images** - Admins can assign / unassign Related Images to the selected category. Images must be assigned in order to be visible in the "Images" tab within the Keyfax Application # Setting up Topics Assigning, unassigning and editing Topic properties To reveal the assignment of Topics within a Category, simply click the Category in the left-hand Navigation pane:

**Unassigned Topics** – shows the full list of Topics for the Category that are available for assignment. These are Topics that have been set up in the Master Scripts **Assigned Topics** – shows those Topics that are already assigned to be used for this Category in this Script Set. Script Sets can therefore use a unique selection of the Topics available {% hint style="info" %} **NOTE** Topics must be created within a Category at Master Script Level first or they will not be available at Script Set Level. {% endhint %} To assign a Topic, select the required Topic from the Unassigned Topics list and click on the **right arrow** button. To unassign a Topic, you must first be in [Exclusive Mode](/product-suite/admin/exclusive-mode), then select the required Topic from the Assigned Topics list and click the **left hand** arrow button. ### Category Images #### Topic Hotspots Images with ‘Hotspot’ areas are displayed to Operators as they select a Category. Hotspots are linked to Topics within the selected Category. By selecting a Hotspot, Operators are selecting the associated Topic. Click on ‘**Topic Hotspots**’ to open the Hotspot Editor. This will display the image and the Hotspots with the associated Topics that have been created at the Master Script level. By default, this will be the image displayed to the Operators:

To modify the Hotspot click **Edit** in the Menu Bar A message will appear:

If '**Yes**' is selected, the changes made at Script Set level will be unique to that Script Set. To continue, select ‘**Yes**’ and the following screen will be displayed, showing the hotspot areas have been removed. Admins can either reapply these, upload a new image or select an existing image to use instead.

The Properties shown are: **Image** – identifies the image file being used – default images are ‘PNG’ format. ‘GIF’, ‘BMP’ and ‘JPG’ format can also be used. **Display Text** – the name for the image to be displayed to Operators. **Upload New Image** - click to upload a new image to use for a hotspot. **Select Existing Image** - click to select an existing image that has previously been uploaded. **Topic** – displays the Topics within the selected Category. Where a Hotspot has not been created a '**+'** (plus sign) is shown to the right of the Topic. To create a Hotspot for the Topic click the plus sign; a new Hotspot area will be created in the image which can be moved and resized as required (any overlapping areas will be highlighted in red). {% hint style="info" %} If you are in **Exclusive** mode and you have overridden the Master Hotspot for this category (as detailed above) there will be an option to remove the image and all related hotspots. To do so, click **Edit** and then '**Remove image and Hotspots**', you can then save your changes. This will align your Set level image with that of the Master set. {% endhint %} **Text Pos.** - setting the text position of Top, Bottom, Left, Right or Centre will add a clickable call-to-action button to the image. This can be used when using an image that has no text labels. This feature provides Administrators greater flexibility to upload their own images and add their own text buttons (v4.4.7 and later only). ### Related Image Assignment Keyfax also provides a facility for Operators to view additional images appropriate to the selected Category; this is visible from the related images tab. Images available within each Category are set up at Master Script level. Click on ‘**Related Images Assignment**’ to view the assigned images. The following screen will appear:

**Unassigned Images** – shows the full list of images for the Category available for assignment. These are images that have been set up in the Master Scripts. **Assigned Images** – shows those images already assigned to be used for this Category in this Script Set. Script Sets can therefore use a unique selection of images available. {% hint style="info" %} You must set up Related Images Categories at the Master Script level before they are available at Script Set level. {% endhint %} To **assign** images, select the required image in the Unassigned Images list and click on the **right arrow** button. To **unassign** an Image, select the required image from the Assigned Images list and click the left arrow. # Topic Properties An overview of the Topic Properties at Set level. In the Navigation Pane, select a Topic to display the Topic Properties in the Editing Pane. By default, the Topic details will be those inherited from the Master Scripts. These can be amended at the Script Set level to present a unique set of Script Topics for the Script Set. Click **Edit** on the Menu Bar to amend details for the Script Set:

**Name** – the displayed name of the Topic. **Key Words** – keywords used by the keyword search for Operators when looking for a Topic – use all words that might assist with the selection. By default Keyfax search will use keywords entered at Master Script level. **Related Image** – this is the image displayed to Operators when they select the ‘Images’ tab for the Topic when using the Keyfax Application. The drop-down list displays all images available for the Category. Any image selected will be shown in the display area. If an associated thumbnail image has also been created, this will be displayed in the display area to the right. **Topic Selection Image** - displays the Topic Image inherited from Master Script level if it exists. **Selectable (visible)** – if this button is checked, the Topic is visible to Operators. **.. Continuation (not visible)** – if this box is checked, the Topic is not visible to Operators and would be used as a continuation Script linked to a visible Script. Topics that have been set as Continuation (not visible) are displayed in the navigation pane with the leading ‘..’ **Test** – if this is checked, Scripts are visible to you, the Administrator, when run using the Script Test (Test - on the Main Menu) but not to Operators:

If you put at a Topic into 'Test' mode, it will appear in the tree with a warning triangle:

# Loading Script Sets Present tailored Keyfax scripts based on tenure type, audience or other criteria. {% embed url="" %} Using start up [System Scripts](/product-suite/admin/script-levels/system-scripts) Keyfax can dynamically load different [Script Sets](/product-suite/admin/script-levels/script-sets) based on supplied start-up data or other business criteria. On this page we present some basic examples for both Repairs Diagnostics and Repairs Self-Service to help you understand how dynamically loading Script Sets can be achieved for both call centre advisors and self-service tenants alike. ### Repair Diagnostics {% hint style="info" %} **TIP:** Write the desired script set code to `Startup/Tenancy/text()`. {% endhint %} In the below example we present unique out of hours scripts if the advisor visits Keyfax before 8am or after 6pm. During business hours the user would be presented with the default script set.

Conditionally loading Repairs Diagnostic Script Sets

This works by setting the `Startup/Tenancy` start-up element to the script set code we wish to display to the advisor. ### Repairs Self Service {% hint style="info" %} **TIP** Write the desired script set code to `Startup/ScriptSet/text()`. {% endhint %} You can see below for Repairs Self Service we are asking the tenant to select a specific example script set via a list question within a Keyfax start up system script...

Conditionally loading Repairs Self Service Script Sets

This writes the script set code for the list item the tenant selected into the `Startup/ScriptSet` start-up element which instructs Keyfax Repairs Self Service to load the selected script set. # Script Editing Learn how to edit scripts via Keyfax Admin Tools. Scripts take the operator or end-user through a series of questions until an outcome is achieved. Decision making by the Scripts is performed by responding to Answers and other factors that can control the flow of script, e.g. Databoxes. All Scripts (System, Master or Script Sets) are displayed and edited in the Scripting Grid. To edit, open the required Scripts, navigate to the Topic and click the Edit button. For new Topics, create the Topic first.

As per the header, the grid contains: **Script Step** – the questions and options displayed in a hierarchical tree structure **Rec** – if checked, the selected response is recorded and added to the fault/enquiry description **Act** – indicates the type of action. These can be any of:

Code	What it does
DBR	reads the contents of a Databox
DBW	writes to a Databox
LNK	Links to another script
MKR	denotes a Marker, used for deeper reporting
MSG	denotes a Message
PRI	sets a Priority
SVC	selects a Service code (aka SOR)
TSK	denotes a Task

**Action** – displays the selected Action **Next Step** - indicates the next step to be taken from a drop down menu. This menu offers the following options:

Option	What is does
Next Step	simply jumps to the next step (nothing is displayed in the grid)
End	the Script finishes (will then return to any calling Script)
Cancel	the Script will be cancelled
Submit	this defines where a Script will terminate and navigate to the results page
>FL	jumps to another Script Type (in this example, the code 'FL' denotes a script type named 'Frontline', meaning the Enquiries Script Type)
Section 1	go to a declared section of Script (you can name these as you wish - meaningful names will add clarity to your script!)

### Adding Script Sections To add a new script section edit the script then use the "Add" button within the toolbar to create a new script section. The new script section will appear at the very bottom of the script and the name can be changed by updating the section name displayed within the grid. Multiple Sections can be added. ### Quick Editing Items that you wish to include in your script are normally created in advance. However, to assist with editing, by right clicking on the **Script Step** or **Action** columns, context menus can be viewed, which allows for the creation of a new items, or to edit an existing Entity or Action. Right clicking the **Script Step** column displays this menu:

Quick Edit menu from the Script Step column

...whereas right clicking in the **Action** column displays this menu:

### Editing hints, tips & tricks **Adding an Action** - if an Action is already in place against a Script Step, by dragging a new Action and holding the '**Shift**' key forces the original item down a step, to allow the new Action to be in the correct place. {% hint style="info" %} **NOTE** Keep an eye on the area above the Script grid as guidance or errors will be displayed here as you manoeuvre elements of your script, e.g. ![](/files/SiQAZzC5IlhN25XEQ0Lf) {% endhint %} **Duplicating Actions** - by holding the '**Ctrl**' key and selecting a Message, Priority, Service Code or Task already being used, these can be duplicated and moved to other positions within the Script Grid.\ \ **Displaying Properties** - by **double clicking** on a script item a new tab will open that displays its current properties.\ \ **Reordering Sections** - a section can be moved in the Script Gird by clicking on the 'Action' Column and **dragging and dropping** it to the desired location. This can only be done above or below another whole section, rather then *within* a section. For clarity, Section headers are shaded and extend across the Script Grid. ### Undoing your changes Once you have made changes to your script, by clicking the **Restore** button you will be prompted with this message:

{% hint style="info" %} Note that the **Restore** button is not an '**Undo**' button - all changes to to the script will be undone and the script will appear as it did when you began to edit it. {% endhint %} ### Get and Set Master You will normally create your scripts within Topics at the Master level. When assigning Topics to a Script Set, links to the associated Master topic will be auto-generated, e.g.

By clicking '**Get Master**' you will be prompted with this message:

By clicking **Yes**, the Master Script steps will be copied into the grid, replacing the current contents of the grid. ### Script Links - some rules The available Script links are dependent on the Script Type. Please be aware of the following: * Scripts within a Script Set can Link to Scripts within the same set, to Master and Systems Scripts * System Scripts can only Link to Custom System Scripts * Master Scripts can Link to Master Scripts and Custom System Scripts but not to Script Sets. # Script Editing - The basics Getting started with script editing. ### Master Script Links How to link a Master Script to another Master Script. {% embed url="" %} ### System Script Link How to link a Master script to a Custom System Script. {% embed url="" %} ### Drag & Drop Any of the different Item types can be added to the Script by using drag and drop. Select an item (Question, Message, Task or any other item) from the list of items shown in the Navigation Pane.

Left-click on the item with the mouse, hold the left mouse button down and move the cursor to the required position and release. Initially the cursor will change to ![](/files/75eHpd4J02u3nsMEroMi)indicating that the question cannot be moved, but as you move the mouse into the Editing Pane a symbol ![](/files/Ic7UZwcZcxSn2hliQFGR) will appear to the left of the Script Step column. The cursor will also change to ![](/files/Ck5yG4ajX8qvKyPWgk2Q) as it moves over an area where the item can be placed. Releasing the left mouse button will place the item into a position ***below*** the step where the cursor is located; this makes it the next step in the sequence. To place the item ***above*** an existing step, hold down the **Shift** key before dropping and the icon by the Script Step will change to ![](/files/xYX7mrMLWGc2ZaxnA8kZ). ### Deleting an item To delete any item, select it with the mouse and click the **Delete** button.

Script steps are displayed in a hierarchical tree structure. The tree can be expanded and closed by clicking on the **plus** and **minus** buttons.

### Sections At key steps in a Script, you may want major branches in the Script logic as well as Script elements that apply to more than one branch. To develop this logic, you can create **Sections** within a Script.\ When in Script Edit mode click the **Add** button and a new section will be added to the end of the Grid. Sections are automatically named **Section1**, **Section2**, etc as they are added. These can be edited to create more meaningful headings as required. The example below shows two Sections have been created and linked to from the Next Step column.

Example of Sections being used within a Master Script

# Copy & Paste Copy and paste functionality From Keyfax version 4.4.8, Keyfax Admins can utilise the new copy and paste feature to speed up the scripting process. All elements of a script (Script Steps, Actions, Script Links, Sections, Next Step) and be copied to the clipboard and pasted within an existing or new topic, as well as external applications such as Word, Notepad etc. ### Copying items Simply select the items to be copied (holding down shift will allow you to select multiple items or use the Select All option), right click and select Copy.

A dialogue window will open to display the items to be copied.

**Copy to Clipboard** - click this to copy the selected items to the clipboard **Do not paste Actions** - only applicable when pasting. Tick this box if you do not want to paste Actions (Tasks, Messages etc) **Cancel** - will close the dialogue window ### Pasting to a script Select the existing or new script you want to paste to and click "Edit". Right click in the location required and select "Paste".

The dialogue window will appear showing the items copied to the clipboard:

Click "Paste to Script" to paste the selected items. {% hint style="info" %} **Note:** Actions will be pasted unless you tick the option "Do not paste Actions". {% endhint %}

{% hint style="info" %} **Note:** Newly pasted items cannot be copied until the Script is saved. This message will appear: {% endhint %}

### Pasting to external application such as Word or Notepad Copy the required items as explained above. Open the required application and paste. The formatting will be displayed as below:

{% hint style="info" %} **Note:** You cannot paste from an external application into a script. {% endhint %} # References Using References to locate items in your scripts. {% embed url="" %} Most toolbars will have a **References** button within the Menu Bar:

Clicking this icon will open a new tab and display all references to the particular entity, e.g. Services, Messages, Priorities etc. so that you can easily discover which scripts use a particular entity. This can be useful when removing items that are no longer required and for checking scripts that use a particular entity before beginning to make changes, in order to be certain of the extent/effect any editing will have. For example, to find out which scripts use a particular Service code, select the appropriate code and click References. The tab will include the number of References found and a list of all References. The occurrence(s) will be highlighted in yellow:

Results of References for a Service Code

In the event that no References exist the Navigation Pane will display the result of "\". ### Find references Clicking the "Find" icon will open the selected referenced item in a new tab.

# Testing your changes How to test changes before releasing them into production. {% embed url="" %} The Test Container page can be launched from the main menu:

The Test Container page provides access to a screen for launching Scripts and testing their operation prior to release to Operators. Some Scripts will have been set up to operate only as ‘test’ Scripts and are only accessed via this facility. The Test page has some different features depending on whether it is run from Diagnostic Scripts or Enquiry Scripts. The Script Test page goes some way to emulate data that echoes what is passed to Keyfax from a host system in the Startup (XML) data file. This may vary between installations/configuration but for Repairs this comprises: * **Restart Script** - option to restart the test container at any point, negating the need to close and re-launch the test container * **Clear Cache** - option to clear cached memory at any point, allowing users to see script changes without having to close and reopen the test container * **User** – logon username * **TenantText** - the Tenant name and address * **Property or Tenant ID** – reference held in host system * **Asset ID** – reference held in host system, not always provided and may be same as property /tenant ID * **Tenancy Type** – code denoting service or client group and links to Script Set code * **Repairs No** - the Script Test allows for a Repairs Number to be passed * **Return to address** - a pre-configured URL to return the user to specific pages upon completion or cancellation of a script * **Test Changes** – if checked, the Script set being run will include any Scripts set as ‘Test’ mode. See screen shot below The Test page for Enquiries includes two additional fields as below: * **LAID** - the Local Authority ID held in the host system * **Scheme** - Reference held in the host system The Script Test allows these elements to be changed to test the effect of such changes as well as, most importantly, to allow testing of Script's functionality. To launch the Scripts, select the appropriate settings and click on Submit. Scripts will then appear and can be run to replicate the Operators actions.

Test Container for Repairs Diagnostics including Scripts in Test mode

On completion of a Script, after the final Submit, the Scripts will generate an export data document (XML, although JSON can also be returned). The details of this file are displayed back in the Script Test tab.

Test page export XML for Repairs Diagnostics

### Flagging up Test Topics When a Topic is set to Test mode, e.g.

you will see the warning icon against the script in Admin Tool's Navigation pane:

# Script Flows Visualise your script structures with script flows. {% embed url="" %} ### Explore, understand, streamline Visual script flows introduced with Keyfax 4.4 allow you explore any script within Keyfax in a visual interactive manner. Script flows are designed to help script authors using Keyfax to better understand the possible paths and outcomes residents or call centre advisors can expect whilst walking through Keyfax scripts. Script flows can also be shared via a regular hyperlink allowing you to share a visual representation of your scripts with key decision makers and stakeholders within your organization. This is helpful during the script creation or review process to gather feedback, inform decisions & help streamline your diagnostics scripts for both residents and call centre advisors. Whenever a script is present in the editing grid, the **Flow** button can be used to display a visual representation of your script:

A typical flow can be seen:

Upon initial load script flows are displayed in a "Pan & Zoom" mode. This "Pan & Zoom" mode allows you to quickly navigate larger scripts by simply dragging to move around the script and holding CTRL/CMD and using the middle mouse button to quickly zoom in or out of the script. Script authors can also toggle into "Selection" mode to select individual script steps to see additional script step properties. A description of each highlighted area from the screen grab above is provided below. {% hint style="info" %} **TIP:** The ability to download all scripts flow into a single document is available via [Reports](/product-suite/admin/reports) {% endhint %} #### Script Flow Tools Using the script flow tools, you can toggle between "Pan & Zoom" or "Selection" modes. You can also reset the visualisation or open the flow visualisation full screen within a new side-by-side window. A brief description of each toolbar option is provided below. **Pan & Zoom Mode**

The Pan & Zoom mode allows script authors to quickly navigate larger scripts by simply dragging to move around the script and holding CTRL/CMD and scrolling the middle mouse button to quickly zoom in or out within the script. **Selection Mode**

The Selection Mode allows script authors to select any script step shown within a script flow to reveal further information about about the selected script step. Selecting a specific script step will also highlight all possible paths through the script from the currently selected script step. Selecting messages or tasks within a script flow will also reveal an abstract or summary of the selected message or task. **Fit to Page**

As the title suggests the Fit to Page option attempts to center and fit the entire script flow within the visible area within Keyfax administrator tools. This can be helpful for larger scripts if you want to quickly reset the view after panning and zooming within a script flow. **Open in new window**

It's can be helpful to have multiple script flows open at once to better understand how certain scripts relate to one another. You can use the Open in new window option to open any displayed script flow within it's own independent floating window leaving you free to continue work within Keyfax admin tools but leave the script flow open for reference. #### The Script Flow The main interactive script flow. All script steps presented within a script flow are uniquely colour coded and have a unique icon to help visually identify the type of script step at a glance. By default script flows open up in "Pan & Zoom" mode allowing script authors to quickly explore scripts. Script authors can also swap to "Selection" mode to select any individual script step shown within a script flow to reveal additional properties & information about the selected script step. #### Details & Options Using the "**Details**" button you can view general information about the current script being visualized.

Using the "**Options**" button you can also easily export the script flow as an `SVG`, `PNG`, `GIF` or `BMP` for viewing offline.

Exporting your Flow to various graphic formats

If exporting a static script flow is not enough you can also optionally share a link to the fully interactive web based script flow via a temporary, private, unique URL. This can be helpful to easily share script flows with key stakeholders or business owners. You can see an example of the share dialog below\...

### Make Better Business Decisions #### Understand Outcomes Script flows make it easier to understand the possible outcomes of a Keyfax script by providing a more visual colour coded representation of any Keyfax script. This colour coding helps you quickly identify at a glance the priority, tasks and / or services that would be associated with the outcome of any Keyfax repair or enquiry. #### Understand the User Journey Using Selection Mode within any script flow and selecting a specific script step will highlight all possible paths through the Keyfax script from the currently selected script step. This makes it easy to visually understand the journey tenants or Operators could take through the Keyfax script until completion. We hope by making it easier for script authors to understand the user journey through scripts, script authors can have more confidence they are developing the most streamlined, useful, user-friendly scripts. You can see an example of this below\...

### Script Flow Legend A guide to Script Flow colours, icons and labels.

# Script Entities Entities are the various elements that form the building blocks of your scripts. Entities are the various elements that build a script, either as a Question to gather information or dictate the direction of the script, or as an Action which would be the result of a question being answered in a particular way. Each type of entity will need to be created before it can be added to a script (although using Quick Editing you can dynamically build components whilst you script away). To access Entities, select the required Entity from the Main Menu:

Once you are in Edit mode, the different types of entities can be selected from the ‘**Item Type**’ of the Navigation Pane:

### See Also * [Databoxes](/product-suite/admin/entities/databoxes) * [Questions](/product-suite/admin/entities/questions) * [Asset Data](/product-suite/admin/entities/asset-data) # Databoxes An introduction to Databoxes within Keyfax. Databoxes are used in scripts to capture, manipulate and evaluate data. During the process of designing and creating scripts, data are captured when entered by the user. This data may be used in a subsequent task or may be used to control the path taken within the Scripts. This data capture and evaluation is performed using Databoxes. A Databox can simply be viewed as a ‘box’ which stores information. This ‘box’ can have data stored in it (write), and the same data can then be pulled out of it (read). This means the Administrator does not have to worry about the technicalities of locating where the data is physically stored and how it is accessed. Data can be manipulated or interrogated by use of [Databox Expressions](/product-suite/admin/databox-expressions). ### Databox Types These are the six types of Databox and how they relate to the manipulation of data.

Databox Type	Description
/pages/a6pMy2JNbeUuD7lfRNzg	A Script Data Databox is used to hold data gathered within a script e.g. an answer to a question. The information being captured or manipulated in Keyfax can be ‘written’ to a Script Data Databox and re-used at a later point within the Scripts. Typically, Script Data Databoxes are used to store data that is to be integrated into a subsequent task (such as an email or letter).
/pages/xy0eIkQyUKwQRqwxBOG7	An SQL Query* Databox is linked to a database, either the Keyfax database or an external database via a SQL query. Because of this, SQL Query Databoxes are known as ‘Read Only’. This means that they are only used to pull data from a database and not to write data back into the connected database. Queries can use Views or Stored Procedures.
/pages/Pvqzs92Syc71OxlaAosu	An Import XML Databox is linked to the information given by the Host System to Keyfax when it is launched. Examples of the type of information passed are TenantID, AssetID, Tenant Address and UserID. A typical breakdown of the elements available in your Startup XML can be obtained from your Keyfax Account Manager or by reviewing the Test page within the administration console.
/pages/J4BSXyjj7z5EfGSqlM96	An Export XML Databox is linked to the information that is passed back to the Host System by Keyfax after clicking the ‘Submit’ button. Depending on the path taken a Script, the information held in the Export XML can vary considerably. An Export XML Databox can be used to change the data passed back to the Host System. A good example of this would be the setting of a Trade or Location Code following the diagnosis of a repair in Keyfax.
/pages/DqoitXhIFSvPNXVtJNPk	A System Values Databox is linked to information associated with the computer running Keyfax. A typical example of this would be the current time/date. These are sometimes seen as ‘Keyfax’ Databoxes.
/pages/wi4CWLiR3UJCcAaw9rPk	A Company Data Databox usually contains a list of set values that can be used within the Scripts. An example of this would be a list of email addresses set against their counterpart user names.

{% hint style="info" %} **NOTE** For SQL Query databoxes normally these queries will be supplied by your host system vendor, IT support or Omfax Systems support. {% endhint %} ### Accessing Databoxes Using [Keyfax Administrator Tools](/product-suite/admin) open the Databoxes tab by clicking the main menu's **Databoxes** button as shown below\...

Select the type of Databox you wish to create or, select an existing Databox to edit from the left-hand menu. If you have already selected a Databox, you can click '**Add**' to create a new one. ## Help is always at hand! Databoxes can sometimes appear a little daunting and that's why help is always available when you need it via Keyfax Administrator Tools. Hover over topics in the '**Help with Expressions**' pane to learn more and see examples directly within Keyfax Administrator Tools....

If more information or examples are required, click the keyword / item and a popup window will appear. ### See Also * [Databox Examples](/product-suite/admin/databox-examples) * [Databox Expressions](/product-suite/admin/databox-expressions) # Script Data Using Script Databoxes in your scripts {% embed url="" %} Here we are editing an existing Databox:

### Properties **Group** - when displayed in the Selection List, Databoxes are arranged into groups. Select a group from the drop down list to add the Databox to an existing group or type in a new group name to create a new group. **Name** – a descriptive name for the Databox. If you can, make this a meaningful description to enable easy identification in your scripts.. **Empty bookmarks allowed** – check this box if the Databox can be used in a Task or Message without being required to hold a value. **Description** - a short description of the Databox. This is displayed in the Databox Selection list in and is searchable using the filter. **Expressions** – these are covered in-depth in the [Databox Expressions](/product-suite/admin/databox-expressions) section. **Test** – [test the Expressions](/product-suite/admin/entities/databoxes/testing-databoxes-and-expressions) setup against the databox. # Host-specific notes Managing Script Data Databoxes for different hosts out there... ### MIS-AMS ActiveH When creating a **Script Data** Databox, an additional **'For MIS**' checkbox is displayed as highlighted below:

The Script Data Databox in an MIS integration

By checking this box, this 'publishes' the Databox to the ActiveH system where **User Defined Element (UDE)** mapping can be defined to pull resultant diagnostic data returned from Keyfax onto forms in CRM. # SQL Query Using SQL Query Databoxes in your scripts ### Introduction SQL Query Databoxes are powerful and can return a variety of information from a host system's database(s) which could prove useful in the course of a diagnostics script either by controlling the flow, minimising the number of questions asked or for displaying relevant information that assist the call handler or end user alike. For example, they are often used: * in Startup scripts to decide which set of scripts to use, e.g. General, Leasehold, Communal * to provide additional tenant/caller profile data, e.g. date of birth, vulnerability indicators, warnings. no. of bedrooms * to provide additional asset related information, e.g. heating type, in defects, void property, repair responsibilities * historical information e.g. previous repairs or enquiries * present rent account information in Messages SQL Queries can be issued against any configured/compliant database in order to return a single row of data which internally is held as an XML packet and can be referenced by Expressions, e.g. '**Item**' (see example below). Select an existing SQL Databox or click **Add** to create afresh.

### Properties **Group** - when displayed in the Selection List, Databoxes are arranged into groups. Select a group from the drop down list to add the Databox to an existing group or type in a new group name to create a new group. **Database** - the database drop-down list specifies which database connection the SQL Query Databox will access. By default the Keyfax Database is available. If you are wishing to query other SQL databases these will need to be added by Support, to do this read-only login credentials will be needed, along with database name and location. The necessary permissions will also need to be established. **Name** – a descriptive name for the Databox. If you can, make this a meaningful description to enable easy identification in your scripts.. **Empty bookmarks allowed** – check this box if the Databox can be used in a Task or Message without being required to hold a value. **Description** - a short description of the Databox. This is displayed in the Databox Selection list in and is searchable using the filter. **SQL Query** – This is where the SQL query is added. The Query normally includes a reference to another Databox, for example, a Databox obtaining the AssetID of a property. The maximum length of the query is around 1900 characters; this varies depending on the selected database name and the possible references to other Databoxes. Longer SQL queries should be set up as Stored Procedures in the database with EXECUTE permissions granted to the role: OMFAXROLE. The Databox SQL can then simply execute the stored procedure with the appropriate parameters. {% hint style="info" %} Note that there is no need to specify a **database name** as part of your SQL query. For example, in the statement: **SELECT PropertyType FROM PropertyDb.dbo.Assets** mention of '**PropertyDb**' should be omitted. By selecting the correct Database (from the dropdown list) when editing the SQL Databox, the Query will be executed against the chosen database. {% endhint %} **Test** – [test](/product-suite/admin/entities/databoxes/sql-query/testing-sql-query-databoxes) the SQL and Expressions setup against the databox. **Expressions** – these are covered in-depth in the [Databox Expressions](/product-suite/admin/databox-expressions) section. Typically, the Expression Item will be used to access individual columns returned by the query. In the example above you'll see four [Item](/product-suite/admin/databox-expressions/text-expressions#item) Expressions which point at **Name**, **Email**, **Telephone** and **TelephoneExt** which match up exactly with the column names returned. {% hint style="warning" %} All Databoxes are re-evaluated **every time they are referenced** either directly or through an Expression; for SQL Databoxes this will re-run the SQL query and could be inefficient. If it is known the query will always return the same result and the query returns multiple values or is referenced several times in the script then it is better to use a Databox-Write to store the original result into a separate [Script](/product-suite/admin/entities/databoxes/script-data) Databox and use the latter for all subsequent references. {% endhint %} ### In the above example... The example retrieves four items, e.g. the user's **Name**, **Email**, **Telephone** and **Extension No**. The key piece of data (used in the WHERE clause) is '**{Import.UserCode}'** that has been supplied by the host system. As you can see in the Expression list, each element of data can be referenced separately. To [ensure the SQL query and its Expressions are working](/product-suite/admin/entities/databoxes/sql-query/testing-sql-query-databoxes), click **Test.** {% hint style="info" %} If an SQL query returns just a **single column**, this will not result in an XML packet and the value of the Databox will be the value returned and no Expression is required. {% endhint %} ### Handling multiple rows of data Since 4.4.8 of Keyfax it is now possible to handle multiple rows of data with both SQL and HTTP databoxes. For HTTP databoxes this is built in by default. For SQL databoxes - so as not to change the operation of existing scripts - the multi-row support requires an opt-in on the SQL databox definition page by selecting 'Multiple records in result allowed'. {% hint style="warning" %} For 4.4.7 and earlier: If an SQL Query returns **more than a single row**, this is considered an error and the SQL query should be amended to ensure this cannot happen. It is good practice to always test for this eventuality in which case you will see this message: '**Unable to process multiple rows returned**'. Depending on the context, there may be various techniques to restrict results to a single row; typically this may use the '**TOP n**' clause. For example, to return a single row containing the current balance for the most recent tenancy record:\ \ **SELECT TOP 1 CurrentBalance FROM Tenants WHERE TenantID = {Import.CallerId} ORDER BY TenancyStartDate DESC** \ \ Having said that, there are exceptions where multiple rows *can* be returned but the results must be coerced into an XML packet; this will require more specialist knowledge - see the section [Handling multiple rows from SQL](/product-suite/admin/best-practices/handling-multiple-rows-from-sql). It should also be taken into consideration that if an SQL Query doesn't return anything then any Expressions against it will not run. {% endhint %} # Testing SQL Query Databoxes Ensuring your queries work properly This is best shown in an example. Once your SQL is crafted and appropriate Expressions have been added, click the **Test** button. As the description says, this query will return all columns from an Asset table. A number of Expressions will test or retrieve the returned data.

Extracting data (here, from an external database connection)

This will present a dialogue as shown below. In this example, you can see the DataBox **Import.AssetID** needs to be supplied; you should enter any test values and click **Evaluate**. In this case, **100** has been entered and in the **Results** section you can see the full result (which is provided in the form of an XML snippet) and the accompanying results of the Expressions:

{% hint style="info" %} Caution: it is important that your SQL queries return a single row of data - [read more here](/product-suite/admin/entities/databoxes/sql-query#multiple-rows-of-data). {% endhint %} # HTTP Request Using HTTP Query Databoxes in your scripts ### Introduction HTTP Query Databoxes can be used to retrieve information from any web API. They are also capable of updating data in certain environments that supply a web API to do so. To demonstrate the functionality this page will show how to produce this message based upon the HTTP APIs offered by Geoapify (a paid for service that provides local area information around the globe - see here: ):

### Creating the HTTP Databoxes Two HTTP databoxes are required to get the data for the above message box. This is due to the design of the Geoapify API. The hospital search API requires a 'Place\_id' which is defined within Geoapfify; this place\_id can only be accessed by providing the tenant's postcode to the Geoapify API. So: * The first HTTP databox gets the place\_id by passing Geoapify the tenant's postcode. * The second HTTP databox passes the place\_id to Geoapify and gets back the list of hospitals in the local area (equally this could be dental surgeries or supermarkets) The first databox looks as follows (with the apiKey blanked here - the Geoapify website will provide you with an API key when an account is created).

The second databox references the first, utilising the returned place\_id in it's HTTP URL:

{% hint style="info" %} In previous versions of Keyfax it was not possible to 'chain' calls to SQL databoxes by nesting references to other bookmarks within the SQL - but in 4.4.8 these rules have been relaxed to make multi-call SQL or HTTP databoxes a possibility. {% endhint %} ### Creating the Message The message is a normal message - but as we are creating HTML elements from the output of a databox (in this case a list using 'ul' and 'li' HTML elements) there's a little bit of scripting trickery to take care of. The 'HTML Source' view of the message should be set to the following: ```

Local services:

{HTTP.NearestHospitals.Hospital}

``` ### Overview ### Properties **Group** - when displayed in the Selection List, Databoxes are arranged into groups. Select a group from the drop down list to add the Databox to an existing group or type in a new group name to create a new group. **HTTP Verb -** a the 'verb' is part of the HTTP protocol specification. Common verbs to use are: GET, POST, PUT, UPDATE, OPTIONS - see for the full list **Name** – a descriptive name for the Databox. If you can, make this a meaningful description to enable easy identification in your scripts.. **Xpath Record Identifier** – all data retrieved from an HTTP databox is converted to XML (even JSON responses), this setting allows Xpath to be used to identify the root element of each record of data in a multi-record response. **Description** - a short description of the Databox. This is displayed in the Databox Selection list in and is searchable using the filter. **URL** – The URL to call when this databox is executed - this field can incorporate references to other databox expressions to pass URL parameters taken from, for example, the startup XML. **Headers -** some HTTP web api servers require authorisation headers to be callable, those authorisation and authentication headers can be placed here. In some cases and initial HTTP call to retrieve a token (via one databox) is required before that token is used in a second HTTP databox to full authenticate against the service. Headers are also used to specify the format of the incoming Body of the HTTP request - please see an HTTP tutorial for full details. **Body -** the HTTP body is usually only passed in a POST or PUT (HTTP Verb) request but can be present for any call. If the aim of the request is to update a server with information, that information is almost always POST'ed in the body section of the request in either JSON or 'Forms Encoded' format. Once again, please see an HTTP tutorial for full details. **Test** – [test](/product-suite/admin/entities/databoxes/sql-query/testing-sql-query-databoxes) the HTTP request and Expressions setup against the databox. **Expressions** – these are covered in-depth in the [Databox Expressions](/product-suite/admin/databox-expressions) section. Typically, the Expression Item will be used to access individual 'columns' of data returned by the query. In the example above you'll see a rowmerge Expression which merges the 'formatted' field returned from the HTTP request into a single string which is then displayed by the message definition in script. {% hint style="warning" %} All Databoxes are re-evaluated **every time they are referenced** either directly or through an Expression; for HTTP Databoxes this will re-run the HTTP query and could be inefficient. If it is known the request will always return the same result and the request returns multiple values or is referenced several times in the script then it is better to use a Databox-Write to store the original result into a separate [Script](/product-suite/admin/entities/databoxes/script-data) Databox and use the latter for all subsequent references. {% endhint %} ### Handling multiple rows of data Since 4.4.8 of Keyfax it is now possible to handle multiple rows of data with both SQL and HTTP databoxes. For HTTP databoxes this is built in by default. For SQL databoxes - so as not to change the operation of existing scripts - the multi-row support requires an opt-in on the SQL databox definition page by selecting 'Multiple records in result allowed'. {% hint style="warning" %} For 4.4.7 and earlier: If an SQL Query returns **more than a single row**, this is considered an error and the SQL query should be amended to ensure this cannot happen. It is good practice to always test for this eventuality in which case you will see this message: '**Unable to process multiple rows returned**'. Depending on the context, there may be various techniques to restrict results to a single row; typically this may use the '**TOP n**' clause. For example, to return a single row containing the current balance for the most recent tenancy record:\ \ **SELECT TOP 1 CurrentBalance FROM Tenants WHERE TenantID = {Import.CallerId} ORDER BY TenancyStartDate DESC** \ \ Having said that, there are exceptions where multiple rows *can* be returned but the results must be coerced into an XML packet; this will require more specialist knowledge - see the section [Handling multiple rows from SQL](/product-suite/admin/best-practices/handling-multiple-rows-from-sql). It should also be taken into consideration that if an SQL Query doesn't return anything then any Expressions against it will not run. {% endhint %} # Testing HTTP Request Databoxes Ensuring your queries work properly HTTP request databoxes can be tested in much the same way as SQL Query databoxes. The same test dialog appears with the same prerequisites and operation (the only difference being is that an HTTP request is being made rather than a SQL query being executed). For more details please refer to the [Testing SQL Query Databoxes](/product-suite/admin/entities/databoxes/sql-query/testing-sql-query-databoxes).

{% hint style="info" %} Remember: HTTP requests can timeout. If the server is there but not responding quickly or correctly then an HTTP databox can take up to 30 seconds to timeout. In these situations the test dialog will take up to 30 seconds to come back with a result. {% endhint %} # Import XML Pulling data into your scripts from the calling host {% embed url="" %}

**Group -** when displayed in the left hand menu, Databoxes are arranged into groups. Select a group from the drop down list to add the Databox to an existing group or type in a new group name to create a new group. **Name –** a descriptive name for the Databox. Use a meaningful description to identify the Databox in relation to its purpose for ease of recognition. **Empty bookmarks allowed –** check this box if the Databox can be used in a task or message without being required to hold a value. If they are not allowed, the operator will be prompted to compelte them before sending the email or printing a letter. **Description -** a short description of the Databox. \ \ **Read Only** – check this box if the Databox will only be available to be read from when used within the Scripts. **XPath** - the XPath details the node/element of the Import XML that is to be read from by the Databox. This has to be detailed in standard XPath format. {% hint style="info" %} XPath is a language that describes how to locate specific elements, attributes or processing instructions in an XML document. It allows you to locate particular content within a document. XPATH treats an XML document as a logical ordered tree. XPath statements can get very complex but in the context of Databoxes, this shouldn't get more complicated than **NodeName/NodeName/text()**, e.g. **Startup/AssetID/text()** {% endhint %} **Test** – if your Databox owns any Expressions, this is how to confirm that they are set up correctly and will work whatever data is passed to it, including null/empty values.\ \ **Help with Expressions** – Help on constructing expressions to manipulate the data, which also includes examples of specific expressions and guidance on where to find extra help. # Export XML Returning the results of your diagnostic to the calling host

**Group -** when displayed in the left hand menu, Databoxes are arranged into groups. Select a group from the dropdown list to add the Databox to an existing group or type in a new group name to create a new group. **Type** – select from the dropdown list to specify how data is to be exported into the XML. The default options are: * **General -** Standard exporting of data into a node of the export XML. * **Service** - Exporting into a Service Code node in the export XML. * **Custom** - Creates a ‘Custom Key’ node in the Export XML. This is primarily used for backwards compatibility and for specific host systems that require data exported in a ‘Custom Key’ format. * **Audit -** Used for exporting information that requires being audited or logged by Keyfax. **Name** – a descriptive name for the Databox. Use a meaningful description to identify the Databox in relation to its purpose for ease of recognition. **Append ‘recorded’ data** - checking this option ensures that any data exported by the Databox is appended to any existing data. The data exported will be delimited by a semi-colon.\ \ **Empty bookmarks allowed –** check this box if the Databox can be used in a Task or Message without being required to hold a value. If not allowed, any empty bookmarks will present to the advisor and values must be entered.\ \ **Read Only** – check this box if the Databox will only be available to be read from when used within the Scripts.\ \ **XPath** - the XPath details the node/element of the Export XML that is to be written to by the Databox. This has to be detailed in standard XPath format. {% hint style="info" %} XPath is a language that describes how to locate specific elements, attributes or processing instructions in an XML document. It allows you to locate particular content within a document. XPATH treats an XML document as a logical ordered tree. XPath statements can get very complex but in the context of Databoxes, this shouldn't get more complicated than **NodeName/NodeName/text()**, e.g. **Fault/Job\_Code/text()**. {% endhint %} **Test** – if your Databox owns any Expressions, this is how to confirm that they are set up correctly and will work whatever data is passed to it, including null/empty values.\ \ **Help with Expressions** – Help on constructing expressions to manipulate the data, which also includes examples of specific expressions and guidance on where to find extra help. # System Values What they are and how to use them A System Values Databox can be one of a number of different types according to the System Value selected on creation of the Databox.

**Group -** when displayed in the left hand menu, Databoxes are arranged into groups. Select a group from the dropdown list to add the Databox to an existing group or type in a new group name to create a new group. **Name** – a descriptive name for the Databox. Use a meaningful description to identify the Databox in relation to its purpose for ease of recognition. The value returned for each **System Value** is described in the sections below. **Date** - This returns the current date and time in the format "Apr 06 2018 09:00:00". **CallRef -** This returns the Order Id reference where a Service (SOR code) has been generated by the script. It can only be used as a Task bookmark as the Order Id is not generated until after the system results script and only if any Service has been generated by the script. **Services -** This is only available for use as a bookmark in Keyfax Tasks and returns details of all Services recorded in a script in an XML format as in the sample below. This is typically used in conjunction with a Transform expression to format the results into an html table for inclusion in an email. {% hint style="info" %} Note: specific elements and names may vary according to individual integration requirements. Other templates are available such as Services2SMV to include the Standard Minute Value. Please contact Omfax Systems if you have any custom requests. {% endhint %}

Transform Example:

**ScriptPath -** This returns the current list of questions and responses formatted as required for each specific host Housing Management System. This is typically only of use in scripts when the export ScriptPath is returned as plain text or html. It is typically only used in 'stand-alone' online configurations to email the online Q\&A responses for advisors to manually process the request. Prior to InterView v4.1.4.16, the ScriptPath System Value is only available for use as a Task (or message) bookmark. **TaskCode** - This should only be used in a task template and returns the task action code for the 'current' task being processed. This is typically used to place the task code on the template as a visible 'stamp' to identify the source of a letter or email after it has been sent. TaskId This returns the ContactView Task Id reference and is only relevant for installation with ContactView configured (requires a separate license). It can only be used as a template bookmark as the ContactView Task Id is not generated until after the system results script. **TotalCost -** This returns the total cost based on the Services generated by a script. The total cost is based on the recorded services and quantities with a configurable fee plus VAT. This is formatted to 2 decimal places. # Company Data AKA 'Fixed Text' data. {% embed url="" %}

These Databoxes (abbreviated as '**CO**') are used to store any text that can be used in multiple places across your scripts. In the example above, a number of reasons for justifying priority changes are represented by two character codes. Another example would be that within your organisation you may have a number of key email addresses which can be stored in Company Data Databoxes. As 'fixed text' Expressions cannot be applied to these values. **Group -** when displayed in the left hand menu, Databoxes are arranged into groups. Select a group from the dropdown list to add the Databox to an existing group or type in a new group name to create a new group. **Name** – a descriptive name for the Databox. Use a meaningful description to identify the Databox in relation to its purpose for ease of recognition. # Testing Databoxes & Expressions Ensuring everything works as expected! Expressions can be created against all types of Databox except Company Data (aka Fixed Text). Wherever you create Expressions, a Test facility is provided. In essence, it will allow you to evaluate what happens when certain data is encountered by the Databox. When you click **Test** (in the Editing pane, not the main menu) a popup window will appear where you can supply a value for the Databox by entering a value. Then click **Evaluate**. Any errors will be reported but, if all is well, you will see the results of the Expressions:

### Here's an idea... You might find that it's a useful idea to have a 'scratch' Databox whose only purpose is to house a number of example Expressions which you can use to test and confirm that the (sometimes esoteric!) formatting is correct. Here's such a random selection:

# Databox Read Pulling information out of a Databox Data held in a Databox can also be ‘read’. Reading from a Databox allows the data to be used elsewhere. For example, it may be data that is to be: * used in a Message or Task * read so that the data can be manipulated and then written to another Databox To read data from a Databox, edit your script and select the **Databox - Read** option from the Item Type list:

Databox - Read in the dropdown item list

The list of Databoxes that can be read from is displayed. Select the Databox and drag it onto the Script to the position required. ### **Example** In a System Startup script, we will use a Databox to determine if your scripts are ever run outside of normal hours in which case, a different Script Set will be loaded. Firstly, edit the System Script '**Startup**':

Locate the **SystemValues.OOH Check** Databox. This is included as part of the the Model content; if it doesn't exist, create one, add the Expression below and tick the '**Cond**' checkbox. {% hint style="info" %} By ticking the 'Cond' checkbox, this Databox provides a Conditional assessment where the script logic can determine if an Expression results in **True** or **False** and the script flow can deviate accordingly. Whenever you drag a Databox marked as '**Cond**' onto your grid, it will insert an '**Otherwise**' step to manage the script flow. See this in action below\... {% endhint %}

The Out of Hours Check Databox and Expression

Having located the Databox, expand it by clicking the small chevron and you'll see the Expression '**Between 0800 and 1800?**'. Drag this onto the script grid. {% hint style="info" %} If your script already has content and you wish to position the Databox at the very **top**, you will need to hold the **SHIFT** key down as you drag the Databox across. {% endhint %}

The Databox dragged into the Script grid

Because this is a Conditional expression, you can choose what action to take if the Expression is **true**. In this case, we will be doing another Databox Read by dragging '**Company.Script Set Code.Out of Hours**' into the script; this represents a fixed value, in this case '**OOH**':

To complete the script, add a Databox **Write** to store the value '**OOH**' in the Databox **Import.Tenancy** (for Repair Diagnostics, this is normally used to determine which Script Set to load at Startup. So the finished script looks like this:

# Databox Write Using Databoxes - writing to a Databox To write data to a Databox, open the Script in Edit mode and select the **Databox - Write** option from the Item Type drop down list in the Navigation Pane:

Script items showing the Databox Write option

The list of Databoxes that can be written to, is displayed:

Select the required Databox and drag it onto the Script Step line that would return the data you wish to capture. In this example, the question '**What type of basin is it?**' has two options; if the Databox **Additional\_Info** is dragged into *both* possible answers, when chosen by the operator, the text '**pedestal basin**' or '**basin on brackets**' will be written to the Databox:

Drag and drop of a writable Databox into a Script

In the case of **Additional\_Info**, this is an **Export** Databox. The Results page normally displays this field alongside others:

# Databoxes in Messages & Tasks Learn how to use Databoxes within messages and tasks. A ‘**Databox – Read**’ can be used to display the contents of a Databox within the body of a Message or Task. When editing the body text of a Message or Task, the list of available Databoxes is displayed alongside the editor. ### Tasks

Simply position the cursor and click the '**+**' sign or just drag and drop the Databox into the body. ### Messages

The above example uses a telephone number stored in a Company Databox:

Company (Fixed text) Databoxes holding telephone numbers

...with the end result:

# Questions What they are and how to use them. {% embed url="" %} Questions are used in your Keyfax scripts to obtain information about an enquiry/diagnostic. They form the main steps in a Script for processing the enquiry in order to obtain an accurate diagnosis in response. The Navigation Pane shows the Question Selection, containing a list of the questions already built.

Adding a new question via Keyfax Administrator Tools

### Question Selection Questions can be created at either **System** or **Master Script** Level for use in the relevant type of script. To appear in a Script Set, a question must be created within the given category, held at Master level.

**Level** – displays a drop down list of System and Master: * **System** - lists all Questions set up at the System level. These are **available to all System Scripts** and are useful for functionality that is shared by all Scripts. * **Master** - lists all Questions set up at Master level. These are **available only within the category they are assigned to**, when used in Script Sets. Other ways to tailor the list of Questions: * **Filter** - type in characters to search for Questions with the specific text. As you type into the Filter the list will update with Questions matching the Filter criteria selected. Click the Category name to view its Questions. * **Unused** - shows any unused questions. ### Question types The supported question types are... * [Address](/product-suite/admin/entities/questions/address) * [Checklist](/product-suite/admin/entities/questions/checklist) * [Date/Time](/product-suite/admin/entities/questions/date-time) * [Numeric](/product-suite/admin/entities/questions/numeric) * [List](/product-suite/admin/entities/questions/list) * [Text](/product-suite/admin/entities/questions/text) * [Dynamic Lists](/product-suite/admin/entities/questions/dynamic-lists) * [File Upload](/product-suite/admin/entities/questions/file-upload) * [External Forms (eForms)](/product-suite/admin/entities/questions/external-forms-eforms) * [Video Call](/product-suite/admin/entities/questions/video-call) To add a new question, you must first select a Category where you wish to store the Question. The list of question types will not be enabled until a Category selection is made:

The Question Type list (disabled before a target Category is chosen)

{% hint style="info" %} **NOTE** When creating a question it must be created within the category (Master) you wish to use it, otherwise it will not appear at script runtime. If necessary, drag/drop the question in the navigation pane to the correct category. {% endhint %} ## **Moving / Copying Questions** Once created Questions can be moved and/or copied between existing Categories. You may wish to replicate an existing Question from another Category, or to move a Question that has been created in the wrong Category: \ \ To do this, click to select the Question that you want to move/copy and use either of the following options: 1. Drag the question into the new category (this should show the pointer icon with no '+'). 2. Force the question to be copied by holding the Ctrl key (this should show the pointer icon with '+'). 3. The question will be automatically copied if it cannot be moved i.e., if the administrator is not in [Exclusive Mode](/product-suite/admin/exclusive-mode) or the Question is already referenced in a Script (this should show the pointer icon with a '+'). # Address Question type used to capture address data. {% embed url="" %} This question type allows the input of an address, or components of an address into the system:

### Properties **Admin Display** - a descriptive name to identify the Question within the system.\ \ **Operator Display** - the Question text as displayed to the Operator.\ \ **Record value** - if checked the value will be added to the Recorded text (breadcrumb).\ \ **Fields** - the fields required for use and to display within the Question. Select an item by checking the relevant box/boxes. Select whether or not the field is to be mandatory by clicking the required box. ### User Experience The Address question presents to the operator/end-user as below (this is showing *all* possible fields):

Address question showing all available fields

### Accessing Address data Data gathered by Address questions are available for use in Databoxes where Expressions can access individual items. Data is actually held in a snippet of XML and items held can be accessed using the [Item ](/product-suite/admin/databox-expressions/text-expressions#item)Expression. All the possible fields gathered by an Address question in this example: ```xml Mr SG Miller Sales Bath Salts Ltd 132 High Street Fernway Exter Devon EX11 00X 07967 377162 1332 N/A SGM@GMAIL.COM 01395 377169 Stephen ``` # Checklist The question type allowing multiple option selections. {% embed url="" %}

### Properties **Admin Display** - a descriptive name to identify the Question within the system. **Operator Display** - the Question text as displayed to the Operator. **Asset Data** – see [this page](/product-suite/admin/entities/asset-data) for more details. **Mandatory** - checking this prevents the Operator from continuing without completing the question. **Record value** - if checked the value will be added to the recorded text. ### Checklist Items **Display Prompt** – the text of the option to be displayed to the Operator. **Return Value** – the text to be entered that can be stored in a Databox and/or added to recorded text (breadcrumb). If this is left blank the ‘Display Prompt’ will be entered. ### Re-ordering, adding or deleting items Controls on the right hand side allow you to change the order of the prompts and Add or Delete items. Remember you have to be in **Exclusive** mode to Delete items. ### User Experience The Checklist question presents to the operator/end-user as below:

# Date/Time Describing the Date / Time question type. {% embed url="" %} This question type allows a date and optionally a time to be entered.

### Properties The following properties are available: **Admin Display** - a descriptive name to identify the Question. **Operator Display** - the Question text as displayed to the Operator/end-user. **Asset Data** – see [this page](/product-suite/admin/entities/asset-data) for more details. **Record value** - if checked the value will be added to the recorded text. **Mandatory** - checking this prevents the Operator from continuing without completing the question. **Date** - set if this is a date range. **Time** - Set 12 or 24 hour clock. **Min date** **= today +/-** - Set start of the date range relative to today in years, months, weeks or days. **Max date = today +/-** - Set end of the date range relative to today in years, months, weeks or days. ### User Experience

# Dynamic Lists Lists powered by SQL and how to use them {% embed url="" %} This question type allows a list of options to be dynamically presented to the operator by using a key value, either passed to Keyfax in the Start-up XML (for example TenantID, AssetID, Tenancy) or picked up within the scripts and stored in a Databox. A value is returned dependant on the operator’s selection, which can in turn be written to a databox for subsequent use.

### Properties **Admin Display** - a descriptive name to identify the Question. **Operator Display** - the Question text as displayed to the Operator. **Display all items** – If checked then display all items on the page, if not checked then the operator will need to scroll if there are more options than defined in the “Scroll items per page” value. **Scroll items per page** – number of items displayed before the operator needs to scroll. **Database** – Select which database is being queried **SQL Query** – Build the SQL to query the selected database **Test** – Test the SQL entered in SQL Query **Value column** – column of the table in the database from which a value will be returned dependant on the option selected by the operator. This field is case sensitive. **Record value** - if checked the value will be added to the recorded text. **Display column(s)** – Column of table in the database from which a value will be displayed to the operator. This field is case sensitive. {% hint style="info" %} Both the Value and Display column fields are case sensitive. Entering a field name with the wrong case (i.e. one that does not match the result data coming from the SQL or the databox, whether SQL or HTTP) can result in the dynamic list question displaying no answer options. {% endhint %} ### Testing your Dynamic List Clicking **Test** will present a dialogue showing the results of the SQL query. In this case, the selection of '**Black**' will return a code of '**4**', for further use in your scripts:

### User Experience This shows 5 rows returned by the SQL query with a scroll bar added

The code representing the choice made can be written to a Databox for subsequent use, .e.g.

# Testing Dynamic Lists Ensuring they work as expected! When creating/editing a Dynamic List, clicking **Test** will present a dialogue showing the results of the SQL query. In this simple example, the SQL Query returns all Keyfax users that belong to the **HELPDESK** group. It appends the Surname to the Forename (column name is **Name**) and also displays the **EmailAddress** column. It's the email address that we want to pass on to another Databox for use elsewhere in the scripts:

# Dynamic List Examples Various examples showing how to use the Dynamic List question type within Keyfax. Dynamic Lists can be used to present any data from a SQL Server database during a Keyfax script. On this page we provide a few common examples to help you get started with Dynamic Lists. ### Joining Multiple Columns into a single Dynamic List You may have data in different table columns that you wish to display as a single list via a Dynamic List question type. To acheive this you can use the SQL `UNION` operator as demonstrated below. In this example we'll query for 3 phone numbers for the current caller from different table columns and display found phone numbers within a Dynamic List. You can see the SQL below\...

The results are shown below. In this example only 2 phone numbers were found...

#### Handling NULLs If your columns allow and contain nulls you may need to filter out the null values so these don't appear in the Dynamic List as shown below\...

# External Forms (eForms) Extending script functionality {% hint style="info" %} Note that some specialist knowledge is required in order to integrate eForms with your scripts. {% endhint %} External HTML forms can be seamlessly integrated into your scripts by using an iFrame to present additional information to the user allowing the user to interact with the form entering or selecting data to be returned to the script. Typically, these forms will be dynamic web pages i.e. dynamically generated with a server-side technology such as ASP.Net, JSP, PHP etc.\ \ These forms will accept request parameters to select the information to be displayed and to determine their behaviour. The request parameters should only contain simple key identifiers and conform to the usual browser url requirements. The input parameters are not intended for passing large data items and should typically contain < 100 characters. A simple mechanism is provided for forms to pass data back to integrate with your scripts as described here. Forms can be hosted anywhere (with an appropriate connection) and do not have to reside on the same Keyfax web server. Data is returned to the script by posting the form data to a URL on the Keyfax website. A script-specific url is passed to the eform as an additional request parameter and the eform must dynamically update the HTML form action with the supplied value when presenting the form to the browser. E.g. in ASP.Net this would be as below: ```

" method="post"> ``` As posted data there is no restriction on the number or size of fields returned however it should be considered how this information is to be used within the script and it is not expected that large volumes of data will be returned. The Keyfax form return url will receive the posted data (formatted into xml for multiple form fields) for the current script step. This will typically record the result into a Script Databox with a Databox Write action. The script will then replace the iframe with the next script step as appropriate. To create an eForm, select 'External Form' on the Question type menu (if this option is not listed, please contact Support as the functionality may be disabled): You will then be prompted to enter the fields as below:

### **Properties** **Name** - The internal name of this eForm **Display** - Optional text to be displayed above the eForm **Url** - The target address to use for the eForm. Note this can include Databox bookmarks (right click in field to show popup menu of bookmarks). **Query string** - Optional list of query string arguments, as required. Note this can include bookmarks (right click in field to show popup menu).\ \ For a more Technical Description of how to use eForms, [click here](http://dev.touch-base.com/helpconsole2010/Keyfax%20Help/default.aspx?pageid=eform_technical_details). # External Forms - Technical Expanding on the topic of eForms There follows a simple example eForm (ASP.NET i.e. **.ASPX** file extension) which accepts a single parameter **p1** and returns items **field1** and **field2**. {% code lineNumbers="true" %} ```aspnet <%@ Page Language="VB" %>

Processing input p1=<%= Request.QueryString("p1")%>

Field 1

Field 2

``` {% endcode %} The returned data can be written to a Databox as normal. Individual items can then be accessed by use of Expressions, e.g.:

# File Upload How to handle uploading of images and other file types {% embed url="" %} To upload a file (typically a photo) which can subsequently be attached to emails or returned to the host system, select 'File Upload' from the Question Type menu (if this option is not listed, please contact Support as this functionality may be disabled).

### Properties **Admin Display** – a descriptive name to identify the Question. **Operator Display** - the Question text as displayed to the Operator. **File Types** – defines the permitted file types. This text is displayed to the end user. More information below\... **Max Files** - This option allows script authors to control how many files users can attach whilst completing the question. If the user attempts to upload more than the allowed max files a validation message will be presented informing users they cannot upload any more files. **Max File Size** - This option allows script authors to control the maximum file size allowed for any individual file uploaded whilst completing the question. Any individual file uploaded must be below the "Max File Size" otherwise a validation message will be displayed informing the user the file is too big. This setting does not limit the total size of all combined files. For example, if you allow the user to upload 5 files and set a max file size of 10mb then the user can upload 5 10mb files for the question which would of course total 50mb on the server. If any individual upload exceeded 10mb then the file would be rejected, and the file is too big validation message would be displayed – other valid files would still be processed if you selected multiple files. **Record Value** - if checked the value will be added to the recorded text. **Mandatory** - check this box to make an upload mandatory. ### More about File Types The permitted file types will be displayed to the operator/end-user. You can specify the permitted file types in various ways... * 'jpg' and 'gif' and 'png' and 'docx' and 'mp4' and 'zip' and 'pdf' * jpg, gif, png, docx, mp4, zip, pdf * jpg,gif,png,docx,mp4,zip,pdf * .jpg, .gif, .png, .docx, .mp4, .zip, .pdf * .jpg,.gif,.png,.docx,.mp4,.zip,.pdf * .jpg,.gif,.png,.docx,mp4,zip,pdf ### Setting sensible defaults Although the File Types, Max Files & Max File Size can be customized on a per question basis it's also possible to set *global* defaults for these fields. These defaults will be used when creating new file upload questions or editing existing questions before these fields were introduced. For assistance with setting these defaults please contact support. ### User Experience

Typically, the path(s) of the uploaded files can be subsequently used in (e.g.) email attachments or can be returned to the host system. As part of your initial implementation (or upgrade), Support can advise how to access the Filepaths and URLs that are available for use, either within Keyfax or when returned to the host. Here, the path is written to a Databox:

Upload question writing the path to a Databox

...which can then be specified as an email attachment:

### Housekeeping WIth potentially large amounts of disc storage required for uploaded files, automatic housekeeping jobs will run every night in order to delete old files. The retention period is configurable; please [Contact Us](/links/support) for assistance with customizing your upload retention period. ### Export Uploads Files uploaded during a Keyfax script are exposed within the Keyfax export XML / JSON for host systems to consume. Examples of the exposed upload results can be seen below. {% hint style="info" %} **NOTE** The below example uses Keyfax Repair Diagnostics. The `` element is exposed in a consistant manner for all Keyfax script types however the full XPath may be different depending on the script type. For example the `` element would typically be replaced with a `` element for Keyfax Repairs Self Service. {% endhint %} #### Example XML ``` ``` #### Example JSON ``` { "KeyfaxData": { "Fault": { "@name": "Fault1", "@type": "RD", "Uploads": { "File": [ { "@name": "Chair_-_Copy.JPG", "@type": "image/jpeg", "@length": "2059660", "#cdata-section": "https://keyfax.domain.com/InterView/Main/Uploads/?f=b11b7fdf-9d33-43a1-bb80-9ad4aba5eb95/Chair_-_Copy.JPG" }, { "@name": "IMG_0003.MOV", "@type": "video/quicktime", "@length": "6115110", "#cdata-section": "https://keyfax.domain.com/InterView/Main/Uploads/?f=7f7e95f8-37f3-4586-bec0-d41ae3d092ad/IMG_0003.MOV" }, { "@name": "IMG_0055_-_Copy.JPG", "@type": "image/jpeg", "@length": "1291112", "#cdata-section": "https://keyfax.domain.com/InterView/Main/Uploads/?f=e46e1fc7-fd63-4568-bc4d-63d6b135f774/IMG_0055_-_Copy.JPG" }, { "@name": "IMG_0401.JPG", "@type": "image/jpeg", "@length": "962949", "#cdata-section": "https://keyfax.domain.com/InterView/Main/Uploads/?f=e23e98bd-549a-418e-bba1-cdb22e5ff980/IMG_0401.JPG" }, { "@name": "Omfax_Social_MASTER.mp4", "@type": "video/mp4", "@length": "13745195", "#cdata-section": "https://keyfax.domain.com/InterView/Main/Uploads/?f=d6c78b87-ebbd-4557-978f-154d64068852/Omfax_Social_MASTER.mp4" } ] } } } } ``` ### Security Although we whitelist the file type extension (configurable above in the File Type definition), we do not interrogate the file content to confirm the content type or perform any other checks. **This should be further secured with 3rd party AV scanning software running on the file server**. # List Questions that present a manual list of options. {% embed url="" %} This question type allows a list of options to be displayed for the Operator to select from.

### **Properties** **Admin Display** – a descriptive name to identify the Question.\ \ **Operator Display** - the Question text as displayed to the Operator.\ \ **Asset Data** – see [this page](/product-suite/admin/entities/asset-data) for more details.\ \ **Enable text input on final option** - check this to allow freeform text to be entered. **Hotspot Image** - (Keyfax version 4.4.7 or later) clicking this button presents an image selection pop-up allowing the user to upload a new image or select an existing. The images are uploaded to and available from the 'List Question Hotspot Image' group of images. Once an image is selected the List Question is no longer presented as a list of text items to be chosen - but, instead, a single image with hotspots that can be clicked to answer the question. Hotspot areas can also (optionally) contain the text of the answer that the user is accepting with some control over the text placement. Clearing the hotspot image reverts the question display in the web environment back to a text list (assuming that all icon images have also be removed - if not the web will display the question as an icon list). {% embed url="" %} ### **Options** **Display Prompt** – the text of the option to be displayed to the Operator. **Return Value** – the text to be stored in a Databox or appended to the recorded text (breadcrumb). If this is left blank the ‘Display Prompt’ will be entered. A value will only be entered if the Rec(ord) box is ticked, as shown above. **Icon Image** – (Keyfax version 4.4.7 or later) if this cell is clicked with the mouse an image selection pop-up appears allowing the user to upload a new image or select an existing. The images are uploaded to and available from the 'List Question Answer Image' group of images. Once an image is selected for any of the answers the List Question is no longer presented as a list of text items to be chosen - but, instead, a list of images with text beneath each that can be selected. Clearing all answer images reverts the question display in the web environment back to a text list (assuming that no hotspot image is selected). {% embed url="" %} ### Re-ordering, adding or deleting options Controls on the right hand side allow you to change the order of the prompts and Add or Delete options. {% hint style="info" %} The Delete button (and up/down buttons to re-sequence options) are disabled **if any referencing script is being edited**. If an Option List question is being edited, then it is not available for use in a script edit. {% endhint %} ### User Experience Without images (both hotspot and all icon images are cleared):

With a hotspot image (Keyfax version 4.4.7 or later):

With icon images (with hotspot image cleared - Keyfax version 4.4.7 or later):

# Numeric Question for numbers. {% embed url="" %} This question type allows the input of a numeric value:

### **Properties** **Operator Display** - the Question text as displayed to the Operator. **Asset Data** – see [this page](/product-suite/admin/entities/asset-data) for more details. **Min** - the minimum value the field will accept without returning an error. **Max** - the maximum value the field will accept without returning an error. **Mandatory** – checking this prevents the Operator from continuing without completing the question. **Decimal places** - set how many decimal places (if any) to be recorded for the value. **Record Value** - if checked the value will be added to the recorded text. ### User Experience

# Text Questions that capture Text input. {% embed url="" %} This question type allows the Operator to enter text in order to answer the question.

### Properties **Admin Display** – a descriptive name to identify the Question within the System. **Operator Display** - the Question text as displayed to the Operator. **Asset Data** – see [this page](/product-suite/admin/entities/asset-data) for more details. **Min Characters** - define the minimum number of allowed characters for the question. Default value will be zero (no limit). **Max Characters** - define the maximum number of allowed characters for the question. Default value will be zero (no limit). **Multi-line** - check this box to allow multiple lines of text to be entered. **Mandatory** - check this box to make input into this field mandatory. **Record Value** - if checked the value will be added to the recorded text.
{% hint style="info" %} Each single line text question input accepts input and pasting of up to 512 characters. Typing over 512 characters is prevented. Each multiline question accepts virtually unlimited amounts of text There is a limit of 1500 characters in the recorded text. We recommend therefore that you use the Max Characters option to control the total number of characters returned if necessary. {% endhint %} ### User Experience

# Video Call Integrating video recording sessions with your scripts Keyfax supports integration with [Keyfax KeyNect](/product-suite/keyfax-keynect) to allow you to integrate video with your scripts meaning you could, for example... * Capture ASB as it is happening * Have subject matter experts assist on more difficult repairs without attending to ‘inspect’ * Have advisors help residents who are vulnerable (or who have poor eyesight) by * Confirming what the boiler make is * Talking them through resetting the boiler * Just seeing exactly what the issue is {% hint style="info" %} Note that Video Calls may not be configured in your installation. For more information contact Omfax Systems. {% endhint %} Choose **Video Call** from the Questions list and you will be presented with this screen:

### Properties * **Admin Display** - a descriptive name to identify the Question within the system * **Operator Display** - the Question text as displayed to the Operator * **Full Name** - The name displayed in the SMS and email * **Email** - The email address of the recipient * **Mobile** - The mobile number of the recipient * **Mandatory** - Determines if a video call must be completed * **Record value** - Records the URLs of any captured media in the recorded text ### Auto-populating the question's fields To automatically populate the Full Name, Email & Mobile form fields that appear when the Video Call question is presented within Keyfax scripts you can use the Full Name, Email & Mobile data sources available when editing the question via Keyfax admin tools to control how these fields are populated...

### User Experience In the scenario where there is a need to start a video session with a caller, the advisor/call handler can proceed to a Video Call question where they will be presented with the following dialogue

1. Click “Send Link & Join Video Call”. 2. Click “Join Video Call”.

3. Mobile user joins the call. 4. Once connected, the KeyNect call then follows the process explained here: [KeyNect Two Way Call](https://docs.keyfax.biz/product-suite/keyfax-keynect/starting-a-call/keynect-two-way-call). 5. End the KeyNect call and close the tab for the KeyNect call. 6. A record of any resources will appear in the Keyfax window. Clicking a file will open it in the KeyNect portal.

7. Click “Submit Video Call”. 8. Click “Submit Video Call” again.

9. Complete the script as required. 10. A copy of the media files will be available in the **Current Call tab**.

11. And on the **results summary page**.

12. Any “Call notes” captured on the KeyNect call will be stored in the “Additional information” field:

13. Click “Submit” to complete the script.

14. The URLs for the media files can be recorded in the description and are also returned as part of the Keyfax Export XML details. Workflow may be needed within your IT systems to write the URLs into the Housing Management System. # Asset Data Certain Question types support the use of Asset Data. Where relevant, you will see this input field:

This allows a Databox’s content to be used to suggest the answer to a question. This can be used to provide default values and assist/guide Operators. Clicking on the ellipsis button, you will be presented with a list of Databoxes:

Expand these groups of Databoxes by clicking the arrowheads:

### Question types that can use Asset Data **List and CheckList Questions** - the relevant option that corresponds to the data in the Databox will be highlighted. If the data in the Databox does not correspond to one of the list options, the data will only be displayed if the question allows freeform text. **Numeric, DateTime & Text Questions** - the data in the Databox will be displayed. To link a Databox to a question, click on the search button ![](http://help.keyfax.biz/Keyfax%20Administrator%20Tools%2041xx%20HC6/images/assetdatabutton41.png) by the Asset Data field. This displays the Databoxes in a new dialog box: For more details about Databoxes please [click here](/product-suite/admin/entities/databoxes). # Markers What they are and how to use them. {% embed url="" %} Markers can be added into a script for reporting purposes. It could be used to record such things as avoidable contacts or any other matter that needs to be measured and reported on. A standard report and dashboard item are provided to monitor the use or Markers. {% hint style="warning" %} **NOTE:** Markers are stored permanently but only after submitting at the final (results) page of a script. Markers are only logged if the script is completed and the script is not cancelled. {% endhint %} Click on the main menu's Marker button to display the Markers tab:

Click the "**Add**" icon to create a new marker. ### Properties **Group** - Markers are arranged into groups so that they can appear together in the Marker Selection list. When creating/editing a new Marker we can select an existing group, select/save at root level by selecting "\" or overtype this to create a new Group. **Marker Code** – the code for the Marker. This code may be alphanumeric, up to 15 characters in length. It is useful to make the code meaningful so that it carries some relevance/identification when viewed within a report or script. **Description** – a short description of the Marker content that will be displayed in the Marker Selection list in the Navigation Pane. This will also be the search criteria when using the filter and visible within the reports to identify issues or reportable matters. {% hint style="info" %} **TIP** Move multiple Markers into a group by either holding Shift whilst clicking to select a block of Markers, or by holding Ctrl whilst clicking to select multiple Markers and then drag them into the desired group in the Marker Selection list. {% endhint %} ### Marker report A summary of Markers logged is available via the **Reports** icon from Main menu.

# Messages Messages inform the operator and end-user {% embed url="" %} {% embed url="" %} Messages are displayed during the Scripts to give information and guidance to the Operator or end-user. The 'Current Call' tab on the Operator pages includes previously displayed Messages for reference. Messages can also feature links to related documents or websites. Click the Messages button on the main menu:

### Properties **Group** - Messages are arranged into groups so that they can appear together in the Message Selection list. {% hint style="info" %} **TIP** When creating or editing a Message, you can either select a group from the drop down list or type a name to create a new group. {% endhint %} **Code** - a code for this Message. This code may be alphanumeric, up to 15 characters in length. It is useful to make the code meaningful so that it's purpose is clear when viewed within the Scripts. **Title** - the Message Title displayed in the bar above the main body of text, as viewed by an Operator. Messages provided in the model use the titles such as ‘Staff information’ in the above example. **Style** - a model set of styles are provided for Messages. These vary the colour scheme, font and sizes. Choose the style for each Message by selecting it from the drop down list. If you would like any amendments or additions to the styles you should contact Support. **Description** - a short description of the Message content that will be displayed in the Message Selection list in the Navigation Pane. This will also be the search criteria when using the filter and visible within the scripts to identify the message. **Link text** - you can add a button to Messages linked to Web Pages or Files within your network. The link text is the name that will be displayed on the button in the Message, for example ‘Help’. There is space for 50 characters. **Link URL** - the location of the Web Page or File the button on the Message will open. For Web Pages enter the URL e.g. . For files, enter the network path e.g. `FILE://\\\\servername\sharename\file1.doc`. {% embed url="" %} **Parameters** - where a URL contains parameters captured from a previous point, these can be added into this box to be added to the URL. For example: Google Maps contains post codes which would be added in here. Databoxes (bookmarks) can be dropped into this field.\ \ **Test** - this enables any defined URLs, including bookmarked databoxes and any relevant parameters, to be tested. **Width** - moving the slider left or right changes the width of the Message. Use the Test button to preview how changes you have made affect the appearance of the Message for the Operator. ### Editing Messages {% embed url="" %} {% embed url="" %} {% embed url="" %} {% embed url="" %} Click the Edit button to start making changes. To edit the Message text itself, either **click in the Preview pane** or the **Text** button. You will see an HTML editor with many formatting functions available for your use:

Databoxes (aka bookmarks) will be displayed in the navigation pane. These can be dragged/dropped onto the Message body or by positioning the cursor in the Message body, click the '**+**' sign. {% hint style="info" %} **TIP** Move multiple Messages into a group by either holding Shift whilst clicking to select a block of Messages, or by holding Ctrl whilst clicking to select multiple Messages and then drag them into the desired group in the Message Selection list. {% endhint %} ### Spacing Above Message Text To add spacing above the message move the insertion cursor to the start of the text and use one of the following techniques to insert a space. * Press \ ***before*** you press \ to create a new 'empty' paragraph at the top of the message. > or... * Hold SHIFT while pressing RETURN to insert a blank line at the beginning of the paragraph.\ If you find the top spacing 'disappears' after you save the message, you may have created a completely empty paragraph (with no content) which is still in the underlying html but does not display in the browser. To rectify this, use one of the techniques above. You should also 'clean-up' the underlying html by clicking the 'Source' button in the Formatting Menu and manually removing the empty \

.....\

at the start of the message. # Testing Messages Check how Messages look to the end user. {% embed url="" %} When creating a Message you'll want to preview the presentation and test databoxes and links work as expected. Simply click the Test button:

You'll be presented with the following:

Enter values as appropriate and click **Evaluate** to see the Message as it will be seen by the end user:

# Services What Services are and how to use them. {% embed url="" %} {% embed url="" %} Services are used in your Scripts to denote when an order for a service or work needs to be given. For repairs and similar work, these are usually codes representing the Schedule of Rates (SOR). They contain information on the work required and the cost involved. Other pieces of information can be attached to a Service Code.

### Properties **Group** - Services can be arranged into groups so that they appear together in the Service Selection on the Navigation Pane. **Service Code** – the code associated with the Service. This is a unique code; it can be any combination of numbers or letters, up to a maximum 15 characters. If you can, make the code meaningful so that it can be easily identifed when viewed in your Scripts. This code will be passed back to the Host in the Export XML and shown to the Operator on the Results screen. **Short Description** - a brief description of the Service/Work, this will appear in the scripts, alongside the codes. **Long Description** – a detailed description of the Service/Work. **Default Priority** – the default priority assigned to the Service. Unless amended within a script this will be the priority diagnosed. **IR Certification** - sets the Inland Revenue (IR) Certification to true if checked. **Unit of Measure** – sets the unit of measure for each Service code. For example LM, No., Job or SM. **Unit Cost** – the cost per unit or the total cost of the Service Code, this is shown on the result screen. **SMV** – the ‘Standard Minute Value’ for the Service. **Contractor** – the code of the contractor to be associated with the Service. ### Filter on Services Admins can search on Services via the Service Code or Description using the Filter option.

Admins can also search on Services based on the Default Service Priority by entering the Priority Code within brackets as below or including text and the code, for example as "Basin (E)":

### Organising lists and grouping of Service Codes {% hint style="info" %} **TIP:** Move multiple Services into a group by either holding Shift whilst clicking to select a block of Services, or by holding Ctrl whilst clicking to select multiple Services and then drag them into the desired group in the Service Selection list. {% endhint %} When creating or editing a Service, you can either select a group from the drop down list or type a name to create a new group. For a priority to override the default it must appear in the script after the code, rather than before it. If two codes are being picked up, the priority must appear after the code it is overriding, but before the second code. # Host-specific notes Managing Services for different hosts out there... ### MIS-AMS ActiveH Keyfax is quite tightly bound with the ActiveH system from MIS. For Service codes, an additional dropdown list of **Service Types** is available:

The list of options presented is read from the ActiveH database and may differ from those shown in the above example. Clearly, in most cases, '**SOR**' would apply, but other options, including types of **Inspection** can affect what is passed back to ActiveH following a diagnostic, and subsequent back-office workflows/processing. # SOR Import Bulk import schedules of rates codes ### SOR Import From Keyfax version 4.4.8 onwards, Schedule of Rates (SOR) codes can be bulk imported into the Services of the current script type from a comma separated file (Excel CSV, Txt file etc). The import can create brand new Services, and, using the Advanced features, can update the details of existing Services that already share the same Service Code. Before anything is written to the database, the import shows you a full preview of the work it plans to carry out, so you can check (and copy out) exactly what will change before committing. {% hint style="info" %} **Note:** You must be in **Exclusive Mode** for this option to be available. Switching to Exclusive mode reveals the Import button on the Services screen, along with the Delete Group and Export buttons. {% endhint %}

### Before you begin {% hint style="info" %} **TIP:** Before running a large import, we recommend taking a back of the selected Keyfax database. You can also use the Export button on the Services screen to take a copy of the current Services. This gives you a snapshot to refer back to (or re-import) should you need it. {% endhint %} Switch to Exclusive mode. Select the correct Script Type from the drop-down at the top right of the window (e.g. Repairs Diagnostics). The import creates and updates Services within the currently selected Script Type only. **Prepare your import file** The file should be a comma separated list (CSV/Txt, or saved out of Excel) with a header row naming each column. Typical columns include the SOR code, short and long descriptions, unit of measure, unit cost, SMV, IR certification flag and priority. ### Step 1 - Start the import On the Services screen, press the Import button and browse to your import file.

### Step 2 - Assign columns to Service properties The **Select Columns to Import** dialog lists every column header found in your file. Against each header, choose the Service property it should populate from the **Select Property** drop-down.

Columns you do not want to import should be left as **No Selection**, they are simply ignored.\ Your file's headers do not need to match the property names, that is exactly what this mapping step is for. Once the columns are assigned, click the button **Show The Changes That Would be Made**. Nothing is imported at this point; the next screen is a preview. You may be notified of any issues such as the below, but click OK to continue.

### Step 3 - Review the work planned The **SOR Import Work Planned** dialog shows, line by line, the changes that will be made to the Services within the current script type. Please read this screen carefully before continuing - this is your opportunity to check the import before anything is committed. Each row shows the Group, Service Code, descriptions, unit of measure, unit cost, SMV, IR certification, contractor and priority the Service will have after the import. New Services will be colour coded light blue:

Rows are colour coded **green** if the service **exists** but the data being imported **is different**. Here items highlighted in green are different to the existing Services.

Hover over a row for a tooltip explaining its status, for example "New SOR Code (no match in current script type)". **Copy Work Planned List to Clipboard** This copies the full list so it can be pasted into Excel for checking or sign-off before you commit the import. **Refresh Work Planned List, below\..** Recalculates the list after you change any of the inputs described below. **Create New Services Only (the default)** With Create New Services Only ticked, the import will only ever insert **new Services**, nothing existing is touched. **Group to use for NEW services** This controls which Group the newly created Services are placed in. The token \`\[group]\` stands for the incoming group name from your import file, so: * "\[group]-new" (the default) keeps the incoming group name and adds a \`-new\` postfix. For example, incoming "Building" codes are created in a group called Building-new * Any "\[group]-postfix" of your choosing works the same way. A plain name (no token) places all new Services into that one named group. Placing new Services into a post-fixed group keeps them clearly separated from your existing Services, so they can be reviewed and then moved into their final groups on the Services screen afterwards. ### Advanced features - updating existing Services Untick **Create New Services Only** to reveal the Advanced features, which allow the import to also update existing Services, whose Service Code matches a row in the import file.

**Group to use for UPDATED Services** This works exactly like the NEW services input, but applies to Services being updated. The default of "\[group]" leaves updated Services in their existing group; use "\[group]-postfix" to move them into a post-fixed group as they are updated. Services that are not updated remain where they are. **Restrict updates to Services residing in this comma separated list of groups** This limits which existing Services are eligible for update. Only Services currently in one of the listed groups will be matched and updated; leave it empty to allow updates across all groups. This is useful when the same SOR codes exist in more than one group and only a specific set should be refreshed. The existing prefix of an SOR code can be augmented by using the token syntax in these edit boxes. For example, if the prefix had been "Building", then "\[prefix]-new" would produce "Building-new" as the prefix of the new (or updated) SOR codes. After changing any of these inputs, click **Refresh Work Planned List, below\...** to see the revised plan. ### Step 4 - Run the import When you are happy with the work planned list, press **Import** and confirm you are ok to proceed. The changes listed are applied to the Services of the current script type. Pressing **Cancel** at any point abandons the import without making any changes.

### After the import Review the newly created group(s) on the **Services** tab. New Services can be moved into their final groups by selecting them (hold Shift to select a block, or Ctrl to select individually) and dragging them to the required group. Switch out of Exclusive mode when you are finished, so other administrators can resume editing. {% hint style="info" %} **TIP:** If a Priority Code in your import file does not match an existing Priority, check the **Priorities** entity and add it before importing, so imported Services pick up the correct Default Priority. {% endhint %} ### Delete Group Deleting a Service group will delete all services within that group. If a service within the group is still in use, the group and all services within it will be left intact. Prior to deleting a service group a hard copy of the services can be taken by exporting the services beforehand or alternatively a request to ack the Keyfax database could be sent to your IT department or Omfax prior to continuing. ### Export Clicking the Export icon will export all Services into a comma separated list so that these can be re-imported if required. # Priorities What are Priorities and how to use them. {% embed url="" %} {% embed url="" %} {% embed url="" %} Priorities are timescales associated with actions. They determine how quickly the action that is described by the Service or Task should be carried out. Services and Tasks are defined with a Default Priority; manually scripting a Priority is only required if you wish to override the default.\ \ Priorities apply separately to each Service and Task in a script; to override a default priority, the required Priority entity must be encountered *after* the Service or Task has been generated by the script. Priority overrides always apply to the most recently generated Service or Task. As soon as a script encounters another Service or Task, subsequent Priority overrides do not affect any earlier Services or Tasks.\ \ For example, if a script generates **Service1** then **Task1** then the priority is set to 'Urgent'; Service1 is exported with its default priority and Task1 is exported with an 'Urgent' priority.

### Properties **Priority Code** – is a unique code for the Priority that is passed back within the Export XML, as part of the diagnosis. This code may be any combination of numbers or letters, up to a maximum 15 characters. The code should mirror the code ID that exists in the host system. **Description** - a short description of the Priority content that will be displayed in the Priority Selection list in the Navigation Pane. This will also be the search criteria when using the Filter. **Premium Factor** – for a service or repair that is chargeable. The factor will be the multiplier applied to the service cost. This is expressed as a decimal; for example a 25% add-on is expressed as a Premium Factor of 1.25. Technical note: this is by configuration (Financial/@feeType="0") and cannot be configured together with "Premium Fixed". **Premium Fixed** - for a service or repair that is chargeable. The factor will be the amount added to the service cost. This is expressed as a whole number; for example a £25 add-on is expressed as a Premium Fixed of 25. This must be enabled in the Keyfax configuration (Financial/@feeType="1") and cannot be configured together with "Premium Factor". **Target Days** - the number of (calendar) days in which the case must be dealt with, in order to follow policy. The **Keyfax Model** scripts contain the following Priorities: | Priority Code | Description | Premium Factor | Premium Fixed | Target Days | | ------------- | ----------- | -------------- | ------------- | ----------- | | E | Emergency | 1 | 0 | 1 | | R | Routine | 1 | 0 | 28 | | U | Urgent | 1 | 0 | 5 | {% hint style="info" %} **TIP:** Any edits made will immediately be reflected in the scripts where this priority is used. If the edit tab is greyed out, this is because you are editing in another tab. You cannot delete priorities that are being used in scripts. The Delete button will remain greyed out unless you are logged in **exclusively**. {% endhint %} # Tasks What they are and how to use them Tasks are used in your Scripts to generate **Letters** or send **Emails**, or simply to create **Notes** to convey information to the host or back-office system. Scripts can collect various items of information for use in Tasks via [Databoxes ](/product-suite/admin/entities/databoxes)from either the Host System or entered via the Operator.

### User Experience For Contact Centre or staff use, any Task details will be presented on the Results page and optionally require action to continue:

### Properties **Group** - Tasks can be arranged into groups so that they appear together in the left hand Task Selection list. {% hint style="info" %} **TIP** When creating/editing a Task, you can either select a group from the drop down list or type a name to create a new group. {% endhint %} **Code** – a unique code for the Task. This code may be alphanumeric up to a maximum 15 characters. If you can, make the code meaningful so that it is easily identified when viewed within your Scripts. Codes must be unique. **Short description** – a brief description of what the Task will do. **Full description** - a detailed description of what the Task will do. **Default priority** – the Default priority assigned to the Task. When this Task code is used within a Script it will be assigned the default priority. {% hint style="info" %} **NOTE** For a priority to override the default it must appear in the script *after* the code, rather than before it. If two codes are being picked up, the priority must appear after the code it is overriding, but before the second code. {% endhint %} ### Task Templates Templates are used to create Letters, Emails or Notes to be actioned as part of the Task. The Task Templates shows all the Templates attached to the Task. #### Add Template The drop down list displays the list of ‘base task templates’ to include with your task To edit the template once you have added it to the task, click the ellipsis button as highlighted below; this will open the Editing pane:

A Task showing the 'Add Templates' dropdown menu and 'edit' buttons

#### Add Item Add an attachment, for example, an advice leaflet, to a Template by selecting the '**+**'. The drop down list contains the options of a Continuation (opens a new blank page with editor) or, an Enclosure if linked to a **Letter** or an Attachment if linked to an **Email**:

A Task showing the Add Item dropdown menu

{% hint style="info" %} **TIP** Move multiple Tasks into a group by either holding Shift whilst clicking to select a block of Tasks, or by holding Ctrl whilst clicking to select multiple Tasks and then drag them into the desired group in the Task Selection list. {% endhint %} # Enclosures & Attachments How they work with your Tasks If you are editing a Task and click 'Add Item' a dropdown menu is displayed. For a task template type of '**Letter'**, this will display two items:

For a task template type of '**Email'**, instead of 'Add Item', you'll see an '**Attachment**' button:

Selecting either **Enclosure** or **Attachment** will present a tab:

### Properties **Description** – enter a description of the Attachment or Enclosure **File** – for Attachments enter the file path or select via the browse button **Select File** - select a file from your local machine **Select Upload** - upload a file from the Keyfax database # Continuations Adding them to a Task Typically, with a letter, you may wish to include Continuations. For example, after diagnosing Damp, you may wish to send an advisory letter which includes a leaflet describing condensation and how to prevent or deal with it:

When you click to '**Add item**' and select '**Continuation**' a tab with an HTML editor will be displayed where you can enter text as appropriate. Shown below is an existing Continuation being edited. Alongside is the **Bookmark Selection** menu where you can drag and drop onto the text area (alternatively, position the cursor then click the '**+**'):

# Host-specific notes Managing Tasks for different hosts out there. ### MIS-AMS ActiveH Keyfax supports two types of tasks: 1. **Keyfax Tasks** - these are handled/processed within the Keyfax system 2. **MIS Tasks** - these are returned to the MIS ActiveH system For MIS environments, an 'MIS task' option is present:

Additionally, the options for **Task Templates** will only display MIS task templates. In an MIS environment, a '**MIS task**' checkbox is available:

### VoiceSage # Reports Learn about the standard reports available via Keyfax Admin Tools. To access, select Reports from the Main Menu. A number of standard reports are provided as well as a dashboard.

Standard reports are displayed in the **Report Selector**. {% hint style="info" %} Advanced users may wish to create their own reports using a suitable Report Builder application. For further information, contact Omfax Systems. {% endhint %} ### Standard Reports

Report Name	Description
Dashboard	Shows a summary of the system on a user specified day together with a summary of the system for the previous six months from the day the report is run.
List of Markers	Lists all or user specified markers in a script type. The user can change whether to show markers that are referenced in scripts or not.
List of Messages	Lists all or user specified messages in a script type. The user can change whether to show messages that are referenced in scripts or not.
List of Priorities	Lists all or user specified priorities in a script type. The user can change whether to show priorities that are referenced in scripts or not.
List of Services	Lists all or user specified services in a script type. The user can change whether to show services that are referenced in scripts or not.
List of Tasks	Lists all or user specified tasks in a script type. The user can change whether to show tasks that are referenced in scripts or not.
Feedback	Lists all the feedback received within a date range.
Order History	Shows the order history for a user specified date range, including the number of users per month. Note that it is possible that History is not captured in your installation. Please contact Support if in doubt.
Summary by Category and Topic	Lists a summary of the usage by category and topic for a user specified date range alongside the top categories for that date range.
Summary by User and Category	Lists a summary of the usage by user and category for a user specified date range alongside the top users and top categories for that date range. Details specific to a single user can be requested.
Summary of Markers Logged	Lists a summary of all or user specified markers logged within a user specified date range alongside the top markers logged for that date range.
Summary of Priorities Logged	Lists a summary of all or user specified priorities logged within a user specified date range alongside the top priorities logged for that date range.
Summary of Services Logged	Lists a summary of all or user specified services logged within a user specified date range alongside the top services logged for that date range.
Summary of Tasks Logged	Lists a summary of all or user specified tasks logged within a user specified date range alongside the top tasks logged for that date range.
User Information	Shows all or user specified users of the Keyfax system alongside the number of active/inactive users and last five active users.
'By Scriptpath' Reports...	The following reports are designed to report System and Master script references with a Script Set name of ‘System’ and ‘Master’ respectively. Rows will appear in the following sequence: • System scripts • Master scripts then • Set level Scripts (alphabetically)
Markers in Scripts by Scriptpath	Lists all or user specified markers and where they can be found within a script.
Messages in Scripts by Scriptpath	Lists all or user specified messages and where they can be found within a script.
Priorities in Scripts by Scriptpath	Lists all or user specified priorities and where they can be found within a script.
Services in Scripts by Scriptpath	Lists all or user specified services and where they can be found within a script.
Tasks in Scripts by Scriptpath	Lists all or user specified tasks and where they can be found within a script.
Scripts	Lists the script, as seen by an operator, for a user specified topic and highlights the rows where there is a change of script.
Cancelled Scripts	Lists scripts that were cancelled before completion, drawn from the cancellation audit log. Results are grouped by Script Set, script type, Category, Topic and the path taken through the script, with a count of cancellations for each — so you can see exactly where in a script users are dropping out. Filterable by From/To date-time range and Script Set, plus a Type picker that selects one cancellation kind at a time: User Cancelled, Script Jump Cancellation (the script itself jumped to a cancel), or User Abandonment (session timed out after 20 minutes of inactivity).
Audit History	Report how often results of a diagnosis have been overridden by the operators. This report allows you to see instances where the priority has been overridden and the reason given. Also any time a tenant responsible repair has been logged as re-chargeable.
Search Requests	Lists all tree-search requests made by users at the category/topic level, covering both Staff and Self Service operators. Data comes from the search audit log and is grouped by Script Set, script type and the search text entered, with a total count of results found for each search. Filterable by From/To date-time range and Script Set.
Script Flows	Generates a script flow diagram for every script in the chosen Script Set (or the Master scripts). You pick a Script Set and optionally narrow to a single category/topic before running it. Note this is a long-running report — it can take more than 20 minutes to complete.
TSM - Historic	Shows a historical line chart of Tenant Satisfaction Measure results across the last several reporting years (up to 10, each running April–March). For each TSM question it plots total responses, satisfied count and percentage satisfied per year, so trends over time are visible. An "LCHO Stock" checkbox restricts the results to low-cost home ownership tenants.
TSM - Time Period	Shows a table report of tenant satisfaction results for a chosen date range, formatted to comply with the Tenant Satisfaction Measures Direction (1st October 2026). The From/To dates default to the current reporting year (1 April – 31 March), and the "LCHO Stock" checkbox splits out LCHO tenants. For each TSM question it reports total valid responses, satisfied count and percentage satisfied (excluding "N/A"/"Don't know" answers).
TSM - Raw Data	Shows the raw, question-by-question response data collected from the TSM Questionnaire, intended for export rather than on-screen analysis. Filterable by the same From/To reporting-period dates and the LCHO Stock checkbox. Useful for submitting or independently verifying the underlying survey data.
TSM - Homes Responded	Shows the number of homes that responded to the TSM Questionnaire, grouped by any categorisation applied by the TSM Keyfax script. Like the other period-based TSM reports, it takes a From/To date range (defaulting to the current April–March reporting year) and an LCHO Stock filter. This gives a response-coverage picture to sit alongside the satisfaction percentages

# Report Subscriptions Learn about subscribing to emailed reports via Keyfax Admin Tools (Keyfax version 4.4.8 and later). To access, select Subscriptions from the Main Menu in the REPORTING section. All reports accessible from the Reports page are available as email subscriptions within the Report Subscriptions page.

The Subscriptions are displayed in the **Report Subscription Selector**. Each subscription is listed by name in the right hand column beneath a parent 'Report Type'. {% hint style="info" %} Report Subscriptions can be seacrhed for using the Filter option at the top of the Report Subscription Selector. {% endhint %} ### Adding a Report Subscription Select the 'Add' button the the details toolbar. This will present a new Report Subscription. From here the report subscription can be customised with the following properties. ### Properties **Subscription Name** - a descriptive name to identify the Report Subscription within the system. **Report** - the report that is required for use with this Report Subscription. **Report Format** - one of PDF, Excel, Word, CSV, XML. **Frequency** - the frequency at which the report should be delievered to the recipients e.g. Daily, Weekly, Monthly, Annually, Annualy (Financial). **To / CC /** **BCC** - the recipient email addresses. Each field can contain multiple email addresses if separated by commas or semicolons. **Subject** - the email address subject field content to be used. **Email Text** - the main body of the email to be used. This also supports the inclusion of the text {StartDate} and {EndDate} which will be substituted for the start and end dates of the priod the report covers, if that report supports a date range parameter. **Page Width / Page Height** - the page width and height for the reports, these are initialised to the values set in the reports themselves. These fields allow overriding of the default report values for these settings. ### Report Parameters The report parameters displayed in a Report Subscription are dependent upon the report selected. {% hint style="info" %} Use the Reports viewer page to experiment with the settings required for your subscription. When satisfied with the parameters you require copy them (using the Windows clipboard) to your Report Subscription parameters area. {% endhint %} # Databox Examples Various databox examples to help scripters get the most from Keyfax. # Business Days How to add business days to today's date. Demonstrates how to calulcate business / working days. Please check with Omfax Systems support before following this guide as this example below relies on... * The `syHolidays` table being populated with all public holidays * The SQL function `fn_DueDate` being present (possibly not the case in older Keyfax versions) Two script steps demonstrate this; the first asks for the number of business days and stores it in a Databox named Script.Business Days:

Example script demonstrating Business Days calculation

This [SQL Query](/product-suite/admin/entities/databoxes/sql-query) Databox executes the function `fn_DueDate`, supplying the Databox above and a country code (**EN**gland). The expression **PlusBusinessDays** is the one of interest:

This Message references both Databoxes:

For example...

# Working Hours You may want to disable some scripts or use another Script Set... Here's a very simple way to determine if you are running a script within operating hours:

The way this works is to find if today is a holiday (the database table is `syHolidays`) and the WHERE clause LOOKS FOR an entry for today, in **EN**gland (other standard values supplied are **NI** and **SCO**). It also checks for weekend (Saturday=7 and Sunday=1) and finally if the time is in working hours. It adds all three resultant boolean values and the Expression will be True if the value returned is greater than zero, meaning we are operating outside of normal hours. # Time of day Check if the current time is between a time range. Helpful if you wish to apply a rule based on certain times of the day. For example changing the priority between the hours 4pm and 8pm. Conditional Expression (for normal working hours. (08:00 – 16:59)): **AsDate Format(‘HH’) AsNum Between(8,16)**

Please note, for the time slot between 9am and 10am the expression would be as follows: **AsDate Format("HH") AsNum between (9,9)** For half hours use the following: **AsDate Format("HHmm") AsNum between (0800,1530)** # Higher priority jobs Read the Service Priority ### Using the priority export databox How to use the priority export databox to read the service priority and display a message, {% embed url="" %} The following example demonstrates how a **Startup script** uses a SQL Databox to check for previous jobs raised within the past 5 minutes by the same user, on the same property and writes the details into a script Databox. Later, a **Custom Script** checks the details of any previous job found. ### The Startup Script This is the Startup Script which executes Databox Read i.e. **Keyfax.MultiOrderCheck** where the results are written to the Databox **MultipleJobs.Details:**

### The SQL Databox This query will looks for any orders submitted in the last 5 minutes, for the same operator and Asset ID. The query runs against the Keyfax table **syOrder**:

In the WHERE clause, you'll see references to other Databoxes in **{**curly**}** braces, including **Keyfax.DateChecks** below (subtracting 5 minutes from the current time could easily have been done using SQL in the above query but it is split out into a Databox just for demonstration purposes):

A Databox that subtracts 5 minutes from the current time

### Using the results of the above Query The Databox **MultipleJobs.Details** contains a number of Expressions, two of which are Conditional and are checking for values representing the Priority (you will see their use in the **Result script** below).

### The Custom Script If a job is found and it has an **Urgent** priority then the priority of the current job is checked. If the current job is an **Urgent** or **Emergency** priority then nothing is done. If the current job is a **Routine**, the priority needs to increase to an **Urgent** to match the previous job. If there is a job found and it has an **Emergency** priority then the priority of the current job is checked. If the current job is an **Emergency** then nothing is done. If the current job is anything else, the priority needs to increase to an **Emergency** to match the previous job. To add another level of checking, as notification to the Operator, a question is displayed informing the Operator that a priority change is required. If they continue, the priority will be upgraded accordingly.

# Script Duration Work out how long scripts/calls are taking... This Databox reads from a [System Values](/product-suite/admin/entities/databoxes/system-values) **Databox** that represents the current date and time and stores this in the Databox **Keyfax.Timer started** at the point that you wish to start timing. ### Databox Creation You will first need to create the [System Values](/product-suite/admin/entities/databoxes/system-values) Databox as shown below\...

Recording exactly when the timer started...

Calculating the difference using a SQL query

### End Result This can be demonstrated in a simple script comprising 3 steps. The first saves the current time, the second is a random question and the third displays a message showing the time spent.

Here is the message...

And the final output...

Message showing results of time spent in script

{% hint style="info" %} **NOTE:** The actual time spent in the script may be usefully returned to the host or calling application. The timer would normally be started in a **Startup Script** and the number of seconds could be returned to the host in a **Results Script**. {% endhint %} # How did it happen? Some clients prefer to ask ‘How did it happen?’ at the beginning of a script: the idea being that if this is a tenant action they may warn of tenant recharges and see if the tenant still wishes to continue and if so to later provide advice as to the estimated cost incurred. However, when calling multiple scripts this ‘How did it happen’ may appear several times and so the following is designed to address this issue. ### How it works When a script links to the system script ‘How did it happen?’ it initially checks the Databox HDIH for a ‘1’, if this is there the script Ends, if it is not there then a ‘1’ is put in the HDIH Databox and the script continues. Thus if this link occurs again the 1 is now in the Databox HDIH and the system script will end. ### Databox Creation Create the following Databoxes:

Amend the System script ‘How did it happen?’ as shown below\...

# Repair Description Appending text to the recorded text (breadcrumb) description. {% embed url="" %} In order to append further information to question responses, additional text can be added to the response using [Text Expressions](/product-suite/admin/databox-expressions/text-expressions). In this example we will append " tiles affected" to the answer to the question "How many tiles are affected?" (note the space before the word tiles). Setup a [Script Data](/product-suite/admin/entities/databoxes/script-data) Databox or use one of the existing and in the expression value add the following + " tiles affected". Add a new expression line by clicking "+" and then simply add the text to the new expression line.

To add this into the script. Against the relevant question write the result into the Script Databox that you have just created the expression line for, and then underneath read the expression value of the Databox, ensuring that the result is recorded.

This will now append your answer to how many tiles are affected with " tiles affected".

The Repair Description in Keyfax should now read something like the below:

# Concatenating CSV How to concatenate CSV values. If you have some comma separated values that you want to concatenate in Keyfax then there is an expression you can use to do that. For example you may have `TenantID` made up from several values. If you wanted to combine three comma separated values you can use the following [CSV](/product-suite/admin/databox-expressions/text-expressions/csv) expression as shown below\.... * `csv(1) & csv (ds, 2) & csv (ds, 3)` You can see this in action via the expression tester as shown below\...

You can see that the value 10002435,44653,3323 has been concatenated to read 10002435446533323 # Tenant Handbook If you would like to display a message that directs the caller to the relevant page or pages of their Tenant Handbook then this may be set up in the following way. Create the following Databoxes. {% hint style="info" %} **NOTE** The first Databox (below) already exists so only the *Expression* needs to be added. {% endhint %}

The above Databox allows the on-going maintenance of the script to be more user friendly, with one easy to understand page for amendments to be made should the relevant pages change. Create the following message (alter the text as you wish):

Create the following Custom System script:

This may then be linked into the [Result](/product-suite/admin/databox-expressions/numeric-expressions/result) System Script or into a specific script where it is needed. For example...

The Message will appear as below:

# Multi-line Addresses An [Address](/product-suite/admin/entities/questions/address) question can capture addresses in various different formats. In general it is best for specific functions to be provided for common formatting tasks, such as `AddrName`, `AddrMain` and `AddrFull`. In some situations you may require a customized function, in which case you must raise a change request as appropriate. The following is probably the cleanest way of formatting an address function and will work for Keyfax 4.0.0 and above. It works by merging the HouseNo and Address1 into a single expression. A comma separated list of selected items is then created, starting with Address2. This list is then tidied to eliminate the ‘blanks’ and then formatted for multiline html as in the original expression. ### Databox Example

### Message Example

### The Final Result

# Priority / Response Days To show the number of days until a repair must be completed, use the following Export databox. If you do not already have it, then set it up as shown below.

### ### Example Usage Here is a simple example of it's use. First setup a message to display the priority and the response days as shown below\...

Then add this new message to your [Results](/product-suite/admin/script-levels/system-scripts/results) System Script as shown below\...

When you run through a script you will see this message appear at the end just before the final Keyfax results screen as shown below\....

This is also shown on the final results screen as shown below\....

# Contains Text Learn how to compare and evaluate text stored within a Keyfax databox. To check for the presence of a specific string within a databox the following approaches can be used. Which approach you use may depend upon your specific requirements. {% hint style="danger" %} **DANGER** It's important when using the CHARINDEX function and / or LIKE operator below that you don't allow user supplied input within your SQL databoxes. Only fixed text databoxes or hardcoded values should be allowed within Keyfax SQL databoxes. {% endhint %} ### CHARINDEX Function In the example below we've created 2 text questions asking the user for text to search and the string to find. This supplied input is captured within two Script databoxes. The "Text is present" SQL databox below is then used to check if the "Text to search" Script databox value contains the string captured within the "Text to find" Script databox value. You can see this example below\...

The "Text is present" SQL databox above performs the logic to determine if the string was found anywhere within the source string as shown below\...

The SQL code for the above SQL databox is enclosed below\... ``` DECLARE @find NVARCHAR(MAX) = '{Script.Text to find}'; DECLARE @source NVARCHAR(MAX) = '{Script.Text to search}'; SELECT CHARINDEX(@find , @source ); ``` {% hint style="info" %} **NOTE** The `{Script.Text to find}`and `{Script.Text to search}`Script databoxes used in the example above are only provided for example purposes and these will likely need to change within your real implementation. {% endhint %} To verify this is working as expected during development the following message could be displayed if a match is found (i.e. the SQL databox returned 1 or above). 0 will be returned if no match is found.

You can use the "Test" button to test your SQL databox via Keyfax Administrator Tools. Within Keyfax you would then see the test message from above like so to verify the string is being found...

### LIKE Operator The LIKE operator is used in a WHERE clause to search for a specified pattern in a string. There are two wildcards often used in conjunction with the LIKE operator: * The percent sign `%` represents zero, one, or multiple characters * The underscore sign `_` represents one, single character For example the following SQL databox will return 1 if the databox value contains AST and zero or more characters after...

Should you have any further quesitons please don't hesitate to [Contact Us](/links/support) {% hint style="info" %} An alternative means to find text within a comma separated list of items is the use of [IndexOf](/). {% endhint %} # Databox Expressions Learn how to use Keyfax Databox Expressions. # Text Expressions The most widely used Expressions are based around your textual data. # CSV Returns the nth item in the comma separated list. A Comma Separated Variable (CSV) is a string of textual items separated by commas e.g. "gold, silver, bronze". The CSV expression returns the nth item (1 being the *first*) from a Comma Separated Variable. If the entry is not found, the result returned is "" (an empty string).

Expression	Databox Value	Result	Comments
`CSV(2)`	gold,silver,bronze	silver	Will return the specified section from within a Comma Separated Variable (CSV)
`CSV(3)`	18843,49978,2114	2114

# Entry Returns an entry from a delimited list at the specified index. Returns the nth (1 being the first item) from a list. Returns an empty string if the entry does not exist. This differs from the [CSV](/product-suite/admin/databox-expressions/text-expressions/csv) Expression as you can specify separators other than commas.

Expression	Databox Value	Result
`Entry(2, ";")`	line1; line2; line3	line2
`Entry(3,"/")`	07/11/2023	2023
`Entry(3,",")`	item 1, item 2, item 3	item 3

# Exists Returns a Boolean to indicate if the Databox value exists. Returns False if a Databox value is empty or blank, otherwise returns True if the Databox value contains any characters or data. This expression can be used to perform [logical expressions](/product-suite/admin/databox-expressions/logical-expressions).

Expression	Databox Value	Result
`Exists`	The quick brown fox	True
`Exists`	0	True
`Exists`	1	True
`Exists`		False

# FieldMerge Returns a named item from a multi-value Databox (Keyfax version 4.4.8 and later). This Expression constructs a string from a multi-value Databox such as an [Address ](/product-suite/admin/entities/questions/address)question, an HTTP Request or a [SQL Query](/product-suite/admin/entities/databoxes/sql-query) returning multiple columns with individual column values accessible using the column name. The syntax of the call is: 1. format - a string containing a string with square bracketed column names to indicate the positions at which the column values should be substituted into the string

Expression	Databox Value	Result	Comments
`FieldMerge("[name] ([userId])")`	<KFXmlValue rows="1"><KFRow id="0"><userId>1</id><name>George Smiley</name></KFRow></KFXmlValue>	George Smiley (1)	If the databox value has multiple records (as supported by multi-record-set databoxes (Keyfax 4.4.8 only) FieldMerge will return a merge of fields in the first row only.

{% hint style="info" %} Using an expression in a databox driven Dynamic List Question (a 4.4.8 feature) that contains a FieldMerge will result in the FieldMerge expression being executed on each row of the Dynamic List Question options. This is an ideal way to format Dynamic List Question options. {% endhint %} # RowMerge Merges content from a multi-record-set databox result into a single string (Keyfax version 4.4.8 and later). This Expression constructs a string from a multi-record Databox such as can be achieved by selecting the multi-record-set option on a [SQL Query](/product-suite/admin/entities/databoxes/sql-query) or HTTP databox. The syntax of the call is: 1. format - a string containing a string with square bracketed column names to indicate the positions at which the column values should be substituted into the string 2. separator - a string containing the characters to use between each formatted string when joining the result together

Expression	Databox Value	Result	Comments
`RowMerge("[name] ([userId]), ",")`	<KFXmlValue rows="1"><KFRow id="0"><userId>1</id><name>George Smiley</name></KFRow><KFRow id="1"><userId>2</id><name>Ann Sercomb Smiley</name></KFRow></KFXmlValue>	George Smiley (1), Ann Sercomb Smiley (2)	This expression compliments FieldMerge that achieves this goal only for the first record of a databox result (if multiple records exist).

{% hint style="info" %} RowMerge is useful when you require a comma separated list of results from a SQL or HTTP databox. {% endhint %} # Index Returns the index of the specified string within the Databox value. This is useful to find the position of an item in a comma separated list (or other separator). The first argument (aka parameter) is the string of text you are looking for. The second argument is the delimiter that separates the list of items. Counting starts from 1 and zero is returned if the item is not found in the list. {% hint style="warning" %} Note that an **exact match** is required e.g. text case and spaces {% endhint %}

Expression	Databox Value	Result
`Index(" line2", ",")`	line1, line2, line3	2
`Index("red", "/")`	Blue, Red, Green	0

To avoid mistakes with mixed case, this will switch the Databox contents to upper case and then look for "RED"

Expression	Databox Value	Result
`Upper Index("RED", "/")`	Blue/Red/Green	2

# IndexOf Returns the location of one string within another for a Databox (Keyfax version 4.4.8 and later). This Expression returns a number indicating the position of the first character of a string being searched for within the databox value or 0 (zero) if no string match is found. The syntax of the expression is as follows - parameters: 1\. string - a list of strings that should be searched for within the databox value\ 2\. string - the list delimiter e.g. a comma (",") to indicate how to split the string in the first parameter\ 3\. integer - 1 to indicate that the string comparison should ignore case, 0 to indicate that the string comparison should take case into consideration (i.e. when 1 "LiKeS" = "likes"

Expression	Databox Value	Result	Comments
`IndexOf("LiKeS,George", ",", 1)`	George Smiley likes chess	14	As the case insensitive parameter is set to 1 the first string in the list of strings to search for 'LiKeS' is found at position 14.
`IndexOf("LiKeS,George", ",", 0)`	George Smiley likes chess	1	As the case insensitive parameter is set to 0 the change of case in 'LiKeS' does not match the 'likes' in the databox value, instead the second search string 'George' is matched and found at position 1.
`IndexOf("NotThere", ",", 0)`	George Smiley likes chess	0	As the string 'NotThere' cannot be found in the databox value the return value is 0.

# InList Returns a Boolean to indicate if the specified string exists within the Databox value. Returns True if text is in list. Arguments are the list of items separated by the delimiter specified in the 2nd argument (usually, but not restricted to commas). {% hint style="warning" %} Note that an **exact match** is required e.g. text case and spaces {% endhint %}

Expression	Databox Value	Result	Comments
`Inlist("A,B,C", ",")`	[Any of] A, B or C	True	True as text is in list.
`Inlist('107753;75536;86653', ';')`	86653	True	Note semi-colon separator and use of single quotes to envelope arguments

# Item Returns a named item from a multi-value Databox. This Expression returns a named item from a multi-value Databox such as an [Address ](/product-suite/admin/entities/questions/address)question or a [SQL Query](/product-suite/admin/entities/databoxes/sql-query) returning multiple columns with individual column values accessible using the column name.

Expression	Databox Value	Result	Comments
`Item("Surname")`	Smith	Smith	Typically this is accessing Address question details. See Address question for all available fields
`Item("County")`	Devon	Devon

# Len Returns the number of characters held within the Databox value. Returns the number of characters held within the Databox value.

Expression	Databox Value	Result
`Len`	The quick brown fox	19
`Len`	1.775	5
`Len`		0

# ListTidy Removes leading, trailing and duplicated occurrences of the given separator. Removes leading, trailing and duplicated occurrences of the given separator.

Expression	Databox Value	Result
`ListTidy(";")`	;B;;D;	B;D
`ListTidy(",")`	,Actinolite,Amosite,Anthophyllite,,	Actinolite,Amosite,Anthophyllite

# Lower Converts any uppercase characters to lowercase. Converts any uppercase characters to lowercase.

Expression	Databox Value	Result	Comments
`Lower`	Main Road	main road

--- [Next Page](/llms-full.txt/1)