Create a Custom Activity for a Desktop Application with Designer

Aternity Activity Designer is a visual tool for creating custom activities for desktop and mobile applications without requiring any programming knowledge. Designer enables you to pinpoint the UI events that mark the start and end of your new activity.

For example, if you receive user complaints about the time it takes to open the Outlook address book, use the Aternity Recorder to record users opening the address book in different ways, bookmarking each. Then, transfer the recording to Designer and create a custom activity based on the start and end events for opening the address book.

Create an activity, upload it to Aternity, and distribute it to monitored devices

You can ensure that the custom activity captures the right events by using Designer to refine the event's literal definitions (properties) and parameters (details). A literal is an exact description of an event which you want to capture to mark the start or end of your activity. A literal contains event properties along with details of those properties. Edit the properties and details in Aternity Activity Designer, to accurately define your custom activity. When a user performs an activity on a monitored device, if the literals of the start and end events match the literals picked up by the Agent, it reports the activity to Aternity.

For example, configure the literals of a LeftMouseClick start event so that it applies to a click on To... for an email that has any title, rather than the specific title captured in the recording.

The Designer

When you've completed the creation of the activity, use Designer to generate a signature. A signature is an XML file created in the Aternity Activity Designer, which contains the core definition of a custom activity, including its start event and end event.

When you upload a custom activity to Aternity and distribute it to monitored devices, the Agents listen for OS events that match the activity. An Agent only reports an activity and its performance data if there is a match between the application's events and those that you defined for the activity.

You can create custom activities for web applications using Designer, if you record the activities in Google Chrome with the Aternity Extension for Chrome. The events appear in the Designer's HTML tab.

Tip

While you can use the Designer also for web applications, we recommend using the Aternity Web Activity Creator (learn more) for a more interactive experience.

Before you begin

  • Define the business transaction that you want to assess. Learn more.

  • Use the Aternity Recorder to record a user performing the business transaction, where the device had Agent for End User Devices 9.x or later. Learn more.

  • Transfer the recording to the Designer.

Procedure

  1. Step 1 Download and extract the latest version of Designer from the Riverbed Support Site.
  2. Step 2 Open Designer by double-clicking <extracted folder>\Aternity Designer <version>\Activity Designer.
    Launch Aternity Activity Designer
  3. Step 3 Add a new application by right-clicking My Library and selecting New Application.
    Create a new app in Designer

    Enter a unique name for the application, for example, Microsoft Outlook.

  4. Step 4 Load your recording of the business transaction by right-clicking the application and selecting Load Recording.

    Designer displays the video and a list of events, with detailed fields for each event. The literal properties also refer to these fields.

    For example, you can load a recording of a user opening the Outlook address book.

    Add a recording to the Designer
    Field Description
    #

    Displays the sequential number assigned to the OS event by Designer

    Timestamp

    Displays the time at which the OS event took place.

    Event

    Displays the type of OS event, for example:

    • For a left mouse click on the To... button, the event is LeftMouseClick.

    • For a window completion, the event is ObjectShow.

    • For using a keyboard shortcut to Bcc..., the event is KeyPress.

    Role

    Displays the element in the Windows framework which caused this event to occur:

    • For a mouse click on the To... button, the role is push button.

    • For a window completion, the role is window.

    • For using a keyboard shortcut for Bcc..., the role is text.

    Name

    Displays the UI label of the object associated with this OS event, for example:

    • For a mouse click on the To... button, the name is To....

    • For a window completion, the name of the object is the name of the window, such as Select Names: Global Address List.

    • For using a keyboard shortcut for Bcc..., the name is Bcc...

    Value

    Displays the value associated with this OS event. For example:

    • When you open an email, a series of ObjectValueChange events have values equal to the time the mail was sent, the subject, and the name of the sender.

    • When you save a new file and type its name, a series of ObjectValueChange events have the value of that name, showing one additional character in each event.

    Window Title

    Displays the title of the window containing the object. For example, Adam.Covert@riverbed.com - Outlook.

    Window Class

    Displays the name or number of the Windows class for the main window in focus when the OS event took place. For example:

    • For a mouse click on the To... button, the window class is rctrl_renwnd32.

    • For a window completion, the window class is #32770.

    • For using a keyboard shortcut for Bcc, the window class is rctrl_renwnd32.

    Event Class

    Displays the class of the object where the OS event takes place. For example, Button for an event associated with a button.

    Key Code

    Displays the Unicode value and friendly name of a key that the user pressed, if they pressed a key. For example, 13 (enter).

    Modifiers

    Displays a key press modifier such as Control or Shift if one was pressed by the user before pressing another key or clicking with the mouse.

    State

    Displays the status of the OS event, for example:

    • For a mouse click on the To... button, the state is rctrl_renwnd32.

    • For a window that is complete, the state is #32770, whereas read only indicates that the user cannot yet interact with the window.

    • For using a keyboard shortcut for Bcc, the state is rctrl_renwnd32.

    App Name

    Displays the name of the application in which the event took place, such as Microsoft Outlook

    Process Name

    Displays the application's process name, such as Outlook.exe.

  5. Step 5 Select one of your video bookmarks from the drop-down list.

    The bookmarks are listed in the order in which you created them. When you select a bookmark, Designer focuses on that portion of the video and the related events.

    Narrow the scope of events with a bookmark

    In this example, select the Left Mouse Click To bookmark, to find a start event for opening the address book by clicking To....

  6. Step 6 Play the video from the beginning of the bookmark until you locate the approximate moment where the user begins the activity, and then pinpoint the start event in the events list.
    Field Description
    Play

    Select to play the video.

    You can also use the keyboard shortcut ctrl + spacebar

    Step forward

    Select to step forward one video frame, which is 0.1 seconds long and may include many events.

    You can also use the keyboard shortcut ctrl + right arrow

    Step backward

    Select to step backward one video frame.

    You can also use the keyboard shortcut ctrl + left arrow

    For example, to create an activity that measures how long it takes to open the address book, start by looking at the video to see where the user selects the button that actually opens the address book. If the user opens a new email and then selects the To button, skip over the opening of the email. In general, ignore the irrelevant user interaction and focus on the event itself.

  7. Step 7 Use the Designer filters to more easily find the right event.
    Field Description
    Show only user events

    Display only user-generated events (framed in blue) by right-clicking any event in the pane and selecting Show only user events.

    Typically, start events are user events, such as a mouse click or a key press, whereas complete events are usually OS events, such as ObjectShow.

    Limit the display to user events
    Clear Filters

    Select to remove all of the filters, so that Designer displays all of the events.

    Clear the filters to see all of the events
    Search events for...

    Display only the events containing the search string. For example, if you want to see only events that include a button push, search for push.

    Designer searches in the filtered list of events. To search the entire list, select Clear Filters and then search.

    Search for a string in your list of events

    Common user events are: LeftMouseClick, RightMouseClick, LeftMouseDoubleClick, and KeyPress.

  8. Step 8 Add the start event to the activity by right-clicking the event you identified as the start of the activity, and selecting Use Event as Start > New Activity.

    In the example, in the Left Mouse Click To bookmark, LeftMouseClick with a Role of push button and the Name To... is the event that starts the Open Address Book activity.

    Select the event that starts the activity
    Designer prompts you to create a new activity, and automatically gives it the same name as the bookmark. Change the name as needed.
    Create a new activity for the new application
    Note

    If you are creating an application event, select it as your start event. Then, drag the event hexagon into the Complete field and edit its contextuals.

  9. Step 9 Find the complete event in the video, right-click it, and select Use Event as Complete > <ActivityName> to add it to the activity.

    For example, click through the Open Outlook address book recording one video frame (0.1 seconds) at a time.The address book dialog appears in the video, but stays gray and unusable until the ObjectShow event, which marks the completion of the activity.

    Select the event that marks the completion of the activity
    Tip

    When you identify a potential complete event, ensure that it is unique. If it occurred previously and you choose it as your complete event, the Agent will report inaccurate data for the activity. To check for possible duplicate events, right click the event and select Show Only The Same Events. Designer displays your potential complete event, and any other events in the bookmark that have the same properties.

  10. Step 10 Add additional start events by choosing each bookmark, right-clicking the start event you identify, and selecting Use Event as Start > <Activity Name>.
    Add start events to your existing activity
  11. Step 11 Select an activity in the left pane to see its visual representation and definition.
    View the anatomy of the activity, where each event is a hexagon.

    The visual pane has six sections:

    Field Description
    Start

    Displays one or more events (light green hexagons) that indicate the user has started the activity. For example, displays several different key presses and mouse clicks on different buttons.

    Any one of the start events indicates that the activity is starting, as indicated by the Any label.

    Any one of the events starts the activity
    Complete

    Displays events (dark green hexagons) that indicate that the activity is complete, for example, the successful rendering of a window or the appearance of a success notification.

    If there is more than one event that indicates that the activity has completed, you can select:

    • Any to indicate that either event marks the completion of the activity.

    • All to indicate that all of the events must take place to mark the completion of the activity.

    Choose any or all for the end of the event
    Incomplete

    Displays events (gray hexagons) that indicate that the activity did not complete successfully, for example, if the user selected Cancel. The Agent does not report incomplete activities. The incomplete activities are created automatically by Designer.

    Any one of the events indicates that the activity is incomplete.

    Identification

    (Optional) Displays events that help the Agent uniquely identify the activity.

    For example, your application may have an OK button to start several different activities. Add context so that the Agent detects the activity's unique Save event.

    You can assign multiple events to Identification, which the Agent must detect in chronological order to identify the event.

    Identification events must occur in order, top to bottom
    Sandbox

    Stores events that you want to temporarily remove from an activity, so that you can test different configurations of the activity.

    Unavailable

    Displays events that indicate that the application is unavailable. We recommend that you not add events to this category without the assistance of Customer Services.

  12. Step 12 Select an event hexagon (literal) to view its properties, then select a property to view its details.

    A literal is an exact description of an event which you want to capture to mark the start or end of your activity. A literal contains event properties along with details of those properties. Edit the properties and details in Aternity Activity Designer, to accurately define your custom activity. When a user performs an activity on a monitored device, if the literals of the start and end events match the literals picked up by the Agent, it reports the activity to Aternity.

    View the UX properties (definitions) and their details (parameters)

    Each property of an event (described here) has a number of details, known as Literal Parameters.

    Field Description
    Auto fail-safe

    Displays that the Designer automatically assigned this event as an incomplete event.

    Every start event is marked by Designer as Auto fail-safe by default, and Designer creates a replicate incomplete event for that start event. Designer does this so that when a user quickly creates two start events, such as when they double-click a button, the Agent ignores the first click because that activity is incomplete, interrupted by the second click. This ensures that the Agent returns meaningful performance data, rather than data for the first click, which does not perform an activity.

    Incomplete after

    (Advanced users) Displays at what point in the activity the Agent should recognize an Incomplete event. You can choose to cancel an activity due to an incomplete event after a start event, after identification events have taken place, or after either start or identification.

    Match

    Displays whether the first or last possible complete event should be considered a match.

    For example, if a user saves a Word document, you can use an ObjectReorder event with a value of Status Bar as the complete event. However, as the status of the save operation proceeds, that event, in which the status bar is refreshed, can occur several times. When you select Last Event, the Agent waits three seconds, and if it detects another complete event, it ignores the previous one. If after three seconds there is not another complete event, it uses the last complete event as the end of the activity.

    Name

    The OS name for the event, such as Search or LeftMouseClick.

    Screenshot

    Displays the video screenshot at the moment the event takes place. Click the screenshot to enlarge it, and to add text to describe it. The screenshot and the text are added to the signature documentation.

    Show Removed Properties

    (Advanced users only) Select to display the properties that Designer automatically removed from the Literal Definitions.

  13. Step 13 Modify start and completion events so that they do not require a very specific match.

    Remove or modify references to items such as specific user names, device names, window titles, or servers that may have been captured by the Recorder. When you deploy the activity, too many specifics means the Agents will ignore a lot of activities.

    For example, the Window Title literal definition is Exact= Untitled - Message (HTML), because you recorded a user clicking To... in an untitled email message. This results in a match only when the user performs the activity in an email (not in a meeting request), only when working in HTML format, and only if they have not yet added a subject.

    If a user opens the address book here, the activity would not be reported

    If the user started the activity from a meeting window, or from an email with the subject Missed Activities, there would be no match and the Agent would not report the activity.

    Too exact a definition results in missed events
    1. a In the Literal Definitions > Window Title > Match one of, select Exact=Untitled - Message (HTML).
      Find a Literal Definition that is too specific
      Field Description
      Name

      Enter the string that the custom activity will use to identify the user event.

      String matching logic

      Displays how the activity will compare an event string with the custom activity.

      • Exact requires that the string on the button exactly match the string in the activity.

      • Substring requires that the string on the button contain the string in the activity.

      • Regex requires that the string on the button match the string in the activity using a regular expression pattern.

      Relation to other Titles

      Select whether to include this string as a positive or negative event for the match.

      • Match the above (OR) indicates that the string is one of the possible matches for the event.

      • Don't match the above (NOT) indicates that the string is not a match, and the event containing the string should be ignored. For example, if you want the activity to only detect the opening of the address book from emails, select this option for a Meeting substring.

    2. b Change the match string to be less specific, and change the String Matching Logic to Substring.

      For example, shorten the Untitled - Message (HTML) string to Message.

    3. c Right-click Literal Definitions > Window Title > Match one of > Add to add additional strings that can be part of the event.

      For example, add Meeting to the list of matches, and ensure that all of the strings are matched as substring, to capture the activities from meetings and emails, named and unnamed, HTML or plain text.

      Add other strings that can be matches

      Also in the example, the completion event may refer to the offline global address list (if the user was offline when recorded). Fix this in the Literal Definitions of the completion event, by generalizing the string, and requiring only substring match.

      Change the recording-specific matches to more generic matches
  14. Step 14 (Optional) Merge events that are very similar, to make the number of start events easier to edit if needed.

    Merge events by expanding the definition of one start event to include others, and then deleting those other events.

    For example, combine the start events of a mouse click on To..., Cc..., Bcc... and From....

    Select the start event of a left mouse click on To..., and in the Literal Definitions > Name, right-click Match one of > Add.

    Add the other strings that could match the name of the button, and set the String Matching Logic, which determines the exactness of the string matching approach. For example, add Cc..., and leave the String Matching Logic set to Exact.

    Repeat these steps to add all of the possible button names.

    All of the possible button names are listed

    Delete the start events that you merged into a single event, by right-clicking each event hexagon and selecting Delete.

    For example, having merged the Cc..., Bcc..., and From... events into the To... event, you can delete those three event hexagons.

    Delete the merged events
  15. Step 15 (Optional) Configure the activity to report custom contextual activity information that you want to gather.

    The contextual information appears in the User Experience dashboard when you hover your mouse pointer over a result in the Response Time, in Analyze dashboards as Breakdown and Filter options, and in advanced dashboards.

    Your contextual information appears in Analyze dashboards

    Select Project Explorer > My Library > <activity>, and then select the Contextuals tab.

    Select one of the available Contextual Parameters: Info 1, Info 2, or Title. You can rename these parameters, and the new names appear in Aternity dashboards. Aternity's REST APIs report this data using the default names.

    Select the activity to access the Contextuals tab

    For example, if you have a single start event for a left mouse click on either To..., Cc..., Bcc..., or From..., you may want to report which of those buttons was clicked.

    Field Description
    Activate

    -> Select to add one or more contextuals to this activity.

    UI Name

    Select to set the name used to display the information in the User Experience dashboard.

    Select Input Literal Parameter

    Enter which event will include the contextual information, and what information that activity will report.

    In the first field, select the event. In the second, choose from the list of information that is available to the event.

    In the example, the start event includes the name of the button. If you want to collect whether the user opened the address book from an email or a meeting request, choose LeftMouseClick push button and Name.

    Select the event and the information that the Agent should report
    Save in Raw Data

    Select to indicate to the Agent that Aternityshould store this information as raw data for eight days, and should not aggregate it.

    Important

    We strongly recommend that you always select this option. If you choose to collect custom information that is highly variable, such as customer IDs, and do not save it as raw data, Aternity aggregates the data for each customer, creating an enormous amount of aggregated data that is stored for a long time.

    The only situation in which you can safely leave this unselected is if you have a limited number of possibilities for the custom data. For example, you could collect data aggregated according to customers, resources, or financial reports.

    Manipulate String

    (For advanced users) Select to enable more complex manipulation of the context string using a Regex Expression.

    For example, if you are measuring performance of file saving in Microsoft Office, and want to return the file name in contextual information, but not the application name, use Manipulate String.

    Use a regex expression to modify what contextual information the Agent reports
    Note

    For application events, Info1 displays in the Category field in Aternity dashboards. Use this to categorize an application usage event, or to store the type of error in an application error event, or for other custom data. Info2), displays in the Details field. Use this to store the details of the event or error or other custom data.

    After you activate and configure the contextuals, generate the signature.

  16. Step 16 Validate the activity in the Designer.

    The Designer validation compares the functionality of your new activity to the events in the recording that you loaded previously. After the Designer validation, perform a Recorder validation, and then test in a test group. Learn more.

    1. a Right-click the recording and select Validate.
      Start the Designer validation
    2. b Enter the local path to an Agent for End User Devices .msi file which Designer uses to validate the activity.

      The file must match the version of the Agent running on the monitored device on which you made the recording.

      Provide the path to an Agent package

      If you do not have the right Agent package on the computer, use the link provided to download it.

      Note

      Designer requests this file the first time you validate an activity. This Agent file is used only by the Designer and does not report data to Aternity.

    3. c Select the activities to validate and then select Validate.

      Validate only the activities that take place in the recording.

      Select the recorded activities that you want to validate

      The validation pane presents the results. In the example, you successfully opened the address book by several mouse clicks and key presses, and the validation detected and reported complete activities, with activity response times.

      View complete and incomplete activities in the validation pane

      Select a complete activity from the validation results to move the video to its start event, and to highlight the start and complete events in the events list. Ensure that these are the right events for this instance of the activity, and see if the activity response time (shown in parentheses) has an expected value.

      Select a complete event to move the video to the start event, and to highlight start and complete events

      The Designer should capture all of the activities you intended to capture from the recording. For example, if you intended to capture a left mouse click on To..., and an Alt+b key press, and only receive one complete activity, you likely have an editing error in the other activity.

  17. Step 17 Generate the signature by right-clicking the activity and selecting Generate Signature (keyboard shortcut Alt+G).
    Generate the signature

    You can also generate signatures for all of the valid activities in an application by right=click the application and selecting Generate Signatures for All Valid Activities (keyboard shortcut Alt+Ctrl+G).

    Provide account details, which the Designer uses to customize the documentation for each signature you generate, and the directory in which you want to save the signature, <signature>.xml and the signature documentation, <signature>.html.

  18. Step 18 (Application events only) Manually remove the start event.
    1. a Open the file in a plain text editor.
    2. b Search for <States> and replace it with <States><act:State id="idle" type="start"/>.
    3. c Search for <act:Transition from="Start" id="Start-Complete" to="Complete"> and replace it with <act:Transition from="idle" id="idle-Complete" to="Complete">.
    4. d Save the file.
  19. Step 19 After you generate the signature, provide it to an Administrator of Aternity so that they can upload your custom activity to Aternity. Learn more.

    When you upload an activity, it is automatically assigned to a test group of monitored desktop devices.

  20. Step 20 Perform a Recorder validation. Learn more.