--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/buildframework/helium/doc/src/manual/signaling.rst Wed Oct 28 14:39:48 2009 +0000
@@ -0,0 +1,181 @@
+Configuring Signaling
+=====================
+
+Helium signaling framework offers you a simplest way to control
+failures on build flow, and provides you an easy way to get reporting on
+some crucial steps of your build.
+
+
+The configuration
+-----------------
+
+The signaling configuration is divided on three parts:
+
+ * the signalConfig: defines the signal (Depreciated - please use signalListenerConfig)
+ * the signalListenerConfig: defines the signal
+ * the signalInput: defines what to do when a signal is raised
+ * the notifierList: defines a set of notifiers
+
+signalListenerConfig
+....................
+
+This part of the configuration is not targeted to be overridden by the build manager.
+
+The following example defines a custom signal named as **customSignal**.
+The default configuration must reference a default signalInput configuration using a nested inputRef element,
+so the signaling framework knows how to behave when a signal is raised.
+
+.. code-block:: xml
+
+ <hlm:signalListenerConfig id="customSignal" target="target-name" message="target-name triggered a signal">
+ <signalNotifierInput>
+ <signalInput refid="signalInputId" />
+ <notifierInput file="some/file/to/notify.html" />
+ </signalNotifierInput>
+ <hlm:targetCondition>
+ </available file="some-file.txt" />
+ </hlm:targetCondition>
+ </hlm:signalConfig>
+
+A signal will then be triggered each time the **target-name** completed. The signalInput will then defined how it should be handled.
+
+Other way to trigger a signal is by using the signal task:
+
+.. code-block:: xml
+
+ <hlm:signal name="customSignal" result="1">
+ <signalNotifierInput>
+ <signalInput refid="signalInputId" />
+ <notifierInput file="some/file/to/notify.html" />
+ </signalNotifierInput>
+ </hlm:signal>
+
+
+signalInput
+...........
+
+This Ant type defines what a signal should do when it is raised. The failbuild attribute defines
+if a build failure should be:
+
+ * failing the build now (value: now)
+ * deferred at the end of the build (value: defer)
+ * ignored (value: never)
+
+Then the configuration will accept a reference to a notifierList using the notifierListRef element.
+
+Example of configurations
+
+.. code-block:: xml
+
+ <hlm:signalInput id="customSignalInput" failbuild="now">
+ <hlm:notifierListRef refid="customNotifier" />
+ </hlm:signalInput>
+
+This will run all notifier from the customNotifier configuration then fail the build.
+
+.. code-block:: xml
+
+ <hlm:signalInput id="customSignalInput" failbuild="defer"/>
+
+This will defer the failure at the end of the build, no notifier will be run.
+
+notifierList
+............
+
+The notifierList Ant type allows the user to configure a set of Notifier (e.g Email, execute task):
+
+The following example configures a notifier list that will send an email and run few echo task to print
+some information.
+
+.. code-block:: xml
+
+ <hlm:notifierList id="customNotifier">
+ <hlm:emailNotifier templateSrc="${helium.dir}/tools/common/templates/log/email_new.html.ftl"
+ title="[signal] ${signal.name}" smtp="smtp.server.address"
+ ldap="ldap://ldap.server.address:389"
+ notifyWhen="always"/>
+ <hlm:executeTaskNotifier>
+ <echo>defaultSignalAlwaysNotifier: Signal: ${signal.name}</echo>
+ <echo>defaultSignalAlwaysNotifier: Status: ${signal.status}</echo>
+ </hlm:executeTaskNotifier>
+ </hlm:notifierList>
+
+Detailed documentation of the notifier interface could be found `here <../../helium-antlib/index.html>`_.
+
+
+Example: configuring compileSignal
+----------------------------------
+
+In this example we will configure the compileSignal to behave this way:
+
+ * send an email to additional users e.g: user@foo.com, user@bar.com
+ * defer the build failure.
+
+You configuration should contains (e.g build.xml)
+
+.. code-block:: xml
+
+ <?xml version="1.0"?>
+ <project name="mybuild">
+ ...
+ <import file="${helium.dir}/helium.ant.xml"/>
+ ...
+
+ <hlm:notifierList id="myCustomNotifierList">
+ <hlm:emailNotifier templateSrc="${helium.dir}/tools/common/templates/log/email_new.html.ftl"
+ title="[signal] My build goes wrong: ${signal.name}"
+ smtp="${email.smtp.server}"
+ ldap="${email.ldap.server}"
+ notifyWhen="fail"
+ additionalrecipients="user@foo.com,user@bar.com"/>
+ </hlm:notifierList>
+
+ <hlm:signalInput id="compileSignalInput" failbuild="defer">
+ <hlm:notifierListRef refid="myCustomNotifierList" />
+ </hlm:signalInput>
+
+ </project>
+
+
+A custom notifierList has been created with **myCustomNotifierList** as reference ID. It defines
+a emailNotifier which uses the default email template under Helium (${helium.dir}/tools/common/templates/log/email_new.html.ftl).
+It also set the title of you email to be "[signal] My build goes wrong: ${signal.name}" (signal.name property will be replace by the signal name raised).
+**notifyWhen** attribute will make the notifier to send a notification only on build failure.
+Finally the two additional email addresses will be set using the **additionalrecipients** attribute.
+
+We then need to link the signal configuration and our custom the notifier list. The signalInput element is use to achieve that.
+It must be defined using the same reference ID (see reference overriding howto) as the one in the Helium configuration, the naming convention for this is: **<signal_name>Input**.
+Its **failbuild** attribute is set to **defer** which will configure the build to keepgoing, and fail at the end of the build flow.
+Finally an embedded notifierListRef element will reference our custom notifier list: **myCustomNotifierList**.
+
+While failing the signaling framework will execute all notifier defined and then store internally the build failure so it can raise it again at the end of the execution.
+
+
+Example: Report specific errors not included by default
+-------------------------------------------------------
+
+Target prep-work-area has extra log extraction added and output xml is read by a new signal.
+
+.. code-block:: xml
+
+ <hlm:signalInput id="prepWorkAreaSignalInputWarn" failbuild="defer">
+ <hlm:notifierListRef refid="defaultSignalFailNotifier" />
+ </hlm:signalInput>
+
+ <hlm:signalListenerConfig id="prepWorkAreaSignalWarn">
+ <signalNotifierInput>
+ <signalInput refid="prepWorkAreaSignalInputWarn" />
+ <notifierInput file="${build.log.dir}/${build.id}_ccm_get_input.log2.xml" />
+ </signalNotifierInput>
+ <hlm:targetCondition name="prep-work-area" message="Warnings happened during Preparing Work Area">
+ <hlm:hasSeverity severity="error" file="${build.log.dir}/${build.id}_ccm_get_input.log2.xml"/>
+ </hlm:targetCondition>
+ </hlm:signalListenerConfig>
+
+ <target name="prep-work-area" depends="ccmgetinput.prep-work-area">
+ <hlm:logextract file="${build.log.dir}/${build.id}_ccm_get_input.log" outputfile="${build.log.dir}/${build.id}_ccm_get_input.log2.xml">
+ <logfilterset>
+ <logfilter category="error" regex=".*Explicitly specified but not included" />
+ </logfilterset>
+ </hlm:logextract>
+ </target>