Using generic commands

3.9 Using generic commands

A generic command is a way to perform any administrator-configured action on the Web server. Administrators set up generic commands to perform functions that are not part of Viewpoint's built-in commands. For example, canceling a job is one of Viewpoint's built-in commands but editing a job's variable is not. To edit a variable on a job, an administrator can create a generic command that defines the action. Generic commands are represented as additional controls in the various management pages within Viewpoint. When a user clicks on a generic action, a popup window opens allowing the user to input values and submit the form.

All generic commands are configured in an XML configuration file. For generic commands dealing with jobs, the XML is added to the jobs.xml file. Generic commands dealing with reservationss are configured in reservations.xml, etc.

Generic commands are configured in the same sections where other commands are configured. All configurable management pages allow for buttons at the top of a page to perform actions on a record without having to double-click on a record in the table. Also, most management pages allow for controls on the details section after double-clicking on a record.

To perform a function that is not part of Viewpoint’s built-in commands

Open the xml file corresponding to the page in which the generic command will exist. These are typically found in the Viewpoint home directory.

Locate the <controls> element and insert the <generic-command> child element.

Inside of <generic-command>,add the id attribute and give the command a unique name. Insert the label attribute to specify the text that users will see for the generic action performed.

Optional: Use the tooltip attribute to specify the text that is displayed on the control when the mouse hovers over it. Specify the image-url attribute to specify the path to the icon that will be used to display the control.

Inside of the <generic-command> element, set the <header> element to describe the header of the dialog box that is created.

Optional: Set the image attribute within <header> to the location of an image on the Web server.
Optional: Include field references, or keywords, that will be replaced with the value of the field of the current object being viewed. Allowable fields are the same as the allowable fields for the table and details sections.

<header image="image.png">Edit variable of $id!</header>

$id will be replaced with the ID of the object being modified. If this was the job management configuration and the user selected "job.15", then clicked the button created for the generic action Modify, the header would be "Edit variable of job.15".

Insert the <components> element within <generic-command> to describe the components that will be placed on the dialog box. (For more information, see Configuring the <components> element.)

The <components> element works as it does when creating forms; however, as a part of a generic command, it allows you to specify a component's source using the optional <source> element with the property attribute. For example:

<component id="textbox1"
    <description>Textbox auto=populated with OS</description>
    <source property="os" />
    <text-value />
</component>

Insert the <command> element within <generic-command> to describe the command that will run on the Web server.

Insert the <value> child element. This is the command that will run on the server. It can be any string value decider (for more information, see Adding a string decider). For each command, there are certain keywords that an be used to get the values of objects that are being changed. For more information, see the specific action you are modifying.
Optional: Insert the <rule> element within <command>. It must be evaluated to true in order to execute. If <rule> is not set, the command will always run when the specific action takes place. This value can be any boolean decider (for more information, see Setting a Boolean decider). Similar to the <value> element, there are certain keywords for each action that can be used to get the values of the objects being changed. For more information, see the specific action you are modifying.

(Optional) Set the <requirement> child element within <generic-command> to a boolean value decider that determines if a record is valid for the action.

Not all actions are applicable for all records. For example, the administrator may wish to only allow a node with a certain feature to have the ability to change IP address. In order to disable the generic action for some records, then re-enable the action for others, administrators should use the <requirement> element. This accepts any boolean value decider, and any keyword corresponding to the applicable columns for the record in question. For example, the value decider can use "account", "id", "memory", and "link" to job fields for generic commands dealing with job records. It also accepts the "username" variable, which displays the user's Moab username when the generic command is run.

<generic-command id="mycoolNodecmd" tooltip="This will allow you to edit the location of the reservation" label="Edit Location">
    <header image="editLocation.png">Edit location of $id!</header>
    <requirement comparison="equals">
        <first>
            <component id="variable[vm_os]" />
        </first>
        <second>linux</second>
    </requirement>
    <components>
        <component id="textbox1">
            <description>What is the desired location</description>
            <source property="variable[vm_os]" />
            <text-value />
        </component>
        <component id="textbox2">
            <description>Textbox autopopulated with ip addr</description>
            <source property="variable[ip-address]" />
            <text-value />
        </component>
    </components>
    <command>
        <value>/home/user/tools/change_location $id</value>
    </command>
</generic-command>

This example changes a reservation's location using a generic command. This command will only be enabled for reservations with a Linux operating system.