The Manifest

<< Click to Display Table of Contents >>

RayQC > 7.3 u2 > User Guide > Plug-ins > External Plug-ins > Structure of a Plug-in 

The Manifest

From a checklist creator's point of view, a plug-in is determined by its name, available functions and their parameters. Especially for internal plug-ins, this set of information is all a checklist author may access. (Well, actually he has additional information available from this document, but who provides a decent user guide for the set of custom plug-ins established within an enterprise QA department?)

 

The manifest file of a plug-in has to define this set of plug-in properties in a human as well as system readable format. This is why Raynet decided to use XML as manifest file markup language, since it is highly structured and maintains intuitive accessibility for checklist authors.

 

There are several angles from which manifest files may be explored: from the naked XML structure with its tags and attributes, or from the logical and functional requirements regarding information needed for the interface definition. The following section describes the informative scope, whilst the Appendix section provides access from the other side.

 

Plug-in Interface Definition Requirements

Each manifest file represents a specific group of functions and arguments that are somehow related to each other. From this point of view a plug-in is nothing more than a container for standardized program logic.

 

Each plug-in needs a certain set of information to be clearly identifiable. These information includes Name, Version, Filename, and PowerShell version which supports the related PowerShell script. These first set of information is needed to be plainly visible from the manifest.

 

  <Name>PowerShellSample</Name>

  <Description>This a pretty straight external plug-in with two sample function for demonstration.</Description>

  <Version>1.2.3.4</Version>

  <Filename>PowerShellSample.ps1</Filename>

  <PowerShellVersion>3</PowerShellVersion>

 

For this sample manifest file the plug-in name is PowerShellSample, it has 1.2.3.4 as its version. Furthermore this manifest file links to the PowerShellSample.ps1 script which is supported by PowerShell version 3.0 and higher.

 

Alright, the foundation is there - RayQC can recognize the plug-in. But how to communicate what the plug-in is capable of? Well, what is usually required from scripted logic is a classical sequence of using some pieces of information, processing them somehow, and giving feedback about the result of the processing. So, each of these sequences is a capsuled and clearly defined functional group. We interpret plug-ins as containers for functionality, so a plug-in with only one function may exist, but to be true is a poor container. Let's be generous and assume that there has to be at least one function, but authors are free to add as many as pleases them.

 

Combining these properties of plug-in functions and its parameters, the translation to XML is quite obvious: Each function description is embraced by a parent tag, whilst these have to be parts of the plug-in themselves.

 

<Name />

  <Description />

  <Version />

  <Filename />

  <PowerShellVersion />

  <Functions>

    <FunctionParameters>

      <FunctionName />

      <Description />

      <Parameters />

    </FunctionParameters>

  </Functions>

</plug-inData>

 

There seem to be some important facts missing in the sample XML given above. The functions and their parameters are not named, so how could RayQC know which sub-tree to enter when a checklist author selects a plug-in function from the Checklist Editor interface? And up to now there is no reference to the actual source code with the function logic (the part that actually uses the input to somehow generate output).

 

Well, each function and its parameter needs an identifier (a unique one per function, that is easy to find when a user reads the manifest - it seems to be a good idea to set it as an attribute for the function tag).

 

  <Name>PowerShellSample</Name>

  <Description>This a pretty straight external plug-in with two sample function for demonstration.</Description>

  <Version>1.2.3.4</Version>

  <Filename>PowerShellSample.ps1</Filename>

  <PowerShellVersion>3</PowerShellVersion>

  <Functions>

    <FunctionParameters>

      <FunctionName>TestMeOne</FunctionName>

      <Description>PowerShell Function One</Description>

      <Parameters>

        <BooleanParameter>

          <Name>param1</Name>

          <Description>Expects a boolean input (true/false).</Description>

          <IsOptional>false</IsOptional>

          <Default>true</Default>

        </BooleanParameter>

        <StringParameter>

          <Name>param2</Name>

          <Description>Expects a string that matches the regular expression '{0}'.</Description>

          <IsOptional>false</IsOptional>

        </StringParameter>

      </Parameters>

    </FunctionParameters>

  </Functions>

</plug-inData>

 

That looks a lot better, especially the name and description attribute we added for each function and its parameters is quite handy to have.Additionally we have also defined the parameter type, which in turn defined the type of input value that is expected by the script.

 

Additional XML Definitions

Well... we are almost done. There is a tiny task of defining the function logic which has not been performed yet.

 

<?xml version="1.0" encoding="utf-8"?>

<plug-inData xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">

  <Name>PowerShellSample</Name>

  <Description>This a pretty straight external plug-in with two sample function for demonstration.</Description>

  <Version>1.2.3.4</Version>

  <Filename>PowerShellSample.ps1</Filename>

  <PowerShellVersion>3</PowerShellVersion>

  <Functions>

    <FunctionParameters>

      <FunctionName>TestMeOne</FunctionName>

      <Description>PowerShell Function One</Description>

      <Parameters>

        <BooleanParameter>

          <Name>param1</Name>

          <Description>Expects a boolean input (true/false).</Description>

          <IsOptional>false</IsOptional>

          <Default>true</Default>

        </BooleanParameter>

        <StringParameter>

          <Name>param2</Name>

          <Description>Expects a string that matches the regular expression '{0}'.</Description>

          <IsOptional>false</IsOptional>

        </StringParameter>

      </Parameters>

    </FunctionParameters>

  </Functions>

</plug-inData>

 

More information regarding the utilization of these attributes will be provided later.

So let's save the work done up to now as Manifest.xml and then proceed to the next section: The Plug-in Logic Script.

 

tip

Tip:

Preparing the manifest files is as easy as pie with a decent XML editor at one's side. The editor should provide code highlighting and optional support for XML schema definition assistance. There are many free XML editors available online, and most software development suites carry more or less sophisticated XML support along. Feel free to pick an editor of choice.

 

 

papercliper

Note:

Please refer to the Appendix of this document for details regarding formal restrictions for the plug-in manifest file.