Skip to content

Commit

Permalink
Merge pull request #44 from darxriggs/documentation-improvements
Browse files Browse the repository at this point in the history 
Documentation improvements
  • Loading branch information
Marky Jackson committed Apr 27, 2019
2 parents db76ca6 + 731f926 commit e09213c
Show file tree
Hide file tree
Showing 6 changed files with 94 additions and 91 deletions.
35 changes: 16 additions & 19 deletions README.md
View file
@@ -1,8 +1,6 @@


# Groovy Events Listener Plugin

A Jenkins plugin, which executes groovy code when an event occurs.
A Jenkins plugin, which executes Groovy code when an event occurs.

Table of contents
---
Expand Down Expand Up @@ -37,7 +35,7 @@ So I wrote this plugin. Along the way, I realised it could have some other appli
- performance monitoring
- incident escalation
- integration with 3rd party applications
- ???
- much more...

Building
---
Expand Down Expand Up @@ -91,41 +89,41 @@ So lets get started with the simplest example.
log.info "hello world!"
```

Now save the changes, kick off a Jenkins job, and you will see "hello world!" written to the logs three times. Alternatively,
Now save the changes, kick off a Jenkins job, and you will see "hello world!" written to the logs three times. Alternatively,
there's now a `Test Groovy Code` button, which will execute the code with the `event`=`RunListener.onStarted`.

The plugin actually injects a couple of variables, which you can use in your code. Here's some examples using the `event`
and `env` variables.

This code limits the logging to only occur when a Job is completed! **N.B.** this behaviour can also be replicated using the configuration options.
This code limits the logging to only occur when a job is completed! **N.B.** this behaviour can also be replicated using the configuration options.

```Groovy
if (event == Event.JOB_STARTED) {
log.info "hello world!"
}
```

And this one filters on Job's whose name starts with "Foobar"...
And this one filters on jobs whose name starts with "Foobar":

```Groovy
if (env.JOB_NAME.startsWith('Foobar')) {
log.info "hello world!"
}
```

There's also a `context` Map variable. You can add your own variables to this Map, by returning a Map from your code.
There is also a `context` variable of type `Map`. You can add your own entries to it, by returning a `Map` from your code.
E.g.

```Groovy
if (event == Event.JOB_FINALIZED) {
def newCount = (context.finishCount ?: 0) + 1
log.info "hello world! finishCount=$newCount"
return ["finishCount": newCount]
return [finishCount: newCount]
}
```

This will keep a record in memory, of how many times Jobs have finished. You can also achieve the same result, by
adding variables directly to the Map variable... e.g.
This will keep a record in memory, of how many times jobs have finished. You can achieve the same result by
adding variables directly to the `context` variable:

```Groovy
if (event == Event.JOB_FINALIZED) {
Expand All @@ -134,17 +132,16 @@ if (event == Event.JOB_FINALIZED) {
}
```

You can also use `@Grab` annotations ([only where they are valid](https://issues.apache.org/jira/browse/GROOVY-6069))
if you'd like to import external dependencies (thanks [Daniel](https://github.com/CoreMedia/job-dsl-plugin/commit/830fae7a0fd8a046c620600e46633166804190e3)
for your solution!).
You can also use `@Grab` annotations if you'd like to import external dependencies
(thanks [Daniel](https://github.com/CoreMedia/job-dsl-plugin/commit/830fae7a0fd8a046c620600e46633166804190e3) for your solution!).

```Groovy
@Grab('commons-lang:commons-lang:2.4')
import org.apache.commons.lang.WordUtils
log.info "Hello ${WordUtils.capitalize('world')}!"
```

Not bad! And finally, you can import groovy scripts, so you can hide away some of the heavy lifting... here I'm using
Not bad! And finally, you can import Groovy scripts, so you can hide away some of the heavy lifting. Here I'm using
a [RestClient.groovy](src/main/site/includes/RestClient.groovy) script.

```Groovy
Expand All @@ -160,17 +157,17 @@ def resp = client.post('http://localhost:9200/jenkins/runInstances', [
assert resp.status == 201
```

You can pretty much do what ever you want from here... custom logging to a file, sending performance metrics to
an elastic server, sending email or messenger notifications, calling a SOAP service... the world's your oyster. If
You can pretty much do whatever you want from here: custom logging to a file, sending performance metrics to
a server, sending email or messenger notifications, calling a SOAP service... The world's your oyster. If
you've got something cool that you want to share, let me know and I'll add it to the [examples](src/main/site/examples)!

For more details on which events trigger the code, what variables are available and details on configuring logging,
please see the [plugin's help file](https://cdn.rawgit.com/jenkinsci/groovy-events-listener-plugin/master/src/main/resources/org/jenkinsci/plugins/globalEventsPlugin/GlobalEventsPlugin/help-onEventGroovyCode.html).
please see the plugin's [help file](https://cdn.rawgit.com/jenkinsci/groovy-events-listener-plugin/master/src/main/resources/org/jenkinsci/plugins/globalEventsPlugin/GlobalEventsPlugin/help-onEventGroovyCode.html).

Authors
---

Marky Jackson - <marky.r.jackson@gmail.comn>
Marky Jackson <marky.r.jackson@gmail.comn>

License
---
Expand Down
2 changes: 1 addition & 1 deletion src/main/resources/index.jelly
View file
@@ -1,2 +1,2 @@
<?jelly escape-by-default='true'?>
<div>A jenkins plugin, which executes groovy code when an event occurs.</div>
<div>This plugin executes Groovy code when an event occurs.</div>
21 changes: 10 additions & 11 deletions ...resources/org/jenkinsci/plugins/globalEventsPlugin/GlobalEventsPlugin/help-classPath.html
View file
@@ -1,19 +1,18 @@
<div>
If you have some complicated code and you don't want to store it in Jenkins configuration page,
you can easily extract it to groovy file, save in folder and add this folder to class path.

If you have some complicated code and you don't want to store it on the Jenkins configuration page,
you can extract it to a Groovy file, save this file in a folder and add this folder to the classpath.
After that you will be able to import this class from your code.

<p>
Example:
<pre><code>
> cd /var/lib/jenkins
> mkdir groovy_scripts
> echo "class Constants { public static final int TIMEOUT = 10; }" > groovy_scripts/Constants.groovy
> cd /var/lib/jenkins
> mkdir groovy_scripts
> echo "class Constants { public static final int TIMEOUT = 10; }" > groovy_scripts/Constants.groovy
</code></pre>

Now you cad add <code>/var/lib/jenkins/groovy_scripts</code> folder to classpath and do something like this:
<p>
Now you can add the folder <code>/var/lib/jenkins/groovy_scripts</code> to the classpath and do something like this:
<pre><code>
import Constants
log.info Constants.TIMEOUT
import Constants
log.info Constants.TIMEOUT
</code></pre>
</div>
123 changes: 65 additions & 58 deletions ...s/org/jenkinsci/plugins/globalEventsPlugin/GlobalEventsPlugin/help-onEventGroovyCode.html
View file
@@ -1,15 +1,14 @@
<div>
This plugin executes the supplied Groovy code, every time an event is triggered. You can use <code>@Grab</code>
annotations (<a href="https://issues.apache.org/jira/browse/GROOVY-6069">only where they are valid</a>) if you'd
like to import external dependencies.<br/><br/>

This plugin executes the supplied Groovy code, every time an event is triggered. You can use
<a href="http://docs.groovy-lang.org/latest/html/documentation/grape.html">@Grab</a> annotations
if you'd like to import external dependencies.
<p>
<h4 id="variables">Variables:</h4>

This plugin injects the following variables, which can be used in your Groovy code.<br/><br/>

This plugin injects the following variables, which can be used in your Groovy code.
<p>
Additionally, if you return a <code>java.util.Map</code> object, these variables will be added to the context for
any future code invocations.<br/><br/>

any future code invocations.
<p>
<table border="1" cellpadding="2px">
<thead>
<tr>
Expand All @@ -22,12 +21,11 @@ <h4 id="variables">Variables:</h4>
<tr>
<td><code>log</code></td>
<td>The plugin's logger instance.</td>
<td><a href="http://docs.oracle.com/javase/8/docs/api/java/util/logging/Logger.html">java.util.Logger</a>
</td>
<td><a href="http://docs.oracle.com/javase/8/docs/api/java/util/logging/Logger.html">java.util.Logger</a></td>
</tr>
<tr>
<td><code>context</code></td>
<td>A Map containing variables, which are persisted between code executions.</td>
<td>A map containing variables, which are persisted between code executions.</td>
<td><a href="http://docs.oracle.com/javase/8/docs/api/java/util/Map.html">java.util.Map</a></td>
</tr>
<tr>
Expand All @@ -38,32 +36,30 @@ <h4 id="variables">Variables:</h4>
<tr>
<td><code>jenkins</code></td>
<td>The Jenkins instance.</td>
<td><a href="http://javadoc.jenkins-ci.org/jenkins/model/Jenkins.html">jenkins.model.Jenkins</a></td>
<td><a href="https://javadoc.jenkins.io/jenkins/model/Jenkins.html">jenkins.model.Jenkins</a></td>
</tr>
<tr>
<td><code>env</code></td>
<td>(Optional) The EnvVars for a job instance.</td>
<td><a href="http://javadoc.jenkins-ci.org/hudson/EnvVars.html">hudson.EnvVars</a></td>
<td>(Optional) The environment variables used for a job instance.</td>
<td><a href="https://javadoc.jenkins.io/hudson/EnvVars.html">hudson.EnvVars</a></td>
</tr>
<tr>
<td><code>run</code></td>
<td>(Optional) The run object associated with this job instance.</td>
<td><a href="http://javadoc.jenkins-ci.org/hudson/model/Run.html">hudson.model.Run</a></td>
<td>(Optional) The run object associated with a job instance.</td>
<td><a href="https://javadoc.jenkins.io/hudson/model/Run.html">hudson.model.Run</a></td>
</tr>
<tr>
<td><code>listener</code></td>
<td>(Optional) The task listener associated with the job instance.</td>
<td><a href="http://javadoc.jenkins-ci.org/hudson/model/TaskListener.html">hudson.model.TaskListener</a></td>
<td>(Optional) The task listener associated with a job instance.</td>
<td><a href="https://javadoc.jenkins.io/hudson/model/TaskListener.html">hudson.model.TaskListener</a></td>
</tr>
<tr>
</tbody>
</table>
<br/><br/>

<p>
<h4 id="events">Events:</h4>

This Groovy code is executed when any of the below events occur.<br/><br/>

This Groovy code is executed when any of the below events occur.
<p>
<table border="1" cellpadding="2px">
<thead>
<tr>
Expand All @@ -88,88 +84,99 @@ <h4 id="events">Events:</h4>
<td>Called every $scheduledTime minutes.</td>
</tr>
<tr>
<th style="background:lightblue;text-align:left;" colspan="2"><code><a href="http://javadoc.jenkins-ci.org/hudson/model/listeners/RunListener.html">RunListener</a></code></th>
<th style="background:lightblue;text-align:left;" colspan="2"><code><a href="https://javadoc.jenkins.io/hudson/model/listeners/RunListener.html">RunListener</a></code></th>
</tr>
<tr>
<td><code>RunListener.onStarted</code></td>
<td>Called when a build is started (i.e. it was in the queue, and
will now start running on an executor).
</td>
<td>Called when a build is started (i.e. it was in the queue, and will now start running on an executor).</td>
</tr>
<tr>
<td><code>RunListener.onCompleted</code></td>
<td>Called after a build is completed.</td>
</tr>
<tr>
<td><code>RunListener.onFinalized</code></td>
<td>Called after a build is moved to the Run.State.COMPLETED
state.
</td>
<td>Called after a build is moved to the Run.State.COMPLETED state.</td>
</tr>
<tr>
<td><code>RunListener.onDeleted</code></td>
<td>Called right before a build is going to be deleted.</td>
</tr>
<tr>
<th style="background:lightblue;text-align:left;" colspan="2"><code><a href="http://javadoc.jenkins-ci.org/hudson/slaves/ComputerListener.html">ComputerListener</a></code></th>
<th style="background:lightblue;text-align:left;" colspan="2"><code><a href="https://javadoc.jenkins.io/hudson/slaves/ComputerListener.html">ComputerListener</a></code></th>
</tr>
<tr>
<td><code>ComputerListener.onLaunchFailure</code></td>
<td>Called when the slave agent fails to connect
</td>
<td>Called when the agent fails to connect.</td>
</tr>
<tr>
<td><code>ComputerListener.onOnline</code></td>
<td>Called when a node comes online
</td>
<td>Called when a node comes online.</td>
</tr>
<tr>
<td><code>ComputerListener.onOffline</code></td>
<td>Called when a node goes offline
</td>
<td>Called when a node goes offline.</td>
</tr>
<tr>
<td><code>ComputerListener.onTemporarilyOnline</code></td>
<td>Called when a node is marked temporarilyOnline by a user
</td>
<td>Called when a node is marked temporarilyOnline by a user.</td>
</tr>
<tr>
<td><code>ComputerListener.onTemporarilyOffline</code></td>
<td>Called when a node is marked temporarilyOffline by a user
</td>
<td>Called when a node is marked temporarilyOffline by a user.</td>
</tr>
<tr>
<th style="background:lightblue;text-align:left;" colspan="2"><code><a href="http://javadoc.jenkins-ci.org/hudson/model/queue/QueueListener.html">QueueListener</a></code></th>
<th style="background:lightblue;text-align:left;" colspan="2"><code><a href="https://javadoc.jenkins.io/hudson/model/queue/QueueListener.html">QueueListener</a></code></th>
</tr>
<tr>
<td><code>QueueListener.onEnterWaiting</code></td>
<td>Called when a job enters the queue
</td>
<td>Called when a job enters the queue.</td>
</tr>
<tr>
<td><code>QueueListener.onEnterBlocked</code></td>
<td>Called when a job isn't ready to start for some reason other than executor availability
</td>
<td>Called when a job isn't ready to start for some reason other than executor availability.</td>
</tr>
<tr>
<td><code>QueueListener.onEnterBuildable</code></td>
<td>Called when a queued job is ready to run when an executor is available
</td>
<td>Called when a queued job is ready to run when an executor is available.</td>
</tr>
<tr>
<td><code>QueueListener.onLeft</code></td>
<td>Called when a job leaves the queue after starting or being cancelled
</td>
<td>Called when a job leaves the queue after starting or being cancelled.</td>
</tr>
<tr>
<th style="background:lightblue;text-align:left;" colspan="2"><code><a href="https://javadoc.jenkins.io/hudson/model/listeners/ItemListener.html">ItemListener</a></code></th>
</tr>
<tr>
<td><code>ItemListener.onCreated</code></td>
<td>Called after a new job is created and added to Jenkins, before the initial configuration page is provided.</td>
</tr>
<tr>
<td><code>ItemListener.onCopied</code></td>
<td>Called after a new job is created by copying from an existing job.</td>
</tr>
<tr>
<td><code>ItemListener.onDeleted</code></td>
<td>Called right before a job is going to be deleted.</td>
</tr>
<tr>
<td><code>ItemListener.onRenamed</code></td>
<td>Called after a job is renamed.</td>
</tr>
<tr>
<td><code>ItemListener.onLocationChanged</code></td>
<td>Called after an item's fully-qualified location has changed.</td>
</tr>
<tr>
<td><code>ItemListener.onUpdated</code></td>
<td>Called after a job has its configuration updated.</td>
</tr>
</tbody>
</table>
<br/><br/>
<b>N.B.</b> There is also now an <a href="https://github.com/jenkinsci/groovy-events-listener-plugin/blob/master/src/main/groovy/org/jenkinsci/plugins/globalEventsPlugin/Event.java">Event class</a>
<p>
There is also an <a href="https://github.com/jenkinsci/groovy-events-listener-plugin/blob/master/src/main/groovy/org/jenkinsci/plugins/globalEventsPlugin/Event.java">Event</a> class
(automatically imported) which contains constants for all of the available event names.

<br/><br/>

<p>
<h4 id="logging">Logging:</h4>

To configure a logger, use the logging filter "<code>org.jenkinsci.plugins.globalEventsPlugin</code>".
To configure a logger for this plugin, use the logging filter <code>org.jenkinsci.plugins.globalEventsPlugin</code>.
</div>
2 changes: 1 addition & 1 deletion ...urces/org/jenkinsci/plugins/globalEventsPlugin/acceptance/Groovy Script - Runtime.feature
View file
@@ -1,6 +1,6 @@
Feature: Groovy Script - Runtime
As a developer
I want to be able to execute my groovy script
I want to be able to execute my Groovy script
So that I can have an action performed


Expand Down
2 changes: 1 addition & 1 deletion .../org/jenkinsci/plugins/globalEventsPlugin/acceptance/Groovy Script - User Testing.feature
View file
@@ -1,6 +1,6 @@
Feature: Groovy Script - User Testing
As a developer
I want to be able to test my groovy script
I want to be able to test my Groovy script
So that I get instant feedback on compilation errors/runtime errors/behaviour anomalies/etc


Expand Down

0 comments on commit e09213c

Please sign in to comment.