Workflow Activities - Available Built-In Activities

In the Workflow editor window, the Activities pane groups the Workflow activities as follows:

The following table lists and describes all of the default activities.

Activity Group/Name Description and Usage

Control Flow

Acquirelock Allows the Workflow engine to obtain a lock on an entity name (such as, client, folder, file, etc.,) so that during Workflow execution, other Workflow jobs running on the same entity name are blocked.

This can be useful in cases where you want to make sure that only one workflow is acting on something or only one workflow of the same type gets started at one time.

This activity requires the following inputs:

  • name

    A string value which specifies the entity name on which the Workflow is being executed. The lock can be acquired on the workflow itself, or any name, or input variable (such as, client, folder, file name, etc.,)

    Examples:

    1. Setting the name input to the workflow name would block another copy of the same workflow from running until this one completes.

      xpath:{/workflow/system/workflow/workflowName}

    2. Setting the name input to the workflow name, plus “_”, plus the name of a specific input, would block another copy of the same workflow from running that has the same VALUE input as the one currently running.

      xpath:{/workflow/system/workflow/workflowName}_xpath:{/workflow/inputs/id}

  • releaseLockOnCompletion

    A boolean value which determines whether the lock can be released once the Workflow is completed.

  • timeout

    An integer value which specifies the threshold time limit (in minutes) for the acquirelock activity to try acquiring a lock on the workflow. Once the time limit is reached, the activity will stop its attempt to acquire the lock and fails.

    Only workflows running on the same workflow engine would be blocked by this activity. Meaning, if the same workflow was deployed on multiple workflow engines and they started running on each, no blocking would take place.

Break Exits from a loop (for example, a loop initiated by the ForEach activity) so the remaining items in the list are not processed.

Typically, you would have a Decision activity inside the loop where you will define an expression that will trigger the Break activity.

Decision Determines the path that the Workflow will take based on a trigger condition. To specify the condition, the expression input must be set. This input is a Java or JavaScript expression that returns a Boolean value, which divides the Workflow into two different paths: the true and false condition.

This input typically consists of:

  • the output variable of the activity preceding the Decision activity. For example, the output variable can be the exit code of a preceding activity represented in an xpath expression, which you can add by clicking Insert Variable and may look like this:

    xpath:{/workflow/CheckReady_2/exitCode}

  • the expected output for the output variable. Using the example mentioned above, if you want the exit code to be 0 (which means the preceding activity completed successfully), specify == 0 next to the output variable as follows:

    xpath:{/workflow/CheckReady_2/exitCode} == 0

For more information on using expressions, see Setting Activity Values using Expressions.

Delay Pauses a Workflow thread (of activities) for a specific period of time. This activity requires the following inputs:
  • DelayLength

    An integer value which determines the amount of time for the pause.

  • DelayInterval

    A string value which determines if the delay length is in seconds, minutes or hours.

ExecuteProcessBlock Allows you to run operations defined in a ProcessBlock or OnWorkflowComplete activity block, at any given point in the Workflow. For example, when you define a ProcessBlock you can reuse activities that need to be executed more than once in your Workflow, similar to calling a subroutine. The ProcessBlock can have inputs defined that can be set by the ExecuteProcessBlock activity before passing control to the ProcessBlock activity. Once the ProcessBlock completes, control passes to the activity following the ExecuteProcessBlock activity.

The OnWorkFlowComplete activity is also called by the ExecuteProcessBlock activity in the same way.

ForEach Receives a list of elements and executes a set of tasks for each element in the list. For an example of this activity, see the Client Group Policy workflow. The workflow attempts to update the storage policy on default subclients for every fetched client.

This activity, which behaves similar to the ProcessBlock activity, requires the following inputs:

  • values

    An object value which collects the elements to be processed in a list. For example, assume that you specified a SQL query (using the CommServDBQuery activity) to retrieve the name of all clients. You can use the following xpath expression to collect the client names:

    xpath:{/workflow/CommServDBQuery_1/resultSets[1]/row/col[@name='name']}

    Note: When the index '[...]' is not specified in the xpath expression for the CommServDBQuery output, it will always return all the items in the list. For example, no index is provided for row in order to collect all the items from the name column on each row of the first result set.

  • numberOfParallelExecutions

    An integer value which determines the number of elements you want to execute in parallel. By default, the value is 1.

  • continueOnFailure

    Allows the activity to continue processing the list items in the event that one of the items fails. This input provides a true or false value for selection. For example, if you want to move to the next item in the list when an item fails, set this input to true.

Tip: Use the XPathQuery activity with the ForEach activity to iterate through XML elements.
Fork Splits the Workflow into multiple activity threads, which can be later combined to a single thread using the Join activity.
GetCurrentUserToken Returns the current CommServe authenticated token that is being used by the current user to execute QCommand operations. The token output is a string value.
ImpersonateCreator Sets the current authenticated token to the CommCell user who created the Workflow.

By default, the privileges of the user executing the Workflow are used during a Workflow execution. This user is referred as the Workflow executor. If this user does not have permissions on the CommCell objects which the Workflow operates against, but the creator does, use this activity to give the Workflow executor the same permissions as the Workflow creator during execution.

ImpersonateExecutor Sets the current authenticated token to the CommCell user executing the Workflow.

During the Workflow execution, the privileges of the user executing the Workflow are used by default. This user is referred as Workflow executor. If the Workflow is using an impersonation activity (ImpersonateCreator or ImpersonateLogin) to run a high level operation, use this activity to go back to the Workflow executor permissions after the operation completes.

ImpersonateLogin Sets the CommCell user account to be used for executing specific activities in the Workflow. When a Workflow is created by a user which does not have permissions on the objects that the Workflow will operate against, you can use this activity to define the login credentials of a user that has sufficient privileges to perform activities defined on the Workflow. For example, if there is a script to disable any I/O operations on the server, this activity must be placed before the activity containing the script.

This activity requires the following inputs:

  • userName

    A string value which specifies the name of the user account.

  • password

    An encrypted string value which specifies the password for the user account.

Join Combines the multiple activity threads created from the Fork activity into a single thread. The Join activity will wait until all the threads started by the Fork activity completes.
LogoutImpersonatedUser Logs off the current impersonated user.

This activity is optional as the Workflow logs off all impersonated users when completed.

OnWorkflowComplete Creates a separate operation block where you can specify activities that you wish to run once the Workflow ends. This activity is triggered when the Workflow job completes with one of the following states: success, failed or killed. OnWorkflowComplete is a stand-alone activity and should be defined without links from or to other activities.

For example, to cover the scenario when the Workflow job is killed, you can use this activity to define some cleanup operations, such as killing other jobs that the Workflow has started.

ProcessBlock Creates an operation block where you can define a group of activities that can be executed as a unit (as in a try/catch block) or a subroutine (call and return).

For example, assume you want to create a try/catch scenario by defining two ProcessBlock activities. For the try block, you can set the maximum restart property to 0, so that if any activity defined in this block fails, then the entire block fails and transitions to the catch block. For an example of this activity, see the Try Block and Catch Block activities in the New User Signup workflow.

Similarly, in a subroutine scenario, the ProcessBlock would contain one or more activities that need to be executed multiple times within the entire Workflow and exist in different program paths. When ProcessBlock is not used, the same set of activities or code is copied multiple times to accomplish the goal. However, by using an ExecuteProcessBlock activity with a call to a ProcessBlock activity, the code need to exist only once.

ReleaseLock Unlocks the specified global lock name.

This activity requires the following inputs:

  • name

    A string value that specifies the global lock name used by the acquirelock activity.

SuspendWorkflow Suspends the Workflow job. To continue with the Workflow, you can
  • manually resume the Workflow job from the Job Controller window in the CommCell Console
  • use the qoperation jobcontrol activity to programmatically resume the Workflow
Switch Determines the path that the Workflow will take based on a trigger condition. To specify the condition, the expression input must be set. This activity behaves similar to the Decision activity, with the difference that you can set up the condition values to be used, instead of being only true or false.

The expression input is a string value which will divide the Workflow into two or more different paths. For example, if you have a variable that indicates the type of user registering with the Web Console, then click Insert Variable to set the variable to the expression input. The variable may look as follows:

xpath:{/workflow/inputs/userType}

You will be able to create separate activity threads depending on the output value (for example, 1 for an existing user and 2 for a new user).

For the Switch activity, you can set a default transition if the conditional value returns false.

For more information on using expressions, see Setting Activity Values using Expressions.

TransferToken Transfers a user's token from a master CommCell to a registered CommCell. This activity checks whether the passwords on the master CommCell and the specified registered CommCell, match the current user's token. For Active Directory accounts, passwords will automatically be considered a match as long as the Active Directory user account exists on both CommCells.

All activities that users could perform on the master CommCell using their credentials, can be performed on the registered CommCell when the token transfer is effected. This applies to the following activities: CommServeDBQuery, ExecuteCommand, and ExecuteScript.

WizardBlock Adds Back, Next, Cancel, and Finish buttons to a series of PopupInput activities. When user navigates back and forth through these pages, the last entered input data is automatically populated on the pages.

This activity also provides a hideCancelButton option to hide or display the Cancel button.

WorkflowEnd Terminates the Workflow when a specified activity thread fails to complete. This activity is useful to indicate that the Workflow failed and to show the respective reason.

This activity requires the following inputs:

  • completionStatus

    A string value which determines if the activity thread completed or failed.

    For Workflows with multiple activity threads, if you are using this activity on a specific activity thread and you selected the COMPLETED status, WorkflowEnd will terminate the activity thread, but the Workflow will continue to execute the other threads. However, if the FAILED status is set, the Workflow terminates.

  • failureMessage

    (Optional) A string value which describes the reason of the failure. This input is not needed if you set the completionStatus input as completed.

Job

WaitForJobCompletion Waits for an operation to complete and sends the completion status to the following activity in the Workflow.

This activity requires the following inputs:

  • jobId

    An integer value which specifies the job ID of the operation to be monitored for completion. For example, if you want to wait for a backup operation to complete (defined by the QOperationBackup activity), click Insert Variable to add the following variable:

    xpath:{/workflow/OperationBackup_1/jobId}

  • sessionOptions (Optional)

    This input allows you to run the operation using the Workflow executor privileges. By default, the Workflow uses this behavior.

QCommands

 <All QCommand Activities> The QCommand activities are defined based on the QCommand operations executed in the command line.

The options available for a QCommand are provided as inputs for its corresponding QCommand activity. For example, the QCreateBackupset activity is based on the qcreate backupset command. See how the activity inputs represent the command options:

Activity Inputs Command Options
client -c
dataAgent -a
instance -i
backupSet -n
storagePolicy -sp
type -t
argumentFilepath -af

All the QCommand activities also provide the inputs to impersonate a user. These inputs are referred to as sessionOptions:

  • userImpersonatedAccount

    Allows you to enable user impersonation. Valid values are true/false.

  • tokenFile (represents the -tf option in the command line)

    Specifies the path to the file containing the token string.

  • token (represents the -tk option in the command line)

    Specifies the token string. A token is an encrypted string that uniquely identifies the user and the CommServe to which he/she is connected to.

For information on the options available for a specific command, see CommServe and MediaAgent command line pages. You can also check Command Line for end-to-end information.

If you generated an XML using the Save as Script option in the CommCell Console, you can use the QOperationExecute activity to run the XML.

Navigate to the Inputs tab of this activity, copy the contents of the XML file, and paste them into the Value column of the inputXML input. We recommend this approach instead of specifying the XML path because you can later export the Workflow to another CommCell without the need to set up the XML file in that CommCell.

ServiceNow

ServiceNowLogin Logs on to ServiceNow REST API and acquires the OAuth token.

This activity requires the following inputs:

  • username

    A string value, which specifies the user account name to log on to ServiceNow.

  • password

    An encrypted string value, which specifies the password for the user account to log on to ServiceNow.

  • clientId

    An automatically-generated unique ID of the OAuth application on ServiceNow.

    For more information on how to register Simpana, go to the ServiceNow website, OAuth Setup.

  • clientSecret

    A encrypted string value, which enables communication between the client and the OAuth application on ServiceNow.

  • refreshToken

    A string value of the refresh token received from ServiceNow to refresh the expired token.

    OAuth token is a short-lived token and expires in minutes or hours, as determined by the authentication service. Using the refresh token, you can renew the OAuth token.

  • refreshTokenRequest

    A Boolean value of the request to refresh an access token sent to ServiceNow to refresh the expired token.

    Note:  If the refreshToken input is to be used instead of user credentials (username and password), then the input value must be set to true.

  • EndPointURL

    A string value, which specifies the REST API end point for SnapProtect to connect.

ServiceNowQueryRows Retrieves records from a specified table in ServiceNow.

This activity requires the following inputs:

  • tableName

    A string value, which specifies the name of the table to query.

  • displayLimit

    A string value, which specifies the maximum number of rows in the ServiceNow table.

  • filterQuery

    A string value, which specifies the conditions to filter records in the ServiceNow table.

    Example:

    To search for records created today with priority set to High, the filter query is:

    sys_created_onONToday@javascript:gs.daysAgoStart(0)@javascript:gs.daysAgoEnd(0)^priority=2

  • displayValue

    A string value, which specifies whether to return the display value (if set to true) or actual values of fields (if set to false).

  • displayFields

    A string value, which specifies the fields whose values are required.

  • authToken

    The authentication token received from ServiceNow after successfully logging on.

    Note: From the ServiceNowLogin activity, use the authToken value on the Output tab.

  • EndPointURL

    A string value, which specifies the REST API end point for SnapProtect to connect.

ServiceNowGetRowByID Obtains records from the ServiceNow table based on the system-generated ID.

This activity requires the following inputs:

  • tableName

    A string value, which specifies the name of the ServiceNow table to query.

  • ID

    A string value, which specifies the system-generated ID of the record.

  • displayFields

    A string value, which specifies the fields whose values are required.

  • displayValue

    A string value, which specifies whether to return the display value (if set to true) or actual values of fields (if set to false).

  • authToken

    The authentication token received from ServiceNow after successfully logging on.

    Note: From the ServiceNowLogin activity, use the authToken value on the Output tab.

  • EndPointURL

    A string value, which specifies the REST API end point for SnapProtect to connect.

ServiceNowAddRow Creates new records in ServiceNow.

This activity requires the following inputs:

  • tableName

    A string value, which specifies the name of the ServiceNow table where to add records.

  • fields

    An object value, which collects the elements to be processed in a list. For more information, see the CommServDBQuery activity.

    Note: To add new entries to the list, right-click fields and select List > New.

  • authToken

    The authentication token received from ServiceNow after successfully logging on.

    Note: From the ServiceNowLogin activity, use the authToken value on the Output tab.

  • EndPointURL

    A string value, which specifies the REST API end point for SnapProtect to connect.

ServiceNowUpdateRowByID Modifies the specified records from tables in ServiceNow.

This activity requires the following inputs:

  • tableName

    A string value, which specifies the name of the table that contains the records.

  • ID

    A string value, which specifies the system-generated ID of the record.

    If the record ID is not available, use the ServicenowQueryRows activity to query the table before using this activity.

  • fields

    An object value, which collects the elements to be processed in a list, for more information, see the CommServDBQuery activity.

  • authToken

    The authentication token received from ServiceNow after successfully logging on.

    Note: From the ServiceNowLogin activity, use the authToken value on the Output tab.

  • EndPointURL

    A string value, which specifies the REST API end point for SnapProtect to connect.

ServiceNowDeleteRowByID Deletes the specified record from the table in ServiceNow.

This activity requires the following inputs:

  • tableName

    A string value, which specifies the name of the ServiceNow table that contains the records.

  • ID

    A string value, which specifies the system-generated ID of the record in the ServiceNow table.

    Note: If the record ID is not available, use the ServicenowQueryRows activity to query the table before using this activity.

  • authToken

    The authentication token received from ServiceNow after successfully logging on.

    Note: From the ServiceNowLogin activity, use the authToken value on the Output tab.

  • EndPointURL

    A string value, which specifies the REST API end point for SnapProtect to connect.

User Interaction

EndUserSession Closes the last interactive user session opened.
InformationalMessage Displays a message to the user. To display the message, the message input must be set.

The message can be added as a text or an html message with a title name. You can also change the message style to display as a pop-up message or alert message.

The pop-up message can be further classified as Information, Warning, or Error.

Prior to execution of this activity, an interactive user session needs to be started by setting the Start interactive session property to True on either the Workflow property General tab or the UserInput activity General tab.

Sample Use Case

Add this activity to the end of a Workflow to display a custom message such as “Your request has been submitted for approval.”

PopupInput Presents a pop-up window where the user can enter data.

From the Inputs tab, define the inputs the user will be prompted to enter. Click Customize to add additional options to the input variables, for example, to make an input a required field. For details on customizing activity inputs, see Customizing Activity Inputs.

Prior to execution of this activity, an interactive user session needs to be started by setting the Start interactive session property to True on either the Workflow property General tab or the UserInput activity General tab.

Sample Use Case

Add this activity near the beginning of a Workflow to prompt a user to correct a problem with previously entered data.

UserInput Creates an action item for a user. The user completes this action by one of the following methods:
  • Go to Workflows > Interactions and open the job associated with the action.
  • Go to the Forms application in the Web Console and click the Actions tab. For information on the Web Console, see Overview - Web Console.
  • If the Enable reply via email check box is selected in the Email tab of the activity, respond to the email with the actions defined in the Actions tab.

    Before the Enable reply via email check box can be used, additional settings must be added. To add the additional settings, see Enabling Reply via Email for the UserInput Activity.

Configuration

General tab: To display informational messages or pop up inputs after the action is performed (interactive sessions), set the Start interactive session property to True.

Inputs tab: Define the inputs the user will be prompted to enter. Click Customize to add additional options to the input variables, for example, to make an input a required field. For details on customizing activity inputs, see Customizing Activity Inputs.

Actions tab: If Enable reply via email is selected in the Email tab of the activity, define what the user can send in the email reply, for example, Approve or Deny.

Users tab: Add the users who should complete this action. Note: If the action is sent to multiple users, the action is marked as completed when the first user responds.

Email tab: To allow users to complete the action by replying to the email, select Enable reply via email. In the box where you type the body of the email, list the actions you defined in the Actions tab. For example, type "Please respond to this request by clicking Reply and type either Approve or Deny in the body of the email." If you do not enter instructions, the users who receive the email will not know the acceptable responses.

Sample Use Case

Add this activity to a Workflow to send a manager an action to approve a new machine request from his team member.

Utilities

AssignValues Allows you to update the values of Workflow inputs and/or variables during the execution of the Workflow.

From the Workflow Inputs and Workflow Variables tabs, you can define the values for the inputs and variables that you want to update. For example, assume that there is a variable for a client name, and that you are using the CommServDBQuery activity to retrieve all clients in the CommCell. You can use AssignValues to capture the first client from the query by specifying the xpath expression in the Workflow Variables tab, such as:

xpath:{/workflow/CommServDBQuery_1/resultSets[1]/row[1]/col[2]}

where the client name is located in the second column of the first row.

CommServDBQuery Runs SQL queries against the CommServe database. To query the database, the user executing the Workflow must have the Administrative Management capability on the CommServe computer.

To configure the CommServDBQuery activity, provide the following details in the SQL Batch tab:

  • Specify the SQL query in the space provided.
  • Select the CommCell on which you want to run the query from the CommCell drop-down list. You can also insert a variable in the CommCell box to dynamically run a query on a CommCell specified through the variable.

    By default, the current CommCell (on which the Workflow engine resides) is selected. You can run the SQL query on a different CommCell If you have registered other CommCells. See Register a CommCell for more information.

You can also define parameters within the SQL query. This is useful when you execute the Workflow through a website prone to SQL injection attacks. The parameters are designated as ? in the SQL query and the values are defined in the Parameters tab. The index number of these parameters correspond to the order in which the ? is added to the SQL query. For example, the first ? in the query is parameter index 1, the second ? in the query is parameter index 2, and so on.

When the SQL query runs, the output is saved as result sets, which are further divided into rows and columns. The data type of the output is classified as follows (as seen in the Outputs tab):

  • resultSets, returns a List<DataSet> object
  • commCell, returns the name and ID of the CommCell
  • row, returns a List<DataRow> object
  • col, returns a List<Object>
  • errorCode, returns the database error. This is the same error code you see in the SQL Server when a query fails.
  • errorMessage, returns the message associated with the database error.

To access the data from the result sets, you will need to use an xpath expression. For example, use one of the following expressions if you want to retrieve the value from the first result set, row and column:

xpath:{/workflow/CommServDBQuery_1/resultSets[1]/row[1]/col[1]}

  • By default, the query returns the value in the first result set, row and column when the index parameter '[...]' is not specified. In xpath queries, the index always starts from 1, and not 0.
  • If you specify an index that does not exist, the output of the query will be a NULL value. The same applies if you specify a non-existing resultset/row/column name.

You can also reference column names by specifying them as follows:

xpath:{/workflow/CommServDBQuery_1/resultSets[1]/row[1]/col[@name=”columnname”]}

The value within the quotes is the string returned by the SQL query as either the column name or the alias name (if specified in your query). This is a good practice over using numbered index references because if you change the SQL query to output more columns and the index changes, referencing them by name will still work.

See the following examples of how to retrieve the data from the result sets:

EXAMPLE 1: Retrieve Data by specifying the column value

Consider that you defined a SQL query to retrieve the information of a client with the name cwslab05. To better explain this scenario, the following image shows this query and its result from the SQL Server:

Assuming that you want to access the net_hostname of the client, you can get the value of this property by specifying the column name or index:

xpath:{/workflow/CommServDBQuery_1/resultSets[1]/row[1]/col[@name="net_hostname"]}

xpath:{/workflow/CommServDBQuery_1/resultSets[1]/row[1]/col[4]}

EXAMPLE 2: Retrieve Data by specifying the row and column value

Consider that you defined a SQL query to retrieve the information of:

  • clients with the name cwslab05, and
  • Agents installed on a client whose ID is from a client with the name cwslab05

To better explain this scenario, the following image shows these queries and their results from the SQL Server:

In this scenario, you will get more than one result set, as shown in the image above. See the following ways to access the data using row and column values:

  • Getting the data from the third row in the second result set:

    xpath:{/workflow/CommServDBQuery_1/resultSets[2]/row[3]/col[4]}

  • Getting the subclient name of the Agent from the first row in the second result set:

    xpath:{/workflow/CommServDBQuery_1/resultSets[2]/row[1]/col[@name="subclientName"]}

EXAMPLE 3: Retrieve the number of Result Sets, Rows and Columns

Since the output of this activity are list types, you can use the xpath function count() to retrieve the number of elements in the list. Use the following xpath expressions to retrieve the number of:

  • Result Sets

    xpath:{count(/workflow/CommServDBQuery_1/resultSets)}

  • Rows

    xpath:{count(/workflow/CommServDBQuery_1/resultSets[1]/row)}

  • Columns

    xpath:{count(/workflow/CommServDBQuery_1/resultSets[1]/row[1]/col)}

You can also use Java expressions to retrieve the number of result sets, rows and columns as follows:

java:{xpath:{/workflow/CommServDBQuery_1/resultSets}.size()}}:java

java:{xpath:{/workflow/CommServDBQuery_1/resultSets[1]/row}.size()}}:java

java:{xpath:{/workflow/CommServDBQuery_1/resultSets[1]/row[1]/col}.size()}}:java

EXAMPLE 4: Using Java to manipulate the output data

You can manipulate the output data programmatically as shown in the below Java code, where the code tries to retrieve some client information from the first result set:

However, if you want to iterate through each of the result sets instead of checking only the first one, you can use the .get(n) method on the list object as shown below:

ResultSet resultSets = xpath:{/workflow/CommServDBQuery_1/resultSets}.get(n);

// where n is the index (starting from 0) for the result set that you want to retrieve

for (DataSet ds : resultSets){   

// do something with resultSet

}

EXAMPLE 5: Retrieving the Client Names using a Loop Activity

Consider that you want to use the ForEach activity to iterate through the SQL query for retrieving the details of all clients in your CommCell. Define one of the following xpath expressions in the ForEach activity:

  • If you want to iterate through the client names, then use:

    xpath:{/workflow/CommServDBQuery_1/resultSets[1]/row/col[@name=’name’]}

  • If you want to iterate through all the columns (which are the client details) for the first client in the list, then use:

    xpath:{/workflow/CommServDBQuery_1/resultSets[1]/row}

DisableLogging Disables the log files from recording non-error events occurring during the Workflow job. This activity is useful when you do not want the log files to show sensitive information from one or more activities in the Workflow. DisableLogging should be used along with EnableLogging to resume the log record for other activities.

If the Workflow job completes (or goes pending, suspended, etc) while the logs are disabled, then the Workflow will re-enable the logs in order for them to include the exiting information.

Email Sends an email to specific users using the SMTP settings configured in the CommCell Console. Emails can be sent in HTML or text format.

This activity requires the following inputs:

  • From (Optional)

    Specifies the sender's address. By default, it uses the email specified in the SMTP settings of the CommCell.

  • To

    Specifies the users that will receive the email. For example, you can insert a variable that represents a determined set of users.

  • Subject

    Specifies the subject matter of the email. For example, you can reference the Workflow name or job ID by inserting the Workflow variables.

  • HTML

    Sets the email in HTML format.

  • TEXT

    Sets the email in text format.

  • <email body space>

    This space allows you to provide any details to inform the users. If the HTML format is selected, additional editing options are provided in the Edit, Format and Insert menu options.

For an email activity example, see Step 13 in Getting Started.

EnableLogging Enables the log files after they have been disabled by the DisableLogging activity so that the log files continue to record the events occurring during the Workflow job.
ExecuteCommand Executes a command on a specific client computer in the CommCell. The user running this activity must have the Agent Management capability on the client where the command will be executed. Important: The ExecuteCommand activity is supported for clients running SnapProtect Software version 10 or higher.

This activity requires the following inputs:

  • client

    Specifies the name of the client computer. This input provides the existing clients in the CommCell for selection.

  • impersonateUserName (Optional)

    A string value which specifies the account name on the client computer, with sufficient privileges to execute the command.

  • impersonateUserPassword (Optional)

    An encrypted string value which specifies the password for the above user name.

  • startUpPath

    A string value which specifies the location where the command will be executed.

  • command

    A string value which specifies the command to be executed e.g., an executable file name.

  • arguments

    A string value which specifies any arguments that will be needed by the command during execution.

  • waitForProcessCompletion

    Determines if the activity should wait for the command to finish. This input provides a true or false value for selection.

ExecuteScript Executes a script defined in the Workflow. The content of the script is embedded in the Workflow and the activity runs the script on the remote client computer. The user running this activity must have the Agent Management capability on the client where the script will be executed. Important: The ExecuteScript activity is supported for clients running SnapProtect Software version 10 or higher.

This activity requires the following inputs:

  • client

    Specifies the name of the client computer. This input provides the existing clients in the CommCell for selection.

  • impersonateUserName (Optional)

    A string value which specifies the account name on the client computer, with sufficient privileges to execute the script.

  • impersonateUserPassword (Optional)

    An encrypted string value which specifies the password for the above user name.

  • startUpPath

    A string value which specifies the location where the script will be executed.

  • scriptType

    A string value which specifies the type of script file to be executed e.g., batch file, python, powershell, etc.

  • script

    A string value which specifies the actual script to be executed .

  • arguments (Optional)

    A string value which specifies the arguments appended to the interpreter running the script. For example, if you are running a PowerShell script, you could use the arguments -OutputFormat XML so that the powershell script returns the results in XML format. The XML format can then used by the XPathQuery activity to retrieve the data from the script.

  • waitForProcessCompletion

    Determines if the activity should wait for the script to finish. This input provides a true or false value for selection.

If the script already exists, you can use the ExecuteCommand activity to run the script on the remote client computer.

GenericResponse Sends information to the user regarding a specific event occurring in the Workflow during execution. When the Workflow is executed from the command line and it reaches this activity, it will display the resulting error code and message (obtained from XPathQuery activities) which will help to determine the course of action in the Workflow.

The following inputs are required:

  • errorCode

    An integer value which specifies the error code.

  • errorMessage

    A brief text informing the user about the error.

HttpClient Sends HTTP requests to access REST APIs or other web services. The response retrieved from these web services are later used within the Workflow.

The following inputs are required:

  • Method

    The HTTP method to be used in the request. The valid methods are GET, POST, PUT, and DELETE.

  • URL

    Specifies the complete URL to access the web service API. For example, to access the GET Client REST API, type the following:

    http://<web server host name>:81/SearchSvc/CVWebService.svc/client/{clientId}

  • URL Parameters

    Specifies any additional parameters to be sent with the URL. Click Add to insert new parameters.

    The URL parameters can be entered directly in the URL test field or added as individual parameters in the table provided. When parameters are added to the table, the values are automatically encoded in the URL.

  • Headers

    Specify any additional header information for the HTTP request. For example, to access REST APIs, you need to specify the authentication details to access the web service.

  • Data

    Used with POST and PUT methods. Any HTTP forms or raw XML scripts added here are posted to the API.

    Click Add to insert new HTTP forms.

After the inputs are added, click Preview to view the HTTP request.

LogEvent Allows you to log an event for the Workflow job. The event can be seen in the Event Viewer window of the CommCell Console.

The following inputs are required to specify the event details:

  • severity

    A string value which specifies the severity level of the event (such as critical and moderate levels).

  • message

    A string value which specifies the description of the event.

PSExec Executes a command on any remote client computer.  The PSExec activity has the following advantages over ExecuteCommand activity:
  • The remote client is not required to be part of the CommCell.
  • Ability to execute commands that require a restart of CommCell Services.

    The ExecuteCommand activity may fail when the Services are down.

This activity requires the following inputs:

  • hostName

    Specifies the name of the remote client computer.

  • UserName

    A string value which specifies the account name on the client computer, with sufficient privileges to execute the command.

  • Password

    An encrypted string value which specifies the password for the above user name.

  • useImpersonation

    A boolean value to allow user impersonation when Workflow engine and the remote client are on the same domain.

  • program

    A string value which specifies the command to be executed e.g., an executable file name.

  • arguments

    A string value which specifies any arguments that will be needed by the command during execution.

ResultSetToText Converts data from result sets to a delimited text string.

For example, you can retrieve SQL data from the CommServDBQuery or SQLQuery activity and convert it to a CSV file.

This activity requires the following inputs:

  • resultSet

    A dataset value that specifies the result set output of a SQL query.

  • delimiter

    A string value that specifies the delimiter to be used for the conversion.

  • headers

    A boolean value to include column headers during conversion.

Script Executes Java or JavaScript in the Workflow. Select Java or JavaScript from the Select Language box in the upper right of the Script tab. Type your code into the Script tab.

Java Examples

  • In the QOperationExecute activity, you have XML to associate a CommCell user to a user group. If you want this activity to fail the Workflow when an error code is found in the XML output, type the following script:

    #Script Sample

    if (Execute_1.exitCode == 0)
    {
      XML xml = utils.parseXml(Execute_1.outputXml);
      Execute_1.exitCode = xml.selectSingleNode("/App_UpdateUserGroupPropertiesResponse/response/@errorCode");
      if (Execute_1.exitCode != 0) {
    workflow.setFailed(xml.selectSingleNode("/App_UpdateUserGroupPropertiesResponse/response/@errorString"));
      }
    }

  • Reading a file into a workflow:

    Note: Backslashes (\) in the directory path must be escaped.

    String contents = "";
    contents = commvault.cte.workflow.utils.WorkflowUtils.readFile("c:\\filename.txt");
    return contents;

JavaScript Example

The GET Client Properties REST API was accessed using the HttpClient activity. If you want to retrieve the client name from the JSON response, type the following script:

var response = JSON.parse(xpath:{/workflow/HttpClient_3/output});
var clName = response.clientProperties[0].client.clientEntity.clientName;

TextToResultSet Converts a delimited text string to a result set output.

For example, you can read a CSV file into a Workflow using the Script activity and then use the TextToResultSet activity to convert the text to a result set.

This activity requires the following inputs:

  • text

    A string value that specifies the delimited text to be converted.

  • delimiter

    A string value that specifies the delimiter used for the conversion.

  • headers

    A boolean value to include column headers during conversion.

SQLQuery Runs queries on any SQL Server database. This activity requires the following inputs:
  • databaseType

    Specifies the type of database. By default, it is set to MSSQL, which stands for SQL Server databases. Other database types are currently not supported.

  • server

    Specifies the database instance name as seen in the SQL Server.

  • databaseName

    Specifies the name of the database where you want to run the queries.

  • userName

    Specifies a user with sufficient privileges to run queries on the database. You can also provide a domain user account, to perform SQL queries on the database. For example, sample_domain\user1.

  • password

    Specifies the password for the user name provided.

  • query

    Specifies the SQL query.

    You can also define parameters within the SQL query. This is useful when you execute the Workflow through a website prone to SQL injection attacks. The parameters are designated as ? in the SQL query and the values are defined in the Parameters tab. The index number of these parameters correspond to the order in which the ? is added to the SQL query. For example, the first ? in the query is parameter index 1, the second ? in the query is parameter index 2, and so on.

When the SQL query runs, the output is saved as result sets, which are further divided into rows and columns. The data type of the output is classified as follows (as seen in the Outputs tab):

  • resultSets, returns a List<DataSet> object
  • commCell, returns no values because the query is not run on the CommServe database.
  • row, returns a List<DataRow> object
  • col, returns a List<Object>
  • errorCode, returns the database error. This is the same error code you see in the SQL Server when a query fails.
  • errorMessage, returns the message associated with the database error.

To view examples on how to retrieve the data from the result sets, see the CommServDBQuery activity.

UpdateJobDescription Updates the description of the Workflow job during execution in the Job Controller window of the CommCell. This activity requires the following inputs:
  • operation

    A string value which determines if you want to overwrite the existing job description with a new one, or if you want to append the new description next to the existing one. By default, this input is set to overwrite the description.

  • jobDescription

    A string value which specifies the new description for the Workflow job.

XPathQuery Retrieves data from any XML output.

In order to extract the xml data, view the XML output from the workflowengine.log file or from the command line (if the xml is generated from a QCommand), and then determine how to retrieve the exact data you need.

To retrieve a value from an element, do not use an @ symbol in the xpath value:

  • Sample XML: /Element1/Element2/Element3
  • Example: /TMMsg_CreateTaskResp/jobIds[1]/val

To retrieve a value from an attribute, use an @ symbol in the xpath value:

  • Sample XML: /Element1/Element2 attribute=value
  • Example: /TMMsg_CreateTaskResp/jobIds[1]/@val

Tip: Search online for more information on using XPath query language and free online query parsers that can help you construct queries.

Example 1

In this example, the XpathQuery activity is used to retrieve the job ID from the output of a qoperation execute activity. The output of the qoperation execute activity returned the line below as seen in the workflowengine.log:

372 6435899 05/20 06:11:38 1128432 CommandActivity : command succeeded with result [<TMMsg_CreateTaskResp taskId="337364"><jobIds val="1128439" /></TMMsg_CreateTaskResp>]

The XpathQuery inputs would be:
  • xml

    xpath:{/workflow/Execute_1/outputXml} - This is the output of the command that started the job.

  • xpath

    /TMMsg_CreateTaskResp/jobIds[1]/@val - This is the xpath query language statement that will select the job ID from the val attribute of the given xml.

Result: The output of the XPathQuery activity is 1128439. The output can be used in subsequent activities.

Example 2

In this example, the XpathQuery activity is used to read multiple <client> elements from the output of a qoperation execute activity. Then each <client> element is processed in the ForEach activity. The output of the qoperation execute activity returned the XML below:

<client clientId="337364" clientName="client001"/>
<client clientId="458504" clientName="client002"/>

The XpathQuery inputs would be:

  • xml

    xpath:{/workflow/Execute_1/outputXml} - This is the XML output from the qoperation execute activity.

  • xpath

    //client - This is the name of the element.

  • outputType

    XML

Pass the XML output into the ForEach activity and process each <client> element inside the ForEach block.

Utilities - List

AddToList Adds elements to a defined list, which is stored in the Workflow engine. This activity requires the following inputs:
  • addToList

    A string value which defines the name of the list where the items will be added.

  • itemToAdd

    An object value which specifies the item to be added to the list. For example, this value can be a variable for client computers.

ClearList Removes all the elements that were stored in a specific list. To specify the list, the listToClear input must be set. This input is a string value.
ExistsInList Checks if a given element exists in a specific list. This activity will return true or false if the element exists in the list. The following inputs are required:
  • listToCheck

    A string value which defines the name of the list that you want to check.

  • itemToCheck

    An object value which specifies the item that you want to check in the list.

RemoveFromList Removes an element from a specific list. This activity requires the followl>
  • removeFromList

    A string value which defines the name of the list from where you want to remove the item.

  • itemToRemove

    An object value which specifies the item to be removed from the list.

  • Workflows

    All existing workflow definitions You can include any workflow listed in this category into your own workflow the same way you add any other activity.