Visual Dialogue User Guide. Version 6.0

Transcription

1 Visual Dialogue User Guide Version 6.0

2 2013 Pitney Bowes Software Inc. All rights reserved. This document may contain confidential and proprietary information belonging to Pitney Bowes Inc. and/or its subsidiaries and associated companies. Portrait Software, the Portrait Software logo, Portrait, and Portrait Software s Portrait brand are the trademarks of Portrait Software International Limited and may not be used or exploited in any way without the prior express written authorization of Portrait Software International Limited. Acknowledgement of trademarks Other product names, company names, marks, logos and symbols referenced herein may be the trademarks or registered trademarks of their registered owners. Portrait Software Support If you need help with something that s not covered by this documentation, try the Knowledge Base on our web site. and follow the links to your product. You can also download other Portrait Software documentation from the site. If you don t have a username and password or you ve forgotten them please contact us through one of the channels below. If you find a problem with the use, installation, or documentation of this product, please contact us using any of the following methods: support@portraitsoftware.com Phone USA/Canada (toll-free) Rest of world When you report a problem, it helps if you can tell us: The name of the software application The circumstances in which the problem arose What error messages you saw (if any); The version of the software that you were using. Pitney Bowes Software Inc. June 13, 2013

3 Contents Chapter 1: Introduction...9 Purpose...10 Intended audience...10 Related documentation...10 Chapter 2: Product overview...11 About Visual Dialogue...12 Key functionality...12 Chapter 3: Visual Dialogue GUI...13 The main application window...14 Ribbons...14 Ribbon tabs...14 The File tab...14 The Home tab...15 The Create tab...17 The View tab...17 The Web tab...17 Folders...17 About folders in Visual Dialogue...17 The Explorer...18 Browsers...18 The main component browsers...18 The Select Columns window...19 Visual Dialogue options...19 The Background Tasks Monitor window...22 Browsing dependencies...23

4 Chapter 4: Dialogs...25 What is a dialog?...26 Creating a new dialog...27 Dialog Designer...27 About Dialog Designer...27 Design View...28 Execute View...51 Script View...60 The Options tab...61 Dialog properties...62 Telemarketing projects...63 Browsing dialogs...67 Dialog security...68 Dialog templates...69 What is a dialog template?...69 Creating a new dialog template...69 The Dialog Template Designer...70 Guided setup...70 Dialog template properties...73 Dialog template ribbon tabs...74 Chapter 5: Selections...75 About selections...76 Selections in dialogs...76 Selections in Customer View...77 Selection Designer...77 About Selection Designer...77 Creating a new selection...78 Adding a criterion...79 Previewing a selection...80 Adding more criteria...80 Grouping criteria...81 The toolbox in Selection Designer...82 Group criteria...82 Special criterion types...83 Working in Expression Mode...87 Working in SQL Mode Portrait Dialogue 6.0

5 Working with context...88 Browsing selections...90 Chapter 6: Messages...91 About messages...92 Document types...92 Browsing message templates...93 Message Manager...93 Test sending messages...95 Deleting tracking data...95 Master templates...96 About master templates...96 Master template properties...96 Master Template Designer - Message Designer...98 Message templates Creating a new message template HTML templates and web modules Message Template Designer Chapter 7: Questionnaires About questionnaires How questionnaires are used Creating a new questionnaire Questionnaire Designer About Questionnaire Designer Questions View Layout View in Questionnaire Designer Using merge tags Questionnaire properties Testing a questionnaire Building a questionnaire URL Response tracking Browsing questionnaires Running the questionnaire report Exporting response data Deleting response data Questionnaire styles Script Object Model Visual Dialogue User Guide 5

6 Script Object Model overview Global objects, methods, and properties The Question object The Alternative object The Matrix object The Column object The Row object The Cell object The Page object The Section object The Customer object Examples of scripting in questionnaire flow The Dialogue Server API Client-side events and scripts About client-side events and scripts Working with client-side scripts and events Available events Global script methods Global script properties Chapter 8: Reports About reports How and why reports are used Report Designer Creating a new report template About Report Designer Report template properties Data View Layout View in Report Designer The toolbars Using subreports Preview View About Preview View Previewing the report Printing the report Viewing a report in Report Portal Browsing reports Report security Portrait Dialogue 6.0

7 Report formats Report Portal Integrated reporting Integrated reporting overview Standard reports Customizing standard reports Standard report SQL statements Chapter 9: Task Organizer About Task Organizer Workgroups Workgroup users Manual distribution Automatic distribution Deleting workgroups and users Chapter 10: Broadcasts About broadcasts Chapter 11: Published files About published files Chapter 12: Content objects About content objects Creating a new content object Content Object Designer About Content Object Designer Content object properties Working with content items Working with rules Testing a content object Building content object HTML tags Using content objects in a questionnaire Using content objects in an Browsing content objects Visual Dialogue User Guide 7

8 Chapter 13: Export and import of Visual Dialogue objects About export and import The Visual Dialogue export wizard The Visual Dialogue import wizard Portrait Dialogue 6.0

9 Introduction 1 In this section: Purpose Intended audience Related documentation

10 Purpose Purpose This document describes how to use Visual Dialogue to design and implement marketing strategies and campaigns. Intended audience This guide is intended for marketing analysts who are tasked with planning and implementing marketing campaigns. Related documentation Document Media (zip/dvd) and location Portrait Dialogue 6.0 Release Notes Portrait Dialogue media in: \Documentation\<language_code>\ Tip: All documents are also available on Portrait Software s support website: 10 Portrait Dialogue 6.0

11 Product overview 2 In this section: About Visual Dialogue Key functionality

12 About Visual Dialogue About Visual Dialogue Visual Dialogue forms part of the Portrait Dialogue suite of products, which support Customer Relationship Management. Visual Dialogue is used by marketers to define, manage, and carry out large-scale structured communication processes, and is specifically designed to support the principles of one-to-one marketing. The Visual Dialogue application provides you with an intuitive work environment that makes it easy to graphically plan your customer communication process and execute all phases in it. For example, you might use Visual Dialogue to: welcome new customers, query them about their communication preferences, and send them an offer via their preferred communication medium handle complaints, ensuring that all first-time complainers receive a phone call, while chronic complainers receive responses based on their profitability distribute a customer satisfaction survey, evaluate the responses, place customers in different groups according to their responses, and then send appropriate communication or take appropriate actions about each group. Key functionality Visual Dialogue includes five key components to help you implement your marketing strategies and campaigns: Visual Dialogue Designer: Create and execute customer dialogs. Visual Selection Designer: Create and test selections used to differentiate between customers. Message Template Designer: Create and test message templates used to communicate with your customers through different channels. Questionnaire Designer: Create and test questionnaires to get feedback from your customers. Report Designer: Create and test reports to easily access data in your system. 12 Portrait Dialogue 6.0

13 Visual Dialogue GUI 3 In this section: The main application window Ribbons Folders Browsers Visual Dialogue options The Background Tasks Monitor window Browsing dependencies

14 The main application window The main application window When you start Visual Dialogue, the main application window shows the start page. This is one of many windows you will be working with, but a number of the elements are common to all windows. Element Ribbon tabs Quick access toolbar Explorer bar Work area Status bar Header bar Tab bar Toolbox Contains most of Visual Dialogue s commands. In addition, you can use right-click menus to gain access to functions that are directly associated with a specific item. Contains buttons that let you perform common functions without having to go through the menus. Lets you quickly access the different parts of Visual Dialogue. This can also be done from the Home tab. The area in which you work with the different parts of the system. For the start page, this contains references to all your recent work. You can click on a reference to open it. Gives information on application activity. Shows what you are working with at the moment. Lets you switch between the windows that are open. This can also be done from the View tab. Contains different tools that you can use while working The toolbox will change according to what you are working with at the moment. Ribbons Ribbon tabs There are five standard ribbon tabs in Visual Dialogue: the File tab, the Home tab, the Create tab, the View tab and the Web tab. Alongside these tabs, additional task-specific tabs appear in different parts of the application. The File tab These are the commands that you can access from the File tab: Tab option Save Save the item that you are currently working with. 14 Portrait Dialogue 6.0

15 Chapter 3: Visual Dialogue GUI Tab option Save as... Save all Close Recent Print Printer setup... Help Relogin... Options... Exit Save a copy of the item that you are currently working with. Save all items that have unsaved changes. Close the item that you are currently working with. Open items that you have worked with recently. Print the item that you are currently working with. Configure a printer. Display this help file, the reference help, version and license information. Reconnect to the application server. This is necessary if your connection has timed out. View and change different options in Visual Dialogue. Close all windows and exit the application. In addition, when working with objects like dialogues, selections, questionnaires etc. you will get an Info option with the following sub options: Tab option Properties Dependencies Security Show properties of the selected item. Open the dependency browser window for the selected item. Show the security settings window for the selected item. The Home tab These are the commands that you can access from the Home tab: Tab option Active items Explore Cut Copy Paste Delete Find Replace Shows a list of all the items you have open. Open the Explorer window or a main component browser window. Remove the current selection and place it on the clipboard. Copy the current selection to the clipboard. Insert the contents of the clipboard in the active window. Delete the current selection. Search for text. Search and replace text. Visual Dialogue User Guide 15

16 The Home tab Tab option Select all Rename Reports Select everything in the active window. Rename the selected item. Reports enable you to run integrated reports from various places in Visual Dialogue. Reports are only available if integrated reporting is enabled. This is configured in Visual Dialogue options. The content varies depending on which integrated report is applicable in a module/location in Visual Dialogue. See Integrated reporting overview and Standard reports for details. In addition, when working with a main component browser, the following commands are shown in the tab: Tab option Open Properties Security Dependencies Export Import Find Preview Open the selected item. Show properties of the selected item. Show the security settings window for the selected item. Open the dependency browser window for the selected item. Launch the Visual Dialogue export wizard, which lets you export objects (dialogs, selections, etc.) designed in Visual Dialogue to files, or export a list of content of the current browser to file. Launch the Visual Dialogue import wizard, which lets you import Visual Dialogue objects from files. Show or hide a window where you can search for items in the browser. Show or hide a preview of the selected item in the bottom of the browser In addition, when working with the Explorer, the following commands are shown in the tab: Tab option New folder Up Back Forward Create a new folder. Navigate up one level in the folder structure. Navigate back in the folder structure. Navigate forward in the folder structure. 16 Portrait Dialogue 6.0

17 Chapter 3: Visual Dialogue GUI The Create tab Create new dialogs or dialog templates, selections, message or master templates, questionnaires, report templates, broadcasts, questionnaire styles, published files, and content objects. The View tab These are the commands that you can access from the View tab: Tab option Select columns Refresh Explorer bar Toolbox Header bar Tab bar Status bar Previous window Next windows Previous sub view Next sub view Switch language Choose the columns to view in the browsers. Refresh the data in the active window with the newest data from the server. Hide or show the Explorer bar. Hide or show the toolbox. Hide or show the header bar. Hide or show the tab bar. Hide or show the status bar. Move focus to the previous window in the list of open windows. Move focus to the next window in the list of open windows. Go to the previous subview (tab) in the active window. Go to the next subview (tab) in the active window. Select another language to be used in the user interface. The application must restarted for this change to take effect. The Web tab From the Web tab, you can open the web applications Customer View, Telemarketing, Report Portal and Message Designer. In all cases, you will automatically be logged in as the user you are logged into Visual Dialogue with. Folders About folders in Visual Dialogue Visual Dialogue has a folder structure that works very like the Windows folder structure. All Visual Dialogue objects can be contained in folders, and the folders themselves can contain subfolders. Visual Dialogue User Guide 17

18 The Explorer You can use folders to organize your work in any way you want. For example, you could create a folder for each user of the system, or you could create a folder for each dialog, in which you would keep the dialog and all objects it uses, possibly in subfolders. The two methods could of course be combined. The Explorer The Explorer displays the hierarchical structure of objects and folders on your system. You can use the Explorer to organize your folders and objects by dragging to the tree view or by cutting and pasting. You can also create or delete objects, edit existing ones, show properties, and perform other actions in connection with objects. Browsers The main component browsers All the main components display a browser window with a grid as its first window. You can open an item in the browser by double-clicking on it. You can sort the items by clicking on a column header. When you right-click on an item, a new menu appears. These are the commands you can access from this menu: Menu option New... Open Delete Properties Security... Create a new item. Open the selected item. Delete the selected item. Show properties of the selected item. Show the security setting window for the selected item (not applicable for all item types). Browse dependencies... Open the dependency browser window for the selected item (not applicable for all item types). Reports Export... Import... Select Columns... Show available integrated reports for the selected item. Launch the Visual Dialogue export wizard, which lets you export objects (dialogs, selections, etc.) designed in Visual Dialogue to files. Launch the Visual Dialogue import wizard, which lets you import Visual Dialogue objects from files. Open the Select Columns window, to select the columns you want to view and their order. 18 Portrait Dialogue 6.0

19 Chapter 3: Visual Dialogue GUI The Select Columns window In the Select Columns window, you can choose what columns to view and in what order they will appear. View selected columns View all columns Hide selected columns Hide all columns Move selected columns up in viewing order Move selected columns down in viewing order Visual Dialogue options From the File tab, you can open the Options window. Here you can alter various options that change the look and feel of Visual Dialogue and the way it behaves. The General tab Option Show Recent Work Show Explorer Show icons in tab bar Log exceptions to file Log to folder When this box is checked, the recent items in the File tab will be shown as the initial page when you start the application. When this box is checked, the Explorer will be shown as the initial page when you start the application. If this box is checked, the tabs in the tab bar get a small icon to the left of the caption symbolizing their content. If this box is checked, all exceptions (errors) in the application are logged to a file. If you turn on exception logging use this field to specify the folder where the log files are kept. The Dialog General tab Option Quick design mode Show grid Check this option to enable Quick Design Mode. When Quick Design Mode is enabled, dialog groups and operation can be drawn/designed without displaying the properties dialogs. Check this option to show the canvas grid when designing dialogs Visual Dialogue User Guide 19

20 Visual Dialogue options Option Snap to grid Horz. size / Vertical size Automatically display execution progress window Automatically save dialog before executing Enable Dialog Overview view Show component IDs Show comments Show execute options as icons Checking this option makes groups snap to the canvas grid when designing dialogs. These settings specify the horizontal and vertical size of the canvas design grid. Check this option to automatically display the execution progress window when execution a dialog operation. Check this option to automatically save a dialog before executing an operation. If this box is checked, the overview page is shown as part of the Dialog Designer. If this box is checked, the internal IDs of groups and operations are shown in the Dialog Designer. If this box is checked, comments are shown in the Dialog Designer. If this box is checked, execute icons are shown in the Dialog Designer. Execute icons visualize the execute options that you have set for your operations. The Dialog Colors and Skin tab Option Design Execute Active Inactive Selected Default Skin Set the background color of the dialog work area when you are in Design View. Set the background color of the dialog work area when you are in Execute View. Set the color of an active dialog operation. Set the color of an inactive dialog operation. Set the color of a selected dialog operation. Set the default skin used when creating new dialogs. The Message Designer tab Option Open in Design View Open in Source View When this box is checked, message templates will be opened in Design View. When this box is checked, message templates will be opened in Source View. 20 Portrait Dialogue 6.0

21 Chapter 3: Visual Dialogue GUI Option Open in integrated designer Use old style dialog to select published files Launch designer in web browser When this box is checked, Message Designer templates will be opened in Visual Dialogue. When this box is checked, the Visual Dialogue internal published files browser is used to select published files instead of the Message Designer published files browser. The Visual Dialogue internal browser supports folders. When this box is checked, Message Designer templates will be opened in a web browser. The Selection Designer tab Option Auto describe new criteria when suitable If this box is checked, new criteria in Selection Designer are automatically given a textual description if a suitable description can be derived. The Task Organizer tab Option Prompt for confirmation These options turn the confirmation dialog box on or off for the different operations you do in the Task Organizer. The Integrated Reporting tab Option Enable integrated reporting Launch Report Portal Open reports inside Visual Dialogue Open in new window Report view format Enables reports configured for integrated reporting. Select this option to run integrated reports in Report Portal. Select this option to run integrated reports inside Visual Dialogue. Select this option to open integrated reports inside Visual Dialogue in a new window. The output format used when running the reports. For a detailed list of the different formats available, see Report formats on page 245. The Content Object Designer tab Option Open in Design View When this box is checked, content items of type HTML will be opened in Design View. Visual Dialogue User Guide 21

22 The Background Tasks Monitor window Option Open in Source View When this box is checked, content items of type HTML will be opened in Source View. The Web tab Option Always open in Internet Explorer When this box is checked, web applications opened from Visual Dialogue will always use Internet Explorer. Open in Internet Explorer when required Always open in default web browser When this box is checked, web applications opened from Visual Dialogue will use Internet Explorer if they only support Internet Explorer (for instance Customer View, Report Portal and Telemarketing), other web applications will be opened in the system default web browser. When this box is checked, web applications opened from Visual Dialogue will always use the system default browser. The Background tasks tab Option Automatically display execution progress window When this box is checked, the execution progress window for background tasks is always shown when a background task is triggered. When the box is not checked, background task progress will only be shown in the status bar. The Background Tasks Monitor window Background tasks Background tasks are typically long-running tasks that run in the background, enabling you to continue working on other tasks in Visual Dialogue in the meantime. The Background Tasks Monitor window The Background Tasks Monitor window can be used to monitor and abort ongoing tasks that are executed in the background. Examples of tasks that are executed in the background are Clear Dialog, Delete Dialog, and Delete Message bundle. Note: The first time a background task is triggered, a background task execution window appears. You can configure Visual Dialogue so that background tasks are executed without a background task execution window appearing. See Visual Dialogue options on page 19. Alternatively, clear the Automatically show this window checkbox. If this checkbox is not checked, the only place where background 22 Portrait Dialogue 6.0

23 Chapter 3: Visual Dialogue GUI task execution can be monitored is the status bar. Click on the status bar to open the Background Tasks Monitor window. Browsing dependencies Dependency browser windows can be used to browse dependencies between dialogs and message templates, questionnaires, selections, and other dialogs. The upper part of the Dialog Dependencies window shows operations in other dialogs that use the dialog. The lower part shows you what items are used by operations in the dialog. If you open the window for other types of components, only the upper part will be shown. You can click on the edit (pen) button on the right-hand side to close the window and open the selected item. Visual Dialogue User Guide 23

24

25 Dialogs 4 In this section: What is a dialog? Creating a new dialog Dialog Designer Browsing dialogs Dialog security Dialog templates

26 What is a dialog? What is a dialog? In 1:1 marketing we aim to give each customer the feeling of being in direct, 1:1 communication with our organization, even though there are tens or hundreds of thousands of customers. We aim to learn from each customer s communication with us: To let the customer s communication with us influence our further communication with him or her. This is possible when we structure communication in a dialog: A tool for planning, carrying out and keeping track of 1:1 market communication with large numbers of customers. Comparison to moving business cards between file boxes You can best understand what a dialog is by comparing it to the manual process of putting customers business cards into different file boxes, depending on what you want to do with each customer. You might begin by collecting the cards of all the customers who have not bought anything from you for at least a year and put them in a box called Group of those to be contacted. You might put some of the cards in a box marked Call these and some of the cards in a box marked Write to these. After you have called each person, you might put the cards into new boxes: Placed a new order, May be interested, follow up later, or Lost these customers, make a plan to get them back. Below, you see how the communication process would look like using the file box method. In Visual Dialogue, you create the communication process in a graphic environment using elements to illustrate the different stages of the process. 26 Portrait Dialogue 6.0

27 Chapter 4: Dialogs Creating a new dialog To create a new dialog, choose Dialog on the Create tab. The New Dialog Wizard appears. Enter the appropriate information. Option Dialog name Customer domain State Enter the name of the new dialog. Choose the customer domain you want this dialog to get its participants from. The state the dialog is in. This is only an informative field and does not have any influence on how you work with the dialog or how it behaves. When you have entered all the information, click on Next to continue. Option Allow multiple occurrences of customers Enable participant logging Check this if you want the same customer to figure as participant in the dialog more than once, provided the customer has different context information attached to each occurrence. If it is not checked, the same customer can only occur one place in the dialog at any time. Check this to have additional logs created when the dialog is executed. This provides for more basis for statistics and analyses but will slow down execution, in some instances noticeably. If you choose Decide logging on each operation, you can turn logging on or off on each operation. If you choose Always generate participant log, additional logs will always be created. When you have entered all the information, click on Finish to create the new dialog and start working with it in the Dialog Designer. Dialog Designer About Dialog Designer Dialog Designer is used to create and execute dialogs. It has three main modes: the overview page, Design View, and Execute View. The overview page This view contains key information about the dialog, such as its key properties and execution summary. You can also edit the dialog s properties from this page by clicking on Edit... You can open the dialogs folder by clicking on Open folder. You can show or hide this view in Options. Visual Dialogue User Guide 27

28 Design View Design View Design View is where you design your dialogs. Here you can add groups and operations using the toolbox, and you can edit and/or delete them afterwards to refine your dialog. Execute View In Execute View, you can manually execute the dialog operations. You can also manipulate the dialog in other ways, e.g. by moving participants from one group to another, or by deactivating some or all of the participants in a group. This is also where you can view the dialog s participants and the various history logs. Design View About Design View Design View is where you design and customize your dialog. You can add groups and operations using the toolbox on the right-hand side. You can edit groups and operations by clicking on them and choosing Edit Group/Operation, or by double-clicking on them. If you want to change the look of your dialog, you can drag the different elements around or change the color of your groups. It is also possible to change the starting group of your operation or the end group of your branches by clicking and dragging them to different groups to change the flow of the dialog. Quick Design Mode Use Quick Design Mode to easily place groups and operations in a dialog. Use this feature to draw a dialog at first, for later fine-tuning. Dialog elements The following is a visual example of the elements that appear in a dialog: groups, operations, branches, branch points, and entry points. The operation in the example includes only one branch. 28 Portrait Dialogue 6.0

29 Chapter 4: Dialogs Groups Adding groups 1. Click on the group you want to add in the dialog toolbox. 2. Position the mouse pointer, which should now have a small group symbol attached to it, where you want to place the group in the work area, and click once. If Quick Design Mode is turned off, the Edit Group window opens. If Quick Design Mode is turned on, right-click on the group and choose Edit. 3. When you have finished entering information in the Edit Group window, click on OK. Editing a group Double-click inside the group that you want to change, choose Edit selected item from the Design tab, or right-click on the group and choose Edit Group. The Edit Group window opens. Option Group Type Participants Group Name Group ID Allow inserts of participants... Use for reporting In the Type field, you see which group type the group is. The group type cannot be changed. Here you see the number of participants in the group. Give the group a descriptive name. The name you enter here is the name that is displayed inside the group rectangle in the Visual Dialogue, so you want this to be fairly short. This is the unique group id which identifies the group in the database. Enter a description of the group that can help you or other dialog users to understand how the dialog works at a later time. Check Allow manual insert of participants if you want to insert participants into the group from Customer View. Check Use for reporting if you want the group to appear in the summary on the overview page. This property can also be used in some standard reports to decide if the group is shown in the report or not. Group types Groups are containers of customers that you want to do something with. In visual dialogs, these are shown as large rectangles. There are four different group types: Group All known customers The All known customers group contains all the customers in the customer domain you are working with. The customers are identified by ID numbers only and can Visual Dialogue User Guide 29

30 Design View Group therefore appear only once in the group. In other words, the All known customers group can be seen as the participant source group in the dialog. The All known customers group is normally used as the Start group in a dialog. However, it can also be used to enter new participants into a dialog, for instance by using it together with an Import from file operation. Known customers The Known customers group contains a selection of customers. These customers are identified by a combination of ID and context, and therefore the same customer ID may appear more than once in the group or the dialog. Currently, the Known customers group may be used as From group or To group for almost all operation types in a dialog. Market segment The Market segment group contains a description of supposed segment members. That is an unknown number of unidentified customers, possibly including some or all of the customers in the customer database. By having groups with this group type (and the associated operations), users can define dialogs aimed at potential customers and customer capture, and record costs in the same way as for other dialogs. Control group The Control group contains a selection of customers. These customers are identified by a combination of ID and context, and therefore the same customer may appear more than once in the group or the dialog. The control group is an additional group type that includes only participants that are randomly selected into the group for control purposes. The functionality around this group type has not been fully implemented, but is planned for future release. However, the way it currently can be used is to select a group of customers that you do not want in your dialog. You may then use data mining to compare the results of the customers in the control group with the results of the customers that participated in the dialog. Operations Adding an operation 1. Click on Draw operation in the dialog toolbox. 2. In the work area, position the mouse pointer, which should now have a small arrow attached to it, over an empty area or in the group from which you want to start the operation. Click and hold down the mouse button, and drag a line to the area or group in which you want the operation to end. Note: When you are adding an operation, if no to-group is selected and Quick Design Mode is turned off, the New Group window opens automatically, so that you can configure the new group. 30 Portrait Dialogue 6.0

31 Chapter 4: Dialogs 3. Select the operation type that you want. 4. If Quick Design Mode is turned off, the Edit window opens. Enter the appropriate information for the selected operation. For detailed information on the options in this window, see Editing an operation on page When you have entered all the necessary information in the Edit window, click on OK to save the operation. Editing an operation Double-click on the operation that you want to change, right-click on the operation and choose Edit, or select the operation and choose Edit selected item from the Design tab. The Edit window opens. The Edit window can be divided into four parts: main operation information, the Branches tab, the Execute options tab, and the Note tab. Main operation information The main operation information is located on the top of the window. Option Operation ID From group Operation Type Name Operation start/end Operation Active The Operation ID field shows you the ID that the operation has been given. This ID, which is used to identify the operation in tables of the system, cannot be changed. In the From group field, you see the name of the group that is the From group of your operation. In the Type field, you see of which operation type the operation is. In the Name field, you can set or change the name for the operation. The name you enter here, is the name that appears in the Visual Dialogue, so you want this to be fairly short. If you want to limit how long the operation should be active, you can use the Active from field and enter a date for the day from which you want the operation to be active. In the succeeding to field, you enter the date for the last day you want the operation to be active. Dates outside the Start/End date range set in dialog properties will have no effect. If you want to be able to execute the operation, it has to be activated. To activate the operation, check the Active box. If you want to, you can inactivate it to make sure that the operation does not run until you are ready for it to run. If an operation line in a Visual Dialogue has the color red, then the operation is set to inactive. Branches The branch info is displayed in the Branches tab. Visual Dialogue User Guide 31

32 Design View The left side shows all the branches the operation has. The number in front of each branch shows the order the branches will be executed in. Use the arrows on the right side of the list to change the execution order. Option Branch ID Branch Type To group Branch Name Generate participant log Deactivated Use for reporting Parameters The Branch ID field shows you the ID that the branch has been given. This ID, which will be used to identify the branch in tables of the system, cannot be changed. In the type field, you see the branch type. In the To group field, you see the name of the group that your branch leads into. In the Name field, you can set or change the name for the branch. If you check the Generate participant history box, Visual Dialogue will generate history for the participants that are affected by the branch each time the operation is executed. If you do not need the historic information, leave the field empty. This field will only be enabled if you have chosen Decide logging on each operation in dialog properties. By clearing the Deactivate branch checkbox, the branch will be deactivated until you go back to this window and activate it again. This option is also available by right-clicking on the branch itself in Design View. Check Use for reporting if you want the branch to appear in the summary on the overview page. This property can also be used in some standard reports to decide if the branch is shown in the report or not. The parameter fields available depends on what kind of operation type you are working with. See the different parameters for each operation type for more information. Execute options The execute options for an operation are displayed in the Execute options tab. When you add an operation to a dialog, you must decide how the execution of the operation should be started. By default, the option User command is already checked for you. Option User command Waterfall If you select User command, you can execute the operation manually in Execute view at any time. If you select Waterfall, the operation is executed as soon as the prior operation that brings customers into the operations From group is executed. For instance, if you have a Select operation, followed by a Divide operation, and you apply the Completing prior operation option on the Divide operation, the Divide operation will be executed as soon as the Select operation is executed. 32 Portrait Dialogue 6.0

33 Chapter 4: Dialogs Option If you apply this option for an operation that starts in a From group that several operations enter into, the operation will be triggered upon each of the operations leading into the From group. If you want the operation to execute every time the prior operation is finished, check Always run. Check Only run when participants were moved if you want the operation to run only when the prior operation actually moved participants. Scheduled Event triggered If you select Schedule, you can set up a schedule for when you want the operation to be executed. In the Next run fields, enter the date and time that you want the operation to be executed next. This will be the starting point for the schedule. When the operation has been executed, the date and time for the next schedule will be automatically updated here. If you want the operation to be executed only once, check Run only once. This will automatically deselect Run every. If you want to set up a schedule for several executions, go to the Run every field and enter a number specifying how often you want the operation to be executed. For example, if you enter the number 2 and select the Hours option below, the operation will be executed every two hours. You can set the scheduled operation to execute on at most a given number of participants by checking the Run max on [count] participants box and specifying maximum number of participants in the field below. This is similar to manually executing the operation with the Execute advanced popup menu. Note that the operation will only run on schedule if the operation is active and the date is between the dialog s start and end dates, which you can set in the Main Operation Information window. If you select Event triggered, the execution is triggered by the events that are entered in the Respond to these events table. Select the event that you want to trigger the operation, and click on OK. (The events reside in the Dialog database. If you need other events than the ones available, contact your marketing database administrator). To remove an event, deselect the event. Note: By choosing this option, the operation will only run on the relevant participant. If you want the operation to execute every time an event of the selected type(s) occurs, independent of whether the participant is in the from-group of the operation, check Always run. Check Only run if customer is in fromgroup if you want the operation to run only when the participant or customer specified in the event is in the from-group of the operation. Visual Dialogue User Guide 33

34 Design View Notes In the Notes tab, you can add any text that you would like to add to an operation. For example, if you know that some of your coworkers will be working on your dialog, you might use the Notes tab to give instructions to your coworkers about the operation. The information that you add can be edited at any time without affecting the functionality of the operation. Operation types Operation types overview You can choose between different operations depending on what your marketing database administrator makes available for you in the Dialog database. These are the operation types that come with a standard installation of the system: Operation When you are sending to contacts in a dialog, use the Check bounced operation to select the participants whose addresses are OK, and those whose s are bounced (returned) by the mail server. The Check for duplicates operation selects all customers in the from-group that are possible duplicates in the database. See the Technical Documentation for more information on duplicate checking. The Copy to another dialog operation enables you to copy participants from one dialog (the source dialog) to another (the destination dialog). The Create customer operation creates a new customer in your database. This operation needs to be customized depending on the data you have available about the new customer and the structure of your customer database. Because of this, a new operation of this type is created as a scripted operation containing an example script. The Create letter operation uses a message template and information from the customer database, creates a personalized letter in Microsoft Word for each customer in the from-group, and then moves the customer to the to-group. The Create Task operation creates a task for all the participants. You can set a follow-up date and assign the task to a specific workgroup. You can use the Custom operation to create a scripted operation that contains only the bare bones of an operation implementation without any logic. This can be used as a basis for your own customized operation. 34 Portrait Dialogue 6.0

35 Chapter 4: Dialogs Operation The Decision optimization operation takes the customers from a from-group of the Known Customers group type, evaluates them using a decision-optimization rule, and moves the customers into different to-groups based on the outcome. The Divide operation takes the customers from a from-group of the Known Customers group type, compares them to different selection criteria in order of priority, and moves the customers into different to-groups. The to-groups will therefore contain customers who are more alike than the customers in the from-group. The Facebook operation uses a Facebook message template and information from the customer database, creates and posts a personalized facebook posting, and then moves the customer to the to-group. You specify the operations Facebook template when you add the branch to the operation. The Import from file operation takes the customer IDs of customers in a specified text file, checks that each one exists in the database, and then places them in the to-group. If the operation encounters a customer not found in the database, the customer ID is logged in an error file, and the customer is not moved to the to-group. The Inactivate operation inactivates the participants. The Move operation takes the participants in a from-group and simply moves them to another group without performing any other action on them. For example, if you perform an action on customers that reside in an Expiry group, you might want to move them to another group associated with the action that you performed. The Receive response operation detects the registration of a response to a questionnaire for a customer in a from-group and then moves that customer to a to-group. You define which questionnaire should be associated with the operation when you define the branch information for the operation. This will normally be the questionnaire that you used in the Send or Create letter operation earlier in the dialog. The Select operation is used to pick out your target audience (dialog participants) from a group of the All Known Customers group type and move them to a new group. Depending on which branch you choose, the Select operation functions differently. The Send operation uses an message template and information from the customer database, creates and sends a personalized , and then moves the customer to the to-group. You specify the operations template when you add the branch to the operation. Visual Dialogue User Guide 35

36 Design View Operation The Send SMS operation uses an SMS message template and information from the customer database, creates and sends a personalized SMS, and then moves the customer to the to-group. You specify the operations SMS template when you add the branch to the operation. The Set category operation is an operation that makes it possible to set or clear categories in the customer database for selected participants. The Telemarketing operation is an operation that makes it possible to include telemarketing campaigns in a dialog, for instance to use the telephone to ask questions in a questionnaire or to market goods and services. The Twitter operation uses a Twitter message template and information from the customer database, creates and posts a personalized tweet, and then moves the customer to the to-group. You specify the operations Twitter template when you add the branch to the operation. The Check bounced operation Branches OK Bounced Parameters Select participants who s are not bounced (returned) and thus is assumed arrived. Select participants who s are bounced (returned) and thus is not arrived. Parameters: Maximum stale days: The maximum number of days the participant can be in the From Group. If the participant has been in the group longer than this when the operation is run, he or she will be moved. This parameter accepts decimals to allow fractions of a day. Fixed expiry date: After this date, the participants will be moved irrespective of how many days they have been in the From Group. Bounce codes: Select the bounce code(s) representing the reason why the did not arrive to the receiver. The Check for duplicates operation Branches Duplicate check Expiry Parameters Select participants representing customers who might have one or more duplicates in the customer database. See the Technical Documentation for more information on how to set up duplicate checking. See the entry for Expiry in The Divide operation on page Portrait Dialogue 6.0

37 Chapter 4: Dialogs The Copy to another dialog operation Branches Copy to another dialog Parameters Copy participants in the From group to another group in another dialog. Destination group: The group you want to copy the participants into. Note that all the participants might not be copied because the customers they represent might already be participants in the remote dialog. These participants will not be moved to the To group either. Override context: Enter a context value here if you want to copy the participants with a specific context instead of the context they have in the dialog. Expiry See divide expiry. The Create customer operation Branches Create customer Parameters Create a new customer in the database using a customized operation script. The Create letter operation Branches Create letter file Parameters Create a letter to each participant using merge information from the customer domain. Message template: The message template you want to use. This must be a Word document template. Check for blocking category: Clear this checkbox if you want to create letters for customers who have guarded themselves against receiving letters. This should only be done in special circumstances. Customer sort order: This parameter lets you specify how the customers should be sorted when the letter is generated. Expiry See divide expiry. The Create task operation Branches Create task Parameters Creates a task for each participant Task type: The type of the task you want to create. Channel: The channel type for the tasks. Visual Dialogue User Guide 37

38 Design View Branches Parameters Task work group: Assign the tasks to a workgroup for follow up. Follow up date: The follow up date for the tasks. Task description: Assign a task description The Custom operation Branches Parameters Customized branch the customized branch does not contain any logic, you have to implement it yourself as a scripted operation. Parameter may vary depending on how you implement your operation. Decision optimization About decision optimization Decision optimization is the means by which results from Portrait Minercan be executed within dialogs. It provides a smart divide operation, where the choice as to which customer is assigned to which branch of the divide is decided by a real-time analytics rule, generated from the Portrait Optimizer tool from within Portrait Miner. In Visual Dialogue, you use the decision optimization operation to include analytics-based optimized divides in your dialog. The Decision optimization operation Branches Decision branch divide based on an analytics Decision Optimization rule. Parameters Decision optimization: The decision optimization that you want to use. You can pick an existing optimization or you can create a new optimization. The new optimization will then have to be edited in Portrait Optimizer to generate a new optimization result. Optimization outcome: The name of the outcome from the decision optimization rule that will result in a customer being assigned to this branch. Expiry See divide expiry. Creating a new decision optimization Pressing the browse button in a non-configured Decision Optimization operation will open up a wizard, asking whether to use an existing optimization or create new one. Choosing Use an existing optimization will show a list of existing optimizations. Choosing one of them will open up the Configure Decision Optimization Branches window. Choosing Create a new optimization will advance the wizard to the next page, where a new optimization can be created. 38 Portrait Dialogue 6.0

39 Chapter 4: Dialogs Note: Finishing this wizard will create an unfinished optimization. That optimization will need to be defined further in Portrait Miner before the operation can be used in a dialog. All parameters entered in the Create Decision Optimization wizard are saved and can be used and changed from within Portrait Miner. To create new optimization, you need to enter an Optimization name. Other parameters can also be set and used to improve the analysis. The following parameters will be saved into the newly created optimization. These are global constraints and will be editable using the Portrait Optimizer tool within Portrait Miner, when the optimization is finalized. They are global constraints that apply for the whole optimization, regardless of outcome. Click on Finish to complete the wizard. Configuring a decision optimization operation Pressing the Browse button in a decision optimization operation will open up the Configure Decision Optimization Branches window. In this window, it is important to connect the outcomes of the decision optimization to the dialog branches from the operation in Visual Dialogue. It is therefore easier to set this up if the operation in the dialog has been set up with all branches already before you open this window. The red rectangles show which parameters need to be set up for the operation to work fully. In the example, there are three outcomes that need to be mapped to the desired branches by setting values for the Branch mapping (to-group) parameters. Without this mapping, the operation will not run without failing. The values shown for parameters in this window can only be changed when the optimization is created. Thereafter, they are only editable using the Portrait Optimizer tool from within Portrait Miner. The Divide operation Branches Divide using import file divide participants based on customer IDs and possibly contexts in a file. Only participants found in the file will be moved. The operation assumes that the first row in the file contains column headings, and that the ID column is named CustomerID. If you use context, the context column must be named Context. Parameters Import filename: The file that you want to get customer IDs from. Field delimiter: The delimiter used in the import file. Default context: If your dialog uses context (allows multiple customers), it will use the context specified here if the import file does not have a context column. Divide using remote group divide participants based on the participants in another group in another dialog. Only participants found in the remote group will be moved. Divide using call status divide participants based on the call status that they have received in a specific telemarketing project. Only participants Compare to group: The group you want to base your divide on. Telemarketing project: The telemarketing project the participants have been through. Visual Dialogue User Guide 39

40 Design View Branches with one of the specified call statuses will be moved. Parameters Call status (one or more): Only move the participant if he or she received one of these call statuses. Divide using selection divide participants based on a selection. Only participants that fit the selection will be moved. Divide on task complete divide participants based on the completion of a task. Participants will be moved if they have a task of the specified type and the task is set to be completed. Divide on bounced divide participants based on the registration of bounced s. Participants will be moved if the system has registered a bounced with one of the specified bounce codes. Divide on receive response divide participants when they answer a questionnaire. Selection: The selection that you want to use. Task type: The task type you want to check on. Bounce codes: One or more bounce codes to check on. Questionnaire: the participant is moved when he or she submits an answer to this questionnaire. Only answered after: The participant will only be moved if he or she answered the questionnaire on or after this date. Only modified after: The participant will only be moved if he or she modified the questionnaire on or after this date. Divide using address validation divide participants based on the validation of their address. field to check: The customer domain field containing the address to validate. The address is validated using a regular expression defined in the system parameter Check AddressExpr defined in Dialogue Admin. See Technical Guide for more information on system parameters. Divide by random divide participants based on random extracts. Random rule: Specify how you want the random divide to occur. Specify a number of participants randomly selects a fixed number of participants. Specify a percentage of the from group randomly selects a number of participants exactly matching the percentage that you specify. If you Specify a probability in percentage, each par- 40 Portrait Dialogue 6.0

41 Chapter 4: Dialogs Branches Parameters ticipant has the specified probability of being moved regardless of the others. Number/percentage: Number of participants, percentage of participants, or probability in percentage. The parameter accepts decimals: if you specify a number of participants with decimals, it will always be rounded down. Initial selection: You can constrict the extract using an initial selection. Divide using analytic rule divide participants based on an analytic rule created by Portrait Miner or Portrait Explorer. Rule criterion: An expression that describes the rule criterion to use for the divide operation. This expression needs to be constructed by pressing the browse button to the right. It cannot be written directly into the textbox. Note: Browsing will only be available for systems that have Miner integration enabled. Initial Selection: You can constrict the extract using an initial selection. Divide using list divide participants based on list membership. Participants will only be moved if they match customers in the lists. List: The list you want to use. Expiry Move participants after a fixed number of days or after a fixed date. Maximum stale days: The maximum number of days that the participant can be in the fromgroup. If the participant has been in the group longer than this when the operation is run, he or she will be moved. This parameter accepts decimals to allow fractions of a day. Fixed expiry date: After this date, the participants will be moved irrespective of how many days they have been in the from-group. The Facebook operation Branches Create a Facebook Wall Posting publish a Facebook wall posting to each participant using merge information from the customer domain. Parameters Facebook message: The message template you want to use. This must be a Facebook template. Visual Dialogue User Guide 41

42 Design View Branches Parameters Expiry See divide expiry. The Import from file operation Branches Parameters Import select participants into the dialog based Import filename: The file you want to get customer IDs from. The encoding of the file must be on customer IDs and possibly contexts in a file. Only participants found in the file will be selected. in either ANSI or Unicode format. The operation assumes that the first row in the file contains column headings, and that the ID column Field delimiter: The delimiter used in the import is named CustomerID. If you use context, the context column must be named Context. Default context: If your dialog uses context (al- file. lows multiple customers) it will use the context specified here if the import file does not have a context column. The Inactivate operation Branches Parameters Inactivate all inactivates the participants The Move operation Branches Parameters Move move all participants to next group. Expiry See divide expiry. The Receive response operation Branches Answer form received move participants to the next group when they answer a questionnaire. Parameters Questionnaire: When the participant submits an answer to this questionnaire, he or she is moved. Only answers newer than: The participant will only be moved if he or she answered the questionnaire on or after this date. Expiry See divide expiry. 42 Portrait Dialogue 6.0

43 Chapter 4: Dialogs The Select operation Branches Parameters Select using remote group select participants into the dialog based on the participants in a different group in a different dialog. Compare to group: The group you want to base your selection on. Select on response select participants into the dialog when they answer a questionnaire. Questionnaire: When the respondent submits an answer to this questionnaire, he or she is moved into the dialog. Only answered after: The respondent will only be moved into the dialog if he or she answered the questionnaire on or after this date. Only modified after: The respondent will only be moved into the dialog if he or she modified the questionnaire on or after this date. Select using selection select participants into the dialog based on a selection. Selection: The selection you want to use. Select on event select participants into the dialog based on an event. Select by random select participants into the dialog based on random extracts. Random rule: Specify in what way you want the random selection to occur. Specify a number of participants randomly selects a fixed number of participants. Specify a percentage of the fromgroup randomly selects a number of participants exactly matching the percentage you specify. If you Specify a probability in percentage, each participant has the specified probability of being moved regardless of each other. Number/percentage: Number of participants, percentage of participants or probability in percentage. The parameter accepts decimals, if you specify a number of participants with decimals it will always be rounded down. Initial selection: You can constrict the extract using an initial selection Select by analytic rule select participants into the dialog based on an analytic rule created by Portrait Miner or Portrait Explorer. Rule criterion: An expression that describes the rule criterion to use for the select operation. This expression need to be constructed by pressing the browse button to the right, it cannot be written directly into the textbox. Visual Dialogue User Guide 43

44 Design View Branches Parameters Note: Browsing will only be available for systems that have Portrait Miner integration enabled. Initial Selection: You can constrict the extract using an initial selection. Select using list select participants into the dialog based on list membership. List: select participants into the dialog based on list membership. The Send operation Branches Create create and send an to each participant using merge information from the customer domain. Parameters Message template: The message template you want to use. This must be an template. Attachment: Specify a file you want to attach to the . Note that the file you specify must be available to the server your system use to send the s. Check for blocking category: Clear this checkbox if you want to create s for customers who have guarded themselves against receiving s. This should only be done in special circumstances. Max. bundle size: Specifies the number of message to create in each message bundle. Limiting the number of message per bundle will decrease the peak memory usage as the operation runs. The default value is If no value is specified, then all messages will be created in the same bundle. Create with letter attachment create and send an with a Word document attachment to each participant. Both the and the Word document may contain merge information from the customer domain. template: The message template you want to use. This must be an template. Letter template: Specify a message template you want to attach to the . This must be a Word document template. Log letters in customer history: Clear this checkbox if you do not want the Word documents to be logged in the message history log. The messages will always be logged. 44 Portrait Dialogue 6.0

45 Chapter 4: Dialogs Branches Parameters Check for blocking category: Clear this checkbox if you want to create s for customers who have guarded themselves against receiving s. This should only be done in special circumstances. Create admin with letter attachment create and send an with a Word or Rtf document attachment to a specific address. The document attachment may contain merge information from the customer domain. It must be stored as a file, and if one message is produced per customer, only the first message will be attached. To address: The address you want to send the to. From address:the from address that will be used in the . Subject: The subject of the . Body: The body (the actual message) of the . Letter template: Specify a message template you want to attach to the . This must be a Word or Rtf document template. Customer sort order: This parameter lets you specify how the customers should be sorted when the letter attachment is generated. Create admin with report attachment create and send an with a report attachment to a specific address. Note that the report is not connected to the participants in the from-group in any way, and no action will be taken against the participants except moving them to the to-group. To address: The address you want to send the to. From address:the from address that will be used in the . Subject: The subject of the . Body: The body (the actual message) of the . Report template: Specify a report template you want to attach to the . Report format: Specify the report format of the report you want to attach to the . Expiry See divide expiry. The Send SMS operation Branches Create SMS message create and send a SMS to each participant using merge information from the customer domain. Parameters Message template: The message template you want to use. This must be a SMS template. Check for blocking category: Clear this checkbox if you want to create SMS messages for customers who have guarded themselves against receiving SMS messages. This should only be done in special circumstances. Visual Dialogue User Guide 45

46 Design View Branches Expiry Parameters See divide expiry. The Set category operation Branches Parameters Set blocking category set or remove a blocking category for the customers represented by the dialog participants. Option: Mark Set category if you want the category to be set on the customer. Mark Remove category if you want the category to be removed from the customer. Blocking Category: The category you want to be set or removed for the customer. Set simple category set or remove a simple category for the customers represented by the dialog participants. Option: Mark Set category if you want the category to be set on the customer. Mark Remove category if you want the category to be removed from the customer. Simple Category: The category you want to be set or removed for the customer. Set scoring category set or remove a scoring category and a score for the customers represented by the dialog participants. Option: Mark Set category if you want the category to be set on the customer. Mark Remove category if you want the category to be removed from the customer. Scoring Category: The category you want to be set or removed for the customer. Score: The score value you want to set. Set value category set or remove a value category for the customers represented by the dialog participants. Option: Mark Set category if you want the category to be set on the customer. Mark Remove category if you want the category to be removed from the customer. Value Category: The category ant the category value you want to be set or removed for the customer. Expiry See divide expiry. 46 Portrait Dialogue 6.0

47 Chapter 4: Dialogs The Telemarketing operation Branches Parameters Processed by telemarketing this operation sets the participants up for a telemarketing project. After they have been called or for any other reason have been processed through the project, they are moved to the To Group. Expiry See divide expiry. Telemarketing project: The telemarketing project you want to process the participants through. The Twitter operation Branches Parameters Create Tweet publish a tweet to each participant using merge information from the customer domain. Tweet message: The message template you want to use. This must be a Twitter template. Expiry See divide expiry. Comments Comments can be added to the dialog drawing by clicking on Comments in the dialog toolbox. Comments does not change the behavior of a dialog, but can be used to add information about it and mark important parts. You can edit the text pf a comment simply by double-clicking on it and re-size it by dragging its edges. Other actions can be performed in the Design View pop up menu. The dialog toolbox When you are working in Dialog Designer, the Visual Dialogue toolbox is filled with items to help you design the dialog. You can add groups or operations using the Design Tools. You can use the Group Types and Operation Types groups of the toolbox to quickly add specific types of groups and operations to the dialog. Design View popup menus When you right-click on various elements of the dialog, popup menus appear. Right-clicking on a group Menu option Edit Background color Edit the properties of the group. Edit the color of the group. The color pop up will appear, where you can choose between a set of standard colors or create your own colors using the More colors option. Visual Dialogue User Guide 47

48 Design View Menu option Text Copy Delete Edit the color of the text in the group. The color pop up will appear, where you can choose between a set of standard colors or create your own colors using the More colors option. Copy the group. Delete the group. Right-clicking on an operation Menu option Edit Operation Active Edit the properties of the operation. Set the operation active or inactive. Operation script > Show script Open the script view (only enabled if one or more branches are scripted). Operation script > Convert to scripted branch... Operation script > Revert to standard branch Copy Delete Edit selection/template/tm project/questionnaire Convert the first branch of the operation to a scripted branch. Revert all the branches of the operation to standard implementation (not scripted). Copy the operation. Delete the operation. If your operation uses any of these components, they can be edited directly from here. Right-clicking on a branch Menu option Edit Branch deactivated Straighten Line Operation script > Show script Operation script > Convert to scripted branch... Operation script > Revert to standard branch Copy Edit the properties of the branch. Set the branch active or deactivated. If you have segmented a branch line, you can merge the segments back into one line. Open the script view (only enabled if the branch is scripted). Convert the branch to a scripted branch. Revert the branch to standard implementation (not scripted). Copy the branch. 48 Portrait Dialogue 6.0

49 Chapter 4: Dialogs Menu option Delete Edit selection/template/tm project/questionnaire Delete the branch. If your branch uses any of these components, they can be edited directly from here. Right-clicking on a comment Menu option Edit Background color Text Send to back Text alignment Copy Delete Edit the text of the comment. Change the color of the comment. The color pop up will appear, where you can choose between a set of standard colors or create your own colors using the More colors option. Change the color of the comment text. The color pop up will appear, where you can choose between a set of standard colors or create your own colors using the More colors option. Make the comment appear behind all other comments in the dialog drawing. Note that comments are always shown behind groups and operations. Change the alignment of the comment text. Copy the comment. Delete the comment. Copy and paste in Design View You can copy and paste groups, operations, and branches in Design View. To copy and paste objects in the design canvas: 1. Select the objects: Either select an area with the mouse, or select multiple objects by clicking on the objects while holding down the Shift key. 2. Copy the objects: Either choose Copy from the Home tab, or press Ctrl+C, or right-click on the object(s) and choose Copy. 3. Paste the objects: Either choose Paste from the Home tab, or press Ctrl+V, or right-click on the object(s) and choose Paste. You can paste objects from one dialog into another dialog as long as both dialogs are opened in the same Visual Dialogue window. The Design tab When you work with a dialog in Design View, a Design tab is added to the ribbon. Visual Dialogue User Guide 49

50 Design View Tab option Active items Explore Save Close Properties Navigate In Out Normal Edit selected item Text Background color Text alignment Send to back Straighten Line Edit text color Shows a list of all the items you have open. Open the Explorer window or a main component browser window. Save the dialog are working with. Close the dialog you are working with. Show properties of the dialog. Show a navigation pan where you can easily navigate to different parts ot the dialog you are working with. Increase zoom by approximate 50 percent. Decrease zoom by approximate 50 percent. Set zoom to normal. Open the properties window for the selected item. Change the text color in a group or comment. The color drop down will appear, where you can choose between a set of standard colors or create your own colors using the More colors option. Change the color of a group or comment. The color drop down will appear, where you can choose between a set of standard colors or create your own colors using the More colors option. Change the alignment of a comment text. Make a comment appear behind all other comments in the dialog drawing. Note that comments are always shown behind groups and operations. If you have segmented a branch line, you can merge the segments back into one line. Edit the text color of the selected groups. Align left edges Align horizontal centers Align right edges Aligns the selected groups and branch points to the left edge of the leftmost component selected. Moves the selected groups and branch points horizontally until their centers are aligned with the selected component nearest the center. Aligns the selected groups and branch points to the right edge of the rightmost component selected. 50 Portrait Dialogue 6.0

51 Chapter 4: Dialogs Tab option Align tops Aligns the selected groups and branch points to the top edge of the topmost component selected. Align vertical centers Moves the selected groups and branch points vertically until their centers are aligned with the selected component nearest the center. Align bottoms Space equally, horizontally Space equally, vertically Show script Convert to scripted branch... Revert to standard branch Telemarketing projects Aligns the selected groups and branch points to the bottom edge of the bottommost component selected. Horizontally aligns three or more selected groups and branch points so that the middle components are equidistantly spaced between the outer components. Moves the selected groups and branch points vertically until their centers are aligned with the selected component nearest the center. Open the script view (only enabled if the branch is scripted). Convert the branch to a scripted branch. Revert the branch to standard implementation (not scripted). Open the Telemarketing Project Designer. If you have created a new dialog, this is only possible after you have saved the dialog for the first time. Execute View About Execute View In Execute View, you can execute operations, view and manipulate participants, and view dialog history. Executing an operation The Dialogue Server automatically executes operations in a dialog according to their individual execute options. However, operations with the execute option User Command can be started manually from Execute View. To start an operation manually in Execute View, select the operation and right-click to display a popup menu: The popup menu contains five menu items regarding executing operations: Menu option Execute Executes the operation. Execute advanced Executes the operation with a maximum (limited) number of participants. You set this number before the operation is executed. Abort execution Aborts an execution currently running. Visual Dialogue User Guide 51

52 Execute View Menu option Execution details Execution monitor Display the Execution Progress window. Display the Execution Monitor window. The Execution Progress window While an operation is executing it is marked with a green color. If execution fails, the operation will be marked with a red color. When the operation is marked with one of these colors, you can double-click on the operation, or choose Execute details from the popup menu. This will display the Execution Progress window, which shows detailed information about the execution that is currently running or has failed. Participant summary To open the Participant Summary window, right-click on an empty area in the Execute View canvas and select Participant Summary, or choose Participant summary from the Execute tab. The Participant Summary offers functionality and information pertaining to participants in all groups in a dialog. Participant Summary window The Participant Summary Home ribbon provides the following features: Option Close Export Move to Group Inactivate View Participants Refresh (F5) Show Chart Select Columns Closes the Participant Summary window. Exports all participants in the selected group to a file. Moves all participants in the selected group to another group. Inactivates all participants in the selected group. Double-click on a group in the group list, or click on. This opens a new window displaying a list of the participants in the selected group (see The participants window on page 53). Refreshes participants information for all groups. Displays/hides a chart at the bottom of the window, graphically displaying the participant count in all groups. Open the Select Columns window to let you configure the set of columns displayed. Participants window The participants window offers functionality and information pertaining to participants in a single group. See The participants window on page 53 for details. 52 Portrait Dialogue 6.0

53 Chapter 4: Dialogs The participants window To open the participants window, double-click on a group in Execute View, or double-click on the desired group in the Participant Summary window. The participants window offers functionality and information pertaining to participants in a single group. The participants window ribbons provides the following features: Option Close Move to group Inactivate Test Merge Template Open in Customer View Duplicate Check Close the Participants window. Move the selected participant(s) to another group. Inactivate the selected participant(s). Create a test message based on a template used in the dialog and the selected participant. Open the selected user in Customer View. Open Customer View and display potential duplicates of the selected customer. Note: This option is only available if duplicate checking has been configured in Customer Domain setup (Dialogue Admin). Export Show Details Select Columns Max. in list Refresh (F5) Search Export the selected participant(s) to a file. Display/hide details for a selected participant (see Details below). Open the Select Columns window to let you configure the set of columns displayed. This number limits the number of participants displayed. Setting this field to a high number may cause decreased performance for the current window. Refresh participant information. This ribbon tab provides simple search functionality for filtering the participants. Details Clicking on the Details button displays details for a selected participant using five views: Visual Dialogue User Guide 53

54 Execute View View Participant history The Participant history view lists the selected participant s history in the dialog. The table lists the participant s path through the dialog. Note: Participant logging must be turned in order to view logged participant history information. This can be done in Dialog Properties (Advanced tab) for the entire dialog, or for each operation. Telemarketing history Messages Answer forms Activity & tasks The Telemarketing history view lists all Telemarketing projects in the dialog, and the status and history for the participant in each of the projects he or she has participated. Messages View lists all messages related to the customer represented by the selected participant. For each message the status is shown, e.g. send errors of an . Select a message in the list and click View to view the message. The Answer forms view lists all answer forms related to the customer represented by the selected participant. Select an answer form in the list and click View to view the answer form. The Activities & tasks view lists all activities and tasks related to the customer represented by the selected participant. Select an activity or task in the list and click View to view the activity or task. Running reports from the participants window If integrated reporting is enabled, and reports of the system type Customer report or Participant report are defined, a Report menu is added to the menu bar. See Integrated reporting overview on page 246 for details. The operation log To open the Operation Log window, right-click on an operation, or right-click on an empty part of the Execute View canvas, and choose Operation Log. The operation log presents logged information about all operation executions. To see the logged information, select the desired operation in the Operation table. Detailed operation log information is displayed using three views. See Operation log views on page 54 for details. Operation log views Detailed operation log information is displayed using three views: 1. Summary Displays summary information about an operation. 54 Portrait Dialogue 6.0

55 Chapter 4: Dialogs Option From group Total runs Total participants First run Last run Branch details The operation s from-group. The total number of runs of the operation. The total number of participants moved through the operation. The time and date for the operation s first run The time and date for the operation s last run This table contains summary information about each of the operation s branches. 2. All runs Displays detailed information about all runs of an operation. Option All runs of operation This view contains all the runs of the operation. It has the following columns: Start time the start time of the operation run Duration the duration of the operation run Participants the number of participants moved through the operation run Execute mode describes how the operation was started. There are four possible values: Manual execution The operation was manually executed by a user in Visual Dialogue Waterfall The operation was started using the waterfall mechanism Scheduler The operation was started by the scheduler mechanism Event The operation was triggered by an event For more information, see Execute Options. Executed by user the system user that executed the operation run Operation log ID the unique database id for the operation run in the log table Furthermore, the operation run can be expanded in order to see details about each branch for the operation run. Click on the plus sign to open the branch table. The branch table has the following columns: Branch name the name of the operation branch Start time the start time of the operation branch run Duration the duration of the operation branch run Participants the number of participants moved through the operation branch run Priority The priority of the operation branch. The branch with the highest priority (lowest number) is executed first. Visual Dialogue User Guide 55

56 Execute View Option Branch log ID the unique database id for the operation branch run in the log table 3. Time graph Displays information about the participants moved through the operation as a function of time. Option Title Legends Stairs Marks Check this option to display the graph s title Check this option to display the graph s legends Check this option to display the lines in the graph as stairs Check this option to display marks (key numbers) for the lines in the graph To customize the graph, select Customize from the Home ribbon tab. The Execution Monitor The Execution Monitor shows you all activity related to dialog operations that are executed in the background, i.e. waterfall, scheduled, and event-triggered operations. Note: Only operations in the dialog that you used to open the view will be shown. The list view shows you all operations executing in the background at the moment, as well as all background operations that have failed. In the latter case, the lower pane shows information relating to the failure of the operation. Execution Monitor ribbon Option Close Restart Abort Execution Progress Remove Refresh Auto Refresh Closes the Execution Monitor window. Try to execute the selected task once more. A background operation will automatically try to execute three times before it stops because of failure. You can then manually restart the task after you have fixed the cause of the failure. Abort the execution of the selected task. Show the Execution Progress window for the selected task. Delete the selected task. Refresh the view Automatically refresh the view every second. 56 Portrait Dialogue 6.0

57 Chapter 4: Dialogs Option Select Columns Go to Operation Open the Select Columns window to let you configure the set of columns displayed. Center on the selected task in Execute View. Execute View popup menus When you right-click various elements of a dialog, popup menus appear. Right-clicking on a group Menu option View Participants Inactivate Participants Move Participants Export Participants... Reports Open the Participants dialog. Here you can view the participants in the group. You can view the participant in customer view, inactivate individual participants, view answer forms returned by the participants or move individual participants directly to another group. Inactivate all the participants in the group. This will mark the participants as inactive, and they are no longer part of the dialog. Move all the participants in the group directly to another group. Export the participants to a file. You are presented with a wizard that allows you to customize the aspects of the export. Run applicable integrated reports. See Integrated reporting overview on page 246 and Standard reports on page 247 for details. Right-clicking on an operation Menu option Execute Execute advanced... Abort execution Execution details Execution monitor Operation log Execute the operation. You have to set the User command execute option to be able to do this. Execute the operation with a maximum number of participants. You set this number before the operation is executed. Abort an executing operation. Display the execution progress window. Display the execution monitor. Display the operation log window. Edit selection/template/tm project/questionnaire If your operation uses any of these components, they can be edited directly from here. Visual Dialogue User Guide 57

58 Execute View Menu option Reports Run applicable integrated reports. See Integrated reporting overview on page 246 and Standard reports on page 247 for details. Right-clicking on branches Menu option Edit selection/template/tm project/questionnaire Reports If your branch uses any of these components, they can be edited directly from here. Run applicable integrated reports. See Integrated reporting overview on page 246 and Standard reports on page 247 for details. Right-clicking when no components are selected Menu option Participant summary Execution monitor Operation log Reports The Participant summary offers functionality and overview related to participants in all groups in a dialog. Display the execution monitor. The Operation log presents logged information about all operation executions. Run applicable integrated reports. See Integrated reporting overview on page 246 and Standard reports on page 247 for details. The Execute tab When you work with a dialog in Execute View, an Execute tab is added to the ribbon. Tab option Active items Explore Save Close Properties Navigate In Out Shows a list of all the items you have open. Open the Explorer window or a main component browser window. Save the dialog are working with. Close the dialog you are working with. Show properties of the dialog. Show a navigation pan where you can easily navigate to different parts ot the dialog you are working with. Increase zoom by approximate 50 percent. Decrease zoom by approximate 50 percent. 58 Portrait Dialogue 6.0

59 Chapter 4: Dialogs Tab option Normal Execute Advanced Abort Execution Monitor View Participants Move Participants Inactivate Participants Export participants... Inactivate all participants Clear dialog Participant summary Operation log Refresh Reports Set zoom to normal. Execute the operation. You have to set the User command execute option to be able to do this. Execute the operation with a maximum number of participants. You set this number before the operation is executed. Aborts an executing operation. Displays the execution monitor. Open the Participants dialog. Here you can view the participants in the group. You can view the participant in customer view, inactivate individual participants, view answer forms returned by the participants or move individual participants directly to another group. Move all the participants in the group directly to another group. This task is as a background task. Inactivate all the participants in the group. This will mark the participants as inactive, and they are no longer part of the dialog. This task is run as a background task. Export the participants to a file. You are presented with a wizard that allows you to customize the aspects of the export. Deactivate all the participants in the dialog. This task is run as a background task. Effectively clear the dialog. All participants are deactivated, and all generated history logs are deleted. You can also choose to delete message logs and activity logs that were created for the customers who have been participating in the dialog. This task is run as a background task. Display the Participant Summary window. The Operation log presents logged information about all operation executions. Update the count of participants shown in the groups. This can be useful if you have a scheduled operation, an operation that executes when a prior operation has executed or an operation triggered by an event. Run applicable integrated reports. See Integrated reporting overview on page 246 and Standard reports on page 247 for details. Visual Dialogue User Guide 59

60 Script View Script View Scripting an operation When you script an operation, you move the implementation of a branch from the set of predefined operations installed in your system to a wholly customized implementation in the dialog. Attention: Scripting operations require a thorough understanding of scripting technology in general, and of the Visual Dialogue Operation Framework in particular. If you have scripted an operation, a small S will appear on the right-hand side of it. You will also see a Scripts tab at the bottom. If you double-click on the S, the view will be switched to the script implementation. To script a branch, simply right-click on the branch you want to script, choose Scripting > Convert to scripted branch.... In the window that appears, click on Yes if you want to base your script on the standard implementation of the branch; click on No if you want to start with a completely empty script. When you are finished with this, Scripting View will be shown. The right-hand side of the view shows you all the operations in your dialog. Operations with one or more scripted branches are shown with a red bullet. Below the operations are all the branches of the selected operation. You can check the box beside each branch to script it, or clear the checkbox if you want to revert to the standard branch implementation. The left-hand side of the view is the actual script editor. The Reference Documentation contains information on the operation framework and what you need to do to implement an operation. The Script tab When you work in Script View, a Script tab is added to the ribbon. Tab option Active items Explore Save Close Properties Language Script templates Syntax check Shows a list of all the items you have open. Open the Explorer window or a main component browser window. Save the dialog are working with. Close the dialog you are working with. Show properties of the dialog. Select the script language. JScript, VBScript and PerlScript is supported. Replace your current script code with code from a script template. The templates are the implementation of all the standard operations in the system. Use the syntax check to validate the syntax of your script. Note that only the syntax of the script is checked, this will for instance not catch misspelled method an variable names. 60 Portrait Dialogue 6.0

61 Chapter 4: Dialogs Tab option Execute Advanced Abort Line numbers Hide scripts Execute the operation. You have to set the User command execute option to be able to do this. Execute the operation with a maximum number of participants. You set this number before the operation is executed. Aborts an executing operation. Show or hide line number in the script editor. Show or hide the script view. The Options tab When you work with a dialog, an Options tab is added to the ribbon. Tab option Skin Show IDs Show Execute Icons Show Comments Copy image to clipboard Allows you to choose the skin used in a dialog. A skin defines the appearance of all objects used in a dialog. If this box is checked, the internal IDs of groups and operations are shown in the Dialog Designer. If this box is checked, execute icons are shown in the Dialog Designer. Execute icons visualize the execute options that you have set for your operations. If this box is checked, comments are shown in the Dialog Designer. Make a copy of the dialog image and place it on the clipboard. The copied image can then be pasted into an image-editor or a document. Copy image to file Save a copy of the dialog image to a Windows bitmap (bmp) or JPEG compliant (jpg) file. Because of limitations in the Windows operating system, copying large images to the clipboard sometimes fails, and if this happens you can copy the image to a file instead of the clipboard, to manipulate it or use it in other applications. Quick design mode Simple operation list Show grid Snap to grid Show scripts Enable Quick Design Mode, allowing you to easily place groups and operations in a dialog. Use this feature to first draw a dialog, in which you can later configure the groups and operations used. If checked, the list of operations shown in the dialog toolbox is a list with small icons. If not checked, larger icons will be used. Display the canvas grid. Enable snap to grid, making it easier to place objects accurately in the design canvas. Show or hide the script view. Visual Dialogue User Guide 61

62 Dialog properties Tab option Save Dialog as Template Save the dialog as a Dialog Template. Dialog properties The dialog properties window can be opened either from the File tab or from the Dialog Browser. It consists of three tabs. The General tab Field Name State Start/End Date Deactivate dialog The name of the dialog. The state the dialog is in. This is only an informative field and does not have any influence on how you work with the dialog or how it behaves. If you want to limit how long the dialog should be active, you can go to the Start Date field and enter a date for the day from which you want the dialog to be active. In the succeeding End Date field, you enter the date for the last day you want the dialog to be active. If this box is checked, the entire dialog is deactivated and cannot be executed. Note: After you import a dialog from a file, the imported dialog will always be marked as deactivated, and you will need to clear this box to activate it. Customer domain The customer domain the dialog gets its participants from. Multiple occurrences of customers If this is set to yes, the same customer may figure as participant in the dialog more than once, provided the customer has different context information attached to each occurrence. If it is set to no, the same customer can only occur one place in the dialog at any time. Created Created by Last modified Last modified by The date and time the dialog was created. The login name of the user who created the dialog. The date and time the dialog was last modified. The login name of the user who last modified the dialog. 62 Portrait Dialogue 6.0

63 Chapter 4: Dialogs The Advanced tab Field Path Enable participant logging Budget start cost Actual start cost Currency code The path to the directory where the dialog stores all its message templates, messages and log files. If you change this, make sure it points to a share that can be reached by everyone who will use the dialog. Check this to have additional logs created when the dialog is executed. This provides for more basis for statistics and analyses but will slow down execution, in some instances noticeable. If you choose Decide logging on each operation, you can turn logging on or off on each operation. If you choose Always generate participant log, additional logs will always be created. The budgeted cost for the initialization of the dialog as a whole. The actual cost for the initialization of the dialog as a whole. The currency code you want to use in your budget. Enable customer login Check this if you want to enable customers to log in and answer questionnaires using their participant ID in the dialog. This is useful if your dialog produces messages with web links to a questionnaire. The Notes tab On this tab you can enter notes about the dialog. Telemarketing projects About telemarketing projects When using a telemarketing operation in a Dialog, you can set up telemarketing projects that define how the different telemarketing operations should function. For information on how to set up a telemarketing project, see Creating a new telemarketing project on page 64. How to open the telemarketing projects list The telemarketing projects list can be opened from Visual Dialogue by choosing Dialog > Telemarketing projects from the menu bar. Telemarketing projects overview When you open Telemarketing Projects, a list of all telemarketing projects is displayed. Here, you add new or change telemarketing projects. For information on how to do this, see Creating a new telemarketing project on page 64. Telemarketing project properties When you create a new project or editing an existing project, the Properties window opens: Visual Dialogue User Guide 63

64 Telemarketing projects The General tab In this tab, you can set information relating to questionnaires and customer data. For detailed information on how to do this, see Creating a new telemarketing project on page 64. The Operators tab In this tab, you can set the operators who will be allowed to work on participants in the telemarketing project. For information on how to do this, see Setting up legal operators for a telemarketing project on page 66. The Call rules tab In this tab, you can set the call statuses that will apply for the project. For information on how to do this, see Setting up reasons for automatic movement of participants on page 66. The Activity setup tab In this tab, you can set activity types for the project. For further information on how to do this, see Creating a new telemarketing project on page 64. The Advanced tab In this tab, you can set advanced options, like using a customized SQL, for the project. For information on how to do this, see Setting advanced options on page 67. What is an operator? In a telemarketing operation, you must have physical people who make the telephone calls to the participants in the dialog. These people are the operators. For each telemarketing project, and therefore for each telemarketing operation, you can define a group of operators who are allowed to handle the participants in the from-group of the operation. For information on how to do this, see Setting up legal operators for a telemarketing project on page 66. What is a call status? In a telemarketing call situation, several circumstances or conditions can apply. For instance, some participants may not like to answer questionnaires by phone, some may not be home when the operator calls, and others may have changed their telephone number or moved to another address. To differentiate between the circumstances that can apply, the operators can set different statuses for customers who have been called. These statuses are called call statuses. In a telemarketing project, you can use these statuses to define specific reasons for moving participants out of the telemarketing calling queue and into the telemarketing operations to-group. For information on how to do this, see Setting up reasons for automatic movement of participants on page 66. Creating a new telemarketing project You can create as many telemarketing projects as you like. However, only one project can be used in a given telemarketing operation. How to create a new telemarketing project 1. Open the Telemarketing Projects list by choosing Telemarketing projects from the Design tab. 64 Portrait Dialogue 6.0

65 Chapter 4: Dialogs 2. Click on New. The New Telemarketing Projects wizard opens. 3. If you want to create a new (blank) telemarketing project, choose Create a blank project. If, on the other hand, you want to copy an existing telemarketing project, choose Copy an existing telemarketing project. 4. If you are copying an existing telemarketing project, choose which project to copy. 5. Click on Finish. The Telemarketing Project Properties window opens. 6. In the Telemarketing project name field, give the new project a name. 7. In the field, enter a description of the project that will help you or others to understand the purpose of the project later on. 8. In the General tab, you can set information related to questionnaires and customer data: In the Questionnaire field, choose the questionnaire that you want the participants to answer. In the Layout field, choose a layout that you have defined for the questionnaire, to be used in the Telemarketing web application. If you have not created any layouts or if you choose Default layout, a simple default layout will be used. Check the Enable response tracking box if you want to track the progress of respondents as they answer questionnaires. Note that response tracking is not available if you use the default layout. Check the Show customer data box if you want customer data to be visible to operators in the Telemarketing web application. Check the Allow update of customer box if you want operators to be able to edit customer data in the Telemarketing web application. You can set Project start date and Project end date to limit the time that the project will be available in the Telemarketing web application. 9. In the Operators tab, you can specify the operators who will be allowed to work on the participants in the telemarketing project. For detailed information on how to do this, see Setting up legal operators for a telemarketing project on page In the Call rules tab, you can set the call statuses that will apply for the project: In the Allowed calls field, enter the number of times that you think operators should be allowed to call customers. In the Time between calls field, enter the number of minutes that will be applied by the Telemarketing web application when it suggests a new time for an operator to call the same customer again after a call. In the Move participants when list, you can set the call status, which will trigger movement of the participant to the to group. For further information on how to do this, see Setting up reasons for automatic movement of participants on page In the Activity setup tab, you can set activity types for the project: In the Activity type field, choose what type of activity you want to create if you have enabled activity posting. In the Post activity rule field, choose when you want to post activities. Visual Dialogue User Guide 65

66 Telemarketing projects 12. In the Advanced tab, you can set up your project to use a customized SQL statement. For detailed information on how to do this, see Setting advanced options on page 67. Setting up legal operators for a telemarketing project For each project that you define, you must set up the operators that are allowed to make calls in this project. How to set up legal operators for a project 1. Open the Project Properties for the telemarketing project. 2. Go to the Operators tab. 3. Click on + (the plus sign). This opens the Select Groups or Users window. 4. In the Select Groups or Users window, select the operators you want to apply in the project. To select several operators, hold down the Ctrl key while you click on the operator names you want. Note: The operators available in the Add Operators window are defined by the marketing database administrator or someone else responsible for Visual Dialog. Thus, you must contact this person if you need to add other operators than the ones available in the list. 5. Click on OK to add the selected operators to the list on the Operators tab. 6. Click on OK to save your settings. If you need to remove an operator from the list of operators, simply select the unwanted operator and click on - (the minus sign). Setting up reasons for automatic movement of participants On basis of the call statuses that the operators set on the customers, the Telemarketing Projects lets you define specific criteria, or reasons, that automatically send dialog participants out of the Telemarketing calling queue and into the Telemarketing operations To group. This prevents participants from being processed by the Telemarketing web application and the operators forever? How to set up reasons for automatic movement of a participant 1. Open the Project Properties for the telemarketing project. 2. Go to the Call rules tab. When you open the Call rules tab for a new standard project, some items are added for you by default. These items are set by your marketing database administrator or someone else responsible for Visual Dialogue. However, by using the Add and Remove buttons above the list, you can apply the reasons you want. Note: The gray items at the top of the list are obligatorily checked and cannot be cleared. 3. In the Move participants when list, select the reasons that will remove dialog participants from the Telemarketing web applications calling queue and move them into the Telemarketing operations To group. 4. Click on OK to save your settings. 66 Portrait Dialogue 6.0

67 Chapter 4: Dialogs Setting advanced options In the Advanced tab, you can set up your project to use a customized SQL statement. This is a very powerful option, as it enables you to change the way the Dialogue Server fetches telemarketing participants to be called. Check the Use customized SQL box if you want to use a customized SQL statement. This will enable the Get servergenerated SQL and Choose SQL... buttons. Get servergenerated SQL will get a copy of the SQL statement that the server uses to fetch telemarketing participants and place it on the clipboard. You can use this as a basis for your customized SQL statement. Choose SQL... lets you choose a customized SQL statement. This SQL statement must reside in the SQL repository that is accessible from Dialogue Admin. Note that a customized SQL statement has to satisfy a number of conditions to work. Writing a customized SQL statement When you write a customized SQL statement to use in a telemarketing project, there are a number of conditions the SQL has to satisfy: The SQL statement must always return the fields mh_participant_id, mh_customer_id, mh_context, ccpa_current_call_no, ccpa_next_call_datetime, ccpa_assigned_user_name, and ccpa_locked_by_user_name. The SQL statement must also return all the fields that are marked as Show in Telemarketing web in the customer domain. All parameters used in the SQL statement must have a unique name. This is very important, as using SQL statements with nonunique names can make the Dialogue Server stop responding completely. You can use five different parameters: dg_id (dialog from-group), ccp_id (telemarketing project ID), sui_user_name (username), cd_id (customer domain ID), and ct_name (channel type name of telemarketing blocking channel). The Dialogue Server parses the statement and assigns the apropriate value to all parameters that begin with one of these names; i.e. both ccp_id1 and ccp_id2 will get the value of the telemarketing project ID. If your telemarketing operation has more than one from-group, you have to hardcode the different group IDs in the SQL statement. Note that this does not prevent you from using the telemarketing project in more than one operation, as long as none of the operations has more than one from-group. Browsing dialogs To see all defined dialogs, choose Explore > Dialogs from the Home tab in Visual Dialogue. The Browse Dialogs window opens. Sorting the dialog list To sort selections, click on the desired column in the heading of the selection list. Visual Dialogue User Guide 67

68 Dialog security Selecting columns To configure the set of columns displayed in the list, choose Select Columns from the View tab. The columns can also be rearranged by dragging and dropping them to different column positions. Dialog properties To review or edit the properties of a dialog (e.g. the name or the description), select a single dialog and choose Properties from the Home tab. The Dialog Properties window opens. Opening a dialog To open a dialog in About Dialog Designer on page 27, double-click a single dialog in the list, or choose Open from the Home tab. Deleting a dialog To delete a dialog, mark a single dialog and choose Delete from the Home tab. This task is run as a background task. Preview A preview image of the dialog is shown in the bottom of the browser. To turn the preview on or off, click the Preview button on the Home tab. Dialogs marked with a red mark A red mark on the icon of a dialog indicates that the dialog is deactivated. See Dialog properties on page 62 for more information. Dialog security Dialogs have built-in security functionality. This allows you to control a dialog s access rights and permissions. Security settings are applied at both user and user-group levels. The security settings window To open the security settings window for a dialog, do one of the following: Right-click on the desired dialog in the Browse Dialogs window and choose Security. Open a dialog and click on the padlock button in the File ribbon tab: The User group or user window lists all users and user groups with any access rights or permissions for the dialog. Select a user or user group to see their permissions. The permissions are listed below in the Access right or permission window. 68 Portrait Dialogue 6.0

69 Chapter 4: Dialogs Disabled permissions (gray) are global permissions and thus cannot be changed or deleted. Adding users and user groups Click on Add to add a user or user group. The Select Groups or Users window opens. Select the desired user or user group and click on OK. The selected user or group is added to the User group or user list in the security window. Then select the permissions and access rights desired for the user or user group. Access rights and permissions The access rights and permissions available per user and user group are: Delete dialog Permission to delete the entire dialog in Dialog Browser. Execute dialog Permission to work on the dialog in Execute View. This includes executing operations and moving participants from one group to another. Edit dialog Permission to work on the dialog in Design View. This includes adding, editing and deleting groups and operations. Clear dialog Permission to clear the dialog s execute data. This includes removing all participants and all history from the dialog. Clearing a dialog is done from the dialog s Execute View. Dialog templates What is a dialog template? Dialog Templates are used to create templates for quickly creating a dialog in Visual Dialogue, and to create templates for Guided Dialog Setup. The templates consist of two parts: 1. The Dialog Flow (Design View) 2. Definition for pages, sections and questions (Guided Setup) The Guided Setup is only needed for templates intended for use in Portrait HQ, and will have no effect on Dialogs created in Visual Dialogue. In Visual Dialogue, the link to the dialog templates list is located under the Manage area on the left menu Explorer bar. Creating a new dialog template To create a new dialog template, choose Dialog Template from the Create tab. Enter a name for your dialog template, and choose the domain it should be used in. Set default options for your template. This will be inherited by dialogs based on this template. Click on Finish to create your dialog template and go to Design View. Visual Dialogue User Guide 69

70 The Dialog Template Designer The Dialog Template Designer The Dialog Template Designer is used to design your templates. There are two views: Design and Guided Setup. Design View is used to design your dialog flow. The dialog design is done in the same way as you design a standard dialog. Guided Setup View is used to define pages, sections, and questions to use your template in Guided Dialog Setup. Guided setup What is guided setup? Guided setup enables users to configure dialogs without having to use Visual Dialogue. This is done by defining a set of questions that the user must answer. The answers are then used to configure the dialog automatically. The questions are answered within the Portrait HQ application. When the answers have been completed, a new dialog will be created based on the answers. If the user changes the answers later, the changes will be applied to the dialog. Questions about the selection and template are defined in Visual Dialogue. The questions are answered by specifying the selection and template in Portrait HQ. The answers are applied to a new dialog. Defining a guided setup A guided setup consists of three different items: steps, sections, and questions. Steps are used to divide the setup into different pages, sections are used to divide each page into logical parts, and questions are used to get the actual input from the user. Example: Send out s and Send out reminder could be steps, Select target group and Select template could be sections, and Target group, template, and Don't send to customers who could be questions. Guided Setup Designer To use guided setup in a dialog template, you need to enabled guided dialog setup on the Campaign setup tab in the dialog template properties box. Guided Setup Designer has two main parts. The left part shows you a tree view of all the steps, sections, and questions that have been defined for the setup. This is also where you add steps, sections, and questions. The right-hand view shows a simple preview of the currently selected step. Guided setup step Right-click in the tree view and choose New step..., or choose Step from the Guided Setup tab, to create a new step. Double-click or press Enter on an existing step to edit it. 70 Portrait Dialogue 6.0

71 Chapter 4: Dialogs Option Setup step name Key The name of the step. This is the name shown to the user in Portrait HQ. A description of the step This an internal key used by the system. You do not need to change this. Guided setup section Right-click in the tree view and choose New section..., or choose Section from the Guided Setup tab, to create a new section. Double-click or press Enter on an existing section to edit it. Field Setup section caption Instructions The section caption. This is the caption shown to the user in Portrait HQ. Instructions that are shown to the user in Portrait HQ. Setup question Guided setup question Right-click in the tree view and choose New question..., or choose Question from the Guided Setup tab, to create a new question. Double-click or press enter on an existing question to edit it. Field Question caption Instructions Answer required Key The question caption. This is the caption shown to the user in Portrait HQ. Instructions that are shown to the user in Portrait HQ. If this is checked, the user is required to answer this question before the setup is regarded as completed This is an internal key used by the system. You do not need to change this. The Type tab In the Type tab, you can select what type of question you want. There are two types of questions, plain checkbox questions and branch parameter questions. Checkbox questions are typically used to enable or disable other questions or branches. They can be checked or not checked by default. Branch parameter questions are used to take input from the user to configure dialog branches. Field Operation Branch Select the operation you want to configure. Select the branch of the operation you want to configure. Visual Dialogue User Guide 71

72 Guided setup Field Parameter Min. value Max. value Default value Ask for treatment Select the parameter of the operation you want to configure. Here you can enter a minimum value for the answer from the user. This is only applicable to some types of parameters. Here you can enter a maximum value for the answer from the user. This is only applicable to some types of parameters. Here you can enter a default value that will be automatically selected for the user. If you check this, the user will have to choose from a list of treatments from the Portrait HQ campaign she is working with when answering the question. The treatment will be assigned to the branch when the dialog is configured. The Conditions tab Conditions are used to enable or disable the question you are configuring based on whether another question in the setup has been answered or not. You typically base this on the answer to a checkbox question. The Additional parameters tab Using the Additional parameters tab, you can configure branch parameters in the dialog in addition to the one you specified on the Type tab. The parameters must be of the same type, and all the parameters will be assigned the same value, depending on how the user answers the question. Use the Add, Edit, and Delete buttons to set up additional parameters. The Activate branches tab In the Activate branches tab, you can activate or deactivate branches based on whether the question you are configuring have been answered or not. You typically use this with a checkbox question to enable or disable parts of your dialog. Use the Add, Edit, and Delete buttons to set up additional parameters. The Guided Setup tab When you work in Guided Setup View, a Guided Setup tab is added to the ribbon. Tab option Active items Explore Save Close Properties Shows a list of all the items you have open. Open the Explorer window or a main component browser window. Save the dialog are working with. Close the dialog you are working with. Show properties of the dialog. 72 Portrait Dialogue 6.0

73 Chapter 4: Dialogs Tab option Step Section Question Edit Selected Item Move up Move down Verify Show Messages Insert a new guided setup step. Insert a new guided setup section. Insert a new guided setup question. Edit the selected item. Move the selected item up in the tree view. Move the selected item down in the tree view. Runs a check on the dialog template and displays the result in a pane in the bottom of the window. This pane will display a list of messages describing (possible) problems in the template. You can double-click or press Enter on a verification message in the list to set focus to the problem area in template Show or hide the verification pane. Dialog template properties The dialog properties window can be opened either from the File tab or from the Dialog Template Browser. It consists of four tabs. The General tab Name Deactivate dialog template Customer domain Created Created by Last modified Last modified by The name of the dialog template. If checked, the template is deactivated and cannot be used to create new dialogs. The customer domain dialogs created using this template will get its participants from. The date and time the template was created. The login name of the user who created the template. The date and time the template was last modified. The login name of the user who last modified the template, The Campaign setup tab Enable guided dialog setup Dialog execution If checked, the template supports guided dialog setup. This setting only applies if guided dialog setup has been enabled. It is used by Portrait HQ to determine if someone has to go in and manually execute all or Visual Dialogue User Guide 73

74 Dialog template ribbon tabs parts of dialogs based on this template, or if dialogs based on this template will execute automatically without user intervention. It is up to you as the template designer to determine this and design your template accordingly. Automated dialog templates are usually designed using a mix of scheduled, waterfall and/or event triggered operations. The Advanced tab Allow multiple occurrence of customers Enable participant logging Budget start cost Actual start cost Currency code Enable customer login If this is checked, the same customer may figure as participant a dialog based on this template more than once, provided the customer has different context information attached to each occurrence. If it is not checked, the same customer can only occur one place in the dialog at any time. Check this to have additional logs created when the dialogs based on this template are executed. This provides for more basis for statistics and analyses but will slow down execution, in some instances noticeable. If you choose Decide logging on each operation, you can turn logging on or off on each operation. If you choose Always generate participant log, additional logs will always be created. The default budget cost for the initialization of dialogs based on this template. The default actual cost for the initialization of dialogs based on this template. The default currency code used in dialog budgets based on this template. Check this if you want to enable customers to log in and answer questionnaires using their participant ID in dialogs based on this template. This is useful if your dialog produces messages with web links to a questionnaire. The Notes tab In this tab, you can enter notes about the template. Dialog template ribbon tabs The tabs you use in Dialog Template Designer are much alike the tabs used in Design View in Dialog Designer. There is, however, an addition to the Options tab. New Dialog From Template Create a new dialog based on this dialog template. Note that dialogs based on the template will only reflect the state of the template at the time you create them. Any changes to the template made after this will not be inherited by the dialogs. In addition to this there is the Guided Setup tab related to Guided Setup Designer. 74 Portrait Dialogue 6.0

75 Selections 5 In this section: About selections Selections in dialogs Selections in Customer View Selection Designer Browsing selections

76 About selections About selections Selections are one of the key concepts of Portrait Dialogue. What is a selection? A selection is basically a subset of all customers in a customer database. A selection somehow defines one or more criteria used to create such a subset. How selections are defined Visual Dialogue contains a module called Selection Designer, which is used to define selections. This tool enables selections to be created using different approaches, suitable both for marketers and for users with database knowledge. Use of selections Selections have various uses in the available modules. The following topics describe these in more detail: Selections in dialogs on page 76 Selections in Customer View on page 77 Selections in dialogs Selections are used in dialogs in select and divide operations. Typically, the initial operation of a dialog is to select a dialog participant from the customer database using a selection. Divide operations are used to split groups of dialog participants upon which different actions are to be taken. Selections are used in divide operations to define the divide criteria. In the picture below, a divide operation splits participants with an address from those without an address. A selection tells the system how to identify participants with an address. 76 Portrait Dialogue 6.0

77 Chapter 5: Selections Selections in Customer View Selections can be used in Customer View on the Search Page under search type Advanced. You can choose from a list of selections, and the search result will be a list of customers contained in the chosen selection. Selection Designer About Selection Designer Selection Designer was designed to help marketers to create selections based on customers data available in the system. Through the administrative configuration, groups of customer information are made available to users of Visual Dialogue. All this customer data, which consists of both customer key information (ie. name, addresses, sales) and interaction history, can be used to define selections. Who will use Selection Designer? Typically dialog designers will use Selection Designer because selections are used in select and divide operations in dialogs. In addition, more technical users than the marketer, will sometimes use Selection Designer to support the marketer with advanced selections where database and SQL knowledge is required. To support different levels of users in Selection Designer, different approaches are available when designing selections. Visual Dialogue User Guide 77

78 Creating a new selection Designing selections using Design Mode The easiest and most intuitive way of designing a selection is using Design Mode, the default mode in Selection Designer. In this mode you can define selection criteria one-by-one, and can combine them using AND and OR grouping. The criteria in a selection are outlined in a tree structure. Designing selections using Expression Mode All selections designed in Design Mode can be represented as a textual expression. Expressions are used in Visual Dialogue to access customer data. In Expression Mode, the selection expression can be edited directly. Working in Expression Mode is not as straightforward as working in Design Mode, because knowledge about expressions is required. However, there are more possibilities available when writing expressions directly. To find out more about expressions, refer to Reference Help. Example: Sex = "Female" and (has Work or has Telefax) Designing selections using SQL Mode In some cases it is more suitable to define the selection using an SQL SELECT statement, instead of using Design or Expression Mode. The reason might be the complexity of the selection, the availability of data, or performance. When working in SQL Mode, you write an SQL statement that returns the unique IDs of the customers contained in the selection. Working in SQL Mode requires knowledge of SQL and the underlying data structures (database). An example of using SQL Mode is shown below. SELECT cust_char_id as mh_customer_id FROM mhcust.customer, mhcust.person WHERE cust_id = pers_cust_id AND pers_sex = 'F' AND (not cust_ 1 IS NULL OR not pers_day_telefax IS NULL) Creating a new selection To create a new selection, choose Selection from the Create tab in Visual Dialogue. The New Selection Wizard opens. In the wizard, you need to specify a name for the new selection. You can optionally also enter a description. A selection always operates on one specific customer domain. If more than one domain is defined in an installation, you need to choose the customer domain in the wizard. Write selection using SQL specifies whether the selection will be saved using SQL Mode. To learn more about saving selections in SQL Mode, see Working in SQL Mode on page 88. Use in Customer View specifies whether the selection will be available in Customer View under Advanced search. 78 Portrait Dialogue 6.0

79 Chapter 5: Selections Note: All options in the New Selection Wizard, except the customer domain, can be changed at a later stage. After you have given the new selection a name and chosen the appropriate domain, click on Finish. Selection Designer now opens in Design Mode with no criteria defined. The upper part of the screen shows the criteria in the selection, while the lower part is reserved for test messages (that is, selection error messages) and a selection preview (a sample of the customers in the selection). A selection without any criteria contains all customers (in the domain) by definition. To check the number of customers in a selection, choose Count > Count selection from the Selection ribbon tab. When no criteria are defined, the displayed number is equal to the number of customers in the domain. Adding a criterion To add a criterion to the selection, choose New Criterion > Field criterion... from the Design tab. The New Customer Field Criterion window is displayed. A field criterion is the standard criterion type, where you can define conditions regarding customer data. The Field drop-down list is the customer data field for which you want to define a condition. Operator is the type of condition to use. The following operators are available: Operator = > < >= <= <> has Tests whether Field is equal to Value. Tests whether Field is greater than Value. Tests whether Field is less than Value. Tests whether Field is greater than or equal to Value. Tests whether Field is less than or equal to Value. Tests whether Field is different from Value. Tests whether the specified field has a value (not an empty string or a null value). Note: The list of available operators in the drop-down list depends on the field selected. Not all operators are relevant for all fields, because different fields have different data types. For example, the operators > and < only apply to numeric and date/time fields. Value is the field where you specify the value for the condition. Depending on the field and operator selected, the edit control for Value varies between a normal edit field and a drop-down list. The... button beside the edit control is enabled if a browse window is available. In such a browse window, possible values can be selected. For example, for date values, a calendar is displayed. The criterion can be given an optional description using Textual description. The description that is entered will then be displayed in the criterion outline. After clicking on OK, the new criterion will be displayed in Selection Designer. Visual Dialogue User Guide 79

80 Previewing a selection The number of customers in the selection has probably decreased, in comparison to the number before the criterion was added. To change the criterion added, double-click on the criterion, or select it and choose Edit Criterion from the Design tab. The New Customer Field Criterion window opens again. To delete a criterion, select it and choose Delete from the context menu or the Home ribbon tab. More advanced customer data criteria can be defined by adding a group criterion. Note: Full cut, copy, and paste functionality is supported in Selection Designer. Hence, criteria can be cut or copied, and then pasted elsewhere in the criterion outline, or even into another selection. Selection Designer also supports undo and redo actions. Previewing a selection At any stage in selection design process, it is possible to see a preview of the customers in the selection. This is called a selection sample, meaning that a small set of all the customers in the selection is displayed inside Selection Designer. To execute a sample, choose Sample > Sample selection from the Design tab. The lower part of the screen shows a list of customers. Tip: To view one of the customers listed in Customer View, mark a customer and choose Open in Customer View from the context menu. The + to the left in the list of customers gives access to more information about the customer, for example, a list of all the customer s activities. To control how the selection is sampled, there is a window called Sample Options. Choose Sample > Sample options... from the Design tab to display this window. Max. number of customers in sample is the number of customers displayed in the list, unless the selection contains a smaller number of customers. Additional data groups to retrieve and show specifies the information available when the + button in the customer list is expanded. Show advanced fields specifies whether to show customer data marked as Advanced use only by the system administrator. The button Sample now will close the window and execute Sample Selection with the new option settings. Adding more criteria To see how Selection Designer behaves with more than one criterion, we add a few more criteria to our selection. As shown below, the top-level node in the criterion outline becomes a group node. A group node is a criterion node which can contain subcriteria. The two criteria defined become subnodes of the group node. 80 Portrait Dialogue 6.0

81 Chapter 5: Selections Criteria description - AND-group "New customers in third quarter" and "Customer with address" Definition - AND-group DateValue(Registered)> ' ' has Work . The group node is called an AND-group because the subnodes are in an AND-conjunction. It is also possible to use an OR-conjunction. To edit the group node, mark it and choose Edit Criterion The Criterion Group window opens. We now add the third criterion. Three criteria are now displayed in the outline. We now have a selection containing three criteria. The customers in the selection will be those fulfilling all these three criteria. Executing Count selection now gives a smaller number than before. It is also possible to count the customers fulfilling a single criterion ( Count > Count selected node on the Design tab), or to perform a count for all nodes at the same time. Choose Count > Count all nodes on the tab. The number of customers fulfilling each single criterion are now listed in the count column. Furthermore, it is possible to get a preview of customer in a single-criterion node. Mark a criterion and choose Sample > Sample selected node from the Design tab. Grouping criteria To create AND and OR relations between criteria, Selection Designer has a mechanism called grouping. Consider the three criteria defined earlier. Imagine that we want to select new customers with either an address or a fax machine. Then we need to use an OR-conjunction between the criterion and the Fax criterion. Select both criteria using the Shift or Ctrl key (multi-select). Then choose Group criteria using OR from the context menu. A new group node of type OR is created. Criteria description - AND-group "New customers in third quarter" - and "New criteria group" "Customer with fax" or "Customer with address" Definition - AND-group DateValue(Registered)> ' ' OR-group has Telefax has Work Similar groups of type AND can be created using Group criteria using AND. Visual Dialogue User Guide 81

82 The toolbox in Selection Designer To ungroup criteria in a group, mark the group node and choose Ungroup criteria from the context menu. To give the group node a name, mark it and select Edit criterion. The Criterion Group window opens. Fill in the textual description with an appropriate description. You can now count the customers for all nodes in the selection. You will see that the result reflects the OR-group. Note: Grouping corresponds to using parentheses in expressions. The toolbox in Selection Designer When working in Selection Designer, the Visual Dialogue toolbox is filled with items to help you design criteria. Under Customer fields in the toolbox, all available data groups and fields are listed. Doubleclicking on an item opens the Field criterion window with the clicked item selected. Another example is the category group of the toolbox. All defined categories are listed. Double-clicking on a category opens the Category Criterion window with the clicked category selected. Group criteria A group criterion is different from a field criterion in that it sets conditions on a one-to-many group. To add a group criterion to the selection, choose New Criterion > Group criterion, and select the data group that you want to create a criterion with. The Group Criterion window opens. A group criterion lets you define one or more conditions relating to customer data found in a one-to-many group. The Add Condition button lets you add a condition to the criterion, while the Add Group button lets you add a group of conditions. All the conditions in the criterion must be fulfilled for the criterion to be true. The criterion shown above will select all customers with an address with address type Postal address and postal code below 1000 or above The operators used in the conditions are the same as those used in a field criterion. Group criterion commands Group criterion Add Condition Add Group Add a condition to the criterion. If you have a condition selected, the new condition will be inserted into the same group as the selected one. If you have a group selected, the new condition will be inserted into this group. Add a group of two conditions to the criterion. If you have a condition selected, the new group will be inserted into the same group as the selected condition. If you have a group selected, the new group will be inserted into the selected group. 82 Portrait Dialogue 6.0

83 Chapter 5: Selections Group criterion Group Ungroup Delete Group the selected conditions and/or groups into a new group. Conditions and groups can be selected and de-selected by clicking in the selector area on the right side. If you have one or more conditions selected inside a group, they will be ungrouped by this command. If you have a group selected, everything inside the group will be ungrouped. Conditions and groups can be selected and deselected by clicking in the selector area on the right-hand side. Delete the selected conditions and groups. Conditions and groups can be selected and deselected by clicking in the selector area on the right-hand side. Editing group criteria Sometimes a group criterion will be opened in a special criterion type window when you try to edit it. This is because the group criterion you have defined can also be interpreted as a special criterion. To force the criterion to open in a group criterion window, you can mark it and either press Ctrl+W or select Advanced > Edit as group criterion... from the Design tab. Special criterion types About special criterion types In addition to the general criterion types Field criterion and Group criterion, a set of special criterion types are supported. While the field and group criterion windows let you define criteria using any customer data available, these special criterion types focus on data especially available in the Dialog Database. For example, there is a special criterion type available to define a condition using questionnaire answers. All the special criterion types have a corresponding window where the criteria are defined. On the New Criterion button, the special criterion types are listed. The following special criterion types are supported: Questionnaire answer criteria on page 84 Activity criterion on page 84 Category criteria on page 85 Dialog criteria on page 85 Message criteria on page 85 tracking criteria on page 85 Link tracking criteria on page 86 Response tracking criteria on page 86 Sub-selection criteria on page 86 Analytic rule criterion on page 87 List criteria on page 87 Visual Dialogue User Guide 83

84 Special criterion types Questionnaire answer criteria A questionnaire answer criterion relates to answer forms in the Dialog Database. To create a new questionnaire answer criterion, choose New Criterion > Questionnaire answer criterion from the Design tab. The New Questionnaire Answer Criterion window opens. On the top of the window, you select a questionnaire. The questions in the questionnaire are then listed to the left. As soon as you select a question, the answer alternatives are listed to the right. You can then select one or more answer alternative. You can also select if both complete and/or incomplete answer forms should be taken into account when evaluating the criterion. If you only want to check if the answer form has been answered, use the Only check if questionnaire has been answered option. In the same way, if you only want to check if the question has been answered, use the Only check if question has been answered option. If the answer alternative selected is a multi-option question (checkbox or radio-button alternatives), then you can choose to select either respondents who checked at least one of the alternatives, or those who checked all of them. If the selected answer alternative is a textbox alternative (where the respondent fills in text), the window shows a textbox, where you can fill in text. Respondents who filled in text matching the text specified in the criterion will be selected. If the question selected is a matrix question, there is a Select matrix question combo box below the Question list box. This combo is used to select which question in the matrix you want to specify. Note: To use AND and OR between different answers, define all criteria needed, and then group the criteria in AND-groups and OR-groups. Activity criterion An activity criterion relates to activities in the Dialog Database. To create a new activity criterion, choose New Criterion > Activity criterion from the Design tab. The Activity Criterion window opens. Example: If you chose the following values listed below then it would select all customers who have activities of type Message, where the interaction took place through an outgoing after September 1st, 2004, and was followed up and completed since October 1st, Group criterion Activity type Channel Direction Created Done Message Out > >= Portrait Dialogue 6.0

85 Chapter 5: Selections Category criteria A category criterion relates to categories in the Dialog Database. To create a new category criterion, choose New Criterion > Category criterion from the Design tab. The Category Criterion window opens. You can select a category in a drop-down list. The customers fulfilling the criterion will then be those who are a member of that category. If the selected category is of type scoring category, you can specify an interval for the scoring value. If the selected category is of type category with values, a drop-down list of possible values is displayed. Dialog criteria A dialog criterion relates to dialog participants. To create a new dialog criterion, choose New Criterion > Dialog criterion from the Design tab. The Dialog Criterion window opens. You can select a dialog from a drop-down list. The customers fulfilling the criterion will be those who participates in that dialog. Furthermore, a group in the selected dialog can be specified. The criterion will then limit to participants in the selected dialog group. It is also possible to include conditions for the date when the participant was inserted into the dialog (Entered dialog), and when the participant moved into the current group (Last moved). Message criteria A message criterion relates to messages (that is, letters or s) sent to customers. To create a new message criterion, choose New Criterion > Message criterion from the Design tab. The New Message Criterion window opens. First select the communication channel. The customers fulfilling the criterion will then be those who have received messages through the specified channel. Furthermore, a template name and a message name can be specified and a condition for the Sent date. This will limit the criterion to customers who have received messages with a specific name and/or at a certain point in time. tracking criteria An tracking criterion relates to HTML messages sent to customers where the s has been tracked using tracking. To create a new tracking criterion, choose New Criterion > tracking criterion from the Design tab. The New Tracking Criterion window opens. Select a template name. The customers fulfilling the criterion will then be those who has been registered by the system as opening the in question. Note: tracking has to be enabled for the template. Because of the way that HTML is handled by clients (such as Microsoft Outlook), not all customers who actually open the will be registered by the system. Visual Dialogue User Guide 85

86 Special criterion types Link tracking criteria A link tracking criterion relates to hyperlinks in HTML messages sent to customers where the hyperlinks has been tracked using link tracking. To create a new link tracking criterion, choose New Criterion > Link tracking criterion from the Design tab. The New Link Tracking Criterion window opens. Either select a link name or specify a URL. The customers fulfilling the criterion will then be those who has received an HTML with the link and clicked on the link. You can furthermore narrow down the selection by specifying a template name, thereby only selecting the customers who clicked on a link from a specific template. Notice that the link name will not be available in the Link name drop-down until the first click is registered. You can however write directly into the edit box to create a criterion based on links in templates that has not been used to send out messages yet. If you do not specify a name when you enable link tracking in you HTML template, you can specify the URL you used instead. Response tracking criteria A response tracking criterion relates to questionnaires completed by customers having been tracked using response tracking. To create a new response tracking criterion, choose New Criterion > Response tracking criterion from the Design tab. The New Response Tracking Criterion window opens. First select a questionnaire. The customers fulfilling the criterion will then be those who have started responding without finishing the whole questionnaire. Furthermore, a layout and optionally a page within the layout can be specified. This will limit the criterion to customers who have been tracked using the specified layout and have reached the specified page. Notice that questionnaires answered without using a layout will not have any response tracking registered, and consequently will not fulfill the criterion even when you only specify a questionnaire. Sub-selection criteria A sub-selection criterion gives access to other selections. To create a new sub-selection criterion, choose New Criterion > Sub-selection criterion from the Design tab. The New Sub-selection Criterion window opens. You can select a selection from a drop-down list. The customers fulfilling the criterion will be those who are contained in the chosen selection. Sub-selection criteria make it possible to combine selections. Note: There are currently two technical limitations to sub-selection criteria: 1. The sub-selection cannot use context. 2. The sub-selection must have an SQL representation (most selections have). Selections using context are not listed in the drop-down list. 86 Portrait Dialogue 6.0

87 Chapter 5: Selections Analytic rule criterion An analytic rule enables selections to be created based on rules from Portrait Miner. To create a new analytic rule criterion, choose New Criterion > Analytic rule criterion. You can select an existing rule from a drop-down list, select the operator, and enter the value for which the selection should apply. List criteria A list is a set of customers stored in the database. Customers in a list are called list members. Lists can be created and updated using the Portrait Explorer application. The lists can then be used in selections and dialogs (including Guided Dialogs) in Portrait Dialogue. The database tables used to store lists and list members are LIST and LIST_MEMBER. A list criterion gives access to lists. To create a new list criterion, choose New Criterion > List criterion from the Design tab. The New List Criterion window opens. You can select a list from a drop-down list. The customers fulfilling the criterion will be those who are contained in the chosen list. Working in Expression Mode When working in Design Mode, it is always possible to change to Expression Mode and edit the selection criteria as pure text, and vice versa. Selection Designer is a two-way tool in the sense that changes in Design Mode are reflected in Expression Mode, and changes in Expression Mode are reflected in Design Mode. Actually, when a selection is saved to the database, it is the expression string which is stored. Hence, the expression contains all information about the criteria in the selection. If you define one criterion in Design Mode, and then switch to Expression Mode, you can see the expression representation of the criterion. Criteria description "New customer in third quarter" Definition DateValue(Registered) > ' ' In the Selection expression window: "New customers in third quarter" : DateValue(Registered) > ' ' You can then add a criterion in Expression Mode by typing in the criterion as text. To verify that the expression is valid, choose Check from the Design tab. If there is an error in the expression, Selection Designer will show a message and position the cursor at the error. If you now switch back to Design Mode, the criterion outline will reflect the new criteria added in Expression Mode. When working in expression Mode, the functionality available on the New Criterion button on the Design tab is still available. Also, choosing Edit Criterion opens a window for editing the criterion at the cursor position. Visual Dialogue User Guide 87

88 Working in SQL Mode When editing an expression, you can get a list of valid fields and functions by pressing Ctrl+Space. Working in SQL Mode To create a new selection using SQL Mode, choose Selection from the Create tab. Ensure that you check the Write selection using SQL option in the New Selection Wizard. Selection Designer is now displayed in SQL Mode, with an SQL template to help you start to write the SQL. The basic rule when writing a selection SQL query is that the SQL has to be a SELECT statement returning customer IDs. The statement should return a column named mh_customer_id. Otherwise, Selection Designer will return an error message. We can now change the initial statement to a real executable SQL statement. To test the statement, choose Check from the Design tab. A sample of the result set of the SQL is then displayed in the lower part of the screen. If the SQL statement contains errors, the lower part of the screen will display the error message from the database server. Furthermore, there are options like those in Design and Expression mode to count and preview the selection. Choose Count > Count Selection to calculate the number of customers in the selection. To see a preview of the customers in the selection, choose Sample > Sample selection from the Design tab. Working with context Context in Visual Dialogue is a relatively advanced concept. What is context? Context is a value assigned to a customer participating in a dialog, meaning that the customer is not only identified by a unique ID, but by the unique ID and the context value together. This opens for that one customer can appear as more than one participant in a dialog with different context values. To be able to use context in dialogs, it must be possible to have select operations which inserts participants with context values. Therefore, it is possible to create selections specifying context values. Enabling context in a selection Enabling context in a selection is done through the Design tab. Use the option Advanced > Use context in selection to do this. 88 Portrait Dialogue 6.0

89 Chapter 5: Selections When the Use context in selection option is enabled, a context value can be specified either in Expression Mode or SQL Mode. Specifying context in Expression Mode A context expression can be specified in Expression Mode. This expression should be of data type string. It can be a constant or a value which varies from customer to customer. In the picture below, the selection contains customers with an address. The context value is a concatenation of the customer ID and the current time. Note that in the selection sample, the context value is shown as the second column. In this case the value is different for each customer in the selection. Specifying context in SQL Mode In SQL Mode, context is specified as a separate column in the SELECT statement. When working with context, the selection SQL needs to return a column called mh_context in addition to the mh_customer_id column. Visual Dialogue User Guide 89

90 Browsing selections Browsing selections To see all selections defined, choose Explore > Selections from the Home tab in Visual Dialogue. The Browse Selections frame is displayed. To sort selections, click on the desired column in the heading of the selection list. To configure the set of columns displayed in the list, choose Select Columns from the View tab. To review or edit the properties (i.e. the name or the description of the selection), make a single selection and choose Properties from the Home tab. Use in Customer View specifies whether the selection is accessible from Advanced search in Customer View. Use when testing message templates specifies whether this selection is available in the Test options window in Message Designer. Use when defining conditions in message templates specifies whether this selection is available when defining conditions in the Message Designer. To open a selection in Selection Designer, double-click on a single selection in the list, or choose Open from the Home tab. To delete a selection, mark a single selection and choose Delete from the Home tab. 90 Portrait Dialogue 6.0

91 Messages 6 In this section: About messages Document types Browsing message templates Message Manager Test sending messages Deleting tracking data Master templates Message templates

92 About messages About messages Message templates is the basis for producing messages in Visual Dialogue and in Customer View. When the system produces a message, it starts with a message template and then merges customer information into the template to make a complete message. In Visual Dialogue, you use the Message Template Designer to create and edit your message templates. Document types All message templates are of a specific type. The types are defined by your marketing database administrator. A template can be a simple file (text, HTML, etc.), which can be edited through the built-in template editor, or in a special file format (e.g. a Microsoft Word template), which must be edited with an external editor. 92 Portrait Dialogue 6.0

93 Chapter 6: Messages Browsing message templates To see all message templates defined, choose Explore > Message Templates from the Home tab in Visual Dialogue. The Browse Message Templates frame is displayed. To sort the templates in the list, click on the desired column in the heading. To configure the set of columns displayed in the list, choose Select Columns from the View tab. To review or edit the properties (e.g. the name or the description of the message template), select a single template and choose Properties from the Home tab. The Message Template Properties window opens. To open a template in the Message Template Designer, double-click on a single template in the list or choose Open from the Home tab. To delete a template, mark a single template and choose Delete from the Home tab. A preview of the template is shown in the bottom of the browser. To turn the preview on or off, click the Preview button on the Home tab. Preview images are automatically generated when you save a template, but you can also manually generate them by choosing Update preview image from the context menu in the browser. Message Manager Message Manager is a tool inside Visual Dialogue to manage messages. Concepts The term message is used to cover all kinds of information sent to customers, including s, letters, and SMS messages. In dialogs, messages are often created in large numbers. A message bundle represents a set of messages created at the same time. For example, when a create operation is executed, a message bundle is created. The bundle contains all individual s produced. The next time the operation is executed, a new bundle is created. A message has one of five possible status values: In outbox The message resides in the outbox. A manual action in Message Manager is required for the message to be sent. In Send queue The message is in the send queue. The Send Message Service will send it as soon as possible. This status only applies to message types that can be sent electronically (typically an , but not a letter). Visual Dialogue User Guide 93

94 Message Manager The Send Message Service is a software module running on the Dialogue Server. It is responsible for sending electronic messages (i.e. s and SMS messages). Marked as Erroneous If an error occurred when the Send Message Service attempted to send a message, it is marked with an error flag and an error message. You can manually put the message back in the send queue from Message Manager. This status only applies to message types that can be sent electronically. Filed as Sent item When the message has been communicated to the customer, it is marked as sent. For electronic messages, this happens automatically when the Send Message Service has sent the message. For non-electronic messages, you can mark the message manually in Message Manager. Bounced ( s only) When an message has been communicated but was returned with a bounce code. See Reference Help for technical details on bounced s. The Message Manager interface To open Message Manager, choose Explore > Message Manager from the Home tab. Message Manager has five views reflecting the possible status values of a message: Outbox, Send queue, Erroneous, Sent item, and Bounced s. The upper part of the screen shows message bundles containing messages matching the current view. The lower part of the screen shows individual messages in the selected bundle. Only those messages in the bundle matching the current view are shown. The list of messages is not shown automatically for performance reasons. You need to double-click on a bundle, or mark it and press Enter. To view the content of a single message, mark a message and choose Open from the Home tab. Message Manager will launch an internal viewer or an external program (e.g. Microsoft Word) depending on the message type. The Message Manager ribbon tab Message Manager has its own ribbon tab in Visual Dialogue. Bundles > Send will move all messages in the selected bundle(s) from the outbox to the send queue. Bundles > Resend will move all messages in the selected bundle(s) from Erroneous View to the send queue. Bundles > Mark as Sent will move all messages in the selected bundle(s) from the outbox to the Sent Items view. Open > Open in external editor will open the selected message in the external program that is associated by Windows with the file type. Messages > Send will move selected messages from the outbox to the send queue. Messages > Resend will move selected messages from Erroneous View to the send queue. Messages > Mark as Sent will move selected messages from the outbox to the Sent Items view. 94 Portrait Dialogue 6.0

95 Chapter 6: Messages Open > Open message by ID... lets you open a specific message by entering a unique message ID (ml_id of the database table message_log). Options > Show Customer Data will display data about the receiving customer for individual messages. This can be turned on or off. Erroneous View When sending a message fails, the message is marked with an error message. In Erroneous View, it is possible to inspect the error message. Bounced View When an bounces, the will be listed in the Bounced view. Note that if a single message bounces multiple times, i.e.. more than one bounce is received by the system, it will be listed once for each bounce. Test sending messages When you use the Message Template Designer to design a message (which is of a type that is sent electronically), you can test send the message. This functionality makes it easy to test the message and see how it looks when received by the client. and SMS messages are examples of message types that can be test sent. A message can be test sent by following these three steps: 1. Test merge: Choose Test from the Design tab or press F9. 2. Open the send window: Choose Test Send from the Home tab or press Ctrl+Enter. 3. Send the message: Enter the receiver address/number/etc., and click on OK. An in an message bundle can also be test sent, following the same procedure as described above. See Message Manager on page 93 for more information about message bundles. Deleting tracking data The Delete Tracking Data Wizard is primarily intended for deleting test data in the form of tracking data that you have posted to the system during development of a process, but it can also be used to delete arbitrary tracking data, so you should use it with great care. To run the Delete Tracking Data Wizard, go to the Message Template Browser and choose Delete tracking data... from the Home tab. A wizard showing the total number of link tracking and tracking records for the selected message template is displayed. On the next page, you can restrict the data to be deleted by specifying a date interval. Visual Dialogue User Guide 95

96 Master templates You are shown the number of tracking records that will be deleted (after applying any date restrictions). Master templates About master templates About master templates Master templates can be used to give your message templates a common style. They can for instance contain common things such as your company logo, address and other things that make up your company profile. Master templates are used as a base when you create a new message templates. Most message templates can be created without using a master template as a base, but some (e.g. Message Designer and word message templates) require a master template. Note that when you change a master template, changes will only affect new message templates based on the master templates. Master templates are edited with the master template designer. Message Designer master templates All Message Designer templates are based on master templates. The master template is used to define the main layout of the template and typically consists of static HTML, style sets, editable regions called Body Areas, and a set of CSS classes used by the master template itself. Master template: The master template is defined in Visual Dialogue and consists of one or more editable regions called Body Areas. It also contains a default style set, and may contain one or multiple style set overrides for Body Area Items and font colors. Message Template: In the Message Designer, you can create a new message template based on a master template. You can edit the Body Areas using a set of predefined Body Area Items. The Items layout is controlled by the Style sets in the master template. If an Item has Style Sets defined, you can quickly switch between them using the Edit Menu for the Item. Customer Message: The completed message template is used to create one or multiple customer messages typically through a dialog defined in Visual Dialogue. The process is often referred to as merging the s. The messages are then send to the customers through the Dialogue Server send engine. Master template properties Master templates have the following properties: 96 Portrait Dialogue 6.0

97 Chapter 6: Messages The General tab Field Name Customer domain Document type Created Created by Last modified Last modified by The name of the master template. A description of the master template. The customer domain the master template gets its customers from. The document type of the master template. The date and time the master template was created. The login name of the user who created the master template. The date and time the master template was last modified. The login name of the user who last modified the master template. Deactivate master template When this is checked, the master template will not be available as a base when you create new message templates. The Advanced tab Field Template file Generate activity Use outbox Enable tracking by default The path and filename of the master template file. If you want activities to be created when messages based on the template are sent, choose an activity type here. One activity will be created for each message and related to the customer. If you check this box, all messages will be sent to an outbox where you can view and check that the messages are OK before actually sending them. This can be done in the Message Manager. If you do not check the box, all messages will be sent as soon as they are produced. This setting is used as a default value when creating new templates from the master. Enables tracking by default in all message templates based on this master template. This setting is used as a default value when creating new templates from the master. This setting applies only to Message Designer templates. The Preview image tab Field Preview image The preview image will be shown when you generate new templates. If you want to use this functionality, you should create an image of the master template. Visual Dialogue User Guide 97

98 Master Template Designer - Message Designer Master Template Designer - Message Designer Designer overview Master templates are edited with the Master Template Designer. The Master Template Designer has three main areas: the work area in the middle where you design the template, the control parameters at the top which is used to set defaults for the message template based on it, and the toolbox at the right which provides quick access to merge fields. In addition, the Master Template Designer has two main modes, HTML view and Style Sets View. HTML view contains the HTML including CSS styles that apply to it, and the Style sets view contains CSS style sets that apply to Body Area Items used in the message template. When working with style sets the toolbox provides quick access to available Body Area Items definitions to help you create CSS styles. The main view also contains a preview pane to preview the selected style for a definition. Creating a new master template To create a new template, choose Master Template from the Create tab in Visual Dialogue. The New Master Template Wizard opens. Step 1 On the first page of the wizard, the new master template is given a name, an optional description, and the domain it will be used in. Step 2 On the second page of the wizard, you choose the document type that this master template will be used for. After completing the wizard, the master template designer opens. HTML View About HTML View The Master Template consists of a standard HTML document including special tags to act as containers for Body Area Items. The HTML View editor is used to create and edit the HTML document. Editor part Control Parameters HTML Editor Toolbox Is used to set up default control parameters inherited by the Message Designer template using the master. Is used to define the full HTML document for the master template. Provides easy access to merge fields available to use in the master template HTML content. 98 Portrait Dialogue 6.0

99 Chapter 6: Messages The HTML editor available in Visual Dialogue has limited functionality. We therefore recommend using a 3rd party HTML editor like Microsoft Expression Web together with Visual Dialogue to design and edit your Master Template. Insert Body Area Placeholder To help you build Body Area tags you can simply use the tag builder available in Visual Dialogue. Choose Body Area Placeholder from the Insert tab, or press Ctrl+Y in the Master Template editor. Field Body area ID Default item alignment Max image width Min items Max items Allowed item types Allowed item definitions Default item definitions A unique id of your Body Area. A simple description of the tag The default alignment for all items added to this container. Defines the maximum allowed image witdh in this item. This is used in the editor to automatically scale down images if users try to insert an image with a width larger than what specified here. Minimum items allowed in this Body Area. Maximum items allowed in this Body Area. List of allowed item definitions separated by a semicolon. List of allowed item types separated by a semicolon. Default item(s) separated by semicolon. Example of the Body Area Placeholder tag in code (HTML): <div MHBodyAreaID="body_1" description="body item area" DefaultItemAlign="default" maximagewidth="560" minitems="" maxitems="" alloweditemdefs="" alloweditemtypes="" defaultitemdefs=""></div> Style Sets View About the Style Sets View The Master Template can have overrides for the default styles for Body Area Items. It can also have one or multiple style sets defined for one or multiple Body Area Item Definitions. The Style Set View editor is used to edit the Style Sets XML document. Editor part Style sets Item preview This is the editor for the XML document defining the different style sets. Provides instant preview of an item with styles from a selected style set applied. Visual Dialogue User Guide 99

100 Master Template Designer - Message Designer Editor part Body area item definitions Provides easy access to all the item definitions to easily copy the item CSS and HTML. Insert Style Set element To help you build Body Area tags you can simply use the tag builder available in Visual Dialogue. Choose Style Set Element from the Insert tab, or press Ctrl+B in the Master Template editor. The Style Set Element builder: Option Name A unique name for the style set. A simple description of the element. This is the text shown to the users when creating an . Style set applies to All item definitions The item definitions selected below Insert CSS classes The set applies to all available items. Specify one or more items using the drop-down list. Insert the default CSS classes for the items you selected in the set. Example of the Style Set element in code (XML): <StyleSet Name="htb_blue" ="Blue and light gray" AppliesToItemDefs="MHHeaderTextBackground">.mh_htst_img_tl {background-color: #6699CC; height: 22px; border-bottom: 1px #ffffff solid;}.mh_htst_img_tm {background-color: #6699CC; height: 22px; padding: 1px 5px 1px 5px; border-bottom: 1px #ffffff solid;}.mh_htst_img_tr {background-color: #6699CC; height: 22px; border-bottom: 1px #ffffff solid;}.mh_htst_txt_body {font-family: Arial; font-size: 11px; color: #333333; word-wrap: break-word;}.mh_htst_txt_header {font-family: Arial; font-size: 13px; font-weight: bold; color: #ffffff; word-wrap: break-word;} </StyleSet> For more information, see The Master Template Style Sets. Item definition CSS and HTML The Body area item definitions toolbox provides fast access to CSS and HTML for all defined item definitions. The selected item is the one shown in the preview window. Expand the item (click on the + sign) to view the individual CSS classes used by an item. Right-click on an item in the toolbox to bring up the context menu. The menu provides the following tools: 100 Portrait Dialogue 6.0

101 Chapter 6: Messages Option Show in preview Copy CSS Copy item definition name Copy HTML fragment Copy preview HTML New style set element Auto preview Show hint Use this to preview this item. (Only apply if auto preview is off) Copy item default CSS to the clipboard Copy the technical name if the item definition. This is the name you use in the field AppliesToItemDefs. Copy item default HTML to the clipboard Copy item default preview HTML to the clipboard Brings up the create new style set dialog box with the current item selected. Enable auto preview. This will preview the item as soon as you select it. Enable hint on each item. This will Tip: Press F8 while the cursor is located inside a style set tag to refresh the preview for the item with that style set. For more information, see The Master Template Style Sets The master template HTML A Master Template is built up using standard HTML including special elements for defining Body Areas. In this chapter we will look at the building blocks of the Master Templates in detail. Example of an Message Designer Master Template as shown in the Message Designer editor: This template consists of standard HTML including two special DIV tags defining the Body Areas Placeholders. A template must include at least one Body Area definition, but usually consists of multiple areas. The HTML for this master template looks like this: Visual Dialogue User Guide 101

102 Master Template Designer - Message Designer Important notes about the HTML code. 1. Document Type Declaration DocType Some clients support and use DocType declaration others dont. We therefore recommend NOT using DocType in your HTML s. 2. Header Meta Tags Include a meta tag for content type and encoding. The encoding should be the same as set up on your output channel in Dialogue Admin. For Scandinavian countries this is normally iso Header Style definitions All general style definitions for your Master Template should be defined in the <style> tag of the header. Styles for the Body Area Items should NOT be defined here. They should be defined in the Master Template Style Sets. you can specify a custom attribute on the style tag to control how style definitions are copied inline to elements for better client support. have a look at Inline CSS support 4. The Body Area Placeholder tag A special <div> tag is used to define the Body Areas that should be editable in the message template. The tag is a standard <div> tag, but it consists of special attributes that defines the properties of the Body Area. Have a look at Insert Body Area Placeholder for how to automatically create, the Body Area Item Definitions on how to view available items and Body Area Placeholder Tag for details on how ID of the tag affect Master Template changing in a message template. 102 Portrait Dialogue 6.0

103 Chapter 6: Messages Note: When you are building master templates, remember that designing HTML for use in is a different task from designing HTML for use on the web. See Designing HTML for use in s on page 104 for more information and best practice. The master template style sets A Master Template can have overrides for the default styles for Body Area Items. It can also have one or multiple style sets defined for one or multiple Body Area Item Definitions. The style sets are defined and edited in the Master Template Editor Style Set View. All Body Area Items available have a set of CSS classes with default properties defined. When you design a new Master Template you typically need to override some or all of the CSS properties, and create different variants of them to meet requirements for the message template. A Style Set XML have three different groups for doing this. Example Style Set XML: Option DefaultStyleSet ColorPalette StyleSet This is where you override the default styles for the body area items different CSS classes. This is the style the Body Area Item will use by default when a user adds an item to a message template. Normally most of the CSS classes are overridden. The body area item text editor a user can set text and background colors. The color palette will automatically include all colors used in any CSS class you specify in ether DefaultStyleSet or StyleSet, if you want to add additional colors you may specify them here. Defines the style set for an body area item or group of items (specified in AppliesToItemDefs). The name must be unique, and the description is shown to the user when selecting a style set in the editor. A Style Sets XML can contain zero or more style sets. These style sets are available in the message editor Item Menu. Note: When you override a CSS class, you must override all properties. The message template will use the default class or the override. It will not merge the classes properties. See Insert Style Set element on page 100 to learn how to insert a Style Set tag. See Item definition CSS and HTML on page 100 to learn how to work with body area items CSS classes. Visual Dialogue User Guide 103

104 Master Template Designer - Message Designer Designing HTML for use in s When building Master Templates it is important to remember that designing HTML for use in s are a different task than designing HTML for web browsers. Designing an HTML that renders consistently across the major clients can be very time consuming. Support for even simple CSS varies considerably between clients, and even different versions of the same client. Unfortunately HTML rendering has been left in Getting even a relatively simple design to work in the 10 or 12 major clients can be a very frustrating task, and support is getting worse, not better. We make sure that the HTML created by the Body Area Item Definitions render correctly in all clients, however the final result (customer message) depends heavily on how well you design your Master Template. Have a look at the Standard Project for useful resources on best practice in HTML design: This site also has a lot of useful information about the different clients and what they support. The Body Area Placeholder tag The mhbodyareaid property of the Body Area Placeholder tag (described in Insert Body Area Placeholder and The Master Template HTML) plays an important role for supporting Master Template reapplying and changing in Message Designer. It is important that you follow a naming convention to support this. When a user choose to change a master template for a message template the program will search for matching Body Area Placeholders in the other master template. If it finds a tag with the same name (the MHBodyAreaID property) it will move all content defined in the source to the destination. If no match is found the content will be removed. Example on changing templates 104 Portrait Dialogue 6.0

105 Chapter 6: Messages This example shows how all items are preserved and moved correctly from one template to another since the tags have matching names. Make sure you apply a naming convention for Body Area Placeholders when you design all your master templates. This will make sure this feature works across all your templates. Body Area Item definitions Message Template Designer is delivered with a set of predefined Body Area Item definitions. This is a set of HTML fragment that are the base for all items a user that design a message template uses. The designer of the master template must make sure that the template and the Style Sets defined for it will provide all style and layout that you require for the message template. All defined Body Area Item definitions can be viewed in the Master Template Style Set View. It is possible to define new types of Body Area Item definitions. This must be done by a system administrator. Note: Note: We recommend that you do not create new definitions unless it is absolutely necessary. Normally, you will be able to use a standard item by modifying the CSS override or creating a new Style Set. All definitions whose names start with the letters mh are considered to be owned by the system and may be changed or deleted when upgrading. This includes new definitions created on site. The same applies to Style Sheet definitions. HTML CSS support Controlling how CSS styles are automatically moved inline by the editor Some clients do not support CSS defined in <style> tags. They will simply ignore the <style> definition. We have solved this by automatically moving the styles defined in the master template <style> tag and style sets inline when a template is saved. This means that you do not have to worry about this when designing a master template. A Message Designer template will by default move all CSS from the <style> tag and the style sets to the elements when you save it or test merge it. It will only move the CSS used by the template; the rest is removed to keep size to a minimum. This behavior can be overridden by specifying a custom attribute on the <style> tag in the master template. Controlling how CSS is applied inline: Style tag definition <style type="text/css"> <style type="text/css" inlinemode="moveinline"> <style type="text/css" inlinemode="copyinline"> Default move all CSS inline. Same as default move all CSS inline. Copy all CSS inline. Visual Dialogue User Guide 105

106 Master Template Designer - Message Designer Style tag definition <style type="text/css" inlinemode="none"> Do not do anything leave the <style> tag as it is. Tip: We recommend using default behavior, which will move all CSS inline. CSS inline support Designer supports application of inline styles for the following selectors: Selector Element ID Class Descendant element Match any specific element. Match a single element with a specific ID. Match any element with the specific class name. Match any descendant element with the specified selector. Example td { color: red } #MyTag { color: blue }.ClassName { color: green }.ClassName td { color: gray } Other CSS selectors are unsupported, e.g.: Selector Universal Pseudo-class Grouping Attribute Child Match any element. Match an element during a user action (not possible to specify inline). Match any of the grouped selectors Match any specific element with an attribute set to a value. Match an element that is a child of another element. Example * { color: blue } a:hover { color: blue } td, div, span { color: red } td [foo=info] { color: green } td > a { color: blue } Note: It is fully possible to use any CSS selector available, but only the supported selectors (as specified above) will be applied inline. Default samples A set of sample Message Designer Master Templates are available in Visual Dialogue to provide you with a best practice example on how to design them. The samples are installed together with a set of images. The images are stored in Visual Dialogue published files Available samples: 106 Portrait Dialogue 6.0

107 Chapter 6: Messages Master Template Name MH Generic blue left sidebar MH Generic blue right sidebar MH Generic blue single column MH Newsletter green left sidebar MH Newsletter green right sidebar MH Newsletter green single column Two body areas one left bar to left and one main area. Two body areas one left bar to right and one main area. One body area. Two body areas one left bar to left and one main area. Two body areas one left bar to right and one main area. One body area. The samples consist of two main layouts three blue layouts and three green layouts. The samples are tested in all major clients and are excellent to use as a starting point to create your own master templates. Note: Samples are not installed by default and have to be set up by a system administrator when installing or upgrading. Please contact your system administrator if the samples are not installed. Message templates Creating a new message template To create a new message template, choose Message Template from the Create tab in Visual Dialogue. The New Message Template Wizard opens. Enter the appropriate information. Enter a Template name, and choose the Customer domain that you want your template to use. Note that when working in Dialog Designer or in Customer View, only those templates that belong to the same customer domain as the dialog or the customer can be used. Choose Next to continue. Choose what document type you want your template to be. Also, choose how you want to create your message template: Create an empty template creates a blank template. This is only available for document types that use the internal editor, i.e. HTML and plain text templates. Base template on master template creates a template that is a copy of a master template. Copy an existing template creates a copy of a message template that you or someone else has made before. When you have entered all the information, click on Finish to create the new message template and start working with it in Message Template Designer overview on page 108. Visual Dialogue User Guide 107

108 HTML templates and web modules HTML templates and web modules The internal editor in web modules (for instance Customer View) cannot handle html, head, and body elements in an HTML template. If they exist, they are removed when the template is displayed in the editor. It removes just the start and end tags, not the content. In most cases, his will not be a problem. However, templates containing elements dependent upon information stored in these tags might not behave as they normally would. To make sure that the HTML templates behave correctly in the web-based editors, you should not include information in these tags that is needed for the template to work correctly. Styles defined in the head tag might, for example, work as normal, as these are not defined in the start and end tags, but it is safest to specify styles directly in the relevant tags in the HTML code. Message Template Designer Message Template Designer overview Message Template Designer has three main areas: the work area in the middle where you design the template, the control parameters at the top which is used to control the message you produce and the toolbox at the right which provides quick access to merge fields In addition, the Message Template Designer has two main modes: Design View and Text View. Design View will only be available when you are working with an HTML or RTF template. Visual Dialogue supports editing of plain text, HTML and RTF templates. If you are working with a template that cannot be edited inside Visual Dialog, for instance a word template, the message template designer will provide you with two links, Open template and Test. The Open template link will open the template in the external program that is associated by windows with the file type. The Test link will do a test merge of the template. Message Designer The Message Designer document type has another special design canvas. See About Message Designer for details on editing a Message Designer template. Message Template Designer ribbon tabs When you work with a message template, Design, Insert and Format ribbon tabs are added. The Design ribbon tab contains items that let you test the message template and customize the message template toolbox. Option Test > Test Do a test merge of the message template. A window is opened where you can see what your message will look when it is created. You can specify how many customers will be shown etc. using the Test options menu choice. 108 Portrait Dialogue 6.0

109 Chapter 6: Messages Option Test > Test options... Specify the number of customers to show when testing your message template. You can specify the number of customers you want to test against and if desirable select the customers by: 1. Specifying a selection. The selection must be marked with Use when testing message templates 2. Enter an expression. 3. Specifying a dialog group containing participants 4. Entering a Customer ID of a specific customer. Count characters Advanced > Show advanced fields Link overview... Count the total number of characters used and the number currently selected. This is only available in Text View. Show or hide advanced fields in the message template toolbox. Advanced fields are fields that you do not normally use in a template, such as internal IDs. Show the Link Overview window. This is only available in HTML Design View. The Design ribbon tab also enables you to use and test a custom SQL statement with your template Option Custom SQL > Use custom SQL Custom SQL > Test SQL Check this to enable the use of a custom SQL statement in your template. Test your custom SQL statement. Custom SQL > Change database... Allows you to use a different database connection than the default connection. Database connections are defined by your administrator in the Dialog Admin tool. The Insert tab lets you insert tables, pictures, hyperlinks and lines into your HTML or RTF template. The Format tab lets you format your HTML or RTF template in different ways. The message template toolbox When working in Message Template Designer, the Visual Dialogue toolbox is filled with items to help designing the template. There are four groups in the toolbox. Double-click on any of the items in the toolbox to add them to your template in Design View or Text View. The Customer fields group lets you add merge fields from the customer domain. The Web links group has different web link tags that you can use. When you do the merging of the data, these tags will be replaced by actual web links that the recipient of the message can click to access parts of Web Modules. From the Expression functions group, you can insert expression functions. Visual Dialogue User Guide 109

110 Message Template Designer Statements is a powerful tool that lets you put insert if..else statements into your template. This can be used to conditionally merge text. Here is an example that writes Miss/Mrs. if the customer is female, Mr. if the customer is male, and nothing if the customer sex is not known: «[if] Sex = "Female"»Miss/Mrs.«[elseif] Sex = "Male"»Mr.«[endif]» If you are using a custom SQL statement you will also have a Custom SQL fields group. Message Template Design View In Message Template Design View, you can edit HTML or RTF message templates. Use the Insert and Format ribbon tabs to insert elements into or format your template. You can use the right-click popup menu to edit elements that are already in the template. Use the toolbox to insert merge fields. If you want to edit the HTML source, you can view and edit this in Text View. The message template text view In the message template text view, you can edit text message templates. This view is also used to edit the HTML source of HTML templates. You can use the toolbox to insert merge fields in text view. Message template properties The message template properties window can be opened either from the File tab or from the Dialog Browser. It consists of two tabs. The General tab Field Name Customer domain Document type Master template Created Created by Last modified Last modified by The name of the template. The customer domain the template gets its customers from. The document type of the template. The master template (if any) used when the template was created. The date and time the template was created. The login name of the user who created the template. The date and time the template was last modified. The login name of the user who last modified the template. The Advanced tab Field Template file Target path The path and filename of the template file. The path to the directory where messages based on the message template are stored. If no path is specified, the message path for the customer domain is used. If you 110 Portrait Dialogue 6.0

111 Chapter 6: Messages Field Generate activity Activity description change this, make sure it points to a share that can be reached by everyone who will use the template. If you want activities to be created when messages based on the template are sent, choose an activity type here. One activity will be created for each message. If you chose to generate an activity when sending messages, you can enter the activity description here. Priority Use outbox Use in customer view The priority used when the message is sent. This setting only applies to messages that are send electronically, e.g. s and SMS messages. Set priority to above normal when it is important that the customer receives the message relatively quickly. An example may be an that contains a forgotten password. If you check this box, all messages will be sent to an outbox where you can view and check that the messages are OK before actually sending them. This can be done in the Message Manager. If you do not check the box, all messages will be sent as soon as they are produced. Check this if you want the message template to be available in Customer View. Using a custom SQL query Note: Writing and using a custom SQL query requires a thorough understanding of both SQL and the Dialog Database. You can write a custom SQL query to make available merge data that cannot be found in the customer domain. Merge data should in general be fetched from the domain, but if you need other merge fields, it is useful to write a custom SQL query to do this. However, note that merging using a custom SQL query will generally slow down the merge process, as the SQL statement has to be executed for every single customer. You start writing a custom SQL query by choosing Custom SQL > Use custom SQL from the Design tab. This will display a new tab in the designer window, Custom SQL. Visual Dialogue User Guide 111

112 Message Template Designer When writing an SQL statement, all the tables and fields in your database are available in the toolbox. You can double-click on one of them to insert it into your statement. The select part of the SQL statement can have one or more fields that is linked to the customer or dialog participant. This can be mh_customer_id, mh_participant_id and/or mh_context. In the example above mh_customer_id is used. All the fields in the select part of your SQL statement will be available as merge fields in your template. There will be a Custom SQL fields group in the toolbox that makes it easy to add the fields to your template. If you want to type them manually, or if you are using an external program to edit your template, they should be written in the form <<CustomSQL.fieldname>>, where fieldname is the name of the field in the SQL statement. Note: If you are using Microsoft Word, you must insert your merge field as «CustomSQLfieldname», without a dot between CustomSQL and fieldname, as Word does not recognize dots in merge fields. You can test your SQL statement by choosing Custom SQL > Test SQL from the Design tab. The result will be shown in the SQL test pane at the bottom of the window. Control parameters Control parameters are used to control the delivery of your message. Different document types have different sets of control parameters, and some, i.e. letters, have none. You can use merge fields in the control parameters. You can for instance use an address merge field in the control parameter To address in templates to merge the customers address into the message. The below paragraphs contain description of the control parameters used by the electronic channels installed. 112 Portrait Dialogue 6.0

113 Chapter 6: Messages Control parameters for messages The following control parameters are used with message types. Most of these control parameters are values defined by the standard protocols. However, some are proprietary control the content of the , or how the is sent. Parameter Subject To address From address CC address BCC address Reply address Attachments Priority CharSet Organization Receipt recipient The subject of the . The address of the receiver of the . Normally, this will be set to the address of the customer. The address from which the is sent. Indicates carbon copy recipients for the message. In other words a list of addresses that will receive a copy of the . Indicates blind carbon copy recipients for the message. The address that the recipient will send to, if he or she replies to the . This value only needs to be specified if it is different from the From address. A semicolon separated list of additional files to attach to the message. Local paths, as seen from the Dialogue Server, must be specified. The priority as it appear to the recipient. This parameter does not control the priority when the is sent. Default value is Normal. Indicates the character set used for the message. Identifies the organizational affiliation for the message author. Return receipt address. Insert identifier in header Add plain text part Controls whether a specific identifier is inserted in the header. This identifier is used by the system to identify bounced s. Specifies whether a plain text part is added to an HTML . The plain text part should be specified in the parameter Plain text part. The default value is False. Plain text part The plain text part added to en HTML if the Add plain text part parameter is set to True. Example: This is a mail message in HTML format. Please enter the URL below in your web browser to read it: «mh_message_url» In the example, the tag mh_message_url will be converted to a link to a web page showing the HTML version of the . is used to insert a line break. Control parameters for Facebook messages The following control parameters are used with Facebook message types. Visual Dialogue User Guide 113

114 Message Template Designer Parameter Facebook username and Facebook access token Location Private Image filename Image URL Link URL Link name Link description Facebook sequrity keys. Your customer data should contain these keys and they have probably been gathered by using a Facebook Application that requested access to a Customers Facebook account. You can provide location information by specifying the Facebook Page ID that is linked with the required location. See Facebook for more information on locations. The Wall status can be made private by specifying True for the Private parameter. Used when uploading an image to Facebook, provide an image filename. A local path, as seen from the Dialogue Server, must be specified. The currently supported image formats are JPG, GIF, BMP, TIF and PNG. Please refer to Facebook for more information on the currently supported image sizes. If available, a link to the picture included with this post. The link attached to this post. The name of the link. The caption of the link (appears beneath the link name). Note: The control parameters for Facebook messages will differ depending on what type of Facebook message you are creating. Please see Facebook documentation for Facebook security details. Control parameters for FTP messages The following control parameters are used with message types that are configured to be send using the FTP channel. Parameter Host Port Passive Username Password Remote directory Remote filename Transfer type The server name or IP address of the FTP server to which the message will be uploaded. The port used for by the FTP server. Default is 21. Specified whether to use active or passive FTP communication mode. The default is false (active mode). User name used to log on to the FTP server. Password used to log on to the FTP server. The directory on the FTP server to which the message will be uploaded. The name given to the message when uploaded. The FTP transfer type. Default is binary. 114 Portrait Dialogue 6.0

115 Chapter 6: Messages Parameter Attachments A semicolon separated list of additional files to upload together with the message. Local paths, as seen from the Dialogue Server, must be specified. Control parameters for SMS messages The following control parameters are used with SMS message types. Parameter Cellular FromNumber The cellular telephone number of the customer. The telephone number or text that will appear as sender when the customer receives the SMS message. Note: The control parameters for SMS message types may differ from installation to installation because systems are set up to use different SMS gateway providers. The parameters listed here are those used with the ScanGIT SMS gateway provider in Norway. Control parameters for Twitter messages The following control parameters are used with Twitter message types. Parameter Access token, Access token Secret, Consumer Keyand Consumer Secret Send to screen name Your data should contain these keys and they have probably been gathered by using a Twitter Application that requested access to a Customers Twitter account. Used to identify the Twitter user that the direct message will be sent to. An example These users need to be followers of the account being used to send the Direct Message from. Attached image path Used when uploading an image to Twitter, provide an image filename. A local path, as seen from the Dialogue Server, must be specified. Note: The control parameters for Twitter messages will differ depending on what type of Twitter message you are creating. Please see Twitter documentation for Facebook security details. URL shortening Portrait Dialogue supports URL shortening. Depending on what message type you are working with, you might be given the opportunity to shorten URLs when inserting hyperlinks. Please refer to the Reference Help for more information about the URL shortening functionality. Visual Dialogue User Guide 115

116 Message Template Designer HTML images When you work with an HTML , you have the option of inserting images. You can choose between various ways of transmitting the images to the receiver (the customer). This is done in the Picture properties window. Inserting a picture To insert a picture when you are working with an HTML , choose Picture from the Insert tab. The Picture properties window opens. When you have finished setting the properties, click on OK, and the picture will be inserted into your template. Picture properties Field Picture Source This determines how the image is transmitted to the receiver: URL: Use this when you want to display an image that is already available on a web server. Enter the URL to the image in the Picture Source field. Example: Note: Make sure you do not unintentionally specify a local file. Published file: A Published file is a file (in this case, a picture) that is stored by the Dialogue Server. Browse: Use this button to display the Select Image window. Here you can select a picture that is already stored by the server because it has been used in another (or the current) template. You can also open a new picture file from disk. Link to file: When you use this, the picture will be available on the web server where the Web Applications are installed. The image is put on the web server by the application, and you just have to select an image using the Browse button. Attach file: Use this when you want the picture to be sent together with the as an attachment. Alternative Text: The text that is displayed if the image is not displayed for some reason, such as the if the Picture source path is wrong or the user has their image display turned off. Layout Alignment: Specifies how to align the image according to surrounding text. Border Thickness: Defines a border around the image. The thickness is specified in pixels. 116 Portrait Dialogue 6.0

117 Chapter 6: Messages Field Spacing Horizontal: Defines white space on the left and right side of the image, specified in pixels. Vertical: Defines white space on the top and bottom of the image, specified in pixels. Choosing image source URL Using a URL is the traditional way to display images in an HTML document. Some reader programs (for instance Microsoft Outlook) do not display URL images by default, but require the user to manually accept showing these images. You have to use an image that is already available on a web server. Link to file Seen from the receiver s point of view, this behaves much like URL and might also require the user to accept showing the images. When you send out large amounts of mail with Link to file images, you might experience performance problems on your web server when many customers open the in a short time interval. The image will automatically be available on the web. Attach file If you use Attach file, the image is sent as an attachment to the . These images will almost always be shown automatically. When you send images as attachments, the images will be sent with each individual and might put extra strain on your server, especially if you use large images. Also beware that some account providers do not allow their users to receive attachments above a certain size, thereby preventing your customers from viewing the images. HTML tracking You can track when an HTML sent by the system is opened by the customer. This is called tracking. To enable tracking of an , choose Tracking Image from the Insert tab. This will place an expression function in your template, which will be replaced by a small image during the merge process. Placing the image at the bottom of the template will usually give the best visual result, as the image will be invisible under most circumstances. When the customer opens the , the image will be downloaded, and the event will be logged in the system. Note: Some clients (for instance Microsoft Outlook) do not display images by default, but require the user to manually accept showing them. This prevents tracking from being 100% accurate. tracking usage tracking reports are available in the message browser and Dialog Designer. You can also use tracking in your selections. Visual Dialogue User Guide 117

118 Message Template Designer HTML link tracking When you insert hyperlinks into your , you have the option to track which recipients actually click on the links. There are two ways to do this: either enable link tracking for a link in the Hyperlink window, or manage several links at once in the Link overview window. Hyperlink properties The Hyperlink window is shown when you insert a new hyperlink or choose Hyperlink from the Format tab. Check Enable tracking for this link if you want to track clicks on the link. You can enter a link tracking name to distinguish between instances of the same link in different templates. Link overview The Link Overview window is accessed from the Design tab. Here you can sees all hyperlinks in the template that you are working on. You can enable or disable tracking on individual links by checking the box beside each link, or you can enable or disable all link trtacking by clicking on Track all links or Track no links. You can edit the link tracking name by pressing F2, or you can edit all link properties by clicking on Edit the selected link or pressing Enter. Link tracking usage Link tracking reports are available in the message browser and Dialog Designer. You can also use link tracking in your selections. HTML advanced features This topic covers advanced features that are available when editing an HTML Template. The web-hide feature It is possible to specify anchors and div elements in an HTML to be visible when a customer receives an and be hidden when viewing it in Customer View or in a Web Browser. In order to use this feature, include the mh_web_hide attribute in the html anchor or div element, as exampled below: The web-hide feature can be useful when e.g. including a Click here if you cannot see the link in your template; The link will thus be visible when the customer views the received in his inbox, but not visible if he views the in his web browser. See Viewing HTML in a web browser on page 119 for details on viewing an in a web browser. 118 Portrait Dialogue 6.0

119 Chapter 6: Messages Viewing HTML in a web browser When you send out HTML s, not all clients are able to handle the HTML correctly. Some clients also block images or modify the in other ways. To make it easier for your customers to view the as it was designed, you can add a hyperlink that will open the customer s web browser and display the . To insert a hyperlink to view the , choose Web links in the toolbox and choose View in Customer Web. The default text of the link is Click here if you cannot read this , but you can change it to anything you like. Note: The will not be available to view in a web browser until it has actually been created in a merge operation. This means that if you try to test merge the , the link will not work correctly. The Message Designer About the Message Designer module The Message Designer is used to create and edit templates for: s Facebook Letter Sms Twitter Templates can optionally be based on master templates (see Master template documentation in the Visaul Dialogue User Guide for details). Master template can consist of style sheets ( messages) and one or more body text areas. Templates overview The Templates overview page lists all Message Designer templates in the system. Template Type Use the Template Type field to shortlist a specific type of template, for example, or Sms. All filtered results appear in the list. Sorting and grouping The list is default sorted by created date. In order to sort the list on any of the fields, simply click the field column header. Click once again on the header in order to reverse the sort order. The list can also be grouped by any of the fields, e.g. Created by: Drag and drop the header you want to group by to the list header field "Drag a column to this area to group by it". Visual Dialogue User Guide 119

120 Message Template Designer Deleting a template To delete a template in the list, right click the template and click Delete. The action must be confirmed and is not reversible when completed. Creating a new template To create a new template, click one of: New Template New Facebook Template New Letter Template New Sms Template New Twitter Template This will open the Create New Template dialog. See Creating new templates for details. Filtering the list The list can be filtered by dragging column headings to the area immediately above and to the left of the Search field. This will filter the list by Name, Domain, Created by or Changed By. Alternatively, you can enter search criteria in the Search field and the list will update or filter automatically. Creating new templates In order to create a new template, click one of the new template options on the side menu, for example, New Template or New Facebook Template. The Create New Template dialog appears. This dialog contains three steps/fields that are required: 1. Enter the new template's name 2. Select the customer domain. This will display all master templates for the selected domain 3. Select the master template on which to base the template. For details regarding master templates, see the Master Template section in the Visual Dialogue help. Click the OK button to create the template; This will open the appropriate edit window corresponding to the template type chosen. For more information on editing a template, see Editing templates. Editing templates In order to edit a template, open templates overview and click on the template to edit. This will open the Template Editor. The Template Editor contains the following sections: Control parameters These fields are the most common template control parameters. Click on the icon to the right of the text boxes in order to insert a merge field. Text or Body page editor 120 Portrait Dialogue 6.0

121 Chapter 6: Messages This is the design area where you add, edit and remove items from the template. If you are editing an template you will see multiple body text areas. If you are editing any other template type, you will see a text editor. Left menu The left menu contains basic template information, template specific actions, testing and spam rating links and master template actions. Editing templates Item menu Each body area and each item in the template has an item menu. If a body area is empty, the Item menu will just contain an Add button. The following actions are available on the Item menu: Edit item Click this button to edit the item. See Editing items for details. Copy/Paste/Clipboard (sub menu drop down) Copy below Click this button to copy the item and paste it below the item Cut to clipboard Click this button to cut the item and place it on the clipboard. See Working with the item clipboard for details. Copy to clipboard Click this button to copy the item and place it on the clipboard. See Working with the item clipboard for details. Paste from clipboard Click this button to paste the last added item from the clipboard. See Working with the item clipboard for details. Delete item Click this button to delete the item Change style set (sub menu drop down) Click this button to set/change the style set for the item. See Style sets for details. Add static item (sub menu drop down) Click this button to add a static item below the item Add item below Visual Dialogue User Guide 121

122 Message Template Designer Click this button to add a new item below the item. This will open the item Add new item dialog. See Adding new items for details. Add item above Click this button to add a new item above the item. This will open the item Add new item dialog. See Adding new items for details. Move down Click this button to move the item down (swap with the item below in the body area) Move up Click this button to move the item up (swap with the item above in the body area) Adding new items Adding an item to an empty body area When a body area is empty, the menu will only contain one button: Add. Click the Add button to add a new item to the empty body area. Adding an item below an existing item In order to add a new item below an existing item, click the Add below button on the existing item's Item menu. Adding an item above an existing item To add an item above an existing item, click the Add above button on the existing item's Item menu. Performing any of these steps will open the Add new item dialog. Browse and select the item type to add and click Ok. Selecting Open item edit dialog will open the newly added item's edit dialog immediately after adding the new item. See Editing items for details on editing different item types. Each item type has its own item edit control. Editing items Editing items In order to edit an template, click the the relevant body text area and click on the Edit item button ( ) on the Item menu. This will open the Edit item dialog. This dialog will contain one edit section for each part of the item. General item properties All items have a set of general properties. These properties can be found at the bottom of the item edit dialog. Content alignment 122 Portrait Dialogue 6.0

123 Chapter 6: Messages Content alignment aligns the content of the item. Possible values are: NotSet: Alignment is not set on the item. This will normally equals Left Right: Aligns to the right edge Center: Aligns to the center Left: Aligns to the left edge Justify: Aligns to the left and right edge Item condition Using Item condition, it is possible to define a customer related condition for the item. This statement is executed at merge-time, deciding if the item is included in the merged . See Item conditions for details. Item type specific properties Each item type has it's own item edit control. For editing text items, see Text items for details. For editing image items, see Image items for details. For editing content object items, see Content object items for details. For editing table items, see Table items for details. For editing mixed items, see Mixed items for details. For editing container items, see Container items for details. Text items When editing a text item type, the edit dialog will contain one text editor control for each text item part. The text editor has the following toolbar actions: Undo Undoes the last action Redo Redoes/Repeats the last action, which has been undone Cut Cuts the selected content and copies it to the clipboard Copy Copies the selected content to the clipboard Paste plain text Pastes plain text (no formatting) into the editor Paste from word Pastes content copied from Word and removes the web-unfriendly tags Paste Visual Dialogue User Guide 123

124 Message Template Designer Pastes the copied content from the clipboard into the editor Font size Allows the user to apply to the current selection font size measured in pixels (px) Bold Applies bold formatting to selected text Italic Applies italic formatting to selected text Underline Applies underline formatting to selected text Foreground color Text Color (foreground) button - Changes the foreground color of the selected text. The colors available are dependent on settings in the master template. Background color Text Color (background) button - Changes the background color of the selected text. The colors available are dependent on settings in the master template. Bullet list Creates a bulleted list from the selection Number list Creates a numbered list from the selection Indent Indents paragraphs to the right Outdent Indents paragraphs to the left Link properties Makes the selected text a hyperlink and/or opens the Link properties dialog Remove link Removes the hyperlink from the selected text Insert merge field Opens the Merge field dialog. Selecting or double clicking a field in this dialog will insert (paste) the merge field into the text at the cursor's position Insert merge field start tag Inserts (pastes) a merge field start tag (<<) into the text at the cursor's position Insert merge field end tag Inserts (pastes) a merge field end tag (>>) into the text at the cursor's position 124 Portrait Dialogue 6.0

125 Chapter 6: Messages Toggle full screen mode Image items Switches the text editor into Full Screen Mode When editing an image item type, the edit dialog will contain one image editor control for each image item part. The image edit control has the following settings: Published file Use this when you want to insert a published file (in this case a picture) that is stored by the Dialog Server. Select button: Use this button to display the Select Image dialog box. Here you can browse all applicable published files on the Dialog Server. Image location Use this when you want to display an image already available on a web server. Enter the URL to the image in the Picture Source field. Example: NB: Make sure you don't unintentionally specify a local file. Tooltip/alternative text Sets a text alternative and for the image Size Sets the size of the image. Toggling the chain between the two text boxes locks or unlocks the aspect ratio for the image size. Click the Reset size button in order to reset the image's size to it's original size. Note: Embed image The maximum image size may be limited by settings in the master template. This setting is only valid when referring a published file. Checking this option will embed the published file as an attachment in the (else the published file will be referred by an url). Enable image link Check this option to enable the image as an hyper link. Image link url The url address or Web Link of the image link, when enabling the image as an link Open link in new window Opens the image link in a new window. This settings is recommended on when enabling the image as an link Enable link tracking Check this option to enable link tracking for the image link Visual Dialogue User Guide 125

126 Message Template Designer Link name The name of the tracked link. This will be automatically populated when enabling link tracking Content object items Table items When editing a content object item type, the edit dialog will contain one content object editor control for each content object item part. The content object edit control has the following setting: Select content object Use this drop down list to select the content object to use When editing a table item type, the edit dialog will contain one table edit control for each table item part. Adding a new row to the table Click Add new row in order to add a new row to the table. This will insert an empty row at the bottom of the table. Adding a new column to the table Click Add new column in order to add a new column to the table. This will insert an empty column at the end of the table. Editing the content of the cells in the table Click a cell to edit it's content. The cell content is edited using the text editor below the table. The cell is continuously updated when working in the text editor. This text editor is the same editor used when editing text items. Thus see Text items for details on using this text editor. Mixed items Deleting rows and columns In order to delete a row or a column, click the delete button in the row's or column's header cell. Items of type Mixed can contain parts of one or multiple different item types. When editing a mixed item type, the edit dialog will contain one item type specific editor control for each different item part. For editing text item parts, see Text items for details. For editing image item parts, see Image items for details. For editing content object item parts, see Content object items for details. For editing table item parts, see Table items for details. Container items 126 Portrait Dialogue 6.0

127 Chapter 6: Messages A container item is a special item for organizing multiple child items in a tabular fashion. The items are organized in columns and may be horizontally aligned: Container item properties The container item edit control has the following settings: Align items horizontally This setting will horizontally align items in the different columns in the container Span static items cross all columns This setting will span static items cross all columns in the container Column width Optional. These text boxes sets the width of the columns. When setting the column's widths, and the container has an width of 100% (standard), it is recommended that one of the column's width is left blank in order for the column to dynamically resize itself to the remaining container width. Visual Dialogue User Guide 127

128 Message Template Designer Clicking the Click here to automatically set width on all columns link will thus set width on all columns except the last. Column spacing Optional. Use this setting to add a spacer column between all columns in the container. Images in containers If the Body Area's maximum image width is set, images (item type image) are scaled down to this width (if they are wider than this width). If adding an item type image to a container, similar logic will be applied to the image: If the column width is set for the containing container column and the image is wider than this value, the image is scaled down to this width. Working with the item clipboard The item clipboard provides functionality for cutting or copying items to a clipboard and pasting a copy of this item anywhere in the template (or other templates). The clipboard's scope is within your user session, thus the clipboard will be reset when logging on the application. Cut and copy to the clipboard On an item's menu, click the Copy/Paste/Clipboard button ( ). This will open a drop down menu - this menu provides the following clipboard related actions: Cut to clipboard Click this button to cut the item and place it on the clipboard. Copy to clipboard Click this button to make a copy of the item and place it on the clipboard. Paste from the clipboard There are two ways to paste an item from the clipboard: Paste the last added item from the clipboard On the Copy/Paste/Clipboard menu, click Paste from clipboard - this will paste the last added item from the clipboard. Paste items from clipboard 1. Open the Add new item dialog. 2. Open the Clipboard tab. This open the Item clipboard. 3. Double-click the item you want to paste. 128 Portrait Dialogue 6.0

129 Chapter 6: Messages Deleting items from the clipboard In order to delete one or many items from the item clipboard, follow these steps: 1. Open the Item clipboard (as described in the previous section). 2. On the item to delete, click the delete button in the upper right corner or Click the Clear clipboard button to remove all items from the clipboard. Style sets Style sets are used for applying different styles to items in your template. Style sets are configured in the Master template. See the master templates documentation for details. Applying style sets In order to apply a style set on an item, follow these steps: 1. On the item menu, click the Change style set button ( the item. 2. Click the style set to apply. ). This will list all applicable style sets for Resetting an item's style set In order to reset an item's style set, follow these steps: 1. On the item menu, click the Change style set button ( ). 2. Click the Default style set. Item conditions It is possible to define an item condition for any of the items in a template. Using Item condition, it is possible to define a conditional statement for the item. This statement is executed at merge-time, deciding if the item is included in the merged . Defining an item condition In order to define an item condition, click the Edit condition at the bottom of the Item edit dialog. This will open the Item Condition dialog. The item condition can be defined either using a selection or an expression. Defining an item condition using a selection The selections available in this dialog are defined in Visual Dialogue. See About Selections in the Visual Dialogue documentation for details on creating selections. Follow these steps to define an item condition using a selection: 1. Check the Customer is in selection radio button Visual Dialogue User Guide 129

130 Message Template Designer 2. Select a Selection from the drop down list The item will be included if the customer is in the specified selection. If checking the Is not in selection, the item will be included if the customer is not in the specified selection. Defining an item condition using an expression Follow these steps to define an item condition using an expression 1. Check the Expression radio button 2. Write a expression in the text box. The item will be included if the customer is in the expression's result set. Click the Test expression button at the right of the text box to test the expression's syntax Changing master templates It is possible to change the master template that template's are based on to other master templates in the same customer domain. Changing the master template will change all non-content data in the template; This includes the new master template's HTML code and style sheets, and all Item definitions' HTML code. If the item restrictions (in the new master template's body areas) is further constricted, items may be removed when changing the master template. Reapplying master templates It is possible to reapply the master template that template's are based on. Reapplying the master template will refresh all non-content data in the template; This includes the master template's HTML code and style sheets, and all Item definitions' HTML code. If the item restrictions (in the master template's body areas) is further constricted, items may be removed when reapplying the master template. Tracking overview tracking You can track when an HTML sent by the system is opened by the customer. This is called tracking. To enable tracking of an , check the Enable tracking in the Tracking Overview dialog. This will insert a tracking image at the end of the . This image will under most circumstances be invisible for the end user. When the customer opens the , the image will be downloaded and the event is logged by the system. Note that some clients (for instance Microsoft Outlook) don't display images by default, but require the user to manually accept showing them. This prevents tracking from being 100% accurate. Link tracking The tracking overview contains a combined list of all links in all text items, table items and image items. 130 Portrait Dialogue 6.0

131 Chapter 6: Messages You can enable or disable link tracking on individual links by checking the checkbox beside each link, or you can enable or disable all links by clicking the Toggle track all links button. You can edit the link tracking name using the text box to the right of the check box. Link tracking usage Link tracking reports are available in the message browser and the dialog designer. tracking usage tracking reports are available in the message browser and the dialog designer. You can also use tracking in you selections. Editing Facebook, SMS, Letter, and Twitter templates In order to edit a template, double-click a Facebook, Twitter, Sms, and Letter template on the Templates Overview screen. This will open the Template Editor screen along with the Text Editor. The Template Editor contains the following sections: Control parameters These fields are the most common template control parameters. Click on the icon to the right of the text boxes in order to insert a merge field. Text or Body page editor This is the design area where you add, edit and remove items from the template. If you are editing an template you will see multiple body text areas. If you are editing any other template type, you will see a text editor. Left menu The left menu contains basic template information, template specific actions, testing and spam rating links and master template actions. Working with the Text Editor In order to edit a template using the Text Editor, double-click a Facebook, Sms, Letter, or Twitter template in the Templates Overview screen. This will open the Template Editor along with the Text Editor. The Text Editor provides the following text editing options: Undo Undoes the last action Redo Redoes/Repeats the last action, which has been undone Cut Cuts the selected content and copies it to the clipboard Copy Copies the selected content to the clipboard Paste Visual Dialogue User Guide 131

132 Message Template Designer Pastes the copied content from the clipboard into the editor Insert merge field Opens the Merge field dialog. Selecting or double clicking a field in this dialog will insert (paste) the merge field into the text at the cursor's position Insert merge field start tag Inserts (pastes) a merge field start tag (<<) into the text at the cursor's position Insert merge field end tag Inserts (pastes) a merge field end tag (>>) into the text at the cursor's position Insert a hyperlink Allows you to insert a hyperlink Toggle full screen mode Switches the text editor into Full Screen Mode Testing and spam rating Test options The Test Options dialog allows you to specify the set of customers you want to use when test merging the template. Specify a set of customers Use this setting to specify a set of customers to use when test merging the template Selection: The selection used to select the set of customers. Setting this to <Not selected> will return the first found customers in the database. Max number of customer: The maximum number of customers returned when test merging. This must be an integer value between 1 and 20 Expression: An optional expression used to filter the customers returned by the selection Specify a single customer Use this setting to specify a single customer (using the customer ID) to use when test merging the template Testing a template The Test template window allows you to test merge a template and preview the result in your browser. The template is merged using a set of customers into a set of messages. See Test options on how to select these customers. Browsing the merged messages Use the First, Previous, Next and Last buttons to preview the test merged messages. Test sending a message Click the Test send button (envelope icon) to test send the message to an recipient. See Test sending a template for details. 132 Portrait Dialogue 6.0

133 Chapter 6: Messages Spam rating a message Click the Spam rate button (red flag icon) to spam rate the message. This will open the Spamrating report window. See Spam rating a template for details. Printing a test message Click the Print message button (printer icon) to print the message. This will normally open your system's Print dialog. Disabling images - messages only Click the Disable images button to disable all images used in the . This will disable all html images (html IMG tags) and all background images referred in CSS. The purpose of this is to preview a message as it will be displayed in an viewer (e.g. outlook) which disables images in HTML s by default. Test sending a template When designing a message in the Template Designer, it is possible to test send the message. This functionality makes it easy to test the message and see how it looks when received by the client. A message can be test sent by following these three steps: 1. Test merge the message: Open the Test message window 2. Open the Send test message dialog: Click the Test send button (envelope icon) 3. Send the message: Enter the key control parameter for example, cellular number for an Sms, or address for an message and click OK. Spam rating a template ( only) Mass communication by is an important part of Portrait Dialogue. One problem when sending s is the possibility of the mail being filtered in a spam filer. To help our customers avoid this we want to give them an opportunity to test the messages they are composing to see how likely it is they will be marked as spam. Spam rating a template In order to spam rate an template, open the Spamrating report window. This will test merge the and produce a spam rating report for the resulting message. The spam score indicates the likelihood that the will pass spam filters. Control parameters Control parameters are used to control the delivery of your message. You can use merge fields in the control parameters. You can for instance use an address merge field in the control parameter To address in templates to merge the customer s address into the message. Visual Dialogue User Guide 133

134 Message Template Designer Control parameters for messages The following control parameters are available in the list. Most of these control parameters are values defined by the standard protocols. However, some are proprietary and control the content of the , or how the is sent. Parameter Subject To address From address CC address BCC address Reply address Attachments The subject of the . The address of the receiver of the . Normally, this will be set to the address of the customer. The address from which the is sent. Indicates carbon copy recipients for the message. In other words a list of addresses that will receive a copy of the . Indicates blind carbon copy recipients for the message. The address that the recipient will send to, if he or she replies to the . This value only needs to be specified if it is different from the From address. A semicolon separated list of additional files to attach to the message. Local paths, as seen from the Dialog Server, must be specified. Validate target address Specifies if the address should be validated before trying to send the . Default value is True. Priority Content transfer encoding CharSet Organization Receipt recipient Insert identifier in header Add plain text part Plain text part The priority as it appear to the recipient. This parameter does not control the priority when the is sent. Default value is Normal. Specifies the MIME encoding for the message during message transmission. Indicates the character set used for the message. Identifies the organizational affiliation for the message author. Return receipt address. Controls whether a specific identifier is inserted in the header. This identifier is used by the system to identify bounced s. Specifies whether a plain text part is added to an HTML . The plain text part should be specified in the parameter Plain text part. Default value is False. The plain text part added to en HTML if the Add plain text part parameter is set to True. Example: This is a mail message in HTML format. Please enter the url below in your web browser to read it: <<mh_message_url>> In the example, the tag mh_message_url will be converted to a link to a web page showing the HTML version of the . is used to insert a line break. 134 Portrait Dialogue 6.0

135 Chapter 6: Messages Control parameters for Facebook messages The following control parameters are used with Facebook message types. Parameter Facebook username and Facebook access token Location Private Image filename Image URL Link URL Link name Link description Facebook sequrity keys. Your customer data should contain these keys and they have probably been gathered by using a Facebook Application that requested access to a Customers Facebook account. You can provide location information by specifying the Facebook Page ID that is linked with the required location. See Facebook for more information on locations. The Wall status can be made private by specifying True for the Private parameter. Used when uploading an image to Facebook, provide an image filename. A local path, as seen from the Dialogue Server, must be specified. The currently supported image formats are JPG, GIF, BMP, TIF and PNG. Please refer to Facebook for more information on the currently supported image sizes. If available, a link to the picture included with this post. The link attached to this post. The name of the link. The caption of the link (appears beneath the link name). Note: The control parameters for Facebook messages will differ depending on what type of Facebook message you are creating. Please see Facebook documentation for Facebook security details. Control parameters for Twitter messages The following control parameters are used with Twitter message types. Parameter Access token, Access token Secret, Consumer Keyand Consumer Secret Send to screen name Attached image path Your data should contain these keys and they have probably been gathered by using a Twitter Application that requested access to a Customers Twitter account. Used to identify the Twitter user that the direct message will be sent to. An example These users need to be followers of the account being used to send the Direct Message from. Used when uploading an image to Twitter, provide an image filename. A local path, as seen from the Dialogue Server, must be specified. Note: The control parameters for Twitter messages will differ depending on what type of Twitter message you are creating. Please see Twitter documentation for Twitter security details. Visual Dialogue User Guide 135

136 Message Template Designer Template properties The Properties window can be opened from the left menu. The window contains two tabs: the General tab and the Advanced tab. The General tab This tab shows the following information: Name The name of the template Customer domain The customer domain the template gets its customers from Document type The document type of the template Master template The name of the master template the template is based on Created by The login name of the user who created the template Created date The date and time the template was created Last modified by The login name of the user who last modified the template Last modified The date and time the template was last modified The Advanced tab This tab enables you to control the following: Generate activity If you want activities to be created when messages based on the template are sent, choose an activity type here. One activity will be created for each message. Activity description If you chose to generate an activity when sending messages, you can enter the activity description here Priority This is the system priority used when the message is sent. Set priority to above normal when it is important that the customer receives the message relatively quickly. An example may be an that contains a "forgotten password". 136 Portrait Dialogue 6.0

137 Chapter 6: Messages Use outbox If you check this, all messages will be sent to an outbox where you can view and check that the messages are ok before actually sending them. This can be done in the Message Manager. If you do not check, all messages will be sent as soon as they are produced. Visual Dialogue User Guide 137

138

139 Questionnaires 7 In this section: About questionnaires How questionnaires are used Creating a new questionnaire Questionnaire Designer Building a questionnaire URL Response tracking Browsing questionnaires Running the questionnaire report Exporting response data Deleting response data Questionnaire styles Script Object Model Client-side events and scripts

140 About questionnaires About questionnaires About questionnaires Questionnaires introduces the concept of receiving structured responses from persons, companies, prospects or other target groups of your business process. Definition of a questionnaire A questionnaire is basically a template containing a set of questions and answer alternatives, which define the data structure of a response. A questionnaire will also contain information about: when, where and how a questionnaire can be used the visual layout of the questionnaire the flow controlling the logic of how questions are displayed to a respondent. Definition of an answer form An answer form is a single set of answers to the question structure defined in a questionnaire. An answer form can be either complete or incomplete. If it is complete, then the respondent has completed answering the questionnaire. If incomplete, the respondent has only partly completed the questionnaire. For example, it is possible to pause answering and continue at a later point in time. In the mean time the answer form will be incomplete. Definition of a respondent A respondent is the customer returning an answer form. A respondent might be identified or anonymous. How questionnaires are used Questionnaire usage Questionnaires are used to collect structured information from customers. Because the information is structured it can easily be analyzed and used to create selections, customer segmentation, reports and to take decisions in dialogs and other business processes. Answers to a questionnaire is stored in the Dialog Database. This maximizes the reuse of collected answers, because all answers are available at any given time to any module inside Portrait Dialogue, as well as to other third-party applications. Examples of questionnaire usage are among others: to collect key information from customers (e.g. address information, habits, interests) to receive a booking or registration for an event 140 Portrait Dialogue 6.0

141 Chapter 7: Questionnaires to measure customer satisfaction to carry out a post-event evaluation survey. Questionnaire access In general, questionnaires are designed and managed in Visual Dialogue, while answer forms are available in the different Web application modules. Visual Dialogue contains a questionnaire designer with a large set of tools to set up the different parts of a questionnaire. It includes WYSIWYG preview and test features, as well as advanced scripting capabilities. Visual Dialogue also contains a wizard for exporting answer forms to different file formats, including Microsoft Excel. The Customer Web Access module makes the questionnaire available to end-customers through a browser-independent web interface. Identified customers may answer questionnaires by clicking on a link in a received or by logging in using a login id and a password. Anonymous respondents may answer questionnaires by following a link on a web page, for example in an online newspaper advertisement. The Customer View and the Telemarketing web modules make questionnaires available to external users like customer consultants. By using the Dialog Server API, integrators can easily access questionnaires and answer forms. For example, answer forms can easily be registered in the Dialog Database by sending a simple XML document containing the answers to the Dialogue Server. Creating a new questionnaire To create a new questionnaire, choose Questionnaire from the Create tab in Visual Dialogue. The New Questionnaire Wizard opens. Step 1 On the first page of the wizard, the new questionnaire is given a name and optionally a description. You also select the language to use in the questionnaire. All texts generated internally, e.g. validation error messages, will be in this language. Checking the Enable in Customer Web Access (CWA) box enables the questionnaire for access by respondents on the internet. Step 2 On the second and last page of the wizard, the survey type is selected. The survey type controls the types of response that will be valid for this questionnaire. There are three different survey types: Mixed mode: Both anonymous and identified respondents can answer the questionnaire. This is the least restrictive survey type. Anonymous: Only anonymous answers are allowed. Anonymous answer forms are never linked to a customer in the database. Visual Dialogue User Guide 141

142 Questionnaire Designer Identified: Anonymous answers are not allowed. The answer forms are always linked to a customer in the database. Optionally, for the mixed-mode and identified survey types, a customer domain can be selected, and only customers in that domain can answer the questionnaire. The customer domain is selected in the Target customer domain drop-down list. Note: All texts and options selected in the wizard can be changed at a later time in the Questionnaire Properties window. After you complete the New Questionnaire Wizard, the Questionnaire Designer is displayed. Questionnaire Designer About Questionnaire Designer About Questionnaire Designer Questionnaire Designer is the tool inside Visual Dialogue where questionnaires are defined. The Questionnaire Designer has two main views: Questions View and Layout View. In brief, you can define questions and answer alternatives in Questions View, while you can edit visual presentation and flow in Layout View. Questions View About Questions View Questions View In Questions View, all sections and questions in the questionnaire are defined. This means that this is where the structure of the questionnaire is defined. In Layout View, different layouts can be applied to the same set of sections and questions. Sections A section is a group of questions. A questionnaire contains one or more sections, numbered from 1. Each section typically contains one or more questions. Questions A question is a basic element in a questionnaire. A question will either be answered, or not, in an answer form. Some questions are required to be answered, while others are not. There are different kinds of questions: simple questions (text, date, integer, etc.), multi-option questions, matrix questions, and more. Some of the question types, like multi-option questions, have answer alternatives. The different question types can have different rules such as a maximum length, a maximum value, a minimum value, and so on. 142 Portrait Dialogue 6.0

143 Chapter 7: Questionnaires For example, the question How often do you go on vacation? is a multi-option question, where the respondent can choose one of the alternatives (Never, Once a year, Twice a year ). Question and alternative keys Each question or alternative has its own key. A key is a short string (maximum 8 characters) that uniquely identifies the question or alternative. Keys are automatically generated when new questions and alternatives are added, but you can change them. The keys are used to refer to questions and alternatives in scripts when defining questionnaire flow. In addition, the keys are used as column headings when exporting answers (see Exporting response data on page 168), and when posting answer forms as XML documents to the Dialog Server API (see the Reference Help). Creating a new section Creating a new section To create a new section, right-click anywhere in the tree view and select New section. The new section s Section Properties window appears. Enter the new section s properties and click on OK. The section s properties The section s properties are: Section Caption: The section s caption (name). This text can include merge tags. Instructions: The section s instructions. This text is displayed below the section s caption. This text can include merge tags. Creating a new question Creating a new question To create a new question, right-click on the section where the question is to be added and choose New question, or select the section and press Insert on the keyboard. The Select Type of Question window opens. The new question options are: Normal: Creates a normal question. Select the type of normal question from the Type list: Simple: Creates a simple question. Multi option: Creates a multi-option question. Ranking: Creates a ranking question. Rating: Creates a rating question. Matrix: Creates a matrix question. When you select this question type, the following options must be set: Rows: The number of rows in the matrix. Visual Dialogue User Guide 143

144 Questions View Columns: The number of columns in the matrix. Multi choice: Select this option if the matrix question should initially be created with multi-choice questions. Single choice: Select this option if the matrix question should initially be created with single-choice questions. Simple question properties A simple question is a question type where only one answer is possible, e.g. a text string, a date, or a number. Simple question properties To display the properties for a simple question, select the question node and choose Edit Selected Item from the Questions tab, or right-click on the question node and choose Edit Selected Item, or simply double-click on the question node in the tree view. Alternatively, click on the question caption in the Question details window. Basic properties of simple questions A simple question has a set of basic (simple) properties and a set of advanced properties. You can toggle between simple and advanced view by pressing Advanced >>/Simple << on the right-hand side of the properties window. The basic properties are described below: Section caption: The caption of the parent section. This property makes it possible to alter the section s caption from the question s property window. This text can include merge tags. Question caption: The question s caption. This text can include merge tags. Answer required: If this box is checked, the question must be answered. Key: The question s key, used to access the question from script and merge tags, for example. Data type: The question s data type. This property sets the data type allowed when answering the question. The data type options available are: String: Any characters can be entered in response to the question. Integer: Only integers can be entered in response to the question. Float: Only floating-point numbers can be entered in response to the question. Date: Only date values can be entered in response to the question. Datetime: Only date/time values can be entered in response to the question. If Answer required is not checked, a date can be given without a time, but a time cannot be given without a date. If Answer required is checked, both date and time must be given. Advanced properties of simple questions Link to domain field: See Linking a simple question to a domain field on page 145. Default value: This sets a value that is filled in by default. This text can include merge tags. Max. length: This specifies the maximum number of characters that the respondent is allowed to enter when answering the question. Only available for questions with string data type. 144 Portrait Dialogue 6.0

145 Chapter 7: Questionnaires Min. value: This sets the minimum (date or numeric) value that the respondent is allowed to enter when answering the question. Only available for questions with data types other than string. Max. value: This sets the maximum (date or numeric) value that the respondent is allowed to enter when answering the question. Only available for questions with data types other than string. Control type The question s control type. The control types that are available depend on the data type: Textbox: A standard textbox control. Available for all data types. Date/time popup: A standard textbox control with a popup button displaying a date-picker popup window. Only available for date and date/time data types. No. of lines: This property sets the number of lines for the string textbox. If the value is set to 2 or more, a textarea (multi-line textbox) will be displayed for the question. Only available for questions with string data type. Linking a simple question to a domain field You can link a simple question to a customer domain field. This requires that a Target Customer Domain is configured under Questionnaire Properties. Linking to a domain field gives you two extra options: Default value You can use the existing value of the domain field as a default value for the answer of the question. To do this, check Use domain field as a default value. Updating the domain: You can use the response value to automatically set the value of the domain field as soon as the respondent finishes answering the questionnaire. To do this, check Automatically update domain field with answer. Multi-option question properties A multi-option question is a question with one or more answer alternatives (options). Multi-option question properties To display the properties for a multi-option question, select the question node and choose Edit Selected Item from the Questions tab, or right-click on the question node and choose Edit Selected Item, or simply double-click on the question node in the tree view. The multi-option question properties window opens. The multi-option question properties explained: Section caption: The caption of the parent section. This property makes it possible for you to alter the section s caption from the question s property window. The text can include merge tags. Question caption: The question s caption. This text can include merge tags. Answer required: If checked, the question must be answered. Key: The question s key, used to access the question from script and merge tags, for example. Multi choice: Select this option if the question allows multiple answers, i.e. if multiple alternatives can be selected by the respondent. Single choice: Select this option if the question only allows one answer, i.e. only one alternative can be selected by the respondent. Visual Dialogue User Guide 145

146 Questions View Options: The list of the question alternative options. The options will be displayed in the order that they are listed. To alter this sequence, use the up and down arrows to move the options. To add an option (alternative), click on the plus sign. To remove an option, click on the minus sign. Select the alternative and press Enter, or click on the edit sign (the pen), to edit the option. This opens the option s properties window. Caption: The option s caption. Selected by default: Check this box to cause the option to be selected by default. Use a textbox control: Check this box to display the option with a textbox input control. Key: The option s key, used to access the option from script and merge tags, for example. Multi choice: Available if the question is multi-choice only. The option is multi-choice and can therefore be selected together with other options. Single-choice: Available if the question is multi-choice only. The option is single-choice, and cannot therefore be selected together with other options. Selecting this option will clear all other selected question options. Allowed number of options to answer: This property sets the minimum and maximum number of options that the user is allowed to answer. Available if the question is multi-choice. Min: The minimum allowed number of options to answer. Max: The maximum allowed number of options to answer. Control type: The question s control type. The control types available are: Check boxes: Available for multi-choice only. Radio buttons: Available for single-choice only. List box: Available for both multi-choice and single-choice. Drop-down list: Available for single-choice only. No. of lines: Available for list-box control type only. This property sets the number of lines for the listbox control. Cannot be less than two. Ranking question properties A ranking question is a question type with one or more items that have to be ranked. The respondent ranks the items by entering their desired ranking (from one upward) in textboxes. Ranking question properties To display the properties for a ranking question, select the question node and choose Edit Selected Item from the Questions tab, or right-click on the question node and choose Edit Selected Item, or simply double-click on the question node in the tree view. Alternatively, simply click on the question caption in the Question details window. The ranking question properties window opens. The ranking question properties explained: Section caption: The caption of the parent section. This property makes it possible to alter the section s caption from the question s property window. This text can include merge tags. Question caption: The question s caption. This text can include merge tags. Answer required: If this box is checked, the question must be answered. 146 Portrait Dialogue 6.0

147 Chapter 7: Questionnaires Key: The question s key, used to access the question from script and merge tags, for example. Items to rank: The list of items to rank. The items will be displayed in the order that they are listed. To alter this sequence, use the up and down arrows to move the items. To add an item, click on the plus sign. To remove an item, click on the minus sign. To edit an item (ranking item properties), select the item, and press Enter or click on the edit sign (the pen). Caption: The item s caption. Key The item s key, used to access the item from script and merge tags, for example. Respondent must rank at least: This property sets the minimum number of items that the respondent must rank. Respondent cannot rank more than: This property sets the maximum number of items that the respondent is allowed to rank. Rating question properties A rating question is a question with one or more alternatives (options) to rate. The alternatives are rated by distributing points from a total sum, or pot. Rating question properties To display the properties for a rating question, select the question node and choose Edit Selected Item from the Questions tab, or right-click on the question node and choose Edit Selected Item, or simply double-click on the question node in the tree view. Alternatively, simply click on the question caption in the Question details window. The rating question properties window opens. The rating question properties explained: Section caption: The caption of the parent section. This property makes it possible to alter the section s caption from the question s property window. This text can include merge tags. Question caption: The question s caption. This text can include merge tags. Answer required: If this box is checked, the question must be answered. Key: The question s key, used to access the question from script and merge tags. Items to rate The list of the question items to rate. The items will be displayed in the order that they are listed. To alter this sequence, use the up and down arrows to move the items. To add an item, click on the plus sign. To remove an item, click on the minus sign. Select the item and press Enter, or click the edit sign (the pen), to edit the item (rating item properties). Caption: The item s caption. Key: The item s key, used to access the item (alternative) from script and merge tags, for example. Total number of points to distribute: This property sets the total sum of points to distribute between the items. Required to rate all items: If this box is checked, all items must be rated. Limit of points per item: Sets the minimum and maximum points allowed to be given to one item. Min: Each item must be given at least this many points. Max: Each item must be given at most this many points. Visual Dialogue User Guide 147

148 Questions View Default number of points per items: The default number of points initially set on all items. Matrix question properties A matrix question is used to arrange question controls inside a matrix grid. A matrix question contains one or more simple or multi-option questions. The question types supported in matrix questions are multi-option single-choice (radio buttons), multioption multi-choice (checkboxes), and simple questions. The matrix can be aligned vertically and horizontally. Matrix question properties To display the properties for a matrix question, select the question node and choose Edit Selected Item from the Questions tab, or right-click on the question node and choose Edit Selected Item, or simply double-click on the question node in the tree view. The matrix question properties window opens. The matrix question properties explained: Section caption: The caption of the parent section. This property makes it possible to alter the section s caption from the matrix s property window. This text can include merge tags. Matrix caption: The matrix s caption. This text can include merge tags. Use horizontal layout: The default ( normal ) matrix layout. Using this layout, the multi-option questions in the matrix are aligned from left to right, in rows. Use vertical layout: Using vertical layout, the multi-option questions in the matrix are aligned from top to bottom, in columns. In other words, the matrix is flipped vertically, meaning that rows become columns and columns become rows. Key: The matrix s key, used to access the matrix from e.g. script and merge tags. Column: The column caption of the selected cell s column in the matrix grid. To add a column, click on the plus sign to the right of the column textbox, and enter the name of the new column. To delete a column, click on the minus sign to the right of the column textbox. Row: The row caption of the selected cell s row in the matrix grid. To add a row, click on the plus sign to the right of the row textbox, and enter the name of the new row. To delete a row, click on the minus sign to the right of the row textbox. Cell type: The question type of the selected cell or column. The cell types are: Text edit: The selected cell is a simple question with datatype string. Number edit: The selected cell is a simple question with datatype numeric (integer or float). Date edit: The selected cell is a simple question with datatype date (date or datetime). Radio button: The selected cell s row contains a multi-option single-choice question. Check box:the selected cell s row contains a multi-option multi-choice question. To clear a cell, select the cell and click the minus sign to the right of the cell type option. 148 Portrait Dialogue 6.0

149 Chapter 7: Questionnaires Matrix simple question properties To edit a simple question in a cell, select a cell in the matrix s grid containing the simple question and click the edit sign (the pen). The properties window for the question opens. Answer required: If checked, the question must be answered. Data type: The questions datatype. These options depends of the Cell type (in the matrix properties). Max. length: This property is available only when the question s datatype is string. The property sets the maximum number of characters allowed to enter when answering the question. Min. value: This property is available only when the question s datatype is other than string. The property sets the minimum (date or numeric) value allowed to enter when answering the question. Max value: This property is available only when the question s datatype is other than string. The property sets the maximum (date or numeric) value allowed to enter when answering the question. Default value: This property sets the question s default value. The question will thus have this value set by default when answering the questionnaire. This text can include merge tags. Control type: The question s control type. The control types (depending on the datatype) available are: Textbox: Available for all the datatypes. A standard textbox control. Date/time popup: Available for date and datetime datatypes only. A standard textbox control with a popup button displaying a datepicker popup window. Question key: The question s key, used to access the question from e.g. script and merge tags. Matrix multi-option question properties To edit a multi-option question in the matrix, select a cell in the matrix s grid containing a multi-option alternative and click the edit sign (the pen). The properties window for the simple multi-option question opens. Question requires an answer: If this box is checked, the question must be answered. Selected by default: Check this box to cause the alternative to be selected by default. Use a textbox control: Check this box to display the alternative with a textbox input control. Multi choice: Select this option to set the question type to be multi-choice, meaning that multiple alternatives can be selected. Checkboxes are used. Single choice: Select this option to set the question type to be single-choice, meaning that only one alternative can be selected. Radio buttons are used. Question key: The question s key, used to identify the question from script and merge tags, for example. Alternative Key: The alternative s key, used to identify the alternative from script and merge tags, for example. Image properties Images can be added to questions and alternatives. One or more images can be added to a question. These images are called question images. One image can be added to each alternative in a multi-option question. These images are called alternative images. Visual Dialogue User Guide 149

150 Layout View in Questionnaire Designer Question images To add images to a question or alternative, select the question in the tree view and choose Images from the Questions tab, or right-click on the question in the tree view and choose Images. Click on the plus sign to add question images. The Browse image window opens. Browse and select the image to add. The Images list shows the question images added to the question. Select an image in the list to display and edit the image s properties: A preview of the image is shown in the preview area. The text in the Image caption textbox is shown as the image s tooltip text. To select another image, click on Browse to open the Browse image window. To export the image to a file ( save as ), click on Export. The images are displayed in the questionnaire in the order they are listed in the Images list. Alternative images To add images to question alternatives, select the question in the tree view and choose Images from the Questions tab, or right-click on the question in the tree view and choose Images. Then select the Alternative images tab. Select an alternative from the Alternatives list, and click on Browse button to add an image to the alternative. The Browse image window opens. Browse and select the image to add. Select an alternative in the Alternatives list to display and edit the alternative image s properties. A preview of the image is shown in the preview area. The text in the textbox Image caption is shown as the image s tooltip text. To select another image, click on Browse to open the Browse image window. To export the image to a file ( save as ), click on Export. To delete the image from the alternative, click on Clear. Layout View in Questionnaire Designer About Layout View in Questionnaire Designer About questionnaire layouts A questionnaire s layout describes the way its content is displayed and organized. A questionnaire can have one or more layouts defined. A layout contains pages, each of which contains zero or more page sections. A questionnaire section is called a page section when it exists within a page. A page section contains zero or more page questions. A question is defined in the Questions View, and is called a page question when it exists within a page. A page question can, if it is a multi-option, ranking, or rating question, contain zero or more page alternatives. An alternative is defined in the question in the Questions View, and is call a page alternative when it exists within a page. 150 Portrait Dialogue 6.0

151 Chapter 7: Questionnaires For information on how to create layouts, see Creating a new layout on page 151. Layout View Layout View consists of two main frames: the layout tree view and the page preview. The layout tree view is where you add, remove, organize, and work with the layouts pages, page sections, page questions, etc. The page preview is a preview of the page selected in the tree view. This preview will display the page exactly as it will be displayed when running the questionnaire. The buttons, however, are disabled in page preview. Creating a new layout Adding a layout to a questionnaire To add a layout to your questionnaire: Right-click anywhere in the layout tree view (that is, the layouts folder). Choose Layout from the Layout tab. The New Layout window opens. Enter the name of the layout in the Name textbox. If a style is to be applied to the layout, choose the style from the style drop-down list. For more information on styles, see Questionnaire styles on page 169. Check Auto create pages with questions. If this option is not checked, the layout will be created without any pages. If the option All sections on one page is selected, one section will be created including all sections. If One page per section is selected, one page will be created for each section. Check Include a "welcome page" (prolog) if a prolog should be added to the layout. Check Include a "thank you" page (epilog) if an epilog should be added to the layout. Check Automatically save after each page if you want to save answer forms as incomplete after each page, in addition to saving the answer form as complete at the end of the survey. Click on OK. The new layout is now created, including the pages specified. Layout properties To display the properties for a layout, select the layout and choose Edit Selected Item from the Layout tab, or right-click on the layout and choose Edit Selected Item, or simply double-click on the layout in the tree view. The Layout Properties window opens. The main layout properties explained: Name: The name of the layout. : The description of the layout (optional). Style: The style applied to the layout. Selecting a style is not required. For more information on styles, see Questionnaire styles on page 169. Use this layout in Customer View: The Customer View web application will display the questionnaire using this layout. Visual Dialogue User Guide 151

152 Layout View in Questionnaire Designer In the lower area of the Layout Properties window, there is a tab sheet containing detailed settings: Navigation tab Show progress information: Displays page progress information in the questionnaire. Allow back: Enables and displays the back button, allowing the respondent to navigate backwards when completing the questionnaire. Show close warning: Determine whether a close warning is shown to the user if they try to close the browser without completing the questionnaire. Save options tab Under Save Options it is possible to control how incomplete answer forms are handled. Display a Save button: A Save button will be displayed on each pages of the layout (except prolog and epilog pages) Automatically save after each page: The answer form is saved as incomplete after each page When customers reopen incomplete answer forms allow customers to resume from previous page: when reopening an incomplete answer form, customers will continue on the page where they paused answering earlier customers start answering from the first page: when reopening an incomplete answer form, customers will always need to start at the beginning, although the answers from before pausing answering earlier are kept. Sections tab Show section numbering: Displays the section s sequential number on each section. Enable section comments: Enables and displays a comment textarea for each section. Hide instructions: Hides instructions on all sections. Questions tab Default question position: The position of captions of questions can be selected Mark required questions with the following text: The text which is displayed to the right of required questions (can be empty). Customer data tab Disable update of customer data: Disables updating of customer data from answers and flow scripts for this layout. Update customer data on naviagtion to next page: When enabled, customer data will be updated to the underlying customer domain (customer database) when the respondent moves to the next page. By default the data are updated when the respondent completes the questionnaire. Adding pages to a layout A layout contains one or more pages. A page contains zero or more page sections. Adding a page to a layout To add a page to a layout: 152 Portrait Dialogue 6.0

153 Chapter 7: Questionnaires Right-click anywhere in the layout tree view. Choose Page from the Layout tab. The New Page window opens. Select the page type of the page to add: 1. Normal: A normal page containing sections. 2. Prolog: A welcome page containing a welcome text. 3. Epilog: A thank you page containing a thank you text. If Normal page is selected, choose the number of pages to add in No. of pages. It is possible to choose where the new page(s) will be inserted: Insert page(s) after current: The new page(s) will be inserted after the currently selected page. If the layout node itself is selected, the new page(s) will be inserted before any other page(s) in the layout. Insert page(s) at end: The new page(s) will be added added to the end of the layout, after any existing pages. Click on OK. The new page(s) are now added to the layout. The pages can easily be rearranged by selecting a page and choosing Up or Down from the Layout tab or by right-clicking on the page and choosing up or down. Page properties To display the properties for a page, select the page and choose Edit Selected Item from the Layout tab, or right-click on the page and choose Edit Selected Item, or simply double-click on the page in the tree view. The page properties window opens. The page properties explained: Page text: This text will be displayed on the top of the page, above all sections. Select the option Pure text if the text shall be display as pure text. Select the option HTML code if the page text is given as HTML code. This text can include merge tags. Style override: Overrides the layout s style setting, thus applying a different style to this page. Styles are described under Questionnaire Styles. Override layout default for "Allow back": Overrides the layout s allow back setting, and thus enables the page to have a different allow back setting from that of the layout. Allow back (user can navigate to previous page): Check this option to force allow back to be enabled for the current page. Clear this option to force allow back to be disabled for the current page. Display a "Close" button: When this box is checked, a Close button is displayed on the page. This is only possible on epilog pages. Hide "Save" button: When this box is checked, the Save button is hidden on the page. This option is only available if display of the Save button has been enabled under Layout Properties. Adding sections to pages Each normal page contains zero or more sections. These sections are called page sections. A page section is the one section included on the actual page. A page section includes page questions. Visual Dialogue User Guide 153

154 Layout View in Questionnaire Designer The same section can be included on multiple pages. Adding sections to a page Zero or more sections can be added to a page. A section can be placed on zero or more pages. To add sections to a page, or remove sections from a page, open the Section on Page window by rightclicking on a page in the tree view and choosing Add section to page. Simply check the section(s) you want to be displayed on the page, or clear the checkbox for a section that you want to remove from the page. The On page column is an overview of the pages on which the sections are included. Page section properties To display the properties for a page section, select the page section and choose Edit Selected Item from the Layout tab, or right-click on the section and choose Edit Selected Item, or simply double-click on the page section in the tree view. The page section properties window opens. The page section properties explained: Hide section caption: Check this box to hide the page section s caption. Override instructions: Check this box to override the instructions specified on the section in Questions View. This text can include merge tags. Note: These properties only apply to the current page section. If the section is included on several pages, the properties will not apply to the sections on the other pages. Page questions The questions included in a page section are called page questions. These questions are defined in the page section s section in Questions View. Therefore page questions cannot be added to or removed from a page section. Page question properties To display the properties for a page question, select the page question and choose Edit Selected Item from the Layout tab, or right-click on the page question and choose Edit Selected Item, or simply double-click on the page question in the tree view. The page question properties window opens. The page properties explained: Hide question: This options hides the page question. Hide question caption: This option hides the question caption for the page question. Control type (override default): Overrides the default control type. This option is only available when multiple controls are available for the question type. No. of lines: This option is used to override the number of lines when the control type is set to list box or text box. Alternative layout: This option is available for multi-option question types only. Select vertical alignment to display the alternatives vertically. Select horizontal alignment to display the alternatives horizontally. 154 Portrait Dialogue 6.0

155 Chapter 7: Questionnaires Columns: If horizontal alignment is selected, set the number of columns (alternatives) displayed before the question alternatives are wrapped to the next line. Display alternatives in random order: Checking this option causes the alternatives to be displayed in random order. Alternative options: This list lists all the question alternatives in the page question, also called page alternatives. To set properties for one page alternative, select the alternative in the list and click on the edit icon, or double-click on the alternative. The page alternative property window opens. Hide alternative: Hides the page alternative. Lock position when alternative order is random: Locks the alternative position when Display alternatives in random order is selected. Question positioning Questions (including matrices) are by default displayed below each other in the order that they are defined in Questions View. Use question positioning to position questions inside a section. The questions are positioned in a grid. Defining question positioning To define question positioning: Select a section in the tree view and choose choose Question Position from the Layout tab or rightclick on the section and choose Question Positioning. The section s question positioning window is displayed. Clear the Use default positioning checkbox. This enables question positioning for the section. Select a cell in the grid and then right-click on the cell. A menu containing all questions in the section is displayed. Select the question you want to position in the selected cell. Repeat this for all questions you want to position in the grid. Questions not positioned in the grid after enabling question positioning will be displayed in the order that they are defined in the Questions View, below the questions that are positioned. Information regarding the question applied to the a cell in the grid is displayed in the yellow box at the bottom of the window. To clear a cell, select the cell, and then right-click on the cell and choose Clear cell. To reset all cells in the grid, thus clearing all cells, right-click on the grid and choose Clear all cells. Image positioning Image positioning is used to position question images relative to questions, and alternative images relative to alternatives. Image positioning is also used to hide and resize question and alternative images. Defining image positioning To define image positioning: Select a question in the tree view, and choose Image Position from the Layout tab, or right-click on the question and choose Image Positioning. The question s image positioning window is displayed. Visual Dialogue User Guide 155

156 Layout View in Questionnaire Designer To position question images, select image position from the drop-down list in the section question images position and size. Positioning options are: top, bottom, left, right, invisible. Selecting invisible hides the images for the question. To set a fixed size for the question s images, set width and/or height in the section question images. To position alternative images, select image position from the drop-down list in the section alternative images position and size. Positioning options are: top, bottom, left, right, invisible. Selecting invisible hides the images for the question s alternatives. To set a fixed size for the alternative images, set width and/or height in the section Alternative images. Note: Setting both width and height can change the image s aspect ratio, potentially distorting the image. In order to avoid this, set only one of width or height. Cascading Style Sheets About Cascading Style Sheets The Cascading Style Sheets standard (CSS) is a widely used standard defined by the World Wide Web Consortium. CSS is a simple mechanism for adding style (e.g. fonts, colors, spacing) to elements in web documents: A CSS stylesheet contains style definitions that are applied to the elements in the questionnaire. CSS styles are grouped together in CSS classes. These CSS classes can then be applied to elements in web pages. An introduction to CSS can be found at W3 Schools (external link). CSS in questionnaires Every GUI element in a questionnaire, such as an image, a question control, or a table has one or more CSS classes defined. When creating a new layout, a set of default CSS classes are applied. If a questionnaire style is applied to the layout, the style s CSS classes are applied. These CSS classes may then be overridden in order to apply a custom style to an element in the questionnaire. To display the CSS classes available at a specific level in the tree view, for example, a question, rightclick on the question in the layout tree view and choose Stylesheet. This displays the stylesheet properties window. A set of CSS classes are marked as advanced. These CSS classes are used for advanced configuration of questionnaire elements GUI. Select the option Show advanced fields in order to show all available classes including classes marked as a dvanced. Hierarchic overriding CSS classes in a questionnaire layout can be hierarchically overridden. More precisely, a CSS class for any element in a questionnaire layout can be overridden at any level in the tree view from the element itself and up. Consequently, if you open the stylesheet properties window for the layout, all CSS classes used in the questionnaire are available. Example: 156 Portrait Dialogue 6.0

157 Chapter 7: Questionnaires If you want to override the caption for a single question, open the stylesheet properties window for the actual question, and edit the mh_question_caption CSS class (see image above the caption color is changed to red). However, if you want to override the caption for all questions on the page, open the stylesheet properties window for the actual page, and override the mh_question_caption CSS class. This will apply the overridden CSS class to all questions on the page. Hierarchic overriding precedence CSS classes at lower levels have higher priority than CSS classes at higher levels. Thus, when overriding the same CSS class at multiple levels, the override at the lowest level will be applied at the actual level and down. Example: Override the caption for a single question, changing the caption color to green. Then override the caption for all questions on the page, changing the caption colors to red. In this case, the override for the first question (color: green) is not overridden as it has a higher precedence. Flow Defining flow Flow Flow in a questionnaire layout is, among other things, used to dynamically control the questionnaire s flow logic, control the questionnaire s user interface, implement advanced validation, and manipulate answers. This is done by defining simple conditions or script blocks on a page s enter and exit events. How flow is defined To define the layout s flow logic, open Flow Designer by choose Flow from the Layout tab, or by rightclicking a page in the tree view and choosing Flow. A page enter action or page exit action can be defined for each normal page that is defined in the questionnaire layout. The page enter action is executed just before a page is displayed. The page exit action is executed when the respondent successfully completes the page and moves on to the next page by pressing the forward button. The actions are defined either by simple conditions or a script. All objects, methods, and properties available when scripting in flow are described in Script Object Model overview on page 169. Page symbols (icons) in layout flow In Flow Editor window s page list, there are special symbols (icons) used to indicate flow logic in pages. These help users to get an overview of where to find existing flow logic. If the left hand side of the icon is colored, it indicates that a page enter flow logic exist within the page. Light blue for simple conditions and dark blue for enter script. Alternatively, if the right hand side of the symbol is colored, it indicates that a page exit flow logic exist within the page. Visual Dialogue User Guide 157

158 Layout View in Questionnaire Designer Tooltips are displayed to indicate flow logic implemented in pages.. Page keys Page keys are used for scripting only. A page key is a short (max. 8 characters) string which is unique to a page in a layout. Keys are used in script code to refer to a page. Pages can also be referred using its index (page number). However, the advantage of using keys over indexes is that a key retains its value when pages are reorganized, where as indexes will change. The default values for keys start from P1 for the first page, P2 for the second page, and so on. Keys can be changed by clicking on Edit key. For example, it can be convenient to call the first two pages INTRO1 and INTRO2 instead of P1 and P2. By using the Reassign keys button, you can choose to revert to the default key values ( P1, P2, ). Examples using flow scripting can be found in Examples of scripting in questionnaire flow on page 187. Page enter action The page enter action is executed just before a page is displayed. The page enter action is defined either in terms of simple conditions or by a script. Simple conditions Edit the page enter action s simple conditions by opening the flow layout, selecting the Page enter action tab, and choosing Use simple conditions. These simple conditions are used to hide sections and/or skip the page when given criteria evaluate to true. To skip the page, edit the action Skip page in the flow layout: Choose a Question and an Alternative from the drop-down lists. If the Selected option is chosen, and the respondent has answered the question alternative, the page will be skipped. If the Not selected option is chosen, and the respondent has not answered the question alternative, the page will also be skipped. To hide a section, edit the action Hide section [section name]: Choose a question and an alternative from the drop-down lists. If the Selected option is chosen, and the respondent has answered the question alternative, the section will be hidden. If the Not selected option is chosen, and the respondent has not answered the question alternative, the section will also be hidden. Scripting Edit the page enter action s scripting by opening the flow layout, selecting the Page enter actions tab, and choosing Use scripting. 158 Portrait Dialogue 6.0

159 Chapter 7: Questionnaires Scripting in the layout flow is, among other things, used to dynamically control the questionnaire flow logic, control the questionnaire user interface, and manipulate the answers. All objects, methods, and properties available when scripting in flow are described in Script Object Model overview on page 169. Scripting a page enter action is typically used to hide or show elements on the page, skipping the page if certain conditions are true, and adding or removing answers. The script language supported for questionnaire flow scripting is Microsoft JScript.NET. Examples using flow scripting can be found in Examples of scripting in questionnaire flow on page 187. Page exit action The page exit action is executed when the respondent successfully completes the page and moves on to the next page by pressing the forward button. The page enter action is defined either in terms of simple conditions or by a script. Simple conditions Edit the page exit action s simple conditions by opening the flow layout, selecting the Page exit action tab, and choosing Use simple conditions. These simple conditions are used to jump to pages when given criteria evaluate to true. One or more conditions can be given: The conditions are evaluated in the order that they are listed. Change this order by selecting a condition and clicking on the up and down arrows. Sequential evaluation stops when a condition evaluates to true. Choose a Jump to page, a Question, and an Alternative from the drop-down lists. If the Selected option is chosen, and the respondent has answered the question alternative, the next page will be set to the page selected in Jump to page. This means that the next page displayed can be a different one from the page following in the layout tree view. If the Not selected option is chosen, and the respondent has not answered the question alternative, the next page will also be set to the page selected in Jump to page. Scripting Edit the page exit action s scripting by opening the flow layout, selecting the Page exit actions tab, and choosing Use scripting: Scripting in the layout flow is, among other things, used to dynamically control the questionnaire flow logic, control the questionnaire user interface, and manipulate the answers. All objects, methods, and properties available when scripting in flow are described in Script Object Model overview on page 169. Scripting a page exit action is typically used to validate answer data, add or remove answers, or alter the page sequence in the flow by setting the ActivePage.NextPage attribute. The script language supported for questionnaire flow scripting is Microsoft JScript.NET. Examples using flow scripting can be found in Examples of scripting in questionnaire flow on page 187. Visual Dialogue User Guide 159

160 Using merge tags Endpoints Under page exit actions, there is a Page is end-point checkbox. If this is checked, exiting this page will complete the questionnaire regardless of the page s position in the list of pages in the layout tree. When the page is exited, answers given will be stored in the database, and the respondent will be taken directly to an epilog page ( Thank you page ). The diagram below shows an example using endpoints. In the layout tree, there are three pages that are defined as endpoints (pages 3, 4, and 5). When exiting page 2, the respondent will be taken to one of these three pages, depending on their answers on page 2. After exiting page 3, 4, or 5, the questionnaire is completed, and the respondent is taken to the epilog (page 6). Using merge tags Merge tags Merge tags introduces the concept of merging dynamic information into captions and default values in questionnaires. It is possible to include five types of information using merge tags: Customer domain data 160 Portrait Dialogue 6.0

161 Chapter 7: Questionnaires Example: First name, address, phone numbers etc. Answer data Answers to questions on a previous page in the questionnaire can be merged into captions and texts on a later page. Example: If the respondent gives his name on page 1, then his name can be used in a caption on page 2. Expressions Results from expressions. See the Reference Help to learn about expressions. Custom values A value stored by a questionnaire script on a previous page in the questionnaire. Content objects Content objects define dynamic content, where the actual content shown is decided by evaluating a set of rules. Example: A content object can be included in a questionnaire s page text. The content object displays one commercial banner to female customers and another to male customers. Merge tags are enclosed with brackets, e.g. [firstname] Tags are used both in the section and question caption, as well as in the default value of the question. Different types of merge tags Domain field tag This type of tag retrieves data from the customer domain of the respondent Syntax: [<domain_field>] Example: Your first name is: [firstname] Answer tag This type of tag retrieves data from a question answered earlier in the questionnaire Syntax: [?<question_key>] Example: You answered: [?Q2] Expression tag This type of tag contains an expression. See the Technical Documentation to learn about expressions. Syntax: [#<expression>] Example: You currently subscribe to [#NumberOf(Subscriptions)] newspapers. Custom value tag Visual Dialogue User Guide 161

162 Using merge tags This type of tag retrieves string data from an item in the CustomValue collection. The CustomValue collection is managed in enter and exit scripts. Syntax: [!<CustomValueItem>] Example: This page contain information related to [!products]. Content object tag This type of tag shows a content object in the location it is placed. Syntax: [$(<Content Object key>, <optional parameters>)] Example: The following tag adds the content object with key ContentNr1: [$(ContentNr1)]. Optional parameters: It is possible to include a couple of extra parameters when specifying the content object tag. The parameters are separated from the content object s key by a comma, and they are separated from each other using a semicolon. Example: [$(ContentKey, Option1;Option2)] Caching content objects shown using merge tags are cached by default. You can force a content object to be executed each time it is shown by specifying C=Ignore in the content object tag. The cache timeout is by default 5 minutes, but you can override this by specifying CTO=<timeout>, where <timeout> is the timeout in minutes. See the Content Objects section in the Technical documentation for more information about content object caching. Example: [$(ContentObjectKey, C=Ignore)] No caching is used. Example: [$(ContentObjectKey, CTO=15)] Setting cache timeout for the Content Object to be 15 minutes. NoScramble The querystring of the URL generated by the content object tag is by default scrambled. Use this parameter to get an unscrambled URL. Example: [$(ContentObjectKey, NoScramble)] ShowError If an error message should be shown if an error occurs showing the content object. Mainly used when debugging. - Example: [$(ContentObjectKey, ShowError)] UsePageMode The content object tag is by default replaced with a script tag that automatically inserts the content object where the tag is placed. If you want to include the content object in an iframe, you specify this parameter and set the content object tag as the value of the iframe s source attribute. Example: <iframe src="[$(contentobjectkey, UsePageMode)]"></iframe> Additional parameters You can include as many additional parameters as you want, both with and without values. - Example: [$(ContentObjectKey, NoScramble;Score=5;IsInterested)] 162 Portrait Dialogue 6.0

163 Chapter 7: Questionnaires Where merge tags can be used Merge tags are available for most texts in a questionnaire, including: Questions View Section captions and instructions Question captions Question default values Matrix captions Alternative captions Layout View Page headers Page section instructions (override section instructions) Note: When you are changing headings and captions using scripts under flow, you can use merge tags as well. The tags will be replaced by actual values as soon as the questionnaire page is rendered. Questionnaire properties To edit the properties of a questionnaire, choose Properties from the File tab when working in Questionnaire Designer. The different pages of the properties window are described below. The General tab The general page contains the name and description of the questionnaire. In addition, it shows information about when and by whom the questionnaire was created and modified. The Language tab The language page contains the language setting of the questionnaire. All texts generated internally, e.g. validation errors, will follow this language. The Survey type tab On this tab the type of survey is selected: Mixed mode: Both anonymous and identified respondents can answer the questionnaire. This is the least restrictive survey type. Anonymous: Only anonymous answers are allowed. Anonymous answer forms are never linked to a customer in the database. Identified: Anonymous answers are not allowed. The answer forms are always linked to a customer in the database. Furthermore, a Target Customer Domain can be selected. This option applies to the mixed-mode and identified survey types, and it restricts the respondents to the specified customer domain. Visual Dialogue User Guide 163

164 Testing a questionnaire The option Enable update of existing customers specifies whether it is possible to update customer data for existing customers based on their answers. This can be done either by linking a simple question to a domain field, or by writing flow scripts (where a customer object is available). Similarly, it is possible to create new customers based on their answers using the option Enable creation of new customers from anonymous responses. This functionality requires mixed mode and that the response starts as anonymous (e.g. a landing page ). The new customers are created in the specified Target Customer Domain. The Activity tab On the activity page an activity type can be selected. When an identified respondent answers the questionnaire, an activity of the selected activity type will be created and related to the customer. This activity will have a link to the answer form. The Web access tab To make the Questionnaire available to customers through the Customer Web Access module (CWA), you need to check Enable in Customer Web Access. In addition, you can set a date range, controlling the period for which the questionnaire will be available. Password not required for login controls if a customer can log in and answer the questionnaire without supplying a password. Customers can change existing answers controls if a customer can reopen an answer form already registered and change answers. Enable response tracking enables tracking the progress of respondents answering questionnaires. Note that response tracking will not be available if you use default layout. Show in favorite list in Customer View describes if the questionnaire should be listed in the short list (favorite list) of questionnaires in Customer View. Other Enable section comments in default layout enables and displays a comment textarea for each section in the default layout. Testing a questionnaire Activating the Questionnaire Test window To test a questionnaire while working in Questionnaire Designer, choose Test (F9) from the Questions or Layout ribbon tab. The Questionnaire Test window. Under testing, the questionnaire will behave exactly as it will when it is completed by a real respondent, including logic such as validation and flow. The only difference is that the answer form will not be stored in the Dialogue Server database. 164 Portrait Dialogue 6.0

165 Chapter 7: Questionnaires Questionnaire test and layout If you are working in Layout View and a specific layout is selected, this layout will be displayed in the Questionnaire Test Window. If no layout is selected or you are working in Questions View, the questionnaire is displayed using the default layout. The default layout is a layout automatically generated by the system. Questionnaire test options When a questionnaire is being answered, the respondent will be either identified or anonymous. To simulate these two modes when testing a questionnaire, an options window is available. To display this window, choose Test > Test and preview options... from the Questions or Layout ribbon tab. Note: The options set in this window also apply to the Page Preview when you are working in Layout View. Building a questionnaire URL Customers can answer questionnaires through the Customer Web Access module (CWA). To access a specific questionnaire using this module a URL is needed. To create such URLs a special tool is available in Questionnaire Designer. Open the Questionnaire Browser and choose Build questionnaire URL from the Home tab to start building a questionnaire URL. The Build Questionnaire URL window opens. The Build Questionnaire URL Window Before a URL can be generated some options have to be selected. You have to specify the questionnaire that the respondent is to answer, and the layout to use. There are several URL types that can be built: Anonymous response: The respondent will not be identified when answering the questionnaire, meaning that the answer form will not be related to any customers in any customer domain. Identified response using personified URL: This option is only available when designing messages in the Message Designer. A URL which includes a customer ID (and possibly a context value and a participant ID) will be generated. Identified response using login: The respondent will be taken to a log in page before answering the questionnaire. A customer domain has to be selected in the drop down box. The customer domain defines if and how customers will be authenticated, thus the URL created will only work for customers in the customer domain selected. There are two types of login URLs: Login using Login ID: The customer is authenticated using the Login ID and Password defined in the customer domain setup in Dialogue Admin. Visual Dialogue User Guide 165

166 Response tracking Login using Participant ID: The customer is authenticated using a Participant ID (dp_id) from a dialog where the customer participates. To login using a participant ID, this has to be enabled for the specific dialog under Dialog Properties. The password is defined in the customer domain setup in Dialogue Admin (same as for Login using Login ID). Furthermore, it is possible to relate the response to a broadcast. By selecting a broadcast, answer forms registered using the generated URL will be related to this broadcast. For example, this may be useful for analyzing the efficiency of web popup ads (advertisements). Scramble URL specifies whether, or not, the URL parameters should be encrypted with a check sum. Note: Note: Using this option in a live survey on the internet is strictly recommended. Omitting the scramble option may be useful for testing. When you click on OK, the application will offer to copy the generated URL to the clipboard. In this way you can paste the URL into documents in other applications, e.g. a web page editor. Using questionnaire URLs Questionnaire URL are most often made available to customers through links in s, or through web pages being accessed by customers. Response tracking Introduction Response Tracking is used to track the progress of respondents answering questionnaires. A response tracking log item is stored in the database for each questionnaire page a respondent visits. Response tracking must be enabled either in the questionnaire web access configuration or a telemarketing project to log responses. Using response tracking Visual Dialogue includes a standard report for easy access to a questionnaire s response tracking data. The report contains the following information: How many of the respondents finished answering the questionnaire. The percentage of respondents who finished answering the different pages of the questionnaire (compared to the total number of respondents which started answering the questionnaire) The average time used to answer the questionnaire. The average time used to answer the different questionnaire pages. 166 Portrait Dialogue 6.0

167 Chapter 7: Questionnaires Browsing questionnaires Browsing questionnaires To see all questionnaires defined, choose Explore > Questionnaires from the Home tab in Visual Dialogue. The Browse Questionnaires frame is displayed. To sort the questionnaires in the list, click on the desired column in the heading. To configure the set of columns displayed in the list, choose Select Columns from the View tab. The Select Columns window opens. To review or edit the properties (e.g. the name or the description of the questionnaire), select a single questionnaire, and choose Properties from the Home tab. The Questionnaire Properties window opens. To open a questionnaire in Questionnaire Designer, double-click on a single questionnaire in the list, or choose Open from the Home tab. To delete a questionnaire, mark a single questionnaire, and choose Delete from the Home tab. A preview of the questionnaire is shown in the bottom of the browser. To turn the preview on or off, click the Preview button in the ribbon bar. Preview images are automatically generated when you save a questionniare, but you can also manually generate them by choosing Update preview image from the context menu in the browser. Running the questionnaire report To run the integrated questionnaire report, go to the Questionnaire Browser and choose Response overview from the Home tab. A wizard with report parameters opens. You need to select a questionnaire, as well as choosing the time interval to report on. This means that the report will contain information about responses to one questionnaire in a given time period. Furthermore, you can choose whether to include only complete responses, only incomplete responses, or both. You can also choose how percentage numbers in the report are calculated. Percentages can be calculated relative to the total number of answer forms in the report, or relative to the total number of answers to a question. The percentage option applies to multi-option questions only. After finishing the wizard, the questionnaire report will be generated and shown in the Visual Dialogue main window. The report document format is HTML. Visual Dialogue User Guide 167

168 Exporting response data Exporting response data To run the Export Response Data Wizard, go to the Questionnaire Browser and choose Export > Export response data from the Home tab. A three-stage wizard is displayed. On the first page (shown below), you can select: the questionnaire for which to export data the target file format and some options applying to that file type (e.g. Include column headers) the name of the file. On the second page, you can choose which questions to export. By default, all questions in the questionnaire are selected and will be included in the exported file. When it comes to single-choice questions, a special option is available: Export single-choice questions as one column. This option controls whether single-choice questions are exported as one column containing the key of the selected alternative, or if all alternatives of the question are put in separate columns. On the third and last page of the wizard, you can choose whether to include only complete responses, only incomplete responses, or both. Alternatively, advanced users are given the option of providing an SQL statement to filter the answer forms to export. Deleting response data The Delete Response Data wizard is primarily meant for deleting test data in the form of answer forms that you posted to the system during development of a process, but it can also be used to delete arbitrary response data, so you should use it with great care. To run the Delete Response Data wizard, go to the Questionnaire Browser and choose Delete response data from the Home tab. A wizard showing the total number of answer forms and response tracking records for the selected questionnaire opens. On the next page, you can restrict the data to be deleted by specifying a date interval. On the next page, you can restrict the data to be deleted by specifying a response type. You can choose whether to delete only complete responses, only incomplete responses, or both. After possibly specifying restrictions, you are shown the number of answer forms and tracking records that will be deleted with the restrictions applied. 168 Portrait Dialogue 6.0

169 Chapter 7: Questionnaires Questionnaire styles Questionnaire styles are used to create a uniform look to your questionnaires. They consist of two parts: an HTML template and a collection of CSS classes. The HTML template The HTML template is simply an HTML page that the questionnaire page is displayed in. You place a special tag, #MHQUESTIONNAIRE, where you want the questions to appear on the HTML page. Beyond this, the page is just like an ordinary HTML page. While you are designing the template, you can press F9 to get a preview in your default web browser. CSS classes CSS classes are used to control the look of the different elements on a questionnaire page. When you create a new layout, you get a set of default CSS classes, which you can change to suit your style. The CSS classes can also be overridden on individual questionnaire elements. Note: The CSS classes on the CSS Classes page can only contain the predefined classes. If you want to have your own classes, you must place them in the HTML template. Script Object Model Script Object Model overview Overview The Script Object Model (SOM) is a collection of objects representing the elements contained in a questionnaire. The model allows you to programmatically read, manipulate, and modify these elements in the questionnaire. The objects accessible in the model are: Question, Alternative, Page, Section, Matrix, Column, Row, and Cell. In addition, there are a set of global methods and properties directly available when scripting in SOM. Real-life examples using scripting with the SOM in questionnaires can be found in Examples of scripting in questionnaire flow on page 187. Each property and method of each objects is explained with examples. The script language The script languages supported for questionnaire flow is Microsoft JScript.NET, Microsoft C# and Microsoft Visual Basic.NET. JScript.NET is the default language and is a script language from Microsoft that is Visual Dialogue User Guide 169

170 Global objects, methods, and properties expressly designed for use with web technologies. It adheres to the ECMAScript standard and is basically Microsoft s equivalent to the widely used JavaScript. If you want to use C# or Visual Basic.NET when scripting, you have to specify [C#] or [VB] accordingly on the first line of each script. The object model visualized The SOM has a tree structure of objects. The different objects have various properties and methods, and access to subobjects are available through these properties and methods. For example, a question object gives access to its alternative objects. 1. Global objects, methods, and properties on page The Question object on page The Alternative object on page The Matrix object on page The Column object on page The Row object on page The Cell object on page The Page object on page The Section object on page The Customer object on page 186 Global objects, methods, and properties Overview These global properties and methods are available directly when scripting in Questionnaire Designer. 170 Portrait Dialogue 6.0

171 Chapter 7: Questionnaires Properties The following global properties are supported: Property page ActivePage long AnswerFormID int BroadcastID string ChannelName string Context customer Customer int CustDomainID string CustomerID object CustomerAPI object DialogAPI object GenericAPI bool IsAnonymous bool IsNew long ParticipantID int QuestionnaireID string ServerSession collection Questions Gets the page object representing the current page. Gets the answer form ID. Gets the broadcast ID. Gets the channel type name. Gets or sets the answer form context. Gets the customer object representing the customer answering the questionnaire. Gets or sets the customer domain ID. Gets or sets the customer ID. Gets the Customer API, providing a set of methods for accessing data related to customers. Gets the Dialog API, providing a set of methods for accessing data related to dialogs and participants. Gets the Generic API, providing a set of methods for accessing generic objects defined in Dialogue Admin. These include datasets and SQL statements stored in the SQL Repository, as well as generic plug-ins. Gets or sets the boolean property indicating if the answer form is anonymous. Gets the boolean property indicating if the answer form is new. Gets or sets the participant ID. Gets the questionnaire Id. Gets the user session s session key. Gets the collection of question objects, representing all the questions in the questionnaire. Question information and functionality are accessible through properties and methods on the question object. Usage question Questions[string Key] Accesses questions using the question key. question Questions[int Index] Accesses questions using a zero-based index, meaning question one has index 0, question two has index 1, and so on. int Questions.Count Visual Dialogue User Guide 171

172 Global objects, methods, and properties Property Returns the total number of questions in the questionnaire. Examples Questions["Q17"].Hide = true; Questions[16].Hide = true; var iquestioncount = Questions.Count; collection Matrix Gets the collection of matrix objects, representing all the matrices in the questionnaire. Matrix information and functionality are accessible through properties and methods on the matrix object. Usage matrix Matrix[string Key] Accesses matrices using the matrix key. matrix Matrix[int Index] Accesses matrices using a zero-based index, meaning matrix one has index 0, matrix two has index 1, and so on. int Matrix.Count Returns the total number of matrices in the question. Examples Matrix["A2"].Hide = true; Matrix[1].Hide = true; var imatrixcount = Matrix.Count; collection Pages Gets the collection of page objects, representing all the pages in the questionnaire. Page information and functionality are accessible through properties and methods on the page object. Usage page Pages[string Key] Accesses pages using the page key. page Pages[int Index] Accesses pages using a one-based index, meaning page one has index 1, page two has index 2, and so on. int Pages.Count Returns the total number of pages in the questionnaire. Examples Pages["P2"].Skip = true; Pages[2].Skip = true; var ipagecount = Pages.Count; 172 Portrait Dialogue 6.0

173 Chapter 7: Questionnaires Property collection CustomValue Returns a name value collection. The collection represents a sorted collection of associated String keys and String values that can be accessed using either the key or the index. The collection is persistent between page loads, and can therefore be used to store data and information between pages. Usage Adding values: CustomValue.Add(key, value); Retrieving values: var myvalue = CustomValue[ key ]; collection Sections Gets the collection of section objects, representing all the sections in the questionnaire. Section information and functionality are accessible through properties and methods on the section object. Usage section Sections[int Index] Accesses sections using a one-based index, meaning section one has index 1, section two has index 2, and so on. int Sections.Count Returns the total number of sections in the questionnaire. Examples Sections[2].Hide = true; var isectioncount = Sections.Count; Methods The following global methods are supported: Method string EvaluateExpression(string expression) Returns an XML document containing the result value of the specified expression. expression is the expression to evaluate. bool EvaluateExpressionBool(string expression) Evaluates and returns the result of a boolean expression. expression is the expression to evaluate. Specifying a non-boolean expression raises an exception. string EvaluateExpressionString(string expression) Evaluates and returns the result of an expression. expression is the expression to evaluate. Specifying an expression that returns a data group or an array raises an exception. To evaluate such an expression, use the EvaluateExpression method. Visual Dialogue User Guide 173

174 The Question object Method string GetCustomerData(string datafield) Gets customer domain data. datafield is the field to get from the domain. Note: The GetCustomerData method uses the questionnaire s caching mechanism to access customer data. Therefore, from a performance point of view, it is the preferred way of accessing customer data, in comparison to using the EvaluateExpression methods above. Example var s address = GetCustomerData(" "); The Question object Overview The Question object is accessible through the Questions collection. Question information and functionality are accessible through properties and methods on the Question object. Access Question objects in the Questions collection using the questions key. The Question object has no default property. Example: var oquestion = Questions["Q17"]; Properties The following properties are supported: Property collection Alternatives This property gets the collection of alternative objects, representing the alternatives available on the question. The collection is empty if the question is not a multi-option question. Alternative information and functionality are accessible through properties and methods on the alternative object. Usage alternative Alternatives[ string Key ] Accesses alternatives using the alternative key. alternative Alternatives[ int Index ] Accesses alternatives using a zero-based index, meaning alternative one has index 0, alternative two has index 1 and so on. int Alternatives.Count 174 Portrait Dialogue 6.0

175 Chapter 7: Questionnaires Property Returns the total number of alternatives in the question. Examples Questions["Q17"].Alternatives["A1"].Hide = true; Questions["Q17"].Alternatives[0].Hide = true; var ialternativescount = Questions["Q17"].Alternatives.Count; string Caption This property gets and sets the questions caption. Example: Questions["Q17"].Caption = "Cars"; string ErrorMessage This property is used for question validation. The property gets or sets the question error message displayed on the question when the questions IsValid property is set to false. Example: Questions["Q17"].ErrorMessage = "Answer is not valid"; bool Hide bool IsValid This property forces the question to be hidden and shown. Thus, if set to true, the question will always be rendered, and if set to false, the question will never be rendered. If not set, the question will render according to the questionnaire layout definition. Example: Questions["Q17"].Hide = Questions["Q16"].IsAnswered(); This property is used for question validation. The property gets and sets a boolean value representing the validation status of the question. Example: Questions["Q17"].IsValid = false; Methods The following methods are supported: Method void ClearAnswer() Deletes any answer given on the question. The method has no return value. Example: Questions["Q17"].ClearAnswer(); Visual Dialogue User Guide 175

176 The Question object Method DateTime GetAnswer- DateTime() Returns the given answer as a DateTime value. If no answer exists, Date- Time.MinValue is returned. Example: var dtanswer = Questions["Q17"].GetAnswerDateTime(); Note: To check if a question has been answered, use the IsAnswered() method. float GetAnswerFloat() Returns the given answer as a float value. If no answer exists, 0 is returned. Example: var fanswer = Questions["Q17"].GetAnswerFloat(); Note: To check if a question has been answered, use the IsAnswered() method. int GetAnswerInt() Returns the given answer as an integer value. If no answer exists, 0 is returned. Example: var ianswer = Questions["Q17"].GetAnswerInt(); Note: To check if a question has been answered, use the IsAnswered() method. string GetAnswerText() Returns the given answer as a string value. If no answer exists, an empty string is returned. Example: var sanswer = Questions["Q17"].GetAnswerText(); string GetSingle- ChoiceAnswer() Returns the alternative key for the given answer for a single choice question. If no answer exists, an empty string is returned. Example: var salternativekey = Questions["Q17"].GetSingleChoiceAnswer(); bool IsAnswered() Returns true if the question has an answer, otherwise false. Example: Questions["Q19"].Hide = Questions["Q18"].IsAnswered(); void SetAnswer- Text(string answervalue) Saves a text answer on the question. The method has no return value. answervalue is the answer string value to set on the question. 176 Portrait Dialogue 6.0

177 Chapter 7: Questionnaires Method Example: Questions["Q17"].SetAnswerText("Opel"); void SetAnswerInt(int answervalue) Saves an integer answer on the question. The method has no return value. void SetAnswer- Float(float answervalue) void SetAnswerDate- Time(DateTime answer- Value) void SetAnswer- Bool(bool answervalue) answervalue is the answer integer value to set on the question. Example: Questions["Q17"].SetAnswerInt(19); Saves a float answer on the question. The method has no return value. answervalue is the answer floating point value to set on the question. Example: Questions["Q17"].SetAnswerFloat(2.54); Saves a datetime answer on the question. The method has no return value. answervalue is the answer DateTime value to set on the question. Example: Questions["Q17"].SetAnswerDateTime(datetime); Saves a boolean answer on the question. The method has no return value. answervalue is the answer bool value to set on the question. Example: Questions["Q17"].SetAnswerBool(true); Note: For future use only. The Alternative object Overview The Alternative object is accessible through the Alternatives collection. Alternative information and functionality are accessible through properties and methods on the Alternative object. Access Alternative objects in the Alternatives collection using the alternatives key. Visual Dialogue User Guide 177

178 The Alternative object The Alternative object has no default property. Example: var oalternative = Questions["Q17"].Alternatives["A2"]; Properties The following properties are supported: Property string Caption bool Hide This property gets and sets the alternatives s caption. Example: Questions["Q17"].Alternatives["A2"].Caption = "Opel"; This property forces the alternative to be hidden and shown. Thus, if set to true, the alternative will always be rendered, and if set to false, the alternative will never be rendered. If not set, the alternative will render according to the questionnaire layout definition. Example: Questions["Q17"].Alternatives["A2"].Hide = Questions["Q16"].IsAnswered(); Methods The following methods are supported: Method bool IsAnswered() void ClearAnswer() Returns true if the alternative is answered, otherwise false. Example: Questions["Q18"].Alternatives["A1"].Hide = Questions["Q17"].Alternatives["A2"].IsAnswered(); Deletes any answer given on the alternative. The method has no return value. Example: Questions["Q17"].Alternatives["A2"].ClearAnswer(); string GetAnswerText() Returns the given answer as a string value for the alternative s textbox. If no answer exists, an empty string is returned. Example: var sanswer = Questions["Q17"].Alternatives["A2"].GetAnswerText(); 178 Portrait Dialogue 6.0

179 Chapter 7: Questionnaires Method void SetAnswer- Bool(bool answervalue) Saves a boolean answer on the alternative, thus setting the question s alternative. The method has no return value. answervalue is the answer boolean value to set on the alternative. Example: Questions["Q17"].Alternatives["A2"].SetAnswerBool(true); void SetAnswer- Text(string answervalue) Saves a text answer on the alternative. The alternative must have an appropriate textbox. The method has no return value. answervalue is the answer string value to set on the alternative textbox. Example: Questions["Q17"].Alternatives["A2"].SetAnswerText("Opel"); The Matrix object Overview The Matrix object is accessible through the Matrix collection. Matrix information and functionality are accessible through properties on the Matrix object. Access Matrix objects in the Matrix collection using the matrix s key. The Matrix object has no default property. Example: var omatrix = Matrix["M2"]; Properties The following properties are supported: Property string Caption This property gets and sets the matrixs caption. Example: Matrix["M2"].Caption = "Personal information"; collection Columns This property gets the collection of column objects, representing the columns available on the matrix. Column information and functionality are accessible through properties on the column object. Usage column Columns[ int Index ] Visual Dialogue User Guide 179

180 The Column object Property Accesses columns using a zero-based index, meaning column one has index 0, column two has index 1 and so on. int Columns.Count Returns the total number of columns in the matrix. Examples Matrix["M2"].Columns[2].Hide = true; var icolumncount = Matrix["M2"].Columns.Count; bool Hide This property forces the matrix to be hidden and shown. Thus, if set to true, the matrix will always be rendered, and if set to false, the matrix will never be rendered. If not set, the matrix will render according to the questionnaire layout definition. Example: Matrix["M2"].Hide = Questions["Q16"].IsAnswered(); collection Rows This property gets the collection of row objects, representing the rows available on the matrix. Row information and functionality are accessible through properties on the row object. Usage Row Rows[ int Index ] Accesses rows using a zero-based index, meaning row one has index 0, row two has index 1 and so on. int Rows.Count Returns the total number of rows in the matrix. Examples Matrix["M2"].Rows[0].Hide = true; var irowcount = Matrix["M2"].Rows.Count; The Column object Overview The Column object is accessible through the Columns collection. Column information and functionality are accessible through properties on the Column object. The Column object has no default property. 180 Portrait Dialogue 6.0

181 Chapter 7: Questionnaires Example: var ocolumn = Matrix["M2"].Columns[2]; Properties The following properties are supported: Property string Caption bool Hide This property gets and sets the column s caption. Example: Matrix["M2"].Columns[2].Caption = "Name"; This property forces the column to be hidden and shown. Thus, if set to true, the column will always be rendered, and if set to false, the column will never be rendered. If not set, the column will render according to the questionnaire layout definition. Example: Matrix["M2"].Columns[2].Hide = Questions["Q16"].IsAnswered(); The Row object Overview The Row object is accessible through the Rows collection. Row information and functionality are accessible through properties on the Row object. The Row object has no default property. Example: var orow = Matrix["M2"].Rows[3]; Properties The following properties are supported: Property string Caption This property gets and sets the rows caption. Example: Matrix["M2"].Rows[3].Caption = "Medium"; Visual Dialogue User Guide 181

182 The Cell object Property bool Hide This property forces hide and show for the row. Thus, if set to true, the row will always be rendered, and if set to false, the row will never be rendered. If not set, the row will render according to the questionnaire definition. Example: Matrix["M2"].Rows[3].Hide = Questions["Q16"].IsAnswered(); collection Cells This property gets the collection of Cell objects, representing the cells available on the row. Cell information and functionality are accessible through properties on the cell object. Usage cell Cells[ int Index ] Accesses cells using a zero-based index, meaning cell one has index 0, cell two has index 1 and so on. int Cells.Count Returns the total number of cells in the row. Example: Matrix["M2"].Rows[2].Cells[1].Hide = true; var icellcount = Matrix["M2"].Rows[2].Cells.Count The Cell object Overview The Cell object is accessible through the Cells collection. Cell information and functionality are accessible through properties on the Cell object. The Cell object has no default property. Example: var ocell = Matrix["M2"].Rows[3].Cells[2]; Properties The following property is supported: 182 Portrait Dialogue 6.0

183 Chapter 7: Questionnaires Property bool Hide This property forces the cell to be hidden and shown. Thus, if set to true, the cell will always be rendered, and if set to false, the cell will never be rendered. If not set, the cell will render according to the questionnaire definition. Example: Matrix["M2"].Rows[3].Cells[2].Hide = Questions["Q16"].IsAnswered(); The Page object Overview The Page object is accessible through the Pages collection. Page information and functionality are accessible through properties on the Page object. The Pages collection is 1-indexed, meaning that page one is 1, page two is 2, and so on. The Page object has no default property. Example: var opage = Pages[2]; Properties The following properties are supported: Property bool IsValid This property is used for page validation. The property gets or sets a boolean value representing the validation status of the page. Example: Pages[2].IsValid = false; string ErrorMessage This property is used for page validation. The property gets and sets the page error message displayed on the page if the pages IsValid property is set to false. Example: Pages[2].ErrorMessage = "Page is not valid"; string Key This property gets the key of the page. The key is a short string unique to the page within the layout. The value is read only. Visual Dialogue User Guide 183

184 The Page object Property string PageText This property gets and sets the PageText string. This string is displayed on the top of the page, above all sections. This text can include merge tags. Example: Pages[2].PageText = "Please fill in all fields on this page"; bool PageTextIsHtml This property gets and sets the text format of the PageText property. Setting this property to false will display the PageText as pure text. Setting this property to true will display the PageText HTML code. Example: Pages[2].PageText = "<h4>please fill in all fields on this page</h4><br><hr>"; Pages[2].PageTextIsHtml = true; bool Skip Gets and sets a boolean value stating if the page shall be skipped. If set to true, the page passes the flow to the next page given by the NextPage property. Example: Pages[2].Skip = true; int NextPage Gets and sets the next page using the index of a page. Note: It is recommended to use the NextPageKey instead of NextPage because the key of a page will remain constant when pages are moved or rearranged. The property is by default set to the next page (current page + 1). For the last page, the property is set to -1. If this property is set to -1, the page will act as an Endpoint page. Example: Pages[2].NextPage = 4; string NextPageKey Gets and sets the next page using the key of a page. The property is by default set to the next page s key. For the last page, the property is set to a blank string. If this property is set to a blank string, the page will act as an Endpoint page. Example: Pages["P2"].NextPageKey = "P4"; 184 Portrait Dialogue 6.0

185 Chapter 7: Questionnaires The Section object Overview The Section object is accessible through the Sections collection. Section information and functionality are accessible through properties and methods on the Section object. The Sections collection is 1-indexed, meaning that Section one is 1, section two is 2, and so on. The Section object has no default property. Example: var osection = Sections[2]; Properties The following properties are supported: Property string Caption bool Hide This property gets and sets the sections caption. Example: Sections[2].Caption = "Personal information"; This property forces the section to be hidden and shown. Thus, if set to true, the section will always be rendered, and if set to false, the section will never be rendered. If not set, the section will render according to the questionnaire layout definition. Example: Sections[2].Hide = Questions["Q16"].IsAnswered(); Methods The following methods are supported: Method bool SetComment(string commentvalue) string GetComment() Adds a comment to a section. The method has no return value. commentvalue is the comment string value to set on the section. Example: Sections[2].SetComment("Enter your comment here"); Returns the section comment as a string value. If no comment is given on the section, an empty string is returned. Visual Dialogue User Guide 185

186 The Customer object Method Example: var scomment = Sections[2].GetComment(); void ClearComment() Deletes a section comment, if one exists. The method has no return value. Example: Sections[2].ClearComment(); The Customer object Overview The Customer object gives access to customer data. It enables you to get and set values of customer domain fields from flow scripts. Example: var Gender = Customer.Fields["Gender"]; Properties The following properties are supported: Property object Fields[string FieldName] Gets or sets the value of a customer domain field for the customer completing the questionnaire. Example: Customer.Fields[" "] = Questions[" "].GetAnswer- Text(); Note: To be able to set/update customer data, the questionnaire must be configured correctly. See Questionnaire properties on page 163. bool HasChanged Indicates whether the Customer object contains any cached changes to customer data that has not yet been written to the underlying customer domain (the customer database). The customer domain (customer database) will normally be updated when the customer finishes responding to the questionnaire. This means that the answer form and any changes to customer data are saved at the same time, and in the same database transaction. Methods The following methods are supported: 186 Portrait Dialogue 6.0

187 Chapter 7: Questionnaires Method void Remove (string FieldName) Removes a change to a value of a domain field that has previously been set using the Fields property. Remove must be called before the change is written to the underlying customer domain (customer database). Example: Customer.Remove(" "); void RemoveAll() Removes all changes to values of domain fields that have previously been set using the Fields property. RemoveAll must be called before the changes are written to the underlying customer domain (customer database). Example: Customer.RemoveAll(); Examples of scripting in questionnaire flow Overview Here are some real-life examples using scripting in questionnaire flow. Question and alternative keys are given in parentheses. Example: altering page flow This example checks which answer is given for a single-choice question (Q1) with three options (on page 1), and sets the next page to page 2, 3, or 4, depending on the answer given for question Q1. The script is located in the page s page exit action. if (Questions["Q1"].Alternatives["A1"].IsAnswered()) ActivePage.NextPageKey = "P2"; else if (Questions["Q1"].Alternatives["A2"].IsAnswered()) ActivePage.NextPageKey = "P3"; else if (Questions["Q1"].Alternatives["A3"].IsAnswered()) ActivePage.NextPageKey = "P4"; Example: hiding matrix rows This example checks which answer is given for a single-choice question (Q5) with three options, and hides a row in a matrix (M2), depending on the answer given for question Q5. The script is located in the page s page enter action. if (Questions["Q5"].Alternatives["A1"].IsAnswered()) Matrix["M2"].Rows[2].Hide = true; else if (Questions["Q5"].Alternatives["A2"].IsAnswered()) Matrix["M2"].Rows[3].Hide = true; else if (Questions["Q5"].Alternatives["A3"].IsAnswered()) Matrix["M2"].Rows[4].Hide = true; Visual Dialogue User Guide 187

188 Examples of scripting in questionnaire flow Example: using domain data to verify answers This example retrieves the customer s street address and zip code from the customer domain and checks these against the examples given by the customer in question Q15 and Q16. If the names match, the next page is skipped. If the names do not match, the next page is not skipped, prompting the user to verify the data in questions Q17 and Q18 (section 10). The script is located in the page exit action for page 5. var sdomainstreetaddress = EvaluateExpressionString("Streetaddress"); var sdomainzipcode = EvaluateExpressionString("Zipcode"); var sgivenstreetaddress = Questions["Q15"].GetAnswerText(); var sgivenzipcode = Questions["Q16"].GetAnswerText(); if ((sdomainstreetaddress!= sgivenstreetaddress) (sgivenstreetaddress!= sgivenzipcode)) { Sections[10].Caption = "Please verify your street address and zip code."; Questions["Q17"].SetAnswerText(sGivenStreetaddress); Questions["Q18"].SetAnswerText(sGivenZipcode); } else Pages["P6"].Skip = true; Example: validating answers This example checks whether the user has checked a checkbox (A1) in a multi-choice question (Q2, requesting information sent by ). If the checkbox is selected, the given address (Q3) is verified using a regular expression. If the test fails, the answer is cleared and an error message is displayed on the question. The script is located in the page s page exit action. if (Questions["Q2"].Alternatives["A1"].IsAnswered()) { var s = Questions["Q3"].GetAnswerText(); var regex = /^([a-za-z0-9_\-\.]+)@((\[[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.) (([a-za-z0-9\-]+\.)+))([a-za-z]{2,4} [0-9]{1,3})(\]?)$/; if (!regex.test( address)) { Questions["Q3"].IsValid = false; Questions["Q3"].ErrorMessage = "Please enter a correct address" } } + "(you entered: " + s + ")"; Questions["Q3"].ClearAnswer(); Example: setting customer data This example is from a sign-up page where an anonymous response is used to create a new customer in a sign-up domain. Some fields of the customer are set in the user interface of Questionnaire Designer by linking simple questions to domain fields, while some fields have to be set in the script instead of the user interface because the questions are of other types (e.g. multi-option). The script is located in a page s page exit action. [C#] // Set gender in customer data 188 Portrait Dialogue 6.0

189 if (Questions["GENDER"].Alternatives["F"].IsAnswered()) Customer.Fields["Gender"] = "Female"; else Customer.Fields["Gender"] = "Male"; // Set country in Customer data if (Questions["COUNTRY"].Alternatives["OTHER"].IsAnswered()) Customer.Fields["Country"] = Questions["COUNTRY"].Alternatives["OTHER"].GetAnswerText(); else Customer.Fields["Country"] = Questions["COUNTRY"].Alternatives[Questions["COUNTRY"].GetSingleChoiceAnswer()].Caption; The image below shows the question structure. Chapter 7: Questionnaires Visual Dialogue User Guide 189

190 The Dialogue Server API The Dialogue Server API The Generic API Overview The Generic API provides a set of methods for accessing generic objects defined in Dialogue Admin. These include datasets and SQL statements stored in the SQL Repository, as well as generic plug-ins. Example: var dataset = GenericAPI.GetDataset("MyCustomSQL"); Methods The following methods are available: Method variant ExecutePlugin(string PluginName, array Params) Executes a Dialogue Server plug-in of type Generic plug-in, implementing the interface IMHGenericPlugin. PluginName is the name of the plug-in as defined in Dialogue Admin. Params is an array that contains parameter values. The return value is the value returned from the plug-in. integer ExecuteSQL(string SQLName, array Params) Executes an SQL statement stored in the SQL repository in Dialogue Admin. void ExecuteSQLScript(string SQLName, array of MHGenericParam Params) SQLName is the technical name of the statement. Params is an array that contains parameter values. The return value is the number of records affected. Executes an SQL script (multiple SQL statements) stored in the SQL repository in Dialogue Admin. SQLName is the technical name of the statement. Params is an array that contains parameter values. The definition of MHGenericParam may be a record, a struct, or a class depending on the calling language. Note: This method enable clients to execute a series of SQL statements in one transaction. void ExecuteStored- Proc(string StoredProcName, array Params, string ConnectionName) Executes a stored procedure using the specified database connection. StoredProcName is the name of the stored procedure as defined in the database. Params is an array that contains parameter values. 190 Portrait Dialogue 6.0

191 Chapter 7: Questionnaires Method ConnectionName is the technical name of the secondary database connection defined in Dialogue Admin. Leaving ConnectionName blank indicates that the default database connection should be used. DataSet GetDataset(string SQLName, array Params) Returns a DataSet object defined in Dialogue Admin as XML. SQLName is the name of the item in the SQL Repository defining the dataset. Params is an array that contains parameter values (database host variables). DataSet GetDataset (string SQLName, array Params, integer MaxRows) Returns a DataSet object defined in Dialogue Admin as XML. SQLName is the name of the item in the SQL Repository defining the dataset. Params is an array that contains parameter values (database host variables). MaxRows indicates the maximum number of rows to retrieve. Setting MaxRows to -1 returns all rows, while a value of 0 will return only an empty dataset. Returns the next value of the specified sequence. Sequences are provided by the Dialogue Server to maintain unique identifiers. The Dia- logue Server guarantees uniqueness of the numbers returned by distinct calls to GetSequenceID. long GetSequenceID(string SequenceName) SequenceName is the name of the sequence. If a non-existent sequence is specified, a new sequence is created automatically. Note: Sequences are an internal mechanism in the Dialogue Server and should not be confused with database sequences. For example, Oracle has its own mechanism called sequences. variant UpdateDataset(string SQLName, array Params, DataSet dataset) Updates a dataset that was retrieved earlier using the GetDataset method. UpdateDataset returns the last ID generated by the database for the top-level table in the dataset. Typically this will be the value from an auto-incremented column or a database sequence. If such columns are not defined in Dialogue Admin, the return value is null. SQLName is the name of the item in the SQL Repository defining the dataset. Params is an array that contains parameter values. These parameter values must be equal to the parameter values that were specified when the original dataset was retrieved using GetDataset. Visual Dialogue User Guide 191

192 The Dialogue Server API Method dataset is the DataSet object containing new, updated, or deleted records. The Customer API Overview The Customer API provides a set of methods for accessing data related to customers. Methods The following methods are supported: Method DataSet EvaluateExpression(int CustDomainID, string CustomerID, string Expression) bool EvaluateExpression- Bool(int CustDomainID, string CustomerID, string Expression) Returns a DataSet object containing the result value of the specified expression. CustDomainID is the ID specifying the customer domain, and CustomerID is the ID of the customer for which the expression will be evaluated. Expression is the expression to evaluate. Evaluates and returns the result of a boolean expression. CustDomainID is the ID specifying the customer domain, and CustomerID is the ID of the customer for which the expression will be evaluated. Expression is the expression to evaluate. Specifying a non-boolean expression raises an exception. string EvaluateExpression- String(int CustDomainID, string CustomerID, string Expression) integer GetCustomer- Count(int CustDomainID, string FilterExpression, string ContextExpression) Evaluates and returns the result of an expression. CustDomainID is the ID specifying the customer domain, and CustomerID is the ID of the customer for which the expression will be evaluated. Expression is the expression to evaluate. Specifying an expression that returns a data group or an array raises an exception. To evaluate such an expression, use the EvaluateExpression method. Returns the number of customers fulfilling the criteria specified. CustDomainID is the ID that specifies the customer domain. FilterExpression is an expression used to filter or refine the selection of customers counted. 192 Portrait Dialogue 6.0

193 Chapter 7: Questionnaires Method DataSet GetCustomers(string FilterExpression, string ContextExpression, string DataFields, integer MaxCount) DataSet GetCustomers(int CustDomainID, string FilterExpression, string ContextExpression, string DataFields, integer MaxCount) DataSet GetCustomerSelection(int SelectionID, string DataFields, integer MaxCount) ContextExpression will, if specified, assign context values to customers before they are counted. ContextExpression is an expression returning a string value, or possibly an array of strings. In the case of a string array, there can be multiple context values per customer, and a customer can be included more than once once for each context value. Returns a DataSet object containing the customers with customer data that fulfil the criteria specified. FilterExpression is an expression used to filter or refine the selection of customers returned. ContextExpression will, if specified, assign a value to the field mh_context in the returned DataSet. ContextExpression is an expression returning a string value, or possibly an array of strings. In the case of a string array, there can be multiple context values per customer, and a customer can be included more than once once for each context value. DataFields is a semicolon-separated list of customer data groups and fields (from the customer domain definition) to return in the DataSet object. MaxCount is the maximum number of customers to return. Set Max- Count to -1 to return all customers fulfilling the other criteria specified. Returns a DataSet object containing the customers with customer data fulfilling the criteria specified. CustDomainID is the ID that specifies the customer domain. FilterExpression is an expression used to filter or refine the selection of customers returned. ContextExpression will, if specified, assign a value to the field mh_context in the returned DataSet. ContextExpression is an expression returning a string value, or possibly an array of strings. In the case of a string array, there can be multiple context values per customer, and a customer can be included more than once once for each context value. DataFields is a semicolon-separated list of customer data groups and fields (from the customer domain definition) to return in the DataSet object. MaxCount is the maximum number of customers to return. Set Max- Count to -1 to return all customers fulfilling the other criteria specified. Returns a DataSet containing customers in the specified selection. SelectionID is the ID of the selection. Visual Dialogue User Guide 193

194 The Dialogue Server API Method DataFields is a semicolon-separated list of customer data groups and fields (from the customer domain definition) to return in the DataSet. MaxCount is the maximum number of customers to return. Set Max- Count to -1 to return all customers fulfilling the other criteria specified. integer GetCustomerSelectionCount(int SelectionID) DataSet GetSingleCustomer(string DataFields) DataSet GetSingleCustomer(int CustDomainID, string CustomerID, string DataFields) DataSet GetCategories() Returns the number of customers in the specified selection. SelectionID is the ID of the selection. Returns a DataSet object containing the current customer with customer data fulfilling the criteria specified. DataFields is a semicolon-separated list of customer data groups and fields (from the customer domain definition) to return in the DataSet object. Returns a DataSet object containing a single customer with customer data fulfilling the criteria specified. CustDomainID is the ID specifying the customer domain, and CustomerID is the ID of the customer to retrieve. DataFields is a semicolon-separated list of customer data groups and fields (from the customer domain definition) to return in the DataSet object. Returns a DataSet object containing all categories defined in Dialogue Admin. void PostEvent(string Event- TypeName, string, string Context) Posts a system event. System events are defined in Dialogue Admin, and the Dialogue Server can be set up to take actions when system events occur. For example, an operation in one or more dialogs can be executed. EventTypeName is the technical name of the event type defined in Dialogue Admin. is an optional description of the event. Context is the customer s context value. If context is not required, set Context to the string "0". void PostEvent(string Event- TypeName, string, int CustDomainID, string CustomerID, string Context) Posts a system event. System events are defined in Dialogue Admin, and the Dialogue Server can be set up to take actions when system events occur. For example, an operation in one or more dialogs can be executed. EventTypeName is the technical name of the event type defined in Dialogue Admin. is an optional description of the event. 194 Portrait Dialogue 6.0

195 Chapter 7: Questionnaires Method void RemoveCategory(int CustDomainID, string CustomerID, string CategoryName) CustDomainID is the ID specifying the customer domain, and CustomerID is the ID of the customer related to the new event. Context is the customer s context value. If context is not required, set Context to the string "0". Removes a customer from a category, i.e. delete the category membership. CustDomainID is the ID specifying the customer domain, and CustomerID is the ID of the customer. CategoryName is the technical name of the category as defined in Dialogue Admin. void RemoveCategoryValue(int CustDomainID, string CustomerID, string Category- Name, string Value) void SetCategory(int CustDomainID, string CustomerID, string CategoryName) Removes a customer s value from a category. The category must be of type category with values. CustDomainID is the ID specifying the customer domain, and CustomerID is the ID of the customer. CategoryName is the technical name of the category as defined in Dialogue Admin. Value is the string value to remove, as defined in the category setup in Dialogue Admin. Adds a customer to a category, i.e. create a category membership. CustDomainID is the ID specifying the customer domain, and CustomerID is the ID of the customer. CategoryName is the technical name of the category as defined in Dialogue Admin. void SetCategoryValue(int CustDomainID, string CustomerID, string CategoryName, string Value) Adds a customer to a category with a value, i.e. create a category membership or add a value to an existing membership. CustDomainID is the ID specifying the customer domain, and CustomerID is the ID of the customer. CategoryName is the technical name of the category as defined in Dialogue Admin. Value is the string value to set, as defined in the category setup in Dialogue Admin. string UpdateSingleCustomer(string DataFields, DataSet CustomerData) Sends updates of customer data to the Dialogue Server to store changes. This method may insert a new customer, or delete or update an existing customer. If a new customer is inserted, the Customer ID of the new customer is returned. Visual Dialogue User Guide 195

196 The Dialogue Server API Method DataFields is a semicolon-separated list of customer data groups and fields (from the customer domain definition) contained in the Customer- DataXML. CustomerData is the DataSet object containing changed customer data. Note: DataFields is theoretically redundant information. However, in the current version it is required, in order to ease communication of changes between a client and the Dialogue Server. string UpdateSingleCustomer(int CustDomainID, string CustomerID, string DataFields, DataSet Customer- Data) Sends updates of customer data to the Dialogue Server to store changes. This method may insert a new customer, or delete or update an existing customer. If a new customer is inserted, the Customer ID of the new customer is returned. CustDomainID is the ID specifying the customer domain, and CustomerID is the ID of the customer to update, delete, or insert. DataFields is a semicolon-separated list of customer data groups and fields (from the customer domain definition) contained in the Customer- DataXML. CustomerData is the DataSet object containing changed customer data. Note: DataFields is theoretically redundant information. However, in the current version it is required, in order to ease communication of changes between a client and the Dialogue Server. The Dialog API Overview The Dialog API provides a set of methods for accessing data related to dialogs and participants. Methods The following methods are supported: Method DataSet EvaluateExpression(int CustDomainID, double ParticipantID, string Expression) Returns a DataSet object containing the result value of the specified expression. CustDomainID is the ID specifying the customer domain, and ParticipantID is the ID of the dialog participant for which the expression will be evaluated. 196 Portrait Dialogue 6.0

197 Chapter 7: Questionnaires Method bool EvaluateExpression- Bool(int CustDomainID, double ParticipantID, string Expression) Expression is the expression to evaluate. Evaluates and returns the result of a boolean expression. CustDomainID is the ID specifying the customer domain, and ParticipantID is the ID of the dialog participant for which the expression will be evaluated. Expression is the expression to evaluate. Specifying a non-boolean expression raises an exception. string EvaluateExpression- String(int CustDomainID, double ParticipantID, string Expression) integer GetParticipant- Count(int CustDomainID, int GroupID, string FilterExpression) Evaluates and returns the result of an expression. CustDomainID is the ID specifying the customer domain, and ParticipantID is the ID of the dialog participant for which the expression will be evaluated. Expression is the expression to evaluate. Specifying an expression that returns a data group or an array raises an exception. To evaluate such an expression, use the EvaluateExpression method. Returns the number of participants fulfilling the criteria specified. CustDomainID is the ID specifying the customer domain. GroupID is the ID of the dialog group containing the participants. FilterExpression is an expression used to filter or refine the selection of participants counted. DataSet GetParticipants(int Returns a DataSet object containing participants with customer data. CustDomainID, int GroupID, CustDomainID is the ID specifying the customer domain. string FilterExpression, string DataFields, integer MaxCount) GroupID is the ID of the dialog group containing the participants. DataSet GetParticipantSelection(int GroupID, int Selection- ID, string DataFields, integer MaxCount) FilterExpression is an expression used to filter or refine the selection of participants returned. DataFields is a semicolon-separated list of customer data groups and fields (from the customer domain definition) to return in the DataSet object. MaxCount is the maximum number of participants to return. Set Max- Count to -1 to return all participants. Returns a DataSet object containing participants with customer data. The returned participants must be in the specified dialog group and at the same time be contained in the specified selection. GroupID is the ID of the dialog group containing the participants. SelectionID is the ID of the selection. Visual Dialogue User Guide 197

198 Client-side events and scripts Method DataFields is a semicolon-separated list of customer data groups and fields (from the customer domain definition) to return in the DataSet object. MaxCount is the maximum number of participants to return. Set Max- Count to -1 to return all participants. integer GetParticipantSelectionCount(int GroupID, int SelectionID) Returns the number of participants fulfilling the criteria specified. The counted participants must be in the specified dialog group and at the same time be contained in the specified selection. GroupID is the ID of the dialog group containing the participants. SelectionID is the ID of the selection. DataSet GetSingleParticipant(long ParticipantID, string DataFields) Returns a DataSet object containing a single participant with customer data. CustDomainID is the ID specifying the customer domain. ParticipantID is the ID of the participant to return. DataFields is a semicolon-separated list of customer data groups and fields (from the customer domain definition) to return in the DataSet object. Client-side events and scripts About client-side events and scripts Overview The questionnaire module supports client-side scripting using the standard JavaScript language. The purpose of using client-side scripting is to manipulate the browser page user interface, like changing values or showing/hiding elements/questions. Scripts can be defined for a variety of events on question and alternative controls, and the page object. The script language The script language used is the widely used standard JavaScript language. A set of special client-side support functions and properties is available when writing JavaScript in the questionnaire module. These support functions provides easy access to elements and controls on the page, and functionality for e.g. setting values and displaying messages. 198 Portrait Dialogue 6.0

199 Chapter 7: Questionnaires Events A numerous set of events are available on question and alternative controls, and the page object when using client-side scripting in a questionnaire. See Working with client-side scripts and events on page 199 for details. Working with client-side scripts and events Overview Client-side scripts in a questionnaire can be defined for a numerous set of events for layouts (all pages), pages, questions and alternatives. The MHControl property is always available when writing a script for an event. This property will always return the element that fired the event. JavaScripts in a questionnaire can be added on four levels: 1. Layout JavaScripts added on the layout level will be added to all pages. Adding a script for the same event on a specific page will override the script added on the layout. 2. Page JavaScripts for the page object. 3. Question JavaScripts for events on the question control. 4. Alternative JavaScripts for events on the question alternative control. Adding JavaScripts To define a JavaScript for one event, open a layout in the questionnaire, and find the layout, page, question or alternative that you want to add a script to. Right-click and choose JavaScripts (or click on the script button). The JavaScripts window opens. Select an event in the Events list. Write the JavaScript statement in the Script textbox. Click on OK. JavaScripts overview The JavaScripts Overview window displays an overview of all javascripts used in a layout. Scripts listed here can be edited directly from this window. To display the JavaScripts Overview window, right-click anywhere in the layout tree view, and choose JavaScripts Overview. See Available events on page 200 for a detailed list of all events available when scripting. Visual Dialogue User Guide 199

200 Available events Available events Available events Below is a list of the events available in the questionnaire module: Event onclick onchange onblur ondblclick onfocus onkeydown onkeypress onkeyup onmousedown onmousemove onmouseover : Fires when the user clicks the left mouse button on the object Applicability: Page, Question, Alternative : Fires when the contents of the object or selection have changed Applicability: Question, Alternative : Fires when the object loses the input focus Applicability: Question, Alternative : Fires when the user double-clicks on the object Applicability: Page, Question, Alternative : Fires when the object receives focus Applicability: Question, Alternative : Fires when the user presses a key Applicability: Page, Question, Alternative : Fires when the user presses an alphanumeric key Applicability: Page, Question, Alternative : Fires when the user releases a key Applicability: Page, Question, Alternative : Fires when the user clicks on the object with either mouse button Applicability: Page, Question, Alternative : Fires continuously when the user moves the mouse over the object Applicability: Page, Question, Alternative : Fires when the user moves the mouse pointer into the object 200 Portrait Dialogue 6.0

201 Chapter 7: Questionnaires Event Applicability: Page, Question, Alternative onmouseup onpageenter onpageexit onbeforevalidate onaftervalidate onmouseout : Fires when the user releases a mouse button while the mouse is over the object Applicability: Page, Question, Alternative : Fires immediately after the browser loads the object Applicability: Page : Fires immediately before the object is unloaded Applicability: Page : Fires immediately before the page is validated Applicability: Page Use: Returning false will prevent the page from being validated and submitting (return false;) : Fires immediately after the page is successfully validated Applicability: Page Use: Returning false will prevent the page from submitting (return false;) : Fires when the user moves the mouse pointer outside the boundaries of the object Applicability: Page, Question, Alternative Global script methods Global methods The following global functions are available when using client-side JavaScript in a questionnaire: Function void MHDisplayErrorMessage(string errormessage [, string questionkey]) Parameters errormessage: The error message to display. questionkey (optional): Specifies the question key. If specified, the error message will be displayed on the question, otherwise the error message will be displayed at the bottom of the page. Visual Dialogue User Guide 201

202 Global script methods Function This method provides easy functionality for setting the value of a question s or an alternative s control. This method has no return value. Return value This method has no return value. Example This example displays an error message related to a question: MHDisplayErrorMessage("Please fill in your phone number", "Q7"); object MHGetAlternativeContainer( string questionkey, string alternativekey ) Parameters questionkey: The question key. alternativekey: The alternative key. object MHGetAlternativeImage( string questionkey, string alternativekey) Return value Returns the element (TABLE) containing a radiobutton or checkbox alternative. The return value is of type: Table HTML element (click to view external documentation). Example This example chenges the border of an alternative: var alternative = MHGetAlternativeContainer("Q2", "A3"); alternative.style.border = "2px outset red"; Parameters questionkey: Specifies the question key. alternativekey: Specifies the alternative key. Return value Returns an alternative s image element. The return value is of type: Img HTML element (click to view external documentation). Example This example changes the URL of an alternative s image: var image = MHGetAlternativeImage("Q5", "A3"); image.src = " 202 Portrait Dialogue 6.0

203 Chapter 7: Questionnaires Function object MHGetCaption( string questionkey [, string alternativekey]) Parameters questionkey: Specifies the question key. alternativekey (optional): Specifies the alternative key. If omitted, the question caption element is returned. Return value Returns a question s or alternative s caption element. The return value is of type: Span HTML element (click to view external documentation). Example This example changes a questions s caption: var caption = MHGetCaption("Q3"); caption.innerhtml = "Custom Question Caption"; object MHGetControl(string questionkey [, string alternativekey, bool getalternativetextbox] ) Parameters questionkey: Specifies the question key. alternativekey (optional): Specifies the alternative key. If omitted, the question control is returned. getalternativetextbox (optional): Passing true to the function will return the alternative s textbox. Return value Returns a question, alternative or alternative textbox element. The return element type depends on the requested questionnaire element: Single-line textbox control: Input HTML element, type=text (click to view external documentation). Multi-line textbox control: Textarea HTML element (click to view external documentation). Drop-down list control: Select HTML element (click to view external documentation). Listbox control: Select HTML element (click to view external documentation). Radio button control: Input HTML element, type=radio (click to view external documentation). Checkbox control: Input HTML element, type=checkbox (click to view external documentation). Example This example sets a checkbox (of a multi choice question): var chkbox = MHGetControl("Q1", "A2"); chkbox.checked = true; Visual Dialogue User Guide 203

204 Global script methods Function object MHGetMatrixCaption( string matrixkey [, string type, int index]) object MHGetQuestionContainer( string key [, bool ismatrix]) object MHGetQuestionImage(string key [, int index, bool ismatrix]) Parameters matrixkey: Specifies the matrix key. type: (optional) Specifies if a row or column. Set to "row" or "column" to get the row or column caption element. If omitted or other value, the matrix s caption is returned. index (optional): Specifies the index of a row or column. The first row or column has index = 0. Return value Returns a matrix s caption element or a matrix s row or column caption element. The return value is of type: Span HTML element (click to view external documentation). Example This example changes the caption of the second row in a matrix: var rowcaption = MHGetMatrixCaption("M1", "row", 1); rowcaption.innerhtml = "Custom Row Caption"; Parameters key: Either a question key or a matrix key. ismatrix (optional): Specifies if the container is a matrix. If omitted, the container is considered a question. Return value Returns the element (SectionItem) containing a question or a matrix. The return value is of type: Table HTML element (click to view external documentation). Example This example hides an entire question: var question = MHGetQuestionContainer("Q2"); question.style.display = "none"; Parameters key: Specifies the matrix or question key. index (optional): Specifies the index of the question or matrix image. The first image has index = 0. If omitted, the first image is returned. ismatrix (optional): Specifies if a matrix question is requested. If omitted, the image is considered a question image. Return value 204 Portrait Dialogue 6.0

205 Chapter 7: Questionnaires Function Returns a question s or a matrix s image element. The return value is of type: Img HTML element (click to view external documentation). Example This example changes the URL of a question image: var image = MHGetQuestionImage("Q4"); image.src = " object MHGetSection(int sectionindex) Parameter sectionindex: Specifies the index of the page section. The first section has index 0. object MHGetSectionCaption( int sectionindex) void MHSetValue(variant value, string questionkey [, string alternativekey, bool getalternativetextbox] ) Return value Returns the section element. The return value is of type: Table HTML element (click to view external documentation). Example This example hides the second section on the page: var section = MHGetSection(1); section.style.display = "none" Parameter sectionindex: Specifies the index of the page section. The first section has index 0. Return value Returns the section s caption element. The return value is of type: TD HTML element (click to view external documentation). Example This example changes the caption of the first section on the page: var caption = MHGetSectionCaption(0); caption.innerhtml = "Custom Section Caption"; Parameters variant: The value to set. The type of this parameter is dependent of the question or alternative control specified. questionkey: Specifies the question key. alternativekey (optional): Specifies the alternative key. getalternativetextbox (optional): Passing true to the function will set the alternative s textbox value accordingly to the first parameter. Visual Dialogue User Guide 205

206 Global script properties Function This method provides easy functionality for setting the value of a question s or an alternative s control. This method has no return value. Return value This method has no return value. Example This example sets the value of a simple (text) question: MHSetValue("Type Some Text Here...", "Q6"); Global script properties Global properties The following global properties are available when using client-side JavaScript in a questionnaire: Property string MHAlternativeKey This property returns the alternative key of the alternative control that fired the event. Property type This property is of type string object. object MHBackButton Gets the back button. Property type The property is of type: Input HTML element, type=submit (click to view external documentation). object MHCloseButton Gets the close button. Property type The property is of type: Input HTML element, type=submit (click to view external documentation). string MHContext Gets or sets the answer form s context. Property type 206 Portrait Dialogue 6.0

207 Chapter 7: Questionnaires Property The property is of string type. object MHControl This property returns the control that fired the event. Property type The property type depends on the control that fired the event: Single-line textbox control: Input HTML element, type=text (click to view external documentation). Multi-line textbox control: Textarea HTML element (click to view external documentation). Drop-down list control: Select HTML element (click to view external documentation). Listbox control: Select HTML element (click to view external documentation). Radio button control: Input HTML element, type=radio (click to view external documentation). Checkbox control: Input HTML element, type=checkbox (click to view external documentation). Page control: Div HTML element (click to view external documentation). int MHCustomerDomainID Gets the customer domain id. Only relevant if MHIsAnonymous = false. Property type The property is of integer type. int MHCustomerID Gets the customer id. Only relevant if MHIsAnonymous = false. Property type The property is of integer type. object MHForwardButton Gets the forward (next) button. Property type The property is of type: Input HTML element, type=submit (click to view external documentation). bool MHIsAnonymous This boolean property is true if the answer form is anonymous, else false. Property type Visual Dialogue User Guide 207

208 Global script properties Property The property is of boolean type. bool MHIsNew bool MHIsPagePreview This property is true if the answer form is new (not previously stored), else false. Property type The property is of boolean type. This boolean property is true when previewing a page in Visual Dialogue, else false. Property type The property is of boolean type. bool MHIsPreviewMode This boolean property is true when previewing the questionnaire in Visual Dialogue, else false. Property type The property is of boolean type. string MHQuestionKey object MHPage int MHPageIndex int MHParticipantID This property returns the question key of the question control that fired the event. Property type This property is of type string object. Gets the questionnaire page element. Property type The property is of type: Div HTML element (click to view external documentation). Gets the current page index. Property type The property is of integer type. Gets or sets the participant id. 208 Portrait Dialogue 6.0

209 Chapter 7: Questionnaires Property Property type The property is of integer type. object MHResetButton Gets the reset button. Property type The property is of type: Input HTML element, type=submit (click to view external documentation). Visual Dialogue User Guide 209

210

211 Reports 8 In this section: About reports How and why reports are used Report Designer Preview View Browsing reports Report security Report formats Report Portal Integrated reporting

212 About reports About reports Visual Dialogue ships with integrated functionality for designing and running reports. The integrated Report Designer tool is used for designing the reports. Report Designer Report Designer is used to design custom reports using domain and/or SQL datasources. See About Report Designer on page 213 for details. Report templates Use Report Designer to create report templates. A report template is the template used when generating (and optionally saving) reports in the Report Portal application. See Creating a new report template on page 213 for details on how to create templates. How and why reports are used Reporting is the process of accessing data, formatting it, and delivering it inside and outside your organization. Reporting is also used in Business Intelligence strategy, providing your users with the requested information, formatted in the requested format. The Report Portal simplifies managing, securing, and delivering reports over the web. And it presents information in familiar, easy-to-use formats. The report equation The process of using reports is shown in the equation below. data access + data process + report layout = report output Data Access Data Access is the physical data in a database. Data Process Data Process refers to the calculation of intermediate results based on the data and the modification of the report layout as the report is generated. Report Layout Report Layout is a set of design components that describe the look and feel of the report and define the behavior of components during report generation. 212 Portrait Dialogue 6.0

213 Chapter 8: Reports Report Output Report Output is the result of the reporting process, presenting the exact content in the requested format. This equation more or less covers the entire area of development known as reporting. In terms of importance, each element of the equation is basically equal. If any one element of the equation is not supported or is weakly supported, than the utility of the reporting solution is greatly reduced. Report Designer Creating a new report template To create a new report template, choose Report Template from the Create tab in Visual Dialogue. The New Report Template Wizard opens. Step 1 On the first page of the wizard, the new report template is given a name and optionally a description. In addition, you need to choose the report portal folder in which to save the report template. To delete, create, or rename a report portal folder, click on the button to the right of the folder drop-down list. The Select Report Portal Folder window opens. Step 2 On the second and last page of the wizard, the Default output format is selected. The different report formats are listed in Report formats on page 245. Note: All texts and options selected in the wizard can be changed at a later time in the Report Properties window. After you have completed the New Report Template Wizard, the Report Designer opens. About Report Designer Report Designer is the application you use to build and design report templates. Report Designer has three views: Data Data View opens by default when you open a report or create a new report. Defining your datasources is normally your first task. Layout Layout View is divided into two areas: the canvas and the workbench. The canvas is the area that contains the report design itself. This is where you place the bands and components that will ultimately Visual Dialogue User Guide 213

214 Report template properties control the content of each page of the report. The workbench consists of toolbars, component palettes, rulers, and other tools that can be used to manipulate the canvas. Preview Preview View is used for previewing your report, based on a set of test parameter values. Report template properties To review or edit a report template s properties, choose Properties from the File tab. For information related to report security, see Report security on page 244. The General tab General template properties. Name The report template s name The report template s description Created (read only) The date and time the template was created Created by (read only) The username of the user who created the report Last modified (read only) The date and time the template was last modified Last modified by (read only) The username of the user who last modified the template The Report Portal tab Use these properties to control the report s behaviour in Report Portal. Report Portal folder The report portal folder in which the template is saved. Click the browse button to the right of the folder name to browse and manage the template folders. Default format The default output format used when running the report. For a detailed list over the different formats available, see Report formats on page 245. Publish in Report Portal s overview Check this option to make the report template available in Report Portal s overview. The overview page in Report Portal is a list of all published report s, as shown in Report Portal. A common use of this option is to leave it cleared until you have finished designing the template. Enable run report Check this option to allow Report Portal users to run the report. If this is option not checked, only the template s archive will be available. The Advanced tab Use these properties to relate the report to a system type. All standard reports have a system report type set, for example. Relate to a system report type A list of all system report types available. Use only with a specific customer domain A list of all domains available. Set this drop-down list to use the system report type with one domain only. 214 Portrait Dialogue 6.0

215 Chapter 8: Reports Data View About Data View Data View opens by default when opening or creating a report. This is where you define all the datasources used in the report. Working in this view, you define your datasources, and you specify the parameters that are used for filtering/limiting the data at runtime. Datasources Data can be selected from two different types of datasource: 1. Custom SQL This option lets you write custom SQL queries, selecting data from SQL databases. 2. Customer domain This option lets you retrieve data from customer domains. Predefined selections may be used to limit the data selection. To define new datasources, see Defining datasources on page 215. A datasource may also be created as a sub-datasource. A sub-datasource is a datasource created below another datasource, binding it to its parent datasource. To define new sub-datasources, see Defining a sub-datasource on page 216. Parameters Parameters are used to filter or limit the data selection at runtime. One or many parameters may be defined, each being bound to one or many datasource fields. The Data View user interface The image below shows an example of Data View, where two SQL datasources are defined. Defining datasources To create a new datasource, choose Datasource > New datasource... from the Data ribbon tab, or right-click on the datasource folder in the treeview and choose New datasource. The New Datasource Wizard opens. Visual Dialogue User Guide 215

216 Data View Step 1 On the first page of the wizard, the datasource is given a name and optionally a description. Step 2 On the second page of the wizard, the Datasource type is selected: Custom SQL This option lets you write custom SQL queries, selecting data from SQL databases. Customer domain This option lets you select data from a customer domain. If you select Custom SQL, the wizard completes after this step. If you select Customer domain, the third page (step) must be processed. Step 3 On the third and last page of the wizard, the Customer Domain, and optionally a selection (to limit the data selection), is selected: Related information To define new sub-datasources, see Defining a sub-datasource on page 216. After a datasource is created, parameters bound to the datasource can be defined. See Defining and binding parameters on page 217. To test a datasource, see Testing datasources on page 218. To sort a datasource, see Datasource sorting on page 220. Defining a sub-datasource A sub-datasource is a datasource created below another datasource, binding it to its parent datasource. Creating a sub-datasource To create a sub-datasource, select the parent datasource then choose Datasource > New sub datasource... from the Data tab, or right-click on the datasource folder in the treeview and choose New sub datasource. The New Datasource Wizard opens. Note: A sub-datasource can only be created under an SQL datasource, and can only be defined using an SQL statement (so the wizard only encompasses the first step). Binding the sub-datasource to its parent datasource When defining the sub-datasource, the datasource must be bound to its parent datasource using a host variable; this host variable refers directly to one field in the parent datasource. 216 Portrait Dialogue 6.0

217 Chapter 8: Reports Using host variables, you can also bind Report parameters to a sub-datasource. If the parameter name contains spaces, these spaces should be replaced with underscores when referred to in the SQL statement. Usage The sub-datasource is executed once for each row in its parent s datasource result data table. Thus sub-datasources are useful, for example, when using subreports or the DBChart component. Related information After a datasource is created, parameters bound to the datasource can be defined. To learn how to test your datasource, see Testing datasources on page 218. To learn how to sort a datasource, see Datasource sorting on page 220. Defining and binding parameters Parameters are used to filter or limit the data selection at report generation runtime. One or more parameters can be defined for a report. To create a parameter, choose Parameter from the Data tab, or right-click on the parameter folder in the treeview and choose New parameter. The New parameter window opens. The General tab In the General tab, the following properties are defined: Parameter name The parameter s name (required) The parameter s description (optional) Required parameter Checking this option sets the parameter as required Data type The parameter s data type (required) Operator The parameter s operator (required) Fixed operator Check this option to lock the operator. If it is not checked, you can change the operator at runtime. Default value Use this option to set the parameter s default value (optional) The Bindings tab In the Bindings tab, the bindings to one or more datasources may be defined. Click on Add binding to add one binding. Datasource Select the datasource to bind to Field Select the datasource field to bind to Then click on OK The parameter binding is added to the list of parameter bindings (as shown two images above). To edit one binding, select the binding and click on Edit binding. The Parameter binding property window opens. Visual Dialogue User Guide 217

218 Data View To delete one binding, select the binding and click on Delete binding. Note: Instead of binding a field to a parameter, you can also refer to a parameter directly in the top SQL statement of a datasource. Example: SELECT * FROM dialog where dlg_id = :Dialog If the parameter name contains spaces, these spaces should be replaced with underscores when referred to in the SQL statement. The Lookup SQL tab If desired, a lookup SQL query can be defined. When you run the report in Report Portal, the lookup SQL is executed, and the result is displayed in a checkbox list if the parameter s operator is in. If not, it is shown in a drop-down list. To use a lookup SQL query, check Enable lookup SQL and write the SQL statement. To test your SQL, click on Test lookup SQL. (The number of rows returned is reported.) Note: One or two columns must be returned by the SQL statement: If one column is returned, the column is used both as value and display text in the checkbox list/drop-down list. If two columns are returned, the first column is used as value and the second column is used as the display text in the checkbox list/drop-down list. The Advanced tab Check this option to relate the parameter to a system parameter type. Select the system parameter type from the drop-down list. If the report is of e.g. system report type Dialog Report, the report must have a parameter with the system parameter type set to Dialog ID. Testing datasources All datasources in a report can be tested. This allows you to see a preview of a datasource s dataset. Testing an SQL datasource An SQL datasource can be tested with or without sub-datasources: Testing an SQL datasource without sub-datasources To test an SQL datasource without taking into account any sub-datasources, select the datasource and choose Test SQL > Test SQL from the Data tab, or right-click on the datasource and choose Test SQL. This executes the SQL statement and displays the result in the Datasource data preview window. Testing an SQL datasource inclusive sub-datasources To test an SQL datasource including eventual sub-datasources, select the datasource and choose Test datasource from the Data tab, or right-click on the datasource and choose Test datasource. This executes the SQL statement and the sub-datasources, and displays the result in the Datasource data preview window. Each row in the datasource result can be expanded in order to see the subdatasource s results. 218 Portrait Dialogue 6.0

219 Chapter 8: Reports If the datasource has no sub-datasources, the result will be the same as for the previous procedure. Testing a sub-datasource A sub-datasource can be tested with or without the binding to its parent datasource: Testing a sub-datasource with the binding To test a sub-datasource with the binding to its parent datasource, select the datasource and choose Test datasource from the Data tab, or right-click on the datasource and choose Test datasource. This executes the SQL statements including the sub-datasource, and displays the result in the Datasource data preview window. Each row in the parent datasource result can be expanded in order to see the sub-datasource s results. Testing a sub-datasource without the binding To test a sub-datasource without the binding to its parent datasource, select the datasource and choose Test SQL > Test SQL from the Data tab, or right-click on the datasource and choose Test SQL. A window then appears, prompting for the binding parameter. Fill in the parameter value and click on OK. This executes the SQL statement and displays the result in the Datasource data preview window. Testing a customer domain datasource To test a customer domain datasource, select the datasource and choose Test datasource from the Data tab, or right-click on the datasource and choose Test datasource. This returns the result in the Datasource data preview window. Report parameter test values To test your datasources with one or more parameter values given, choose Parameter Values from the Data tab, or right-click on the treeview and choose Report parameter values. The Report parameter test value window appears. Set the test values of the desired parameters and click on OK. Required parameters are marked as red in the window. When testing the datasources in the report, the given parameter values are used. See Test options on page 219 for global test value settings. Test options The test options are global settings in Report Designer and thus apply when working with all reports in the designer. To set the test options for testing reports in Report Designer, choose Test Options from the Data ribbon tab. The Report Test Options window opens. Max. number of records in SQL sample This setting sets the maximum number of records returned when executing an SQL datasource. To disable this limitation, either clear the field or set it to -1. Max. number of records in customer domain sample This setting sets the maximum number of records returned when executing a customer domain datasource. To disable this limitation, either clear the field or set it to -1. These settings also apply when previewing reports in the Preview View. Visual Dialogue User Guide 219

220 Layout View in Report Designer Datasource sorting It is possible to set sorting for any datasources that are defined for a report. To set the sorting for a datasource, select the datasource in the treeview, right-click, and choose Datasource Sort Settings. The Datasource sort settings window opens. Select the available fields (columns) that you want the datasource to be sorted by, and click on the left arrow. This will move the selected fields to the Sort fields list. To sort by all available fields, click on the double left arrow. To remove fields from the Sort fields list, select the desired items and move them back to the Available fields list by clicking on the right arrow. To change the sort order for a datasource item, select the item and click on. Layout View in Report Designer About Layout View in Report Designer Layout View is where you design and build a report layout. Layout View is divided into two areas: the toolbox and the canvas. The toolbox The toolbox consists of component palettes, toolbars, rulers, and other tools that can be used to manipulate the canvas. See Layout tools overview on page 221 for details about the available toolbox components. The canvas The canvas is the area that contains the report design. This is where you place the bands and the components (from the toolbox) that will ultimately control the content of each page of the report. Report bands About report bands The canvas is divided into sections called bands. These are where you place the components that will control the content of each page of the report. The bands A band is labeled in the section divider immediately below it: the first band is called header, the second is called detail, and the third is called footer. When the report is generated, the bands are printed on different parts of the page. There are many different types of band for different occasions. To add or remove bands from a report, choose Bands from the Layout ribbon tab. The available bands you can or must use in a report are: Detail 220 Portrait Dialogue 6.0

221 Chapter 8: Reports The detail band is the body of your report. This band is always present and cannot be removed. Header The content of the header band appears at the top of each page of the report. Footer The content of the footer band appears at the bottom of each page of the report Title The content of the title band appears once at the beginning of the report. Summary The content of the summary band appears once at the end of the report. To learn how to adjust the bands, see Band adjustment on page 221. Band adjustment If a shape does not quite fit in a band, e.g. the header band, you can remedy this by increasing the height of the band. To adjust the height: 1. Place your cursor over the divider labeled Header. Your cursor will change to an up/down arrow, indicating that you can drag the divider up and down. 2. Hold down the left mouse button and drag the divider up and down. Notice the two little lines that appear on the vertical ruler to the left of the divider. These lines are called guides because they represent the new position of the divider. 3. Increase the height of the header band by dragging the divider. This method of changing the size of the header band works for all bands. Layout tools Layout tools overview The layout tools consist of component palettes, tabs, rulers, and other tools that can be used to manipulate the canvas. Report components: The components that are available to design the report canvas are shown on the toolbar. For more information, see The Component palette toolbar. Report objects: All objects and components used in the report are listed in the Report Tree on the left side. For more information, see The Report Tree on page 222. See The Report Objects toolbox tab on page 222 for details. The Component palette toolbar The Component palette toolbar provides components for designing the report canvas. To use a component in a report, select the desired component in the Component palette toolbar, move the cursor to the desired location in the canvas, and then click to insert the component. Properties for a selected component in the canvas are available as toolbars in Layout View. The components available are: Visual Dialogue User Guide 221

222 Layout View in Report Designer Keep all component descriptions until next section, 'The Datasources and Fields toolbox tab' Remove all component descriptions until next section 'The Datasources and Fields toolbox tab' Rewrite the 'Report Objects toolbox tab' section The Report Tree The Report Tree provides a hierarchical overview and quick access to all objects and components used in a report. To access or select an object used in a report, browse the object outline and select the desired object. The selected object will be selected (get focus) in the report canvas. Properties for a selected object in the canvas are available as toolbars above the Layout View. The Datasources and Fields toolbox tab The Datasources and fields toolbox tab allows you to simply drag and drop database fields and parameters onto a report. By using parameter fields in a report, the parameter values used when running the report will be displayed in the report. Properties for a selected field in the canvas are available as toolbars in Layout View. Options Right-click in the Datasources and fields tab and choose Options to view the options for the fields. All Creates both the label and value field for the selected field. Style Choose Tabular to create the fields above each other. Choose Vertical to create the fields besides each other. Labels Creates the label for the selected field only. Fields Creates the value field for the selected field only. The Report Objects toolbox tab The Report Objects toolbox tab provides a hierarchical overview and quick access to all objects and components used in a report. To access or select an object used in a report, browse the object outline and select the desired object. The selected object will be selected (get focus) in the report canvas. Properties for a selected object in the canvas are available as toolbars above the Layout View. Components Crosstabs About spreadsheets The spreadsheet was one of the first applications that made the PC so successful. Spreadsheets present calculations in a grid format, that is, with column headers, row labels, and calculations in the cells. There are many different formats a spreadsheet may take. The crosstab format is one of the most popular. Crosstab stands for cross tabulation, a process by which totals and other calculations are performed based on common values found in a set of data. 222 Portrait Dialogue 6.0

223 Chapter 8: Reports For example, let s assume you have a set of data that describes the sales for a company. Each sale is represented by a row of data. Each row of data contains a customer name, city, state, sale date, and sale amount. Now, assume you want to know the total sales for each month by state. Here is one way you could present the data: State: AL Year: 1999 Total Sales: $2577 State: CA Year: 2000 Total Sales: $3548 This format is OK, but it makes a state-to-state comparison difficult. Another format is as follows: This format is easier to read and more compact. We are putting more information into less space. It is easy to make state-to-state comparisons. This format is a crosstab. The month and state values are called dimensions because they orient the data in rows and columns. The values in the cells are the calculations created when the sales data is summarized. The simple crosstab we have outlined here can be taken a step further. What if we wanted to know the sales by city (within state) as well as the total number of sales per city. We can present this information by adding another dimension to the columns (i.e. city) and another calculation to the values (i.e. count of sales). The resulting crosstab would look like this: Visual Dialogue User Guide 223

224 Layout View in Report Designer Notice the new subtotal columns after each state. This crosstab shows all of the information of the initial crosstab, plus more detailed information by city. You can see that crosstabs can express a lot of information in a very small amount of space. Report Designer has a built-in facility for creating crosstabs. The crosstab component is designed to handle the most common crosstab requirements with minimal effort on your part. For example, let s assume you wanted to create the crosstab we just described. You would take the following steps: 1 Select the sale data from the database 2 Create a crosstab component in the report layout. 3 Select the state, city, and month as dimensions. 4 Select count and sum as values. 5 Preview the report. It would look something like this: The Crosstab component Overview This tutorial shows how use the Crosstab tool when creating a report. 224 Portrait Dialogue 6.0

225 Chapter 8: Reports Step 1 Create a datasource with customer information containing, among other things, the following fields: SaleMonth SaleAmount Step 2 Create a crosstab: 1. Access the layout view. 2. Place a crosstab component in the detail band. 3. Use the Edit toolbar to assign the crosstab to the Customer datasource. 4. Choose File > Printer Setup, and set the orientation to Landscape. Click on OK. 5. Right-click over the crosstab and select Configure. Crosstab Designer will be displayed 6. Read the instructions at the top of Crosstab Designer. 7. Select the SaleMonth field, and drag it over the new row cell. Look for the black, triangular indicators that show where the dimension will be created. 8. When the indicators appear to the left of the new row element, drop the field into the diagram. 9. Click on OK. 10. Preview. A blank page is displayed because no values have been assigned to the crosstab. Step 3 Design the crosstab: 1. Return to the layout, right-click over the crosstab, and select Configure. 2. Drag the Sale Amount field over the new value cell. When the indicators appear, drop the field into the diagram. Note: The number 1000 that appears represents the format of the calculated value. The Grand Total indicates that the last row of the crosstab will show the total sale amount for all months. 3. Select SaleMonth and use the highlight color palette to set the color to green. Notice that the element turns fuchsia instead of green. This is because the cell is selected. Deselect it by clicking another element and it should turn green. 4. Select Grand Total and set the color to yellow. 5. Select Sum of Sale Amount and set the color to fuchsia. 6. Select the 1000 under Sum of Sale Amount and set the color to red. 7. Select the 1000 to the right of the grand total and set the color to gray. 8. Close the Crosstab Designer. 9. Preview. The colors allow you to see where each element prints. The values in red represent the sale amount per month. The value in gray is the grand total for the year. The numbers in green represent the months. The yellow and fuchsia sections show where the headings, or captions, print. The DBCalc component This component can be used to do various simple calculations on a datasource field. Visual Dialogue User Guide 225

226 Layout View in Report Designer Using the DBCalc component Create a DBCalc component in your report. Select the component in the canvas and then select the datasource field (must be numeric) to be used in the calculation. Right-click on the component in the canvas and choose Calculations to set the type of calculation/logic to use. The different calculations available are: Sum Summarizes the field. Min Displays the minimum value of the field Max Displays the maximum value of the field Average Displays the average value of the field Count Counts the number of the field Note: The DBCalc component calculates its value based on the values of the iterated field s accumulated value. For example, when using the Count calculation, the output will be 1, 2, 3, 4, Formatting the output value To format the component s numeric output value, right-click on the component in the canvas and choose DisplayFormat. The Format window opens. Then select the desired format from the list. The display format will then be formatted according to the selected format syntax. It is also possible to enter a custom format, or change a selected format by editing its syntax. The Chart component The Chart component The chart component provides functionality to draw charts and graphs based on a set of static values. A wide range of different graphs and settings are available. Configuring the Chart component Right-click on the component in the canvas and choose Edit Chart to configure the Chart component: The Edit Chart window is divided into two or more levels of tabs. The topmost tabs are: The Chart tab General chart configuration, information and functionality like adding series, changing titles, formatting etc. All tabs in this tab are documented in The Series tab on page 228. The Series tab Editing and configuring the series added. The Data tab Setting the series data (values), thus describing, for example, a bar graph or line graph. The Export tab Functionality for exporting the chart to an image file. The Print tab Functionality related to printing. 226 Portrait Dialogue 6.0

227 Chapter 8: Reports Adding and setting up series Adding and setting up series is the most common, and often one of the first tasks you do when configuring a chart component. In the Edit Chart window, open the page Chart > Series, and click on Add to add a series. The TeeChart Gallery window opens. A wide range of series is available. Under the Seriestab, series based on values can be selected. Under the Functions tab, series based on functions (e.g. y=f(x)) can be selected. Different versions of a series is available by clicking the little arrow at bottom left of the series icon. Note: Different configuration settings are available for each series selected. Configuring and setting up the data After adding series, an essential task is to configure the data. In order to do this, open the Data tab in the Edit Chart window. The Data tab contains all Series values. Use it to enter and modify series points. Each Series offers one or more values depending on the series style. For example, the Bar series has one value for each bar point. The Line series can optionally have an X value (horizontal position) for each point. Series values (X and Y) can be numeric or date/time. From this tab you can also change the specific color for each point. Simply double-click on the color you want to change. The Color Editor opens, enabling you to choose a different one. To modify a value you must double-click on the text or number you want to change, and press Enter after entering new values. Pressing the F2 key also enables data modification. Using the right-click menu, you can add new points to the series, by selecting Append row, and delete points, by selecting Delete row. The buttons with arrows enable you to change the selected cell. When you enter values that are very large, they might not be completely visible. You can resize the columns by clicking and dragging the line dividing the grid titles. If you enter erroneous data, you will not be able to change the cell contents. This is important when entering dates or numbers with floating decimals. Check or change your Regional Configuration at Windows Control Panel to customize dates and floating point numbers. To add a new row, right-click on the table and choose Append row. To delete a row, right-click on the row and choose Delete row. Note: This view may vary depending on the type of series used. The DBChart component The DBChart component provides functionality to draw charts and graphs based on values from a datasource. A wide range of different graphs and settings are available. Configuring the DBChart component Right-click on the component in the canvas and choose Edit Chart to configure it. Visual Dialogue User Guide 227

228 Layout View in Report Designer The Edit Chart window, as seen above, is divided into two or more levels of tabbed pages. The topmost tabbed pages are: Chart General chart configuration, information and functionality like adding series, changing titles, formatting etc. See The Series tab on page 228 for details. Series Editing and configuring the series added. Data Setting the series data (values), thus describing e.g. a bar- or line-graph. Export Functionality for exporting the chart to an image file. Print Functionality related to printing. Adding and setting up series Adding and setting up series is the most commonly, and often one of the first tasks you do when configuring a chart component. In the Edit Chart window, open the page Chart > Series, and click on Add to add a series. The TeeChart Gallery window opens. A wide range of series is available. Under the Series tab, series based on a datasource can be selected. Under the Functions tab, series based on functions (e.g. y=f(x)) can be selected. Different versions of a series is available by clicking the little arrow at bottom left of the series icon. Note: Different configuration settings are available for each series selected. Configuring and setting up the data After adding series, an essential task is to configure the data. To do this, open the page Series > Data Source in the Edit Chart window. Select Data Pipeline. Then select the label, x-value and bar (y-axis) value. Note: This view may vary depending on the type of series used. The Chart tab The Series tab This allows you to add, delete, change, etc. the chart Series on screen. Series check-box This property shows the selected Series in the Chart when checked. Series text By double-clicking on the Series type, an additional tab will be displayed containing the Chart Series properties. Arrows This property allows you to move through the selected Chart Series. Add By clicking on the Add button, a gallery of Chart Series types will be displayed. Delete This property allows you to Delete the selected Series. Title By clicking on the Title button, you will be able to change the title of the selected Series. Clone The Clone button allows you to duplicate the selected Series. Change By clicking on the Change button, a gallery of Series Types will be displayed where you can change the selected Series for a new Series. The General tab 228 Portrait Dialogue 6.0

229 Chapter 8: Reports This tab enables you to modify the Chart properties in general. Print Preview If you click on this button, the Print Editor window will be displayed containing Chart printing page-configuration options. Margins This option allows you to define the margins of the Chart page: Right, Left, Top, Bottom. The margins are expressed as percents. The Zoom tab Allow This option enables/disables the zoom function in the Chart. Animated This property determines if Zoom will be performed directly or it will be displayed as an animated sequence of zooms. Steps This property controls the number of zoom steps. Pen Pen property is used to draw a surrounding rectangle of the zoom area as mouse is dragged. By clicking on this button the Border Editor dialog will be displayed where you can define the Pen type. Pattern By clicking on this button the Pattern Editor will be displayed where you can define the Pattern type for the zoom area. Minimum Pixels Sets the minimum number of onscreen pixels traversed by the mouse drag for the zoom action to actuate. Direction Set the direction of the zoom (Horizontal, Vertical or Both) on a selected area. Mouse Button Sets the Mouse button used to enable the zoom action. The Scroll tab Allow Scroll This option enables/disables the scroll function in the Chart Series. Mouse Button Sets the Mouse button used to enable the scroll action. The Axis tab This tab allows the onscreen Chart Axis to be defined. The Axis tab has several parts: Visible This property shows or hides the Chart Axis (X, Y). Behind This property shows the Chart Axis behind the Series, or not. Axes The Chart has five Axes: Right, Left, Top, Bottom and Depth. It allows you to modify the Axes properties using the tabs options near it. Signs (+) and (-) This option enables to add or delete Chart Axes. The Scales tab Automatic Sets the selected Axis properties for the Chart to be proportional. Visible This property shows or hides the selected Axis lines. Inverted The selected Axis values can be inverted resulting in an inverted Chart. Auto / Change Auto property sets the Axis values automatically. Change property allows you to define a maximum and minimum axis value. Visual Dialogue User Guide 229

230 Layout View in Report Designer Change This property allows you to define the Axis Increment. The Axis increment is the minimum step between axis labels. Logarithmic This boolean property scales the Axis Logarithmically. Log Base Sets the base for the Logarithmic scale. The Title tab The Style tab Title This property allows you to define a Title or text for the selected Axis. Angle This property allows you to define the Title label angle. Size This property allows you to define the Axis title label size. Visible This property displays or hides the selected Axis title. The Text tab Font By clicking on this button the Font Editor dialog will be displayed, in which you can choose the desired title font. Color box By clicking on this button, the Color Editor dialog will be displayed, in which you can choose the desired text color. Outline By clicking on this button, the Border Editor dialog will be displayed, in which you can define the outline/border style for the axis title label. Inter-char spacing This property allows you to define the number of spaces from character to character in the Axis title text. Shadow By clicking on this button the Color Editor dialog will be displayed, in which you can define the Axis title label shadow color. Horizontal and Vertical Size Sets the title size. The Labels tab The Style tab Visible This property displays or hides the selected axis texts. Multi-line Activating multi-line axis labels will automatically break the Label line on occurrence of the space. Round First This property controls whether labels of the Axis selected will be automatically rounded to the nearest magnitude. Label On Axis This property controls whether Labels will be shown at Axis minimum and maximum positions, or not. Size This property allows you to define the Label Size of the selected Axis. Angle This property allows you to define the Label Angle of the selected Axis. Minimum Separation This property specifies the minimum distance between Axis Labels as a percentage. Style This property defines the text Style of the selected Axis; Auto, Value, Marks, Text and None. Format Tab Exponential This property defines the Axis values Exponentially. 230 Portrait Dialogue 6.0

231 Chapter 8: Reports Values Format This property defines the Axis Labels text Format/Mask Default Alignment This property controls whether the Axis Labels will be shown in the default position, or not. Text Tab Font By clicking on this button the Font Editor dialog will be displayed, in which you can choose the desired Axis Label text. Color box By clicking on this button, the Color Editor dialog will be displayed, in which you can choose the desired Axis Label text color. Outline By clicking on this button, the Border Editor dialog will be displayed, in which you can define the Outline/border style for the Axis Label text. Inter-char spacing This property allows you to define the number of spaces from character to character in the Axis label text. Shadow By clicking on this button the Color Editor dialog will be displayed, in which you can define the Axis label text shadow color. Horizontal and Vertical size Sets the Axis Label text shadow thickness. The Ticks tab Axis By clicking on this button, the Border Editor dialog will be displayed, in which you to define the Axis Ticks border. Grid By clicking on this button, a Border Editor will be displayed allowing you to define the Axis Ticks Grid. Ticks / Len This property defines the Border and Length in pixels of the Axis ticks. Inner / Len This property defines the Border and Length in pixels of Axis ticks drawn inside Chart boundaries. At Labels Only This property sets the Axis Ticks and Axis Grid to be drawn only at Labels. The Minor tab Ticks / Length This property defines the Border and the Length in pixels of Axis Minor ticks. Grid / Count This property defines the Grid Border and the number of Grid lines. The Position tab Position Axis position as a percentage (0-100%). 0% being Top for a horizontal Axis and Left for a vertical Axis. Start Axis Starting position on its own Axis expressed as percentage (0-100%). For a vertical Axis a StartPosition of 75% would place the top of the Axis 75% down the Chart. End Axis Ending position as a percentage. For the Vertical Axis a value of 75% would place the beginning of the scale 75% down from Top. Other side It controls the opposite Axis Position. Horizontal It determines the Axis Position Horizontally. The Titles tab This tab defines a Title, SubTitle, SubFoot, or Foot for the Chart. The Titles tab is divided into several subtabs: Visual Dialogue User Guide 231

232 Layout View in Report Designer The Style tab Visible This property controls whether the Title, SubTitle, etc. will be shown, or not. Adjust Frame This property controls the Text Label Frame. Alignment This property determines the position of the Title Label in the Chart panel: Left, Right or Center. Text This property defines the Label Text. The Position tab Custom This controls a Customized position for the Chart Title, SubTitle, etc. The Format tab Color By clicking on this button, the Color Editor dialog will be displayed, in which you can select the Title Label color. Pattern By clicking on this button, the Pattern Editor dialog will be displayed, in which you can define the Title Label Pattern. Transparent This property sets the Title Label BackColor transparent. Transparency This property sets the Title Label BackColor transparency. The Border tab Bevel This property defines the Bevel type: Lowered or Raised. Frame By clicking on this button, a Border Editor dialog will be displayed, in which you can define the Title Label Border/Frame. Size This property defines the Title Label Bevel size. Round Frame This property determines a rounded Frame for the Title Label. Size This property defines the Title Round Frame size. The Text tab Font By clicking on this button, the Font Editor dialog will be displayed, in which you can choose the desired Title text Font. Color box By clicking on this button, the Color Editor dialog will be displayed, in which you can choose the desired Title text color. Outline By clicking on this button, the Border Editor dialog will be displayed, in which you can define the Outline/border style for the Title text. Inter-char spacing This property allows you to define the number of spaces from character to character in the Title text. Shadow Color By clicking on this button, the Color Editor dialog will be displayed, in which you can define the Title text shadow color. Horizontal and Vertical size This property sets the Title text size. The Gradient tab Visible This property shows or hides the Title gradient fill. Direction The Direction property specifies the direction the Title gradient fill will be applied. Colors By clicking on any of the following buttons: Start, End and Middle, the Color Editor dialog will be displayed, in which you can define the desired color for each. 232 Portrait Dialogue 6.0

233 Chapter 8: Reports The Swap property exchanges the Start and End colors. No Middle It controls whether the gradient fill Middle color will be displayed or not. The Shadow tab Color By clicking on this button, the Color Editor dialog will be displayed, in which you can define the shadow Color. Size It sets the Shadow thickness. The Legend tab This tab defines the chart legend. The legend is visible by default. The Legend tab is divided into several tabbed pages: The Style tab Visible This property shows or hides the Chart Legend. Inverted This property shows or hides the Legend items in the opposite direction. Check Boxes This property enables/disables the display of Legend check boxes for each Series. Font Series Color Set this property to determine whether or not the color of the font of the Legend text is the same as the Series color. Legend Style This property defines the Legend style. Text Style This property defines the Legend Text style: Plain, Left value, Right value, etc. Vertical Spacing This property determines the vertical spacing between Legend items (pixels). Dividing Lines This property specifies lines separating Legend items. The Position tab Position This property sets the Chart Legend position. Resize Chart This property indicates whether Legend will automatically reduce the Chart rectangle to prevent overlapping of Legend and Chart rectangles. Margin This property determines the number of screen pixels between Legend and Chart rectangles. Position Offset This property indicates the displacement as a percentage depending on the Legend position. Custom This property allows you to customize the Legend position in the Chart panel. The Symbols tab Width This property determines the Legend Symbols Width. Width Units It defines the Width of Symbols as a percentage or in pixels Position This property sets the Symbols and Units position respectively in the Legend. Continuous This property lets the different legend color rectangles flow into each other. The color rectangles of the different items are drawn attached to each other (no vertical spacing). The Format tab Color By clicking on this button, a Color Editor dialog will be displayed where you can select the Legend Label color. Visual Dialogue User Guide 233

234 Layout View in Report Designer Pattern By clicking on this button, a Pattern Editor dialog will be displayed where you can define the Legend Pattern style. Transparent This property sets the Legend BackColor transparent. Transparency This property sets the Title Label BackColor transparency. The Border tab Bevel This property defines the Legend Bevel: Lowered, Raised or None. Color By clicking on this button, a Color Editor dialog will be displayed where you can select the Legend Label color. Frame By clicking on this button, a Border Editor dialog will be displayed where you can define the Legend border/frame. Size This property sets the Legend bevel size. Round Frame This property sets the Legend Rounded Frame. Size This property sets the Title Round Frame size. The Text tab Font By clicking on this button, a Font Editor dialog will be displayed where you can select the Legend text Font. Color Box By clicking on this button, a Color Editor dialog will be displayed where you can select the Legend font color. Outline By clicking on this button, a Border Editor will be displayed where you can define the Legend Border Outline. Inter-char spacing This property allows you to define the number of spaces from character to character in the Legend text. Shadow Color By clicking on this button, a Color Editor dialog will be displayed where you can define the Legend text shadow color. Horizontal and Vertical size This property sets the Legend text size. The Gradient tab Visible This property shows or hides the Legend gradient fill. Direction This property sets the Legend gradient fill direction. Colors By clicking on any of the following buttons: Start, End, Middle, a Color Editor dialog will be displayed where you can select the desired color for each. The Swap?property exchanges the Start and End colors. No Middle This property controls whether the Middle color of the Legend gradient fill will be displayed or not. The Shadow tab Color By clicking on this button, a Color Editor dialog will be displayed where you can select the Legend shadow color. Size This property sets the Legend shadow thickness. The Panel tab This tab defines the Chart Panel properties. 234 Portrait Dialogue 6.0

235 Chapter 8: Reports The Panel tab is divided into several subtabs: The Background tab Panel Color By clicking on this button, a Color Editor dialog will be displayed, enabling you to select the Chart Panel color. Back Image By clicking on the Browse button, a dialog box will be displayed, enabling you to select an image from your computer files to be displayed on the Chart Panel. The Inside property defines the image inside the Chart. The Transparent property makes the image background transparent. The Style property adjusts the image to the Chart size. The Borders tab Bevel Inner / Width This property sets the Inner Chart Panel bevel: Lowered, Raised, or None. Bevel Outer / Width This property sets the Outer Chart Panel bevel: Lowered, Raised, or None. Border This property shows or hides the Chart Panel border. The Gradient tab Visible This property determines whether or not the Chart Panel gradient fill will be displayed. Direction This property sets the direction of the Chart Panel gradient fill. Colors By clicking on Start, End, or Middle, the Color Editor dialog will be displayed, enabling you to select the desired color for each. Swap exchanges the Start and End colors. No Middle This property controls whether the Middle color of the Chart Panel gradient fill will be displayed, or not. The Paging tab The Paging tab defines the number of points per Chart page. Points per page It sets the number of points per chart page. Scale Last Page This property controls how the last Chart page will be displayed. When it is activated, the last Chart page will have the same horizontal scaling as the other pages. When not, the last Chart page scaling will be adjusted based on the number of visible points on that last page. Current page Legend This property determines whether or not the Legend only shows the current page items when the Chart is divided into pages. Page 1 of 1 This property determines whether or not the page number is displayed on the Panel. The Walls tab The Walls tab contains the properties/methods for TeeChart left, bottom, and back walls. The Walls tab contains several subtabs and properties: Visible Walls This property shows or hides the Chart Walls. Left, Right, Bottom and Back Tabs Each of these tabs contains the following properties: Color By clicking on this button, a Color Editor dialog will be displayed where you can define the Wall color. Visual Dialogue User Guide 235

236 Layout View in Report Designer Border By clicking on this button, a Border Editor dialog will be displayed where you can define the Wall Border. Pattern By clicking on this button, a Pattern Editor dialog will be displayed where you can define the Wall Pattern style. Gradient By clicking on this button, a Gradient Editor dialog will be displayed where you can define the Wall gradient fill. Visible This property controls whether the Wall selected will be displayed or not. Dark 3D This property colors the 3D Depth area of a wall a darker shade than the rest of it. Size This property defines the Wall thickness/size. Transparent This property controls whether the Wall color or gradient will be displayed or not. The 3D tab This tab contains the properties to define the objects in 3D. 3 Dimensions This property controls whether the Chart will be displayed in 3D or not. The D defines the 3D percentage. Orthogonal This property sets the Chart orthogonally. The Angle defines the angle it will be displayed at. Zoom Text This property controls the Text size when 3D. Zoom This property controls the Chart size. Rotation The Rotation property is supported when a Chart is in 3D, but not for Orthogonal Charts. It enables the Chart to be rotated through a full 360. Elevation The Elevation property is supported when a Chart is in 3D, but not for Orthogonal Charts. It enables the Chart to be rotated vertically through a full 360. Horizontal and Vertical Offset This property moves the Chart on a Horizontal or Vertical plane. Perspective The Perspective property is supported when a Chart is in 3D, but not for Orthogonal Charts. It offers a distance adjustment for the Chart displayed, giving the appearance of perspective between the nearest and furthest parts of the Chart. Series types Adding and setting up series Adding and setting up series is the most commonly, and often one of the first tasks you do when configuring a chart component. In the Edit Chart window, open the page Chart > Series, and click Add to add a series. The TeeChart Gallery window opens. The TeeChart Gallery is a visual catalogue of all the available chart types within the Chart component. Every time a Series is added, a chart type can be chosen. The Gallery consists of two tabbed pages at the top level: Series and Functions. The Series tab The Series tab includes the subtabs for all chart types available. 236 Portrait Dialogue 6.0

237 Chapter 8: Reports The existing series types are: Line Bar Horizontal bar Area Point Pie Fast line Bubble Arrow Gantt Shape The Functions tab In this tab you will find subtabs related to function series types. The existing function series are: Add Subtract Multiply Divide High Low Average y = f(x) Median Mode The Formula component The Formula component With this component, it is possible to use formulas using the datasource s data fields. Using the Formula component Right-click on the component in the canvas and choose Formula to state the formula in the Formula Definition window. The window is divided into two sections: The Formula pane The formula statement The object toolbox The object toolbox provides easy access to commonly used objects and formula functions. The toolbox contains three tabs: 1. The Datasources and fields tab This tab lists all parameters and fields in all datasources defined in the report. Double-click on a field to use it in the formula definition. Visual Dialogue User Guide 237

238 Layout View in Report Designer 2. The Report Objects tab This tab provides a hierarchical overview and quick access to all objects and components used in a report. Double-click on an object to use it in the formula definition. 3. The Functions tab This tab provides a wide range of type-conversion, date, string, and mathematical functions. Double-click on a function to use it in the formula definition. Formatting the output value To format the components numeric output value, right-click on the component in the canvas and choose DisplayFormat. The Format window opens. Then select the desired format from the list. The display format will then be formatted according to the selected format syntax. It is also possible to enter a custom format, or change a selected format by editing its syntax. Working with dates in the Formula component Right-click on the component in the canvas and choose Formula to open the Formula Definition window. Then choose Date, time functions in the Functions section. Working with dates The following date/time functions are available under Date, time functions: Year(s) Returns a whole number representing the year. Month(s) Returns a whole number between 1 and 12, inclusive, representing the month of the year. Day(s) Returns a whole number between 1 and 31, inclusive, representing the day of the month. WeekDay(s) Returns a whole number representing the day of the week. Hour(s) Returns a whole number between 0 and 23, inclusive, representing the hour of the day. Minute(s) Returns a whole number between 0 and 59, inclusive, representing the minute of the hour. Sec(s) Returns a whole number between 0 and 59, inclusive, representing the second of the minute. StrToStamp(d) - Returns the stamp (the number of days since December 31, 1899) representation of the date specified in the argument. LastDay(x) - Returns the last day of the month in the date specified by the stamp value in the argument. StampToStr(x) Adds a number of days (specified by the argument) to the date December 31, 1899 and returns the calculated date and time. StampToDateStr(x) Adds a number of days (specified by the argument) to the date December 31, 1899 and returns the calculated date. StampToTimeStr(x) Adds a number of days (specified by the argument) to the date December 31, 1899 and returns the calculated time. _NOW Returns the current date and time according to the setting of your computer s system date and time. _TIME Returns the current time according to the setting of your computer s system date and time. _DATE Returns the current date according to the setting of your computer s system date and time. Working with strings in the Formula component Right-click on the component in the canvas and choose Formula to open the Formula definition window. Then choose String operations in the Functions section. 238 Portrait Dialogue 6.0

239 Chapter 8: Reports Concatenating strings To concatenate two strings, use the pipe ( ), as shown in the image above. String functions The following string functions are available under String operations: Length(s) Returns the length of the supplied string. Pos(t, s) Return the position of the first argument(string) in the second argument(string). Trim(s) Returns a string containing a copy of a specified string with no leading or trailing spaces. TrimLeft(s) Returns a string containing a copy of a specified string with no leading spaces. TrimRight(s) Returns a string containing a copy of a specified string with no trailing spaces. Upper(s) Returns a string or character containing the specified string converted to uppercase. Lower(s) Returns a string or character containing the specified string converted to lowercase. Copy(s, x, [y]) Returns the substring of the first argument, starting at the position specified in the second argument and ending at the position specified in the third argument. CopyTo(s, x, [y]) Returns the substring of the first argument, starting at the position specified in the second argument and ending at the position specified in the third argument. Delete(s, x, [y]) Returns the substring of the first argument, after deleting a portion of the string starting at the position specified in the second argument and ending at the position specified in the third argument. Insert(s, t, x) Returns the first argument (string), after inserting a the string specified by the second argument at the location specified by the third argument. Replace(s, t, v, [1/0=ReplaceAll, 1/0=IgnoreCase]) Returns the first argument (string), after replacing the string specified by the second argument with the string specified by the third argument. IFF(a, s, t) If the first argument (integer) is larger than 0, the second argument (string) is returned, else the third argument is returned. Prefix(count, char, s) Returns a copy of the string specified by the third argument, prefixed with the character specified by the second argument, resulting in a string with a (minimum) total length of the integer specified by the first argument. The toolbars The toolbars This section describes the toolbars available when designing reports and their basic functions. Toolbars are used to set the properties of a component. The different toolbars available are dependent of the component selected in the canvas. To display or hide toolbars, right-click in the toolbar area and select or deselect the desired toolbars. The different toolbars are: The nudge toolbar The size toolbar The draw toolbar The align toolbar Visual Dialogue User Guide 239

240 The toolbars The format toolbar The nudge toolbar This toolbar is useful when you want to move a component or selection of components with extreme precision. Each icon represents the direction the selection will move. Button Nudge all selected components up by one pixel. Nudge all selected components down by one pixel. Nudge all selected components left by one pixel. Nudge all selected components right by one pixel. The size toolbar You can use this toolbar to set all of the components within a selection to a uniform height or width. Button Set the width of the selected components to the width of the narrowest. Set the width of the selected components to the width of the widest. Set the height of the selected components to the height of the shortest. Set the height of the selected components to the height of the tallest. The draw toolbar This toolbar is used to set the color and style used by line, shape, and region components. Button Set the fill color of a shape or region. Set the color of a line, or the border color of a shape or region. Set the thickness of a line. Set the style of a line. 240 Portrait Dialogue 6.0

241 Chapter 8: Reports The align toolbar This toolbar is useful when components need to be positioned uniformly. For example, it can align several components so that the tops are all even, or it can space components so that they have an equal amount of space between them. The first component selected determines the position to which the others will align. Button Horizontally align a group of components with the leftmost edge of the first-selected component. Horizontally center a group of components on the center of the first-selected component. Horizontally align a group of components with the rightmost edge of the first-selected component. Vertically align a group of components with the topmost edge of the first-selected component. Vertically center a group of components on the center of the first-selected component. Vertically align a group of components with the bottom-most edge of the first-selected component. Horizontally distribute a set of components between the leftmost edge of the first-selected component and the rightmost edge of the last-selected component. Vertically distribute a set of components between the topmost edge of the first-selected component and the bottom-most edge of the last-selected component. Horizontally center a component within a band. Vertically center a component within a band. The format toolbar The format toolbar works just like the format toolbar in other Windows applications, and enables you to change text attributes such as font details, text color, and justification, as well as controlling whether objects appear in front of or behind overlapping objects. Using subreports Subreports are inline reports in a report (master report). The subreport will run each time the band in the master report is rendered. It is common to use sub-datasources for subreports. This makes it possible to design subreports that iterates a set of data for each iteration in the master report. Subreports are design in the same way as standard reports, using the toolbox and toolbars available. Visual Dialogue User Guide 241

242 Preview View Inserting subreports Use the SubReport component from the toolbox to insert a subreport into the report. To set the datasource used by the subreport, select the component in the canvas and select the datasource in the Field dropdown list above the canvas. Subreports can be inserted in any of the master report s bands. The subreport inserted into the master report is visible as a tabbed page below the layout canvas. To design and work with the subreport, click on the subreport s tab. Preview View About Preview View Preview View enables you to preview a report. It is divided into two areas: the Preview overview frame and the Preview frame. The Preview overview frame The Preview overview frame provides a simple overview of the generated report s pages. Only the first page of the report is loaded by default. The overview is updated when browsing through the report s pages. The Preview frame The Preview frame previews the current report page. See Previewing the report on page 242 for details. Previewing the report When you open the Preview View, the report is generated using the report test options given in Test options on page 219 and Testing datasources on page 218. The preview frame previews the current report page. The page number preview is displayed in the preview toolbar. For details about printing the report, see Printing the report on page 242. Printing the report To print the previewed report, choose Print from the Preview ribbon tab. The Print dialog opens, with the standard printing options, in addition to the Print to File option. Printing the report to file You can print the report either to a printer or to a file. 242 Portrait Dialogue 6.0

243 Chapter 8: Reports To print the report to a file: 1. Select Print to file. 2. Select the file type from the Type drop-down list. For a detailed list over the different formats available, see Report formats on page Enter the report s filename and location in the Where textbox. Click on the button to the right of the textbox to browse for the filename and location. Viewing a report in Report Portal To view a report in Report Portal, choose In Report Portal from the Preview ribbon tab. The report opens, and the Run page is displayed in the Report Portal. If the report has parameters, set these, then select the desired format and click on Run. The report is then generated and displayed. For more information on Report Portal, see Report Portal on page 245. Browsing reports Browsing reports To see all reports defined, choose Explore > Report Templates from the Home tab in Visual Dialogue. The Browse Reports frame is displayed. Sorting the report list To sort selections, click on the desired column in the heading of the selection list. Selecting columns To configure the set of columns displayed in the list, choose Select Columns from the View tab. The Select Columns window opens. The columns can also be rearranged by dragging and dropping them to different column positions. Report properties To review or edit the properties (e.g. the name or the description of the report), select a single report and choose Properties from the Home tab. See Report template properties on page 214 for full details of the properties available. Opening a report To open a report in Report Designer, double-click on a single report in the list or choose Open from the Home tab. Visual Dialogue User Guide 243

244 Report security Deleting a report To delete a report, mark a single report and choose Delete from the Home tab. Report security The report module has built in security functionality. This allows controlling the report templates s access rights and permissions. The security settings are applied at the user and user group level. The security settings window To open the security settings window for a report, do one of the following: Right-click on the desired report in the Report Browser and select Security. Open a report template and click the padlock button in the File ribbon tab: The report template security setting window opens. The User group or user window lists all users and user groups with any access rights or permissions on the report template. Select one user or user group to see its permissions. The permissions are listed below in the Access right or permission window. Disabled permissions (gray) are global permissions and thus cannot be changed or deleted. Adding users and user groups Click on Add to add a user or user group. The Select Groups or Users window opens. Select the desired user or user group and click on OK. The selected user or group is added to the User group or user list in the security window. Then select the desired permissions and access rights for the user or user group. Access rights and permissions The access rights and permissions available per user and user group are: Edit report template Permission to edit the report template in the report designer Run report Permission to run (generate) the report in Report Portal View archived reports Access to the report s archive in Report Portal Save reports to archive Permission to save generated reports to its archive in Report Portal Delete reports from archive Permission to delete reports from the report s archive in Report Portal 244 Portrait Dialogue 6.0

245 Chapter 8: Reports Report formats A number of different formats are available when displaying and saving reports. Report formats overview The table below defines the different formats available. Format Index Adobe Acrobat PDF-files. HTML with page breaks HTML one page XHTML Rich Text Format Microsoft Excel Single page JPEG image format GIF image format BITMAP image format Window Metafile Enhanced Windows Metafile Microsoft Excel Multi page Output files One PDF file is generated. One HTML file per page is generated. Pictures and charts are returned as JPG files. One HTML file containing all pages is generated. Pictures and charts are returned as JPG files. One XHTML file per page is generated. Pictures and charts are returned as JPG files. One RTF file is generated. One Excel sheet is generated. Does not include graphics. One JPG file per page is generated. One GIF file per page is generated. One BMP file per page is generated. One WMF file per page is generated. One EMF file per page is generated. One Excel sheet per report page is generated. Includes graphics (e.g. images). Graphs will be included as images. Report Portal The Report Portal application provides you with an intuitive work environment that makes it easy to run report templates and view archived reports. For example, you might use Report Portal to: Run report templates Save reports to the report s archive Visual Dialogue User Guide 245

246 Integrated reporting View archived versions of a report For details, see Report Portal s own help file. Integrated reporting Integrated reporting overview Integrated reporting is functionality for running reports in context of different system objects and modules. Reports set up with integrated reporting will thus be available in applicable locations in Visual Dialogue, Customer View and Telemarketing Web. Creating new reports for integrated reporting A report using integrated reporting is related to a system report type. To create a report with integrated reporting support: 1. Create and design the report using report designer. See Creating a new report template on page 213 for details. 2. If the system report type requires a parameter (e.g. a Dialog Report), add the report parameter, open the Advanced tab in parameter properties, and select the System parameter type. See Defining and binding parameters on page 217 for details. 3. Open the report template s properties, and select the Advanced tab. Check Relate to a system report type. 4. Select the system report type. The report types available are: Content object report Customer report Dialog group report Dialog operation report Dialog report message bundle report template report Global report for content objects Global report for dialogs Global report for messages Global report for questionnaires Message bundle report Message template report Participant report Questionnaire report Telemarketing project report 246 Portrait Dialogue 6.0

247 Chapter 8: Reports Integrated reporting system settings The behaviour of integrated reporting can be controlled with system options: Choose Options > Integrated Reporting to edit the settings. Enable integrated reporting Enables all integrated reports. Launch Report Portal Select this option to run integrated reports in Report Portal. Open reports inside Visual Dialogue Select this option to run integrated reports inside Visual Dialogue. Open in new window Select this option to open integrated reports inside Visual Dialogue in a new window. Report view format The output format used when running the reports. For a detailed list over the different formats available, see Report formats on page 245. Standard reports A set of Standard Reports is installed using Integrated Reporting. See Standard reports on page 247 for details. Standard reports Visual Dialogue is installed with a set of standard reports. Standard reports are related to a system module and are available from the system menus. The standard reports installed are: MH Bounced Report : Displays sent and bounced (not deliverable) statistics per template. Accessibility: Message Template Browser and dialog operations using an HTML template. MH Bundle Bounced Report : Displays sent and bounced (not deliverable) statistics per message bundle. Accessibility: Message Manager. MH Content Object Report : Displays information about a content object and its execution statistics. Accessibility: Content Object Browser. MH Dialog Cost and Income Report : Displays cost and income calculations for all operations in a dialog having specified cost and/or income, including total summations. Accessibility: Dialog Browser and Dialog Designer execute view. MH Dialog Execution Report : Displays statistics and key execution information for all groups and branches in a dialog. Accessibility: Dialog Browser and Dialog Designer execute view. MH Dialog Group Report Visual Dialogue User Guide 247

248 Standard reports : Displays a group s key properties and execution statistics, including graphs showing participants movement. Accessibility: Groups in Dialog Designer execute view. MH Dialog Operation Report : Displays execute settings, key properties and statistics for an operation. Accessibility: Operations in Dialog Designer execute view. MH Dialog Specifications Report : Displays key dialog properties and lists of all groups, operations and branches in a dialog. Accessibility: Dialog Browser and Dialog Designer execute view. MH Dialogs Overview Report : Lists key properties and figures for all dialogs in Visual Dialogue. The lists are grouped into active dialogs, not active dialogs and dialogs having automated operations. Accessibility: Dialog Browser. MH Tracking Report - Displays statistics. This includes and link tracking, as well as and send and bounce rates. Browser statistics for and link tracking is included. Accessibility: Message Browser and Operations using an HTML message template. MH Tracking Report - General : Displays message statistics, including link tracking, send rates and error rates. Browser statistics link tracking is included. Accessibility: Message Browser and Operations using an HTML message template. MH Message Report : Displays key properties, number of messages sent and graphs displaying messages sent by day. Accessibility: Message Browser and Operations using a message template. MH Questionnaire Report : Displays questionnaire properties, answer form statistics and statistics per question. This report only includes complete answer forms. Accessibility: Questionnaire Browser and Operations using a questionnaire. MH Questionnaire Report (including incomplete) : Displays questionnaire properties, answer form statistics and statistics per question. This report is the same as MH Questionnaire Reportbut it also includes incomplete answer forms. Accessibility: Questionnaire Browser and Operations using a questionnaire. MH Telemarketing Report : Displays telemarketing project properties, queued participants figures, processed participants statistics, call statistics per operator, location of successful participants by group and by group per operator. 248 Portrait Dialogue 6.0

249 Chapter 8: Reports Accessibility: Execute view in Dialog Designer. MH Response Tacking Report : Displays questionnaire information, response statistics and browser statistics. Accessibility: Questionnaire Browser and Operations using a questionnaire. Customizing standard reports You can customize the standard reports installed with Visual Dialogue. Customizing the standard reports To customize a standard report, open the report in Report Designer, perform the desired changes, and save the report. See About Report Designer on page 213 for details on working with Report Designer. Note: When you are customizing a standard report, you are recommended to rename or save a copy of the report. Otherwise, your changes could be lost in future system upgrades. Standard report SQL statements The standard reports installed with Visual Dialogue have been written to support both Microsoft SQL Server and Oracle RDBMS. If you want to customize standard reports at your site, multiple-platform support should not be of any concern to you, but understanding the mechanism we use to support multiple database platforms might help you if you want to change any of the SQL statements used. SQL statement tags Multiple database platforms are supported by the use of special tags. A tag is composed of a set of curly brackets with a tag name and possibly one or more parameters within: {Tagname parameter1 parameter2}. The tag name and parameters are separated by spaces. Common tags TIMESTAMP Parameters: : SQL Server implementation: Oracle implementation: N/A Returns the current date and time. CURRENT_TIMESTAMP SYSDATE TODAY Parameters: : N/A Returns the current date with a time of midnight. Visual Dialogue User Guide 249

250 Standard report SQL statements SQL Server implementation: Oracle implementation: cast(floor(cast(current_timestamp as float)) as datetime) trunc(sysdate) DATEPART Parameters: : SQL Server implementation: Oracle implementation: DatetimeValue Returns the DatetimeValue parameter with a time of midnight. cast(floor(cast(datetimevalue as float)) as datetime) trunc(datetimevalue) TIMEDIFF_HOUR Parameters: : SQL Server implementation: Oracle implementation: StartDatetime, EndDatetime Returns the number of hours between StartDatetime and EndDatetime rounded downwards. If StartDatetime is later than EndDatetime a negative value is returned. datediff(hh, StartDatetime, EndDatetime) trunc((enddatetime - StartDatetime) * 24) TIMEDIFF_MIN Parameters: : SQL Server implementation: Oracle implementation: StartDatetime, EndDatetime Returns the number of minutes between StartDatetime and EndDatetime rounded downwards. If StartDatetime is later than EndDatetime a negative value is returned. datediff(mi, StartDatetime, EndDatetime) trunc((enddatetime - StartDatetime) * 24*60) TIMEDIFF_SEC Parameters: : SQL Server implementation: StartDatetime, EndDatetime Returns the number of s between StartDatetime and EndDatetime rounded downwards. If StartDatetime is later than EndDatetime a negative value is returned. datediff(ss, StartDatetime, EndDatetime) 250 Portrait Dialogue 6.0

251 Chapter 8: Reports Oracle implementation: trunc((enddatetime - StartDatetime) * 24*60*60) YEAR Parameters: : SQL Server implementation: Oracle implementation: DatetimeValue Returns the year of DatetimeValue. year(datetimevalue) extract(year from DatetimeValue) MONTH Parameters: : SQL Server implementation: Oracle implementation: DatetimeValue Returns the month of DatetimeValue. month(datetimevalue) extract(month from DatetimeValue) DAY Parameters: : SQL Server implementation: Oracle implementation: DatetimeValue Returns the day of DatetimeValue. day(datetimevalue) extract(day from DatetimeValue) AGE Parameters: : DatetimeValue Calculates and returns the number of years since DatetimeValue. Visual Dialogue User Guide 251

252 Standard report SQL statements SQL Server implementation: Year(getdate()) - Year(DatetimeValue) - case when Month(getdate()) < Month(DatetimeValue) then 1 when (Month(getdate()) = Month(DatetimeValue )) and (Day(getdate()) < Day(DatetimeValue )) then 1 else 0 end Oracle implementation: extract(year from current_date) - extract(year from (DatetimeValue)) - decode( Sign(extract(month from current_date) - extract(month from (DatetimeValue))), -1, 1, 0, decode(sign(extract(day from current_date) - extract(day from (DatetimeValue))), -1, 1, 0), 0) DAY_OF_WEEK Parameters: : SQL Server implementation: Oracle implementation: DatetimeValue Returns the day of the week from DatetimeValue. The result is always an integer between 1 and 7, but what day is considered the first day of the week is determined by your database. datepart(dw, DatetimeValue) to_number(to_char(datetimevalue, 'd')) ADD_MONTHS Parameters: : SQL Server implementation: DatetimeValue, IntegerValue Returns DatetimeValue with IntegerValue months added to it. dateadd(mm, IntegerValue, DatetimeValue) 252 Portrait Dialogue 6.0

253 Chapter 8: Reports Oracle implementation: add_months(datetimevalue, IntegerValue) UPPER Parameters: : SQL Server implementation: Oracle implementation: StringValue Returns StringValue with lowercase character data converted to uppercase. upper(stringvalue) upper(stringvalue) LOWER Parameters: : SQL Server implementation: Oracle implementation: StringValue Returns StringValue after converting uppercase character data to lowercase. lower(stringvalue) lower(stringvalue) LENGTH Parameters: : SQL Server implementation: Oracle implementation: StringValue Returns the number of characters of StringValue. len(stringvalue) length(stringvalue) STR_CONCAT Parameters: : SQL Server implementation: Oracle implementation: N/A Concatenates two strings. + ISNULL Parameters: : SQL Server implementation: Oracle implementation: Value, Replacement Returns Replacement if Value evaluates to null, otherwise Value is returned. isnull(value, Replacement) nvl(value, Replacement) Visual Dialogue User Guide 253

254 Standard report SQL statements CAST Parameters: : SQL Server implementation: Oracle implementation: Datatype, Value Casts Value to the given Datatype. The supported data types are string, float, integer and datetime. cast(value as Datatype) to_char(value), to_number(value) or to_date(value) ORDER_NULL_FIRST Parameters: : SQL Server implementation: Oracle implementation: N/A Returns an order clause which orders null values first. asc desc ORDER_NULL_LAST Parameters: : SQL Server implementation: Oracle implementation: N/A Returns an order clause which orders null values last. desc asc EMPTY_FROM_CLAUSE Parameters: : N/A Returns a FROM clause that can be used when you do not want to select from any database objects. SQL Server implementation: Oracle implementation: from dual MSSQL_TOP Parameters: : SQL Server implementation: StringValue Returns a TOP keyword on SQL Server TOP StringValue Oracle implementation: 254 Portrait Dialogue 6.0

255 Chapter 8: Reports MSSQL_NOLOCK Parameters: : SQL Server implementation: N/A Returns a NOLOCK table-level locking hint on SQL Server. with (NOLOCK) Oracle implementation: MSSQL_TABLOCKX Parameters: : SQL Server implementation: N/A Returns a TABLOCKX table-level locking hint on SQL Server. with (TABLOCKX) Oracle implementation: ORACLE_ALL_ROWS Parameters: : N/A Returns an ALL_ROWS optimizer hint on Oracle. SQL Server implementation: Oracle implementation: /*+ ALL_ROWS */ ORACLE_FIRST_ROWS Parameters: : N/A Returns an FIRST_ROWS optimizer hint on Oracle. SQL Server implementation: Oracle implementation: /*+ FIRST_ROWS */ ORACLE_ONLY Parameters: : Statement Returns the statement specified on the Oracle platform only. SQL Server implementation: Oracle implementation: Statement MSSQL_ONLY Visual Dialogue User Guide 255

256 Standard report SQL statements Parameters: : SQL Server implementation: Statement Returns the statement specified on the Microsoft SQL Server platform only. Statement Oracle implementation: 256 Portrait Dialogue 6.0

257 Task Organizer 9 In this section: About Task Organizer Workgroups Workgroup users Manual distribution Automatic distribution Deleting workgroups and users

258 About Task Organizer About Task Organizer Task Organizer is a tool inside Visual Dialogue used to distribute tasks to users and groups. Concepts Tasks are created either by running a Create task operation in a dialog, or manually in Customer View. With Task Organizer, you can distribute tasks to task workgroups and users. This can be done manually, automatically, or using a mixture of the two methods. The Task Organizer interface To open Task Organizer, choose Explore > Task Organizer from the Home tab in Visual Dialogue. The Task Organizer interface has two main panels. The left panel gives you an overview of all your workgroups and users. The right panel gives you a list of all tasks assigned to the workgroup or user selected in the left panel. You can also get a summary of tasks assigned to the selected workgroup or user in the left pane if you select the Summary tab. Note: If you find that changing between the different users and workgroups in the left pane is slow, try turning off Show customer data in list of tasks. See Visual Dialogue options on page 19. Workgroups Workgroups divide your users into different groups. This way you can assign tasks to a workgroup and later decide which user should handle the task. Workgroups can represent company branches, departments or any other logical segmentation you want to use. Adding a workgroup To add a workgroup, choose Add from the Organize ribbon tab, or right-click in the left pane and choose Add work group. Fill in the properties of the new group and click on OK. Workgroup properties Workgroup name Responsible Allowed activity types The name of the workgroup An optional description of the workgroup The user responsible for the workgroup. Note that this user is not a member of the group if you do not add him or her explicitly. Here you can set which allowed activity types should be default when you add a new users to the group. 258 Portrait Dialogue 6.0

259 Chapter 9: Task Organizer Default auto distribute weighting Here you can set what weighting value should be the default when you add a new users to the group. Workgroup users A workgroup user is a user as defined by your system administrator in Dialogue Admin. They become workgroup members when you add them to one of your workgroups. Your users do not have to be member of a workgroup to have tasks assigned to them, but they must be if you want to use the auto distribute feature. A user can be member of only one workgroup. Adding a user to a workgroup To add a user to a workgroup, select the workgroup you want to add the user to, then choose Add Users from the Organize ribbon tab, or right-click on the workgroup and choose Add user(s) to group. In the Select New Group Members window, choose one or more users from the list and click on OK to add them to the group. Note: Users already assigned to other workgroups are also listed. This lets you move a user from one group to another. User properties User properties are only available for users who are members of a workgroup. This is because all the user properties have to do with automatic distribution of tasks. User Member of workgroup Temporary do not assign tasks to user Allowed activity types Auto distribute weighting The name of the user as defined. The name of the workgroup this user is a member of. A user can be a member of only one workgroup. Check this if you do not want tasks to be assigned to the user when using automatic distribution. This can be overridden when you start the automatic distribution and you can also assign tasks manually to the user regardless of this setting. Here you can set which activity types you want the user to be assigned when you use automatic distribution. You can set the automatic distribution to disregard this setting when you start it and you can manually assign tasks to the user regardless of this setting. Here you can define how automatically distributed tasks are divided between workgroup users. A user with weighting 2 will get twice as many tasks as a user with weighting 1, and a user with weighting 3 will get three times as many as a user with weighting 1. You can set the automatic distribution to disregard this setting when you start it, and you can manually assign tasks to the user regardless of this setting. Visual Dialogue User Guide 259

260 Manual distribution Manual distribution You can manually distribute tasks to all users, regardless of if they are assigned to a workgroup or not. You can also manually distribute tasks to workgroups. To manually distribute tasks, select the tasks you want to work with in the right pane and either rightclick with your mouse, which will present you with a number of options, or choose an option from the Organize ribbon tab. Assign task(s) to user Assign task(s) to work group Auto distribute tasks Return task(s) to work group Unassign task(s) Open in Customer View Delete Assign the selected tasks to a user. Assign the selected tasks to a workgroup. Use automatic distribution to distribute the selected tasks. Unassign the selected tasks from a user but keep them assigned to a workgroup. This is only available for tasks that have been assigned to a user that is member of a workgroup. Unassign the selected tasks from both the user and the workgroup they are assigned to. Open the selected task in Customer View. This can only be done if a single task is selected. Delete the selected tasks. It is also possible to distribute tasks manually using drag and drop. Automatic distribution Automatic distribution lets you distribute tasks between users in a workgroup based on different preferences you can set for each user. To initiate automatic distribution of tasks, select the tasks you want to distribute in the right pane. Then choose Auto Distribute from the Organize ribbon tab, or right-click on the tasks and choose Auto distribute tasks. The Auto Distribute Tasks window opens. Select the workgroup you want to distribute the tasks to. Select the distribute options you want to use. Use weighting will make the distribution take into account the weighting of each group member. A group member with weighting 2 will get twice as many tasks as a group member with weighting 1. If you are not using weighting, the task distribution will try to evenly distribute the tasks between the workgroup users. Use allowed activity types will onlyassign tasks to users based on their allowed activity types. Use total task count will make the distribution try to distribute tasks among the users based on total amount of tasks assigned to each user after the distribution is done. 260 Portrait Dialogue 6.0

261 Chapter 9: Task Organizer Select the users you want to distribute the tasks to. Users that are marked as Temporary do not assign tasks to user are not selected by default, but you can select them if you want to. When you are satisfied with the setup, you can click on Preview to see how the tasks will be distributed. Click on OK to distribute the tasks and close the window. Deleting workgroups and users To delete workgroups or members of a workgroup, select them in the left pane and choose Delete from the right-click menu, or press Delete. If you delete a workgroup, tasks assigned to members of the group will still be assigned to the users. The users themselves are moved to <Users outside work group>. Tasks assigned only to the group will be unassigned. If you delete a user from a workgroup, the members will be moved to <Users outside work group>. The tasks assigned to this user will still be assigned to him or her, but will unassigned from the workgroup. Visual Dialogue User Guide 261

262

263 Broadcasts 10 In this section: About broadcasts

264 About broadcasts About broadcasts Broadcasts are used to track the origins of customer activities and survey responses. Typical examples of broadcasts are ads in magazines and papers, ads on web sites, and fliers. Broadcast properties Name: The name of the broadcast. Publishing channel: The channel used to publish this broadcast. Published date: The date the broadcast was published. Related document: An optional path to a document related to the broadcast, for instance, the document used as a basis for a magazine add. Active: This checkbox controls whether the broadcast is available for selection when you create a new customer activity or a link to a questionnaire. Clear the checkbox when the broadcast is no longer in use. 264 Portrait Dialogue 6.0

265 Published files 11 In this section: About published files

266 About published files About published files A published file is a file that is stored by and available through the Dialogue Server. Published files are accessible on the web through specially constructed URLs and can be used in any web page. In Visual Dialogue they are used in HTML templates and Questionnaire styles. Managing published files You can manage published files through the Published Files Manager. To sort the files in the list, click on the desired column in the heading. To configure the set of columns displayed in the list, choose Select Columns from the View ribbon tab. You can use the right-click menu to perform a number of actions (and these actions are also available from the Home ribbon tab). New... Open Delete Properties Update content... Build URL to file... Copy Content ID to Clipboard Export content to disk Export... Import... Show preview Select Columns Create a new published file by opening a file from one of your disk drives. Open the selected published file in the program associated with the file extension. Delete a published file. Show the properties for the selected published file. Here you can alter the name and the description of the published file. Update the content of the published file by replacing the current content by another file from one of your disk drives. This can be very handy if you for instance want to change a logo you have used in your message templates. Create a URL that can be used in an HTML document to access the published file. The URL can be copied to the clipboard and pasted directly into your HTML document. Copy the selected published file s Content ID to the clipboard. Each published is identified by a Content ID which is a 32 character long string. Copy the content of the selected published file to one of your disk drives. Launches the Visual Dialogue Export Wizard which lets you export Visual Dialogue objects (e.g. one or more published files) to files. Launches the Visual Dialogue Import Wizard which lets you import Visual Dialogue objects from files. Turn the preview in the bottom of the window on or off. Configure the set of columns displayed in the list. Note: Deleting a published file, or updating its content, might affect s already created and sent. For instance, if an links to a picture (a published file), then the picture will become unavailable if it is deleted. If an embeds a picture and the file is deleted, then the receiver will still have the picture, but viewing the in Message Manager will fail (the picture will not be dis- 266 Portrait Dialogue 6.0

267 Chapter 11: Published files played). You are recommended not to change or delete published files that are in use or have been in use recently. Visual Dialogue User Guide 267

268

269 Content objects 12 In this section: About content objects Creating a new content object Content Object Designer Building content object HTML tags Using content objects in a questionnaire Using content objects in an Browsing content objects

270 About content objects About content objects About content objects The concept of content objects comes from the idea of communicating personalized content to customers. When a customer navigate to a web site and identifies himself, we can display content depending on what we know about the customer. One example of such content will be a personalized offer to the customer. Content objects offer a structured and centralized way to define and work with personalized and dynamic content. Definition of a content object A content object is basically a set of rules that describes what content to deliver under given circumstances. A content object has a set of possible contents, called content items, and a set of prioritized rules. Each rule will be either true or false. The first rule that is true, under the given circumstances, is responsible for delivering the content of the object. This content will be one of the defined content items. The given circumstances, under which a content object executes, will in most cases relate to a specific customer and make it possible to deliver personalized content. However, other information than the identification of a specific customer may also be used to determine the content from the content object. For more detailed information about the definition and design of content objects, see About Content Object Designer on page 272. Using content objects Content objects can be used to deliver content in different channels. For example, a content object can be a part of a web page, it can be shown in a questionnaire or be part of an . The illustration below shows how one single content object can be reused in an , questionnaire and on a web page. 270 Portrait Dialogue 6.0

271 Chapter 12: Content objects For details on using content objects, see the following topics: Building content object HTML tags on page 280 Using content objects in a questionnaire on page 281 Using content objects in an on page 282 Creating a new content object Creating a new content object To create a new content object, choose Content Object from the Create tab in Visual Dialogue. The New Content Object Wizard is displayed. Step 1 On the first page of the wizard, the new content object is given a name and optionally a description. Visual Dialogue User Guide 271

272 Content Object Designer Step 2 On the second and last page of the wizard, the Target audience type is selected. The target audience controls whether the content objects always executes in the context of a known customer, or not. There are three different target audience types: Identified: A known customer from a specific customer domain is always specified when the content object executes. Anonymous: Only anonymous requests to the content object are allowed. Mixed mode: Both anonymous and identified requests to the content object are allowed. Note: All texts and options selected in the wizard can be changed at a later time in the Content Object Properties window. After completing the New Content Object Wizard, Content Object Designer will be displayed. Content Object Designer About Content Object Designer Content Object Designer is the tool inside Visual Dialogue where content objects are created and edited. In Content Object Designer, you work with content items and rules. Content object properties To review or edit a content object s properties, choose Properties from the File tab. The General tab This tab contains general content object properties. Name The name of the content object. An optional description of the content object. Key Key is a unique string that identifies the content object. This value is used when calling a content object. If Key is blank, a unique value will be generated when the content object is saved. Created (read only) The date and time when the content object was created. Created by (read only) The username of the user who created the content object Last modified (read only) The date and time when the content object was last modified. Last modified by (read only) The username of the user who last modified the content object. Deactivate content object Check this option to deactivate the content object and make it inaccessible. The Audience type tab Use these settings to control how the content object can be accessed. There are three possible values of Target audience type: 272 Portrait Dialogue 6.0

273 Chapter 12: Content objects Identified: A known customer from a specific customer domain is always specified when the content object executes. Anonymous: Only anonymous requests to the content object are allowed. Mixed mode: Both anonymous and identified requests to the content object are allowed. The Other tab This tab contains miscellaneous setting(s) to control the behavior of the content object. Enable logging of object execution If checked, all execution of the content object is logged to the database table CONTENT_OBJECT_LOG. This information is valuable for reporting and analysis. This option is on by default when creating a new content object. The Delete log button lets you clear the content object s execution log. When you click on this button, the Delete Content Object Log window opens. Delete complete log This option will clear the entire log. Delete only log items with the specified origin This option will only clear log items with the specified origin. Origin is an optional parameter which can be specified when calling a content object (see Portrait Dialogue Technical Help for details on calling content objects). Origin corresponds to the database field COL_ORIGIN in the table CONTENT_OBJECT_LOG. Working with content items About content items About content items Each content item defined in a content object represents a possible content of that content object. When a content object executes, one of the content items will be the returned as a result of that particular execution. All content items of a content object are listed in the tree view to the left in the designer. Different types of content items There are different types of content items, representing different types of content: Image The content item specifies a link (URL) to an image. For more information, see Image content items on page 274. HTML The content item contains a piece of HTML code. For more information, see HTML content items on page 275. Text The content item contains pure text. For more information, see Text content items on page 275. Message template Visual Dialogue User Guide 273

274 Working with content items The content item is based on a mesage template. For more information, see Message template content items on page 276. URL The content item points to web page. For more information, see URL Content Items on page 276. Creating a new content item To create a new content item, choose New Content Item from the Design ribbon tab. The Content Item Properties window appears. For details about setting up the properties of a content item, see Content item properties on page 274. Content item properties of content item properties These properties are common independent of the content type. Content item name The name of the content item as it will be displayed in Content Object Designer. An optional description of the content item. Key A key that identifies the content item. The value of the key must be unique inside a content object. When a new content item is created, the system suggests a key value. Content type The type of content. See About content items on page 273 for more information. Disable merge fields Some types of content, e.g. HTML and text, support merge tags. This means that customer data can be merged into the content, as in a message template. To increase performance, you can disable this functionality where it is not used. Random weighting A number that weights the different content items relative to each other when a rule is configured to pick a random content item. Setting this value to 0 excludes the content item from being part of a random draw. Image content items About image content items A content item of type image links to an image that is accessible on the internet. Configuring an image content item When you are configuring an image link, you can either specify a URL for the image or select a published file. After you have specified the image, the Content preview area is updated. You can optionally specify an image link. This is a URL that will be opened if the user clicks on the image. The Image Link Settings window has the following configuration options: Enable image link Enable or disable the image link option. Link URL The actual URL of the link. Open link in new window Specify if the link should open in a new browser window. 274 Portrait Dialogue 6.0

275 Chapter 12: Content objects Enable link tracking Specify if link tracking should be used for logging when the user clicks on the link. Link name An optional name of the link used when storing tracking information in the database. Note: Link tracking in content objects uses the same logging mechanism as link tracking in HTML s. This mechanism depends on links being related to specific s sent to customers. Consequently, the logged information will only identify a customer if the content object is used in an . In other cases, the logged information will not be related to a customer, and will only contain other information, e.g. when a specific link was clicked, browser type, etc. Link tracking is logged in the database table web_track_log. HTML content items About HTML content items A content item of type html contains HTML code similar to an HTML template. Designing an HTML content item When working with HTML content items, you can work in either Design Mode or HTML Mode. The toolbox contains merge fields and other tags that can be used if the audience type of the content object is identified. See Content object properties on page 272 for more information about audience types. Designing HTML content items is very similar to working with HTML templates. See Message Template Designer overview on page 108 for detailed information about working with HTML design. Text content items About text content items A content item of type text contains textual content, much like a text-based template. A text content item can, for example, be used in a text-based or in an SMS message. Designing a text content item When working with text content items, you enter textual code in the designer. The toolbox contains merge fields and other tags that can be used if the audience type of the content object is identified. See Content object properties on page 272 for more information about audience types. Designing text content items is very similar to working with text-based templates. See Message Template Designer overview on page 108 for more information about menu options and toolbox functionality. Visual Dialogue User Guide 275

276 Working with rules Message template content items Message template content items A content item of type message template points to a message template that defines the actual content. Configuring a message template content item To configure the content item, select a message template by clicking on Browse... URL Content Items About URL content items A content item of type url points to a web page that defines the actual content. Configuring a URL content item To configure the content item, specify a URL. Note: The URL may contain merge fields, as in the following example: Working with rules About rules About rules A content object contains one or more rules. The rules define the logic of the content object. The rules of a content object are ordered. When a content object executes, rule number one is evaluated first. If this rule evaluates to true, then this rule applies and the content item specified in this rule will be the result of the execution. If the first rule evaluates to false, then rule number two is evaluated. Subsequent rules are evaluated until one rule in the list evaluates to true. If all rules evaluates to false, an error occurs. This is because execution of the content object must return some content. Note: At least one rule must be defined before the content object can be executed. All rules of a content object are listed in the tree view to the left in the designer. Different types of rules There are different types of content items which representing different types of content: The none rule type 276 Portrait Dialogue 6.0

277 Chapter 12: Content objects The rule type called none has no types of criterion, and the rule will always apply. This rule type is mostly used to specify default content for the content object. For more information, see The none rule type on page 278. Selection-based rules A selection-based rules points to a selection. The rule evaluates to true if the customer specified in the request to the content object is part of the specified selection. For more information, see Selectionbased rules on page 278. Expression-based rules Expression-based rules contains an expression. The rule evaluates to true if the expression is true for the the customer specified in the request to the content object. For more information, see Expressionbased rules on page 278. Scripted rules Scripted rules are the most advanced type of rule and let you implement logic using a scripting language. For more information, see Scripted rules on page 278. Creating a new rule To create a new rule, choose New Rule from the Design ribbon tab. The Properties of Rule window appears. For details about setting up the properties of a rule, see Rule properties on page 277. Rule properties of content item properties General properties of a rule are independent of the rule type. Rule name The name of the rule as it will be displayed in the Content Object Designer. An optional description of the rule. Rule type The type of rule. See About rules on page 276 for more information. Content item The content item that will be used if this rule applies (evaluates to true) when the content object executes. In addition to selecting one specific content item, the Content Item property can be set to three special values: 1. [Unselected] No content is specified. This value should only be used for rules of type script. This type of rule can specify the content dynamically in the script code by programmatically returning a content item. 2. [Blank content] Blank content is returned when the rule applies. 3. [Choose a random content item] A random content item is picked. The random algorithm weights the content items using the Random weighting property of the content items (see Content item properties on page 274). Specify an active period If checked, the rule is only used for a limited timeframe, specified in Active from and Active until. Outside this timeframe, the rule will be skipped when the content object executes. Active from The start date of the active period. If left blank, there is no starting date. Active until The end date of the active period. If left blank, there is no end date. Visual Dialogue User Guide 277

278 Working with rules Note: The Active from and Active until values can also contain a time part in addition to a date. Example: :00 The none rule type About the none rule type The rule type called none always evaluates to true. It is usually used to specify default content for a content object. There are no criterion settings that need to be configured for this type of rule. Selection-based rules About selection-based rules Selection-based rules point to a selection defined in Visual Dialogue. Selection-based rules evaluate to true if the customer specified in the call to the content object is part of the actual selection. Configuring a selection-based rule To specify what selection to use, click on Browse... in the Rule details pane of the designer. The Apply rule to customers who are not in the selection box can be checked to invert the result of the rule evaluation, meaning that the rule evaluates to true if the customer is not part of the specified selection. Expression-based rules About expression-based rules An expression-based rule contains an expression. A rule evaluates to true if the expression is true for the customer specified in the request to the content object. Designing an expression-based rule When designing an expression-based rule, write an expression similar to those used in Selection Designer. For a detailed description of the expression language, see Customer Domains and Expressions in Portrait Dialogue Reference Help. Scripted rules About scripted rules Scripted rules are the most advanced type of rule. They enable you to implement logic using a scripting language. 278 Portrait Dialogue 6.0

279 Chapter 12: Content objects Designing a scripted rule When designing a scripted rule, you implement a function called EvaluateRule (see the examples below). This function has three input parameters: ContentItems A list of all content items defined in the content object. The outcome of the content object execution can be determined by returning one of the content items in this list (see example 3 below). Customer An object representing the customer if the call to the content object is identified. This parameter can be used to access customer data (see example 1 below). If the call to the content object is anonymous, Customer has a value if null. RequestParams A list of additional parameters in the call to the content object (See example 2 below). The return value of the EvaluateRule function should be a boolean value (true or false), or a content item. Returning a boolean value means that the rule evaluates successfully, and that the content item specified to use for this rule will be the result of the execution of the content object. Returning a content item also means that this rule evaluates successfully, but that the returned content item is the result of the execution of the content object. Returning false means that the rule should not apply in the current execution of the content object. For a detailed description of EvaluateRule and its parameters, see IMHContentObjectRulePlugin in Portrait Dialogue Reference Help. Scripting languages The default scripting language is Microsoft JScript. Other scripting languages available in Windows Script can be selected using the Language button on the Script ribbon tab. Example: using customer data function EvaluateRule(ContentItems, Customer, RequestParams) { if (31 <= Customer.FieldValue("Age") <= 40) return true else return false; } Example: using RequestParams function EvaluateRule(ContentItems, Customer, RequestParams) { if (RequestParams.Value("MyParam") == "A") return true else return false; } Example: returning content items function EvaluateRule(ContentItems, Customer, RequestParams) { if (RequestParams.Value("MyParam") == "A") return ContentItems.ContentItem("C1") // Using content item key else return ContentItems.ContentItem(1); // Using the index of the content Visual Dialogue User Guide 279

280 Testing a content object item } Example: creating a content item on the fly function EvaluateRule(ContentItems, Customer, RequestParams) { if (Customer.FieldValue(" ") == null) { NewContentItem = ContentItems.AddContentItem(); NewContentItem.ContentType = "text"; NewContentItem.ContentText = "Please register your address..."; } return NewContentItem; } else return false; Testing a content object Activating the Content Object Test window To test a content object while working in the Content Object Designer, choose Test Content Object (Shift+F9) from the Design ribbon tab. The Content Object Test opens. Using the Content Object Test window To test the content object, click on Execute in the test window, or press F9. To execute the content object in context of a customer, enter a customer ID in the Customer ID field, as shown below. If the Customer ID is left blank, the content object is tested in anonymous mode. Building content object HTML tags Content objects are accessible through the Web Utilities application. This means that it is possible to use a content object inside a web page by linking to the Web Utilities application using the appropriate HTML tags and URLs. To create such an HTML tag or URL, a special tool is available in the Content Object Designer and in the Content Object Browser. Choose Build HTML Tag from the Design ribbon tab in the Content Object Designer to start. The Build Content Object HTML Tag window opens. The Build Content Object HTML Tag window This window lets you build HTML tags or URLs to use the content object. At the bottom of the window the result is displayed, and it can be copied to the Windows clipboard. Before an HTML tag or URL can be generated some options have to be selected: 1. A content object must be selected. 280 Portrait Dialogue 6.0

281 Chapter 12: Content objects 2. There are several types of tags or URLs which can be built. You need to select one of the following types. HTML script tag: The result will by an HTML script tag that renders the content object using dynamic HTML. HTML i-frame tag: The result will by an HTML i-frame tag showing the content object. Only URL to content: The result will a URL to a web page containing the content object. 3. It is possible to specify a customer domain and a customer ID. If this is specified, the content object will execute in the context of an identified customer. 4. The option Enable showing errors specifies whether error message will be displayed. If not, blank content is displayed if errors occurs. 5. The option Scramble URL specifies whether, or not, the URL parameters should be encrypted with a check sum. Note: For a full description of URL parameters when accessing a content object through the Web Utilities application, see Content Objects in Portrait Dialogue Reference Help. Example To illustrate how a script tag can be used, we create a simple web page using the HTML code below. <html> <head> <meta http-equiv="content-type" content="text/html; charset=utf-8"> <title>this is a test page</title> </head> <body> <h1>this is a test page</h1> <hr> <script src=" instance=mssql_doc45&om=wrapped&cok=co1&custdomainid=1001&customerid=106981" type="text/javascript"></script> <hr> </body> </html> By changing the customerid parameter of the URL in the script tag, you obtain a different result, because a different rule in the content object applies to a different customer. Using content objects in a questionnaire Content objects can be used when designing questionnaires in Visual Dialogue. There are two possible ways of using a content object in a questionnaire: 1. Content objects can be placed in the page text of a page. Visual Dialogue User Guide 281

282 Using content objects in an 2. Content objects can be used in a questionnaire style. Using content objects in the page text Content objects can be used in the page text of a page in a questionnaire layout. A special tag has been defined to support this. Examples are: [$(CO1)] [$(CO1, myparam1=a;myparam2=b)] For details about this merge tag, see Using merge tags on page 160. Using content objects in a questionnaire style Content objects can be used in questionnaire styles. The same tags as in the page text are used. Note: Questionnaire styles can be used by the My Profile page in the Customer Web Access (CWA) application. Hence, by adding a content object to a style, the content object can be displayed on the My Profile page. For information on how to configure the My Profile page to use a questionnaire style, see the document Configuration CWA.pdf. Using content objects in an Content objects can be used when designing s in Visual Dialogue. Content objects are available in the toolbox in Message Designer. By double-clicking a content object in the toolbox, a tag is inserted in the . When the is merged, the content object is executed, and the resulting content is put inside the . Note: A merge tag like «$(CO223)» is used to insert the content object in the . Note that link tracking in the content object is handled specially by this tag, and that, consequently, link tracking in the content object will work as if the links were put directly in the template itself. Browsing content objects To see all content objects defined, choose Explore > Content Objects from the Home tab in Visual Dialogue. The Browse Content objects frame is displayed. To sort the content objects in the list, click on the desired column in the heading. To configure the set of columns displayed in the list, choose Select Columns from the View tab. The Select Columns window opens. 282 Portrait Dialogue 6.0

283 Chapter 12: Content objects To review or edit the properties (e.g. the name or the description of the content object), select a single content object, and choose Properties from the Home tab. The Content Object Properties window will appear. To open a content object in Content Object Designer, double-click a single content object in the list, or choose Open from the Home tab. To delete a content object, mark a single content object, and choose Delete from the Home tab. To build an HTML tag or URL to access the content object, select Build content object HTML tag from the Home tab. See Building content object HTML tags on page 280 for details. Content objects marked with a red mark A red mark upon the icon of a content objects indicates that the content object is Deactivated. See Content object properties on page 272 for more information. Visual Dialogue User Guide 283

284

285 Export and import of Visual Dialogue objects 13 In this section: About export and import The Visual Dialogue export wizard The Visual Dialogue import wizard

286 About export and import About export and import Visual Dialogue supports export to and import from files. For example, after you have designed dialogs, selections, and message templates in Visual Dialogue, you can export these objects to a file. This file can later be imported into another installation of Visual Dialogue. In Visual Dialogue, objects are exported using the Visual Dialogue Export Wizard and imported using the Visual Dialogue Import Wizard. Object types supported Most objects you work with inside Visual Dialogue can be exported and imported. These are: Dialogs (including Telemarketing projects) Selections Message templates Questionnaire Report templates Broadcasts Questionnaire styles Published files Content objects. Different ways to import objects Import can be done in two different modes: complementary and non-complementary. Complementary Mode Complementary Mode is designed to let you copy and update objects between a set of systems that belong together. An example is when there is one system for development, one for pre-production testing, and one for production. We say that these systems are part of the same complementary environment. In a complementary environment, it is possible to migrate new and changed objects from one system to another. See the illustration below. 286 Portrait Dialogue 6.0

287 Chapter 13: Export and import of Visual Dialogue objects For technical details about how to configure a complementary environment, see Technical Help. Non-complementary Mode Non-complementary Mode is the standard import mode. In this mode, objects are always imported as new objects. This means that objects cannot be updated using the import functionality. Note: In a system that is not part of a complementary environment, imports will automatically take place in Non-complementary Mode. You will not have to take into account whether to use Complementary or Non-complementary Mode. Visual Dialogue User Guide 287