1. Home
  2. Language Guides
  3. Coldfusion
  4. Crash Reporting
  5. Installation

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)

Step 1 - Installation

To get the latest from the master repository:

box install raygun4cfml

To install a specific release or tag:

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

Example tag names are 1.2.0, 1.2.1 etc. Please check the list of tags on Github.
We recommend using the latest tag. Versions below 1.2.0 do not support Commandbox/Forgebox.

To manually install the Raygun4CFML library, you have two options:

  • 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'.

  • 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'.

Note: Manual installation will not fulfill any necessary dependencies.

Step 2 - Configuration

The /src directory 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 = "paste_your_api_key_here"
);

  • 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 directory 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 = "paste_your_api_key_here"
);

/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 and more samples as well as a structure (but no tests at this stage) for Testbox unit and BDD tests.

For further details on library organisation and instantiation, please see our documentation.

Deploy Raygun into your production environment for best results, or raise a test exception. Once we detect your first error event, the Raygun app will automatically update.

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.

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 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 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);

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.

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);

The provider is open source and available at the Raygun4cfml repository.

On this page: