Privacy | Trademarks | Terms of Use | Feedback
Updated: 18 June 2020
© 2016 - 2020 Pegasystems Inc. Cambridge, MA All rights reserved.
Using the Interaction.xml File
The Interaction.xml file defines the contexts, activities, plug-ins that comprise the Agile Desktop implementation you are designing. An Interaction.xml file is created for each project when you add the InteractionManager component and save the project. The Interaction.xml file is stored in the root of the Projects folder. Typically, there will only be one, but you can define multiple interaction XML definition files. Here is an example:
C:\Users\YourName\Documents\OpenSpan Studio for VS 2015\Projects\ProjectName\Interaction.xml
You can name this xml file anything you want, as long as you update the name in the Configuration File property when setting properties for Interaction Manager in Solution Explorer. Do not, however, change property names in the Interaction.xml file.
Note: When you add the Interaction Manager component to a solution, Studio creates a copy of the Interaction.xml file for you. You can then customize that file as needed.
Interaction.xml File Settings
This table describes the settings found in the Interaction.xml file:
Section |
Keys |
Context |
The Context section defines the information Interaction Manager will track and make available to the various automations, such as property values. For instance, you can use these values as variables, such as ClientFullName, when you define predefined text for the Notes plug-in. You define the relationship between the interrogated controls and these context values when you tie items together in your automations. Name – Specifies the property's name used in automations and the plug-in configuration. Type – Identifies the property's data type. You can choose from these types: String, Number, Boolean, and Date. Format – Optional. This is based on .NET format strings. For instance, enter C to format the number as currency or P for percentages. Omit this attribute if the value is not an amount. This property only affects how the value is displayed. For example: <Value Name=”TotalDue” Type=”Number” Format=”C” Default=”0”/> would display the numerical value TotalDue in a currency format (Format=”C”). Default – Use this attribute to specify a default value. The attribute is populated with this value when an interaction is created. If there is no default, define this attribute as shown below. Default="" Here is an example: <Value
Name="ClientFullName" Type="String" Default=""
/> |
Globals |
Use this section to define information that is stored independent of interactions. Global values are accessed through the global dictionary component. Defining a global value is similar to defining a context value: Name – Identifies the property in automations and in the plug-in configuration. Type – Specifies the property's underlying data type. You can choose from String, Number, Boolean, and Date. Default – Use to specify a default value. The property is populated with this value when the system starts. Format – Controls how the system displays the value. You can format strings as numbers or dates. You have these Numeric options:
You have these Date options:
|
Activities |
An activity describes a piece of work that needs to done. An automation can request for activity to be performed or it can perform an activity when requested. Activities are queued and run sequentially. Only one activity can be processed at a time. Any automation can request for an activity to be performed by calling the Activity.StartActivity()method. Once called, the activity is placed at the bottom of the queue and is processed when the activities before it in the queue are completed. An activity is completed when all of the automations listening to Activity.ActivityStarted have completed their execution. Note: Be sure to define all of the information needed to process the activity in the Context section. Value/Name – Provides a descriptive name of an activity. Value/Type – Specifies the type of the Value, such as Boolean, Date, or String. RequiresInteraction – Specifies if an interaction needs to be active for the activity to run. The default is True. In this example, the Close Account activity has a StartActivity() method with two parameters: CustomerId and Effective Date. There is also an ActivityStarted event with CustomerId and EffectiveDate outputs. Additionally, an activity component for Close Account will have a CustomerId property and an EffectiveDate property. These property values can be set or retrieved during the execution of the activity or will be set when responding to the ActivityCompleted event. <Activity
Name="Close Account" ShortcutOrder="2"> Note: When defining an activity, make sure all information required to perform the activity is available through context values or via these Activity properties. |
Plugins |
Plug-ins are HTML user interface sections which appear in the toolbar. Agile Desktop includes these plug-ins:
Generic plug-in settings For all plug-ins, you have the following options. Name – Specifies the name of the plug-in. isActive – Set to True if you want the plug-in to appear on the toolbar. Set to False to make the plug-in inactive. The default is True. hasExtendedView – Set to True if you want to allow the user to expand the plug-in to show more information. Set to False to prohibit expansion. The default is True. enableWithNoActiveInteraction – Set to True if you want to allow the user to interact with the plug-in even if there is no active interaction. Set to False to only enable the plug-in if there is an active interaction. The default is False. canHide – Set to False if you do not want the user to hide the plug-in from the gear menu. Set to True if you want to allow the user to hide the plug-in via the gear menu. The default is False. section name – Assign a name to logically group elements in the plug-in. visibility – Choose from the following options. Primary – The section is added to the Primary view. Extended – The section is added to the extended view. Both – The section is added to both the Primary and Extended views. Here is an example: <Plugin
name="StartInteraction" isActive="false" enableWithNoActiveInteraction="true"> 360 View plug-in settings The name for this plug-in is 360AppBar. Section:Name – Indicates the type of the styling to use for the section. This affects how the data is presented. You can choose from these stylings: Images (only appears
in sections which have the Name attribute set to Images) Section:Label – Lets you add section labels for each section in the 360AppBar. Section:InnerLabel – Lets you add an optional shorter label that only appears on top of the IInformation section. The default is Contact Information. Section:Divider – Enter True if you want a divider like to appear above the section. Enter False if you do not. Section:ImagePadding – Enter a number which specifies, in pixels, the amount of padding to add. This option only affects the Images section. If you leave this option blank, the default padding of 24 pixels is used. Section/Item:Name – Indicates the name of item to add to the plug-in. Section/Item:Image – This only applies to the images section. Indicates what image is displayed. You can specify a .png file that is located on your hard drive or in the startup project of your solution. To specify a .png file on your hard drive, use the CustomImagePath key in the RuntimeConfig.xml file. Section/Item:Tooltip – This only applies to the images section. Defines the text that is displayed when you hover your mouse over the image. Section/Item:TextWrap – Enter True if you want the text for this Item to wrap to the next line, instead of truncate. Default is False. This option must be in the Item element and only works with items in the Products, Balances, and Custom sections. Section/Item:TextAlign – This only applies to items in Custom sections. Enter Right to set the text alignment of an Item. The default is Left. Section/Item:Context Name – Indicates the name of context value used to populate this item. This value is defined in the Context section. As the associated context attribute value changes, this item is automatically updated. Section/Item/Label – Use to define the text label that is displayed in the toolbar. If omitted, the Name value is used. Section/Item/Visible:Criteria – Use the Visibility element to specify if a shortcut button will be visible based on the results of a logical expression. You can use context values and global dictionary items. For example, for showing and hiding buttons which lead to updating customer records, you could include a Boolean interaction context value called ValidatedCaller and use one of the following: <Visible Criteria="ValidatedCaller"/> The default Criteria will evaluate to True and will be visible. Section/Item/MaxValue – Defines the maximum range of the rating indicator. For instance, if you enter 5, the range will be from one to five. You can set up any item on the 360 View to be a clickable shortcut, if you are using Studio version 7.1.63 or higher. Use these options to make an item clickable: ShortcutType – Use this option to specify the type of shortcut. Choose from these types of shortcuts:
ActivityName – If this is an Activity shortcut, enter the name of the activity that you want to start when the user clicks this item. Target – Enter the destination for the shortcut. For example, if the shortcut is a website, you enter the URL. If the shortcut launches an executable file, enter the name of that file. Project – If this is an automation shortcut, enter the name of the project that contains the automation. If the project name contains a space, replace the space with an underscore. For instance, My Project should become My_Project. AutomationName – For automation shortcuts, enter the name of the automation that you want to start when a user clicks the item. If the automation name contains a space replace, it here with an underscore. For instance, My Automation should become My_Automation. Note: The automation should have an entry point and you can pass parameters into the entry point if needed. Params – Use this option to pass parameters into automation. Only use this option if you chose Automation as the Shortcut type. The parameters should be a comma-delimited list that is represented as a single string. Keep in mind that the parameters are passed into the automation in the order as they appear in the list. You can use these keywords inside the params string:
The parameters will be listed as a string and can be enclosed in either quotation marks (" ") or apostrophes (‘ ’). If you are passing a string literal as a parameter to an automation, then it should be enclosed in apostrophes and the parameter list would then be enclosed in quotation marks, or vice versa. Use regular HTML entities for other special characters if there is a XML syntax error. Also note that if there is no active interaction, Context. and Interaction.ActiveKey are passed as null values. Notes plug-in settings This plug-in lets you add predefined notes, manually enter notes, and review the historical notes for an interaction. The name of this plug-in is Notes. Section/Item:Name – Specifies the name of item to add to the plug-in. Section/Item:IsActive – Determines whether the template is displayed on a menu. Section/Item:Content – Specifies the name of the context value (defined in the Context section) used to populate this item. As the associated context property value changes, this item is automatically updated. Section/Item/Activity – Defines the activity that will occur. You must define this activity in the Activities section. Config/TimeZone – Specifies the time zone you want to use to format dates for notes. Config/LineBreak – Specifies the line break format for notes. Config/NoteCharacterLimit – Specifies maximum number of characters allowed per note. The Enter key will be counted as provided by the Linebreak Setting. If this element is left blank or removed, no character limit is enforced. Here’s an example of the settings for the Notes plug-in: <Plugin
name="Notes" isActive="true" hasExtendedView="true"
canHide="true" enableWithNoActiveInteraction="false"> The NoteTemplates section contains predefined notes that reference context values. For example: “<Content>Call with {{ClientFullName}} started</Content>” would become Call with Ed Ricketts started if Ed Ricketts was the value defined for the current interaction in the ClientFullName context . The NotesConfig section contains values that determine how long and how many notes appear. maxNotesToReturn – Use to specify the maximum number of notes you want shown in the historical notes display. maxDaysToReturn – Use to specify the time range from which to pull historical notes. For instance, if you only want to see notes from the past two weeks, you would enter 14. Shortcuts plug-in settings The name for this plug-in is Shortcuts. Place the items for the Shortcuts plug-in under a section element. Here is an example: <Plugin
name="Shortcuts" isActive="true" hasExtendedView="false"
canHide="true" enableWithNoActiveInteraction="true"
Label="Quick Links"> Label – Use to define the heading text that is displayed for this section. The default is Quick Links. config/Layout – Lets you determine how shortcuts are displayed. You have the following options. 2 – Indicates
a two-column layout. config/VisibleRows – Use this setting to specify the number of shortcut rows you want to appear. The default is two (2) rows. Section/Name – Specifies the name of the shortcut section. This description does not appear in the Agile Desktop user interface. Section/Item:Name – Enter the text you want to appear on the shortcut button. This will appear on one row, centered vertically. Section/Item:RowOneLabel – This defines text that is displayed on the upper half of the shortcut button. This is an alternative to Name attribute. Section/Item:RowTwoLabel – This defines text that is displayed on lower half of the shortcut button. This is an alternative to Name attribute. The sections add structure to the Interaction.xml file and are required. The ShortcutType attribute defines the type of shortcut and affects which other attributes are required. ShortcutType – Defines the type of shortcut. You can choose from the following options.
Use these item element attributes to define individual shortcuts: ActivityName – For Activity shortcuts, enter the name of the shortcut. This name is displayed on the button. Note: To have the name appear on two rows, use the RowOneLabel and RowTwoLabel attributes. DropdownType – Use the DropdownMenu type for the ShortcutType attribute in the Interaction.xml file. You can use this option to display a pop-up menu when it is clicked. MenuItem - Defines the items that appear on the dropdown menu. Target – Enter the destination for the shortcut. For instance, if the shortcut is a website, you enter the Uniform Resource Locator (URL). If the shortcut launches an executable file, enter the name of that file. Project – For automation shortcuts, enter the name of the project that will run the automation. ActivityName – For Activity shortcuts, enter the name of the activity pressing the button should start. AutomationName – For Automation shortcuts, enter the name of the automation clicking the button should start. Params – For Automation shortcuts, enter a comma-delimited string to pass a parameters that will appear as separate items in an automation entry point. You can also pass in the interaction active key, global dictionary variables, and interaction context items from the active interaction. Section/Item/Enabled:Criteria – Use this option to specify if a shortcut button should be enabled based on the results of a logical expression. You can use context values and Global dictionary items in the expression. For example, to enable buttons which which let users update customer records, you could include a Boolean interaction context value named ValidatedCaller and use one of the following: <Enabled Criteria="ValidatedCaller"/> The default Criteria will evaluate to True and will be visible. Note: Be careful when using this option. Buttons that appear and disappear can confuse users. Note too the difference between enabling and disabling shortcut buttons and hiding or showing them. Disabled buttons are simply grayed out but retain their position in the list of shortcuts. Hidden buttons do not appear and do cause the list of shortcuts to reflow. Plugin/Section/Item/DropdownType – Use the DropdownMenu type for the ShortcutType attribute in the Interaction.xml file. You can use this option to display a pop-up menu when it is clicked. Plugin/Section/Item/MenuItem – Use to specify a pop-up menu item inside the DropdownMenu element. |
|
InteractionManager plug-in settings This plug-in displays a list from which you can select the active interaction. close an interaction, and optionally start an interaction. This plug-in includes these specific settings: section/Item/Context Name – Enter the context property you want to use in the list from which the end user will select an active interaction. For instance, if there is a context property named ClientFullName and you want your end users to select an interaction based on the client's name, you would enter ClientFullName here. config/EnableStartInteraction – Enter True if you want to show a plus (+) button to let the user manually start an interaction. The default is False. Here is an example: <Plugin name="InteractionManager"
isActive="false" showOn="360AppBar"> StartInteraction plug-in settings This plug-in displays a modal dialog inside the plug-in that lets you start a new interaction and includes these specific settings: enableWithNoActiveInteraction – Enter True if you want to display the StartInteraction dialog when no interactions exist. config/label – Enter the text you want to appear on the dialog's heading This text should describe what the user needs to do to start a new interaction, such as Enter Claim Number. config/project – Enter the name of the project that contains the automation which starts a new interaction. config/automation – Enter the name of the automation which starts a new interaction. This automation can validate user input and initiate a new interaction by calling InteractionManager.StartInteraction(). config/defaultErrorMessage – Enter the text of the message you want to display if an error occurs while starting an interaction and the start interaction automation does not return error text. If the automation does not define the error message and you omit this option, Agile Desktop displays this message: Unable to start interaction Here is an example: <Plugin name="StartInteraction"
isActive="false" enableWithNoActiveInteraction="true"> |
Privacy | Trademarks | Terms of Use | Feedback
Updated: 18 June 2020
© 2016 - 2020 Pegasystems Inc. Cambridge, MA All rights reserved.