org.mule.modules

mule-module-freshbooks

config

Namespace	http://www.mulesoft.org/schema/mule/freshbooks
Schema Location	http://www.mulesoft.org/schema/mule/freshbooks/current/mule-freshbooks.xsd (View Schema)
Schema Version	1.0
Minimum Mule Version	3.2

Module Overview

FreshBooks

Summary

Configuration
<freshbooks:config> Configure an instance of this module

Message Processors
<freshbooks:create-callback> Create a new callback for a specific event or a set of events.
<freshbooks:create-category> Create a new category.
<freshbooks:create-client> Create a new client and return the corresponding client_id.
<freshbooks:create-invoice> Create a new invoice complete with line items.
<freshbooks:create-item> Create a new item and return the corresponding item_id.
<freshbooks:create-payment> Create a new payment and returns the corresponding payment_id.
<freshbooks:create-session> Create a session
<freshbooks:create-system-user> Create a system user
<freshbooks:create-tax> Create a new tax and returns the corresponding tax_id.
<freshbooks:delete-callback> Deletes a callback.
<freshbooks:delete-category> Delete an existing expense category.
<freshbooks:delete-client> Delete the client with the given client_id.
<freshbooks:delete-invoice> Delete an existing invoice.
<freshbooks:delete-item> Delete an existing item.
<freshbooks:delete-payment> Permanently delete a payment.
<freshbooks:delete-tax> Permanently delete a tax.
<freshbooks:get-category> Return the complete category details associated with the given category_id.
<freshbooks:get-client> Return the client details associated with the given client_id.
<freshbooks:get-current-user-information> Returns information about the current user
<freshbooks:get-invoice> Return the complete invoice details associated with the given invoice_id.
<freshbooks:get-item> Get an existing item with the given item_id.
<freshbooks:get-payment> Retrieve payment details according to payment_id.
<freshbooks:get-tax> Retrieve tax details according to tax_id.
<freshbooks:list-callbacks> Return a list of registered callbacks.
<freshbooks:list-categories> Returns a list of expense categories.
<freshbooks:list-clients> Returns a list of client summaries in order of descending client_id.
<freshbooks:list-invoices> Returns a list of invoice summaries.
<freshbooks:list-items> Returns a list of items, ordered by descending item_id.
<freshbooks:list-payments> Returns a list of payment summaries.
<freshbooks:list-taxes> Returns a list of taxs, ordered by descending tax_id.
<freshbooks:undelete-client> Undelete a client
<freshbooks:undelete-invoice> Undelete an invoice
<freshbooks:update-category> Update an existing expense category with the given category_id.
<freshbooks:update-client> Update the details of the client with the given client_id.
<freshbooks:update-invoice> Update an existing invoice with the given invoice_id.
<freshbooks:update-item> Update an existing item.
<freshbooks:update-payment> Update an existing payment.
<freshbooks:update-tax> Update an existing tax.
<freshbooks:verify-callback> Verify a callback.

Configuration

To use the this module within a flow the namespace to the module must be included. The resulting flow will look similar to the following:

<mule xmlns="http://www.mulesoft.org/schema/mule/core"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xmlns:freshbooks="http://www.mulesoft.org/schema/mule/freshbooks"
      xsi:schemaLocation="
               http://www.mulesoft.org/schema/mule/core
               http://www.mulesoft.org/schema/mule/core/current/mule.xsd
               http://www.mulesoft.org/schema/mule/freshbooks
               http://www.mulesoft.org/schema/mule/freshbooks/current/mule-freshbooks.xsd">

      <!-- here goes your flows and configuration elements -->

</mule>

This module is configured using the config element. This element must be placed outside of your flows and at the root of your Mule application. You can create as many configurations as you deem necessary as long as each carries its own name.

Each message processor, message source or transformer carries a config-ref attribute that allows the invoker to specify which configuration to use.

Attributes
Type	Name	Default Value	Description	Java Type	MIME Type	Encoding
xs:string	name		Optional. Give a name to this configuration so it can be later referenced.
xs:string	apiUrl		Api URL
xs:string	authenticationToken		Authentication Token

Message Processors

<freshbooks:create-callback>

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

XML Sample

INCLUDE_ERROR

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

Attributes

Name	Default Value	Description	Java Type	MIME Type	Encoding
config-ref		Optional. Specify which configuration to use.
sourceToken		Optional. Source token value	String	/	UTF-8
callback	#[payload]	Optional. To be created	Callback	/

Returns

Return Type	Description
Callback	callback id

<freshbooks:create-category>

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

XML Sample

INCLUDE_ERROR

Attributes

Name	Default Value	Description	Java Type	MIME Type	Encoding
config-ref		Optional. Specify which configuration to use.
sourceToken		Optional. Source token value	String	/	UTF-8
category	#[payload]	Optional. To be created	Category	/

Returns

Return Type	Description
Category	The created category

<freshbooks:create-client>

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

XML Sample

INCLUDE_ERROR

Attributes

Name	Default Value	Description	Java Type	MIME Type	Encoding
config-ref		Optional. Specify which configuration to use.
sourceToken		Optional. Source token value	String	/	UTF-8
client	#[payload]	Optional. To be created	Client	/

Returns

Return Type	Description
Client	The created client

Exception Payloads

Payload Class	Description
FreshbooksException

<freshbooks:create-invoice>

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.

XML Sample

INCLUDE_ERROR

Attributes

Name	Default Value	Description	Java Type	MIME Type	Encoding
config-ref		Optional. Specify which configuration to use.
sourceToken		Optional. Source token value	String	/	UTF-8
invoice	#[payload]	Optional. To be created	Invoice	/

Returns

Return Type	Description
Invoice	The created invoice

Exception Payloads

Payload Class	Description
FreshbooksException

<freshbooks:create-item>

Create a new item and return the corresponding item_id.

XML Sample

INCLUDE_ERROR

Attributes

Name	Default Value	Description	Java Type	MIME Type	Encoding
config-ref		Optional. Specify which configuration to use.
sourceToken		Optional. Source token value	String	/	UTF-8
item	#[payload]	Optional. To be created	Item	/

Returns

Return Type	Description
Item	The created item

Exception Payloads

Payload Class	Description
FreshbooksException

<freshbooks:create-payment>

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.

XML Sample

INCLUDE_ERROR

Attributes

Name	Default Value	Description	Java Type	MIME Type	Encoding
config-ref		Optional. Specify which configuration to use.
sourceToken		Optional. Source token value	String	/	UTF-8
payment	#[payload]	Optional. To be created	Payment	/

Returns

Return Type	Description
Payment	The created Payment

Exception Payloads

Payload Class	Description
FreshbooksException

<freshbooks:create-session>

Create a session

XML Sample

INCLUDE_ERROR

Attributes

Name	Default Value	Description	Java Type	MIME Type	Encoding
config-ref		Optional. Specify which configuration to use.
sourceToken		Optional. Source token value	String	/	UTF-8
session	#[payload]	Optional. The session to be created	Session	/

Returns

Return Type	Description
Session	created session information

<freshbooks:create-system-user>

Create a system user

XML Sample

INCLUDE_ERROR

Attributes

Name	Default Value	Description	Java Type	MIME Type	Encoding
config-ref		Optional. Specify which configuration to use.
sourceToken		Optional. Source token value	String	/	UTF-8
systemUser	#[payload]	Optional. The system user to be created	SystemUser	/

Returns

Return Type	Description
SystemUser	created system user

<freshbooks:create-tax>

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.

XML Sample

INCLUDE_ERROR

Attributes

Name	Default Value	Description	Java Type	MIME Type	Encoding
config-ref		Optional. Specify which configuration to use.
sourceToken		Optional. Source token value	String	/	UTF-8
tax	#[payload]	Optional. To be created	Tax	/

Returns

Return Type	Description
Tax	The created Tax

Exception Payloads

Payload Class	Description
FreshbooksException

<freshbooks:delete-callback>

Deletes a callback.

XML Sample

INCLUDE_ERROR

Attributes

Name	Default Value	Description	Java Type	MIME Type	Encoding
config-ref		Optional. Specify which configuration to use.
sourceToken		Optional. Source token value	String	/	UTF-8
callback	#[payload]	Optional. To be deleted	Callback	/

<freshbooks:delete-category>

Delete an existing expense category.

XML Sample

INCLUDE_ERROR

Attributes

Name	Default Value	Description	Java Type	MIME Type	Encoding
config-ref		Optional. Specify which configuration to use.
sourceToken		Optional. Source token value	String	/	UTF-8
category	#[payload]	Optional. To be deleted	Category	/

<freshbooks:delete-client>

Delete the client with the given client_id.

XML Sample

INCLUDE_ERROR

Attributes

Name	Default Value	Description	Java Type	MIME Type	Encoding
config-ref		Optional. Specify which configuration to use.
sourceToken		Optional. Source token value	String	/	UTF-8
client	#[payload]	Optional. To be deleted	Client	/

Exception Payloads

Payload Class	Description
FreshbooksException

<freshbooks:delete-invoice>

Delete an existing invoice.

XML Sample

INCLUDE_ERROR

Attributes

Name	Default Value	Description	Java Type	MIME Type	Encoding
config-ref		Optional. Specify which configuration to use.
sourceToken		Optional. Source token value	String	/	UTF-8
invoice	#[payload]	Optional. To be deleted	Invoice	/

<freshbooks:delete-item>

Delete an existing item.

XML Sample

INCLUDE_ERROR

Attributes

Name	Default Value	Description	Java Type	MIME Type	Encoding
config-ref		Optional. Specify which configuration to use.
sourceToken		Optional. Source token value	String	/	UTF-8
item	#[payload]	Optional. To be deleted	Item	/

<freshbooks:delete-payment>

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

XML Sample

INCLUDE_ERROR

Attributes

Name	Default Value	Description	Java Type	MIME Type	Encoding
config-ref		Optional. Specify which configuration to use.
sourceToken		Optional. Source token value	String	/	UTF-8
payment	#[payload]	Optional. To be deleted	Payment	/

<freshbooks:delete-tax>

Permanently delete a tax.

XML Sample

INCLUDE_ERROR

Attributes

Name	Default Value	Description	Java Type	MIME Type	Encoding
config-ref		Optional. Specify which configuration to use.
sourceToken		Optional. Source token value	String	/	UTF-8
tax	#[payload]	Optional. To be deleted	Tax	/

<freshbooks:get-category>

Return the complete category details associated with the given category_id.

XML Sample

INCLUDE_ERROR

Attributes

Name	Description	Java Type	MIME Type	Encoding
config-ref	Optional. Specify which configuration to use.
sourceToken	Optional. Source token value	String	/	UTF-8
categoryId	The category id	String	/	UTF-8

Returns

Return Type	Description
Category	A `Category` object

<freshbooks:get-client>

Return the client details associated with the given client_id.

XML Sample

INCLUDE_ERROR

Attributes

Name	Description	Java Type	MIME Type	Encoding
config-ref	Optional. Specify which configuration to use.
sourceToken	Optional. Source token value	String	/	UTF-8
clientId	The client id	String	/	UTF-8

Returns

Return Type	Description
Client	A `Client`

Exception Payloads

Payload Class	Description
FreshbooksException

<freshbooks:get-current-user-information>

Returns information about the current user

XML Sample

INCLUDE_ERROR

Attributes

Name	Default Value	Description	Java Type	MIME Type	Encoding
config-ref		Optional. Specify which configuration to use.
sourceToken		Optional. Source token value	String	/	UTF-8

Returns

Return Type	Description
Staff	current user information

<freshbooks:get-invoice>

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.

XML Sample

INCLUDE_ERROR

Attributes

Name	Description	Java Type	MIME Type	Encoding
config-ref	Optional. Specify which configuration to use.
sourceToken	Optional. Source token value	String	/	UTF-8
invoiceId	The invoice id	String	/	UTF-8

Returns

Return Type	Description
Invoice	The invoice retrieved.

<freshbooks:get-item>

Get an existing item with the given item_id.

XML Sample

INCLUDE_ERROR

Attributes

Name	Description	Java Type	MIME Type	Encoding
config-ref	Optional. Specify which configuration to use.
sourceToken	Optional. Source token value	String	/	UTF-8
itemId	The item id	String	/	UTF-8

Returns

Return Type	Description
Item	The item retrieved.

<freshbooks:get-payment>

Retrieve payment details according to payment_id.

XML Sample

INCLUDE_ERROR

Attributes

Name	Description	Java Type	MIME Type	Encoding
config-ref	Optional. Specify which configuration to use.
sourceToken	Optional. Source token value	String	/	UTF-8
paymentId	The payment id	String	/	UTF-8

Returns

Return Type	Description
Payment	The payment retrieved.

<freshbooks:get-tax>

Retrieve tax details according to tax_id.

XML Sample

INCLUDE_ERROR

Attributes

Name	Description	Java Type	MIME Type	Encoding
config-ref	Optional. Specify which configuration to use.
sourceToken	Optional. Source token value	String	/	UTF-8
taxId	The tax id	String	/	UTF-8

Returns

Return Type	Description
Tax	The tax retrieved.

<freshbooks:list-callbacks>

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

XML Sample

INCLUDE_ERROR

Attributes

Name	Default Value	Description	Java Type	MIME Type	Encoding
config-ref		Optional. Specify which configuration to use.
sourceToken		Optional. Source token value	String	/	UTF-8
callbackRequest	#[payload]	Optional. `CallbackRequest` CallbackRequest object	CallbackRequest	/

Returns

Return Type	Description
Iterable<Callback>	iterable of callbacks

<freshbooks:list-categories>

Returns a list of expense categories.

XML Sample

INCLUDE_ERROR

Attributes

Name	Default Value	Description	Java Type	MIME Type	Encoding
config-ref		Optional. Specify which configuration to use.
sourceToken		Optional. Source token value	String	/	UTF-8
categoryRequest	#[payload]	Optional. `CategoryRequest` CategoryRequest Object	CategoryRequest	/

Returns

Return Type	Description
Iterable<Category>	A iterable of categories

Exception Payloads

Payload Class	Description
FreshbooksException

<freshbooks:list-clients>

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

XML Sample

INCLUDE_ERROR

Attributes

Name	Default Value	Description	Java Type	MIME Type	Encoding
config-ref		Optional. Specify which configuration to use.
sourceToken		Optional. Source token value	String	/	UTF-8
clientRequest	#[payload]	Optional. `ClientRequest` ClientRequest object	ClientRequest	/

Returns

Return Type	Description
Iterable<Client>	A iterable of clients

Exception Payloads

Payload Class	Description
FreshbooksException

<freshbooks:list-invoices>

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

XML Sample

INCLUDE_ERROR

Attributes

Name	Default Value	Description	Java Type	MIME Type	Encoding
config-ref		Optional. Specify which configuration to use.
sourceToken		Optional. Source token value	String	/	UTF-8
invoiceRequest	#[payload]	Optional. `InvoiceRequest` InvoiceRequest object	InvoiceRequest	/

Returns

Return Type	Description
Iterable<Invoice>	A iterable of Invoices

<freshbooks:list-items>

Returns a list of items, ordered by descending item_id.

XML Sample

INCLUDE_ERROR

Attributes

Name	Default Value	Description	Java Type	MIME Type	Encoding
config-ref		Optional. Specify which configuration to use.
sourceToken		Optional. Source token value	String	/	UTF-8
itemRequest	#[payload]	Optional. `ItemRequest` ItemRequest object	ItemRequest	/

Returns

Return Type	Description
Iterable<Item>	A iterable of Items

<freshbooks:list-payments>

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

XML Sample

INCLUDE_ERROR

Attributes

Name	Default Value	Description	Java Type	MIME Type	Encoding
config-ref		Optional. Specify which configuration to use.
sourceToken		Optional. Source token value	String	/	UTF-8
paymentRequest	#[payload]	Optional. `PaymentRequest` PaymentRequest object	PaymentRequest	/

Returns

Return Type	Description
Iterable<Payment>	A iterable of Payments

<freshbooks:list-taxes>

Returns a list of taxs, ordered by descending tax_id.

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

XML Sample

INCLUDE_ERROR

Attributes

Name	Default Value	Description	Java Type	MIME Type	Encoding
config-ref		Optional. Specify which configuration to use.
sourceToken		Optional. Source token value	String	/	UTF-8
taxRequest	#[payload]	Optional. `TaxRequest` TaxRequest object	TaxRequest	/

Returns

Return Type	Description
Iterable<Tax>	A iterable of Taxes

<freshbooks:undelete-client>

Undelete a client

XML Sample

INCLUDE_ERROR

Attributes

Name	Default Value	Description	Java Type	MIME Type	Encoding
config-ref		Optional. Specify which configuration to use.
sourceToken		Optional. Source token value	String	/	UTF-8
client	#[payload]	Optional. To be undeleted	Client	/

Returns

Return Type	Description
String	the undeleted client id

Exception Payloads

Payload Class	Description
FreshbooksException

<freshbooks:undelete-invoice>

Undelete an invoice

XML Sample

INCLUDE_ERROR

Attributes

Name	Default Value	Description	Java Type	MIME Type	Encoding
config-ref		Optional. Specify which configuration to use.
sourceToken		Optional. Source token value	String	/	UTF-8
invoice	#[payload]	Optional. To be undeleted	Invoice	/

Returns

Return Type	Description
String	The undeleted invoice id

<freshbooks:update-category>

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

XML Sample

INCLUDE_ERROR

Attributes

Name	Default Value	Description	Java Type	MIME Type	Encoding
config-ref		Optional. Specify which configuration to use.
sourceToken		Optional. Source token value	String	/	UTF-8
category	#[payload]	Optional. To be updated	Category	/

Returns

Return Type	Description
Category	updated category

<freshbooks:update-client>

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

XML Sample

INCLUDE_ERROR

Attributes

Name	Default Value	Description	Java Type	MIME Type	Encoding
config-ref		Optional. Specify which configuration to use.
sourceToken		Optional. Source token value	String	/	UTF-8
client	#[payload]	Optional. To be updated	Client	/

Returns

Return Type	Description
Client	updated client

Exception Payloads

Payload Class	Description
FreshbooksException

<freshbooks:update-invoice>

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.

XML Sample

INCLUDE_ERROR

Attributes

Name	Default Value	Description	Java Type	MIME Type	Encoding
config-ref		Optional. Specify which configuration to use.
sourceToken		Optional. Source token value	String	/	UTF-8
invoice	#[payload]	Optional. To be updated	Invoice	/

Returns

Return Type	Description
Invoice	updated invoice

Exception Payloads

Payload Class	Description
FreshbooksException

<freshbooks:update-item>

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

XML Sample

INCLUDE_ERROR

Attributes

Name	Default Value	Description	Java Type	MIME Type	Encoding
config-ref		Optional. Specify which configuration to use.
sourceToken		Optional. Source token value	String	/	UTF-8
item	#[payload]	Optional. To be updated	Item	/

Returns

Return Type	Description
Item	updated item

Exception Payloads

Payload Class	Description
FreshbooksException

<freshbooks:update-payment>

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.

XML Sample

INCLUDE_ERROR

Attributes

Name	Default Value	Description	Java Type	MIME Type	Encoding
config-ref		Optional. Specify which configuration to use.
sourceToken		Optional. Source token value	String	/	UTF-8
payment	#[payload]	Optional. To be updated	Payment	/

Returns

Return Type	Description
Payment	updated Payment

Exception Payloads

Payload Class	Description
FreshbooksException

<freshbooks:update-tax>

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

XML Sample

INCLUDE_ERROR

Attributes

Name	Default Value	Description	Java Type	MIME Type	Encoding
config-ref		Optional. Specify which configuration to use.
sourceToken		Optional. Source token value	String	/	UTF-8
tax	#[payload]	Optional. To be updated	Tax	/

Returns

Return Type	Description
Tax	updated Tax

Exception Payloads

Payload Class	Description
FreshbooksException

<freshbooks:verify-callback>

Verify a callback.

XML Sample

INCLUDE_ERROR

Attributes

Name	Default Value	Description	Java Type	MIME Type	Encoding
config-ref		Optional. Specify which configuration to use.
sourceToken		Optional. Source token value	String	/	UTF-8
callback	#[payload]	Optional. To be verified	Callback	/

Returns

Return Type	Description
Callback	verified callback