Interfacing with FinancialForce Accounting is possible from a number of technologies available through both the Force.com platform APIs (otherwise known as the Enterprise API and Apex SOQL) and the tailored FinancialForce business APIs described on this website. The decision to use one or a combination of approaches depends less on your preferred integration platform (as both native Web Services and Apex flavours are provided) but more on the functional needs of the interface you are building.

The Force.com Enterprise API and Apex SOQL can provide both read and write access to records stored in the orgs. However, the FinancialForce APIs offer a more tailored business-like API for creating and posting documents without requiring an understanding of the underlying schema, and critically in a write and update scenario will do so in a controlled way. In fact, the triggers applied against the FinancialForce schema will not permit update through any other means to ensure data integrity is maintained through the use of the business APIs only. So, while direct SOQL over any FinancialForce custom object is supported for querying needs, developers are required to use the FinancialForce API to write and update records instead of using direct DML against FinancialForce custom objects, unless otherwise stated.

We have recently been working to provide DML access. For more information please see Using the Salesforce API.

The following diagram provides an overview of typical use cases, Force.com technologies and interfacing best practices around the FinancialForce API.

The FinancialForce API covers business operations on the core document types such as Sales Invoices, Purchase Invoices, Credit Notes, Journals and Cash Entries. These operations permit the creation, editing, posting and other document-specific business functions such as Invoice Schedules. Posting is a key process that will generate the credits and debit records in the FinancialForce transaction engine. These APIs provide the developer with the opportunity to develop alternate user interfaces or flows, or maybe to integrate FinancialForce into an existing user interaction. These APIs are appropriate for low-volume, end-user, interactive requirements. They must not be called in loops, and as such are not appropriate for bulk data volumes. For these use cases, use the BulkXXXX operations in conjunction with Batch Apex as described below.

Within an Apex Trigger context, the Force.com governor limits are currently too low to directly invoke many of the FinancialForce APIs successfully, especially when considering bulk record operations on custom objects. To avoid hitting governor limits, consider starting a background Batch Apex job from the trigger instead. However, be warned, as per the Apex Developer’s Guide, the platform limits the number of concurrent Batch Apex jobs queued per org to five. Once this is reached, the Database.executeBatch method will throw an exception and the records associated with the given trigger invocation will not be inserted. The advice from Salesforce is that the developer needs to take great care to consider this constraint if using Batch Apex from a trigger. The advice from FinancialForce.com is to avoid this approach, and instead consider using the new Spring '10 Scheduler or a button to invoke a Batch Apex job. Only consider using Batch Apex from a trigger if you are 100% confident you understand the implications. Specifically, that you have put in place adequate error handling and recovery, have volume tested, and ideally have control of the means by which your users manage records for the custom object associated with the trigger.

Within an Apex Trigger context, the Force.com platform governor limits are currently too low to directly invoke the FinancialForce APIs successfully, though bulkified SOQL queries over FinancialForce custom objects are fine. This is especially true when considering bulk record operations on the associated custom objects. To avoid hitting governor limits, consider starting a background Batch Apex job from the trigger instead (passing the full trigger record set on bulk). However, be warned, as per the Apex Developer’s Guide, the platform limits the number of concurrent Batch Apex jobs queued per org to five. Once this is reached, the Database.executeBatch method will throw an exception and the records associated with the given trigger invocation will not be inserted. The advice from Salesforce is that the developer needs to take great care to consider this constraint if using Batch Apex from a trigger. As an alternative to a trigger approach consider using the new Spring '10 Scheduler or a button to invoke a Batch Apex job (as described in this article). Only consider using Batch Apex from a trigger if you are 100% confident you understand the implications. Specifically, that you have put in place adequate error handling and recovery, have volume tested, and ideally have control of the means by which your users manage records for the custom object associated with the trigger.

The Batch Apex technology on Force.com can be used to achieve much higher volumes when used in conjunction with the FinancialForce API. This technology takes up to five million records and breaks up the processing into manageable chunks. The chunk size is definable. The FinancialForce API BulkXXXX methods are designed to be used in this environment, as they can take many documents as input. These API calls are tuned for bulk operations as per the Salesforce recommendations. While other FinancialForce APIs can be used, it is not advisable to call other API methods while iterating over records within a chunk. Batch Apex implementations can also leverage the new platform Scheduler feature to automate the process of consuming records on custom objects in one application in preparation for entering them into FinancialForce Accounting.

When using Batch Apex, it is important to test your code with an adequate number of records, at least the number of a single chunk. The default chunk size is 200, but this can be adjusted to fit. The general rule is that the more you try to do in each Batch Apex chunk, the more governed resources are used. This includes the size and complexity of the FinancialForce documents passed to the FinancialForce API. So, if in your testing you run into governor limits, use the optional chunk size/scope parameter on the Database.executeBatch method to reduce the chunk size. The platform will still process the same number of records overall, regardless of the chunk size.