Designing a Dynamic Request for Job Activation

In this example, we will design a PromptSet and assign it to a Windows Job. This Job executes a Windows command on the computers on which specific Agents are installed. Through the PromptSet, a dynamic dialog is displayed when the Job is executed. The dialog prompts the user to provide the following information:

• Select the Agents on which the Job should run
• Select the Queue that should process the Job
• Enter the OS command that should be processed

The Agents and the Queue that are available for selection are retrieved dynamically from the Automation Engine database at runtime. VARA objects are used for this purpose.

After filling up and submitting the PromptSet, the Job is activated on the selected Agents.

What Will You Learn?

• How to design a PromptSet object
• How to create and use internal SQLI VARA objects
• How to create a simple Windows Job
• How to create a simple Script that calls the PromptSet and starts the Job

Requirements

• You use an SQL database

• The settings for SQLI VARA Objects in UC_SYSTEM SETTINGS are as follows:

  SQLVAR_INTERNAL= Y

  For more information, see SQL Variables Parameters

• The security level in VAR_SECURITY_LEVEL is set to 1 (or 2 or 3) to be able to create and use internal SQL

Overview

1. Create the VARA Objects
2. Create the PromptSet
3. Create the Script Object
4. Create the Windows Job
5. Start the Script Object

 

Create the VARA Objects

We need two VARA objects, one to retrieve the available Agents and another one for the available Queues. Since we want to retrieve values from the database at runtime, we will create SQLI VARA objects. This way, the PromptSet always contains updated values. If, for example, a new Agent is added, it is automatically available for selection next time that the PromptSet is called.

Create VARA.SQLI.AGENT

1. In SQL Server Statement enter the following statement:

   select OH_Name from oh where oh_otype='HOST' and OH_HostAttrTypeDst='WINDOWS' and OH_Name like '%WIN%' order by OH_Name

2. Save and click Preview to verify that the statement is correct. If it is correct, a table is displayed with the list of the available Agents.

Create VARA.SQLI.QUEUE

1. In SQL Server Statement enter the following statement:

   select OH_Name from oh where oh_otype='QUEUE' and OH_Client='&$CLIENT#' and OH_RefIdnr = '0' order by OH_Name

2. Save and click Preview to verify that the statement is correct. If it is correct, a table is displayed with the list of the available Queues.

Note: &$CLIENT# retrieves the Client number at runtime.

Create the PromptSet

The PromptSet object is called PRPT.AGENT. It will generate a dialog that contains the following sections:

• A text field that will provide the name of the Job
• A section with checkboxes to let users select the Agents on which the Job should run
• A combo box to let users select the Queue that should process the Job
• A text field where users can enter the OS command

To design the PromptSet, in the Prompt Designer you drag elements from the right pane to drop them into the design area at the center of the screen.

Create the Job name text field

Insert a Text Field element and configure it as follows:

1. In Data Reference select UC_DATATYPE_STRING.
2. In Label, enter Job.
3. In Variable Name, enter &JOB#.
4. Select Mandatory.
5. In Job enter the following default value: JOBS.WIN.PROMPT

Create the Agent selection section

Insert a Checkbox section and configure it as follows:

1. In Data Reference select VARA.SQLI.AGENT.
2. In Label, enter Select Agent.
3. In Variable Name, enter &Agent#.
4. Select Mandatory.
5. Select Multi-select.

Create the Queue selection section

Insert a Combo box section and configure it as follows:

1. In Data Reference select VARA.SQLI.QUEUE.
2. In Label, enter Select Queue.

3. In Variable Name, enter &Queue#. This retrieves the Queue from the Script object.

Create the OS command section

Insert a Text Field element and configure it as follows:

1. In Data Reference select UC_DATATYPE_STRING.
2. In Label, enter JCL.
3. In Variable Name, enter &JCL#.
4. Select Mandatory.
5. In Enter JCL enter the following default value: dir C:\

Click the Preview button to verify that the resulting dialog is as expected.

Create the Script Object

The Script object calls the PromptSet object, reads its values and activates the Job. Call it SCRI.START.JOBS.

1. On the Variables & Prompts page, assign it the PromptSet that you have just created.

   Note: If necessary, you can change the default values here. These changes apply only to this instance of he PromptSet and not to the original object.

2. Go to the Process page and enter the following lines:

    

   :SET &LEN# = LENGTH(&AGENT[ ])

   :WHILE &LEN# > 0

   : PSET &HOST# = &AGENT[&LEN#]

   : IF SYS_HOST_ALIVE(&HOST#) = "Y"

   : SET &RET# = ACTIVATE_UC_OBJECT(&JOB#,,,,,PASS_VALUES,&QUEUE#, "&JOB#_&HOST#")

   : P "Start Job &JOB# on agent &HOST# with RunID &RET#"

   : ELSE

   : P "Agent &HOST# is not active."

   : ENDIF

   : SET &LEN# = &LEN# - 1

   :ENDWHILE

   This script does the following:

   • It retrieves the number of Agents that have been selected in the PromptSet
   • It reads the Agent names from the script array
   • If the Agent is active, it starts the Job
   • The Job starts with an alias that is made up of the Job name followed by an underscore and the Agent name. For example: JOBS.WIN.PROMPT_WIN01. This helps you distinguish it in the Executions list.

Create the Windows Job

Create a Windows Job that executes the command you want to process on the computer of the Agents that you select in the PromptSet. Call it JOBS.WIN.PROMPT.

1. On the Attributes page, select the Login object that contains the credentials that the Job needs to run on the Windows Agent.

2. Go to the Pre Process page and enter the following line:

    

   : PUT_ATT HOST = &HOST#

    

   As a result, the Agent that has been passed on by the Script object through the variable is set at runtime.

3. Go to the Process page and enter the following lines:

   :DATA &jcl#

   :DATA "@set retcode=%errorlevel%"

   :DATA "@if NOT %ERRORLEVEL% == 0 goto :retcode"

Start the Script Object

Start the Script to call the input dialog that results from the PromptSet. Right-click on SCRI.START.JOBS and select Execution Options > Execute.

Result

The Requests view opens up. It displays the fields that you have created in the PromptSet object (PRPT.AGENT) that you have assigned to the Script.

1. Alternatively, in Job change the name of the Job. This way, the Job is executed under an alias name that helps you easily find it in the Executions list.
2. In Select Agent, activate the checkboxes that correspond to the Agents on which you want the Job to run.
3. In Select Queue choose the Queue that should process the Job.
4. The command that you have defined as default in the PromptSet is displayed in Enter JCL. Leave it as it is.
5. Click Submit. The command is executed on the computers where the selected Agents are installed.

Tip: Check the Executions list and open the report of the Script object to see the details of the execution.

Useful Links

• User-Defined VARA Objects
• SEC_SQLI VARA Objects
• PromptSets (PRPT)
• Scripts (SCRI)
• Windows Jobs
• Execution Options
• Execution Data
• Reports
• Requests

Script Reference:

• :SET
• :WHILE... :ENDWHILE
• :PSET
• :IF... :ELSE... :ENDIF
• :PRINT
• :PUT_ATT
• :DATA