9.3. Template library

This chapter explains the PxM template library, the role they play and how they are managed. The following topics are covered:

9.3.1. What are templates?

Templates are an interface between PxM and a device. Templates provide PxM with the necessary access control and account provisioning information to communicate with the device.

Templates are:

  • XML or AutoIt files
  • Not part of the PxM installation and external to the PxM system so can be easily edited, changed and new ones created and uploaded.
  • Required per device but can be used by multiple compatible versions of the device.
  • Easily uploaded through the Web Management Interface individually or using a template library.

Provisioning a device means adding a device into PxM so it can be managed. To provision a device a template must be available.

Templates allow PxM to:

  • Interact with and manage the device using it’s native management interfaces.
  • Define single sign-on access to the device.
  • Delegate tasks to users.

Currently, PxM supports the following protocols:

  • SSH
  • TELNET
  • HTTP
  • HTTPS
  • RDP
  • vSphere
  • MSSQL Management Studio (using sql authentication)

9.3.1.1. Template structure

Templates can be broken down into three main areas:

  • Configuration
  • Action Tasks
  • Data Collection Tasks

9.3.1.1.1. Configuration

The device configuration information includes:

  • Connection critical configuration: required in order for PxM to connect and communicate with the device: hostname, IPaddress, port etc.
  • Device access: details about how the device can be accessed by PxM and through single sign-on for PxM Users.
  • Access tokens: Defines the access levels supported by the device and which can be used for user single sign-on.
  • User tools: Lists the access protocols that are supported by the device and can be used to access the device.

9.3.1.1.2. Action Tasks

Device tasks configured within a template include:

  • User add/delete/set password
  • Set device parameters

9.3.1.1.3. Data Collection Tasks

Data collection tasks with a template include:

  • User show
  • Device version
  • Read-only parameters

9.3.1.2. Working with templates

Before adding tasks to an existing template, we recommend a number of best practices be implemented when editing and updating PxM templates.

There are two ways that templates can be edited:

  • Using the Web Management Interface inline editor.
  • Or downloading the template and edit locally on your workstation.

9.3.1.2.1. Inline Editor

You can create a template file or edit a template or template library containing several files from the Template Editor page in the Web Management Interface.

To create a template file:

  1. Go to the Template library page.
  2. Click the New template button. The Template Editor opens in a new browser window.

To edit a template:

  1. Go to the Template library page.
  2. On the table, click a template. The Template detail page opens, displaying a summary of the template details.
  3. On the Template detail page, click Edit. The Template Editor opens in a new browser window.

The inline template editor has a built-in auto-completion feature displaying the available tags and parameters.


9.3.1.2.2. Download

You can download a template or template library (contains several files) from within the Web Management Interface in System > Template library.

To download a template/template library:

  1. On the Template library page, Left-click a template. Best practice is to select the latest template.
  2. Select Download template from the context menu.
  3. Save the downloaded template zip file to a preferred location.

9.3.1.2.3. Sub Template Files

The best way to add an additional task into an existing template is to create a sub template file. To use sub template files follow the followings rules:

  • Open the Inline Editor.
  • If one does not already exist, create a folder next to the main template file and name it the same as the main template file minus the .xml extension.
  • Create a file inside this folder that begins with an underscore and ends with the extension .xml.
  • Add a <devicetemplate> open tag at the beginning of the file.
  • Add a </devicetemplate> closure tag at the end of the file.

You can then add any of the following tags inside the sub template file to create your task:

  • <release_note>
  • <parameters>
  • <tasks>

If you are downloading and editing files locally, then create the file within the saved location of the downloaded template/template library. Once created, .zip or .tgz the template/template library and upload into PxM.

Best practice is to create separate sub template files for your own custom user tasks. This allows them to be easily moved into new PxM releases of core templates.

9.3.1.3. Template versioning

Templates are continually evolving and tasks can be edited and added at any time. It is therefore important to manage the version number of the templates so they can be easily tracked.

The templates attribute contains the following version control elements:

version_major:

  • The major version number of the template that is being released.
  • This number is for PxM use only and is incremented whenever we formally release new versions of templates.
  • Formally released templates have a major version of 1 and above.

version_minor:

  • The minor version should be incremented for edits and additions being made to the template.
  • This number is for customer use and is used to control changes to release templates.
  • All PxM released templates have a minor version of 0.

WebUI Template version XML

This information is displayed on the Template library page under the Version column in the Web Management Interface when a template is uploaded.

Templates that have not yet been formally released (but can be made available for experimental use) have a template version of below v1.0.

When making changes and developing templates within PxM use the version_minor increments with additional zero’s so you can distinguish between versions, but leave the version_major as this relates back to the release template the edited template is based on.

9.3.1.4. Template Release Notes

The <release_note> tag is used to track changes made to a template. This information is then made visible in the Web Management Interface when managing templates.

The <release_note> tag can be placed anywhere in the template, although generally PxM released templates have them placed at the start of the template.

Additional <release_note> tags can be added before any additional tasks to provide useful information and comments about the added task. Additional Release Notes comments will also be made visible in the Web Management Interface.

If you are using the inline template editor to add a release note tag, use the following steps:

  • Press the < less than key and you’ll get the auto correct list of options. Select release_note. The editor will auto fill the tag name.
  • Press spacebar and it will auto fill the timestamp= parameter (as this is the only parameter available in the release_note tag).
  • Press single quote ‘ key and the editor will automatically fill in the timestamp for you.
  • Close the tag with > greater than key. You will now be placed on the next line ready to enter your release note text. The editor also automatically adds the closure tag </release_note> on the next line too.

9.3.2. Managing templates

The Template library page lists all the templates that have been uploaded into PxM.

WebUI Template library table

The following information is presented on the Template library page:

Heading Description
MAP If checked Checked box, indicates that a MAP server is required for for full functionality.
Vendor The name of the vendor that manufacturers the device.
Template The display name given to the template.
Version The version number of the template.
Device Type Shows the device type defined in the template. Each device type has it’s own icon. Icons are shown on device detail pages.
Authentication Service

Indicates the type of authentication service used by this template.

See Active Directory or see Manage static vaults.

Supported device versions Details the device versions that are supported by the template.
Devices Shows the current number of devices currently using this template.
Expansion icon Shows the release notes inside the template.

By default, the templates are sorted by vendor, then template name, then version.

To configure the sort:

  1. Click on Template library in the left-hand menu.

  2. Within the Template library page, click on a column heading, and then select Configure sort… from the context menu.

    WebUI Template library table sort options

  3. Within the Sort window, you will see the default sort which has been configured. Amend the sort configuration and required.

    WebUI Sort window

  4. Click Apply when you have finished.

  5. The columns which the table is being sort by will contain a number in the heading to indicate what order the sort is being done.

    WebUI Multicolumn sort

9.3.2.1. Uploading the template

Before you can provision any devices you will need to upload the latest template library.

To download and upload the PxM Template:

  1. Click Template library from the left-hand menu.

    WebUI Template Library location

  2. Go to the PxM Latest Template bundle page.

    Note

    If you are uploading templates for the first time, click Click here on the Template library page to be directed to the PxM download page.

  3. In order to download the template library you have to be a registered user with a valid username/password. Login and download the latest Template library.

  4. Back on the Template library page, click Upload template(s).

  5. Within the Upload device template(s) window, click Choose file to select the Template library.

    WebUI Upload templates

  6. Click Upload. Templates will be uploaded.

    WebUI uploading Templates screen

  7. The Device template(s) upload result page appears listing the status of each template. Click Dismiss to see the templates listed within the Template library page.

Note

If your template is not available in the current template library then please contact us at info@osirium.com for advice and help with creating a template.

9.3.2.2. Uploading an individual template

New or updated templates can easily be uploaded into PxM.

To upload a new template:

  1. On the Template library page, click Upload template(s).

    WebUI Upload template window

  2. Browse and select the new template or template library to be uploaded.

  3. To overwrite any existing templates click on the checkbox. Only changes/additions to the tasks will take effect during the overwrite.

  4. Click Upload.

9.3.2.3. Show template

The Template detail page provides an overview of the tools and tasks that have been configured in a template. It also displays any release notes defined in the template.

To view a template, on the Template library page, Right-click a template and then click Show template. You will be navigated to the Template detail page.

WebUI Template detail screenshot

9.3.2.4. Edit a template

Templates can either be updated using the Inline Editor or Downloaded and updated using an external editor.

To edit a template using the inline editor:

  1. On the Template library page, left-click a template and then Show template.

  2. On the Template detail page, click Edit. The template will open in a new browser window within the inline editor.

    WebUI Template editor window

  3. Before you start making any changes to the template you need to update the template version. These updates are classed as Customer updates so the *version_minor* should be incremented and not the *version_major*. This is to prevent any clashes between PxM released template library in the future, as PxM increments the *version_major* when updating and releasing new or updated templates.

    WebUI Template editor version screenshot

  4. Now we have updated the version we can now start to add our task. The best way to add your own additional task into the template is to create a sub template file.

    Right-click the Folder icon folder and select New file from the context menu.

    WebUI New file context menu

  5. Give the task file a name which must start with an underscore and end with a file extension of .xml.

    WebUI New file name field

  6. Hit ENTER to save the file. The file should now be listed in the left-hand pane, within the template Folder icon folder.

  7. Click the new file and then click in the right-hand pane which should be blank.

  8. You can start building your task. Firstly you need to add the file definition tag which you will see at the start of every template file. This is important as it sets the character encoding to UTF-8.

    WebUI Empty task XML

  9. Then add a <devicetemplate> tag. The main template file has a <devicetemplates> tag and all sub-files which start with an underscore _ filename must contain a <devicetemplate> tag for them to be included in the overall template when loaded into PxM.

    Within the right-hand pane start by entering an opening tag with a < less than symbol. The auto-completion adds in devicetemplate. Close the tag with a > greater than symbol. The auto-completion will add in the closing tag.

    WebUI Template editor auto complete

  10. Now start to build your task. To help, see Tutorial: Adding user tasks guide.

  11. Before uploading the changes, ensure your syntax is correct. Any issues can be identified by the proceeding code turning red.

  12. The task is now complete. Click the Save iconUpload changes.

    WebUI Template update notification

Note

More information on creating templates can be found on in our Template Guide documenation.

9.3.2.5. Uploading a Web driver

New web drivers can now be uploaded through PxM templates. The new web driver can then be used to single sign-on to devices.

To upload a new web driver using the inline editor:

  1. On the Template library page, click the link on the template name. The Template detail page will open.

  2. On the Template detail page, click Edit. The template will open in a new browser window within the inline editor.

  3. Before you start making any changes to the template, you need to update the template version. These updates are classed as Customer updates so the *version_minor* should be incremented and not the *version_major*. This is to prevent any clashes between PxM released templates in the future, as PxM increments the *version_major* when updating and releasing new or updated templates.

    WebUI Template editor version screenshot

  4. Now create a new sub template file.

    Right-click the Folder icon folder and select New file from the context menu.

    WebUI New file context menu

  5. Give the file a name http_{vendor_name}.py or https_{vendor_name}.py

    WebUI Template editor window new file

  6. Hit ENTER to save the file. The file should now be listed in the left-hand pane, within the template Folder icon folder.

  7. The new file will be open, click in the right-hand pane which will be blank.

  8. Copy the contents of the web driver file provided by PxM into the new file created.

  9. Click the Save iconUpload changes. The new web driver file will be stored with the new version of the template. Devices provisioned with the updated template will use the new web driver file when single sign-on to the device through PxM.


9.3.2.6. Downloading a template

Templates can easily be downloaded from PxM so they can be amended and updated.

To download a template:

  1. On the Template library page, left-click a template, click Download template.
  2. Save the template to a preferred location.

9.3.2.7. Download bulk import template

Devices of the same type can be bulk uploaded by downloading and populating the bulk import device csv (comma separated value) template format for that device.

To bulk import devices:

  1. On the Template library page, right-click a template and click Download bulk import template.
  2. Save the bulk import template to a specified location. See Bulk importing.

9.3.2.8. Delete a template

Deleting a template permanently removes it from PxM.

A template which is currently in use by a provisioned device can’t be deleted. To delete the template you would have to first unprovision all devices using the template or migrate the devices to another template.

To delete a template:

  1. On the Template library page, Right-click a template and then click Delete template.
  2. The Question window opens. Click Yes.