Tag: <input> - Passing Input Parameters to a Task

Definition

The <input> tag is used define parameters that can be used with in a task.

This tag has the following attributes:

Parameters

• display_name (str) : This is the display string for the input in the PAM UI when the task runs. Display name is not used for inputs of type configuration.

• name (configuration, string, select, boolean, file) : This is the substitution name of the input when used in a command within the task. This defines the type of input.

• hide (true, false) : This defines if the input is to be hidden from view when the task is launched in the PAM UI. The default if not specified is false.

• device_parameter (str): This the is name of the parameter whose value is pulled into the task. This only applies to configuration and select input types.

Type Values

The type attribute can have the following values:

Fieldtype Value	Description
configuration	Defines that the input is a fixed value of a named parameter configured in the Admin Interface.
string	Defines that the input is a free text input box.
select	Defines that the input is a drop-down select box, linked to a named list of options defined in the Admin Interface.
boolean	Defines that the input is a checkbox.
file	Defines that the task will upload a file from the users workstation, and send it on to the device the task is running against (only applies to Windows devices at present). Note, the file is not stored on Osirium PAM.

Configuration String

A fixed configuration string is like defining a constant in a programming language. You use Osirium PAM template language to setup the constant and then use the constant in a task.

The value of the constant is set within the Admin Interface. This allows a template to use a constant in a task that can be applied to many instances of device without having to change the template each time, as the value of the constant is set in the Admin Interface on a per device basis.

Now, before we can run the task we need to set the value of the configuration parameter in the Admin Interface. You do this on the Tasks tab of the device you are setting the task up under:

Once defined, and given a value, the configuration parameter can then be used as a substitution in a task, for example:

<?xml version='1.0' encoding='utf-8'?>
<devicetemplate>

   <parameters>
      <parameter fieldname='tomcat_webapp' display_name='Tomcat Web Application Name' fieldtype='string' ondevice='no'/>
   </parameters>

   <tasks>
       <task name='restart_tomcat_webapp' display_name='Restart Tomcat Application' type='status'>
         <input name='tomcat_webapp' device_parameter='tomcat_webapp' type='configuration'/>
         <commands>
            <command>tomcat --app=%(tomcat_webapp)s --restart</command>
          </commands>
      </task>
   </tasks>

</devicetemplate>

String (Free Text Input Box)

A simple text input box can be added to a task with the following:

<?xml version='1.0' encoding='utf-8'?>
<devicetemplate>

   <tasks>
      <task name='restart_tomcat_webapp' display_name='Restart Tomcat Application' type='status'>
         <input name='tomcat_webapp' display_name='Web App Name' type='string'/>
         <commands>
            <command>tomcat --app=%(tomcat_webapp)s --restart</command>
         </commands>
      </task>
   </tasks>

</devicetemplate>

The user running the task will then get an input box to enter text into.

Select/Dropdown Input

Another form of input is to select from a dropdown list. This works similar to the configuration string, but rather than entering just one single text string into the Admin Interface, you set up a list of items. Like the configuration text, you need to define a parameter to use within the task.

<parameters>
   <parameter fieldname='tomcat_webapp_list' display_name='Tomcat Web Application List' fieldtype='list' ordering='1' ondevice='no'/>
</parameters>

!!! note:: It is usual with a dropdown list selection give the parameter fieldname a name ending in _list. This is so when the parameter is used later in the task, it is clearly a list parameter.

The list parameter is then pulled into the task like the configuration string,like this:

<?xml version='1.0' encoding='utf-8'?>
<devicetemplate>

<parameters>
   <parameter fieldname='tomcat_webapp_list' display_name='Tomcat Web Application List' fieldtype='list' ondevice='no'/>
</parameters>

<tasks>
   <task name='restart_tomcat_webapp' display_name='Restart Tomcat Application' type='status'>
      <input name='tomcat_webapp' display_name='Tomcat Application:' device_parameter='tomcat_webapp_list' type='select'/>
      <commands>
         <command>tomcat --app=%(tomcat_webapp)s --restart</command>
      </commands>
   </task>
</tasks>

</devicetemplate>

The Tomcat Web Application list parameter will now appear in the right-hand Task parameter panel, on the devices Tasks tab page.

Click on the to edit the list, rather than just being able to type directly into an input box, the Edit value window pops up.

You now have a few options to build/edit the list, you can:

• Add a single entry
• Generate a sequence of entries
• Import (or paste) CSV

Single Entry

To add a single entry you can right-click in the big white open space of the list window and select Add entry or you can click the menu item New and then select Add entry. This will open up a new line in the list editor and put it into edit mode:

Here you can now add a new entry. The fields breakdown to:

Attribute	Contents
Name	The name field is the name that is displayed as the option within the dropdown selection. This is what the user running the task sees and would select within the dropdown list. This can contain spaces and capitalisation.
Value	The value field is the actual value that gets passed to the task to be used in the substitution. The case of this value is preserved when passed to the task. This field can contain spaces but if it does ensure you consider this when you write the task and quote the substitution if necessary.

There are two fields so that a clear business display name can be used to make sure the user running the task selects the right option, but then the task can still be passed a more technical object name or configuration item within the context of the device the task is being run on.

For our Tomcat Web Application list example we might use names that relate to the application as it's known within the business. Then if some on the helpdesk is running the task it is clear to them which to choose, even if the name of the actual tomcat service running on the server is slightly different.

If you want the display name and the value to simply be the same you will need to set both fields to be the same.

Once the data has been entered click the Save changes button and the list will be saved. The list can be edited at any time by clicking the |Edit pencil icon| next to the Task parameter entry on the Tasks tab of the device. Any individual lines can be deleted from the list by clicking the |Delete icon| icon on the row you wish to delete.

The order in which the options are listed in the dropdown to the user is the same as the order they appear in the list editor. To change the order, drag and drop the entries and move them up or down to the new position you want them to appear in the list.

Generate Sequence

To create a few entries and have a sequence/pattern to the field values then you can use the built-in sequence generator.

Not relevant for this Tomcat restart application task example but what if you had a 24 port switch and you wanted to have a task that allowed a user to select a port with which to, for example, disable, then you would right-click in the main panel of the list editor back and select Sequence Generator.

The five fields in the sequence generator breakdown to:

Attribute	Contents
Start	The number that the sequence of numbers generated starts from and includes.
End	The number that the sequence ends at and includes.
Increment	The size of the steps that the sequence will be increase by each step.
Name Template	This is the text that will become the name field for each entry in the sequence. The string #{i} will get replaced by the value of the sequence at each step, as defined by the Start, End and Increment fields.
Value Template	This is the text that will become the value field for each entry in the sequence. The string #{i} will get replaced by the value of the sequence at each step, as defined by the Start, End and Increment fields.

Generated sequence example:

Column	Value
Start	1
End	5
Increment	1
Name Template	Port #{i}
Value Template	eth#{i}

Generates:

Generated Sequence: Name	Generated Sequence: Value
Port 1	eth1
Port 2	eth2
Port 3	eth3
Port 4	eth4
Port 5	eth5

Import (or paste) CSV

You can also create a list of options in advance in a spreadsheet or text editor. By selecting the New -> Import CSV option in the Edit value window, you can paste CSV text from the clipboard or import a CSV file.

The format is a very simple::

   name,value

Select Dropdown within the PAM UI

Now we've created our Tomcat Web Application List and assigned it to our template and set our list option choices, the task is ready to be run. When the user runs the task from the UI they will see the following:

The user can make a selection from the list of options in the task and make their selection based on the names. The values are hidden and are only passed to the task when it is run. For example, if the user were to pick the first option Payment Broker then the corresponding value would be broker_app_14.

So after the substitution, the final command which will be run against the device will be::

tomcat --app=broker_app_14 --restart

Note

For values with space in, you may need to place quotes around the string in the task.

Boolean (or Checkbox)

Another simple input to a task is a checkbox (or tickbox). This is setup like the free text input, i.e. you don't need a parameter defined, just an <input> tag inside the task. To add a checkbox, add an <input> tag inside the task like this:

<task ...>
   <input name='flush_arp_flag' display_name='Flush ARP Cache at end of task?' type='boolean'/>

The value of the field will be True if checked and False if not checked.

Now we use the Boolean value, in this example the name 'flush_arp_flag' to decide if we want to do something or not in the task commands. To do this we use a <conditions> tag.

Conditions are used inside the <command> tag to specify if that particular command is to be executed. The command will only be run if the condition test returns true. So here we have a checkbox to say we want to flush the arp cache (a task we looked at earlier) at the end of the main task, but only if the checkbox is ticked, i.e. set to True. To do this we would use:

<command format='textual_dataset'>arp -flush
   <conditions>
      <testEq name='flush_arp_flag' value='True'/>
   </conditions>
</command>

The <conditions> tag is a container to hold multiple tests. In order for the conditions to be met, ALL tests needs to return true.

In this example we only need one condition test to act on the checkbox input.

More info here: :ref:conditions-group-of-test.

The <testEq> tag is a test that is looking for one value to equal another.

A checkbox (Boolean) returns a value of True if checked, therefore we have a <testEq> tag inside the <conditions> tag that is checking to see if the value of flush_arp_flag is equal to True. If it is then the outer <command> tag that the <condition> tag is inside of will then be executed. If not matched, the command will skipped. When a checkbox is not checked we just want to do nothing so no other conditions or actions are required.

<?xml version='1.0' encoding='utf-8'?>
<devicetemplate>

   <tasks>
      <task name='restart_tomcat_webapp' type='status'>
         <input name='flush_arp_flag' display_name='Flush ARP Cache at end of task?' type='boolean'/>
         <commands>
            <command>tomcat --app=tomcat_webapp_1 --restart</command>
            <command>arp -flush
               <conditions>
                  <testEq name='flush_arp_flag' value='True'/>
               </conditions>
            </command>
         </commands>
      </task>
   </tasks>

</devicetemplates>

Note

The example task above has one fixed Tomcat Web Application name, just for simplicity.

When this task is then run through the PAM UI, the user experience looks like:

The user running the task then simply has to tick the checkbox for the condition commands in the task to be run. You can have multiple commands that use the same conditions value to test, for example, multiple commands that are run if just one checkbox is ticked, and you can have multiple checkboxes in a task, as long as they have different names.

File Upload (to a Microsoft Windows device)

Files can also be uploaded to a Windows device as part of a task. This is done by adding an input tag that has the type file, like this:

<task ...>
   <input name='upload_file' display_name='File to upload to server' type='file'/>

Then in the task itself you can tell Osirium PAM where to copy the file too:

<?xml version='1.0' encoding='utf-8'?>
<devicetemplate>
   <tasks>
      <task display_name='Upload File Test' name='upload_file_test' type='status'>
         <input display_name='File to upload' name='upload_filename' type='file'/>
         <commands>
            <command type='call' taskname='verify_and_create_share'/>
            <command command='smb.put' destination='//%(share_root)s%(device_name)s/%(upload_filename.filename)s' source='%(upload_filename)s' type='local_shell'>
               <success type='ci_match' value=''/>
               <success type='ci_in' value='putting'/>
               <failed type='default'/>
             </command>
         </commands>
      </task>
   </tasks>

</devicetemplates>

For more details on the file upload locations, see the Windows File Copy example in Tag: <command>

Parent Tags

• Tag: <task>

Child Tags

• None