Sentinel Collector SDK 2014 Updates: Collector Documentation

Sentinel Collector SDK 2014 Updates: Collector Documentation

This article is part of a series of articles diving into the new functionality present in the 2014 Preview Sentinel SDK. Today I will be covering the new documentation options and what they mean for those who have developed collectors previously, as well as all of us developing collectors now and in the future. As in other articles, it may be useful to dive into some of the history of the SDK to lead into where we are going in the future, and provide some of the rationale behind that map.

The Sentinel SDK has been available to the public for many years, and has been evolving during that time to simplify the setup, provide additional capabilities to developers, and generally improve the base/boilerplate code that powers all of the plugins within Sentinel based on customer feedback; the 2011.1 SDK beta a few years ago had a lot of big changes to make the SDK setup a simple process that anybody can do instead of ten pages of steps. The documentation for collector plugins has existed throughout this time, and the format of the documentation has always been a template file provided by default when the collector plugin was started in the SDK, with some fields being pulled in from other parts of the collector at build time. Perhaps an example will help explain this.

In the 2011.1, as well as the 2014 Preview, SDK when building a new collector plugin there is a release.odt file which is a stock file with generic information that applies to collectors in general. This is editable using a proper document editor (LibreOffice, OpenOffice, or anything else supporting the public OpenDocument format) to add specific information for the current collector plugin. There are also document variables contained within this file which are automatically filled-in whenever the document is built; for example:

@AUTHOR@ - Replaced with the plugin's author
@PLUGIN@ - Replaced with the name of the plugin.
@UUID@ - Replaced with the plugin's UUID


During the build process for a collector there used to be a prompt that would ask something along the lines of, "Do you want to build documentation?" If you chose 'yes', and if you had your system configured properly (LibreOffice or OpenOffice installed, and referenced within the SDK plugin) the build process would use the release.odt file, plus a bunch of settings from the collector plugin that was being developed, and merge everything into a nice single document on the fly, creating a PDF and embedding it where necessary. The result is that a Production build of the collector automatically had (as much as possible) up-to-date information on the collector itself; connection methods were in there and updated, names of plugins, authors, vendors, your customized description of the plugin updated five minutes go per the customer's request, etc. For more details on how things used to be, see the Plug-In Documentation page found at https://www.novell.com/developer/plugin-sdk/sdk_documentation.html of the SDK web-based documentation. Because this process called an external process and then did a lot of mangling of information in release.odt within the document, it was a bit slow compared to the rest of the build process. Also, the PDF that was built was stored along with the collector, but usually has not been the one available within the plugin, and therefore accessible to a Sentinel user within ESM who was given a different version of mostly-boilerplate information. Finally, PDF is a great format, but it requires a special client of some sort to read it, where other formats can be read by just about anything. This all leads up to changes in the latest SDK.

Today all of that is still present, but you do not need it anymore. If you want to use it, particularly if you are upgrading to using the 2014 Preview SDK with a collector plugin created from a previous version of the SDK which already has documentation that you are not yet ready to recreate, you can enable building of the old style of documentation by modifying ~/.netiq/pluginsdk/oo.properties as the build output states:

_build-externaldoc:

[echo] External PDF will not be created because the variable build.pdf
in ~/.netiq/pluginsdk/oo.properties has been set to no.

Looking in the file mentioned the option to enable this setting, or prompt for it, or specify an alternate path for soffice, is all pretty obvious:

soffice.path.value=/usr/bin/
prompt.for.oo=no
build.pdf=no
macro.already.installed=yes


Now that we know how to do the old way if needed, let's talk about the new way. My opinion of the drawbacks to be overcome with the old way were requirements for external software (LibreOffice/OpenOffice), slowness, inconsistent documentation within the plugin vs. what was distributed separately, and limitations around the formats used (PDF in particular). Keeping in mind the need to keep everything properly cross-platform, the only options for some sort of document template and merge system other than the LibreOffice/OpenOffice format would be something like HTML which can be rich in nature but is completely able to be hacked with standard markup tools (WYSIWYG editors, text editors, XSLT and XML tools, etc.). Removing this dependency also removes some slowness due to lighter-weight applications being loaded, and the removal of the PDF format. As long as the documentation that was built was placed both inside the plugin as well as alongside it in the build directory, all problems are solved. Tada, here we are today.

The new way, using HTML as the final format, should be accessible anywhere... mobile phone, dedicated monitoring system, laptop, tablet; really what cannot open and render HTML pretty well these days? There was a potential downside to HTML in my mind, and that was the traditional use of dozens of files to support a single final product. For example, look at how many HTTP request are made by your web browser the next time you hit a website, and you'll see that there are images, CSS files, JS files, etc. all being roped in to make the final display what the author expects. While CSS and JS are regularly embedded, what about images? It turns out that while images are being avoided generally (big, harder to render on smaller screens, overused and providing a disproportionately small amount of value compared to size and other downsides) it is possible to embed an image entirely in HTML, so this was good news for me. Since it is useful information generally, let's start there.

For a quick read on the topic outside of the Sentinel world, check out this link from StackOverflow: http://stackoverflow.com/questions/1207190/embedding-base64-images (Embedding Base64 Images) The technology is known as Data URIs, is described on Wikipedia with some quick details including browser compatibility http://en.wikipedia.org/wiki/Data_URI_scheme and solves our problem nicely. There are some good reasons to NOT use these in normal web-based content, but this is neither normal nor web-based, so we'll make an exception. Note that adding images or other heavy content to a page will make it load more-slowly, as always, no matter how it is roped in for use in the client.

The basic look of the <img/> tag changes from something like this:

<img src="path/to/image.png"/>

to this:
<img src="alt="Embedded Image" src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAA/MAAABN"/>


Note that the src field includes the string 'data:', a colon (:), a MIME type (image/png), semicolon (;), a format (base64), one more comma (,), and then the base64-encoded image (obviously truncated here for brevity). The end result when putting these images somewhere in the HTML file is you end up with long lines of base64-encoded data, but it makes something otherwise impossible able to be done pretty easily. As an example, pretend you have decided to include a screenshot of the application vendor's logo, or maybe your customer's/employer's logo, and you want that somewhere in the final documentation to provide something extra and personalized. The first step is to get the image, if not available already, into a format that is made for the web; Portable Network Graphics (PNG) format is a good option, as is Scalar Vector Graphics (SVG), or maybe Joint Photographic Experts Group (JPEG). Once the file is available the next step is to base64-encode it and determine the proper MIME designation (image/png, image/svg+xml, or image/jpeg). Base64-encoding is trivial most of the time, and can be done using something like the following on any old server you have:

base64 /path/to/image/file.png | tr -d '\n'


The line above uses the built-in base64 command, giving it a file to encode, and then strips out newlines in the resulting output so only one big long string of base64-encoded data remains. The reason for the newlines is mostly convention; it is common for encodings like base64 to be "folded" after so many characters (78 usually) to fit within the size of an old-fashioned terminal window nicely, and to avoid pain and suffering in today's powerful editors that will otherwise try to show you the millionth character in a megabyte-long string of data. Still, for our purposes with data URIs we want one big long string of stuff, so we send the encoded data through 'tr' telling it to delete newlines, and now we're ready.

To provide a workable example with a known file, let's take SUSE's logo from Wikipedia: http://upload.wikimedia.org/wikipedia/en/b/b5/Suse_logo_w-tag_color.png Pull down the file, encode it as shown above (or with another base64-encoding mechanism of your choosing) and then create the data URI that results:

curl -O http://upload.wikimedia.org/wikipedia/en/b/b5/Suse_logo_w-tag_color.png
base64 Suse_logo_w-tag_color.png | tr -d '\n'


The resulting data URI should look like this:

<img src="alt="SUSE Logo Embedded Image" src="data:image/png;base64,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"/>


For those interested in the details about encoding (such as base64-encoding) the original file size was 11,989 bytes, and the encoded size is now 15,988 bytes which is 1.3x the original size, as is normal with base64-encoding since the encoding standard uses four bytes to represent three of the original bytes, expanding the total size by 1/3 or 33%. This is probably another reason why doing this on the web generally is not advisable.

Moving past the specifics of the data URI we can get into how to build the actual documentation. Within the collector plugin in Eclipse there is a 2011.1/docs/html directory which is where the customized HTML files will go before being joined together to make one large document holding the final documentation. By default this directory has three files: 'Known Issues.html', 'Release Notes.html', and 'Sections.seq'. The first two are basic HTML files, mostly empty, which can be customized with appropriate, plugin-specific content per their titles. Examples for Release Notes could include assumptions made during development, or maybe a bunch of documentation on how to setup the application to send the correct data per the collector's requirements, or future-looking statements about what may come in the next version of the plugin, or how to potentially handle newer version of the application that may otherwise be unsupported. Known Issues, of course, mentions known issues with the plugin such as limits on types of data, or event rates, or other limitations found during testing. For a first release both of these may be blank other than to indicate this is the first release.

The really interesting part is that Sections.seq file, which has a single commented-out line within to give some guidance on its use:

~~~Existing Index Section Name,New Index Section Name(optional),New Index Section Indent(optional),HTML resource


While this is maybe something that makes sense to those familiar with the purpose of the file, in reality this is not enough, or meant to be enough, to get going with expanding the documentation. In fact, these three files have under 1 KiB of information combined, so obviously a lot more is happening that needs to be covered. As a starter, the 2014 Preview documentation has some information on (currently) page 96 in the section titled 'HTML Plug-Iin Documentation'. The documentation briefly discusses 'HTML Document Fragments', which is basically what we are seeing with the Release Notes and Known Issues files which can be edited via any HTML or text editor, depending on the user's preference and ability.

Just to show what happens by default, go ahead and modify the Release Notes and Known Issues files and add some searchable content to them keeping the HTML nature of the documents intact. Run a build from Eclipse by right-clicking on the collector's '2011.1' and choosing 'Create Development Build'. Assuming the build completes properly, somewhere near the end should be a line like the one bolded below:

    [echo] Individual HTML fragements substitution in skeleton doc complete
[echo] HTML Document generated successfully
[copy] Copying 1 file to /home/ab/code/sentinel-plugin-sdk/content/build/Collector/ABSoftware_ABProduct_2011.1r1-201412241602-internal-test/plugin/docs
[move] Moving 1 file to /home/ab/code/sentinel-plugin-sdk/content/build/Collector/ABSoftware_ABProduct_2011.1r1-201412241602-internal-test
[echo] HTML Document generated at : /home/ab/code/sentinel-plugin-sdk/content/build/Collector/ABSoftware_ABProduct_2011.1r1-201412241602-internal-test/ABSoftware_ABProduct_2011.1r1-201412241602-internal-test.html
[echo] ABSoftware_ABProduct_2011.1r1-201412241602-internal-test.html should now be available in the build directory
[xmltask] Setting standalone

_package-plugin:

_prepackage-plugin:
[xmltask] Setting standalone
[zip] Building zip: /home/ab/code/sentinel-plugin-sdk/content/build/Collector/ABSoftware_ABProduct_2011.1r1-201412241602-internal-test/ABSoftware_ABProduct_2011.1r1-201412241602-internal-test.clz.zip
BUILD SUCCESSFUL
Total time: 3 seconds


Notice a few things here, specifically that the build completed successfully and that the SDK informed you as much at the very end in capital letters; no ambiguity with the build-time success or failure at least. Also, notice that the HTML document is generated and the path to access it is printed out for easy access. Copying this path and dropping it into a regular web browser should show the standard documentation, which should now include your little edits.

The documentation generated by default creates a nice page with a table of contents and information on this particular plugin's connection methods and other properties. Like the ODT-based documentation, a lot of base information is present for any collector but it is intended that the developer add and customize information a bit, which is where the 'seq' files come in. The two sequence (seq) files tell the build process in what order to place the included HTML files, and what "indent' level, so that the document is structured as the author intends. The original Document.seq file looks like this, as taken from sentinel-plugin-sdk/current/sdk/2011.1/Collector/static/docs/html/Document.seq:

~~~Tabs(optional),Index Section Name,HTML resource
,Legal Notice,legal.html
,About This Guide,About This Guide.html
,Audience,Audience.html
,Contacting Sales Support,Contacting Sales Support.html
,Contacting the Online User Community,Contacting the Online User Community.html
,Additional Documentation,Additional Documentation.html
,Documentation Conventions,Documentation Conventions.html
,Collector Overview,Collector Overview.html
,Supported Products,Supported Products.xsl
,Connection Methods,Connection Methods.xsl
,Configuration,Configuration.html
,Observer Configuration,Observer Configuration.html
,Collector Configuration Options,Collector Configuration Options.html
,Predefined Collector Parameters,Predefined Collector Parameters.xsl
,Configuring Time Zone,Configuring Time Zone.html
,Upgrade Procedures,Upgrade Procedures.html
,Collector Customization,Generic Collector Customization.html
,Troubleshooting,Troubleshooting.html
,Revision History,Revision History.html
,Known Issues,Known Issues.html
,Release Notes,Release Notes.html


As you can see there are a lot of sections in place already, as each .html file is also present as part of the default SDK. In that same directory are the following files, just to provide a current list with dates and sizes:

-rw-r--r-- 1 ab users  442 Aug 12 13:00 Collector Configuration Options Head.html
-rw-r--r-- 1 ab users 462 Aug 12 13:00 Collector Configuration Options.html
-rw-r--r-- 1 ab users 175 Aug 12 13:00 Collector Overview.html
-rw-r--r-- 1 ab users 4483 Aug 12 13:00 Collector Pack.html
-rw-r--r-- 1 ab users 5772 Aug 12 13:00 Collector Parsing.html
-rw-r--r-- 1 ab users 1639 Aug 12 13:00 Configuration.html
-rw-r--r-- 1 ab users 2704 Aug 12 13:00 Configuring Time Zone.html
-rw-r--r-- 1 ab users 1276 Aug 12 13:00 Connection Methods.html
-rw-r--r-- 1 ab users 5024 Aug 12 13:00 Connection Methods.xsl
-rw-r--r-- 1 ab users 1061 Aug 12 13:00 Document.seq
-rw-r--r-- 1 ab users 1073 Aug 12 13:00 ESM Component Configuration.html
-rw-r--r-- 1 ab users 612 Aug 12 13:00 Exploit Detection Advisor.html
-rw-r--r-- 1 ab users 1966 Aug 12 13:00 Generic Collector Customization.html
-rw-r--r-- 1 ab users 458 Aug 12 13:00 Integration Testing.html
-rw-r--r-- 1 ab users 840 Aug 12 13:00 Observer Configuration.html
-rw-r--r-- 1 ab users 7396 Aug 12 13:00 Predefined Collector Parameters.xsl
-rw-r--r-- 1 ab users 114 Aug 12 13:00 Revision History.html
-rw-r--r-- 1 ab users 219 Aug 12 13:00 Sections.seq
-rw-r--r-- 1 ab users 1255 Aug 12 13:00 Supported Data Sources.html
-rw-r--r-- 1 ab users 1932 Aug 12 13:00 Supported Products.xsl
-rw-r--r-- 1 ab users 3410 Aug 12 13:00 Troubleshooting.html
-rw-r--r-- 1 ab users 5244 Aug 12 13:00 Upgrade Procedures.html


It may also be useful to note that some of these files do not end in .html, but use .xsl instead. As these are XSLT files (XML stylesheets) their intention is not to be used directly but instead to be executed against data in the dev environment created by the collector's developer. It is in this way that dynamic settings from the collector build process, such as application descriptions, connection methods, etc. are all pulled into the documentation at build time. Since an XSLT file needs some kind of input, note that the package.xml, as generated during the build process, is used directly for this input. As a result, to have something dynamically roped into the documentation it needs to exist in the package.xml file.

It is possible, likely even, that some of these default sections are not exactly what you want to have in your custom documentation for a collector. To provide options for this scenario NetIQ has provided the ability to override any of these files, including the Document.seq and Sections.seq files, by placing exactly-named replacement files in the collector's development directory structure. Currently the 2011.1 directory that shows up in Eclipse has several files and a few directories underneath, and the 'docs' directory is, appropriately, where we look for documentation details. Within there is an 'html' directory as mentioned above, and while there are only three files by default more can be added, including copying originals from the main SDK directories for modification on a per-plugin basis. This is particularly neat because it means you can take advantage of what comes by default from NetIQ which is likely applicable to collectors worldwide, but then modify different pieces to meet your own needs, even if that means appending to an existing section without modifying the index (via the Sections.seq file), adding new main sections or subsections (Sections.seq or Document.seq, depending on needs), or removing sections that are not wanted (Document.seq probably). A recent example I had was a request to document, with screenshots, all of the types of events for several custom collectors. Even though they were entirely customized from this SDK, I used a lot of the boilerplate files, customized a few to better meet my needs, and then added a few of my own with a lot of information that did not easily fit in the existing document. Because many of these changes were company, not plugin, specific, I was able to reuse those fragment documents in multiple collectors to further save time. Basically we see all of the benefits programmers have seen for decades in breaking up source files to relevant components, but in documentation.

The Sections.seq file looks like this by default:

~~~Existing Index Section Name,New Index Section Name(optional),New Index Section Indent(optional),HTML resource


Note that the first and last fields are required in this file. The middle fields are only required if you are creating a new subsection, and if you want that new subsection to be indented relative to the original section specified in the first field, respectively.

A few rules surrounding overrides are important to know:

  1. An override (the file overriding the original file) must exist in the plugin's documentation directory (2011.1/docs/html) as mentioned above. The build process needs to find it, and this is where it looks, so put it there. I have not tried using symlinks yet to see if I can put a common file somewhere of my own and then link to it from many plugins' 2011.1/docs/html directory, bu that's on my list of things to try. If symlinking does not work, hard-linking certainly should.


  2. The overriding file must have the exact same name as the overridden file. If off at all, keeping in mind we're dealing with computers and computers are case-sensitive by default, the override will not work. Similarly, if the Sections.seq file is used to add to an existing section, or add a subsection, the reference to an existing section must be exactly correct per the original section's name.


  3. There are some limitations around what you can do in a Sections.seq file, and other limitations in a Document.seq file. You could probably get away with just having a Document.seq file and defining everything within and modify everything everywhere, but it appears that NetIQ anticipates that most of the we will either override an HTML file completely or else we'll append to it with Sections.seq. Between the two files, there are a lot of great options, and of course it's best to redefine as little as possible to take advantage of SDK improvements in the future as seamlessly as possible.


  4. In the Document.seq file the first field is a Tabs field, which indicates how indented the defined section (the one on the current row) is from the root of the document. Only tab characters (0x09) matter and all other whitespace characters are ignored. Also note that a subsection can only ever be indented by one tab more than its parent section, so trying to go from something with zero tabs to something Indented by two tabs is not allowed without an intermediate section indented by one tab. This mostly impacts the created document index and links within the document, as the actual sections of the document are not somehow indented.


For the record, the following are the default locations for HTML files for those plugins which support them:

collectors - sdk/2011.1/Collector/static/docs/html
actions - sdk/2011.1/Action/static/docs/html
reports - sdk/2011.1/Report/static/docs/html
solutions -sdk/2011.1/Solution/static/docs/html


Working on formatting within document sections there are a few common things which may be desirable to know, such as inserting a Note to the reader which stands out as such. For this, the built-in stylesheets (CSS, not XSLT) have a class of 'note' which will properly format things to stand out as a note. Also, because we're dealing with Information Technology (IT), it is likely we'll want to paste code or something formatted like code in our documentation. Surprisingly enough, there is a 'code' class that can be applied to HTML elements just like the 'note' class, so random div/p/span tags can have content formatted appropriately with very little work on our part.

There is more to cover, but this was supposed to be a quick review so perhaps more for later. Some other ideas that have come up after working through this last use of the SDK include using the symlinks (or hardlinks) for vendor-specific things, to try to minimize the need for plugin-specific alterations by instead having one document that is referenced by all of the plugins-specific directories. Another idea may be to do some outside-the-SDK generation of data from source files, particularly when doing images that may update frequently. Getting screenshot for 100 types of events is painful, and then encoding them and placing them in the appropriate files for the build process to consume is not exactly an exercise in anything other than repetition, so creating a quick script to automate that would be worth doing in the future, especially if there is any chance of the events changing as they often do during development.

Happy Computing!

DISCLAIMER:

Some content on Community Tips & Information pages is not officially supported by Micro Focus. Please refer to our Terms of Use for more detail.
Top Contributors
Version history
Revision #:
1 of 1
Last update:
‎2015-01-15 23:29
Updated by:
 
The opinions expressed above are the personal opinions of the authors, not of Micro Focus. By using this site, you accept the Terms of Use and Rules of Participation. Certain versions of content ("Material") accessible here may contain branding from Hewlett-Packard Company (now HP Inc.) and Hewlett Packard Enterprise Company. As of September 1, 2017, the Material is now offered by Micro Focus, a separately owned and operated company. Any reference to the HP and Hewlett Packard Enterprise/HPE marks is historical in nature, and the HP and Hewlett Packard Enterprise/HPE marks are the property of their respective owners.