Spice Process Editor User Guide
From SpiceCSM
Contents
|
Introduction
The Spice Process Editor is an application that is used for developing a series of question & answer relationships. It was initially developed for use with call centers; to guide customer service agents through the support process.
This guide will walk you through the features of Spice Process Editor. If at anytime the guide is not enough to get you going please do not hesitate to seek help from our forum at www.opencsm.org/forum.
Getting Started
The first time the Spice Process Editor loads, a window pops up that lets you choose to load a help process in the editor, reader or both. There is also an option to not show the window again. Loading the process in the editor will load the help process in the editor so you can see how everything was made. If you just want to read about how to make a process then you can just load the process in the process reader. Or, you could do both.
Interface Overview
The Spice Process Editor interface is easy to use and implements multiple ways to interact with the process.
Process Tool Bar
The most obvious way to work with the editor is through the Process Tool bar. The tool bar is divided up into sections which are separated by a vertical bar. The first section has buttons to create a new process, load a process, save a process and edit process information. The second section has buttons for copying, cutting, pasting, deleting and saving a subprocess. The next section allows you to undo and redo. The section after that is the view section; where you can zoom in and out, reset the zoom level, and fit the process to the window. The last section has buttons for previewing the process, saving the process image to a file and help.
Right Click Menu
Another way to interact with the editor is through the right click menu. Depending on where you click, on a node or on white space, different options will be available. The easiest way for you to get familiar with the right click menu is to browse it.
Currently the only way (there is one exception) to interact with a node is through the right click menu. We are planning to add a Node Tool bar and short cut keys for interacting with nodes.
The scroll wheel on the mouse zooms in and out.
Shortcut Keys
The latest version of the Spice Process Editor implements the following shortcut keys:
Ctrl + s = Save process Ctrl + n = New process Ctrl + o = Open process file Ctrl + i = Edit process information Ctrl + c = Copy subprocess Ctrl + x = Cut subprocess Ctrl + v = Paste subprocess Ctrl + z = Undo Ctrl + shift + z = Redo Ctrl + delete = Delete subtree F1 = Help menu
Double Click
The Spice Process Editor implements a few double click operations. You can double click on a node to show the edit node window and you can also do the same for answers. Just double click on the word on an answer line to show a window that edits that line. At the moment, double clicking does not work with Internet Explorer.
Nodes
This section will explain the different types of nodes and the way they can interact.
Types
There are four types of nodes that the Spice Process Editor implements. The names of the node basically tell what the nodes are used for. The Question node is used for asking a question. The Information node is used to present information. The Data node is used to collect data and/or retrieve data from a remote host. The Switch node is used to switch a process on a certain variable.
Question
The Question node is used to ask questions; this can be done in two ways. There can be one question in the script text of a node with many answers to that question. Or, the answers on the node can be questions themselves. This node can save the answer that is selected in the process reader.
The question node can have infinitely many children, gotos, and kickouts.
Information
The Information node is used to present information. This node has many other features that are very useful. The node can be hidden to the process reader; the reader just passes over the node and does not show any of it's information. The information node can also save a specified variable to a specified value. These two features are useful when determining if a path in a process has been traversed. Adding a hidden information node at the end of the path will not alter the flow of the process. Setting a variable in that hidden information node will tell whether that path has been traversed. This node can also be chained, which will be explained more later.
The information node can only have one answer, whether it be a child, goto, or a kickout.
Data
The Data node, as stated above, is used to collect data and/or retrieve data.
There are four different ways to collect data with this node; text fields, text areas, check boxes, and radio buttons are implemented in the current version. Text fields and text areas can require data input before being able to continue in the process reader. With text fields you can specify the number of fields that you want. So you could create an data node with 1 text field or with 15 text fields. The same is true for check boxes and radio buttons. With the data node you can save the information that was collected to a specified variable. The data node can also be chained, more on that later.
The data retrieval portion of the data node does what it sounds like. It retrieves information from a remote server and returns the data. The returned information can be displayed in the script text of the node and/or it can be saved to a variable. This part of the node is a bit more difficult to use because information is needed from the remote server. That information is covered in the 'Forms' section of this page under 'Edit Node' -> 'Node Specific' -> 'Data Node'.
The data node can only have one answer, whether it be a child, goto, or a kickout.
Switch
The Switch node is used to switch on variables. When the process reader finds that it's at a switch node, the process reader sees the variable that the node wants to switch on. Say that variable is 'OS_Type' and the value of the variable is 'Windows 98'. The process reader will look for an answer coming off of the switch node that is 'Windows 98'. If that value is found to be on the 'short answer' of a line or kickout, the process reader will automatically select that answer and continue without the user knowing. If, on the other hand, the value is not found to be on a 'short answer' the process reader will automatically select the default case, which is specified when editing the switch node. BUT if the process reader finds that the switch node has an answer or kickout with the 'short answer' ":undef:", that answer will be selected when the switch variable is undefined.
Say you want to switch on the answer to a question. The switch node has to have all of the same answers as the question node. If it does not, the reader would select the default case if the value for the switch variable is not found.
The switch node can have infinitely many children, gotos, and kickouts.
Chaining
As stated above, different nodes can be chained. That means that the process reader will display all the nodes in the chain in one window. So if there are four chained data nodes each with a different set of input fields, the reader will display all of the fields from the four nodes in one window. You can also chain information and question nodes. But the question nodes can only be the last node in a chin. So you can chain, for example, three data node, two information nodes, eight data nodes, and a question node.
Invalid
Nodes can be marked invalid by a giant red X. If a node is invalid the process cannot be saved. This prevents invalid processes from accidentally being used in live applications.
Question
The question node can be invalid if it does not have any answers or if there are two answers with the same labels.
Infomation
The information node will be invalid if it has more than one answer.
Data
The data node is invalid if it has more than one answer.
Switch
The switch node will be invalid if there is no default case specified, no switch variable specified, or if it has two answers that are the same.
Root
The root node (the node that is first in the process) is distinguished by a 'shadow' on the node. When the node is selected, the shadow becomes darker.
End
End nodes (nodes that have no answers) are distinguished by having a red outline when not selected or having red text when selected.
Answers
There are three types of answers in the Spice Process Editor; children, gotos, and kickout. Answers are depicted in the editor by lines between nodes or arrows next to the node.
Children
A child is created when you add a node to another node. The child is depicted by the black line with blue letters which connect different nodes. A child forms a parent child relationship.
Gotos
A goto allows the reader to jump to a different node in the process. A goto can jump to any other node in the process except the parent of the node that you are adding the goto to. It is depicted by a light blue line with red text.
If multiple gotos are added to the same node, then a 'multiline' will be created. They are still gotos but it is depicted differently.
Kickouts
A kickout is a way to go to the root node of another process in another file. When the user selects a kickout in the process reader, the reader will locate the file and load it into the process reader. The user can not tell the difference when a kickout is selected opposed to a child or goto. When the kickout process reaches an end node, the reader will look back at the node that had the kickout to see if there are any other answers. If there are other answers then the reader will kick back to the original process and continue from there. If there are no other answers then the process will finish.
Variables that were set in a kickout process are available for use when the process reader kicks back to the original process.
One technique used is to add a kickout to a switch node as the default case. The switch variable for the node will be one set in the kicked out process. So when the process kicks back and encounters the switch node, the variable will be set and the proper answer will be selected automatically.
Kickouts were implemented so the processes could be relatively small and generic. If a more specific process was needed, then you could kickout to one.
Using Variables
This section is all about variables and how to use them. When explaining the different nodes, there were parts that explained how to save variables and switch on variables. The following sections provide more information on variables.
Interpolation
In several places, including Script Text, Agent Hints, URL pops and kickout file names, you can use interpolation. Interpolation comes in 2 flavors; straight variable substitution and ternary expressions.
Variable substitution
This one is very easy, just insert a string of the form #[VARNAME] where VARNAME is the name of the variable to substitute in.
For example the string:
Thank you for calling #[br_label], my name is #[ag_fname], how may I assist you?
Becomes:
Thank you for calling SpiceCSM, my name is Tom, how may I assist you?
If the variable you're trying to interpolate isn't defined or is set to null, the string Undefined Variable will be substituted instead.
Variables can also be stored in lists. The syntax is fairly easy. In the following example assume that there is a variable named products and that there are two products, Spice Process Editor = 1 and Spice Process Reader = 2. The number that refers to the element in the list is called the key.
Example:
The product you are interested in is #[products[1]]. You are also interested in #[products[2]].
Becomes:
The product you are interested in is Spice Process Editor. You are also interested in Spice Process Reader.
To make this a bit more generic, you can use variable substitution on the key. In the following example assume that the variables are the same as the previous example, adding key to be 2.
Example:
The product you are interested in is #[products[#[key]]].
Becomes:
The product you are interested in is Spice Process Reader.
Ternary Interpolation
This form is a lot more complex. It allows you to effectively do conditional expression. The ternary expression has 3 components; the test, the 'true' branch and the 'false' branch. The test and one of the 2 branches are mandatory, one branch can be omitted. For more information see the wikipedia article on the ternary operator.
The process reader currently supports five different conditional expressions which check:
- if a variable is set - #{variable ? true case : false case}
- if a variable is set to something - #{variable = something ? true_case : false_case}
- if a variable is not set to something - #{variable ! something ? true_case : false_case}
- if a variable is greater than something - #{variable > something ? true_case : false_case}
- if a variable is less than something - #{variable < something ? true_case : false_case}
- NOTE - the value of the variable and the 'something' in the last two cases can only be numbers.
The 'something' can be another variable or any text that you want.
Here's an example, assuming there's a variable called securesmtp to indicate whether you supports secure SMTP:
Please configure your SMTP port to #{securesmtp ? 465 : 25}, your SMTP server to #[smtp] and #{securesmtp ? enable : disable} TLS.
Becomes, assuming securesmtp is set:
Please configure your SMTP port to 465, your SMTP server to mail.example.com and enable TLS.
Or, if securesmtp is not set:
Please configure your SMTP port to 25, your SMTP server to mail.example.com and disable TLS.
As you can see, this allows you to reduce the duplication of script text in the case where brands differ in little ways. More to come on more advanced ternary interpolation.
Examples of ternary expressions with omissions:
#{isangry ? I'm angry! : } -- the false condition is omitted
#{securesmtp ? : Secure SMTP is not supported} -- the true condition is omitted
Forms
In this section we will go over the various window that can be opened.
New Process
To create a new process you can use the process tool bar, right click menu or the shortcut key listed above. All of these will open a new process window titled 'New Process Form'. The fields in the window are as follows:
Process Label should be a few words describing what the process is used for. This will appear in the upper left corner of the window.
Process Notes specifies anything that someone else should know about the process, so they can make changes.
File Name will be the name of the file that this process is saved to.
Process Tier specifies how much experience the user should have, with 1 being the least amount of experience.
Brand specifies the brand that the process should be used with. If the process is going to be used with many brands, then select 'Generic'.
Load Process
There is only one field in the load window, file. File is the file that will be loaded. Click the browse button to select a process from the local filesystem.
Save Process
There is also only one field in this window, file name. File Name specifies the name of the file that this process will be saved to.
Edit Process Information
Editing the process information is exactly like creating a new process except that it updates the current process. See above for more details.
Save Process Image
Save Process Image will save the current view of the process to a file. A window will open with the following fields: File Name is the name of the file that this process' image will be saved to. Width specifies the width of the image that will be saved. Height is the height of the image that will be saved.
Edit Node
To edit a node, simply double click on the node that you want to edit. Or you can right click on the desired node and go to 'Node' -> 'Edit Node'. The edit node form is created dynamically based on the properties of the node. Therefore, depending on the situation, there may not be all of the features listed here. When the edit node window opens there will be different tabs along the top. The following are descriptions of these tabs.
Main
The main tab is the default tab that opens when the edit node window is opened. This is the main tab for all of the nodes except for the Switch Node.
The 'Node Label' is what will appear on the node in the Process Editor. It is used for describing the basic function of the node. For example, if the node asks a question about a modem then the Node Label could be 'modem?'.
The Script Text field specifies the information that the Process Reader will show to the user. This can be a question, an instruction or just used to present information.
The Agent Hints field also specifies information that the user will see in the Process reader. The information in this field is for helping the user. Example: Say the Script Text is 'What modem do you have?' Then the Agent Hints could be 'Go to the web site 'www.mymodem.com' to find out.'
The Image check box is for displaying an image in the Process Reader. When the check box is checked, the following two fields will appear.
The image is specified by the Image Path field. This has to be a relative path or an absolute path. A relative path is a path that is relative to where the Process Reader lives. Say the Process Reader lives on a web server and there is a directory called images. The relative path could be '/images/myimage.jpg' or '../images/myimage.jpg'. An absolute path is the entire path to the webserver and image. Example: 'http://mywebserver.myserver.com/images/myimage.png'
Text Location specifies the location of the Script Text relative to the image. So if 'Below' is selected, then in the Process Reader the image would appear first and then the Script Text would appear below the image.
Main Switch Node
The switch node is invisible to the Spice Process Reader so this node has a unique main tab.
The Node Label is what will appear on the node in the Process Editor. It is used for describing the basic function of the node.
The Default Case drop down has to be set for the node to be valid. The 'Default Case' specifies the answer that will be selected if the 'Switch Variable' is not set.
The Switch Variable is what variable the node will switch on. Example: Say a question node saves an answer as 'hello' and the switch variable is also set to 'hello'. Then the Process Reader will look for the value of the 'hello' variable. If the Switch node does not have an answer that matches the value of the 'hello' variable, then the reader will use the 'Default Case' as the answer. But, if the reader finds that the Switch node has a 'Short Answer' that matches the value of 'hello' that answer will be selected.
Node Specific
Each node has it's own set of features and therefore each node has something different in the 'Node Specific' tab. The Switch Node does not have a node specific tab because its main tab is basically its node specific tab.
Question Node
The question node allows you to save the answer to the question. If you want to save the answer just click the save answer check box and specify the name of the variable that you want the answer of the question to be saved as.
Information Node
The Hidden check box tells the Process Reader that the node should not be displayed.
The Chain check box is for creating a chain of nodes. This means that the Process Reader, in one window, will display all the fields for all the nodes in the chain. The check is not for this node, it is saying to attach the next node to this node.
The Save Variable check box is used for saving a variable. If the box is checked the following two fields will appear.
The Variable Name field is for specifying a name for the variable that is being saved.
The Variable Value field is for specifying the value of the variable named in the 'Variable Name' field.
Data Node
Data Collection
The data node allows for collection of information through text fields, text areas, check boxes, and radio buttons. The options for check boxes and radio buttons are identical.
The Input Type field specifies the type of input for this node, which will be displayed in the Process Reader.
Number of Fields is the number of fields that this node will have in the Process Reader. For example, if 'Text Field' is selected then 'Number of Fields' specifies how many text fields will appear in the Process Reader. The same is true for 'Check Box' and 'Radio Button.'
Save Variable is used to save the data that is collected with this node. The variable can then be used by the Switch Node.
Text Area Label is what will appear in the Process Reader as the label for the Text Area.
The Require Data check box halts the Process Reader until this node's fields are non empty.
The Chain check box is for creating a chain of nodes. This means that the Process Reader, in one window, will display all the fields for all the nodes in the chain. The check is not for this node, it is saying to attach the next node to this node.
Check Box/Radio Button
Check boxes and radio buttons can be created by specifying the Number of Fields and then clicking on the Specify Fields button. They can also be created by using a variable, specifically an array variable (a list variable). So how ever may elements are in the array (list) is how many check boxes or radio buttons there will be in the reader. This is accomplished by checking the box labeled Create from variable and specifying the variable in the field labeled Variable Label. This variable will be used to create the labels of the check boxes or radio buttons.
Text Fields
When text filed is selected for the input type and the 'Apply Changes' button is pressed, a window will open. This window allow you to specify the names of the text fields that will appear in the process reader. The window also allows you to specify the variables that will be used to save the values of the text fields. Each text field has its own save variable.
Data Retrieval
As stated earlier, the data node can retrieve information from a remote server or host. This cannot solely be accomplished by the author of the process; someone has to make a script or something else that returns the information. The location of the script (or whatever else it may be) is specified by the URL field.
Scripts can use post variables to determine different information, if the script was designed that way. If the specified script uses post variables then the number variables can be specified by the Number of POST variables field. Once this field is filled in then the labels and values of the post variables can be defined by clicking the button Specify Variables . Once this button is pressed a panel with text fields will slide out from the right. This panel is where the post variables can be specified; the label and the value. These fields can have a single value so the script returns the same information every time or they can be interpolated so the script can return different information every time. Both the variable label and the variable value can be interpolated. For more on interpolation see the Interpolation section of this user guide.
When information is returned it can be handled two ways. It can be displayed in the script text of the node and/or it can be saved to a variable. The Display return value check box allows for displaying the return value and the Save return value check box allows for saving the returned information. When the Save return value box is checked, a field labeled Save Variable will appear so that the variable label can be specified. When retrieving information the data node can be hidden, so the reader just gets the information and continues on in the process. Nothing is displayed for the node. This is useful for saving the returned value to a variable without the user knowing.
NOTE - Data collection and data retrieval can be used in the same node, BUT the data retrieval portion is executed first so you cannot collect information in a node and try to use the collected information for the post variables in the data retrieval portion of the node. You can however have two data nodes, the first one can collect the information and the second one can retrieve information based on the first nodes collected information.
NOTE - Data collection can be chained BUT if a data node is in a chain, data retrieval will not work .
Optional
These fields do not have to be set in every node. They only should be set if there is a change in the process status, tier, issue, or sub issue. You will be unable to select an issue unless a brand is selected. You will be unable to select a sub issue unless a brand is selected and there are subissues for that issue.
The Status field allows for setting the status of the process at this node. Suppose a status is set for this node. When the node is traversed in the Reader, the status of the process is changed to the status of the node.
The Tier drop down specifies how much experience the user should have, with 1 being the least amount of experience.
The Issue Type drop down sets the current issue of the process to the selected issue.
If there is a sub issue for the current issue, the Subissue Type drop down sets the current subissue of the process to the selected subissue.
Answers
The answers tab allows you to edit all the children and gotos that the node has. The following fields will have a number after it which indicate what fields belong together.
The Short Answer field is what will appear in the Process Editor on the answer line connecting this node to the next node. This is also what the Process Reader saves if a question node is saving the answer.
The Full Answer is what will appear on a button in the Process Reader as an answer for this node.
The URL field optionally specifies a url to open in a new window. In the Process Reader there will be a button to the right of the answers. This button will pop a new window with the specified URL.
Kickouts
Kickouts are a way to go from a node in one process to the root node in another process.
The Short Answer field is what will appear in the Process Editor on the answer line connecting this node to the next node. This is also what the Process Reader saves if a question node is saving the answer.
The Full Answer is what will appear on a button in the Process Reader as an answer for this node.
The File field specifies the file of the process that should be loaded as an answer for this node. The file will be loaded and the root node of the process will be an answer for this node.
The Fallback File specifies another file to load just in case the original file, specified in the 'File' field, is not found.
Answer Position
This tab allows for rearranging the answers for this node. Just drag and drop an answer to change it's button location in the Process Reader.
Notes
This tab allows for adding notes to the node. This is useful when using many different variables or for informing other people working on the same process.
Add Node
The Short Answer field is what will appear in the Process Editor on the answer line connecting this node to the next node. This is also what the Process Reader saves if a question node is saving the answer.
The Full Answer is what will appear on a button in the Process Reader as an answer for this node.
The Node Label is what will appear on the node in the Process Editor. It is used for describing the basic function of the node. For example, if the node asks a question about a modem then the Node Label could be 'modem?'.
Add Goto
The Short Answer field is what will appear in the Process Editor on the answer line connecting this node to the next node. This is also what the Process Reader saves if a question node is saving the answer.
The Full Answer is what will appear on a button in the Process Reader as an answer for this node.
The URL field optionally specifies a url to open in a new window. In the Process Reader there will be a button to the right of the answers. This button will pop a new window with the specified url.
Add Kickout
The Short Answer field is what will appear in the Process Editor on the answer line connecting this node to the next node. This is also what the Process Reader saves if a question node is saving the answer.
The Full Answer is what will appear on a button in the Process Reader as an answer for this node.
The File field specifies the file of the process that should be loaded as an answer for this node. The file will be loaded and the root node of the process will be an answer for this node.
The Fallback File specifies another file to load just in case the original file, specified in the 'File' field, is not found.
Remove Goto/Kickout
This window is the same for both gotos and kickouts.
The Apply button removes the checked items.
Remove All removes all of the items whether they are checked or not.
Brand Variables
The brand variables window displays the variables for the brand of the process. If the brand 'Generic' is selected, then there will be no option to view the brand variables.
Process Variables
The process variables window displays the variables and the node that they are set or used in.
Preview Process
This window is the process reader. This allows you to view the current process and see what it will look like in the process reader.
When the window opens there is a brand selection box. Select the brand that you want to test the process with. Then click the Ok button; at this point the window contains the process reader.
Lite Mode
Lite mode is for creating the basic framework for a process. Editing nodes, answers and kickouts are all done by double clicking on text of the desired element. When editing a node, only the script text and the notes can be modified. Branding is not used in lite mode.
