Billings Developer Info

As of version 2.5, you can send information from your application to Billings pretty easily. All you need is a BEX file (which is a standard plist) and a simple AppleScript command.

Composing the ".bex"

Composing the plist in a Cocoa application is pretty easy. The root of the plist is a dictionary (NSDictionary or CFDictionary) with specifies the kind of object you are sending and array (NSArray or CFArray) of dictionaries representing those objects.

Each object can have related objects. For example, if you have a dictionary representing a Project, within it, you can have an array of EstimateSlips. See tge specificiation below for all the valid keys.

Once you've composed your BEX, simply save it out and specify ".bex" as the file extension.

Maintaining updatability

The BEX supports the concept of updability. You can send a BEX with the same info and it will just update the existing record instead of creating a new. For this to work correctly, you just specify 3 keys in an object: foreignAppName, foreignAppEntityName and foreignAppImportID.

foreignAppName is your application name - ie. Daylite
foreignAppEntityName is your object class or entity - ie. MySuperDuperProjectClass
foreignAppImportID is your unique ID for that class or entity

The combination of these 3 attributes helps us identity the original record you sent so we can update it.

Example BEX files

If you need to see what an actual BEX file looks like, simple select a project in Billings and export it using the File -> Export -> Export Project... command. If you need more help, feel free to contact us and we'll be happy to help.

The AppleScript command


tell application "Billings"

	ImportBEXFile filename "the full path to the BEX file with extension .bex"

end tell

The following are the keys accepted by a BEX system. Currently the specification is at version 2.

Root Dictionary
Key	Type	Description
entityName	String	either TimeSlip, EstimateSlip or Project
objects	Array	Slips where each slip is represented as a dictionary
promptUserForClientIfNone	BOOL	[Optional] This will prompt a sheet for the user to choose a Client if no Client is provided

Project
Key	Type	Description
useNickname	Integer	Should the nickname used by default
startDate	Date	Start date
client.derivedName	String	The client’s full name
projectCode	String	Project code
poNumber	String	PO Number
objective	String	Objective of the project
nickname	String	Nickname for the project
name	String	Name of the project
extraField1	String	Extra field
extraField2	String	Extra field
extraField3	String	Extra field
extraField4	String	Extra field
dueDate	Date	Due date
completeDate	Date	Complete date
balance	Real	Balance of the project
createDate	Date	Create date
modifyDate	Date	Modify date
appliedRetainerAmt	Real	Applied retainer amount
client.clientABRef	String	The Adresss Book Reference ID
state.stateCode	Integer	State code, Active = 1001, Completed = 1002, Cancelled = 1003, Estimate = 1004
activeTimeslips	Array	An array of working slips
estimateSlips	Array	An array of estimate slips
foreignAppName	String	The name of the application this Project was imported from
foreignAppEntityName	String	The entity which the project type corresponds to in the foreign app
foreignAppImportID	String	The ID which corresponds to the ID managed in the foreign app
client.firstName	String	Client's first name
client.lastName	String	Client's last name
client.company	String	Client's company
client.email	String	Client's email

EstimateSlip
Key	Type	Description
project.name	String	Name of the project.
project.client.derivedName	String	The client name.
units	Real	The quantity for a Quantity Estimate Slip
startDateTime	Date	The start date/time
roundTime	Integer	The time to round to when calculating amount owed. ex. 15 min increments.
rate	Real	Billing rate of the slip
nature	Integer	The nature of the slip. Billable = 101, My Eyes Only = 103
name	String	The name of the slip.
mileageType	Integer	The mileage type. Miles = 0, Kilometers = 1
markup	Real	The markup on the slip as a percent.
endDateTime	Date	The end date/time.
duration	Real	Duration in Seconds. For Timed and Flat slips.
dueDate	Date	The due date/time.
distance	Real	The distance for a mileage slip measured in units specified by mileageType.
discount	Real	The discount on the slip as a percent.
createDate	Date	The create date/time.
comment	String	Comment
type.typeCode	Integer	The type of slip. Timed = 101, Flat = 102, Quantity = 103, Expense = 104, Mileage = 105
category.name	String	Name of the category.
foreignAppName	String	The name of the application this Project was imported from
foreignAppEntityName	String	The entity which the project type corresponds to in the foreign app
foreignAppImportID	String	The ID which corresponds to the ID managed in the foreign app
project.client.firstName	String	Client's first name
project.client.lastName	String	Client's last name
project.client.clientABRef	String	Client's Address Book UID
project.client.email	String	Client's email
project.client.company	String	Client's Company
project.foreignAppName	String	Foreign App Name for project
project.foreignAppEntityName	String	Foreign App Entity name for Project
project.foreignAppImportID	String	Foreign App ID for Project

TimeSlip
Key	Type	Description
project.name	String	Name of the project.
project.client.derivedName	String	The client name.
units	Real	The quantity for a Quantity Estimate Slip
startDateTime	Date	The start date/time
roundTime	Integer	The time to round to when calculating amount owed. ex. 15 min increments.
rate	Real	Billing rate of the slip
nature	Integer	The nature of the slip. Billable = 101, My Eyes Only = 103
name	String	The name of the slip.
mileageType	Integer	The mileage type. Miles = 0, Kilometers = 1
markup	Real	The markup on the slip as a percent.
endDateTime	Date	The end date/time.
dueDate	Date	The due date/time.
distance	Real	The distance for a mileage slip measured in units specified by mileageType.
discount	Real	The discount on the slip as a percent.
createDate	Date	The create date/time.
comment	String	Comment
type.typeCode	Integer	The type of slip. Timed = 101, Flat = 102, Quantity = 103, Expense = 104, Mileage = 105
category.name	String	Name of the category.
activeForTiming	Boolean	YES = 1, NO = 0
timeEntries		Array of time entries
foreignAppName	String	The name of the application this Project was imported from
foreignAppEntityName	String	The entity which the project type corresponds to in the foreign app
foreignAppImportID	String	The ID which corresponds to the ID managed in the foreign app
project.client.firstName	String	Client's first name
project.client.lastName	String	Client's last name
project.client.clientABRef	String	Client's Address Book UID
project.client.email	String	Client's email
project.client.company	String	Client's Company
project.foreignAppName	String	Foreign App Name for project
project.foreignAppEntityName	String	Foreign App Entity name for Project
project.foreignAppImportID	String	Foreign App ID for Project

TimeEntry
Key	Type	Description
startDateTime	Date	Start date/time
isManual	Boolean	Was this time entry created manually? YES = 1, NO = 0
endDateTime	Date	End date/time
createDate	Date	Create date/time
comment	String	Comment
foreignAppName	String	Foreign App Name for TimeEntry (if foreign App does not have concept of Time Entries use same value as TimeSlip)
foreignAppEntityName	String	Foreign App Entity name for TimeEntry (if foreign App does not have concept of Time Entries use same value as TimeSlip)
foreignAppImportID	String	Foreign App ID for TimeEntry (if foreign App does not have concept of Time Entries use same value as TimeSlip)