CloudyK Cloud Technology Talk, Tips, Tutorials.

FinancialForce Sales Invoice API Tutorial

I began working on FinancialForce for a client a few months back.  For those who don't know what it is, FinancialForce is an accounting package developed on the Force.com platform and sold on the Salesforce.com Appexchange.  The application is quite robust and built on technology developed by Coda.  The main advantage that FinancialForce presents for Salesforce.com customers is the ability to have your accounting package tightly integrated with Salesforce CRM or Force.com applications.

FinancialForce offers a lot of out-of-the-box integrations to Salesforce and has a fairly well-built API for deep integration.  Today, I will be discussing my experiences with the API.

During a project I was working on recently, the requirement for automated Sales Invoice generation came up.  I accomplished this through the Sales Invoice API. We will be calling the API directly from Apex and not over web services.  Here is what we did...

Resources

Below are some resources that will come in handy:

• FinancialForce API Reference
• FinancialForce Best Practices Guidelines
• Salesforce.com Apex Developer Guide

Set up the API

The first thing that needs to be done is the setup of the API.  FinancialForce will supply you with API keys and you must have an API key for each environment (production, sandbox, etc).

Once you have the API key, you must enter it in the API key field on the User object in Salesforce.  By default, this field will be excluded from your Page Layouts so you must add it.  Once you do this you are good to go.

The class

Create a new Apex class. In this example, I called it FinancialForceTestClass. You will need the Id or Name for the Account you are creating the invoice for and the Id or Name for the Product2 you will be using. In this example, I am creating an invoice with only one Product but you could use multiple Products.

public class FinancialForceTest {

     //The Salesforce Account that we will create the invoice for
     public Account acc = new Account();

     //The product that we will use for the Sales Invoice
     public Product2 prod = new Product2();

     public FinancialForceTest() {

          //SOQL queries to get our Account and Product
          acc = [SELECT Id, Name FROM Account Limit 1];
          prod = [SELECT Id, Name FROM Product2 WHERE name = 'Widget' Limit 1];

     }

     //Method for creating our sales invoice
     public void CreateFFSalesInvoice() {

     }
}

Now we need to call the Sales Invoice API from our method. In this example, I am using version 4.0.

NOTE:  FinancialForce uses an API class called Reference to reference another object or record.  The Reference class can take either an Id or Name to get a record.  To use a reference, call the API class and assign it an Id or a Name.  In the code below, you will see the Reference class used for the Account and InvoiceCurrency.

     //Method for creating our sales invoice
     public void CreateFFSalesInvoice() {

          //Call the CODAAPIInvoiceTypes_4_0.Invoice API class to create the invoice
          c2g.CODAAPIInvoiceTypes_4_0.Invoice salesinvoice
               = new c2g.CODAAPIInvoiceTypes_4_0.Invoice();

          //Set the fields for the invoice
          salesinvoice.Account = new c2g.CODAAPICommon.Reference();
          salesinvoice.Account.Id = acc.Id;
          salesinvoice.CustomerReference = 'Sale #1';
          salesinvoice.InvoiceCurrency = new c2g.CODAAPICommon.Reference();
          salesinvoice.InvoiceCurrency.Name = 'USD';
          salesinvoice.InvoiceStatus
               = c2g.CODAAPIInvoiceTypes_4_0.enumInvoiceStatus.InProgress;
          salesinvoice.InvoiceDate = System.now().date();
          salesinvoice.DueDate = System.now().date() + 30;
          salesinvoice.InvoiceDescription = 'Widget order for ' + acc.Name;
          salesinvoice.UsePartPeriods = false;
          salesinvoice.PrintedText1AllowEdit = false;
          salesinvoice.PrintedText2AllowEdit = false;
          salesinvoice.PrintedText3AllowEdit = false;
          salesinvoice.PrintedText4AllowEdit = false;
          salesinvoice.PrintedText5AllowEdit = false;

          //Set up the Sales Invoice to receive line items
          salesinvoice.LineItems
               = new c2g.CODAAPIInvoiceLineItemTypes_4_0.InvoiceLineItems();
          salesinvoice.LineItems.LineItemList
               = new List<c2gCODAAPIInvoiceLineItemTypes_4_0.InvoiceLineItem>();
     }

Now we can create the line item for the widget and send it to the Sales Invoice. Again, we will use a Reference object to set the Product.

          //Create the line item
          c2g.CODAAPIInvoiceLineItemTypes_4_0.InvoiceLineItem salesinvoiceitem
               = new c2g.CODAAPIInvoiceLineItemTypes_4_0.InvoiceLineItem();
          salesinvoiceitem.Product = new c2g.CODAAPICommon.Reference();
          salesinvoiceitem.Product.Id = prod.Id;
          salesinvoiceitem.UnitPrice = 200;
          salesinvoiceitem.Quantity = 1;
          salesinvoiceitem.LineDescription = '1 $200 Widget';
          salesinvoiceitem.TaxValue1 = 0;
          salesinvoiceitem.UsePartPeriods = false;

         //Add the line item to the Sales Invoice
          salesinvoice.LineItems.LineItemList.add(salesinvoicelineitem);

Finally, we can create the invoice using the API. The invoice will only be created, and not posted to FinancialForce. The CreateInvoice method returns a Reference which will supply you with the Id and Name of the newly created Sales Invoice. This is handy if you need to redirect the user to the invoice or display it somewhere, perhaps in a Visualforce page.

         //Create the Sales Invoice via the API
          c2g.CODAAPICommon.Reference ref
               = c2g.CODAAPISalesInvoice_4_0.CreateInvoice(null, salesinvoice);

And here is the entire class, all put together and ready to go.

public class FinancialForceTest {

     //The Salesforce Account that we will create the invoice for
     public Account acc = new Account();

     //The product that we will use for the Sales Invoice
     public Product2 prod = new Product2();

     public FinancialForceTest() {

          //SOQL queries to get our Account and Product
          acc = [SELECT Id, Name FROM Account Limit 1];
          prod = [SELECT Id, Name FROM Product2 WHERE name = 'Widget' Limit 1];

     }

     //Method for creating our sales invoice
     public void CreateFFSalesInvoice() {

          //Call the CODAAPIInvoiceTypes_4_0.Invoice API class to create the invoice
          c2g.CODAAPIInvoiceTypes_4_0.Invoice salesinvoice
               = new c2g.CODAAPIInvoiceTypes_4_0.Invoice();

          //Set the fields for the invoice
          salesinvoice.Account = new c2g.CODAAPICommon.Reference();
          salesinvoice.Account.Id = acc.Id;
          salesinvoice.CustomerReference = 'Sale #1';
          salesinvoice.InvoiceCurrency = new c2g.CODAAPICommon.Reference();
          salesinvoice.InvoiceCurrency.Name = 'USD';
          salesinvoice.InvoiceStatus
               = c2g.CODAAPIInvoiceTypes_4_0.enumInvoiceStatus.InProgress;
          salesinvoice.InvoiceDate = System.now().date();
          salesinvoice.DueDate = System.now().date() + 30;
          salesinvoice.InvoiceDescription = 'Widget order for ' + acc.Name;
          salesinvoice.UsePartPeriods = false;
          salesinvoice.PrintedText1AllowEdit = false;
          salesinvoice.PrintedText2AllowEdit = false;
          salesinvoice.PrintedText3AllowEdit = false;
          salesinvoice.PrintedText4AllowEdit = false;
          salesinvoice.PrintedText5AllowEdit = false;

          //Set up the Sales Invoice to receive line items
          salesinvoice.LineItems
               = new c2g.CODAAPIInvoiceLineItemTypes_4_0.InvoiceLineItems();
          salesinvoice.LineItems.LineItemList
               = new List();

          //Create the line item
          c2g.CODAAPIInvoiceLineItemTypes_4_0.InvoiceLineItem salesinvoiceitem
               = new c2g.CODAAPIInvoiceLineItemTypes_4_0.InvoiceLineItem();
          salesinvoiceitem.Product = new c2g.CODAAPICommon.Reference();
          salesinvoiceitem.Product.Id = prod.Id;
          salesinvoiceitem.UnitPrice = 200;
          salesinvoiceitem.Quantity = 1;
          salesinvoiceitem.LineDescription = '1 $200 Widget';
          salesinvoiceitem.TaxValue1 = 0;
          salesinvoiceitem.UsePartPeriods = false;

         //Add the line item to the Sales Invoice
          salesinvoice.LineItems.LineItemList.add(salesinvoicelineitem);

          //Create the Sales Invoice via the API
          c2g.CODAAPICommon.Reference ref
               = c2g.CODAAPISalesInvoice_4_0.CreateInvoice(null, salesinvoice);

     }
}

Notes

If you are creating Sales Invoices and other operations within an Apex trigger, you should use the BulkCreateInvoice method instead which utilizes Batch Apex, and allows you to pass a list of invoices in for creation.  I also ran into a Save Point issue when creating 4 invoices in one method.  I had to use the BulkCreateInvoice method to circumvent this error.