Developer Setup Guide

Install Development Tools

Chocolately is a package manager for windows applications. It is a handy tool for getting common applications installed and keeping them current on your developer machine. We will be using it to install most Agent requirements.

Install Chocolately

From an administrative cmd.exe command prompt execute the following.

@powershell -NoProfile -ExecutionPolicy unrestricted -Command "iex ((new-object net.webclient).DownloadString('https://chocolatey.org/install.ps1'))" && SET PATH=%PATH%;%ALLUSERSPROFILE%\chocolatey\bin

From the same shell now you should be able to run Chocolately install commands.

Add packages required by Agent 5

These packages are required for doing Agent 5 development.

choco install ruby
choco install git

Handy package to have for zip file handling.

choco install 7zip

It is also handy to add browsers you'll be developing with. You should at least update IE to 10 or 11 as Visual Studio 2013 is happier with those versions installed.

choco install ie11
choco install GoogleChrome
choco install Firefox

Install Node.js

Go to https://nodejs.org/ and download the latest LTS (different from "Stable") installer. Run it to install Node.js.

Install Required IIS Features

Windows Authentication

If you plan on using Windows Authentication (Active Directory integration) you'll need to configure IIS for this.

Under World Wide Web Services open Security and select Windows Authorization

Install Dovetail SDK

Download and run the installer for your platform from Dovetail Support.

Install Dovetail Admin

Install Dovetail Seeker

Agent will not work properly without Dovetail's search product Dovetail Seeker as many object pickers are really using search under the hood.

Add MSMQ Support

Install Seeker

It may take a little while for your search index to get created after starting the indexing service.

Install Schema Editor

Install Visual Studio

I installed Visual Studio 2013 With Update 2 from MSDN. I unselected all options but web development. Sit back. This install takes a long time.

Maybe you can get some other install tasks done in the meanwhile.

Using Chocolately to install Visual Studio

Another way to get Visual Studio installed is to use Chocolately. You only need to edit this command line with your Product Key

choco install VisualStudio2013Professional -InstallArguments "/Features:'WebTools SQL' /ProductKey:{ProductKey}"

If you need to find the package name for a different SKU of Visual Studio 2013 try the Chocolately Gallery.

F# Tools

Our acceptance tests use a newer version of the F# tools than come with Visual Studio.

Install F# 3.1.1 tools

Building Agent from source code

You are done installing a lot of software and now we are ready to work with Agent 5.

Get the source

Setup your development database

You can manually apply schema changes and import data files. If you like.

Because during development these things can change a lot we have provided automation which will apply schema changes and data to your development database. You will need to do this before your application will build or run properly.

This automation uses our products Dovetail SchemaEditor and Archive Manager (Diet) to apply schema changes and import data files. Both applications are licensed products, and require a license file or key to function.

Edit Developer Configuration settings

Default database and typical application settings are sourced from configuration files in the /config directory.

Database settings

Open ./config/app{db}Settings.rb for your desired database platform in your favorite editor.

Notice how the database variables get used to build a connection string. These variables are used in other scripts so be sure to setup all the DATABASE variables do not just edit the DATABASE_CONNECTION.

Database platform and other settings

Open ./config/appSettings.rb and ensure the correct database platform is selected. Also make sure the other settings are as you like.

How are these settings used?

Database and common development centric application settings are controlled with these .rb files. rake setup:* and rake package:* tasks will use these settings to update the application configuration settings.

Diet license

Edit the DIET_LICENSE variable to have the correct ArchiveManager (Diet) license.

If you do not wish to put this license in your source code repository you can alternatively set an environment variable DIET_LICENSE with the correct key.

Other configuration

Please ensure the SEEKER_URL is set to where your Dovetail Seeker web service is installed.

Also ensure that your ATTACHMENT_PATH is correct if you are sharing a development database across users this maybe a UNC windows share.

Seeker Agent specifications

There are a few Seeker document specification XML fragments in the directory config/seeker.config which need to be applied to your Seeker document specification.

We have automation which will do this for you when Seeker is installed locally.

rake setup:switch_seeker

Finally

We are done making sure all the configuration is set. It is time to setup your development database.

rake setup:db

Building Agent from the command line

There are steps to build Agent that need occur outside of Visual Studio. This is handled using Rake.

Build Dependencies

Our source code has a few different package manager dependencies integrated with the build.

These dependencies are are retrieved at build time and are all automated.

Dovetail Nugets

Agent source projects take dependencies on non-public Nugets. These non-public Nugets are released to a private feed to which your organization will receive a unique private URL. You need to update the file ripple.config to use this feed.

Private Feed URL

To obtain your private Nuget feed URL login into our support website. The support home page should have a Nuget Feed entry under Your URLs. If you do not see this entry please create a support case and we will setup a private feed for your organization.

Edit ripple.config

Once you have obtained your private Nuget feed URL you need to edit ripple.config at the root of your source directory. This file contains XML. The first <Feed> element is a placeholder for your private Nuget feed.

Build and test

Invoking Rake by itself will build, and run tests for Agent 5. During your first run it will download all build dependencies mentioned above.

rake

Take it for a spin

Two ways to get the web application running.

Launch!

rake start_web

This will build a production version of the application and configure an IIS web site at http://localhost:8989.

Visual Studio

Double click on the 2012 Visual Studio solution /source/agent.sln. Make sure that the source/Web project is your "StartUp Project". If it is. The Web project will be bold in your Solution Explorer.

Hit Ctrl+F5 to build and launch the site.

To launch from Visual Studio you will need to run rake at least once first.

Frontend Development

When developing in frontend code (javascript, less, handlebars, etc.), you'll need to have npm installed in order to run a watch task that processes the files. npm is automatically installed with node.js. To run the watch task that compiles javascript:

npm run webpack -- --watch

This task must be running while doing javascript development in order to process the files correctly.

For styling, there are custom-styles.less and custom-print-styles.less files that can be used to customize the look of Agent. These are automatically compiled into the stylesheets via gulp less.

Custom Styles

Release

When you want to release Agent you'll need to do a release build. This will concatenate, minimize, build, test and setup a web site at http://localhost:8989 with a release ready version of Agent.

release.bat

The release artifacts can be found in the results directory.

Logging

Logging is configured in the agent.log4net file. The defaults should be fine. The logging library Log4net is very flexible and has many configuration options

Customization

The Dovetail Agent Developer Training Wiki is a collection of developer training pages we've created to help out Dovetail customers wishing to customize this product. The wiki is a great resource for customizing Dovetail Agent.