Create a Custom Export Add-on

If your answer is not here the Community Forums are your best bet.

Introduction to export add-ons

Before you get started with this guide, make sure you are running Dradis v3.0 or later (check the footer to confirm your version).
If needed, install the latest version of Dradis from Git with these instructions before moving on.


In this guide we're going to walk through the process to create a custom export add-on. An export add-on will allow you to generate a report from your Dradis project in any format you want.

In this case, we're creating a simple JSON export add-on. Our JSON exporter is going to open up a new browser tab and display all of the Issues in your project in JSON strings.


1. Clone your Add-on

The easiest way to start building is to clone one of the existing export add-ons to use as a working guide as you customize your export add-on.

Which of the available export add-ons is closest to what you're building?


To clone the add-on:

  1. Pick an export plugin from the list above to use as a template.

  2. Click the link above to open the plugin's GitHub repo.

  3. Copy the HTTPS link to clone the repo. In the example below, we're going to clone the dradis-csv repo.

  4. Back on your local system, open the terminal and navigate to the folder where you installed dradis-ce.

  5. Run the following in the terminal:

    $ git clone [repo link]

    Paste in the HTTPS link you copied from GitHub! Example:

    $ git clone https://github.com/dradis/dradis-csv.git

2. Rename your add-on

Below is an example of the file structure of a Dradis add-on. Every export add-on uses this basic file structure. If the add-on uses templates (like dradis-html_export), there will also be a templates/ folder.

Rename files and folders

On your local system, rename your folders and files. For the root folder, we recommend using the dradis-[name] naming convention where [name] is a placeholder for your exporter type (e.g. json). In the examples below, we're going to assume you're working with the dradis-csv repo.

After renaming, your filesystem should look similar to this:


3. Edit your files

Before you upload the add-on to Dradis, you're going to want to edit files and at least change the references to the old export add-on name (e.g. CSV) and change them to your new name (e.g. JSON).

The instructions below will not cover exactly how to code your specific export add-on. They are simply a high-level overview of the different files that comprise an export add-on to help you get started. This is not an exhaustive list of all of the changes you may need to make. After completing the steps below, you should be ready to start your custom coding.

Note: when the instructions say, "update all references to the old name", it means to go through the file and change things like class names to match the new syntax of your custom export add-on. For example, change csv to json and CSV to JSON). Remember: in Ruby, capitalization counts!

Start by editing the following files:

Edit depending on your add-on:

In most cases you can ignore all the following files:


4. Load the Add-on to Dradis

  1. Open up the dradis-ce folder on your local system and open file dradis-ce/Gemfile.plugins.

  2. Add a reference to your new export add-on by adding a line to the # -- Export section:

    gem 'dradis-[name]', path '../dradis-[name]'
    Example:
    gem 'dradis-json', path '../dradis-json'
    Note: make sure that your new export add-on is in the same folder as the other export add-ons on your system so that it matches the filepath you just added to Gemfile.plugins.

  3. On your local system, open the terminal and navigate to the dradis-ce folder. (Shut down Dradis if it was already running). Then run:

    $ bundle install
    $ bundle exec rails server

  4. Open Dradis in your browser and click Export results in the header. Check out the tab for your new export add-on! Depending on how much custom coding you've already done (and how much is left to do) you may be able to test out your export add-on at this point. Otherwise, continue on to the final step.

5. Test, Edit, Repeat

It's almost a guarantee that you'll be spending a lot of time at this step making changes to your code, running into stack traces/errors, searching Google for workarounds, and testing your exporter until it does what you need it to do. If you're this far, keep up the great work!

Remember, StackOverflow is your friend and the Dradis Community Forums are here to help.