Publishing Status for Use Outside of GroundWork

The Publish Status tool enables GroundWork service information to be available outside of the GroundWork portal. This tool is intended to help make available selected service status information for use in custom dashboard applications (e.g., NOC, departmental status page). You can create data templates and associate them with exported data, allowing you to customize how the data from GroundWork gets displayed. The status is updated regularly on a configurable interval. It’s not real-time, but it’s never far behind.

Preparation

As of GroundWork 8.2.0, you can use publish status on a specially dedicated volume, which is exported on a the path /rstools/public. You must enable this volume with the following steps:

Log in to you GroundWork server at the command line, and change to the gw8 directory
```
cd gw8
```
Edit the docker-compose-override.yml file, and add a volume to the rstools: service and the volumes: section as follows:
```
  rstools:
    volumes:
      - rstools-public:/usr/local/rstools/var/dashboard/public
# Uncomment to enable any volume
volumes:
   rstools-public:
```
Be sure to respect the indenting, as this is a yaml format file.
Restart groundwork to pick up the changes:
```
docker-compose down
docker-compose up -d
```

Client Information

A client in this context is simply a location where specific content can be accessed, along with a specification of what data to show, in what format. The data presentation is controlled by templates.

To create a client, go to Configuration > BSM and SLAs > SLA Dashboards.
Go to the Publish status tab.
Select Create client and fill out the options in the Client Information, Monitoring Settings, and Monitoring Options sections (more on this below). After clients are created, you can use the View clients tab to list existing clients, make changes to a client, or delete a client with the corresponding icon buttons.
Enter or edit the fields in the Client information form as follows:
- File: A unique name for the file that will hold the exported content. If you leave it blank, an MD5 sum will be generated and used. You may want something more descriptive, however.
- Name: The HTML name of the content in the File. This is optional, but can be used to label the content and referenced in the template.
- Description: This is another field that can show text information in the HTML that is generated.

Monitoring Settings

Under Monitoring Settings, select the services to be published.

Select a host from the drop-down menu.
Based on the host selected, highlight the services for the host, using Shift for multiple services.
Click Add selected.
On the right, an additional configuration field can be opened for the added services.
- The displayed name field is used to customize the name of the service as displayed in the external view.
- The Additional information field is used to display one text item per service, for example a maintenance note. This field, if supplied, generates an information button that shows this text when clicked.

Monitoring Options

In the Monitoring Options section, the export data format and location are specified.

Under Export format you can choose one or more of the listed formats. For each one you select, a file with the corresponding extension will be generated and published.
Each format used requires its own Export template. On this screen you can select only existing templates. See below to edit or create your own.
Use Transfer method to choose between SSH, FTP and Local. (Note that only Local is supported without other customizations. The other methods are deprecated.)
- For the Local method, enter the Path to where the files will be copied. This has to be /usr/local/rstools/var/dashboard/public (or a subdirectory) to correspond with the volume you will have added in the preparation steps above.
  
  If you want to make the published status files appear in a subdirectory, you must create that subdirectory with a command at the gw8 command line. For example to create a subdirectory called db-status, type:
  docker-compose exec rstools mkdir /usr/local/rstools/var/dashboard/public/db-status
  Then you can create a client that publishes a File called db.html to the Path:
  /usr/local/rstools/var/dashboard/public/db-status
  The resulting file would then be available on https:/{your gw server name}/rstools/public/db-status, e.g. https:/{your gw server name}/rstools/public/db-status/db.html
After saving the new configuration, the Publish status cronjob will run the client regularly (default is every minute) and transfer the data to the chosen location. The service status is thus regularly updated in the external location.

You can now point a web browser to your GroundWork server's URL, adding /rstools/public/{filename} to see the results. For example, if you created a file called db.html on the /usr/local/rstools/var/dashboard/public path on server gw001, you can browse to:
```
https://gw001/rstools/public/db.html 
```
You should see a page that reflects your choice of template and monitoring content.

Creating Export Templates

In the Create Export Template tab, you can create your own templates for any and all export formats.
In the Name field, provide the template name. This is the name you will see when selecting the Export Template for a client under Monitoring Options.
In the View Export Templates tab, you can see the list of all defined templates you have defined, which can be edited or deleted.
Each template is specific to an export type. You can select the Export type for a template. For the HTML export type, there are several placeholders described on the template editing screen which can be used in the template code. CSS and JS are allowed in the Content field. This allows the template to be integrated with a central CSS file, and the placeholders can be used to give the displayed data more context (such as the time stamp of the cronjob, the service description data, etc).
In the Description field, enter text to describe the template. This information is not available in the exported view of the service content. It is to help you keep track of the templates you use.
The Content field contains all the generated code that will be present in the exported file.

Once you have your custom templates, they may be assigned to clients using the client settings, as above.

Troubleshooting

If you are not seeing the files show up at the URL you expect, you may have made an error in configuration that inhibits the creation of the files. One way to tell that this is the case is to example the cron log:

docker-compose logs --tail 200 cron

This will tell you the results of the last few cron jobs. You may see an error such as:

cron_1            | 1637094964: 0 from 1 targets down, took 0s
cron_1            | Client #2 - MV: Could not move to localhost:/usr/local/rstools/var/dashboard/public/foobar/ (Error #1 - Message: mv: cannot move '/tmp/foo.json' to '/usr/local/rstools/var/dashboard/public/foobar//foo.json': No such file or directory).

This would indicate that the path you selected for Client 2 has an extra trailing "/". You might also have forgotten to create the subdirectory "foobar" on the public volume.