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 2010\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. For numeric values, enter C to format the number as currency. Omit this property 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 property to specify a default value. The property is populated with this value when an interaction is created. If there is no default, define this tag as shown here:

Default=""

Here is an example:

<Value Name="ClientFullName" Type="String" Default="" />
<Value Name="Penalties" Type="Number" Format="C" Default="0"/>
<Value Name="TotalDue" Type="Number" Format="C" Default="0"/>
<Value Name="EligibleForUpgrade" Type="Boolean" Default="false"/>
<Value Name="EligibleForUnlimited" Type="Boolean" Default="false"/>

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.

Name – Provides a  descriptive name of an activity.

Value – Specifies the parameters and properties of an activity.

Type – Specifies the type of the Value, such as Boolean or String.

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">
   <Value Name="CustomerId" Type="String" />
   <Value Name="EffectiveDate" Type="Date" />
</Activity>

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:

  • 360 View – Provides access to key customer information at a glance.

  • Notes – Lets you add notes and search historic notes.

  • Shortcuts – Provides buttons to launch an executable, go to a web site, start an automation, or start an activity.

Generic Plug-in Settings

For all plug-ins, you have these 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 these 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.

defaultErrorMessage –  Use this option to specify the content of an error message. 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">
     <config>
       <project>AgileDesktopInteraction</project>
       <automation>StartInteraction</automation>
       <defaultErrorMessage>
Your message text</defaultErrorMessage>
     </config>
   </Plugin>
 </Plugins>

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:

Identity
Ratings
Custom
Balances
Eligibility
Information

Section/Item name – Indicates the name of item to add to the plug-in.

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 property value changes, this item is automatically updated.

Section/Item/Label – Defines the text label that appears to left of the value in the toolbar. If the Label is not defined, the value you entered for Name is used.

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.

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/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. This activity must be defined in the Activities section.

Here’s an example of the settings for the Notes plug-in:

<Plugin name="Notes" isActive="true"  hasExtendedView="true"  canHide="true" enableWithNoActiveInteraction="false">
  <section name="NoteTemplates" visibility="None" >
     <Item name="CallStarted" isActive="true" >
         <Content>Call with {{ClientFullName}} started</Content>
     </Item>
     <Item name="InformDueAmount" isActive="true">
         <Content>Informed of {{TotalDue}} due amount</Content>
     </Item>
     <Item name="Hided Note" isActive="false">
         <Content>This is hide</Content>
     </Item>
     <Item name="Note With Activity" isActive="true">
          <Content>Note added with the validate caller activity</Content>
          <Activity>ValidateCaller</Activity>
     </Item>
  </section>
  <config>
         <TimeZone>GMT-5</TimeZone>
          <MaxNotesToReturn>100</MaxNotesToReturn>
          <MaxDaysToReturn>365</MaxDaysToReturn>
          <LineBreak>\r\n</LineBreak>
  </config>
</Plugin>

The NoteTemplates section contains predefined notes that reference context values. For example:

 “Hello {{ClientFullName}}”

would become Hello Ed Ricketts 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 are 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 tag. Here is an example:

<Plugin name="Shortcuts" isActive="true"  hasExtendedView="false"  canHide="true" enableWithNoActiveInteraction="true" Label="Quick Links">
  <config>
     <Layout>3</Layout>
  </config>
  <section name="Links" visibility="Primary">
     <Item Name="Validate Caller" ActivityName="ValidateCaller" ShortcutType="Activity"/>
     <Item Name="OpenSpan Web Site" Target="http://www.openspan.com/" ShortcutType="URL"/>
     <Item Name="Send Alert" Project="AgileDesktopTest" AutomationName="Alert" ShortcutType="Automation"/>
     <Item Name="Notepad" Target="Notepad" ShortcutType="External"/>
  </section>
</Plugin>

Label – Use to define the heading text that appears for this section. The default is Quick Links.

config/Layout - Lets you  determine how shortcuts are displayed. You have these options:

2 –  Indicates a two-column layout.

3 –  Indicates a three-column layout.

The sections add structure to the interaction.xml file and are required. The ShortcutType tag defines the type of shortcut and affects which other tags are required.

ShortcutType – Defines the type of shortcut. You can choose from these options:

  • Activity

  • URL

  • Automation

  • External (program)

Use these options to define individual shortcuts:

Name – Enter the name of the shortcut. This name appears on the button.

Target – Enter the destination for the shortcut. For instance, if the shortcut is a web site, 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.

 

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">
 <section name="selector" visibility="Primary">
   <Item name="InteractionName" >
      <Context Name="ClientFullName" />
      <Label/>
    </Item>
 </section>
 <config>
    <EnableStartInteraction>true</EnableStartInteraction>
 </config>
</Plugin>

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 OpenSpan 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.

Here is an example:

<Plugin name="StartInteraction" isActive="false" enableWithNoActiveInteraction="true">
 <config>
    <label>Enter Claim Number</label>
    <project>AgileDesktopTest</project>
    <automation>StartInteraction</automation>
    <defaultErrorMessage>Unable to start the interaction.</defaultErrorMessage>
 </config>
</Plugin>