Automate. Quest Software 3.1

PDF

Dokument

Reklamë

Automate

Scenario: Automate a Query and Email the Report

Scenario

You need to create an Excel report that contains current regions and addresses and email it to your manager every week.

Note: This scenario uses the Toad Sample (Access) database that ships with Toad for

Data Analysts.

To automate a task for this scenario

1. Connect to the Toad Sample (Access) database in the Navigation Manager.

2. Enter the following statements in the Editor and save them to a single file named

AutomationTest.sql:

Select * from region;

Select * from address;

3. Select Tools | Automation from the menu.

4. To send yourself an email if an error occurs, click Settings in the Automation design window and enter the following:

Stop or continue on error

Send email when an error occurs

Compose Email

Select Stop On Error

Select this option.

Email Server

Settings

Click Compose Email and enter your email address in the

To and the From fields.

In the Compose Email form, click Email Server Settings and enter your SMTP server address and the port number.

5. Click the Select To File database activity in the toolbox to add it to the design window.

6. Click the File_1 activity and select Toad Sample Database in the connection field.

Toad for Data Analysts User Guide

Automate

7. Click the File_1 activity and enter the following in the Activity Input window:

SQL file

Export file

Select AutomationTest.sql.

Select the following options: l

Destination—Ensure that the Excel file option is selected.

Then, select a folder and enter AutomationTestExcel as the file name.

Add Date/Time suffix to filename—Select this checkbox.

8. Click the Send Email file activity in the toolbox to add it to the design window.

9. Click the Send Email activity and enter the following in the Activity Input window:

From

Add

Attachments

Subject

Body

Enter your email address.

Click Add Attachments. Select AutomationTestExcel from

Activity Reports and click Add. Click the X in the upper-right corner of the dialog.

The file is added as an email attachment.

Enter Weekly Report.

Enter the following: Attached is a copy of the weekly regions and addresses report.

Click Email Server Settings and enter your SMTP server address and port number.

Server

Settings

10. Save the Automation script.

11. Click Test on the wizard bar to ensure that the script works. The automation script is compiled, then executed. All results display in the Log window.

12. Review the log and click the link to the Excel file generated to open the Excel file in Toad.

Notice that the results of each SQL statement are in a different worksheet.

13. To schedule the automation script to run at a later time, click Schedule on the wizard bar.

14. Complete the following fields:

Task Tab

Set password

Description

Click this button and enter and confirm your O/S password.

Toad for Data Analysts User Guide

Automate

Schedule

Schedule task

Start time

Description

Select Once.

Select a time that is 2 minutes from the current time.

15. Check your email for confirmation of execution as well as the status of the job manager window.

Automate Tasks

Use Automation to schedule a single script to run reports and queries, save results in Excel spreadsheets, and distribute results to the business community via email. You can schedule scripts that perform long-running tasks to run when database activity is light.

You can also use variables in automation scripts. With variables, you can update information that may be different each time you run the script, such as the department name, revenue,

fiscal quarter, or product name. See "Use Variables in Automation" (page 83) for more information.

For example, assume you are an analyst at Nick's Flicks movie rentals. You need to run inventory and movie rental reports on a daily basis and distribute them to managers of the inventory department. Using Toad, you create an automation script that runs the reports, exports them to Excel spreadsheets, and emails the spreadsheets to the inventory department everyday at 2:00 AM.

Troubleshooting: l

If Toad displays a "Variable must be initialized before referencing itself" error, you

need to initialize the variable. See "Use System Automation Activities" (page 79) for more information.

You must surround a variable name with the # sign (for example, #sleep#).

Note: This topic focuses on information that may be unfamiliar to you. It does not include all step and field descriptions.

To automate tasks

1. Click Automate.

2. Select the Settings icon in the script design window to specify the script settings before building your script. Use the Activity details pane in the bottom portion of the

Automation window to enter your settings. Review the following for additional information:

Toad for Data Analysts User Guide

Automate

Activity

Input

Stop or continue on

Error

Send email when error occurs

Select Stop On Error to stop the script if an error occurs.

Use relative path to find

SQL files

Select this option to send an email on script error.

If selected, you must also click Compose Email to compose the email message and to edit the Email Server Settings.

Note: When you specify the error email settings, Toad saves your settings and uses them in all subsequent automation scripts.

Select to use a relative path that does not include the drive or full path for all activities in the script. This is useful if you want to share your automation scripts with colleagues, use them with version control, or place them on a shared network folder.

Select to embed the actual SQL from SQL files in the script.

This makes it easier to share the script with colleagues.

Embed

SQL into

Automation script

Truncate log

Run Mode

Select to overwrite the log file each time the script runs.

Select Test mode to run your script in test mode using the database connection specified under Test settings.

Select Production mode to run your script in production mode using the database connection specified under Production settings.

Note: The default connection is the currently active, open connection.

Activity Info

Name Enter a script name.

3. To build your script, click an activity in the Toolbox, or drag an activity from the

Toolbox to the Automation script design window. Repeat to add additional activities to your script.

Note: You must drag the activity to the , then release the mouse button after you see the activity's icon replace the .

4. For each activity in your script, select the activity in the design window and then

Toad for Data Analysts User Guide

Automate

68 specify the activity's properties in the Activity details pane.

See the following topics for details about each activity and its properties: l

Use Database Automation Activities (page 69)

Use File Automation Activities (page 73)

Use System Automation Activities (page 79)

Tip: You can save an activity and its properties as a template to reuse in other scripts.

Right-click the activity in the design window and select Save As Template. After you create the first template, a Templates toolbox displays.

Note: Click Settings in the design window at any time to go back and review the

Automation script settings.

5. When you finish building your script, select one of the following actions from the

Automation toolbar or the Wizard bar:

Add to Project

Save

Run

Schedule

Add an automation script to the current project in the

Project Manager. The script is automatically placed in the project's Automation Scripts folder.

Save an automation script (.tas) in a folder on a local or network drive.

Run an automation script before scheduling it. The script executes once and the execution log is displayed in the

Log window. Resolve any problems that cause activities to fail, or disable failed activities before scheduling the script.

Tips: l

Press F5 to run the automation script.

To view the script log, select the Log tab or select

View | Output.

Schedule an automation script in the Job Manager. You can schedule a script to execute once or to run periodically

at a defined interval. See "Execute Automation Scripts"

(page 90) for more information.

Tips: l

Double-click an activity in the script design window to open the Activity Properties pane in a format used in earlier versions of Toad.

Right-click within the script design window and select Print Script to print the script's workflow diagram.

Toad for Data Analysts User Guide

Automate

Use Database Automation Activities

You can use the following activities in automation scripts.

Note: When building an automation script, you must have the appropriate connections open for database activities.

Tip: You can save an activity and its properties as a template to reuse in other scripts. Rightclick the activity in the design window and select Save As Template. After you create the first template, a Templates toolbox displays.

Activity

Database

Connection

Select to File

Description

In previous versions of Toad, the Database Connection activity was required in order to specify database connection details.

In the current version of Toad, the database connection details are specified in each activity's properties.

Notes: l

If the connection was open before the script ran, it closes the connection once the activities in the connection box are complete.

You can include connections for multiple databases in the same automation script.

Execute an existing SQL script or Query Builder query and export the results to an Excel, HTML, or CSV file. You can then use additional activities to add the exported result file to a zip file, attach the file to an email, or copy the file.

Review the following for additional information: l

Row count variable—Enter a name for the row count variable.

The value assigned to this variable equals the number of rows returned from the activity. You can use this variable with the

If..Condition.. and While system activities. See "Use Variables in Automation" (page 83) for more information on use cases for

this field.

SQL—Manually enter SQL or select a SQL script or Query

Builder query to run. For SQL scripts, you can create a new worksheet for the results of each SELECT statement in a script by entering GO after each statement.

Note: To manually enter SQL in the text box, deselect Link

SQL file.

Export file—Click the drop-down list to select the export file type. Then, select the file location and enter the name. You can use a variable in this field by entering the number sign before

Toad for Data Analysts User Guide

Automate

Activity

Execute Script

Select to

Editor with

Results

Description and after the variable (#VariableName#). If you select Excel

file, you can append the date and time that the file was generated to the file name as a suffix.

Note: You can only use one variable per field or file name (a suffix counts as one variable for a file name).

Execute an existing SQL script or Query Builder query.

Review the following for additional information: l

Row count variable—Enter a name for the row count variable.

The value assigned to this variable equals the number of rows returned from the activity. You can use this variable with the

If..Condition.. and While system activities. See "Use Variables in Automation" (page 83) for more information on use cases for

this field.

SQL—Manually enter SQL or select a SQL script or Query

Builder query to run. For SQL scripts, you can create a new worksheet for the results of each SELECT statement in a script by entering GO after each statement.

Result variable—Enter a name for the result variable, which contains a data table with the results of the execution script.

You can use the result variable with the Loop Dataset activity.

See "Use System Automation Activities" (page 79) for more information.

Execute an existing SQL script or Query Builder query and save it and any results sets in a Toad editor file (.tef).

This file format is useful for building scripts that have large result sets that you do not want to continue executing or for saving results when you have not finished building a script.

Review the following for additional information: l

Row count variable—Enter a name for the row count variable.

The value assigned to this variable equals the number of rows returned from the activity. You can use this variable with the

If..Condition.. and While system activities. See "Use Variables in Automation" (page 83) for more information on use cases for

this field.

SQL—Manually enter SQL or select a SQL script or Query

Builder query to run. For SQL scripts, you can create a new worksheet for the results of each SELECT statement in a script by entering GO after each statement. l

Editor File—Select the file location and enter the name. You can use a variable in this field by entering the number sign before and after the variable (#VariableName#).

Toad for Data Analysts User Guide

Automate

Activity Description l

Suffix—Select a suffix to append to the file name. The suffix can be the date and time that the file was generated or the content of a variable that you define with the Set Variable

system activity. See "Use System Automation Activities" (page

79) for more information.

Note: You can only use one variable per field or file name (a suffix counts as one variable for a file name).

Export Wizard Export data from databases, tables, views, or a query into a CSV,

Excel, or other file.

Review the following for additional information: l

Export template—You can select an existing template, edit an existing template, or create a new template.

Use automation connection—Select this option to use the connection associated with the database activity. Clear the checkbox to use the connection associated with the export template.

Import Wizard Import data from a CSV, Excel, or other file into a new table or append to an existing table.

Review the following for additional information: l

Import template—You can select an existing template, edit an existing template, or create a new template.

Use automation connection—Select this option to use the connection associated with the database activity. Clear the checkbox to use the connection associated with the import template.

Toad Report Use this activity to open one or more Toad data reports and export the contents as a PDF, HTML, Excel, CSV, RTF, or MHT file. You can then add another activity to your script to zip the new file, attach it to an email, or save it to a new location.

Review the following for additional information: l

Row count variable—Enter a name for the row count variable.

The value assigned to this variable equals the number of rows returned from the activity. You can use this variable with the

If..Condition.. and While system activities. See "Use Variables in Automation" (page 83) for more information on use cases for

this field.

Report files—Select one or more Toad data reports from the

Project Manager or other location, or edit an existing report.

Export file—Select the file type and location and enter the

Toad for Data Analysts User Guide

Automate

Activity

Toad Pivot

Grid

Clean Data

Description name. You can use a variable in this field by entering the number sign before and after the variable (#VariableName#).

Suffix—Select a suffix to append to the file name. The suffix can be the date and time that the file was generated or the content of a variable that you define with the Set Variable

system activity. See "Use System Automation Activities" (page

79) for more information.

Note: You can only use one variable per field or file name (a suffix counts as one variable for a file name).

Refresh an existing pivot grid and export results to an Excel, HTML, or CVS file. You can then add another activity to your script to zip the new file, attach it to an email, or copy it to a new location.

Review the following for additional information: l

Row count variable—Enter a name for the row count variable.

The value assigned to this variable equals the number of rows returned from the activity. You can use this variable with the

If..Condition.. and While system activities. See "Use Variables in Automation" (page 83) for more information on use cases for

this field.

Pivot file—Select a Toad pivot file from the Project Manager or other location, or edit an existing pivot file.

Export file—Select the file type and location and enter the name. You can use a variable in this field by entering the number sign before and after the variable (#VariableName#).

Suffix—Select a suffix to append to the file name. The suffix can be the date and time that the file was generated or the content of a variable that you define with the Set Variable

system activity. See "Use System Automation Activities" (page

79) for more information.

Note: You can only use one variable per field or file name (a suffix counts as one variable for a file name).

Execute data cleansing to create a new data set by filtering an existing data set or data source.

Review the following for additional information: l

Data cleansing creates a new, cleansed table and leaves the source table intact. Implement a data hub repository or some form of internal data store. Alternatively, you can specify a schema or database to create, or alter and drop tables.

Each data hub table needs a name and Test Representation

Language (TRL) representation. Groups of tables, data

Toad for Data Analysts User Guide

Automate

Activity Description validation actions, and the sequential flow between them are grouped and stored into projects displayed in the workbench.

Data Cleansing file—Select a data cleansing file or edit an existing file.

Row count variable—Enter a name for the row count variable.

The value assigned to this variable equals the number of rows returned from the activity. You can use this variable with the

If..Condition.. and While system activities. See "Use Variables in Automation" (page 83) for more information on use cases for

this field.

Export to file—Select a file location and enter the name. You can use a variable in this field by entering the number sign before and after the variable (#VariableName#).

Export to local storage—Select or create a database and table in local storage to receive cleansed data.

Notes: l

Status—Select Enabled to include the activity in script execution. Select

Disabled to disable the activity, for example, when testing other activities. Or right-click the activity in the design window and select/deselect Enabled.

Stop on Error—Allows you to select, for each activity, whether to stop or continue execution if Toad encounters an error.

Select the Log tab to review a script's execution log.

Automation does not support positional parameters denoted by a question mark.

For each activity, you can specify the database connection in the activity's properties. The default connection is the currently active, open connection.

Use File Automation Activities

You can use the following activities in automation scripts.

Activity

Copy File

Description

Copy or move one or more files to a shared folder where they can be accessed by your business community. You can copy or move a file generated by other activities in the automation script and overwrite an existing copy of a destination file.

Toad for Data Analysts User Guide

Automate

Activity

Delete File

Log Comment

Zip Files

Description

Review the following for additional information: l

Source file—Select a single file to copy, or use an asterisk

(*) as a wildcard to select multiple files in the same directory to copy.

Copy name—Enter the name. You can use a variable in this field by entering the number sign before and after the variable (#VariableName#).

Suffix—Select a suffix to append to the file name. The suffix can be the date and time that the file was generated or the content of a variable that you define with the Set

Variable system activity. See "Use System Automation

Activities" (page 79) for more information.

Move/Copy—Select Move to move a file from the source folder to a destination folder. Select Copy to copy the file to the destination folder.

Notes: l

If you want to use this activity for files generated by other automation activities, those activities must precede this one. The filenames and paths specified should match the directories and names displayed in properties for the preceding activities.

You can only use one variable per field or file name (a suffix counts as one variable for a file name).

Delete one or more files from a specified location. You can use this activity to delete files that are created earlier in the script.

Note: You can use an asterisk (*) in the FileName field as a wildcard to select multiple files in the same directory to delete.

Writes a comment to the scripts's log.

Create a zip file and add files to it. Files generated with other activities can be added to the zip file. You can then email the zip file to colleagues.

Review the following for additional information: l

Archive name—Select a location and name for the zip file.

You can use a variable in this field by entering the number sign before and after the variable (#VariableName#).

Encryption—Select whether to create a zip file without encryption (Standard) or to encrypt the zip file.

Note: If you encrypt the zip file, you must have a zip utility that can support 128-bit or 256-bit decryption.

Toad for Data Analysts User Guide

Automate

Activity

Find and Replace

Description l

Zip all files in this directory—Select a directory. All files in the directory will be included in the zip file.

Source files—Select one or more files. You can select files that are generated by the automation script.

Notes: l

You can only use one variable per field or file name (a suffix counts as one variable for a file name).

This activity opens one or more files and performs a find and replace within those files. You can write the results to a different location and file name.

Review the following for additional information: l

Find/Replace—You can have multiple Find/Replace tasks within one activity. You can specify a different set of properties for each Find/Replace task.

Source file—Select the file in which to perform the find and replace activity. To select multiple files for one

Find/Replace task, use standard wildcard characters in the file name.

Find—Enter the content to find.

Replace with—Select the type of replacement content: a value, contents from a file, or a variable.

Set value—Enter the replacement value, enter the replacement variable, or select a file containing replacement content.

You can use a variable in this field by entering the number sign before and after the variable (#VariableName#). In the following example, if variable X has a value of 10, the updated file would display "Region 10" instead of

"Region".

Save file—Select a location and file name.

Default file is the source file.

Toad for Data Analysts User Guide

Automate

Activity

Send Email

Description l

Suffix—Select a suffix to append to the file name. The suffix can be the date and time that the file was generated or the content of a variable that you define with the Set

Variable system activity. See "Use System Automation

Activities" (page 79) for more information.

Notes: l

You can only use one variable per field or file name (a suffix counts as one variable for a file name).

Use drag and drop or up/down arrows to change the order of multiple Find/Replace tasks in one activity.

Send an email to notify yourself or colleagues about the automation script status. The message automatically includes execution status for each activity that precedes the email activity.

You can also attach files generated by other activities and include a log file or error messages in the email.

Note: To use this activity, an SMTP service must be running.

Review the following for additional information: l

Enter recipient email address, subject line, and body text.

Email Server Settings—Specify SMTP server name and port.

Default settings are the Email Server Settings specified in

Settings properties.

Add Attachments—Click to add files created by this script or to browse for other files to add as attachments.

Use file for body—Select a file to use as the body of the email. This is useful if you need to send an email to a mobile device that does not support attachments. For example, you could send the results of an Execute Script activity in the body of the email.

If you use the Toad Report activity, you can select

HTML as the output format type. You can then select that

HTML file as the body for the email to produce a more professional looking email version of the report.

You can also customize the file with the Find and Replace activity.

Notes:

Toad for Data Analysts User Guide

Automate

Activity

FTP File

Run Automation

Script

Description l

For the To, CC, Subject, and Body fields: You can use a variable in this field by entering the number sign before and after the variable (#VariableName#).

You can only use one variable per field or file name (a suffix counts as one variable for a file name).

Upload or download a file using an FTP or SFTP connection.

Review the following for additional information: l

Select an FTP connection—Select an FTP connection or define a new connection.

Transfer ONLY if—Select this option to set conditions for

FTP transfer, and then select a condition from the list. If you select this option, the FTP activity only runs if the conditions you specify are met. For example, you would select remote file exists if a vendor uploads a file to the

FTP site containing a mailing list l

Local directory—If you selected local directory exists or

local file exists, select the local directory to check.

Local file—If you selected local file exists, enter the name of the local file.

Remote directory—If you selected remote directory exists or remote file exists, select the remote directory to check.

Remote file—If you selected remote file exists, enter the name of the remote file.

Define Operations—Review the following for additional information: o Use file mask—Select this option if you want to match files that use the file mask specified in the

File mask field at the bottom of this page.

o Move files—Select whether to move the files from the source location to the target location when uploading or downloading the files.

Run another automation script in your current automation script.

Review the following for additional information: l

Automation script—Select an automation script (.tas file).

Toad for Data Analysts User Guide

Automate

Activity

Compare Data

Description l

Return code—Enter a variable name, such as "RC," for the return code. Return code values are: o 0 = Successful execution o 999 = An error occurred during execution o 111 = An error occurred, but you selected continue on error.

You can use this variable with the If..Condition activity.

Open a Toad data compare project and export the contents as a

PDF, HTML, Excel, CSV, RTF, or MHT file.

Project file—Select a Toad data compare project file.

Report file—Select a file location, file name, and file type for the export file.

Suffix—Select a suffix to append to the file name. The suffix can be the date and time that the file was generated or the content of a variable that you define with the Set

Variable system activity. See "Use System Automation

Activities" (page 79) for more information.

Visualize Data Open a Toad data visualization project, refresh the chart, and export contents as a PDF, HTML, image, Excel, RTF, or MHT.

Data Visualization document—Select a Toad data visualization file (.tdv).

Output file—Select a file location, file name, and file type for the export file.

Suffix—Select a suffix to append to the file name. The suffix can be the date and time that the file was generated or the content of a variable that you define with the Set

Variable system activity. See "Use System Automation

Activities" (page 79) for more information.

Notes: l

Status—Select Enabled to include the activity in script execution. Select

Disabled to disable the activity, for example, when testing other activities. Or right-click the activity in the design window and select/deselect Enabled.

Stop on Error—Allows you to select, for each activity, whether to stop or continue execution if Toad encounters an error.

Select the Log tab to review a script's execution log.

Automation does not support positional parameters denoted by a question mark.

Toad for Data Analysts User Guide

Automate

Use System Automation Activities

You can use the following activities in automation scripts.

Activity

Run Program

Set Variable

Description

Run a program with optional command-line arguments. Review the following for additional information: l

Program—Select a .bat or .exe file.

Arguments—Enter command-line arguments. You can also enter a variable, such as #sleep# in this field.

Note: If you want to run a macro in Access, enter

databasename /x macroname in this field. For example, if you have a macro that beeps and runs in your Northwind database, you would enter Northwind 2007.accdb /x beep. l

Run Directory—Select the directory to change to when running the program.

Return Code Variable—Enter a name for the return code variable. You can use this variable with the If..Condition

activity.

Verb—Enter verbs used when running the program, such as

"Print".

Wait for program to exit—Select this option to pause if there is an error. Select duration of wait time in minutes.

Note: If the script opens a command-line window, you must manually close the window once the script completes.

Add one or more variables to the script. When you execute the script,

Toad replaces the variable with the defined value. With this feature, you can update information that may be different each time you run the script, such as the department name, revenue, fiscal quarter, or product name.

Review the following for additional information:

Value—Select this option to specify a value for the variable or to build a variable expression. Click to build an expression. Build your expression by selecting from the list of variables, operators, and functions. (Click a list name in the left pane to display the items in the right pane. Double-click an item to add it.) Click Test to test the expression. See the following link for more information on VBScript functions: http://www.w3schools.com/VBscript/vbscript_ref_

Toad for Data Analysts User Guide

Automate

Activity

If..Condition

While..

Description functions.asp

SQL—Select or enter a variable value, you can enter a SQL statement to use as the variable. If you enter a statement, the value from the first row and column returned in the query is used as the variable value.

This is useful if you need a variable with a date.

See "Use Variables in Automation" (page 83) for more information.

Note: You can only use one variable per field or file name (a suffix counts as one variable for a file name).

Execute activities conditionally based on the value of a variable. For each condition you can define unique activities, such as connecting to a database, generating files, and sending emails.

To use this activity you must define a variable in the automation script with the Set Variable activity.

This activity can have one or more conditions. To delete a condition, select it and press DELETE. To add a condition, right-click the

If..Condition.. activity and select Add Branch. If you have multiple conditions, they do not have to be mutually exclusive. Multiple branches can be true.

Build condition expression—To define a condition, enter the variable name and expression in the expression field. Build your expression by selecting from the list of variables, operators, and functions. (Click a list name in the left pane to display the items in the right pane. Double-click an item to add it.) Click Test to test the expression. See the following link for more information on VBScript functions: http://www.w3schools.com/VBscript/vbscript_ref_functions.asp

Execute activities while the variable condition is true. The activity ends when the condition becomes false, or when it completes the selected number of loops.

To use this activity you must define a variable in the automation script with the Set Variable activity.

This activity can have one or more conditions. To delete a condition, select it and press DELETE. To add a condition, right-click the

If..Condition.. activity and select Add Branch. If you have multiple conditions, they do not have to be mutually exclusive. Multiple branches can be true.

Review the following for additional information: l

Build condition expression—To define a condition, enter the variable name and expression in the field. Build your expression by selecting from the list of variables, operators, and functions. (Click a list name in the left pane to display the

Toad for Data Analysts User Guide

Automate

Activity

Loop dataset

Description items in the right pane. Double-click an item to add it.) Click

Test to test the expression. See the following link for more information on VBScript functions: http://www.w3schools.com/VBscript/vbscript_ref_functions.asp

Loop—Enter the number of times to loop the activity. If the condition never becomes false, Toad ends the activity after this number. The default is 10.

Execute activities on each row of a data table. The data table must be the result set from an Execute Script activity that occurs previously in

the automation script. See "Use Database Automation Activities" (page

69) for more information.

You can reference a column in the data table by setting the value of an initialized variable to 'DataTableName.ColumnName'. To initialize a variable, your script must have two different Set Variable activities.

The first Set Variable activity defines the variable value with a numeric value (such as 0 or 1.53), and the second defines it with the column variable name.

For example, assume you want to perform a set of activities on each of your company's products. You add the following activities and values: l

Execute Script—Execute a script that returns product IDs. You enter ProductIDTable in the Results variable field.

Set Variable—Add activity to give the variable an initial value.

You enter ID in the Name field and 0 in the Value field.

Loop dataset—Loop based on the dataset from the Execute

Script activity. You enter ProductIDTable in the Data Table field.

Set Variable—Add a second variable activity to reference the

Product_ID column in the data table. You enter ID in the Name field and ProductIDTable.Product_ID in the Value field. This redefines the values of the ID variable to the values in the

Product_ID column.

Toad for Data Analysts User Guide

Automate

Activity Description

Pause

See "Use Variables in Automation" (page 83) for more information on

a scenario that uses this activity.

Stops an activity for a set number of seconds before continuing. This is useful, for example, if you are using parallel activities and need to pause one branch while waiting for results or the complete execution of another branch.

Use this activity to group and organize two or more activities together.

Group

Activities

Parallel Run two or more activities in parallel. After adding a parallel activity to the design pane, you can right-click it to add additional branches for parallel activities.

Notes: l

Status—Select Enabled to include the activity in script execution. Select

Disabled to disable the activity, for example, when testing other activities. Or right-click the activity in the design window and select/deselect Enabled.

Stop on Error—Allows you to select, for each activity, whether to stop or continue execution if Toad encounters an error.

Select the Log tab to review a script's execution log.

Automation does not support positional parameters denoted by a question mark.

Toad for Data Analysts User Guide

Automate

Use Variables in Automation

Variables are a powerful feature that allow you to change data in your script or use a dataset collected from an activity in the automation script. For example, you can use variables to perform the following tasks: l

Send an email to a group of people where the list of recipients is automatically selected with a query.

Generate repetitive reports where only the product number, date, region, or other single element changes.

Customize file names by including a variable in the file name or automatically including the date that the automation script ran.

Find content in a file and replace it with the value of a variable.

Note: You must surround a variable name with the # sign (for example, #sleep#).

Generate Reports per Product

(Use the Loop Dataset Activity)

This scenario describes generating a report for each product, but you can use variables for a variety of reporting purposes: l

Report on warehouse inventory—query warehouse inventory with the inventory number as the variable, and then use the If..Condition.. activity to create different reports for items with no inventory, low inventory, and high inventory.

Report on revenue for each fiscal quarter—create a query with the fiscal quarter as the variable.

Report on revenue per sales person—create a query with the sales person's name or identification as the variable.

Scenario

Your Sales Manager wants a separate sales report for each of the company's products every week. He wants you to email the reports to him after they are generated.

To provide the reports to the Sales Manager, you need to create the product queries and the sales report. Then, you can use them in an automation script to run the queries, generate reports, and email the

Sales Manager every week.

To generate reports per product

1. Use the Query Builder to create a query that returns the product IDs.

2. Save the query and name it ProductIDQuery.tsm.

Toad for Data Analysts User Guide

Automate

3. Use the Query Builder to create a query that returns the sales information for products and enter the following search criteria in the specified columns:

Column

Product_ID

Order_Date

Search Criteria

Click in the Where Condition field. Select = and then Constant. Enter :ID in the field to define the variable.

Click in the Where Condition field. Select the Date

Range tab and then Last week.

4. Save the query and name it ProductSalesQuery.tsm.

5. Click Run Query and enter a value for the ID variable. The query results display.

6. Right-click the query results and select Send To | Data Report Designer.

7. Create the data report.

8. Save the report and name it ProductSalesPerWeek.tdr.

9. Close the report.

10. Click Automate to create a new automation script.

11. Click the Execute Script activity to add it to the Design pane and complete the following fields:

SQL file

Variable

Select ProductIDQuery.tsm.

Enter ProductIDTable.

12. Click the Set Variable activity and complete the following fields:

Name

Variable value

Enter ID.

Enter 0. Entering a number initializes the variable, which is required before you can redefine the value to another variable.

13. Click the Loop dataset activity and enter ProductIDTable in the Data Table field.

This loops activities on the content of the ProductIDQuery.tsm query.

14. Click the Set Variable activity to add a second variable and drag it into the Loop row.

15. Complete the following fields for the new Set Variable activity:

Name

Variable value

Enter ID.

Enter ProductIDTable.Product_ID. This uses the content of the Product_ID column in the

ProductIDTable table as the values for the variable.

Toad for Data Analysts User Guide

Automate

16. Click the Database Connection activity and drag it into the Loop row beneath the Set

Variable activity.

17. Click the Toad Report activity and drag it into the new Database Connection activity.

18. Complete the following fields in the Toad Report activity:

Report files

Export files

Select ProductSalesPerWeek.tdr.

Select the file location and enter SalesForProduct#ID# for the file name. When the automation script runs, it replaces #ID# with the variable value.

Note: You can only use one variable per field or file name (a suffix counts as one variable for a file name).

19. Click the Send Email activity and drag it beneath the Database Connection activity in the Loop row.

20. Enter the following information and then complete the remaining required fields for the Send Email activity:

Subject

Body

Add Attachments

Enter the Sales Manager's email address.

Enter Weekly sales report for product #ID#. When the automation script runs, it replaces #ID# with the variable value.

Enter the following: Attached is the weekly sales report for product #ID#. See the attached file.

Select the file created in the Toad Report activity and click Add.

21. Click Test to ensure that the script works. The following image displays the automation script in the Design pane:

Toad for Data Analysts User Guide

Automate

If ProductIDQuery.tsm returns five product IDs, Toad creates a report and sends an email for each one. If the first product ID is 101, the first email would have the following properties:

Toad for Data Analysts User Guide

Automate

Attachments

Subject

Body

SalesForProduct101.xls

Weekly sales report for product 101

Attached is the weekly sales report for product 101. See the attached file.

22. Save the automation script.

23. Schedule the automation script to run weekly. See "Execute Automation Scripts"

(page 90) for more information.

Find Unbatched Transactions

(Use the Row Count Field and If..Condition.. Activity)

Scenario

Your company has a web site that customers use to order products.

The orders are automatically batched, and each order is recorded as a row of data. When the batch is sent, it updates a column in the order row.

You need to run a daily report to find orders that were submitted but not batched. If there are any unbatched orders, you need to send an email to yourself with a list of the unbatched orders. If there are no unbatched orders, you need to send an email to yourself so you know that all orders were batched successfully.

To generate a daily report of unbatched orders

1. Save the query and name it UnbatchedOrders.tsm.

2. Click Automate to create a new automation script.

3. Click the Execute Script activity to add it to the Design pane and complete the following fields:

Row count variable

SQL file

Enter rc.

Select UnbatchedOrders.tsm.

4. Click the If..Condition.. activity.

5. Complete the following steps to define the first condition: a. Select the first condition and enter rc=0 in the Build condition

expression field.

b. Click the Send Email activity and drag it into the first condition.

c. Complete the required Send Email activity fields and enter No unbatched

orders in the Subject field.

Toad for Data Analysts User Guide

Automate

6. Complete the following steps to define the second condition: a. Select the second condition and enter rc>0 in the Build condition

expression field.

b. Click the Database Connection activity and drag it into the second condition.

c. Click the Select to File activity and drag it into the Database Connection activity in the second condition.

d. Complete the following Select to File activity fields:

SQL file

Export file

Select UnbatchedOrders.tsm.

Click the drop-down and complete the following: l

Excel file—Select this option, and then select the file location and enter

UnbatchedOrders_ for the file name.

Use column names for header row—Select this option and select a header row color.

Add Date/Time suffix to filename—Select this option and then select Date in the drop-down. This option appends the date the automation script ran to the file name.

e. Click the Send Email activity and drag it beneath the Select to File activity.

f. Enter the following information and then complete the remaining required fields for the Send Email activity:

Attachments

Subject

Body

Select the file created in the Select to File activity and click Add.

Enter #rc# unbatched order(s). When the automation script runs, it replaces #rc# with the variable value.

Enter the following: There were #rc# unbatched orders. See the attached file for more information.

7. Click Test to ensure that the script works. The following image displays the automation script in the Design pane:

Toad for Data Analysts User Guide

Automate

If there are no unbatched orders, Toad executes the first condition and sends an email with "No unbatched orders" in the subject . If there are unbatched orders, Toad executes the second condition. If there are two unbatched orders and you test on

December 10, 2009, the email would have the following properties:

Attachments

Subject

Body

UnbatchedOrders_2009-12-10.xls

2 unbatched orders

There were 2 unbatched orders. See the attached file for more information.

8. Save the automation script.

9. Schedule the automation script to run daily. See "Execute Automation Scripts" (page

90) for more information.

Toad for Data Analysts User Guide

Automate

Execute Automation Scripts

You can execute automation scripts on demand from the Automation window or the

Project Manager. You can also schedule scripts to run on a recurring basis at a specific time. For example, schedule a script that performs long-running tasks to run when database activity is light.

To schedule an automation script

1. With a script open in Automation, click Schedule in the Wizard bar. A Windows

Scheduler task is created for the script and a task properties window displays. See

Schedule Windows Tasks for more information.

2. Select scheduling options in the Schedule tab of the task properties window.

3. After the script executes, to view the script's execution log, select View | Output or select the Log tab in the script's open Automation window.

Note: When you view the Toad Event Log in the Output window, all log content moves to that window. As a result, the log is cleared.

To execute a script from the Automation window

1. Click Test in the Wizard bar. The script is compiled and executes immediately.

2. To view the script's execution log, select the Log tab.

3. If you want to schedule the script, first resolve any problems that caused activities to fail or disable failed activities. An activity can be disabled from its Activity

Info window.

Tip: To execute a script from the Project Manager, right-click the script and select Execute.