12.11. Creating a Custom Job Template

Engineering Knowledge Manager

User's Guide | Chapter 12: Managing Jobs |

12.10. Cluster Monitoring |  | 12.12. Editing a Job Template
Prev |  | Next

## 12.11. Creating a Custom Job Template

When you create a job template, it will appear as an option in the job wizard when setting up jobs, as well as in the Applications panel.

Job templates include the following settings:

- Job type (Batch or Interactive)

- Applications to be launched

- Command line arguments

- Job submission options

- Queues

- Environment variables (for batch jobs)

- Transcript file name (for batch jobs)

- Remote visualization options (for interactive jobs)

- Associated file types

- Variables

- Macro and resource files for a custom interface

- Job status view

Note: Interactive job templates will only appear in EKM if EnginFrame is installed and correctly configured to work with EKM. See Installing and Configuring EnginFrame in the Installation Guide for details.

To create a job template:

1. Go to Home/My Applications or Administration/Shared Applications, then select (New) > Job Template. The Create Job Template dialog box appears:

2. Specify a name for the job template and select the location where you would like to save it. My Applications is a personal page in the Home section which can only be accessed by you. Shared Applications is located in the Administration section and contains applications that will be accessible to all users.

   Note:

   - You cannot use the name of a job template that already exists in the target location.

   - The Shared Applications option is only available if you have `Modify` permission on the Administration/Shared Applications page.

3. Click OK. The template is saved in the target location, and the Edit Job Template dialog box appears:

   Figure 12.18: Edit Job Template Dialog - General Tab

   The Edit Job Template dialog box has four tabs: General, Variables, Script and UI. The settings on the General tab correspond to settings in the Start Job dialog box when running a batch or interactive job. The variables that you define on the Variables tab can be used to define settings on the General tab, such as Command line arguments and Environment variables, so you may want to define your variables first. On the Script tab you can define a script macro and optionally specify a macro for validating variable values. On the UI tab you can specify the name of a macro that defines a custom dialog box for running the job. Note that the UI tab is only available when Batch is the selected job type.

4. Referring to the sections that follow, specify the job template settings and define any variables that you want to use when specifying settings.

5. Click OK to save your changes.

### Defining General Job Submission Settings

On the General tab of the Edit Job Template dialog box, specify the job submission settings that you want to capture in the template. The settings that are available depend on the Job Type that you choose (Batch or Interactive). For both batch and interactive jobs you can define Application keys, Queues, Command line arguments, and Job submission options. For batch jobs you can also specify Environment variables and a Transcript file name. For interactive jobs you can specify Remote visualization options.

To specify Application keys, Queues, Command line arguments, Environment variables, or Remote visualization options, click to add an entry to the list, and then define the entry. To delete an entry that you have added to a list, click the trash can icon in the last column. If you need help with any of the settings, click the help icon next to the setting that you need help with.

Below is a description of the job submission settings on the General tab.

- Job type. Choose either Batch or Interactive. A Batch job contains a sequence of commands to be executed by the operating system, and is submitted for execution as a single unit. Once a batch job has been submitted it can run to completion without any intervention from you. The commands are submitted from the EKM server to a cluster via Remote Solve Manager (RSM). A queuing system on the cluster submit host queues the job, allocates processors, and starts and manages the job. Batch jobs are ideal when you want to run longer processes, or when you are not available to provide input. An Interactive job, on the other hand, is processed in real time. You are prompted to input data and interact with the system as the job executes. A remote desktop application is used during interactive sessions to connect your computer to the execution node.

- Application keys. Create a list of external applications that are to be available for selection when the job is executed. Enable the Default radio button next to the application that you want to be selected by default when the job is executed. This is required even if there is only one application listed.

- Queues. Optionally create a list of job submission queues that are to be available when the job is executed. Add an entry to the list, and then select the desired queue in the drop box. The available queues in the drop list will depend on whether the job type is batch or interactive. If there are two or more queues in the list, enable the Default radio button next to the queue that you want to be selected by default when the job is executed. If no queues are specified then all queues that contain the application will be available for selection.

  Note: Ensure that you make available only those queues that support the type of job being submitted.

- Command line arguments. Define command line arguments for the applications that will be used during job execution. Add an entry to the list and then define the argument using text and/or variables. To add a variable to the definition, press the spacebar to display a list of available variables, and then select the variable to add. Variables are displayed using the {$var} notation. Variables are defined on the Variables tab of the Edit Job Template dialog box. For details see Defining Variables for Job Template Settings.

  Note: The `cores` variable is a built-in variable that can be used in batch job templates to automatically specify the number of processing cores to be reserved if the number is greater than 1. This variable should not be used in interactive job templates.

- Environment variables. (batch jobs only) Define environment variables that will communicate data to processes. Add an entry to the list, and then define the parameter using text and/or variables.

  Note: You can define environment variables for an interactive job by editing the template’s `xml` file.

- Remote visualization options. (interactive jobs only) Define options to map property names and values for the remote visualization tool being used (for example VNC, DCV or HP RGS). These options can be used, for example, to specify screen resolution. For VNC and DCV you can specify resolution using the `vnc_geometry` property, as shown in the following figure:

  The value can be specified in the following format:

  "<width>x<height>[:<full-screen>[:<use-all-monitors>]]"

  The <width> and <height> parameters are mandatory, whereas the <full-screen> and <use-all-monitors> flags are optional. For example:

  - "5120x1600:true:true" = Fullscreen on two 30” monitors (5120x1600)

  - "3840x1200:true:true" = Fullscreen on two 24” monitors (3840x1200)

  - "2560x1600:true:false" = Fullscreen on single 30” monitor (2560x1600)

  - "1920x1200:true:false" = Fullscreen on single 24” monitor (1920x1200)

  - "1024x768:false:false" = Window-mode on single XGA monitor (1024x768)

- Job submission options. Define settings for the batch submission system. Leave this blank if you do not have any options to specify.

- Transcript file. (batch jobs only) Enter a name for the transcript file that is written during job execution. You can use variables if you wish. The transcript is displayed on the Transcript tab when viewing a job on the Job Monitor page, and provides feedback about the job execution. If a name is not specified, the standard output and error streams of the batch job are taken as transcripts.

- Close session when application exits. (interactive jobs only) Specify whether or not you want the interactive session to close as soon as the launched application exits. By default, this setting is enabled. If you are running applications from a script, you should disable this setting so that the script can continue to run after the application exits. Note that this setting only works for interactive jobs started in Linux.

### Associating File Types with a Job Template

Associating a file type with a job template ensures that the template is available when starting jobs from files of that type. For example, if you specify `CfxDefinition,CfxResult` as associated types, the template will be available on the Execute menu when you start a job from a CFX .def or .res file. For details on this job submission method, see Starting a Batch Job from Repository Files.

1. In the Edit Job Template dialog box, select the General tab.

2. In the Associated types edit box, enter the type names in a comma-delimited format. For a list of file type names, refer to Appendix B: Built-in Types - Reference.

Note:

- The LS-DYNA .k file type is not a built-in type, and therefore cannot be associated with the LS-DYNA job template by default. To create such an association, an EKM administrator must first define a custom type for the .k file type, and set the type attribute `allowJobExecution` to `true`. For more information see Defining a New Custom Type.

- The availability of the job template on the Execute menu for an associated file type will take effect at the next sign-in to EKM. This also applies to job templates that have been newly uploaded to EKM.

### Defining Variables for Job Template Settings

Variables hold inputs specified by users or processes. You can use variables when defining command line arguments, environment variables, job submission options, the transcript file, and remote visualization options on the General tab of the Edit Job Template dialog box. The variable list is displayed when you press the spacebar during the specification of these settings.

On the Variables tab of the Edit Job Template dialog box, define the variables to be used when specifying job template settings. Click to add a variable to the list in the left pane, and then define the variable in the right pane.

Figure 12.19: Edit Job Template Dialog - Variables Tab

Specify the settings described below.

- Name. Initially variables are assigned a default name with the format `var` `#`, where `#` is a number that increments each time a variable is added. You can edit the default name to suit your needs. Names cannot begin with a number, and they cannot contain spaces or any of the following characters:

  `/ \ : [ ] % * ' " |`

  If you have edited the name, click to update the name in the variable list.

- Label. Enter a label for displaying the variable in the Start Job dialog box.

- Type. Choose one of the following variables types: `String`, `Long`, `Double`, `File`, `Boolean` and `Expression`. Different options are displayed depending on the type you choose. See Defining Options for Different Variable Types below.

- Default. The default value that you want the variable to have.

You can control the order in which variables appear in the list using the and buttons below the list pane. The order specified here will also be reflected in the variable drop list when defining job template settings on the General tab.

To remove a variable from the list, select it in the list and then click below the list pane.

Note: The `cores` variable is a built-in variable that can be used in a command line argument to automatically specify the number of processing cores to be reserved if the number is greater than 1.

### Defining Options for Different Variable Types

For `String`, `Long` and `Double` types you can create a list of choices for the variable value if you wish. Click to add an entry to the Options list, and then specify a Name and Value for the option. The Name attribute is what is displayed in the interface, while the Value attribute is the value added to command line arguments, environment variables, and other template settings. To delete an entry that you have added to a list, click the trash can icon in the last column.

Figure 12.20: Defining Options for a String Variable

`String` variables can contain any arbitrary text as a value.

`Long` variables can only contain integers such as `0`,`5`, `-5` as values.

`Double` variables can contain any valid real number such as `0.0`, `123.456`. You can also use scientific notation such as `1.235E6` or `1.235E-6`.

For `File` variables, all files in the parent folder of the working directory will be available as options unless a pattern is supplied in the Pattern edit box. If specifying multiple patterns, you must use a regular expression. This means that the patterns must be separated by a vertical bar “|”. Commas, spaces or other characters are not acceptable separators. For example, to list all files in the working directory that have an `.inp` or `.dat` extension, you would enter `*.inp|*.dat` in the Pattern edit box. To create a vertical bar “|”, press Shift + \.

Figure 12.21: Defining a Pattern for a File Variable

`Boolean` variables can only be True or False. You can define values for each state if you wish. In this case, if the Boolean variable is true, the value specified in the True value edit box is used as the value. Otherwise, the False value is used.

Figure 12.22: Defining True/False Values for Boolean Variables

`Expression` variables can be used to specify variables whose value depends on other variables. Expressions can access the value of non-expression variables. These variables will not be shown in the Start Job dialog box as their value is automatically calculated based on other variables. Expression variables can be used anywhere in the job template where other variables are specified, such command line arguments and environment variables.

The value of an `Expression` variable must be expressed in the language (Python or BeanShell) that is selected on the Script tab.

Figure 12.23: Defining an Expression Variable

Note: Variable names can only contain letters, numbers or underscores, and must start with a letter.

### Defining Scripts and Macros in a Job Template

On the Script tab of the Edit Job Template dialog box you can:

- Select a scripting language (Python or BeanShell).

- Define a script containing macros that can access the value of non-expression variables defined on the Variables tab.

- Specify a macro for validating variable values.

- Define a script containing macros that will display a custom interface when a batch job is executed.

The sample script in the figure below contains two macros that can access the `elems` and `defFile` variables defined on the Variables tab.

Figure 12.24: Edit Job Template Dialog - Script Tab

Note: If a macro accesses a Long or Double variable, the variable’s value will be typed as ‘String’. It may need to be converted to an appropriate type before being processed.

If a validation macro is specified in the template, it will be executed when a user clicks Finish in the Start Job dialog box. A validation macro can be used to validate the values specified by a user, and produce error warnings if needed. Warnings will appear in red in the Start Job dialog box, as shown in the figure below.

Figure 12.25: Validation Error in Start Job Dialog Box

### Defining a Script for a Custom Interface

If you are defining a script for a custom interface, you must define the following on the Script tab:

1. An initial macro that specifies the following:

   - The name of the XHTML file that defines the content of the custom interface

   - The name of the action macro that is used when the Start Job dialog box is launched

   - The variables used to store inputs specified by the user in the custom interface

2. An action macro that is called when the user clicks Finish in the Start Job dialog box. This macro processes user inputs and executes commands.

3. An ajax macro (if required) for communicating with the server in the background. An ajax macro is used to update a portion of the interface when a user interacts with it. For example, if the user enables a check-box or radio button, different content may be displayed as a result of his or her choice.

Refer to Example: Creating a Custom Interface for Fluent Batch Jobs in the Administration Guide for a detailed example of the code used and steps taken to create a job execution interface. In order for the custom interface to be used when the job template is executed, the initial macro and resource archive for the custom interface must be specified on the UI tab. See Using a Custom Interface for Job Execution for details.

The built-in job templates, Fluent Batch, CFX Batch, MAPDL Batch, Electronics Batch and Workbench Batch are excellent examples of the types of comprehensive dialog boxes that can be developed for job execution.

### Using a Custom Interface for Job Execution

In a job template you can specify that you want a custom interface to be displayed when a job is launched. This requires the creation of a Python or BeanShell script, which you can define on the Script tab (see Defining Scripts and Macros in a Job Template). It also assumed that the custom interface has been appropriately defined in an .xhtml file, and that all resource files are contained in a `.zip`, `.tar`, `.tar.gz` or `.tgz` file on your local computer.

To specify the use of a custom interface in a job template:

1. On the UI tab of the Edit Job Template dialog box, enter the name of the initial macro that creates the custom interface. (The macro name is specified in the script defined on the Script tab. See Defining a Script for a Custom Interface for details.)

   Figure 12.26: Specifying a Custom Dialog Box in a Job Template

2. Under Resource archive click Browse to select the archive (`.zip`, `.tar`, `.tar.gz` or `.tgz` file) on your local computer that contains the resource files for the custom interface.

To execute a job using a custom interface, you must do one of the following:

- Execute the job template in which the custom interface is specified. See Starting Jobs in EKM for details.

- Launch the Batch job application and select the appropriate job template at the top of the job submission wizard. See Starting a Batch Job Using the Job Launch Application for details. The dialog box will update to show the components defined in the custom interface.

In the example below, the default contents of the Start Job dialog box have been replaced with custom components, options and images.

Figure 12.27: Example of a Custom Dialog Box for Job Execution

Refer to Example: Creating a Custom Interface for Fluent Batch Jobs in the Administration Guide for a detailed example of the code used and steps taken to create a job execution interface.

### Specifying a Job Status View Type for the Job Monitor

When defining a job template, you can control how job status information will be displayed in the Job Monitor when the job is executing.

1. In the Edit Job Template dialog box, select the UI tab.

2. From the Job status view drop box, select the type of view that you would like displayed in the Job Monitor when this template is used to run a job. Selecting Fluent, MAPDL or Electronics will show advanced monitoring and control options when the specified solver is started in server (aas) mode.

   Note: To launch the solver in server (aas) mode, you must specify appropriate command line parameters.

Contains proprietary and confidential information of ANSYS, Inc. and its subsidiaries and affiliates.

Prev | Up / Contents | Next

Release 18.2 - © ANSYS, Inc. All rights reserved.