Tutorial: Creating Toolbox Activities

One of the unique features of PowerWF is the ability for users to extend it by adding their own toolbox activities. This tutorial will create a workflow that uses SAPI to speak whatever text is passed to it. This workflow will then be converted into a toolbox activity which can be dropped into other workflows

Topics Discussed

• Naming Activities
• Combining PowerShell and COM
• Using Input Parameters
• Creating Toolbox activities
• Using custom toolbox activities
• Using the ExecScript activity.
• Using the FormatString activity.
• Using the ForEach activity.
• Using the GetProperty activity.

Procedure

1. Create a new workflow project called “speakToMe”
2. This workflow will utilize the Speech API (SAPI) by using the ExecScript activity from the PowerShell V2 toolbox. Drop an ExecScript activity onto the canvas and set the script to:
   

   $sapi = new-object -com SAPI.SpVoice
   
   
   

   This command creates the SAPI object for later use.

3. To make the workflow more readable, set the Name of ExecScript1 to “Create SAPI”
4. Drop a second ExecScript activity onto the canvas and set the script to:
   
   $sapi.speak(“I hunger”);$sapi.waitUntilDone(10000);
   
   
   
   
   The speak command tells the speech API to say, “I Hunger”. To work properly, the speech API requires that an option be set to wait until the Speak activity is done before proceeding, unless it takes longer than 10 seconds.
5. For readability, set the Name of ExecScript2 to “SayWords”
6. Although PowerWF scripts will run in their own run-space and clean up automatically on shutdown, one more ExecScript activity can be added to clean up the SAPI object. Drop another ExecScript activity on the canvas and set the script to:
   
   $sapi = $null
   
   
   
   Set the name of the ExecScript to “CleanupSAPI”
   
   
   
7. Run the workflow to verify that the computer says “I hunger”. The next step is to parameterize this workflow, so that any text can be passed into it to be spoken. Add a SetVariable activity from the PowerShell toolbox and set the Name property to “words”.
   
   
   
   
8. Instead of setting the Value to a static value, click the yellow barrel icon and set the value to a new property. Name the new property “inputWords”.
   
   
   
   
9. To set the new property as an input parameter, click on the Parameters button. Set inputWords as an Input, set the Help Text to “Enter Text to Speak”, and set the Default Value to “Greetings Program”
   
   
10. The last step for parameterization is to set the spoken text to the inputText. This is done by altering the script for “execScript2” from
    
    $sapi.speak(“I hunger”);$sapi.waitUntilDone(10000);
    
    to
    
    $sapi.speak($Words);$sapi.waitUntilDone(10000);
    
    
11. Rerun the workflow, changing the inputWords from “Greetings Program” to “Wizard shot the food.”
12. Now that the script is properly parameterized, it can be added to the toolbox. Click the “Toolbox Activity” button on the “Deploy” tab of the ribbon bar. Set the toolbox name to “Speech” and insure that the checkbox to “Install into Toolbox…” is checked. Click the build button to create the activity.
    
    
13. The toolbox will refresh and contain a new Activity Group called “Speech”. Expand this group to see the speakToMe activity.
    
    
14. Now that the toolbox activity has been created, it can be used like any other activity in PowerWF. Create a new workflow called “AnnouncePointingDevices”.
15. Drop the “PointingDevice” activity from the Hardware activity pack onto the canvas.
    
    
16. Drop a “Count” activity on the canvas. This activity counts the number of objects in a list; in this case pointing devices.
    
    
17. Drop a FormatString activity on the canvas. Set Arg0 to the Count activities output.
    
    
18. Set the Format of the Count activity to:
    {0}, pointing devices
    
    

    Note: {0} tells the formatString to use Arg0, the “,” after {0} tells the speech API to insert a pause.

19. Drop the SpeakToMe activity on the canvas. Set the inputWords property to the output of the format string.
    
    
20. Drop a ForEach activity from the Flow Control activity pack and set its input to the output of the PointingDevice activity. The ForEach will walk through the list of pointing devices.
    
    
21. Drop in the GetProperty activity in the ForEach sequenceActivity. Set the Property Name to “Caption”
    
    
22. Drop in another SpeakToMe activity in the sequenceActivity. Set the inputWords to outputAsString property of the GetProperty activity.
    
    
23. Run the workflow. It will announce the number of pointing devices as well as describing each device.

Summary

This tutorial showed how to create toolbox activities in PowerWF. With custom toolbox activities, PowerWF can be easily extended and customized to a variety of environments.

The tutorial showed how to take advantage of COM objects in PowerShell. This tutorial used the ExecScript, FormatString, ForEach, and GetProperty activities as well as the new speakToMe activity that was created as part of the tutorial.

• #powershell
• #powershell tools
• #toolbox
• #tutorial
• #COM