Workflow Activities - Create Your Own Activities

Table of Contents

Creating a Custom Activity Using the Workflow Window

If there are tasks that you want the Workflow to perform and they are not available in the list of workflow activities, you can create your own activities from the Workflow editor window and use them in your Workflow. When a custom activity is created, you can re-use it in any existing or future Workflow as it will be part of the workflow activity list of the CommCell.

You can create an activity based on a user-defined script, a user-defined command, user-defined XML operation, or a user-defined HTML client operation, with custom inputs. The following sections describe the steps to create these types of activities.

Creating a Script-Based Activity

The following steps will create an activity that changes a decimal value to a proper percentage value, for example, 0.7 is converted to 70%.

  1. From your Workflow window in the Activities pane, click Create Activity .
  2. In the New Activity Type dialog box, select Script from the Activity Type list and click OK.
  3. Click the General tab and provide the following general details:
    • For the Name property, enter the name of the activity, for example, PercentageToValue. This is the name you will see from the Activities node in the left pane.
    • For the Description property, specify what the activity does.
    • For the Group property, select the activity group where you want to place the new activity, for example, Utilities. If you do not select a group, the new activity will be placed in the Ungrouped group.
  4. Click the Inputs tab to define the input variables for the activity.

    In our example, the PercentageToValue activity needs a variable to store the percentage value:

    1. Click Add.
    2. Enter the name of the variable in the Variable Name box, for example, percentageValue.
    3. Select float from the Variable Type list and click OK.

    You can specify default values for the new input in the Value column.

  5. Click the Script tab to specify the Java or JavaScript code which this activity will perform.

    Following our example, the PercentageToValue activity will need code to return the percentage from the given float value, as shown below:

    return (activity.getInput("percentageValue")*100) + "%";

    Also, specify the activity output in the Output Variable box and select the output type from the Output Type list.

  6. Click OK.

    The new activity should be listed in the left pane under a specific activity group. You can drag the activity to the design area to start using it in your Workflow.

Creating a Command-Based Activity

The following steps will create an activity to execute a SQL query against a specific database as an example.

  1. From your <Workflow> window, click the Create Activity icon.

    By default, the Command activity type is selected. Click OK.

  2. Click the General tab and provide the following general details:
    • For the Name property, enter the name of the activity e.g., SQLquery. This is the name you will see from the Activities node in the left pane.
    • For the Description property, specify what the activity does.
    • For the Group property, select the activity group where you want to place the new activity e.g., Utilities. If you do not select a group, the new activity will be placed in the Ungrouped group.

  3. Click the Inputs tab to define the input variables that the activity will use.

    In our example, the SQLquery activity will need the following string variables to perform the query:

    • sqlServer, which will be the name of the client where the SQL Server resides
    • userName, which will the user account executing the SQL query
    • password, which will be password for the user account
    • database, which will be the name of the SQL database
    • query, which will be the actual SQL query

    To add the inputs follow these steps:

    1. Click Add.
    2. Enter the name of the variable in the Variable Name box, for example, sqlServer.
    3. Select string from the Variable Type list and click OK.

    If applicable, you can specify default value for the inputs in the Value column.

  4. Click the Definition tab to specify the command details. If you need to specify a variable that you created, click Insert Variable and select the variable from the list.

    Following our example, you can use this tab to specify the SQL query command details, as shown in the image below.

  5. Click OK.

    The new activity should be listed in the left pane under a specific activity group. You can drag the activity to the design area to start using it in your Workflow.

Creating an XML-Operation Based Activity

The following steps create an activity that creates a user.

  1. From your <Workflow> window, click the Create Activity icon.

    Select XML Operation from the Activity Type list and click OK.

  2. Click the General tab and provide the following general details:
    • For the Name property, enter the name of the activity, for example, CreateUser. This is the name you will see in the Activities node in the left pane.
    • For the Description property, specify what the activity does.
    • For the Group property, select the activity group where you want to place the new activity e.g., Utilities. If you do not select a group, the new activity will be placed in the Ungrouped group.
  3. Click the Inputs tab to define the input variables that the activity will use.

    In our example, the CreateUser activity will need the following string variables to perform the query:

    • username,  the name of the user account to be created
    • password, the password for the user account
    • fullname, the full name of the user for whom the account is being created
    • email, the email account for the user account being created

    To add the inputs follow these steps:

    1. Click Add.
    2. Enter the name of the variable in the Variable Name box, for example, CreateUser.
    3. Select string from the Variable Type list and click OK.

      If applicable, you can specify a default value for the inputs in the Value column

  4. Click the XML Input tab to specify the XML document details. If you need to specify a workflow variable or a variable that you created, click Insert Variable and select the variable from the list. Click OK.
  5. Click the Script tab to specify the Java or JavaScript code which this activity will perform.

    Following our example, the code will retrieve the output of the XML request. You can use this output perform any sort of data manipulation that you require.

  6. Click the Outputs tab to retrieve the output from the XML operation activity. You can set the xpath statements directly in the value of the output. Click OK.

  7. The new activity should be listed in the left pane under a specific activity group. You can drag the activity to the design area to start using it in your workflow.

Creating an HTTP-Client Based Activity

The following steps create an activity based on an HTTP client request using SnapProtect REST APIs.

  1. From your <Workflow> window, click the Create Activity icon.

    Select HTTP Client from the Activity Type list and click OK.

  2. Click the General tab and provide the following general details:
    • For the Name property, enter the name of the activity e.g., CreateUser. This is the name you will see in the Activities node in the left pane.
    • For the Description property, specify what the activity does.
    • For the Group property, select the activity group where you want to place the new activity e.g., Utilities. If you do not select a group, the new activity will be placed in the Ungrouped group.
  3. Click the Inputs tab to define the input variables that the activity will use.

    In our example, the CreateUser activity will need the following string variables to perform the query:

    • username,  the name of the user account to be created
    • password, the password for the user account
    • fullname, the full name of the user for whom the account is being created
    • email, the email account for the user account being created

    To add the inputs follow these steps:

    1. Click Add.
    2. Enter the name of the variable in the Variable Name box, for example, CreateUser.
    3. Select string from the Variable Type list and click OK.

      If applicable, you can specify a default value for the inputs in the Value column.

  4. Click the Definition tab to specify the details of the HTTP Client activity request. Select an HTTP method from the Method list. Click Preview to preview the action of the selected method.

  5. Click the Script tab to specify the Java or JavaScript code which this activity will perform.

    Following our example, the code will retrieve the output of the XML request. You can use this output perform any sort of data manipulation that you require.

  6. Click the Outputs tab to retrieve the output from the XML operation activity. You can set the xpath statements directly in the value of the output. Click OK.
  7. The new activity should be listed in the left pane under a specific activity group. You can drag the activity to the design area to start using it in your workflow.

Cloning a Custom Activity

Use the following steps to clone a custom activity:

  1. From your <Workflow> window, expand the required activities node.
  2. Right-click the activity you want to clone and click Clone.
  3. On the General tab, enter a name for the activity and select the activity group where you want to place this new activity e.g., Utilities, if you do not select a group, the activity is placed in the Ungrouped group.
  4. Click the other tabs to customize the properties.
  5. Click OK.

Exporting a Custom Activity

Use the following steps to clone a custom activity:

  1. From your <Workflow> window, expand the required activities node.
  2. Right-click the activity you want to clone and click Export.
  3. From the local browser window, navigate to the folder where you want to save the activity.
  4. In the File name box, type a name for the activity and then click Save.

    The activity is saved as an XML file in the folder you specified.

  5. Click OK.

Using Demo Custom Activities

To demonstrate the new custom activity types SnapProtect provides the following demo custom activities:

  • CMD_CreateUser

    Demonstrates how to create a user using the command-based activity.

  • REST_CreateUser

    Demonstrates how to create a user using the HTTP-client based activity.

  • SplitLines

    Demonstrates a way to take string inputs and create a list of lines from that string as output, using the script-based activity.

  • XMLOp_CreateUser

    Demonstrates how to create a user using the XML operation based activity.

You can also clone, import, and export these demo custom activities to use in your workflows. The steps to perform these tasks is the same as any custom activity.

Creating an Activity Package Using External Tools

By default, all the activities listed in the Available Built-in Activities document are provided by the Workflow engine. These activities are provided as a .jar file during the installation of the engine.

If you need a set of customized activities to implement your Workflow, you can implement your own activities and import them as a .jar file to the CommCell.

The following sections describe the steps to create an activity package:

Implementing a New Activity Package

There are many tools you can use to develop a custom activity as well as multiple ways to configure and control the data flow which the custom activity will use. This section provides an example of how to create an activity package using Eclipse as the developer tool.

  1. To get started, copy the following .jar files located in the software_installation_path/WFEngine folder to a new folder of your choice:
    • cte.jar
    • cte_tools.jar
    • workflowEgine.jar

    These .jar file give you the basic functionality needed to develop your custom activities.

  2. From the Java - Eclipse tool menu, click File > New > Java Project to create a JRE 1.6 project.
  3. Type a name for the project in the Project name box and click Next.
  4. Click the Libraries tab and then click Add External JARs to add the SnapProtect .jar files that you copied in Step 1.

  5. From the Java - Eclipse tool menu, click File > New > Class to create an activity class for your project. Your project may have more than one activity class.
  6. From the New Java Class dialog box do the following:
    1. Enter the package name of your project in the Package box.
    2. Enter a name for your activity class in the Name box.
    3. Select any other applicable option and then click Finish.
  7. Develop your activity class, having the following points in consideration:
    • Each activity class must implement the company.cte.workflow.activity.Activity interface interface and return AttemptStatus.SUCCESS or AttemptStatus.FAILED depending on the activity outcome.
    • Each input and output defined in the activity should have get/set functions implemented in order to be configured with a public or private modifier. Input/Output annotations are optional.
    • The ActivityContext property contains a lot of data which can be used in your activity. For example, you can modify the runtime of the ActivityContext with the context.setFailureReason() function in the try/catch block in order to show the pending reason message in the CommCell Console.

    See the following sample activity class implemented to import files:

    For your convenience, you can copy the code of the sample activity class from the following box:

  8. Once your activity class if implemented, you need to create the activities.xml file at the base folder of your project as shown in the image below:

    The XML must have the <activity> tag and the following parameters defined for each activity:

    • name, which specifies the name of the activity.
    • displayName, which specifies the activity name to be displayed in the Activities pane of the workflow editor window.
    • group, which specifies the category where the activity will be placed in the Activities pane.
    • icon, which specifies the path to the image that will be used by the activity in the Activities pane.
    • className, which specifies the name of the activity class that you implemented.

    For your convenience, a sample file for the activities.xml is provided below for download:

    sample_activities.xml

  9. Export the project to a JAR file using the steps below:
    1. From the Java - Eclipse tool menu, click File > Export.
    2. From the Export dialog box, select Java > JAR file.
    3. Specify the name of the .jar file and the folder where it should be exported in the JAR file box.
    4. Click Finish.

    For your convenience, a sample activity .jar file is provided below for download:

    sample_custom_activities.jar

  10. Copy the activity .jar file to the software_installation_path/WFEngine/classpath folder in the computer where the Workflow engine resides.

Importing Activity Package (.jar File) to the CommCell

  1. From the CommCell Browser, right-click the Workflows node and then click All Tasks > Activity Packages.

    If you have the Workflow editor window open, navigate to the left pane and click the icon shown in the image below.

  2. Click Import.
  3. From the Browse for activity jar file dialog box, browse and select the .jar file.
  4. Click OK to start importing the .jar file.
  5. Click OK to the pop up window indicating that the .jar file was successfully imported.
  6. Click Close.
  7. To verify the new activity is available, go to the left pane in the Workflow editor window and go to the group where the activity is associated.

    For example, the image below shows a custom activity listed under the Custom folder.

Deleting an Activity Package

Use the following steps to delete an activity package:

The workflow_activities.jar file cannot be deleted. This activity package is provided by default during the installation of the Workflow engine.

  1. From the CommCell Browser, right-click the Workflows node and then click All Tasks | Activity Packages.

    If you have the Workflow editor window open, navigate to the left pane and click the icon shown in the image below.

  2. Select the .jar file containing the activities you want to delete and then click Delete.

  3. From the Execute On dialog box, select the Workflow engine and then click OK. The engine needs to be executed to process the deletion request.
  4. Click OK to the pop up window indicating that the .jar file was successfully removed.
  5. Click Close.

Managing Web Services

Web services allows the integration of web based applications typically using XML, SOAP, WSDL and other standard services. Web services are mainly used for businesses to communicate with each other and with their clients.

You can use web services in a Workflow by importing them to the CommCell, which is then converted into workflow activities. This is useful if you are creating a Workflow for users that need to apply a particular business logic defined in a web service.

The following sections describe the steps to add web services as activities or remove existing ones.

Import a New Web Service

  1. From the CommCell Browser, right-click the Workflows node and then click All Tasks | Web Services.

    If you have the Workflow editor window open, navigate to the left pane and click the icon shown in the image below.

  2. Click Import and do the following:
    1. In the WSDL Location box, enter the URL of the web service (the actual WSDL) and then click Go. All available web services from the Web Services Description Language (WSDL) provided are shown. You can select or clear the web services you want to import.

      In the image below, the provided WSDL is for a web service which will get a stock quote.

    2. By default, the Workflow engine uses the service URL found in the WSDL to send the web service request. If you want the engine to use a different service, enter the desired service in the Service URL box.
    3. In the Execute On box, select the engine that will parse the WSDL and import the web service as an activity.
    4. Click OK.

  3. Click OK to the pop up window indicating that the web service was successfully imported.
  4. Click Close.
  5. To verify the new activity created from the web service, navigate to the left pane in the Workflow editor window.

    Based on the example provided in the above image, the GetQuote activity should be listed and ready to be used in the Workflow.

Delete a Web Service

  1. From the CommCell Browser, right-click the Workflows node and then click All Tasks | Web Services.

    If you have the Workflow editor window open, navigate to the left pane and click the icon shown in the image below.

  2. Select the URL of the web service and then click Delete.

  3. From the Execute On dialog box, select the Workflow engine and then click OK. The engine needs to be executed to process the deletion request.
  4. Click OK to the pop up window indicating that the web service was successfully removed.
  5. Click Close.