public class

FreshBooksConnector

extends Object
java.lang.Object
   ↳ org.mule.modules.freshbooks.FreshBooksConnector
Known Direct Subclasses
Known Indirect Subclasses

Class Overview

FreshBooks is an online invoicing software as a service for freelancers, small businesses, agencies, and professionals. It is produced by the software company 2ndSite Inc. which is located in Toronto, Ontario, Canada. The product includes a myriad of other related features, such as time tracking, expense tracking, recurring billing, online payment collection, the ability to mail invoices through the U.S. Post, and support tickets.

Summary

Constants
String DEFAULT_API_URL
Fields
private Config config
Public Constructors
FreshBooksConnector()
Public Methods
String authUser(String requestTokenUrl, String accessTokenUrl, String authorizationUrl, String callbackUrl, String requestTokenId, Map<String, Object> headers)
Authorize an user using OAuth1.0a
Callback createCallback(String sourceToken, Callback callback, String accessTokenId)
Create a new callback for a specific event or a set of events.
Category createCategory(String sourceToken, Category category, String accessTokenId)
Create a new category.
Client createClient(String sourceToken, Client client, String accessTokenId)
Create a new client and return the corresponding client_id.
Invoice createInvoice(String sourceToken, Invoice invoice, String accessTokenId)

Create a new invoice complete with line items.

Item createItem(String sourceToken, Item item, String accessTokenId)

Create a new item and return the corresponding item_id.

License createLicense(String sourceToken, License license, String accessTokenId)
Create a license
Payment createPayment(String sourceToken, Payment payment, String accessTokenId)
Create a new payment and returns the corresponding payment_id.
Session createSession(String sourceToken, Session session, String accessTokenId)
Create a session
System createSystemUser(String sourceToken, System systemUser, String userIdentifier)
Create a system user.
Task createTask(String sourceToken, Task task, String accessTokenId)
Create a new task and returns the corresponding task_id.
Tax createTax(String sourceToken, Tax tax, String accessTokenId)
Create a new tax and returns the corresponding tax_id.
void deleteCallback(String sourceToken, Callback callback, String accessTokenId)
Deletes a callback.
void deleteCategory(String sourceToken, Category category, String accessTokenId)
Delete an existing expense category.
void deleteClient(String sourceToken, Client client, String accessTokenId)
Delete the client with the given client_id.
void deleteInvoice(String sourceToken, Invoice invoice, String accessTokenId)
Delete an existing invoice.
void deleteItem(String sourceToken, Item item, String accessTokenId)
Delete an existing item.
void deleteLicense(String sourceToken, License license, String accessTokenId)
Permanently delete a license.
void deletePayment(String sourceToken, Payment payment, String accessTokenId)
Permanently delete a payment.
void deleteTask(String sourceToken, Task task, String accessTokenId)
Permanently delete a task.
void deleteTax(String sourceToken, Tax tax, String accessTokenId)
Permanently delete a tax.
OAuthCredentials getAccessToken(String apiUrl, String verifier, String requestTokenId, String userIdentifier)
Extract accessToken
Category getCategory(String sourceToken, String categoryId, String accessTokenId)
Return the complete category details associated with the given category_id.
Client getClient(String sourceToken, String clientId, String accessTokenId)
Return the client details associated with the given client_id.
Config getConfig()
Staff getCurrentUserInformation(String sourceToken, String accessTokenId, OAuthCredentials credentials)
Returns information about the current user
Invoice getInvoice(String sourceToken, String invoiceId, String accessTokenId)

Return the complete invoice details associated with the given invoice_id.

Item getItem(String sourceToken, String itemId, String accessTokenId)

Get an existing item with the given item_id.

Payment getPayment(String sourceToken, String paymentId, String accessTokenId)

Retrieve payment details according to payment_id.

Task getTask(String sourceToken, String taskId, String accessTokenId)

Retrieve an existing task.

Tax getTax(String sourceToken, String taxId, String accessTokenId)

Retrieve tax details according to tax_id.

Iterable<Addon> listAddons(String sourceToken, String accessTokenId)
Returns a list of addons summaries.
Iterable<Callback> listCallbacks(String sourceToken, CallbackRequest callbackRequest, String accessTokenId)
Return a list of registered callbacks.
Iterable<Category> listCategories(String sourceToken, CategoryRequest categoryRequest, String accessTokenId)
Returns a list of expense categories.
Iterable<Client> listClients(String sourceToken, ClientRequest clientRequest, String accessTokenId)
Returns a list of client summaries in order of descending client_id.
Iterable<Invoice> listInvoices(String sourceToken, InvoiceRequest invoiceRequest, String accessTokenId)
Returns a list of invoice summaries.
Iterable<Item> listItems(String sourceToken, ItemRequest itemRequest, String accessTokenId)
Returns a list of items, ordered by descending item_id.
Iterable<License> listLicenses(String sourceToken, LicenseRequest licenseRequest, String accessTokenId)
Returns a list of licenses summaries.
Iterable<Payment> listPayments(String sourceToken, PaymentRequest paymentRequest, String accessTokenId)
Returns a list of payment summaries.
Iterable<Task> listTasks(String sourceToken, TaskRequest taskRequest, String accessTokenId)
Returns a list of tasks summaries.
Iterable<Tax> listTaxes(String sourceToken, TaxRequest taxRequest, String accessTokenId)
Returns a list of taxs, ordered by descending tax_id.
void setConfig(Config config)
String undeleteClient(String sourceToken, Client client, String accessTokenId)
Undelete a client
String undeleteInvoice(String sourceToken, Invoice invoice, String accessTokenId)
Undelete an invoice
Category updateCategory(String sourceToken, Category category, String accessTokenId)
Update an existing expense category with the given category_id.
Client updateClient(String sourceToken, Client client, String accessTokenId)
Update the details of the client with the given client_id.
Invoice updateInvoice(String sourceToken, Invoice invoice, String accessTokenId)

Update an existing invoice with the given invoice_id.

Item updateItem(String sourceToken, Item item, String accessTokenId)

Update an existing item.

Payment updatePayment(String sourceToken, Payment payment, String accessTokenId)

Update an existing payment.

Task updateTask(String sourceToken, Task task, String accessTokenId)

Update an existing task.

Tax updateTax(String sourceToken, Tax tax, String accessTokenId)

Update an existing tax.

Callback verifyCallback(String sourceToken, Callback callback, String accessTokenId)
Verify a callback.
[Expand]
Inherited Methods
From class java.lang.Object

Constants

private static final String DEFAULT_API_URL

Constant Value: "https://%s/api/2.1/xml-in"

Fields

private Config config

Public Constructors

public FreshBooksConnector ()

Public Methods

public String authUser (String requestTokenUrl, String accessTokenUrl, String authorizationUrl, String callbackUrl, String requestTokenId, Map<String, Object> headers)

Authorize an user using OAuth1.0a

Parameters
requestTokenUrl RequestTokenUrl
accessTokenUrl AccessTokenUrl
authorizationUrl AuthorizationUrl
callbackUrl CallbackUrl for OAuth service
requestTokenId Optional value for identifying the requestToken. If it is not passed the client will use a UUID
headers Outbound headers
Returns
  • Authorize Url
Throws
ObjectStoreException from the Object Store instance
OAuthCommunicationException requesting to OAuth provider
OAuthExpectationFailedException requesting to OAuth provider
OAuthNotAuthorizedException requesting to OAuth provider
OAuthMessageSignerException requesting to OAuth provider

public Callback createCallback (String sourceToken, Callback callback, String accessTokenId)

Create a new callback for a specific event or a set of events.

Valid events

* all

* category

* category.create

* category.delete

* category.update

* client

* client.create

* client.delete

* client.update

* estimate

* estimate.create

* estimate.delete

* estimate.sendByEmail

* estimate.update

* expense

* expense.create

* expense.delete

* expense.update

* invoice

* invoice.create

* invoice.delete

* invoice.dispute

* invoice.pastdue.1

* invoice.pastdue.2

* invoice.pastdue.3

* invoice.sendByEmail

* invoice.sendBySnailMail

* invoice.update

* item

* item.create

* item.delete

* item.update

* payment

* payment.create

* payment.delete

* payment.update

* project

* project.create

* project.delete

* project.update

* recurring

* recurring.create

* recurring.delete

* recurring.update

* staff

* staff.create

* staff.delete

* staff.update

* task

* task.create

* task.delete

* task.update

* time_entry

* time_entry.create

* time_entry.delete

* time_entry.update

Parameters
sourceToken Source token value
callback To be created
accessTokenId AccessTokenIdentifier
Returns
  • callback id

public Category createCategory (String sourceToken, Category category, String accessTokenId)

Create a new category. If successful, returns the category id of the newly created item.

Parameters
sourceToken Source token value
category To be created
accessTokenId AccessTokenIdentifier
Returns
  • The created category

public Client createClient (String sourceToken, Client client, String accessTokenId)

Create a new client and return the corresponding client_id. If a password is not supplied, one will be created at random.

Parameters
sourceToken Source token value
client To be created
accessTokenId AccessTokenIdentifier
Returns
  • The created client

public Invoice createInvoice (String sourceToken, Invoice invoice, String accessTokenId)

Create a new invoice complete with line items. If successful, returns the invoice_id of the newly created invoice.

* If you don't specify an invoice number, it will increment from the last one.
* You may optionally specify a different address on the invoice; otherwise the address will be pulled from your client's details.
* You may optionally specify a return_uri element. If provided, users will be presented with a link to the URI when they pay the invoice.

Parameters
sourceToken Source token value
invoice To be created
accessTokenId AccessTokenIdentifier
Returns
  • The created invoice

public Item createItem (String sourceToken, Item item, String accessTokenId)

Create a new item and return the corresponding item_id.

Parameters
sourceToken Source token value
item To be created
accessTokenId AccessTokenIdentifier
Returns
  • The created item

public License createLicense (String sourceToken, License license, String accessTokenId)

Create a license

Parameters
sourceToken Source token value
license The license to be created
accessTokenId AccessTokenIdentifier
Returns
  • created license information

public Payment createPayment (String sourceToken, Payment payment, String accessTokenId)

Create a new payment and returns the corresponding payment_id.

This function can have one of three possible effects depending on the presence of invoice_id and client_id:

* If you specify an invoice_id only, the payment will be recorded as an invoice payment.

* If you specify a client_id only, the payment will be recorded as a client credit.

* If you specify both an invoice_id and client_id, the payment will be recorded as an invoice payment, and the amount will be subtracted from the client's credit.

Note that 'currency_code' can only be provided when creating a credit, not a regular payment. Regular payments will default to the currency code of the invoice they are being made against.

Parameters
sourceToken Source token value
payment To be created
accessTokenId AccessTokenIdentifier
Returns
  • The created Payment

public Session createSession (String sourceToken, Session session, String accessTokenId)

Create a session

Parameters
sourceToken Source token value
session The session to be created
accessTokenId AccessTokenIdentifier
Returns
  • created session information

public System createSystemUser (String sourceToken, System systemUser, String userIdentifier)

Create a system user. You don't need to be authenticated to call this processor.

Parameters
sourceToken Source token value
systemUser The system user to be created
userIdentifier Identifier to be used for storing the accessToken
Returns
  • created system user
Throws
ObjectStoreException in case of failure storing the accessToken information

public Task createTask (String sourceToken, Task task, String accessTokenId)

Create a new task and returns the corresponding task_id.

Parameters
sourceToken Source token value
task To be created
accessTokenId AccessTokenIdentifier
Returns
  • The created Task

public Tax createTax (String sourceToken, Tax tax, String accessTokenId)

Create a new tax and returns the corresponding tax_id.

*Tax “name” must be unique. You may not create more than one tax with the same name.

Parameters
sourceToken Source token value
tax To be created
accessTokenId AccessTokenIdentifier
Returns
  • The created Tax

public void deleteCallback (String sourceToken, Callback callback, String accessTokenId)

Deletes a callback.

Parameters
sourceToken Source token value
callback To be deleted
accessTokenId AccessTokenIdentifier

public void deleteCategory (String sourceToken, Category category, String accessTokenId)

Delete an existing expense category.

Parameters
sourceToken Source token value
category To be deleted
accessTokenId AccessTokenIdentifier

public void deleteClient (String sourceToken, Client client, String accessTokenId)

Delete the client with the given client_id.

Parameters
sourceToken Source token value
client To be deleted
accessTokenId AccessTokenIdentifier

public void deleteInvoice (String sourceToken, Invoice invoice, String accessTokenId)

Delete an existing invoice.

Parameters
sourceToken Source token value
invoice To be deleted
accessTokenId AccessTokenIdentifier

public void deleteItem (String sourceToken, Item item, String accessTokenId)

Delete an existing item.

Parameters
sourceToken Source token value
item To be deleted
accessTokenId AccessTokenIdentifier

public void deleteLicense (String sourceToken, License license, String accessTokenId)

Permanently delete a license.

Parameters
sourceToken Source token value
license To be deleted
accessTokenId AccessTokenIdentifier

public void deletePayment (String sourceToken, Payment payment, String accessTokenId)

Permanently delete a payment. This will modify the status of the associated invoice if required.

Parameters
sourceToken Source token value
payment To be deleted
accessTokenId AccessTokenIdentifier

public void deleteTask (String sourceToken, Task task, String accessTokenId)

Permanently delete a task.

Parameters
sourceToken Source token value
task To be deleted
accessTokenId AccessTokenIdentifier

public void deleteTax (String sourceToken, Tax tax, String accessTokenId)

Permanently delete a tax.

Parameters
sourceToken Source token value
tax To be deleted
accessTokenId AccessTokenIdentifier

public OAuthCredentials getAccessToken (String apiUrl, String verifier, String requestTokenId, String userIdentifier)

Extract accessToken

Parameters
apiUrl API URL
verifier OAuth verifier. It comes within the callback. The default value is "#[header:inbound:oauth_verifier]"
requestTokenId Id used for identifying the authorized request token. It comes within the callback. By default the query string parameter is userId
userIdentifier Id used for store the accessToken in the Object Store. If it is not provided by the app the connector uses the username from FreshBooks
Returns
  • credentials user credentials
Throws
ObjectStoreException from the object store instance
OAuthCommunicationException requesting to OAuth provider
OAuthExpectationFailedException requesting to OAuth provider
OAuthNotAuthorizedException requesting to OAuth provider
OAuthMessageSignerException requesting to OAuth provider

public Category getCategory (String sourceToken, String categoryId, String accessTokenId)

Return the complete category details associated with the given category_id.

Parameters
sourceToken Source token value
categoryId The category id
accessTokenId AccessTokenIdentifier
Returns

public Client getClient (String sourceToken, String clientId, String accessTokenId)

Return the client details associated with the given client_id.

Parameters
sourceToken Source token value
clientId The client id
accessTokenId AccessTokenIdentifier
Returns

public Config getConfig ()

public Staff getCurrentUserInformation (String sourceToken, String accessTokenId, OAuthCredentials credentials)

Returns information about the current user

Parameters
sourceToken Source token value
accessTokenId AccessTokenIdentifier
credentials Provided by the app when the credentials are not stored yet
Returns
  • current user information

public Invoice getInvoice (String sourceToken, String invoiceId, String accessTokenId)

Return the complete invoice details associated with the given invoice_id.

* You can use the links element to provide your customers with direct links to the invoice for editing, viewing by the client and viewing by an administrator.

Parameters
sourceToken Source token value
invoiceId The invoice id
accessTokenId AccessTokenIdentifier
Returns
  • The invoice retrieved.

public Item getItem (String sourceToken, String itemId, String accessTokenId)

Get an existing item with the given item_id.

Parameters
sourceToken Source token value
itemId The item id
accessTokenId AccessTokenIdentifier
Returns
  • The item retrieved.

public Payment getPayment (String sourceToken, String paymentId, String accessTokenId)

Retrieve payment details according to payment_id.

Parameters
sourceToken Source token value
paymentId The payment id
accessTokenId AccessTokenIdentifier
Returns
  • The payment retrieved.

public Task getTask (String sourceToken, String taskId, String accessTokenId)

Retrieve an existing task.

Parameters
sourceToken Source token value
taskId The task id
accessTokenId AccessTokenIdentifier
Returns
  • The task retrieved.

public Tax getTax (String sourceToken, String taxId, String accessTokenId)

Retrieve tax details according to tax_id.

Parameters
sourceToken Source token value
taxId The tax id
accessTokenId AccessTokenIdentifier
Returns
  • The tax retrieved.

public Iterable<Addon> listAddons (String sourceToken, String accessTokenId)

Returns a list of addons summaries. Results are ordered by descending id.

Parameters
sourceToken Source token value
accessTokenId AccessTokenIdentifier
Returns
  • A iterable of Addons

public Iterable<Callback> listCallbacks (String sourceToken, CallbackRequest callbackRequest, String accessTokenId)

Return a list of registered callbacks. You can optionally filter by event or uri.

Parameters
sourceToken Source token value
callbackRequest CallbackRequest CallbackRequest object
accessTokenId AccessTokenIdentifier
Returns
  • iterable of callbacks

public Iterable<Category> listCategories (String sourceToken, CategoryRequest categoryRequest, String accessTokenId)

Returns a list of expense categories.

Parameters
sourceToken Source token value
categoryRequest CategoryRequest CategoryRequest Object
accessTokenId AccessTokenIdentifier
Returns
  • A iterable of categories

public Iterable<Client> listClients (String sourceToken, ClientRequest clientRequest, String accessTokenId)

Returns a list of client summaries in order of descending client_id.

Parameters
sourceToken Source token value
clientRequest ClientRequest ClientRequest object
accessTokenId AccessTokenIdentifier
Returns
  • A iterable of clients

public Iterable<Invoice> listInvoices (String sourceToken, InvoiceRequest invoiceRequest, String accessTokenId)

Returns a list of invoice summaries. Results are ordered by descending invoice_id.

Parameters
sourceToken Source token value
invoiceRequest InvoiceRequest InvoiceRequest object
accessTokenId AccessTokenIdentifier
Returns
  • A iterable of Invoices

public Iterable<Item> listItems (String sourceToken, ItemRequest itemRequest, String accessTokenId)

Returns a list of items, ordered by descending item_id.

Parameters
sourceToken Source token value
itemRequest ItemRequest ItemRequest object
accessTokenId AccessTokenIdentifier
Returns
  • A iterable of Items

public Iterable<License> listLicenses (String sourceToken, LicenseRequest licenseRequest, String accessTokenId)

Returns a list of licenses summaries. Results are ordered by descending license_id.

Parameters
sourceToken Source token value
licenseRequest LicenseRequest LicenseRequest object
accessTokenId AccessTokenIdentifier
Returns
  • A iterable of Licenses

public Iterable<Payment> listPayments (String sourceToken, PaymentRequest paymentRequest, String accessTokenId)

Returns a list of payment summaries. Results are ordered by descending payment_id.

Parameters
sourceToken Source token value
paymentRequest PaymentRequest PaymentRequest object
accessTokenId AccessTokenIdentifier
Returns
  • A iterable of Payments

public Iterable<Task> listTasks (String sourceToken, TaskRequest taskRequest, String accessTokenId)

Returns a list of tasks summaries.

Parameters
sourceToken Source token value
taskRequest TaskRequest TaskRequest object
accessTokenId AccessTokenIdentifier
Returns
  • A iterable of Tasks

public Iterable<Tax> listTaxes (String sourceToken, TaxRequest taxRequest, String accessTokenId)

Returns a list of taxs, ordered by descending tax_id.

Filters: Use a “compound” tag to return only compound or non-compound taxes.

Parameters
sourceToken Source token value
taxRequest TaxRequest TaxRequest object
accessTokenId AccessTokenIdentifier
Returns
  • A iterable of Taxes

public void setConfig (Config config)

Parameters
config

public String undeleteClient (String sourceToken, Client client, String accessTokenId)

Undelete a client

Parameters
sourceToken Source token value
client To be undeleted
accessTokenId AccessTokenIdentifier
Returns
  • the undeleted client id

public String undeleteInvoice (String sourceToken, Invoice invoice, String accessTokenId)

Undelete an invoice

Parameters
sourceToken Source token value
invoice To be undeleted
accessTokenId AccessTokenIdentifier
Returns
  • The undeleted invoice id

public Category updateCategory (String sourceToken, Category category, String accessTokenId)

Update an existing expense category with the given category_id. Any category fields left out of the request will remain unchanged.

Parameters
sourceToken Source token value
category To be updated
accessTokenId AccessTokenIdentifier
Returns
  • updated category

public Client updateClient (String sourceToken, Client client, String accessTokenId)

Update the details of the client with the given client_id. Any fields not referenced in the request will remain unchanged.

Parameters
sourceToken Source token value
client To be updated
accessTokenId AccessTokenIdentifier
Returns
  • updated client

public Invoice updateInvoice (String sourceToken, Invoice invoice, String accessTokenId)

Update an existing invoice with the given invoice_id. Any invoice fields left out of the request will remain unchanged.

* If you do not specify a lines element, the existing lines will remain unchanged. If you do specify lines elements the original ones will be replaced by the new ones.

Parameters
sourceToken Source token value
invoice To be updated
accessTokenId AccessTokenIdentifier
Returns
  • updated invoice

public Item updateItem (String sourceToken, Item item, String accessTokenId)

Update an existing item. All fields aside from the item_id are optional; by omitting a field, the existing value will remain unchanged.

Parameters
sourceToken Source token value
item To be updated
accessTokenId AccessTokenIdentifier
Returns
  • updated item

public Payment updatePayment (String sourceToken, Payment payment, String accessTokenId)

Update an existing payment. All fields besides payment_id are optional - unpassed fields will retain their existing value.

Note that 'currency_code' can only be provided when updating a credit, not a regular payment. Regular payments will default to the currency code of the invoice they are being made against.

Parameters
sourceToken Source token value
payment To be updated
accessTokenId AccessTokenIdentifier
Returns
  • updated Payment

public Task updateTask (String sourceToken, Task task, String accessTokenId)

Update an existing task.

Parameters
sourceToken Source token value
task To be updated
accessTokenId AccessTokenIdentifier
Returns
  • updated Task

public Tax updateTax (String sourceToken, Tax tax, String accessTokenId)

Update an existing tax. All fields aside from the tax_id are optional; by omitting a field, the existing value will remain unchanged.

Parameters
sourceToken Source token value
tax To be updated
accessTokenId AccessTokenIdentifier
Returns
  • updated Tax

public Callback verifyCallback (String sourceToken, Callback callback, String accessTokenId)

Verify a callback.

Parameters
sourceToken Source token value
callback To be verified
accessTokenId AccessTokenIdentifier
Returns
  • verified callback