ZenPacks.baileytj.TransformLoader

About

A ZenPack to load transforms for Event Classes and Event Class Mappings from a standalone file when utilizing ZenPackLib's yaml format.

When including transform code in the zenpack.yaml file there is no easy way to validate the code syntax or style. By storing the transforms in their own .py files the transform code can be easily verified before ZenPack installation.

Using

Directory Structure

A directory within the ZenPack should be created to hold all of the transforms for the event classes and event class mappings. The directory is typically called transforms and resides alongside the zenpack.yaml file created by ZenPackLib.

Transforms for the event class should be in a file named class.py that resides in a directory structure matching the event class. For example, a transform for an event class of /Status/Example should reside at transforms/Status/Example/class.py.

Event class mapping transforms should be kept in a file named after the mapping with the python file extention. For example, a transform for a mapping of exampleMapping within the /Status/Example event class should reside at transforms/Status/Example/exampleMapping.py.

Loading Transforms

If the ZenPack was created with ZenPackLib, there should be a __init__.py file that resides in the same directory as the zenpack.yaml file that looks like the following:

import os
from ZenPacks.zenoss.ZenPackLib import zenpacklib

CFG = zenpacklib.load_yaml([os.path.join(os.path.dirname(__file__), "zenpack.yaml")], verbose=False, level=10)
schema = CFG.zenpack_module.schema

To load the transforms from their standalone files the load_transforms function should be called from within the __init__.py of the ZenPack. The result should look similar to the following:

import os
from ZenPacks.baileytj.TransformLoader import load_transforms
from ZenPacks.zenoss.ZenPackLib import zenpacklib

CFG = zenpacklib.load_yaml([os.path.join(os.path.dirname(__file__), "zenpack.yaml")], verbose=False, level=10)
load_transforms(CFG, os.path.join(os.path.dirname(__file__), "transforms"))
schema = CFG.zenpack_module.schema

As you can see on line 2 of the new __init__.py file, the load_transforms function is imported from the TransformLoader ZenPack. The load_transforms function takes two arguments. The first is the CFG object generated by zenpacklib. This object contains the ZenPack Spec that was loaded from the zenpack.yaml file within the ZenPack. The transforms that are loaded from the standalone files are added to the CFG object under the correct event classes and event class mappings. The second argument to load_transforms is the path to the transforms directory that was created within the ZenPack. If a different directory name was chosen it should be updated here so that the correct location is searched for transforms. The load_transforms function call must be after the CFG object is generated by zenpacklib, but before the schema variable is defined.

For a transform to be loaded, the event class or event class mapping MUST be defined within the zenpack.yaml file. Transforms that exist solely as python files within the transforms directory will not be automatically created in the CFG object. There is no need to define the transforms field under the event class yaml definition nor the event class mapping yaml definition. As long as the event class or event class mapping is defined in the yaml definition load_transforms will attempt to load the transforms with the corresponding name. The behavior of load_transforms is to always load the transform from the transforms directory and add the loaded transform to the CFG. If a transform is defined within the zenpack.yaml file AND a transform exists within the transforms directory, when load_transforms is called the transform in the zenpack.yaml file will be overwritten.

ZenPack Dependancies

When utilizing the TransformLoader ZenPack with another ZenPack, make sure to add ZenPacks.baileytj.TransformLoader to the INSTALL_REQUIRES line within setup.py. If created by zenpacklib, the line will look like the following:

INSTALL_REQUIRES = ['ZenPacks.zenoss.ZenPackLib']

The line should be updated to include the TransformLoader ZenPack as a requirement, along with any other required ZenPacks.

INSTALL_REQUIRES = ['ZenPacks.zenoss.ZenPackLib', 'ZenPacks.baileytj.TransformLoader']