Skip to content

Commands for Team Notifications, Alerts and Collaboration

← Command Reference
Worksoft SaaS supports a number of commands (constructs) to help you implement within your automated tests alerts and notifications about test execution outcomes that facilitate you in collaborating within and across teams in your organization. 


                                                               

For now, email is the only mechanism that is supported for alerts, notifications and collaboration. In the future, support for other popular and widely used mechanisms like 'Slack' will be implemented.

                                                                                              

Email: 

It is important that the structure of the email is understood before you understand the commands supported in Worksoft SaaS. At a very high level, the email has a header, body and optionally one or more attachments.

                                                                                             
  • The 'header' is usually made up of a from email address, 'To' recipient list, 'Cc' recipient list (optional), 'Bcc' recipient list (optional).
  • The 'body' can be composed by using a template and by feeding the values to be merged into the template from a text string, data set, or a data file.
  • Optionally, one or more 'attachments' can be attached to the email. In Worksoft SaaS, an attachment can be a data file or a file that exists in the same project the test script using the commands in this article is part of. The attachment can also be a screenshot that is captured in the context of a specific test instruction the execution of which precedes the use of the commands mentioned in this article.
Now that you have a pretty good idea of how the Worksoft SaaS constructs (data file, data set, file, etc) correlate to the email structure or contents, you can continue to read about the purpose of the powerful commands that let you implement email-based notifications and alerts for team collaboration in this article.

The table(s) below list the commands in the ascending alphabetic order within each category along with a brief description of the purpose behind the command. By clicking on the hyperlinked command name in the table(s) below, you can review more detailed information about a specific command that includes the syntax for you to follow when using the commands.   Please note that these constructs are supported within the Worksoft SaaS application but unsupported within QaSCRIBE.                                                                                          
   Category                    Command                  Purpose
Email Body
appendBodyPartToBody(Optional)  
 This command appends a 'body part' to the email body defined using the command 'createBody' (and identified with a email body name).

The email body may contain one or more 'bodyparts' if this command was executed previously within the same script in the context of the same email body (identified by the email body name).
Email Body
buildHTMLAnchorTagToAccessTestExectionDetail(Optional)  
 This command returns the complete HTML anchor tag that contains the testRunId along with the hyperlink to access the execution detail page within the Worksoft SaaS application for that testRunId. The returned value will be of the format "<a href="<hyperlink"><testRunId></a>".
Email Body
createBody(Mandatory)		 This command is used to create (or define/initialize) an email body and assign it a 'name'.  This 'name' is referred to in this article and other articles related to these commands as 'email body name'.

This email body name, passed into the 'target' field for this command, will act like a 'variable' that you can then incrementally build (or compose) by adding 'email body parts' by using the commands 'appendBodyPartToBody' and any of the commands that start with 'createBodyPartFrom".
Email Body
createBodyPartFromDataFile(Optional)    
 This command is used to create an 'email body part' from the 'Data File' passed as input.
  • The 'target' for the command is the 'data file name'.
  • The 'value' for the command is a name you provide to the 'body part' that you will end up using as input to the command 'appendBodyPartToBody'. 
The data file passed into the 'value' for this command can have in its contents user-defined variables and/or system variables which during the test execution will get substituted with the then current value of the user-defined variable(s) or the system variables.  If you want the user-defined variables or system variables within the contents of the data file, they must be appropriately enclosed with a '${' on the left and a '}' on the right.  
Email Body
createBodyPartFromDataSet(Optional)    
 This command is used to create an 'email body part' from the 'Data Set' passed as input.
  • The 'target' for the command is the 'data file name'.
  • The 'value' for the command is a name you provide to the 'body part' that you will end up using as input to the command 'appendBodyPartToBody'.  
The Data Set passed into the 'value' for this command can have in its contents user-defined variables and/or system variables which during the test execution will get substituted with the then current value of the user-defined variable(s) or the system variables.  If you want the user-defined variables or system variables within the contents of the data set, they must be appropriately enclosed with a '${' on the left and a '}' on the right.     
Email Body
createBodyPartFromTextOrHTML(Optional)    		 This command is used to create an 'email body part' from the 'Text String' or 'HTML String' passed as input.
  • The 'target' for the command is the 'data file name',
  • The 'value' for the command is a name you provide to the 'body part' that you will end up using as input to the command 'appendBodyPartToBody'.  
The plain text string or the HTML text string passed into the 'value' for this command can have in its contents user-defined variables and/or system variables which during the test execution will get substituted with the then current value of the user-defined variable(s) or the system variables.  If you want the user-defined variables or system variables within the contents of the plain text or html string, they must be appropriately enclosed with a '${' on the left and a '}' on the right.    
Email Body
createStyleForDataTablesInBody(Optional)    		 This command is used to create (define) the 'style' for the data tables that you will append to the email body (name) using the command 'createBodyPartFromDataFile' and/or the command 'createBodyPartFromDataSet'.

The 'target' for this command will have to be a JSON that defines the style for the data tables. The style includes the font style, size, cell background color, etc for the data table header row as well as the same attributes for the rows in the data table.

The style that is defined by use of this command will 'automatically' get applied to all data tables (body parts) appended into the email body (name).

The JSON string passed as input into the 'target' for this command can contain the style for the header and the data rows for the data tables as suggested below:

{"table": "style=\"border-collapse: collapse; border-spacing: 0; border: 1px solid #e0e0e0;\"","tbody": "style=\"background: #fbfafa;\"","th": "style=\"color: #ffffff; background: #2969ae; font-weight: bold; padding: 8px;  font-size: 0.9em; text-align: center;\"","tr": "style=\"background: #fbfafa;\"","td": "style=\"font-weight: normal; padding: 8px;  font-size: 0.9em; text-align: left;  border-right: 1px solid #e0e0e0;  border-bottom: 1px solid #e0e0e0;\""}   

If you have data tables in the email body but you did NOT specify the style to be applied using this command, Worksoft SaaS will apply the default Worksoft SaaS standard style to the data tables, described below:
  • Table Header: "style=\"color: #ffffff; background: #2969ae; font-weight: bold; padding: 8px; font-size: 0.9em; text-align: center;\"";
  • Table Even Row: "style=\"background: #ffffff;\"";
  • Table Odd Row: "style=\"background: #fbfafa;\"";
  • Table Cell: "style=\"font-weight: normal; padding: 8px; font-size: 0.9em; text-align: left; border-right: 1px solid #e0e0e0; border-bottom: 1px solid #e0e0e0;\"";
  • Table: "style=\"border-collapse: collapse; border-spacing: 0; border: 1px solid #e0e0e0;\"";
Email Block
emailBlockEnd(Mandatory ) 
 This command signifies the end of a email block within a test script.

Each 'emailBlockEnd' must be accompanied by a matching 'emailBlockStart' that exists before it within the same test script.

There can be more than one 'pair' of email block start and end commands within a single test script.  
Email Block  
emailBlockStart(Mandatory)		 This command signifies the beginning of a email block within a test script.

Each 'emailBlockStart' must be accompanied by a matching 'emailBlockEnd' that exists after it within the same test script.

There can be more than one 'pair' of email block start and end commands within a single test script.
Email Body
getDirectHyperlinkToAccessTestExecutionDetail(Optional)  
 This command returns the hyperlink to the access the execution detail page within the Worksoft SaaS application for a specific testRunId. The testRunId is optional in the first command. If not passed, the command will return the hyperlink for the test run id in context.
Email Attachments
getIdentifierForFirstFailedInstruction(Optional)    
 This command gets the test instruction identifier for the first failed test instruction within the test run that this command is executing as part of.
  • The 'target' for this command has to be a 'variable' (name string) into which the 'instructionIdentifier' for the first failed test instruction within the test run will be stored. 
  • The optional 'value' for this command is the 'name of the command' for which you want the 'instructionIdentifier'. When you pass a command name into the 'value' field for this command, Worksoft SaaS will return the identifier for the test instruction that involves the 'command' you passed into the 'value' field AND corresponds to the first failure experienced for that specific command during execution. If you had several instructions that failed before the instruction that executes this command but you are interesting in attaching or embedding inline a screenshot that corresponds to a specific command (say 'verifyText') that is not necessarily the immediately preceding test instruction, then this optional input parameter will of great value to you. 
The 'instructionId' stored into the variable can then be used as input to the command 'setAttachmentScreenshot' (to attach the screenshot as an attachment to the email) or the command 'createBodyPartFromScreenshot' in combination with the command 'appendBodyPartToBody' to get the screenshot embedded inline into the email body.

If the name of the command passed as optional input into the 'value' field of the test instruction does not exist in the test run (may be because you accidentally had a typo in the value passed into the 'value' field), then the instruction with fail in the test but the test will not be aborted. The error message will be
"Name of the Command passed into the 'value' field of this test instruction does not exist in this test run."   
Email Attachments  
getIdentifierForLastExecutedInstruction(Optional)    
 This command gets the test instruction identifier for the last executed test instruction within the test run that this command is executing as part of.
  • The 'target' for this command has to be a 'variable' (name string) into which the 'instructionIdentifier' for the last executed test instruction within the test run will be stored. 
  • The optional 'value' for this command is the 'name of the command' for which you want the 'instructionIdentifier'. When you pass a command name into the 'value' field for this command, Worksoft SaaS will return the identifier for the test instruction that involves the 'command' you passed into the 'value' field that had already been executed. If you had several instructions that got executed before the instruction that executes this command but you are interesting in attaching or embedding inline a screenshot that corresponds to a specific command (say 'verifyText') that is not necessarily the immediately preceding test instruction, then this optional input parameter will of great value to you.
The 'instructionId' stored into the variable can then be used as input to the command 'setAttachmentScreenshot' (to attach the screenshot as an attachment to the email) or the command 'createBodyPartFromScreenshot' in combination with the command 'appendBodyPartToBody' to get the screenshot embedded inline into the email body.  

If the name of the command passed as optional input into the 'value' field of the test instruction does not exist in the test run (may be because you accidentally had a typo in the value passed into the 'value' field), then the instruction with fail in the test but the test will not be aborted. The error message will be
"Name of the Command passed into the 'value' field of this test instruction does not exist in this test run."   
Email Attachments  
getIdentifierForLastFailedInstruction(Optional)    
 This command gets the test instruction identifier for the last failed test instruction within the test run that this command is executing as part of.
  • The 'target' for this command has to be a 'variable' (name string) into which the 'instructionIdentifier' for the last failed test instruction within the test run will be stored.
  • The optional 'value' for this command is the 'name of the command' for which you want the 'instructionIdentifier'. When you pass a command name into the 'value' field for this command, Worksoft SaaS will return the identifier for the test instruction that involves the 'command' you passed into the 'value' field AND  corresponds to the last failure experienced for that specific command during execution. If you had several instructions that failed before the instruction that executes this command but you are interesting in attaching or embedding inline a screenshot that corresponds to a specific command (say 'verifyText') that is not necessarily the immediately preceding test instruction, then this optional input parameter will of great value to you.
The 'instructionId' stored into the variable can then be used as input to the command 'setAttachmentScreenshot' (to attach the screenshot as an attachment to the email) or the command 'createBodyPartFromScreenshot' in combination with the command 'appendBodyPartToBody' to get the screenshot embedded inline into the email body.  

If the name of the command passed as optional input into the 'value' field of the test instruction does not exist in the test run (may be because you accidentally had a typo in the value passed into the 'value' field), then the instruction with fail in the test but the test will not be aborted. The error message will be 
"Name of the Command passed into the 'value' field of this test instruction does not exist in this test run." 
Email Body
mergeValuesIntoBodyPartVariables(Optional)    
 This command is used to merge the values from dataset into 'variables for substitution' that exist within either the:
  • email body (name) is created using the 'createBody' command and incrementally populated using the 'appendBodyPartToBody'  command, OR
  • email body part (variable) created using any of the commands that start with 'creareBodyPartFrom' command (excluding the createBodyPartFromScreenshot' command)
The 'target' for this command is the email body (name) or email body part( name) and the 'value' for this command is the 'dataset' name that contains the name-value pairs.

The string passed into the 'target' field should have all variables that have to be substituted enclosed with a '${' on the left and a '}' on the right so that the variable name string looks of the format ${<variable-name>}. You can have the same variable name more than once in the email body string part string. 

The dataset should have the name-value pairs where 'name' is the parameter name and 'value' is the actual value that needs to be substituted. The contents of the 'name' column cells must have the variable names that are NOT enclosed with a '${' on the left and a '}' on the right. 
 
The dataset can have more names (rows) than are needed for substitution (merging of values) into the email body or email body part. All such rows will be ignored. If none of the rows in the dataset have names that match with 'variables for substitution' in the email body or email body part, then there will be no effect of this command on the contents of the email body or email body part.

It is possible for this command to be called more than once with the same target (the email body or email body part) but with a different input to the 'value' field (the 'dataset'). If you have dataset-1 that has 2 name-value pairs and dataset-2 has 3 name-value pairs and the email body or email body part has 5 'variables for substitution', then you call this command once passing dataset-1 as input to the 'value' field for this command, and call the same command a second time but this time feeding as input into the 'value' field dataset-2.

Similarly, it is possible to call the same command more than once passing the same dataset as input to the 'value' field but passing a different email body or email body part as input into the 'target' field. You can do so to store all the name-value pairs that you need for different email body parts in a single dataset, but pass the same dataset as input to different email body parts.

Another option that exists is to first compose the complete email body by appending various email body parts and then calling this command once to get all 'variables for substitutions' merged in with values from the dataset.

Special Data Conditions:
  1. if the dataset does not have a value for the 'name' column, then the dataset has no impact on the value of the variable in the email body part. It simply does not get replaced and stays as a variable and the email will get sent with that variable not replaced.
  2. If the 'value' column of the data set does not have a value, then an empty string is used to replace the variable in the email body part.  Therefore, you should ensure that the dataset has just the 'name' and 'value' columns and that it has as names all variable names that you want to get replaced with a value.
  3. If the dataset that is passed as input to this command has more than 2 columns and the first column has as value the variable name used in the email body part, then the value that is used to replace the variable in the email body part will be the concatenation of the contents of all the other columns of the dataset row beyond the 'name' but each value separated by a newline character '\n'. Obviously, the email body will appear unprofessional with such data corruption. So, be careful when passing a dataset as input to this command. Avoid feeding any dataset that has more columns than two and ensue that the dataset has just the 'name' and 'value' columns.
  4. If the HTML text or plain text or dataset or datafile has user-defined variables or system variables will they get substituted as part of the execution of this command or other commands?
Distribution
sendEmail>(Mandatory)  
 This command is used to send (distribute) the email composed (contents of the 'email body name' created with the 'createBody' command and populated with the use of one or more calls to 'appendBodyPartToBody' command) to the recipient list specified in the To, and if specified in the Cc and Bcc. The sender will be either the default sender or the sender explicitly specified with the 'setSender' command.
Email Attachments
setAttachmentDataFile(Optional)    
 This command is used to set a 'Data File' as an attachment to the email. 

The data file has to be within the same project the test script belongs to.

The input to the 'target' field of this email is the name of the 'data file' along with the status. If status is unspecified, it is assumed to the datafile in the 'active' status. When passed, the 'status' must be appended to the data file name in the format <dataFileName>(<status>), where the <dataFileName> should contain the name of the data file and <status> should contain the name of the status [example: (WIP), (Active)].

If the Data File passed into the 'target' for this command has in its contents user-defined variables and/or system variables, they will NOT get substituted during the test execution.

Worksoft SaaS does not impose any restriction on the number of attachments, including 'data files', that can get attached to the email body (name). But, the recipient's email server may impose restrictions on the number of email attachments and/or the total file size of attachments. Many email servers restrict email attachments that exceed the total byte size of 40 MB.

The name of the file attachments (data file(s)) will remain the same as the names of the data file(s) in the Worksoft SaaS.

Please note that if data files, files and screenshots are attached to the email body, then the order in which the attachments will appear in the email that is composed is as follows:
  •  'Data Files' first, 'Files' next followed by 'Screenshots'
  • Within a file of a particular type (data file or file or screenshot), the files will appear in the order they are attached.
If the 'data file' passed as input to the 'target' field does not exist in the project, during execution of an automated test, this instruction will fail with a message: "The 'data file' passed as input into the 'target' field of this test instruction does not exist in your project."  
Email Attachments  
setAttachmentFile(Optional)    
 This command is used to set a 'File' as an attachment to the email.  

The file has to be within the same project the test script belongs to.  

The input to the 'target' field of this email is the name of the 'file'. 'Status' of the file must not be specified along with the file name because only 'active' files can be attached (inactive ones cannot be).

Worksoft SaaS does not impose any restriction on the number of attachments, including 'files', that can get attached to the email body (name). But, the recipient's email server may impose restrictions on the number of email attachments and/or the total file size of attachments. Many email servers restrict email attachments that exceed the total byte size of 40 MB.

The name of the file attachments (files) will remain the same as the names of the file(s) in the Worksoft SaaS.  

Please note that if data files, files and screenshots are attached to the email body, then the order in which the attachments will appear in the email that is composed is as follows:
  • 'Data Files' first, 'Files' next followed by 'Screenshots'
  • Within a file of a particular type (data file or file or screenshot), the files will appear in the order they are attached.
If the 'file' passed as input to the 'target' field does not exist in the project, during execution of an automated test, this instruction will fail with a message: "The 'file' passed as input into the 'target' field of this test instruction does not exist in your project."
Email Attachments  
setAttachmentScreenshot(Optional)    
 This command is used to set a 'Screenshot' captured during the automated test run (within which the script containing this command executes within) as an attachment to the email.  

The input to the 'target' field of this email is the 'identifier' for a test instruction in the same test run that the test script containing this command is executing within (identified by use of one of the commands that starts with ' getIdentifierFor '), that has a screenshot captured, that you want to attach to the email being composed. 
 
The screenshot is a screenshot that is captured within the same test run (not necessarily within the same test script) within which the email is being composed and has to correspond to a test instruction that is executed before the test instruction that executes this command.

Worksoft SaaS does not impose any restriction on the number of attachments that can get attached to the email body (name), including screenshots. But, the recipient's email server may impose restrictions on the number of email attachments and/or the total file size of attachments. Many email servers restrict email attachments that exceed the total byte size of 40 MB.

The file format for the screenshot attachments will be jpeg (.jpg). 

The name of the file attachments (files) will be set to the global id of the test instruction within the automated test that the screenshot corresponds to (as it appears in the test execution results screen) within the Worksoft SaaS application.

Please note that if data files, files and screenshots are attached to the email body, then the order in which the attachments will appear in the email that is composed is as follows:
  • 'Data Files' first, 'Files' next followed by 'Screenshots'
  • Within a file of a particular type (data file or file or screenshot), the files will appear in the order they are attached.
If the instruction id that is returned from any of the getIdentifier commands does NOT have a screenshot captured (either because the screenshots are disabled for the test run OR because test runs are enabled only on failure but that instruction did not experience failure) and that instruction Id is passed as input to this command, then the instruction will fail with a message:
"The instruction passed as input into the 'target' field of this test instruction does not have a screenshot captured." 
Email Header
setRecipientBCCList(Optional)    
 This command is used to. set the 'Bcc' recipient list that the composed email will be distributed to.    

Each email address in the list must be valid and must be separated from the one before with a comma (with our without a space before or after the comma).  

If you want the user-defined variables or system variables within the contents of the string you pass into the 'target' for this command, they must be appropriately enclosed with a '${' on the left and a '}' on the right. During the test execution, Worksoft SaaS will substitute (replace) the variable names, if any, in the recipient Bcc list with the then-current value of the user-defined or system variable, and string with replaced values will get set as the recipient Bcc list for the email being composed.  
Email Header  
setRecipientCCList(Optional)    
 This command is used to. set the 'Cc' recipient list that the composed email will be distributed to.  

Each email address in the list must be valid and must be separated from the one before with a comma (with our without a space before or after the comma).  

If you want the user-defined variables or system variables within the contents of the string you pass into the 'target' for this command, they must be appropriately enclosed with a '${' on the left and a '}' on the right. During the test execution, Worksoft SaaS will substitute (replace) the variable names, if any, in the recipient Cc list with the then-current value of the user-defined or system variable, and string with replaced values will get set as the recipient Cc list for the email being composed.   
Email Header  
setRecipientToList(Mandatory)    
 This command is used to. set the 'To' recipient list that the composed email will be distributed to.

Each email address in the list must be valid and must be separated from the one before with a comma (with our without a space before or after the comma).

If you want the user-defined variables or system variables within the contents of the string you pass into the 'target' for this command, they must be appropriately enclosed with a '${' on the left and a '}' on the right. During the test execution, Worksoft SaaS will substitute (replace) the variable names, if any, in the recipient To list  with the then-current value of the user-defined or system variable, and string with replaced values will get set as the recipient To list for the email being composed.  
Email Header  
setSender(Optional)    


 This command is used to set the 'Sender' for the email being composed.  

Currently, the full Email address of the sender is supported and not the full name or alias name 

Default sender will be set to Worksoft SaaS ['info@eureqatest.com']

If you want the user-defined variables or system variables within the contents of the string you pass into the 'target' for this command, they must be appropriately enclosed with a '${' on the left and a '}' on the right. During the test execution, Worksoft SaaS will substitute (replace) the variable names, if any, in the sender with the then-current value of the user-defined or system variable, and string with replaced values will get set as the sender for the email being composed.     
Email Header  

setSubject(Mandatory)   
 This command is used to set the 'Subject' for the email being composed. 

It is recommended that the subject line not contain more than 70 characters. Even though Worksoft SaaS can support more characters than that, industry best practices indicate that people prefer shorter subject lines.

If you want the user-defined variables or system variables within the contents of the string you pass into the 'target' for this command, they must be appropriately enclosed with a '${' on the left and a '}' on the right. During the test execution, Worksoft SaaS will substitute (replace) the variable names, if any, in the subject line with the then-current value of the user-defined or system variable, and string with replaced values will get set as the subject for the email being composed.

Worksoft SaaS does not impose any restriction on the maximum length of the subject line. However, the email servers may impose a restriction on the length. Some email servers also may implement rules that treat emails that have very long subject lines as 'spam'. So, be careful while setting the subject line for emails that you want sent out from within the automated tests in execution.



Feedback and Knowledge Base

(thinking…)