In April 2007 Adobe and Salesforce.com announced the availability of the Flex toolkit for Apex, Salesforce.com's on-demand programming language and API for interaction with their hosted CRM solution. This toolkit makes it simple to build Flex applications that interact with your Salesforce.com database.

The benefits of using Flex are numerous: create far more effective and efficient dashboards for your sales team, build "mashup" user interfaces that bring data together from Salesforce and your enterprise systems, and improve the overall usability of Salesforce.com with tools you're already comfortable with.

The API itself is rather simple. Using the toolkit you can execute query operations (create, update, delete), run full-text searches, pull back metadata on your Salesforce environment (tabs, controls, layout information), send e-mail messages, and work with the workflow engine. The most useful aspect of the API is the query operations, so we'll focus on that in the following sample application "sfQuery."

Getting Started
The toolkit is surprisingly easy to get started with. Simply download it from http://www.salesforce.com/developer, unzip the swc file to a convenient location, and add it to your Flex application's build path (see Figure 1).

Add a reference to the Salesforce namespace to your mx:Application tag as indicated below:

<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml"
xmlns:salesforce="com.salesforce.*" layout="absolute" >

To create a connection to the Salesforce.com servers, add this line of code to your application:

<salesforce:Connection id="apex"/>

That's the extent of the configuration of your application. We can now use the connection (referenced as "apex") to interact with the Apex platform.

SOQL: The Salesforce Object Query Language
While this isn't necessarily directly related to the toolkit, it's important to understand some of the peculiarities of SOQL. SOQL is very much like SQL, but with a few key differences. For example, wildcards aren't permitted in your field list in a select statement. Aggregate expressions are basically not supported except for count(), but even that's limited. The biggest difference to be forewarned about is how SOQL handles what we traditionally think of as "join" statements. Instead of returning a table of data, SOQL returns nested result sets from the child tables in a join statement. They refer to this approach as "SOQL relationships." Outer join capability is expected to be included in the Spring 2007 release of Apex. I recommend that you read www.salesforce.com/us/developer/docs/api/index.htm to understand just what you can (and can't) do in SOQL in more detail. It's not difficult to make up the difference in ActionScript, but it sure feels weird knowing you're doing something in code that you could do much easier in SQL!
Anyway, back to the demo:

Doing Stuff
Our demo application will be a simple SOQL query testing application so we can learn the SOQL syntax. You've already created your connection object, so to activate it we have to log in. Prepare a LoginRequest object by populating the username and password fields. Notice that we're defining a callback function (loginResult) that will be fired off when the login response from the Salesforce.com servers is received.

private function login():void
      {
var lr:LoginRequest = new LoginRequest;
// username/password used when logging in interactively
lr.username = username.text;
lr.password = pwd.text;
// server_url and session_id used when deployed in the salesforce environment
// lr.server_url = Application.application.parameters.server_url;
// lr.session_id = Application.application.parameters.session_id;
lr.callback = new AsyncResponder(loginResult);
apex.login(lr);
}

Our callback function is rather simple in this example - all we're doing is changing states. Now that we're logged in let's enter a quick SOQL query:

SELECT Account.Name,
(SELECT Contact.FirstName, Contact.LastName FROM Account.Contacts)
FROM Account

This query will retrieve all contacts for each account in our Salesforce database when the "Execute Query" button is clicked.

   private function executeQuery():void
   {
      apex.query(txtQuery.text,
        new AsyncResponder(function (qr:QueryResult):void
        {
txtQueryOutput.text = ObjectUtil.toString(qr.records);
        })
);
   }

The query() function takes an SOQL statement as the first argument and a callback function as its second. We'll pass the query off to the "apex" connection object and wait for a response. Stylistic comment: rather than define the callback in another function as I did with the loginResult function, I opted to define it inline as an anonymous function. Either method works; the decision as to which way you do this is purely personal.

Once we get the data back we'll use the ObjectUtil class to dump out the returned object as a string in the larger text area. If the query failed, we'd get an error and no results would render. Just like that we now have a quick SOQL statement tester that can help us build our future Flex/Apex applications.