Publish to Billings.

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

Billings Exchange Format.

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.projectCode	String	The project code. This is the simplest field to use to associate estimate slips to an existing 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
owner.name	String	Full name of the person doing the work
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
project.projectCode	String	The project code. This is the simplest field to use to associate workings slips to an existing project
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
owner.name	String	Full name of the person doing the work
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)

Changes in 3.0 (since 2.5)

There are 3 changes to the format:

Updates are non-destructive now. If you update from a .bex file and if the slip/project already exists, then only blank fields will be updated and new items will be added. For example, an existing slip with new time entries. The old information will be untouched, but the new entries will be added.
owner.name has been added both EstimateSlip and TimeSlip. owner.name should be a full name. If that full does not exist, it will be created and added to the Worker Names list (see Preferences -> Labels).
project.projectCode has been added EstimateSlip and TimeSlip. In the past, you had to have the exact project info and client info to match projects when sending from one Billings to another and that was difficult. Now all you need is the project code to match.