Built-In Activities for Workflows

Acquirelock

Allows the Workflow engine to obtain a lock on an entity name, for example, a client, a folder, or a file. During Workflow execution, other Workflow jobs running on the same entity name are blocked. This is useful when you want only one workflow acting on something or only one workflow of the same type started at one time.

Note: Workflows running on the same workflow engine and workflows running on multiple workflow engines are blocked by this activity.

This activity requires the following inputs:

• name

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

  Examples:

  1. Setting the name input to the workflow name blocks 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 for the threshold time limit in minutes. This is the number of minutes the acquirelock activity tries to acquire a lock on the workflow. After the time limit is reached, the activity stops its attempt to acquire the lock and sets the lockAquired output to false.

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 add a Decision activity inside the loop where you define an expression that triggers the Break activity.

Decision

Determines the path that the Workflow takes 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 Defining Activity Inputs 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. 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. By default, the value is false. Set this input to true if you want to move to the next item in the list when an item fails.

  For an example of this activity, see the Client Group Policy workflow. The workflow attempts to update the storage policy on the default subclients for every fetched client.

  Tips:

• If the set of tasks is similar for each element, increase the value of the numberOfParallelExecutions option.

• If there are variations in the tasks performed on the elements, add Decision activities inside the ForEach block.

ForEachJSON

Iterates through array element inside of a JSON string. This activity requires the following inputs:

• json

  The entire JSON object, represented as a string.

• path

  The path to the array inside the JSON object that selects the array to iterate through. To iterate through the elements in the responses in the following JSON example, type root.responses.

  {"root": { "responses": [ {"a": 1, "b": 2, "c": 3}, {"a": 1, "b": 2, "c": 3}, {"a": 1, "b": 2, "c": 3}, {"a": 1, "b": 2, "c": 3} ] }
  }

• 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. By default, the value is false. Set this input to true if you want to move to the next item in the list when an item fails.

  Working with the Output

  The output of the ForEachJSON activity is a list of JSON objects and those objects are determined by the value in the path input. For example, if the path equals root.clients and iterates through the following JSON:

  {"root": { "clients": [ {"clientName": "client001", "clientId": 1}, {"clientName": "client002", "clientId": 2}, {"clientName": "client003", "clientId": 3} ] }
  }

  The output of each iteration would be as follows until all of the clients are returned:

   
  { "clientName": clientName, "clientID": clientId
  }

  To retrieve the client names to use in other activities, inside the ForEach loop use a Script activity.

ForEachXML

Iterates through XML elements by combining the functionality of the XPathQuery and ForEach activities. This activity requires the following inputs:

• xml

  The path to the XML output of an activity, for example, xpath:{/workflow/Execute_1/outputXml}.

• xpath

  The xpath query language statement that selects the elements to iterate through. To iterate through the <response> elements in the following XML example, type /root/response.

  <root>
   <response a="1" b="2" c="3" />
   <response a="1" b="2" c="3" />
   <response a="1" b="2" c="3" />
   <response a="1" b="2" c="3" />
  </root>

• 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. By default, the value is false. Set this input to true if you want to move to the next item in the list when an item fails.

  Working with the Output

  The output of the ForEachXML activity is a list of XML objects and those objects are determined by the value in the xpath input. For example, xpath equals /root/client and iterates through the following XML:

  <root>
     <client>
       <clientName>client001</clientName>
       <clientId>1</clientId>
     </client>
     <client>
       <clientName>client002</clientName>
       <clientId>2</clientId>
     </client>
     <client>
       <clientName>client003</clientName>
       <clientId>3</clientId>
     </client>
  </root>

  The output of each iteration would be as follows until all of the clients are returned:

   
  <client>
     <clientName>client_name</clientName>
     <clientId>client_ID</clientId>
  </client>

  To retrieve the client names to use in other activities, inside the ForEach loop use an XPathQuery activity or a Script activity.

Fork

Splits the Workflow into multiple activity threads, which can be later combined to a single thread using the Join activity.

Tip: If you need to perform the same set of tasks on multiple elements, consider using a ForEach activity with parallel executions instead of the Fork 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 Commvault system administrator user.

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, use this activity to give the Workflow executor the same permissions as the Commvault system administrator 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 waits until all threads directly transitioning into the Join activity execute and complete. This includes threads created by the Fork activity and threads created outside of the Fork activity.

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.

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 do the following:

• 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 paths 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 that is used when all of the other transition condition values are false.

For more information on using expressions, see Defining Activity Inputs Using Expressions.

SwitchToJob

Switches a non-interactive workflow from API mode to job mode. For information about API mode and job mode, see Setting General Properties.

The SwitchToJob activity cannot be used with interactive workflows because the workflow job must be suspended to switch modes. (Interactive workflows have the Start Interactive Session workflow property set to True.)

Sample Use Case

A business logic workflow running in API mode can be switched to job mode when the input XML is processed after a user approves an operation.

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: CommServDBQuery, 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.

Note: When the WorkflowEnd activity is used inside a ProcessBlock activity, the workflow will not transition away from the process block.

This activity requires the following inputs:

• completionStatus

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

  Note: 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.

DownloadFile

Downloads an Edge Drive file or folder based on the path or the GUID.

PreviewFile

Previews an Edge Drive file based on the path or the GUID.

UploadFile

Uploads a file to the Edge Drive. The file GUID is an output of this activity.

CreateFolder

Creates an Edge Drive folder based on the parent folder path or the parent folder GUID. The folder GUID is an output of this activity.

DeleteFileOrFolder

Deletes an Edge Drive file or folder based on the path or the GUID.

ListFolderContents

Lists the contents of a folder based on the path or the GUID.

MoveFileorFolder

Moves an Edge Drive file or folder based on the path or the GUID.

RenameFileorFolder

Renames an Edge Drive file or folder based on the path or the GUID.

SearchFolderContents

Searches the contents of a folder and subfolders based on the path or the GUID. The activity returns the contents that match the search criteria defined in FilterXML input. For instructions and examples of the filter XML, see Filters for Search or List APIs.

DeleteShare

Deletes a share based on the share ID.

ModifyShare

Modifies a share based on the share ID.

ShareFileorFolder

Shares an Edge Drive file or folder based on based on the path or the GUID. The shareId is an output of this activity.

ViewShares

Retrieves the list of shared Edge Drive files and folders. To retrieve a list of all available shares, do not enter values in the shareId or driveType inputs.

AddCustomProperties

Adds custom properties to Edge Drive files and folders based on the GUID.

AddTags

Adds tags to Edge Drive files and folders based on the GUID.

DeleteCustomProperties

Deletes the custom properties from Edge Drive files and folders based on the GUID.

DeleteTags

Deletes tags from Edge Drive files and folders based on the GUID.

ListTags

Lists the tags assigned to an Edge Drive file or folder based on the GUID.

ViewCustomProperties

Lists the custom properties of an Edge Drive file or folder based on the GUID.

ViewPropofFileorFolder

Retrieves the properties of an Edge Drive file or folder based on the path or the GUID.

ViewEdgeDriveAccount

Retrieves the details of your Edge Drive account, for example, the root GUID.

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.

<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:

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.

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 Commvault, 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 Commvault 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 Commvault 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 Commvault 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 Commvault 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 Commvault 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 Commvault to connect.

EndUserSession

Closes the last interactive user session opened.

EndUserSessionWithOutputs

Closes the last interactive user session opened and sends the activity outputs as a response if activity outputs are defined.

InformationalMessage

Displays a message to the user. To display the message, the message input must be added as a text or as html. You can change the message style to display as a pop-up message or an 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.

If an action is defined in the Actions tab, the default time a user has to interact with this activity is 120 seconds. To change the default time, see Changing the Response Time for Interactive Activities. If no actions are defined, the workflow continues.

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 is prompted to enter. Click Customize to validate or add additional options to the inputs, for example, to make an input a required field. For details on validating inputs, see Validating Inputs for User Interaction Activities. For details on customizing inputs, see Customizing Inputs for User Interaction Activities.

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.

The default time a user has to interact with this activity is 120 seconds. To change the default time, see Changing the Response Time for Interactive Activities.

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, the properties for email approval must be configured. To configure the properties, 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 is prompted to enter. Click Customize to validate or add additional options to the inputs, for example, to make an input a required field. For details on validating inputs, see Validating Inputs for User Interaction Activities. For details on customizing inputs, see Customizing Inputs for User Interaction Activities.

• 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.

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.

Call

Triggers an activity through the third-party IFTTT platform.

This activity requires the following inputs:

• to

  This must be trigger@recipe.ifttt.com.

• sender

  The email address for the IFTTT account.

• subject

  The action to be trigger.

• body (Optional)

  Information such as the why the action needs to be triggered.

CommServDBQuery

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

You can use predefined security stored procedures with the CommServDBQuery activity. These stored procedures check which entities and permissions are part of user and user group security associations. For information on the available security stored procedures, see Security Stored Procedure Overview.

Configuration

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

• Specify the SQL query in the space provided.

• From the CommCell drop-down list, select the CommCell on which you want to run the query. You can also insert a variable in the CommCell box to dynamically run a query on a CommCell specified through the variable.

  Note

  By default, the 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 Registering a Remote CommCell for more information.

  You can also define parameters within the SQL query. This is useful to help prevent SQL injection attacks or to eliminate the need to manually escape the data before using it.

  For example, select hostname from app_client where name = ?.

  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.

  Working with Output

  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]}

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)

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

• To

  The users who receive the email. You can insert a variable that represents a set of users.

  Note: You can automatically carbon copy (Cc) a list of email recipients on emails sent from all workflows. For instructions, see Enabling Global Carbon Copy.

• Subject

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

• HTML

  Displays the email in HTML format.

• TEXT

  Displays the email in text format.

• <email body space>

  The body of the email. 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 permission on the client where the command will be executed. Important: The ExecuteCommand activity is supported for clients running Commvault 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. The parameters for the script content can be embedded in the script itself. The ExecuteScript activity runs the embedded script on the remote client computer defined in the startUpPath input. The user running this activity must have the Agent Management permission on the client where the script will be executed.

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, for example, batch file, perl, python, or powershell. The command interpreter for the selected script type must be found in the path of the account where the Commvault Communications Service (CVD) is running.

• 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.

GetCredentials

Allows you to get the user name and password saved in Credential Manager and use the credentials in other activities.

For example, to execute activities like ExecuteCommand and ExecuteScript, you can use the GetCredentials activity to get the current credentials and use it as inputs for these activities. When the credentials change, you can modify the information in Credential Manager.

This activity requires the following input:

• credential

  Specifies the name of the credential account. If the name of the credential account changes, you must update the credential input.

  This activity returns the following outputs:

• userName

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

• password

  An encrypted string value which specifies the password of the credential account. Password output can be used in the activity where the EncryptedString input type is being used.

RespondToCaller

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:

  /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.

IsRequestSigned

Checks the input request XML for an authorization code when the SignRequest activity is used. The authorization code is inserted in the XML to authorize the XML that is executed based on a user request.

This activity returns a True or False value.

JSONToResultSet

Converts a JSON string to a result set output.

This activity requires the following input:

• json

  A JSON string that you want to convert to a result set output.

  For example, you can write a JSON with an array of clients to create a result set output.

  Input:

  [

      {

          "ClientName" : "Client1",

          "ClientId" : "99"

      },

      {

          "ClientName" : "Client2",

          "ClientId" : "100"

      }

  ]

  Output:

  	ClientName	ClientId
  1	Client1	99
  2	Client2	100

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 the ExecuteCommand activity:

• The remote client does not have to be part of the CommCell environment.

• 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, for example, an executable file name.

• arguments

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

• additionalParameters (optional)

  A string value which specifies any parameter needed by the command during execution. For a list of supported parameters, go to Using PsExec, under Process Utilities on the Microsoft website.

RestartServices

Restarts all Commvault services on the client.

This activity requires the following input:

• client

  Specify the client computer in the CommCell to restart the services on.

ResultSetToHTML

Converts data from result sets to an HTML table.

This activity requires the following inputs:

• resultSet

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

• headers

  A boolean value to include column headers during conversion.

  Sample Use Case

  Use this activity to embed a SQL result into an HTML email.

ResultSetToJSON

Converts data from a result set to JSON.

This activity requires the following input:

• resultSet

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

  For example, you can convert a result set of a client dataset to a JSON string.

  Input:

  	ClientName	ClientId
  1	Client1	99
  2	Client2	100

Output:

[

    {

        "ClientName" : "Client1",

        "ClientId" : "99"

    },

    {

        "ClientName" : "Client2",

        "ClientId" : "100"

    }

]

ResultSetToText

Converts data from result sets to a delimited text string. For example, you can retrieve SQL data from CommServDBQuery or SQLQuery activity and convert them 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 Example

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, you can 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"));
}
}

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;

SignRequest

Inserts an authentication code in the input XML request, for example:

<signedRequest>...attributes name="authCode" value="1461d71e-0140-4ada-bd95-caae7test430"...</signedRequest>

Use the IsRequestSigned activity to check for the authentication code.

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.

• properties

  Specifies additional inputs needed to access the SQL Server database. For example, you can pass Applicationintent=ReadOnly as the value for the properties input.

• 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.

For examples of how to retrieve the data from the result sets, see Retrieve Data from Result Sets.

TextToResultSet

Converts a delimited text string to a result set output. For example, when you load a CSV file to a Workflow and want to query the data, you can use the TextToResultSet activity to convert the text to SQL data and retrieve the data from the CSV file using the XPathQuery activity.

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.

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.

XPathMultiQuery

Retrieves data from multiple elements and attributes from any XML output. 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.

For each element or attribute you want to extract from the XML, add a new xpaths block. On the Inputs tab, click xpaths, right-click, and then click List > New.

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/Element3/@attribute

• 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

  In this example, the XPathMultiQuery activity is used to retrieve the start time and the status from part of the output of the DBMaintenance workflow. The output of the DBMaintenance workflow returns the following XML as seen in the workflowengine.log:

  <Email_1>
     <system>
       <startTime>1503860523</startTime>
       <endTime></endTime>
       <status>RUNNING</status>
       <timedOut>false</timedOut>
     </system>
     <emailSent>true</emailSent>
     <errorMessage></errorMessage>
   </Email_1>

  The XPathMultiQuery inputs are:

• xml

  xpath:{/workflow/Email_1/outputXml} - this is the output of the Email_1 activity in the DBMaintenance workflow.

• xpaths > xpath

  /Email_1/system/startTime - this is the xpath query language statement that will select the start time from the startTime element of the given xml.

• xpaths > xpath

  /Email_1/system/status - this is the xpath query language statement that will select the status from the status element of the given xml.

  Result: The outputs of the XPathMultiQuery activity are 1503860523 and RUNNING. The outputs can be used in subsequent activities.

XPathQuery

Retrieves a single element or attribute from any XML output. To extract multiple elements and attributes, use the XPathMultiQuery activity. 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/Element3/@attribute

• Example: /TMMsg_CreateTaskResp/jobIds[1]/@val

Example

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 returns the following XML 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 are:

• 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.

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 following inputs:

• 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.

AttachNetwork

Applies To: Hyper-V, VMware

Attaches the virtual network switch to the virtual machine.

This activity requires the following inputs:

• vmClientName

  The name of the virtual machine client.

• vmName

  The name of the virtual machine. You must provide either the vmName or the vmGUID.

• vmGUID

  The GUID for the virtual machine. You must provide either the vmName or the vmGUID.

• NetworkName

  The name of the virtual network switch.

• virtualizationClient

  The name of the virtualization client. The virtualization client is the single point of administration for backup and restore operations on the hypervisor.

CloneVM

Applies To: Hyper-V, VMware

Creates a copy of an existing virtual machine. The new virtual machine retains the same characteristics of the virtual machine from which it was cloned (such as the operating system).

This activity requires the following inputs:

• vmName

  The name of the virtual machine. You must provide either the vmName or the vmGUID.

• vmGUID

  The GUID for the virtual machine. You must provide either the vmName or the vmGUID.

• vmclient

  The name of the virtual machine client.

• newVMName

  The name of the virtual machine that is created.

• password

  An administrator password to use for the new virtual machine.

• policyName

  The name of the VM lifecycle policy to use for the new virtual machine.

• hostNameOrIPAddress

  The host name or IP address of the host.

• virtualizationClient

  The name of the virtualization client. The virtualization client is the single point of administration for backup and restore operations on the hypervisor.

CreateNetwork

Applies To: Hyper-V, VMware

Creates the virtual network switch. Use the AttachNetwork activity to attach the virtual network switch to the virtual machine.

This activity requires the following inputs:

• HostName

  The host name or IP address of the host.

• NetworkName

  The name of the virtual network switch.

• VirtualizationClient

  The name of the virtualization client. The virtualization client is the single point of administration for backup and restore operations on the hypervisor.

DeleteNetwork

Applies To: Hyper-V, VMware

Deletes the virtual network switch.

• HostName

  The host name or IP address of the host.

• NetworkName

  The name of the virtual network switch.

• VirtualizationClient

  The name of the virtualization client. The virtualization client is the single point of administration for backup and restore operations on the hypervisor.

DeleteVM

Applies To: Amazon, Azure Classic, Hyper-V, VMware

Deletes the virtual machine.

This activity requires the following inputs:

• vmClientName

  The name of the virtual machine client.

• vmName

  The name of the virtual machine. You must provide either the vmName or the vmGUID.

• vmGUID

  The GUID for the virtual machine. You must provide either the vmName or the vmGUID.

• virtualizationClient

  The name of the virtualization client. The virtualization client is the single point of administration for backup and restore operations on the hypervisor.

PowerOff

Applies To: Amazon, Azure Classic, Hyper-V, VMware

Turns off the virtual machine.

This activity requires the following inputs:

• vmClientName

  The name of the virtual machine client.

• vmName

  The name of the virtual machine. You must provide either the vmName or the vmGUID.

• vmGUID

  The GUID for the virtual machine. You must provide either the vmName or the vmGUID.

• virtualizationClient

  The name of the virtualization client. The virtualization client is the single point of administration for backup and restore operations on the hypervisor.

PowerOn

Applies To: Amazon, Azure Classic, Hyper-V, VMware

Starts a virtual machine after it has been suspended or powered off.

This activity requires the following inputs:

• vmClientName

  The name of the virtual machine client.

• vmName

  The name of the virtual machine. You must provide either the vmName or the vmGUID.

• vmGUID

  The GUID for the virtual machine. You must provide either the vmName or the vmGUID.

• virtualizationClient

  The name of the virtualization client. The virtualization client is the single point of administration for backup and restore operations on the hypervisor.

Reboot

Applies To: Amazon, Azure Classic, Hyper-V, VMware

Restarts the virtual machine.

This activity requires the following inputs:

• vmClientName

  The name of the virtual machine client.

• vmName

  The name of the virtual machine. You must provide either the vmName or the vmGUID.

• vmGUID

  The GUID for the virtual machine. You must provide either the vmName or the vmGUID.

• virtualizationClient

  The name of the virtualization client. The virtualization client is the single point of administration for backup and restore operations on the hypervisor.

RemoveNetwork

Applies To: Hyper-V, VMware

Removes the virtual network switch from the virtual machine.

This activity requires the following inputs:

• vmClientName

  The name of the virtual machine client.

• vmName

  The name of the virtual machine. You must provide either the vmName or the vmGUID.

• vmGUID

  The GUID for the virtual machine. You must provide either the vmName or the vmGUID.

• NetworkName

  The name of the virtual network switch.

• virtualizationClient

  The name of the virtualization client. The virtualization client is the single point of administration for backup and restore operations on the hypervisor.

ReplaceNetwork

Applies To: Hyper-V, VMware

Replaces the existing virtual network switch on the virtual machine with the virtual network switch defined in the NetworkName input.

This activity requires the following inputs:

• vmClientName

  The name of the virtual machine client.

• vmName

  The name of the virtual machine. You must provide either the vmName or the vmGUID.

• vmGUID

  The GUID for the virtual machine. You must provide either the vmName or the vmGUID.

• NetworkName

  The name of the virtual network switch.

• virtualizationClient

  The name of the virtualization client. The virtualization client is the single point of administration for backup and restore operations on the hypervisor.

Synchronize

Applies To: Amazon, Azure Classic, Hyper-V, VMware

Synchronizes the virtual machine with its host to update the latest information from the CommServe computer. Use this activity if the IP address is not displayed or is incorrect, or if snapshots or hard disk information is not correctly displayed.

This activity requires the following inputs:

• vmClientName

  The name of the virtual machine client.

• vmName

  The name of the virtual machine. You must provide either the vmName or the vmGUID.

• vmGUID

  The GUID for the virtual machine. You must provide either the vmName or the vmGUID.

• virtualizationClient

  The name of the virtualization client. The virtualization client is the single point of administration for backup and restore operations on the hypervisor.

Workflows

You can include any predefined workflow into another workflow in the same way you would add any other activity. To eliminate duplication, you can write reusable workflows that perform specific functions and then use them in other workflows. Centralizing common tasks helps keep workflows maintainable and organized.