Child pages
  • Creating an automaIT Plug-in
Skip to end of metadata
Go to start of metadata

Table of Contents

Further information

This page describes the structure and contents of an automaIT plug-in. For assistance on handling plug-ins in your development environment we offer an Eclipse plug-in. See page Development Environment for information on installing and using this helpful extension.

Plug-in structure

A plug-in is a zipped folder (usually having a .jar extension) with a plug-in descriptor in its root directory. The plugin-descriptor.xml defines the properties and the content of the plug-in. Usually a plug-in contains additional folders to group elements for better readability.

/
├─ components/
├─ plans/
├─ resources/
└─ plugin-descriptor.xml

There is a template plug-in project for Eclipse available. Besides the basic structure it also contains some files related to the Eclipse build process. Using the Eclipse plug-in you won't need this template as the Eclipse plug-in generates it for you.

The Plug-In Descriptor

The plugin-in descriptor defines the properties of a plugin as well as its contents.

plugin-descriptor.xml
<?xml version="1.0" encoding="UTF-8"?>
<plugin
    xmlns="http://www.novatec-gmbh.de/np/schemas/server/model/2.2"
    vendor="NovaTec Solutions GmbH"
    description="Template for automaIT plugin development."
    name="info.novatec.automait.template"
    version="1.0">
    
    <memberList>
        <folder name="/info/novatec/automait/template" />
    </memberList>
</plugin>

Files that are included in the plug-in zip file and are not mentioned in the plug-in descriptor will not be recognized as part of the plug-in by the automaIT server.

Adding a Component

To add a component, the .xml file defining the component needs to be placed and registered inside the plug-in.

/
├─ components/
│	└─ Component.xml
├─ plans/
├─ resources/
└─ plugin-descriptor.xml

The following code can be used for a simple example component.

components/Component.xml
<?xml version="1.0" encoding="UTF-8"?>
<component
    xmlns="http://www.novatec-gmbh.de/np/schemas/server/model/2.2"
    path="/info/novatec/automait/template"
    description="Create a new directory."
    name="Component">

    <!--
        ID is required and used to identify the installed component instance. One component may be installed
        as several instances using different IDs so we use the distinct value :[path] here.
    -->
    <id name="id" default=":[path]" modifier="FINAL" />

    <!--
        Optional component variables define configuration values which may be modified during installation
        and will be persisted in automaIT for later use in uninstall, controls or other components.
    -->
    <var name="path" default="/tmp/testpath1" prompt="Path to new directory." />
    <var name="user" default="root" prompt="User to use for directory creation. Will become the directory owner but must have write permissions for the parent folder." />
    <var name="permissions" default="0775" prompt="Permissions to set for the directory." />

    <!--
        On or more installSteps must be defined here and describe the installation routine.
        They are also called constructors.
    -->
    <installList>
        <installSteps name="default" description="Create the directory given in path.">
            <!--
                Parameters are optional in (un)installSteps and controls and used to modify their behavior.
                These values won't be persisted and are only valid during execution of the code block.
            -->
            <param name="markOnly" displayMode="BOOLEAN" default="false" prompt="Actions will be done in automaIT with no physical effects on remote host." />

            <!--
                This markOnly construct is strongly recommended to support installations and uninstallations in automaIT which are quiet independent
                from the physical host configuration and very useful in case of component bugs.
            -->
            <if>
                <condition>
                    <not>
                        <isTrue value=":[markOnly]" />
                    </not>
                </condition>
                <then>
                    <!-- Insert code here -->
                    <!--
                        execNatives define commands to be executed on the managed host. 
                        An executing user can be defined different to the default root user.
                    -->
                    <execNative userToRunAs=":[user]">
                        <exec cmd="mkdir">
                            <arg value="-p" />
                            <arg value=":[path]" />
                        </exec>
                    </execNative>

                    <!-- 
                        Defined controls can be used in (un)installSteps, other controls and other components.
                        They allow code encapsulation and reutilization.
                    -->
                    <call blockName="changePermissions">
                        <argList permissionOctets=":[permissions]" />
                        <thisComponent />
                    </call>
                </then>
            </if>
        </installSteps>
    </installList>

    <!--
        On or more uninstallSteps must be defined here and describe the uninstallation routine.
        They are also called deconstructors.
    -->
    <uninstallList>
        <uninstallSteps name="default" description="Remove the directory.">
            <param name="markOnly" displayMode="BOOLEAN" default="false" prompt="Actions will be done in automaIT with no physical effects on remote host." />
            <if>
                <condition>
                    <not>
                        <isTrue value=":[markOnly]" />
                    </not>
                </condition>
                <then>
                    <!-- Insert code here -->
                    <execNative>
                        <exec cmd="rm">
                            <arg value="-rf" />
                            <arg value=":[path]" />
                        </exec>
                    </execNative>
                </then>
            </if>
        </uninstallSteps>
    </uninstallList>

    <!-- Controls are optional and used to perform instance related actions during the instance's lifetime. -->
    <controlList>
        <control name="changePermissions" description="Change directory permissions.">
            <param name="permissionOctets" default="0775" prompt="Permissions to use." />
            <execNative>
                <exec cmd="chmod">
                    <arg value=":[permissionOctets]" />
                    <arg value=":[path]" />
                </exec>
            </execNative>
        </control>
    </controlList>
</component>

 

The plug-in descriptor needs to know which .xml file to use and what type of element it describes. Therefore the plug-in descriptor gets extended by one line.

plugin-descriptor.xml
<?xml version="1.0" encoding="UTF-8"?>
<plugin
    xmlns="http://www.novatec-gmbh.de/np/schemas/server/model/2.2"
    vendor="NovaTec Solutions GmbH"
    description="Template for automaIT plugin development."
    name="info.novatec.automait.template"
    version="1.0">
    
    <memberList>
        <folder name="/info/novatec/automait/template" />

        <component jarPath="components/Component.xml" />	<!-- Defines this .xml file as component and makes it part of the plug-in. -->
    </memberList>
</plugin>

Adding a Plan

Adding a plan is almost the same procedure as Adding a Component. First the .xml file defining the plan needs to be placed into the plug-in.

/
├─ components/
│	└─ Component.xml
├─ plans/
│	└─ Plan.xml
├─ resources/
└─ plugin-descriptor.xml

The following example will install the above component.

plans/Plan.xml
<?xml version="1.0" encoding="UTF-8"?>
<plan
    xmlns="http://www.novatec-gmbh.de/np/schemas/server/model/2.2"
    description="Install Component to create a directory."
    path="/info/novatec/automait/template"
    name="Plan">

    <!--
        Plan parameters are like control parameters and used to configure the execution or change their behaviour.
        Their values won't be persisted and are only valid during plan execution.
    -->
    <param name="markOnly" displayMode="BOOLEAN" default="false" prompt="Actions will be done in automaIT with no physical effects on remote host." />
    <param name="path" default="/tmp/testpath1" prompt="Path to new directory." />
    <param name="user" default="root" prompt="User to use for directory creation. Will become the directory owner but must have write permissions for the parent folder." />
    <param name="permissions" default="0775" prompt="Permissions to set for the directory." />

    <!--
        The following block initiates the installation of the Component.xml using the component variables in compVarList and markOnly as an installer parameter.
        Referenced components are defined by their name and optionally by their path which is necessary if different to the plans path.
        Installation will be performed on the same host, the plan is executed on unless the parameter host is given
        those value is the current hosts name here which makes the usage unnecessary and just a show case.
    -->
    <install blockName="default">
        <argList markOnly=":[markOnly]" />
        <component name="Component" path="/info/novatec/automait/template" host=":[target:sys.hostName]" />
        <compVarList path=":[path]" user=":[user]" permissions=":[permissions]" />
    </install>
</plan>

Then the Plan.xml file needs to be registered inside the plug-in descriptor.

plugin-descriptor.xml
<?xml version="1.0" encoding="UTF-8"?>
<plugin
    xmlns="http://www.novatec-gmbh.de/np/schemas/server/model/2.2"
    vendor="NovaTec Solutions GmbH"
    description="Template for automaIT plugin development."
    name="info.novatec.automait.template"
    version="1.0">
    
    <memberList>
        <folder name="/info/novatec/automait/template" />

        <component jarPath="components/Component.xml" />	<!-- Defines this .xml file as component and makes it part of the plug-in. -->

        <component jarPath="plans/Plan.xml" />	<!-- Defines this .xml file as plan and makes it part of the plug-in. -->
    </memberList>
</plugin>

Now the plug-in contains 

  1. a plug-in descriptor
  2. a component
  3. a plan
Any other files inside the plug-in will be ignored by the automaIT server.

Plug-In Versioning

Currently the plug-in descriptor defines the plug-in version 1.0. It is useful to reflect this version in the plug-in file name: info.novatec.automait.template_1.0.jar. The build script from the template project already uses the version to generate the file name.  A new plug-in version always depends on an older one.

<?xml version="1.0" encoding="UTF-8"?>
<plugin
    xmlns="http://www.novatec-gmbh.de/np/schemas/server/model/2.2"
    vendor="NovaTec Solutions GmbH"
    description="Template for automaIT plugin development."
    name="info.novatec.automait.template"
    version="1.1"
	previousVersion="1.0">
    
    <memberList>
        <folder name="/info/novatec/automait/template" />

        <component jarPath="components/Component.xml" />	<!-- Defines this .xml file as component and makes it part of the plug-in. -->

        <component jarPath="plans/Plan.xml" />	<!-- Defines this .xml file as plan and makes it part of the plug-in. -->
    </memberList>
</plugin>

The previousVersion attribute defines the version this plug-in depends on. Otherwise an error message like The plug-in cannot be imported because the plug-in info.novatec.automait.template#1.0 already exists and the new plug-in is not a patch plug-in. will be raised. Now it only can be imported into the automaIT server if version 1.0 of this plug-in is already installed. Also, it is not possible to skip a version. If a plug-in defines its version 1.3 and the previous version as 1.0 it can not be imported into a server with plug-in version 1.2.

Always keep ALL productive versions of a plug-in. If versions 1.0 to 1.3 are lost it is not possible to install a depending plug-in version 1.4.

  • No labels