Installation

Raygun4cfml is a library that you can add to your ColdFusion/CFML application. Once installed it will transmit all exceptions to your Raygun dashboard. Installation only takes a few minutes so you can start receiving error and crash reports right away.

Supported CFML engines:

• Adobe ColdFusion 9+
• Railo 4.0+
• Lucee 4.5+?

Current Version: 1.1.0 (Jan 2 2016)

Dependencies:

• Testbox 2 (for running unit and BDD tests only)

Installation

Option 1 (preferred):

Use Commandbox and Forgebox to get the library and then follow the ideas outlined in 'Library organisation' for further setup.

To get the latest from the master repository

box install raygun4cfml

To install a specific release or tag:

box install git://github.com/MindscapeHQ/raygun4cfml.git#{tagname}

Example tag names are 1.1.0, 1.0.2.0, 1.0.1.0 etc. Please check the list of tags on Github. Be aware that if you install any tag from before I introduced support for Commandbox and Forgebox there won't be a box.json file and therefore Commandbox will give you a warning as well as there won't be any dependency management for such an installation of the library.

Shortcut for the above:

box install MindscapeHQ/raygun4cfml#{tagname}

To get the latest from my development repository (be warned, this might contain all sorts of untested code):

box install TheRealAgentK/raygun4cfml

Option 2:

Fork and clone the repo to your local system. Move the src/test directories into places of your choice and suitable for your system and follow the ideas outlined in 'Library organisation'.

Option 3:

Download a zip file containing the current content of the repo or a release/tag of your choice. Unzip the resulting file. Move the src/test directories into places of your choice and suitable for your system and follow the ideas outlined in 'Library organisation'.

Notes:

(1) Options 2 and 3 will not fulfill any necessary dependencies, you're on your own.

Library Organization & Instantiation

/src contains the source code. The package structure is nz.co.ventego-creative.co.nz.raygun4cfml but the library's components themselves are independent of the package path. Therefore you can use the library in multiple ways:

Put the content of /src into your webroot and instantiate RaygunClient through something like the following:

raygun = createObject("component","nz.co.ventego-creative.raygun4cfml.RaygunClient").init(
    apiKey = "YOURAPIKEYHERE"
);

Put the contents of /src into any other place of your choice and create a mapping to /nz in your server administrator or through code and then use the instantiation code as above.

Put the contents of the raygun4cfml into a place of your choice where your CFML has some sort of a mapping pointing towards and and just instantiate RaygunClient like this:

raygun = createObject("component","RaygunClient").init(
    apiKey = "YOURAPIKEYHERE"
);

/samples contains a set of files that show how the library can be used in your code through a global error handler as well as a contributed example for ColdBox 3.6

/tests contains manual tests as well as a structure (but no tests at this stage) for Testbox unit and BDD tests.

Example error handler

The following is an example for use in a global error handler template e.g cferror. It also demonstrates how you can add custom data to every message delivered to Raygun.

<cfscript>
    raygun = createObject("component","nz.co.ventego-creative.raygun4cfml.RaygunClient").init(
        apiKey = "YOURAPIKEYHERE"
    );

    result = raygun.send(error);
</cfscript>

Tags

Tags can be sent with each error like this:

tags = ["coding","db","sqlfail"];
raygun = createObject("component","nz.co.ventego-creative.raygun4cfml.RaygunClient").init(
	apiKey = variables.RAYGUNAPIKEY
);

result = raygun.send(issueDataStruct=error,tags=tags);

Custom Data

Custom data objects can be created and sent with each error:

customUserDataStruct = {"session" = {"memberID" = "5747854", "memberFirstName" = "Kai"}, "params" = {"currentAction" = "IwasDoingThis", "justAnotherParam" = "test"}};
customUserData = createObject("nz.co.ventego-creative.raygun4cfml.RaygunUserCustomData").init(customUserDataStruct);

raygun = createObject("component","nz.co.ventego-creative.raygun4cfml.RaygunClient").init(
	apiKey = variables.RAYGUNAPIKEY
);
result = raygun.send(issueDataStruct=error,userCustomData=customUserData);

User Tracking

Data for the affected user which experienced the error can be attached like this:

userIdentifier = createObject("nz.co.ventego-creative.raygun4cfml.RaygunIdentifierMessage").init(Identifier="test@test.com",isAnonymous=false,UUID="47e432fff11",FirstName="Test",Fullname="Tester");

raygun = createObject("component","nz.co.ventego-creative.raygun4cfml.RaygunClient").init(
	apiKey = variables.RAYGUNAPIKEY
);

result = raygun.send(issueDataStruct=error,user=userIdentifier);

The string properties on a User have a maximum length of 255 characters. Users who have fields that exceed this amount will not be processed.

Filtering sensitive data

You can remove sensitive data (e.g financial data or credentials) from error payloads using a content filter:

filter = [{filter = "password", replacement = "__password__"}, {filter = "creditcard", replacement = "__ccnumber__"}];
contentFilter = createObject("nz.co.ventego-creative.raygun4cfml.RaygunContentFilter").init(filter);

raygun = createObject("component","nz.co.ventego-creative.raygun4cfml.RaygunClient").init(
    apiKey =  variables.RAYGUNAPIKEY,
    contentFilter = contentFilter
);

result = raygun.send(error);