﻿<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet type="text/xsl" href="scheduler_job_documentation.xsl"?>
<description xmlns="http://www.sos-berlin.com/schema/scheduler_job_documentation_v1.0" xmlns:xhtml="http://www.w3.org/1999/xhtml" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.sos-berlin.com/schema/scheduler_job_documentation_v1.0 http://www.sos-berlin.com/schema/scheduler_job_documentation_v1.0.xsd">
  <job name="JobSchedulerHobbitMessageJob" title="Check Job Scheduler log file and send status message to Hobbit server" order="both" tasks="1">
    <script language="java" java_class="sos.stacks.hobbit.JobSchedulerHobbitMessageJob" resource="3" />
  </job>
  <releases>
    <release id="1.0" created="2006-04-28" modified="2006-04-28">
      <title>Version 1.0</title>
      <author name="Andreas Püschel" email="andreas.pueschel@sos-berlin.com" />
      <note language="de">
        <div xmlns="http://www.w3.org/1999/xhtml">Initiale Auslieferung</div>
      </note>
      <note language="en">
        <div xmlns="http://www.w3.org/1999/xhtml">initial release</div>
      </note>
    </release>
  </releases>
  <resources>
    <file os="all" type="java" file="sos.scheduler.jar" id="1">
      <note language="de">
        <div xmlns="http://www.w3.org/1999/xhtml">Standard-Jobs der Auslieferung</div>
      </note>
      <note language="en">
        <div xmlns="http://www.w3.org/1999/xhtml">Standard jobs in distribution</div>
      </note>
    </file>
    <file os="all" type="java" file="sos.spooler.jar" id="2">
      <note language="de">
        <div xmlns="http://www.w3.org/1999/xhtml">Klasse Job_Impl</div>
      </note>
      <note language="en">
        <div xmlns="http://www.w3.org/1999/xhtml">Class Job_Impl</div>
      </note>
    </file>
    <file os="all" type="java" file="sos.stacks.jar" id="3">
      <note language="de">
        <div xmlns="http://www.w3.org/1999/xhtml">Standard-Stacks der Auslieferung</div>
      </note>
      <note language="en">
        <div xmlns="http://www.w3.org/1999/xhtml">Standard stacks in distribution</div>
      </note>
    </file>
    <file os="all" type="java" file="sos.util.jar" id="4">
      <note language="de">
        <div xmlns="http://www.w3.org/1999/xhtml">Klassen SOSFile, SOSDate</div>
      </note>
      <note language="en">
        <div xmlns="http://www.w3.org/1999/xhtml">Classes SOSFile, SOSDate</div>
      </note>
    </file>
    <file os="all" type="java" file="sos.xml.jar" id="5">
      <note language="de">
        <div xmlns="http://www.w3.org/1999/xhtml">Klasse SOSXMLXPath</div>
      </note>
      <note language="en">
        <div xmlns="http://www.w3.org/1999/xhtml">Class SOSXMLXPath</div>
      </note>
    </file>
    <file os="all" type="java" file="org.apache.commons.jar" id="6">
      <note language="de">
        <div xmlns="http://www.w3.org/1999/xhtml">Apache Klassen org.apache.commons.httpclient.*</div>
      </note>
      <note language="en">
        <div xmlns="http://www.w3.org/1999/xhtml">Apache classes org.apache.commons.httpclient.*</div>
      </note>
    </file>
  </resources>
  <configuration>
    <params id="job_parameter">
      <param name="url" default_value="http://localhost/hobbit-cgi/bbmessage.sh" required="true">
        <note language="de">
          <div xmlns="http://www.w3.org/1999/xhtml">
            Der Parameter bestimmt die URL, an die Statusnachrichten im HTTP-Protokoll versendet werden.
            <br clear="none" />
            <br clear="none" />
            Stellen Sie bitte sicher, dass das cgi Skript
            <em>bbmessage.cgi</em>
            in Ihrer
            Hobbit Server Installation aktiviert ist und HTTP-Nachrichten vom Server
            entgegennimmt, auf dem der Job Scheduler betrieben wird.
          </div>
        </note>
        <note language="en">
          <div xmlns="http://www.w3.org/1999/xhtml">
            This parameter specifies the URL to which status messages are sent as HTTP posts.
            <br clear="none" />
            <br clear="none" />
            It is important to check that the 
            <em>bbmessage.cgi</em>
            cgi script is acivated in the Hobbit server installation
            and that HTTP posts from the server on which the Job Scheduler is operated can be accepted.
          </div>
        </note>
      </param>
      <param name="host" default_value="job scheduler host" required="true">
        <note language="de">
          <div xmlns="http://www.w3.org/1999/xhtml">
            Der Parameter bestimmt den Host, für den Statusnachrichten versendet werden.
            Dies ist nicht der Host, der die Nachrichten entgegennimmt (siehe Parameter
            <em>url</em>
            ),
            sondern der Host, für den berichtet wird.
            <br clear="none" />
            <br clear="none" />
            Bleibt der Parameter leer, dann wird der Hostname eingesetzt, auf dem der Job Scheduler abläuft.
          </div>
        </note>
        <note language="en">
          <div xmlns="http://www.w3.org/1999/xhtml">
            This parameter specifies the the host for which status messages are sent.
            Note that this is not the host that receives status messages (see parameter
            <em>url</em>
            ),
            but the host for which a status is reported.
            <br clear="none" />
            <br clear="none" />
            If this parameter is not specified then the name of the host
            on which the Job Scheduler is operating is used.
          </div>
        </note>
      </param>
      <param name="test" default_value="scheduler" required="true">
        <note language="de">
          <div xmlns="http://www.w3.org/1999/xhtml">Der Parameter bestimmt den Namen des Tests, für den Statusnachrichten versendet werden.
            Dieser Name erscheint als Spalte in der Web-Konsole des Hobbit Servers.</div>
        </note>
        <note language="en">
          <div xmlns="http://www.w3.org/1999/xhtml">This parameter specifies the the name of the test for which status messages are sent.
            This name appears as a column in the Hobbit server web interface.</div>
        </note>
      </param>
      <param name="type" default_value="status" required="true">
        <note language="de">
          <div xmlns="http://www.w3.org/1999/xhtml">
            Der Parameter bestimmt den Nachrichtentyp, der an den Hobbit Server gesendet wird:
            es werden die Typen
            <em>status</em>
            ,
            <em>notify</em>
            und
            <em>reset</em>
            unterstützt.
            <br clear="none" />
            <br clear="none" />
            <ul>
              <li>
                status
                <br clear="none" />
                <br clear="none" />
                Der übliche Typ, mit dem Nachrichten versendet werden.
              </li>
              <li>
                notify
                <br clear="none" />
                <br clear="none" />
                Dieser Typ erzeugt eine Benachrichtigung durch den Netzwerk Monitor, z.B. per SMS,
                und ist abhängig von der Konfiguration des Netzwerk Monitors.
              </li>
              <li>
                reset
                <br clear="none" />
                <br clear="none" />
                Dieser Typ dient zum Zurücksetzen von Meldungen. Im Normalfall (siehe Parameter
                <code>persistent</code>
                )
                sendet dieser Job Warnungen und Fehler wiederholt. Sie können einen zweiten Job mit dieser
                Implementierung einrichten und mit dem Parameter
                <code>type</code>
                und dem Wert
                <em>reset</em>
                starten, um die Meldung von Fehlerzuständen bewußt zurückzusetzen.
              </li>
            </ul>
          </div>
        </note>
        <note language="en">
          <div xmlns="http://www.w3.org/1999/xhtml">
            This parameter specifies the message type that is sent to the Hobbit server:
            <em>status</em>
            ,
            <em>notify</em>
            and
            <em>reset</em>
            are supported message types.
            <br clear="none" />
            <br clear="none" />
            <ul>
              <li>
                status
                <br clear="none" />
                <br clear="none" />
                This is the usual type that is used to send messages.
              </li>
              <li>
                notify
                <br clear="none" />
                <br clear="none" />
                This type causes a notification to be sent, e.g. via SMS, which depends on
                the configuration of your Network Monitor.
              </li>
              <li>
                reset
                <br clear="none" />
                <br clear="none" />
                This type is used to reset messages. Normally (see parameter
                <code>persistent</code>
                )
                this job repeatedly sends warnings and errors. However, a second job could be set up with this
                implementation and the
                <code>type</code>
                parameter configured with the value
                <em>reset</em>
                in order to avoid the repeated sending of error states.
              </li>
            </ul>
          </div>
        </note>
      </param>
      <param name="lifetime" default_value="" required="false">
        <note language="de">
          <div xmlns="http://www.w3.org/1999/xhtml">
            Der Parameter bestimmt die Dauer, für die eine Nachricht am Hobbit Server als gültig betrachtet wird.
            Zum Zeitpunkt der Dokumentation dieses Jobs heißt es in der Hobbit Dokumentation:
            <br clear="none" />
            <br clear="none" />
            <cite>The default is 30 minutes, but you can set any period you like. ...
              The LIFETIME is in minutes, unless you add an "h" (hours), "d" (days) or "w" (weeks)
              immediately after the number, e.g. "status+5h" for a status that is valid for 5 hours.</cite>
          </div>
        </note>
        <note language="en">
          <div xmlns="http://www.w3.org/1999/xhtml">
            This parameter specifies the duration for which a message is valid for the Hobbit server.
            At the time of writing the Hobbit documentation says:
            <br clear="none" />
            <br clear="none" />
            <cite>The default is 30 minutes, but you can set any period you like. ...
              The LIFETIME is in minutes, unless you add an "h" (hours), "d" (days) or "w" (weeks)
              immediately after the number, e.g. "status+5h" for a status that is valid for 5 hours.</cite>
          </div>
        </note>
      </param>
      <param name="persistent" default_value="true" required="false">
        <note language="de">
          <div xmlns="http://www.w3.org/1999/xhtml">Der Parameter bestimmt, ob Nachrichten über Warnungen und Fehler wiederholt gesendet werden sollen.
            Dies ist relevant, da andernfalls eine Meldung genau einmal gesendet wird und beim
            wiederholten Starten des Jobs an der Konsole des Netzwerk Monitors ein vorheriger
            Fehlerzustand nicht mehr sichtbar ist.</div>
        </note>
        <note language="en">
          <div xmlns="http://www.w3.org/1999/xhtml">
            This parameter specifies whether messages with warnings and errors should be sent repeatedly.
            If this parameter is set to
            <code>false</code>
            then all messages are just sent once.
            This, in turn, means that after a repeated start of this job, 
            the Network Monitor console will not show older error states.
          </div>
        </note>
      </param>
    </params>
    <payload>
      <note language="de">
        <div xmlns="http://www.w3.org/1999/xhtml">
          Die nachfolgend aufgeführten Parameter können bzw. müssen bei Verwendung eines
          auftragsgesteuerten Jobs in der Nutzlast (payload) des Auftrags übergeben werden.
          Dies gilt analog für die in der Sektion
          <em>Job Parameter</em>
          angegebenen Parameter,
          die ebenfalls mit den Nutzdaten des Auftrags angegeben werden.
          <br clear="none" />
          <br clear="none" />
          Sie müssen diese Parameter nicht angegeben, wenn der Job ohne Aufträge standalone abläuft.
        </div>
      </note>
      <note language="en">
        <div xmlns="http://www.w3.org/1999/xhtml">
          The following parameters can and should be specified in the order's payload
          if this job is driven by orders.
          This is equally true for the parameters given in the
          <em>job parameters</em>
          section that should be specified in the payload.
          <br clear="none" />
          <br clear="none" />
          These parameters do not have to be specified, if this job is running standalone without orders.
        </div>
      </note>
      <params id="payload_parameter" reference="job_parameter">
        <param name="color" default_value="green" required="true">
          <note language="de">
            <div xmlns="http://www.w3.org/1999/xhtml">
              Der Parameter bestimmt die Art der Nachricht:
              <br clear="none" />
              <br clear="none" />
              <ul>
                <li>green: ok</li>
                <li>yellow: Warnung</li>
                <li>red: Fehler</li>
              </ul>
              <br clear="none" />
              Ob andere Nachrichtenarten zugelassen sind, ist ggf. von der eingesetzten Hobbit Version abhängig.
            </div>
          </note>
          <note language="en">
            <div xmlns="http://www.w3.org/1999/xhtml">
              This parameter specifies the message severity:
              <br clear="none" />
              <br clear="none" />
              <ul>
                <li>green: ok</li>
                <li>yellow: warning</li>
                <li>red: error</li>
              </ul>
              <br clear="none" />
              See the Hobbit documentation for other values which are accepted.
            </div>
          </note>
        </param>
        <param name="message" default_value="" required="true">
          <note language="de">
            <div xmlns="http://www.w3.org/1999/xhtml">Der Parameter enthält den Inhalt der Nachricht, die an den Hobbit Server gesendet wird.</div>
          </note>
          <note language="en">
            <div xmlns="http://www.w3.org/1999/xhtml">Mandatory message content that will be sent to the Hobbit server.</div>
          </note>
        </param>
      </params>
    </payload>
  </configuration>
  <documentation language="de">
    <div xmlns="http://www.w3.org/1999/xhtml">
      Der Job wird als standalone Lösung eingesetzt, um die Protokolldateien des Job Schedulers
      zu prüfen und ggf. Statusnachrichten an einen Hobbit Server zu senden. Hobbit ist eine
      Open Source Lösung für das Network Monitoring und ist unter
      <a href="http://hobbitmon.sourceforge.net" target="_blank" shape="rect">http://hobbitmon.sourceforge.net</a>
      verfügbar.
      <br clear="none" />
      <br clear="none" />
      Dieser Job prüft die Verarbeitungsergebnisse aller Jobs, die vom Job Scheduler ausgeführt wurden,
      und meldet sie an den Hobbit Server. Sie müssen daher nicht notwendigerweise Ihre eMails prüfen,
      um festzustellen, ob ein Job-Fehler aufgetreten ist, sondern erhalten an der Hobbit Web-Konsole
      Warnungen und Fehler angezeigt.
      <br clear="none" />
      <br clear="none" />
      Es wird keine Hobbit Client-Installation vorausgesetzt, da Statusnachrichten per HTTP-Protokoll
      gesendet werden. Bitte prüfen Sie, ob das cgi Skript
      <em>bbmessage.cgi</em>
      in Ihrer
      Hobbit Server-Installation aktiviert ist und Nachrichten von dem Server entgegennimmt,
      auf dem der Job Scheduler abläuft, siehe Parameter
      <em>url</em>
      .
      <br clear="none" />
      <br clear="none" />
      Der Wechsel von Protokolldateien (log rotation) wird von diesem Job berücksichtigt.
      Die Performance verschlechtert sich nicht bei Verwendung großer Protokolldateien,
      da der Job mit Dateizeigern nur die Einträge verarbeitet, die im Protokoll zwischen
      zwei Job-Starts hinzugefügt wurden.
      Beachten Sie bitte die Gültigkeitsdauer von Nachrichten, die am Hobbit Server
      und mit der einzelnen Nachricht konfiguriert werden kann.
      <br clear="none" />
      <br clear="none" />
      Der Job speichert Nachrichten und versendet sie wiederholt, damit in der Hobbit Web-Konsole
      alle Warnungen und Fehler bei wiederholtem Nachrichtenversand erhalten bleiben.
      Das Zurücksetzen von Meldungen über Fehlerzustände muss durch einen Administrator erfolgen: richten Sie dazu
      einen zweiten Job mit dieser Implementierung ein und konfigurieren Sie den Parameter
      <code>type</code>
      mit dem Wert
      <em>reset</em>
      . Durch das Starten des zweiten Jobs werden alle Meldungen über
      Fehlerzustände zurückgesetzt.
      Wenn Sie ein anderes Verhalten des Jobs bevorzugen, dann setzen Sie den Parameter
      <code>persistent</code>
      dieses Jobs auf den Wert
      <em>false</em>
      , um jede Nachricht nur einmal zu versenden.
      <br clear="none" />
      <br clear="none" />
      Als standalone betriebene Lösung sollte dieser Job regemäßig wiederholt gestartet werden,
      z.B. alle 5 Minuten, damit Fehler und Warnungen von Jobs zeitnah an der Hobbit Web-Konsole erscheinen.
      Der Job versendet
      <em>green</em>
      Statusnachrichten, wenn keine Probleme aufgetreten sind
      und meldet wiederholt Warnungen (
      <em>yellow</em>
      )
      und Fehler (
      <em>red</em>
      ), da es Aufgabe der Administratoren ist zu entscheiden, ob ein
      Fehlerzustand aufgehoben ist oder eine Warnung ignoriert werden kann.
      <br clear="none" />
      <br clear="none" />
      <br clear="none" />
      Als alternatives Einsatzszenario neben der standalone Lösung können Sie diesen
      Job in einer Job-Kette betreiben, der Aufträge hinzugefügt werden, wenn
      Statusnachrichten versendet werden sollen. Dies ist sinnvoll, wenn Sie individuelle
      Jobs mit dem Job Scheduler API entwickeln und Job-Fehler schneller und ggf. durch
      individuelle Meldungen ergänzt an den Hobbit Server senden möchten.
      <br clear="none" />
      <br clear="none" />
      Sie können mit einfachen Mitteln einen zweiten Job schreiben, der einen Auftrag für eine
      <em>green</em>
      Statusnachricht an diesen Job sendet und von Administratoren gestartet werden kann,
      um die Aufhebung eines Fehlerzustands zu signalisieren, z.B. mit JavaScript:
      <br clear="none" />
      <br clear="none" />
      <code>
        var order = spooler.create_order();
        <br clear="none" />
        var params = spooler.create_variable_set();
        <br clear="none" />
        params.set_var("color",   "green");
        <br clear="none" />
        params.set_var("message", "ok, confirmed by administrator");
        <br clear="none" />
        order.payload = params;
        <br clear="none" />
        spooler.job_chain("hobbit_messages").add_order(order);
      </code>
      <br clear="none" />
      <br clear="none" />
      <br clear="none" />
      Ergänzend zu diesen Lösungen können Sie den Job Scheduler überwachen,
      indem Sie wiederholte HTTP polling requests im Hobbit Server konfigurieren.
      Der Job Scheduler enthält einen eingebauten Web Server,
      der über die Adresse http://
      <em>host</em>
      :
      <em>port</em>
      angesprochen wird.
    </div>
  </documentation>
  <documentation language="en">
    <div xmlns="http://www.w3.org/1999/xhtml">
      This job is used as a standalone solution to check the Job Scheduler log files
      and send status messages to a Hobbit server. 
      Hobbit is an open source network monitoring solution that is maintained at
      <a href="http://hobbitmon.sourceforge.net" target="_blank" shape="rect">http://hobbitmon.sourceforge.net</a>
      .
      <br clear="none" />
      <br clear="none" />
      This job is used to check the results of all jobs that have been executed by the Job Scheduler and 
      to report their respective status messages. 
      This means that it is not necessary to check e-mails in order to see whether a job error has occurred.
      Instead, the Hobbit web interface can be used to check for errors and warnings.
      <br clear="none" />
      <br clear="none" />
      No Hobbit client installation is required as all status messages are sent to the Hobbit server using HTTP posts.
      Note, however, that the 
      <em>bbmessage.cgi</em> 
      script must be 
      activated in the Hobbit server installation
      and that it must accept HTTP posts from the server on which the Job Scheduler is operating - 
      see the 
      <em>url</em> 
      job parameter for details.
      <br clear="none" />
      <br clear="none" />
      This job implementation takes account of the Job Scheduler's log file rotation.
      No performance penalties are imposed for large log files as this job uses
      file pointers to read entries that have been appended to the Job Scheduler log file
      between two job starts.
      It is important that the lifetime of status messages is set 
      to comply with the maximum message validity in the Hobbit configuration.
      <br clear="none" />
      <br clear="none" />
      This job stores messages and sends them repeatedly in order to retain
      the warnings and errors in the Hobbit web interface throughout repeated job starts.
      An administrator has to reset messages on error states: a second job could be set up 
      with this implementation und the parameter
      <code>type</code>
      configured with the value
      <em>reset</em>
      .
      Starting this second job will then reset all messages on error states.
      If this behavior is not desired, then the 
      <code>persistent</code>
      parameter of this job could be set to 
      <em>false</em>.
      This will cause every message to be sent only once.
      <br clear="none" />
      <br clear="none" />
      As a standalone solution this job should run repeatedly, e.g. every 5 minutes,
      in order that job execution results appear quickly in the Hobbit web interface.
      This job sends
      <em>green</em>
      status messages if no problems are reported.
      It repeatedly sends
      warnings (
      <em>yellow</em>
      ) and errors (
      <em>red</em>
      ) as it is up to the administrators to decide if an error condition has changed
      or if a warning should be ignored.
      <br clear="none" />
      <br clear="none" />
      <br clear="none" />
      As an alternative scenario to using the standalone solution,
      this job could be run in a job chain.
      Orders would then be added to this job chain should errors or warnings be reported.
      This is useful if jobs are implemented using the Job Scheduler API and 
      errors are to be reported quickly with individual message content.
      <br clear="none" />
      <br clear="none" />
      A second job could be easily created that sends an order for a
      <em>green</em>
      status message to this job and would be launched by an administrator.
      This order would signalize the end of an error condition, e.g. with JavaScript:
      <br clear="none" />
      <br clear="none" />
      <code>
        var order = spooler.create_order();
        <br clear="none" />
        var params = spooler.create_variable_set();
        <br clear="none" />
        params.set_var("color",   "green");
        <br clear="none" />
        params.set_var("message", "ok, confirmed by administrator");
        <br clear="none" />
        order.payload = params;
        <br clear="none" />
        spooler.job_chain("hobbit_messages").add_order(order);
      </code>
      <br clear="none" />
      <br clear="none" />
      <br clear="none" />
      In addition to these solutions the Job Scheduler can be monitored by configuring
      repeated HTTP polling requests in the Hobbit server.
      These requests would be answered by the Job Scheduler's own web server that can be addressed by http://
      <em>host</em>
      :
      <em>port</em>
      .
    </div>
  </documentation>
</description>

