Step 2: Create your script to populate your custom column

Edit online

Create your script to perform calculations to populate your custom column. It is recommended to use one script per custom column for easier debugging. An example script catenate.sh is provided in $GUI_CONFDIR/application/.

Create your script

Edit online

Procedure

  1. Write your script.

    Ensure your script meets the script requirements.

  2. Test and debug your script.

    It is important your script work properly before you integrate it with IBM Spectrum LSF Application Center.

  3. Copy your script to a location that is accessible to the web server.

    Ensure that the directory is readable and executable by all users who will be viewing the Jobs page.

Script requirements

Edit online

Script name

Edit online

The script name must be named according to UNIX file and path naming conventions.

Script type

Edit online

The script can be any executable as long as it meets the required input and output.

Directory in which script is located

Edit online

The directory in which the script is located can be any directory accessible by the web server.

All users who will be viewing the Workload page require read and execute permission to the directory in which the script is located. The script runs as the user who is logged on and viewing the Workload page.

Input

Edit online

Required environment variables

JOB_IDS and JOB_TYPES are environment variables that must be passed to the command script. These must be called within your script.

For example:

ids=`echo $JOB_IDS | tr ';' ' '`
types=`echo $JOB_TYPES | tr ';' ' '`
JOB_IDS
The ID corresponds to jobs, job flows, and job array elements. For job groups, only the IDs of jobs within the group are returned. For job arrays, the ID of array elements is returned. IDs are separated with a semi-colon (;).

Example of IDs returned for jobs and job flows. 

JOB_IDS=”102;103;105”

Example of IDs returned for job arrays (job ID_index). For example, for job array 303, and elements 6, 7, 8:

JOB_IDS=”303_6;303_7;303_8”
JOB_TYPES
Items returned in JOB_TYPES indicate whether the ID returned is a job, a job belonging to a job group, job array element, or a flow. Types returned are JOB, ARRAY, GROUP, FLOW.

The types correspond to the JOB_IDS returned and are returned in the same order and number as the corresponding ID.

For example, ID 102 is a job, 103 is a job within a job group, 105 is a flow, and the other IDs are for job array elements. The environment variables are set by IBM Spectrum LSF Application Center in this way:

JOB_IDS="102;103;105;303_6;303_7;303_8"
JOB_TYPES="JOB;GROUP;FLOW;ARRAY;ARRAY;ARRAY"

Input parameters

Input parameters passed to the command script are predefined keywords recognized by Platform Application Center and are defined in the $GUI_CONFDIR/customJobColumn.xml file with the element <InputParams>. Keywords must be used within the script in capital letters.

Output

Edit online

The output of the command must be to stdout. You must handle every single job ID that is returned by IBM Spectrum LSF Application Center, even if you do not have values to attach to those jobs. Return a dash (-) for job IDs to which no values apply.

Output must be in the following XML format. You can validate against the XSD file $GUI_CONFDIR/customJobColumnOutput.xsd.

<JOB_COLUMNS>    
<JOB_COLUMN JOB_ID="job_ID" JOB_TYPE="job_type">
your_value
</JOB_COLUMN>
</JOB_COLUMNS>

There must be one XML <job> element returned for each job. For example:

<JOB_COLUMN JOB_ID="45657" JOB_TYPE="FLOW">  
99</p><p>
</JOB_COLUMN>

Example output for several jobs:

<JOB_COLUMNS>    
  <JOB_COLUMN JOB_ID="45657" JOB_TYPE="FLOW">
  99
  </JOB_COLUMN>
  <JOB_COLUMN JOB_ID="90123_6" JOB_TYPE="ARRAY">
  119
  </JOB_COLUMN>
</JOB_COLUMNS>

Exit codes

Edit online

On success, the command script must return an exit code of 0.

On failure, the command script must return any value other than 0. Error messages are displayed at the top of the Workload page. If additional information is needed, look for the customJobColumn.xml keyword in $GUI_CONFDIR/../logs/host_name/messages.log.