Automated Task Elements

This article contains the following topics:
casm172
This article contains the following topics:
You create automated tasks by defining steps in an automated process. Automated tasks predefine routines with specific actions on the end-user computer without the need for the analyst or end user to do the process. Common routines include gathering telemetry information, diagnosing problems, and implementing resolutions.
An automated task consists of the following elements:
  • Task Settings
    Specifies the title, description, dimensions of the step windows, HTML headers and footers, and a CSS style sheet applied to the end-user interface.
  • Dependencies
    Specifies the libraries and static content items that the task depends on, such as images or CSS files.
  • Task Steps
    Specifies the executed code for each step. You can author steps by selecting automated task step templates and modify them to fit your needs.
  • Security Settings
    Specifies the appropriate security settings to run the automated task on an end-user computer, such as read/write permissions, registry privileges, and so on.
  • XSDF Files
    Specifies automated task definitions saved to an XML schema in XSDF files (XML Script Definition Format). The XSDF file contains all automated task settings, dependencies, security settings, and step code information.
    If the automated task is dependent on a particular library, the full script code of that library is written to the XSDF file, not only the dependency information. Dependencies are also imported when XSDF files are loaded into the Automated Task Editor or imported into CA SDM, unless a later version of the same dependent library exists in the target environment. The same is true for dependent static content. Script libraries can also be saved on their own to XSDF files for distribution between systems.
The editor lets you define CSS styles for all automated task elements. You can control the appearance by using CSS Styles.
Example Default CSS Styles
The following CSS styles are defined by default.
If you use a custom CSS file, you can override the default values.
#header {                 padding: 2px 8px;                 font-size: 16pt;                 font-weight: bold;                 border-bottom: 2px solid green; } #title {                 background-color: #eee;                 padding: 2px 8px;                 font-size: 12pt;                 font-weight: bold;                 border-bottom: 1px solid green; } #content {                 padding: 8px; } #buttons {                 background-color: #eee;                 border-top: 1px solid green;                 text-align: right;                 padding: 2px 8px; } #buttons input {                 font-family: Verdana;                 font-size: 10pt; } #footer {                 border-top: 2px solid green;                 padding: 2px 8px;                 font-size: 9pt; }
The supplied HTML components declare a CSS Style for an HTML DIV that encloses the component. This declaration allows all elements of the components to be styled through CSS.
The name of this style can usually be set through automated task step template properties for steps that use these HTML components.
Task Object Reference
The task object is directly referenced as Task [e.g., Task.End();]
Methods
Task
Description
End()
Ends the Task immediately.
GetNamedDataItem(key)
Returns the value previously stored with the specified key.
SetNamedDataItem(key, value)
Stores the value against the specified key. These values can be stored in one step and accessed in another using GetNamedDataItem(). The specified value can be JavaScript primitive type (number, boolean, string) or an object or an array of objects. In VBScript, only primitive types can be stored.
GetNextElementId()
Returns a unique identifier that can be used for HTML DOM objects.
GetPageBodyElementById(id)
Returns the HTML DOM object corresponding to the specified ID.
ReplaceDataItems(string)
Returns a copy of the specified string with all instances of stored data items in the format ${key} replaced by their stored values.
CloseIEWindow()
Closes the UI window if it is open.
 
Properties
Property
Description
Title
The title of the automated task.
HeaderHtml
The HTML placed in the header section of the UI window.
FooterHtml
The HTML placed in the footer section of the UI window.
Height
The height, in pixels, of the UI window.
Width
The width, in pixels, of the UI window.
NextStepIndex
The index (0-based) of the next step to be executed.
Step Object Reference
The step object is directly referenced as Step [e.g., Step.End();]
Methods
Step Object
Description
End()
Ends the step immediately. The next step will be invoked.
Controls.Add()
Adds a string or HTML component to the UI content. Strings are automatically converted to Label HTML components.
GetProperty(propertyKey)
Returns the value of the specified property key for the current localization. If no value exists for the current localization, the value of the property in the default localization will be returned.
SetProperty(localizationID, propertyKey, value)
Sets the value of the specified property to the specified value for the specified localization ID.
RegisterEventHandler(controlId, eventHandler, tag)
Registers the specified event handler as the function to be invoked when the IE window's raiseUIEvent(controlId) function is called. Any data passed as tag will be made available when the event handler is dispatched as Step.EventData.
IsUIStep()
Returns true if the current step is a UI step; false otherwise.
 
Properties
Property
Description
Title
The title of the step - displayed in the UI header section.
NextButtonLabel
The label for the "Next" button. Defaults to "Next".
NextButtonVisible
True to show the "Next" button. False to hide it.
PreviousButtonLabel
The label for the "Previous" button. Defaults to "Previous."
PreviousButtonVisible
True to show the "Previous" button. False to hide it.
FinishButtonLabel
The label for the "Finish" button. Defaults to "Finish."
FinishButtonVisible
True to show the "Finish" button. False to hide it.
EventData
When a UI event is raised (by calling raiseUIEvent() from HTML within the IE window) the event handler function previously registered with RegisterEvenHandler() is invoked. The data stored as the "tag" when the event handler was registered will be available as Step.EventData when the handler is dispatched.
 
Logger Object Reference
The Logger object is accessed as Trace.Framework.
Example:
Trace. Framework.Level = TraceLevels.Info
Trace.Framework.Error("An error has occurred")
Methods
Logger Object
Description
Fatal(msg)
Log the specified message if the current trace level is set at Fatal, Error, Warning, Info, Debug, or Verbose.
Error(msg)
Log the specified message if the current trace level is set at Error, Warning, Info, Debug, or Verbose.
Warning(msg)
Log the specified message if the current trace level is set at Warning, Info, Debug, or Verbose.
Info(msg)
Log the specified message if the current trace level is set at Info, Debug, or Verbose.
Debug(msg)
Log the specified message if the current trace level is set at Debug or Verbose.
Verbose(msg)
Log the specified message if the current trace level is set at Verbose.
 
Properties
Property
Description
Level
The current trace level. Set to one of the values in the TraceLevels enumeration (None, Fatal, Error, Warning, Info, Debug, or Verbose).
 
Global Functions
The following global functions are used in Support Automation procedures.
Function
Description
AnyArrayToVBArray(array)
Converts any array (VBScript or JavaScript) to a VBArray. Arrays in JavaScript are different objects to VBScript arrays so it is necessary to convert between them.
AnyArrayToJSArray(array)
Converts any array to JavaScript array.
CreateHashMap()
Returns an object that can be used as a hashmap for storing arbitrary data (key/value pairs). The returned object implements the following methods:
 
Get(key) - Returns the value stored against the specified key.
 
Set(key,value) - Stores the value for the specified key.
 
GetAllKeys() - Returns an array of the keys.
 
Automated Task Step Templates
Automated task step templates are the script code for a given automated task step that can also define automated task step properties. You can customize the behavior of the automated task step template by changing the values of automated task step properties in the property sheet. You can accomplish more extensive customization by editing the code directly, but the intent is to minimize the amount of coding you do.
Steps are end-user action steps or user interface steps that show either to the end user or analyst. The automated task step templates are either end-user action, analyst interface, or end-user interface templates. CA Technologies provides automated task step templates, both action and user interface, to form the building blocks of tasks and enable you to create functional automated tasks with minimal coding.
For steps that define properties, you are prompted to provide values for these properties when the step is first created from the template. You can modify these values using the property sheet.
User Interface Steps
All user interface steps must implement an OnLoad function called by the framework before the step is displayed. The OnLoad function sets up the user interface. The step object exposes several properties and methods that you can use to set up the user interface.
You can control the visibility of the buttons on the step footer using Step.NextButtonVisible, Step.FinishButtonVisible, and Step.PreviousButtonVisible. When you set these properties to True, it makes the button appear. If a button is shown, a handler must be implemented for it. You can add the actual user interface controls to the page body using HTML components.
Example Text Input Box as an HTML Component
The step object has a controls array that is populated with a series of HTML components. These script objects render in HTML, and when the framework renders a user interface page, each HTML component in its controls array renders itself and adds the returned HTML fragment to the HTML body of the page.
HTML components let you write complex user interfaces without extensive HTML knowledge. Using an HTML component, you can create and configure commonly used controls with minimal coding.
Example: Text Input box as an HTML Component
An example of an HTML component is a text input box. The following example combines a label called PromptText and an HTML input box. If you want to prompt the customer or technician to supply a user name for example, the user interface page is constructed in an OnLoad function as follows:
Function OnLoad Dim myInputBox Set myInputBox = UI.MakeInputBox() myInputBox.PromptText = "Please enter your name:" Step.Controls.Add(myInputBox) End Function
CA Technologies supplies samples, but you can also create custom HTML components. An HTML component is a script object that implements a method called GetHtml. Here, for example, is the implementation of that
MakeInputBox()
method call used in the previous example:
function InputBox() { // public properties this.PromptText = ""; this.CssClass = "UIInputBox"; this.InputMaxLength =50; this.InputSize = 50; // private member props var textboxId = Task.GetNextElementId(); // privileged methods // (For example, publicly accessible with access to private props) this.GetHtml = function () { var inputHtml = "<DIV class = '" + this.CssClass + "'>\n"; if(this.PromptText.length>0) { inputHtml += "<SPAN class ='PromptText'>" + this.PromptText + "</SPAN>\n" + "<BR>\n"; } inputHtml += "<INPUT type = text class = 'InputText' id = '"+textboxId+ "' size = '"+this.InputSize+ "' maxlength='"+this.InputMaxLength+"'></INPUT>" + "<BR><BR>\n" + "</DIV>\n"; return inputHtml; } this.GetUserInput = function() { var textBox = Task.GetPageBodyElementById(textboxId); if (textBox) { return textBox.value; } else { throw new Exception (Severity.Error, "Could not read textbox value", "Could not read textbox value"); } } } return new InputBox();
This automated task library function defines a constructor for an object of type InputBox. The last line of the function constructs an instance of the InputBox class and returns it.
Object definitions differ in JavaScript and VBScript. In VBScript, the class keyword is used to declare a class. In JavaScript the function keyword declares the class, because in JavaScript functions are objects. Both languages let the class have public and private member variables and methods. A full description of how object syntax is handled in the two languages is beyond the scope of this chapter, but the internet can provide examples and tutorials on this subject.
In the example above, the code declares the InputBox class with some public and private properties and two public methods, GetHtml and GetUserInput.
The Framework calls GetHtml when rendering user interface steps. The InputBox control also exposes GetUserInput which you can use to access the value that the end user enters into the text box. Each HTML component can expose different methods for configuring it and accessing any user input values.
The HTML coding is abstracted from you by these HTML components so that creating user interface pages is simplified.
You can write your own HTML entirely for a particular automated task. In such a case, you have two choices: Write a new HTML component for the case you require, or construct the HTML code in a string variable and wrap it in a special HTML component called RawHTMLContainer as follows:
Function OnLoad Dim myRawHtmlContainer, myHtml myHtml = "<H1>Hello <B>World</B></H1>" Set myRawHtmlContainer = UI.MakeRawHtmlContainer(myHtml) Step.Controls.Add(myRawHtmlContainer) End Function
Example End-User Input Handling
After the user interface page displays, in many cases it is necessary to handle end-user input when the user clicks one of the footer buttons, such as Next, Previous, or Finish. You implement handler functions to handle end-user input. You implement a function named
NextButtonHandler
to handle the clicking of the Next button. You can use the
PreviousButtonHandler
and
FinishButtonHandler
functions to handle the Previous and Finish buttons.
The handler performs the following actions:
  • Retrieves input data from HTML components on the page
  • Validates the end-user input
  • If end-user input is invalid, display an error message and refresh the page
  • If end-user input is valid, logs stores it for use in a later step
  • Controls the sequence of step execution
Example: End-User Input Handling
HTML components that wrap input controls, such as the InputBox component, expose methods to access the values supplied by the end user. In this case, the
GeUserInput()
function is exposed.
You can control the next step that the framework presents as follows:
  • Return True from the handler to present the default next step (currentStep+1 for NextButtonHandler, currentStep-1 for PreviousButtonHandler, end the automated task for FinishButtonHandler).
  • Return False from the handler to refresh the current step.
  • Set Step.NextStepIndex to the step index (1 based) to skip or repeat steps.
You can handle the Next button being clicked by supplying a NextButtonHandler. Because the NextButtonHandler has to access the HTML component that was created in the OnLoad, the declaration (Dim statement) of this variable is placed outside these functions. Thus, the entire step code would look as follows:
Dim myInputBox Function OnLoad Set myInputBox = UI.MakeInputBox() myInputBox.PromptText = "Please enter your name:" Step.Controls.Add(myInputBox) End Function Function NextButtonHandler Dim userInputValue ' Retrieve the data supplied by the user userInputValue = myInputBox.GetUserInput() ' Validate the data If Len(userInputValue) = 0 Then ' Show error message Functions.ShowMessage "You must supply a name" ' Re-present current step NextButtonHandler=False Else ' Log the data Functions.LogMessage "User name set to: " & userInputValue ' Store the data Task.SetNamedDataItem "UserName", userInputValue ' Proceed to next step NextButtonHandler=True End If End Function