My book recommendations

Using the Jenkins Job dashboard widget – Part three

kj187_Dashboard_2_i4wkw6The Jenkins Job widget is a generic widget for Jenkins, which provides a highly visible view of the build status and build progress of selected Jenkins jobs.

In this part I will show you, how you could add these widget to our new custom dashboard.


This post is part of a series called “Building an awesome dashboard“. We’re going to create a custom dashboard with multiple different widgets from scratch. It will be a six-part series, and this is the third part.

Part One: Prerequisites for building an awesome dashboard
Part Two:
Create a custom dashboard
Part Three: Using the Jenkins Job widget
Part Four: Using the TargetProcess widgets
Part Five: Using the GitHub PullRequest widget
Part Six: Using the Meeting Reminder widget

Requirements

The Jenkins Job widget has a few dependencies to some NPM packages. To get all this dependencies on a easy way, you have to add the following to your dependencies block in the package.json file:

"jenkins-api": "0.2.x",
"cron": "1.1.x",
"moment": "2.4.x",
"memory-cache": "0.1.x",
"request": "2.72.x",

The whole file should be looking now like:

{
  "name": "dashboard_testproject",
  "description": "dashboard_testproject",
  "author": "<Put your name here>",
  "version": "0.0.1",
  "private": true,
  "dependencies": {
    "dashing-js": "~0.1.5",
    "jenkins-api": "0.2.x", 
    "cron": "1.1.x", 
    "moment": "2.4.x",
    "memory-cache": "0.1.x",
    "request": "2.72.x",
  },
  "engine": "node >= 0.10"
}

Alright, as we know from the basic setup, we have to install all these dependencies now. Make sure you are inside the project directory and call the NPM install command:

$ cd /var/www/dashing/dashboard_testproject
$ sudo npm install

You could also add the argument -g to install these modules globally. Otherwise they will be stored into a subdirectory “node_modules” which should be looking like the following now:

├── node_modules
│   ├── cron
│   ├── dashing-js
│   ├── jenkins-api
│   ├── memory-cache
│   ├── moment
│   └── request

Installation

It`s time to install the Jenkins Job widget now. Execute the following command and make sure you are inside the project directory:

$ cd /var/www/dashing/dashboard_testproject
$ dashing-js install https://github.com/kj187/dashing-jenkins_job/archive/master.zip

You will get the following output:

Installing zip "https://github.com/kj187/dashing-jenkins_job/archive/master.zip"
      create  widgets/dashing-jenkins_job-master/
      create  widgets/dashing-jenkins_job-master/README.md
      create  widgets/dashing-jenkins_job-master/config.jenkins_job.sample.js
      create  widgets/dashing-jenkins_job-master/jenkins_job.coffee
      create  widgets/dashing-jenkins_job-master/jenkins_job.html
      create  jobs/jenkins_job.job.js
      create  widgets/dashing-jenkins_job-master/jenkins_job.scss
      move    widgets/dashing-jenkins_job-master/ -> widgets/jenkins_job

Create a new directory “config” in the current project root directory and move the widget/jenkins_job/config.jenkins_job.sample.js file to this new directory and rename it to config.jenkins_job.js:

$ mkdir config
$ cp widgets/dashing-jenkins_job/config.jenkins_job.sample.js config/config.jenkins_job.js

The result:

├── assets
│   └── ...
├── config
│   └── config.jenkins_job.js
├── dashboards
└── ...

For the progressbar visualization we use jQueryUI, so we need the jQueryUI styles and javascript library. In this case it is totally ok if we use the CDN files for that.

Add the following lines to your global layout file “dashboards/layout.ejs” in front of the closing head tag:

<script type="text/javascript" src="//cdnjs.cloudflare.com/ajax/libs/jqueryui/1.11.4/jquery-ui.min.js"></script>
<link rel="stylesheet" href="//cdnjs.cloudflare.com/ajax/libs/jqueryui/1.11.4/jquery-ui.min.css">

Or if you use Jade as your favorite template engine, use the following instead:

script(src='//cdnjs.cloudflare.com/ajax/libs/jqueryui/1.11.4/jquery-ui.min.js')
link(rel='stylesheet', href='//cdnjs.cloudflare.com/ajax/libs/jqueryui/1.11.4/jquery-ui.min.css')

Configuration

To actually use the widget on your own Dashboard, you’ll have to have an access token from your Jenkins server. If you don`t have an access token you can also use your username and password.

Open config/config.jenkins_job.js and adjust the Jenkins settings in line 5-7:

username: 'YOUR_JENKINS_USERNAME',
token: 'YOUR_JENKINS_ACCESS_TOKEN_OR_PLAINTEXT_PASSWORD',
host: 'YOUR_JENKINS_HOST',

To simplify things, delete the jobs array and replace it with:

jobs: [
    {
        id: 'build',
        displayName: 'Build',
        eventName: 'build',
        cronInterval: '*/5 * * * * *',
        apiMethod: 'last_build_info',

        displayArguments: {
            title_isEnabled: true,
            buildNumber_isEnabled: true,
            timeAgo_isEnabled: true,
            branch_isEnabled: true,
            displayDuration_isEnabled: true
        }
    }
]

The “id” must be exactly the same as your Jenkins job projectname. In my case, the Jenkins job I use, is named “build”. Alright, let’s don’t waste time with explaining the other settings. Some of them will be explained in the Usage part below and some of them should be self-explained.

Usage

To include the widget on our dashboard, add the following snippet to our new demo dashboard file (dashboards/demo.ejs), or better, replace it with our sole empty dummy widget:

<li data-row="1" data-col="1" data-sizex="1" data-sizey="1" class="widget-jenkins_job">
  <div data-id="build" data-view="JenkinsJob" data-bind-class="result | append additionalclass" data-additionalclass=" widget"></div>
  <i class="fa fa-archive icon-background"></i>
</li>

The whole demo.ejs should be looking now like:

<div class="gridster">
  <ul>
    <li data-row="1" data-col="1" data-sizex="1" data-sizey="1" class="widget-jenkins_job">
      <div data-id="build" data-view="JenkinsJob" data-bind-class="result | append additionalclass" data-additionalclass=" widget"></div>
      <i class="fa fa-archive icon-background"></i>
    </li>
  </ul>
</div>
<%- contentFor('title') %>
My dashboard title

Or again, if you use Jade as your favorite template engine:

li(data-row='1', data-col='1', data-sizex='1', data-sizey='1', class='widget-jenkins_job')
  div(data-id='build', data-view='JenkinsJob', data-bind-class='result | append additionalclass', data-additionalclass=' widget')
  i(class='fa fa-archive icon-background')

The data-id attribute must be the same as our “eventName” setting in our config file. You can rename it, but keep in mind that both must be the same and it should be unique, otherwise some strange problems could occur.

At this point we should be able to see the widget already. Restart DashingJS and reload your browser (http://127.0.0.1:3030)

And, do you see it? If not, take a look to your shell if DashingJS has some problems. Otherwise, please make sure that your Jenkins server is available and you are using the correct protocol in your config file. If you have still problems, please let me know and write me a comment below.

Otherwise I will refer you to the official documention. You will find explanations to all single settings and you will get some nice help to optimize your layout with half sized widgets or a list style with multiple widgets.

Share on FacebookShare on Google+Tweet about this on TwitterShare on LinkedIn
  • Pingback: Create a custom dashboard – Part Two – Julian Kleinhans()

  • alexandre c deville

    hi Julian,
    i’m getting the following error :
    using npm version 1.4.21 on redhat 6.6
    node -v
    v0.10.30

    /var/www/dashing/dashboard_testproject]# dashing-js install https://github.com/kj187/dashing-jenkins_job/archive/master.zip
    Installing zip “https://github.com/kj187/dashing-jenkins_job/archive/master.zip”

    stream.js:94
    throw er; // Unhandled stream error in pipe.
    ^
    Error: UNABLE_TO_VERIFY_LEAF_SIGNATURE
    at SecurePair. (tls.js:1367:32)
    at SecurePair.emit (events.js:92:17)
    at SecurePair.maybeInitFinished (tls.js:979:10)
    at CleartextStream.read [as _read] (tls.js:471:13)
    at CleartextStream.Readable.read (_stream_readable.js:340:10)
    at EncryptedStream.write [as _write] (tls.js:368:25)
    at doWrite (_stream_writable.js:225:10)
    at writeOrBuffer (_stream_writable.js:215:5)
    at EncryptedStream.Writable.write (_stream_writable.js:182:11)
    at write (_stream_readable.js:601:24)

    • alexandre c deville

      don’t bother it is a SSL issue, i did a wget on your URL & copy the master.zip to an internal webserver to go around the ssl issue.

  • kfh222

    Well, I finally got around to looking at this, and now I’ve got it working! Nice!

    Thanks Julian.

    BTW, let me point out how important the word “move” is in “..move the widget/jenkins_job/config.jenkins_job.sample.js file..”. I copied it instead, and let me tell you, that really doesn’t work!

    -Kelly

    • kfh222

      Julian, I’d be interested in a post that went step by step how to add a new Jenkins job result parameter to the widget. For instance, if I have a job that runs junit tests, and I have a junit results publish step, I’d be interested in showing the passCount, skipCount, and failCount values that are available on the testReport part of the results.

      I can see that it’s doable, but I haven’t figured it out yet.

      Thanks,
      Kelly

  • Igor Sarkisov

    We have multiple jenkins servers, is it possible to somehow configure this plugin to display widgets from different jenkins servers?

  • No unfortunately not per default. But maybe with some code changes

  • Ramkumar D

    Part 1 and Part 2 worked fine seamlessly. But Part 3 (jenkins dashboard) is not working at all. I followed the steps correctly. I am getting widgets with grey color and without any contents.

    • GCS

      What did you do to fix it? I have the same issue and cannot figure out what could be the problem.

      • Ramkumar D

        In the test server it was not working, but in production machine it worked fine and also I removed this file widgets/dashing-jenkins_job/config.jenkins_job.sample.js after having correct file under config directory. Basically you should move the above file to config directory instead of copy.

  • Igor Sarkisov

    I am getting errors trying to install dashing-js, same as here: https://github.com/kj187/dashing-jenkins_job/issues/4

    I tried on OS X, Ubuntu 16, and SLES 12.1

  • Martin Dřimi Dřímal

    Hi, very nice dashboard of widgets. Thanks for sharing. I have a small
    problem with displaying duration of jobs. I set parameter
    displayDuration_isEnabled to true, but duration is not displayed. Color
    of widget is correctly changed to turquoise color when job is performed.
    But no duration of job is visible. I’m using jenkins of version Jenkins
    ver. 1.651.3. Can you give me advise please? Thank you.

  • Ramkumar D

    Shall we have these files locally?