Quick Start Guide

This guide will demonstrate how to quickly get up and running with fbapi4j. This guide assumes that you have already downloaded fbapij, and included the JAR file and dependencies on your classpath. Of course, it also assumes that you already have an active FogBugz account.

Configuring fbapi4j

The easiest way to configure fbapi4j is to put a file at the root of your project named fbapi4j.properties. This file should contain these properties: 

endpoint=THE URL OF YOUR FOGBUGZ INSTALLATION
email=THE EMAIL ADDRESS OF THE FOGBUGZ ACCOUNT TO SUBMIT BUGS ON BEHALF OF 
password=THE PASSWORD FOR YOUR FOGBUGZ ACCOUNT

Example: 

endpoint=https://binarypizza.fogbugz.com
email=michael@binarypizza.com
password=mommasboy

With that file created, you can then instantiate and load the configuration file like this: 

import com.fieldexpert.fbapi4j.Configuration;

public class QuickStartDemo {
	public static void main(String[] args) {
		Configuration conf = new Configuration().configure();
	}
}

Alternatively, if you'd like to use a different properties file, you could load it like this: 

import com.fieldexpert.fbapi4j.Configuration;

public class QuickStartDemo {
	public static void main(String[] args) {
		Configuration conf = new Configuration().configure("config/fb.properties");
	}
}

Or, you could do without a properties file altogether, and specify your settings directly in Java: 

import com.fieldexpert.fbapi4j.Configuration;

public class QuickStartDemo {
	public static void main(String[] args) {
		Configuration conf = new Configuration();
		conf.setProperty("endpoint", "https://binarypizza.fogbugz.com");
		conf.setProperty("email", "michael@binarypizza.com");
		conf.setProperty("password", "mommasboy");
	}
}

Submitting a Case

After loading the configuration, start a new FogBugz Session, and then submit a new case with that session. 

import com.fieldexpert.fbapi4j.Case;
import com.fieldexpert.fbapi4j.Configuration;
import com.fieldexpert.fbapi4j.Session;

public class QuickStartDemo {
	public static void main(String[] args) {
		Configuration conf = new Configuration().configure();
		Session session = conf.buildSession();

		String project = "Online Ordering";
		String area = "Shopping Cart";
		String title = "Problem with Pepperoni Toppings";
		String description = "When customers add pepperoni as a topping " + 
			"the system throws an IllegalToppingException.";

		Case bug = new Case(project, area, title, description);		
		
		session.scout(bug);
		session.close();
	}
}

In the example above, session.scout(bug) will submit the case to FogBugz. If a matching case already exists, the scout method will append to the existing case rather than build a new one.

Submitting a Case Programmatically

In the previous example, the bug description was hard-coded into the Java for demonstration purposes. More realistically, you'll probably want to generate your cases dynamically when exceptions occur in your code, like this: 

package com.fieldexpert.fbapi4j.demo;

import com.fieldexpert.fbapi4j.Case;
import com.fieldexpert.fbapi4j.Configuration;
import com.fieldexpert.fbapi4j.DefaultCaseBuilder;
import com.fieldexpert.fbapi4j.Session;

public class QuickStartDemo {
	public static void main(String[] args) {

		Configuration conf = new Configuration().configure();
		Session session = conf.buildSession();
		String project = "Online Ordering";
		String area = "Shopping Cart";
		DefaultCaseBuilder caseBuilder = new DefaultCaseBuilder(project, area);
		
		try {
			buildPizza();
		} catch (Throwable e) {
			Case bug = caseBuilder.build(e);
			session.scout(bug);
		} finally {
			session.close();
		}
	}
	
	public static void buildPizza() {
		// imagine code here
		throw new RuntimeException("Sorry, we're out of pepperoni.");
		// imagine code here
	}
}

In the above example, the DefaultCaseBuilder will automatically turn the exception into a FogBugz case. The case will have a text attachment that contains the stacktrace.

Attaching a File to a FogBugz Case

Let's imagine you have a file named "screenshot.png" located in a subdirectory named "images". You could attach it to a new case like this: 

Case bug = new Case(project, area, title, description).attach(new File("images/screenshot.png"));

Here's another way of doing the same thing. This time we'll attach an excel spreadsheet, located in the current directory: 

Case bug = new Case(project, area, title, description);
Attachment att = new Attachment("report.xls","application/vnd.ms-excel", new FileInputStream("report.xls"));
bug.attach(att);

Or, if you'd like to attach a file that doesn't actually exist on the local filesystem, you can do that like this: 

Case bug = new Case(project, area, title, description);
bug.attach("attachment.txt","text/plain","This is the contents of a non-existent local file.");

Modifying an Existing FogBugz Case

package com.fieldexpert.fbapi4j.demo;

import java.io.File;
import java.util.Date;

import com.fieldexpert.fbapi4j.Case;
import com.fieldexpert.fbapi4j.Configuration;
import com.fieldexpert.fbapi4j.Session;

public class QuickStartDemo {
	public static void main(String[] args) {
		Configuration conf = new Configuration().configure();
		Session session = conf.buildSession();

		Case fbCase = session.get(Case.class, 1234);
		fbCase.setDescription("Some new description");
		fbCase.setTags("Tag 1", "Tag 3");
		fbCase.setHoursEstimate(2);
		fbCase.setPriority(7);
		fbCase.setDueDate(new Date());
		fbCase.setArea("Some Area");
		fbCase.attach(new File("screenshot.jpg"));
		fbCase.setAssignedTo("nathan@binarypizza.com");
		
		Case parent = session.get(Case.class, 1000);
		fbCase.setParent(parent);
		session.edit(fbCase);		
		
		session.close();
	}
}

Querying all FogBugz Users

package com.fieldexpert.fbapi4j.demo;

import com.fieldexpert.fbapi4j.Configuration;
import com.fieldexpert.fbapi4j.Person;
import com.fieldexpert.fbapi4j.Session;

public class QuickStartDemo {
	public static void main(String[] args) {
		Configuration conf = new Configuration().configure();
		Session session = conf.buildSession();

		for (Person p : session.findAll(Person.class)) {
			System.out.println(p.getId() + " -> " + p.getFullname());
		}

		session.close();	
	}
}

Querying a Specific FogBugz User

package com.fieldexpert.fbapi4j.demo;

import com.fieldexpert.fbapi4j.Configuration;
import com.fieldexpert.fbapi4j.Person;
import com.fieldexpert.fbapi4j.Session;

public class QuickStartDemo {
	public static void main(String[] args) {
		Configuration conf = new Configuration().configure();
		Session session = conf.buildSession();

		// You can find somebody by their id:
		int personId = 5;
		Person person = session.get(Person.class, personId);
		System.out.println(person.getFullname());

		// Or you can find them by their email address:
		person = session.get(Person.class, "joe@binarypizza.com");
		System.out.println(person.getFullname());

		session.close();	
	}
}