Advanced JavaScript support for Transaction Perspective scripts

Transaction Perspective Advanced Scripting allows JavaScript commands to exist inside Keynote Transaction Perspective scripts. Scripting functions are specific to the different browser versions supported by TxP:

Advanced JavaScript for Transaction Perspective scripts for Internet Explorer engine

These functions give customers and Keynote Support personal additional scripting abilities for scripts intended for the TxP Internet Explorer Engine. This functionality is similar to the support provided in Application Perspective.

Some of the capabilities of TxP Advanced Scripting Support are:

  • Programmatic access to the results of a navigation request (HTML source, request headers, response headers, etc.)
  • Execution workflow
  • Retry until successfully logged in
  • Always execute a logout page if error is encountered
  • Random link selection
  • Ability to override errors or generate custom errors.

Advanced scripting options

Advanced script can be executed in number of stages of transaction execution. Most of the functions and objects are accessible throughout the transaction execution.

Pre-transaction

Pre script advanced JavaScript is executed before the first action is executed.

Before action

Before action advanced JavaScript is executed before the first step in the action is executed.

After action

After action advanced JavaScript is executed after all the steps are executed and the completion events are satisfied. This would be just before the execution moves onto the next action, if any.

Step

Step advanced JavaScript is associated with the step. Advanced JavaScript associated with step could have a block of script. The script perform number of step activity within a single step.

Objects

IXMLDOMDocument2

DOMDocument2 is a representation of the top node of the XML DOM tree. This extension supports schema caching and runtime validation, and provides a way to switch on XML Path Language (XPath) support.

For more information on IXMLDOMDocument2, refer to http://msdn.microsoft.com/library/default.asp?url=/library/en-us/xmlsdk/html/832083b0-9400-48eb-aa3c-6447d4b55c91.asp.

IXMLDOMNode

Represents a single node in the XML document tree. IXMLDOMNode is the base interface for accessing data in the XML object model. This interface includes support for data types, namespaces, document type definitions (DTDs), and XML schemas.

For more information on IXMLDOMNode, refer to http://msdn.microsoft.com/library/default.asp?url=/library/en-us/xmlsdk/html/89337bfc-c5a7-44bc-9e98-cbf2363ac42c.asp.

WebBrowser control

WebBrowser control is a component of Internet Explorer browser; it provides access to browsing, document viewing, and data downloading capabilities. In Transaction perspective we control IE to perform the recorded transaction.Within Advanced JavaScript, we provide access to the WebBrowser control used while performing the script transaction. Custom navigation and checks can be performed directly by accessing the WebBrowser object.

For more information on WebBrowser control, refer to http://msdn2.microsoft.com/en-us/library/aa752127.aspx.

IHTMLDocument2

http://msdn2.microsoft.com/en-us/library/aa752574.aspx

This object represents the HTML document in a given browser window. Windows that contain HTML documents always have valid document objects; windows that contain documents in other formats might not have valid document objects.

For more information on IHTMLDocument2, refer to http://msdn2.microsoft.com/en-us/library/aa752127.aspx.

Scripter

Most of the features are accessed via this object. Some of the script steps can be executed programmatically by calling functions associated with this object. This object also provides access to the contents of the window and the frames within the windows. It also exposes the Web browser control which can be directly programmed via JavaScript. Scripter also provides direct as IHTMLDocument2 interface to identify specific HTML elements.

Functions supported by the scripter object

Logging
Internet Explorer
Script XML DOM
Variables
HTTP headers
Custom data
Error reporting

Function list

Logging
Log Method
Syntax Scripter.Log(str)
Description Adds the parameter to log file.
Parameters
  • str - String to log
Return value
Remarks

Example:

Scripter.Log("CurrentPage : " + cPage);       

Internet Explorer
GetWindowCount Method
Syntax Scripter.GetWindowCount ()
Description Returns the number of windows used in the engine so far.
Parameters
Return value

Example:

System.Log("GetWindowCount: " +  System.GetWindowCount())   

GetWebBrowser Method
Syntax Scripter.GetWebBrowser (windowIndex)
Description Returns the WebBrowser control object for a specific window.
Parameters
  • windowIndex - Zero-based index
Return value
Remarks

Example:

var val = System.GetWebBrowser(0);

GetWindowFrameCount Method
Syntax Scripter.GetWindowFrameCount (windowIndex)
Description Returns the number of frames in a specific window.
Parameters
  • windowIndex - Zero-based index
Return value
Remarks

Example:

var val = System.GetWindowFrameCount (0);

GetFrameWebBrowser Method
Syntax Scripter.GetFrameWebBrowser (windowIndex, frameIndex)
Description Returns the WebBrowser control object for a specific frame in the window.
Parameters
  • windowIndex - Zero-based index
  • frameIndex - Zero-based index
Return value WebBrowser control interface IWebBrowser2
Remarks

Example:

var val = System.GetWindowFrameCount (0,1);

GetHTMLDOM Method
Syntax Scripter.GetHTMLDOM (windowIndex)
Description Returns the HTMLDOMDocument2 object for a specific window.
Parameters
  • windowIndex - Zero-based index
Return value Returns HTMLDOMDocument2 interface.
Remarks

Example:

var val = System. GetHTMLDOM (0);

GetFrameHTMLDOM Method
Syntax Scripter.GetFrameHTMLDOM (windowIndex, frameIndex)
Description Returns the HTMLDOMDocument2 object for a specific frame in the window.
Parameters
  • windowIndex - Zero-based index
  • frameIndex - Zero-based index
Return value Returns HTMLDOMDocument2 interface.
Remarks

Example:

var val = System.GetFrameHTMLDOM (0,1);

Script XML DOM
CurrentPageNumber Method
Syntax Scripter.CurrentPageNumber
Description Returns the page number/ action that the script is executing.
Parameters
Return value
Remarks

Example:

var cPage = System.CurrentPageNumber();

GetCurrentAction Method
Syntax Scripter.GetCurrentAction
Description Returns the IXMLNode of the action being executed.
Parameters
Return value
Remarks

GetScript Method
Syntax Scripter.GetScript
Description Returns the IXMLDocumnet2 of the script being executed.
Parameters
Return value Returns IXMLDocumnet2 interface
Remarks

Variables
GetSavedValue Method
Syntax Scripter.GetSavedValue(variablename)
Description Returns a string value, if any was saved under that name.
Parameters
  • variablename - Name to be used to retrieve
Return value
Remarks

Example:

System.GetSavedValue("URL");

SaveValue Method
Syntax Scripter.SaveValue (variablename, value)
Description Saves the value and it can be retrieved later using the variable name.
Parameters
  • variablename - Name to be used to retrieve
  • value - Value to be stored
Return value
Remarks

Example:

System.SaveValue ("URL",’http://www.google.com’);

GetVuserValue Method
Syntax Scripter.GetVuserValue(variablename)
Description Returns a string value, if any available in the VUser table associated with the variable name.
Parameters
Return value
Remarks

Navigate Method
Syntax Scripter.Navigate(windowIndex, frameIndex, URL)
Description Navigate the specified window to the URL specified.
Parameters
Return value
Remarks

Example:

System.Navigate(       1,
0,
"http://www.google.com/",
"header1:value1\r\nheader2:value2\r\nheader3:value3\r\n",
"");

Click Method
Syntax Scripter.Click (windowIndex, frameIndex, HTMLElement)
Description Clicks the element specified in HTMLElement within the window.
Parameters
  • windowIndex - Zero-based window index
  • frameIndex - Zero-based frame index
  • HTMLElement - IHTMLElement2 interface of the element
Return value
Remarks

Example:

System.Navigate(0,0,"http://www.google.com/");
// Code in next action after waiting for Download cycles
//
var doc = System.GetHTMLDOM( 0 );
var searchInputList = doc.getElementsByName("q");
var searchInput = searchInputList.item(0,0);
searchInput.value = "Keynote";
System.Text(1,0, searchInput,"Keynote1");
var butnlist = doc.getElementsByName("btnG");
var butn = butnlist.item(0,0);
System.Click(1,0, butn);

Select Method
Syntax Scripter.Select (windowIndex, frameIndex, HTMLElement,index)
Description Select the index specified in HTMLElement element.
Parameters
  • windowIndex - Zero-based window index
  • frameIndex - Zero-based frame index
  • HTMLElement - IHTMLElement2 interface of the element
  • index
Return value
Remarks

Text Method
Syntax Scripter.Text (windowIndex, frameIndex, HTMLElement, inputText)
Description Changes the value in the field with inputText for the specified HTMLElement element.
Parameters
  • windowIndex - Zero-based window index
  • frameIndex - Zero-based frame index
  • HTMLElement - IHTMLElement2 interface of the element
  • inputText
Return value
Remarks

Example:

System.Navigate(0,0,"http://www.google.com/");
// Code in next action after waiting for Download cycles
//
var doc = System.GetHTMLDOM( 0 );
var searchInputList = doc.getElementsByName("q");
var searchInput = searchInputList.item(0,0);
searchInput.value = "Keynote";
System.Text(0,0, searchInput,"Keynote1");
var butnlist = doc.getElementsByName("btnG");
var butn = butnlist.item(0,0);
System.Click(0,0, butn);

File Method
Syntax Scripter.File (windowIndex, frameIndex, HTMLElement, filename , size)
Description Set the filename and uploads the file specified  in the HTMLElement element. If the filename is not empty, it uses the filename. If the filename is empty, it create a file of the specified size and use that file for upload
Parameters
  • windowIndex - Zero-based window index
  • frameIndex - Zero-based frame index
  • HTMLElement - IHTMLElement2 interface of the element
  • filename - Filename
  • size - File size
Return value
Remarks

Script Method
Syntax Scripter.Text (windowIndex, frameIndex, script, language)
Description Executes JavaScript and AdvancedJavaScript(“Jscript”) in a specific window.
Parameters
  • windowIndex - Zero-based window index
  • frameIndex - Zero-based frame index
  • script - Script to be executed
  • language - Language of the script
Return value
Remarks

ImmediateCompletion Method
Syntax Scripter.ImmediateCompletion ()
Description The Action completes immediately after this call. The engine does not wait for completion of other completion events, if this function is called. This function can also be called from a DOM Script by calling window.external.ImmediateCompletion().
Parameters
Return value
Remarks

Example:

//Advance JavaScript
System.ImmediateCompletion();
// DOM Script Execution 
window.external.ImmediateCompletion();

HTTPHeaders

HTTPHeaders functions are based on the headers captured. This data is available only after the action is complete. Within the action, the headers captured by the action can be accessed in the script that executes after the action.

Example:

var cPage = System.CurrentPageNumber();
System.Log("CurrentPage : " + cPage);
System.Log("URL#: " + System.GetHTTPHeaderURLCount( cPage ));
System.Log("URLs: " + System.GetHTTPHeaderURLs( cPage ));
for( i = 0; i < System.GetHTTPHeaderURLCount( cPage ); i++)
{
url = System.GetHTTPHeaderURLforIndex( cPage,i );
System.Log("URL["+ i + "]: " + url);
System.Log("Req Headers["+ i + "]: " + System.GetHTTPRequestHeadersforIndex( cPage,i ));
System.Log("Resp Headers["+ i + "]: " + System.GetHTTPResponseHeadersforIndex( cPage,i ));
var host = "Host";
var cLen = "Content-Length";
System.Log("Req Headers[ "+ i + ", " + host + "]: " + System.GetHTTPRequestHeaderValueforIndex( cPage,i , host ));
System.Log("Resp Headers["+ i + ", " + cLen      + "]: " + System.GetHTTPResponseHeaderValueforIndex( cPage,i , cLen));
System.Log("Req Headers[" + url + "]: " + System.GetHTTPRequestHeadersforURL( cPage, url ));
System.Log("Resp Headers[" + url + "]: " + System.GetHTTPResponseHeadersforURL( cPage, url ));
System.Log("Req Headers Value [" + url + ", " + host + "]: " + System.GetHTTPRequestHeaderValueforURL( cPage, url, host ));
System.Log("Resp Header VAlue [" + url + ", " + cLen      + "]: " + System.GetHTTPResponseHeaderValueforURL( cPage, url, cLen ));
}

GetHTTPHeaderURLCount Method
Syntax Scripter.GetHTTPHeaderURLCount(pageIndex)
Description Returns the number of URLs captured for the page.
Parameters
  • pageIndex - One-based page index
Return value
Remarks

Example:

System.Log("URL#: " + System.GetHTTPHeaderURLCount( cPage ));

GetHTTPHeaderURLs Method
Syntax Scripter.GetHTTPHeaderURLs (pageIndex)
Description Returns a comma separated URL list captured for the page.
Parameters
  • pageIndex - One-based page index
Return value
Remarks

Example:

var val = CustomData. GetHTTPHeaderURLs (1);               

GetHTTPRequestHeadersforIndex Method
Syntax Scripter.GetHTTPRequestHeadersforIndex (pageIndex, urlIndex)
Description Returns HTTP Request headers for the page and URL index requested.
Parameters
  • pageIndex - One-based page index
  • urlIndex - One-based URL index
Return value
Remarks

Example:

System.GetHTTPRequestHeadersforIndex ( 1,1);

GetHTTPResponseHeadersforIndex Method
Syntax Scripter.GetHTTPResponseHeadersforIndex (pageIndex, urlIndex)
Description Returns HTTP Response headers for the page and URL index requested.
Parameters
  • pageIndex - One-based page index
  • urlIndex - One-based URL index
Return value
Remarks

Example:

System.GetHTTPResponseHeadersforIndex ( 1,1);

GetHTTPRequestHeaderValueforIndex Method
Syntax Scripter.GetHTTPRequestHeaderValueforIndex (pageIndex, urlIndex, headerName)
Description Returns HTTP Request header value for the header name based on page and URL index requested.
Parameters
  • pageIndex - One-based page index
  • urlIndex - One-based URL index
  • headerName - Header name
Return value
Remarks

Example:

System.GetHTTPRequestHeaderValueforIndex( 1,1 , “Host” )

GetHTTPResponseHeaderValueforIndex Method
Syntax Scripter.GetHTTPResponseHeadersforIndex (pageIndex, urlIndex, headerName)
Description Returns HTTP Response header value for the header name based on page and URL index s for the index requested.
Parameters
  • pageIndex - One-based page index
  • urlIndex - One-based URL index
  • headerName - Header name
Return value
Remarks

Example:

System.GetHTTPResponseHeaderValueforIndex ( 1,1 , “Content-Length” );

GetHTTPRequestHeadersforURL Method
Syntax Scripter.GetHTTPRequestHeadersforURL (pageIndex, url)
Description Returns HTTP Request headers for the page index and URL requested.
Parameters
  • pageIndex - One-based page index
  • url - URL string
Return value
Remarks

Example:

System.GetHTTPRequestHeadersforURL( 1, “http://www.google.com/” );

GetHTTPResponseHeadersforURL Method
Syntax Scripter.GetHTTPResponseHeadersforURL (pageIndex, url)
Description Returns HTTP Response headers for the page index and URL requested.
Parameters
  • pageIndex - One-based page index
  • url - URL string
Return value
Remarks

Example:

System.GetHTTPResponseHeadersforURL( 1, “http://www.google.com/” );

GetHTTPRequestHeaderValueforURL Method
Syntax Scripter.GetHTTPRequestHeaderValueforURL (pageIndex, url, headerName)
Description Returns HTTP Request header value for the header name based on URL and page index requested.
Parameters
  • pageIndex - One-based page index
  • url - URL string
  • headerName - Header name
Return value
Remarks

Example:

System.GetHTTPRequestHeaderValueforURL ( 1, “http://www.google.com/”, “Host”);

GetHTTPResponseHeaderValueforURL Method
Syntax Scripter.GetHTTPResponseHeaderValueforURL (pageIndex, url, headerName)
Description Returns HTTP Response header value for the header name based on URL and page index for the index requested.
Parameters
  • pageIndex - One-based page index
  • url - URL string
  • headerName - Header name
Return value
Remarks

Example:

System.GetHTTPResponseHeaderValueforURL ( 1, “http://www.google.com/”,  “Content-Length” );

Custom data

Custom data for the page and page-detail level can only set of the current page.

SetTransLevel_msec Method
Syntax CustomData.SetTransLevel_msec (msec)
Description Sets custom value to be stored at the transaction level.
Parameters
  • msec - Value to be stored
Return value
Remarks

Example:

var stop =  new Date();
CustomData.SetTransLevel_msec( stop.getTime() - start.getTime() );                                                                              

GetTransLevel_msec Method
Syntax CustomData.GetTransLevel_msec ()
Description Returns the custom value stored at the transaction level.
Parameters
Return value
Remarks

Example:

var val = CustomData. GetTransLevel_msec();

SetTransPageLevel_msec Method
Syntax CustomData. SetTransPageLevel_msec (msecIndex ,msec)
Description Sets custom value at the index stored at the page level. Currently, we support storage of 3 values for the page level (index 1 to 3).
Parameters
  • msecIndex - One-based data index
  • msec - Value to be stored
Return value
Remarks

Example:

CustomData.SetTransPageLevel_msec(  1, 2001);

GetTransPageLevel_msec Method
Syntax CustomData. GetTransPageLevel_msec (msecIndex)
Description Returns the custom value at the index stored at the page level. Currently, we support storage of 3 values for the page level (index 1 to 3).
Parameters
  • msecIndex - One-based data index
Return value
Remarks

Example:

var val = CustomData.GetTransPageLevel_msec(  1 );

SetTransPageDetailLevel_msec Method
Syntax CustomData.SetTransPageDetailLevel_msec (url, msecIndex ,msec)
Description Sets custom value at the index stored at the page detail level for the URL specified. Currently, we support storage of 3 values for the page detail level (index 1 to 3).
Parameters
  • url - URL of the page detail
  • msecIndex - One-based data index
  • msec - Value to be stored
Return value
Remarks

Example:

CustomData.SetTransPageDetailLevel_msec(cPage, url, 1, i*100 +1);

GetTransPageDetailLevel_msec Method
Syntax CustomData.GetTransPageDetailLevel _msec (url,msecIndex)
Description Returns the custom value at the index stored at the page detail level for the URL specified. Currently, we support storage of 3 values for the page level (index 1 to 3).
Parameters
  • url - URL of the page detail
  • msecIndex - One-based data index
Return value
Remarks

Example:

var val = CustomData.GetTransPageDetailLevel_msec(cPage, url, 1);

SetTransPageDetailLevel_ObjectTrend Method
Syntax CustomData.SetTransPageDetailLevel_ObjectTrend (url, ObjectTrend)
Description Sets object trend custom string value at the page detail level for the URL specified.
Parameters
  • url - URL of the page detail
  • ObjectTrend - String value to be stored
Return value
Remarks

Example:

CustomData.SetTransPageDetailLevel_ObjectTrend (cPage, url, "conn_id:" + url);

GetTransPageDetailLevel_ObjectTrend Method
Syntax CustomData.GetTransPageDetailLevel_ObjectTrend (url, ObjectTrend)
Description Returns the object trend custom string value at the page detail level for the URL specified.
Parameters
  • url - URL of the page detail
Return value
Remarks

Example:

var val = CustomData. GetTransPageDetailLevel_ObjectTrend (cPage, url);

Error reporting
SetErrorDetails Method
Syntax HRESULT SetErrorDetails(BSTR errorCode, BSTR errorText, BSTR errorPageTitle, BSTR errorHtmlElementText, BSTR errorPageUrl);
Description This function creates an error record in the output data stream for MyKeynote use. It is used to communicate additional error information that is of interest to a particular error condition.
Parameters
  • errorCode - The error code to be set
  • bolFatal - Boolean (false/true); determines if this is a fatal error for the transaction.
  • errorText - The error text (limit 60 characters)
  • errorPageTitle - The page title (limit 255 characters)
  • errorHtmlElementText - The HTML element text (limit 255 characters)
  • errorPageUrl - URL associated with the error
Return value Returns S_OK if successful, or an error value otherwise.

Example:

System.SetErrorDetails( 1000, true,"errorText", "errorPageTitle", "errorHtmlElementText", "errorPageUrl");

Contents supplied in the parameters are displayed within a MyKeynote Scatter Plot Drilldown page like this:

  Extended [Error] Info: [INFO 1: errorPageURL] [INFO 2: errorPageTitle] [INFO 3: errorHtmlElementText] [INFO 4: errorText]

Parameter names are arbitrary and only indicate how they were used by developers.

SetInfoDetails Method
Syntax HRESULT SetInfoDetails(BSTR infoText, BSTR infoPageTitle, BSTR infoHtmlElementText, BSTR infoPageUrl);
Description This function creates a record in the output data stream for MyKeynote use. It is used to communicate additional non-error information that is of interest.
Parameters
  • errorText - The information text (limit 60 characters)
  • infoPageTitle - The page title (limit 255 characters)
  • infoHtmlElementText - The HTML element text (limit 255 characters)
  • infoPageUrl - The page URL (limit 2048 characters)
Return value
Remarks

Parameter names are arbitrary and only indicate how they were used by Keynote developers.

Example:

System.SetInfoDetails("infoText", "infoPageTitle", "infoHtmlElementText", "infoPageUrl");

Advanced API for Chrome and Firefox engines

These APIs are supported by the KITE Chrome and Firefox engines only.

APIs for working with cookies

KNAPI.SetCookie

Allows you to add or overwrite a cookie. Use in the format:

KNAPI.SetCookie( tabIndex, frameIndex, cookieName, cookieValue, cookieEnd, cookiePath, cookieDomain, cookieSecure )

Parameters:

  • tabIndex - the index of the tab
  • frameIndex - the index of the frame
  • cookieName - the name of the cookie
  • cookieValue - the value of the cookie
  • cookieEnd - the Max-age in seconds (e.g., 31536e3 for a year, Infinity for a never-expires cookie), or the expires date in GMTString format or as Date object—if not specified, the cookie will expire at the end of session.
  • cookiePath - the path of the cookie if not specified defaults to the host portion of the current document location.
  • cookieDomain - the domain of the cookie if not specified, defaults to the host portion of the current document location.
  • cookieSecure - whether the cookie should only be applied to secure pages

KNAPI.GetCookies

Gets cookies from a page. Use in the format:

KNAPI.GetCookies( tabIndex, frameIndex, callback )

Parameters:

  • tabIndex - the index of the tab
  • frameIndex - the index of the frame
  • callback - a callback function that will be called with the resulting value - the callback is in the form function ( ArrayOfNameValuePairs ) where ArrayOfNameValuePairs is the cookie string from document.cookie broken up into an array of objects { cookieName: name, cookieValue: value }.

This function causes a tab or frame to load a new URL.

void KNAPI.Navigate( tabIndex, frameIndex, url, headers, postData )

Parameters:

  • tabIndex - the index of the tab to navigate in

  • frameIndex - the index of the frame to navigate in (zero is the tab itself)

  • url - the URL to navigate to

  • headers - any headers that need to be sent as a string, with each header separated with a \r\n sequence, e.g., `

    host: www.google.com\r\nDNT: 1\r\n` , etc.

  • postData - if this is null, the request will be made as a GET; if it is not null it will use a POST, and the data provided will be sent.

ResizeBrowserWindow

Resizes the main browser window.

 void KNAPI.ResizeBrowserWindow( width, height )

Parameters:

  • width - the new width
  • height - the new height

Log

Sends a string to the advanced script log.

void KNAPI.Log( str )

Parameters:

  • str - the string to log

SetErrorDetails

Stores extended error information into the database.

void KNAPI.SetErrorDetails( errorCode, fatal, errorText, errorPageTitle, errorHtmlElementText, errorPageUrl )

Parameters:

  • errorCode - the custom error code
  • fatal - true if this is a fatal error and should stop the script
  • errorText - the error text to store
  • errorPageTitle - the title of the page
  • errorHtmlElementText - HTML description of the error
  • errorPageUrl - URL associated with the error

SetInfoDetails

Stores information text into the database.

void KNAPI.SetInfoDetails( infoText, infoPageTitle, infoHtmlElementText, infoPageUrl )

Parameters:

  • infoText - the info text to store
  • infoPageTitle - the title of the page
  • infoHtmlElementText - HTML description of the info
  • infoPageUrl - URL associated with the info

GetTabCount

Returns the number of open tabs. Returns - the number of open tabs, -1 if there is an error.

int KNAPI.GetTabCount()

GetTabFrameCount

Returns the number of frames in an open window.

int KNAPI.GetTabFrameCount( tabIndex )

Parameters:

  • tabIndex - the tab to count the frames in
  • returns - the number of frames in the tab, -1 if there is an error

GetCurrentActionNumber

Gets the current action number that elements are being recorded into. Returns the current action number, -1 if there is an error.

int KNAPI.GetCurrentActionNumber()

GetElementCount

Gets the number of elements associated with an action. Returns the number of elements associated with that action, -1 if there is an error.

int KNAPI.GetElementCount( actionIndex )

Parameters:

  • actionIndex - the index of the action whose elements we want to count (1 based)

GetMatchingElements

Gets the index of the first matching element with a specific URL, after a starting index. Returns an array of indexes of all the elements that matched.

array KNAPI.GetMatchingElements( actionIndex, url, isURLRegex )

Parameters:

  • actionIndex - the action the element is associated with (1 based)
  • url - the URL we are looking for
  • isURLRegex - if true then the URL parameter is a regular expression, if not it is a URL that must match exactly.

GetElementData

Gets information about an element including its URL, request and response headers, cookies, status, and timing information. All timing information is in milliseconds.

object KNAPI.GetElementData( actionIndex, elementIndex )

Parameters:

  • actionIndex - the index of the action the element is associated with (1 based)
  • elementIndex - the index of the element in the action (1 based)

Returns:

Returns an element object with the following information, null if there is an error:

  • element.url - the URL of the element
  • element.request.headers - an array of request header strings
  • element.request.cookies - the cookies sent with the request
  • element.response.headers - an array of response header strings
  • element.response.cookies - the cookies returned with the response
  • element.status - the status code of the response
  • element.error - the error code set by the engine for this element if there was one
  • element.timing.offset - the time from the start of the action until this element started
  • element.timing.dns - the time spent looking up the DNS for this element
  • element.timing.connect - the time spent making the connection
  • element.timing.ssl - time spent on SSL encryption
  • element.timing.sending - time spent sending the request
  • element.timing.firstByte - the time between the request being sent and a response coming back
  • element.timing.lastByte - the time between the first and last bytes
  • element.timing.system - any system time associated with the element
  • element.timing.totalTime - the total time it took to get the element

SetTransactionCustomValue

Sets a custom value to be stored on the transaction.

void KNAPI.SetTransactionCustomValue( valueMS )

Parameters:

  • valueMS - a custom value in milliseconds to store at the transaction level

GetTransactionCustomValue

Gets the custom value stored on the transaction. Returns a custom value in milliseconds stored at the transaction level, -1 if there is an error.

int KNAPI.GetTransactionCustomValue()

SetActionCustomValue

Sets a custom value to be stored on an action.

void KNAPI.SetActionCustomValue( actionIndex, valueIndex, valueMS )

Parameters:

  • actionIndex - the index of the action to add the custom value to (1 based)
  • valueIndex - the index of the value to set (we currenly only support 1-3)
  • valueMS - a custom value in milliseconds to store at the action level

GetActionCustomValue

Gets a custom value that was stored on an action. Returns the custom value if one was set.

int KNAPI.GetActionCustomValue( actionIndex, valueIndex )

Parameters:

  • actionIndex - the index of the action to get the custom value from (1 based)
  • valueIndex - the index of the value to get (we currenly only support 1-3)

SetElementCustomValue

Sets a custom value to be stored on an element on an action.

void KNAPI.SetElementCustomValue( actionIndex, elementIndex, valueIndex, valueMS )

Parameters:

  • actionIndex - the index of the action to add the custom value to (1 based)
  • elementIndex - the index of the element to store the value on (1 based)
  • valueIndex - the index of the value to set (we currenly only support 1-3)
  • valueMS - a custom value in milliseconds to store at the element level

SetElementCustomString

Sets a custom string to be stored on an element on an action.

void KNAPI.SetElementCustomString( actionIndex, elementIndex, valueString )

Parameters:

  • actionIndex - the index of the action to add the string to (1 based)
  • elementIndex - the index of the element to store the string on (1 based)
  • valueString - a custom string to store at the element level

GetElementCustomValue

Gets a custom value that was stored on an element. Returns the custom value if one was set.

int KNAPI.GetElementCustomValue( actionIndex, elementIndex, valueIndex )

Parameters:

  • actionIndex - the index of the action to get the custom value from (1 based)
  • elementIndex - the index of the element to get the custom value from (1 based)
  • valueIndex - the index of the value (we currenly only support 1-3)

GetElementCustomString

Gets a custom string that was stored on an element. Returns the custom string if one was set.

string KNAPI.GetElementCustomString( actionIndex, elementIndex )

Parameters:

  • actionIndex - the index of the action to get the custom string from (1 based)
  • elementIndex - the index of the element to get the custom string from (1 based)

GetScriptXML

Gets the script associated with the current action. Returns the value of the current action as an XML document.

document KNAPI.GetScriptXML()

GetCurrentActionXML

Gets the script associated with the current action. Returns the value of the current action as an XML document.

document KNAPI.GetCurrentActionXML()

GetSavedValue

Gets a saved value. Returns the value of the variable.

string KNAPI.GetSavedValue( variableName )

Parameters:

  • variableName - the name of the variable saved

SaveValue

Saves a value for later.

void KNAPI.SaveValue( variableName, value )

Parameters:

  • variableName - the name of the variable to save the value in
  • value - the value to save

GetVirtualUserValue

Gets a virtual user value.

string KNAPI.GetVirtualUserValue( variableName, value )

Parameters:

  • variableName - the name of the virtual user variable to get
  • returns - the value to save

TriggerCompletionEvents

Trigger the completion events which will end an action. This function acts as if all the conditions were met to make the completion conditions for an action trigger normally.

void KNAPI.TriggerCompletionEvents()

DumpObjectToLog

Dumps all the properties of an object to the log file.

void KNAPI.DumpObjectToLog( obj, name, maxRecurse )

Parameters:

  • obj - the object you want to dump
  • name - the name of the object
  • maxRecurse - the max depth to dump sub-objects, -1 to recurse the entire tree

RunDOMScript

Runs a DOM script in a specific frame of a specific window.

void KNAPI.RunDOMScript( tabIndex, frameIndex, scriptText )

Parameters:

  • tabIndex - the index of the tab to run the script in
  • frameIndex - the index of the frame to run the script in
  • scriptText - the text of the script to run

TriggerEventUsingXPath

Triggers an event on an element specified by an XPath.

void KNAPI.TriggerEventUsingXPath( tabIndex, frameIndex, xpathToElement, eventName )

Parameters:

  • tabIndex - the index of the tab the element is in
  • frameIndex - the index of the frame the element is in
  • xpathToElement - the XPath that defines the element
  • eventName - the name of the event to trigger

ClickUsingXPath

Clicks on an element in a specific tab and frame.

void KNAPI.ClickUsingXPath( tabIndex, frameIndex, xpathToElement )

Parameters:

  • tabIndex - the index of the tab the element is in
  • frameIndex - the index of the frame the element is in
  • xpathToElement - the XPath that defines the element to click on

SubmitUsingXPath

Submits an element in a specific tab and frame.

void KNAPI.SubmitUsingXPath( tabIndex, frameIndex, xpathToElement )

Parameters:

  • tabIndex - the index of the tab the element is in
  • frameIndex - the index of the frame the element is in
  • xpathToElement - the XPath that defines the element to submit (needs to be a form)

SelectUsingXPath

Selects a value from a drop-down element in a specific tab and frame.

void KNAPI.SelectUsingXPath( tabIndex, frameIndex, xpathToElement, index )

Parameters:

  • tabIndex - the index of the tab the element is in
  • frameIndex - the index of the frame the element is in
  • xpathToElement - the XPath that defines the element to select a value from
  • index - the index of the option in the select to choose

SetTextUsingXPath

Sets the text of an element in a specific tab and frame.

void KNAPI.SetTextUsingXPath( tabIndex, frameIndex, xpathToElement, textToSet )

Parameters:

  • tabIndex - the index of the tab the element is in
  • frameIndex - the index of the frame the element is in
  • xpathToElement - theXPpath that defines the element to set the text of
  • textToSet - the text to set into the input

GetValuesUsingXPath

Gets the values of elements or attributes defined by the XPath.

void KNAPI.GetValuesUsingXPath( tabIndex, frameIndex, xpath, callback )

Parameters:

  • tabIndex - the index of the tab the element is in
  • frameIndex - the index of the frame the element is in
  • xpath - the XPath that defines the elements or attributes to get
  • callback - a callback function that will be called with the resulting values
    The callback is in the form function( ArrayOfNameValuePairs ) where ArrayOfNameValuePairs is all the values found by the xpath in the format [ { name: node name, value: node value } ] .

Pause

Pauses the advanced script for a number of milliseconds.

void KNAPI.Pause( delayMS )

Parameters:

  • delayMS - the number of milliseconds to delay