zkSforce

While developing SoqlXplorer and SF³ it quickly became clear that Cocoa developers needed a quick and easy way to access the Salesforce.com SOAP API, zkSforce is the result. zkSforce is released under the uber liberal MIT license, and although not required, if you use zkSforce, it'd be nice to get a mention in your app's about dialog box. (this seems to be fairly standard policy for Mac apps).

I originally planned to release zkSforce as a framework you embed into your application, however reading Wil Shipley's excellent blog post on frameworks - Frameworks are Teh Suck, Err convinced me otherwise. (BTW, if you've never read Wil's blog, its a great way to loose a weekend, regardless of if you're a Mac developer or not.) So in the zip file you'll find a bunch of classes just add these to your app and off you go. If you're remotely familiar with the Salesforce.com API then a glance at zkSforceClient.h will tell you everything you need to know.

What's with the ZK prefix? convention suggests that classes use a prefix to help reduce naming classes. I would of preferred SF, but Apple already snagged that one, so its ZK, which is short for Zak, my middle name (and nickname of Derby County's Kevin Hector)

What's supported?, zkSforce uses the v8.0 partner API, and can be used to access any Saleforce.com account that includes API access (such as Developer Edition, Enterprise Edition and Unlimited Edition logins). The entire API is not yet implemented, the following operations are implemented,

• login
• describeGlobal & describeSObject
• search, query, queryMore & retrieve
• create, update & delete (including support for the MruHeader)
• you can send up a partner clientId, by calling setClientId: on the ZKSforceClient object.

The following operations are not yet implemented

• describeLayout, describeTabs or describeSObjects
• upsert
• convertLead
• getDeleted & getUpdated
• process & merge
• Headers for AssignmentRuleHeader, QueryOptions

In general the client acts just like the API, however in a few places it has some smarts to make your life easier.

• it'll track the duration of the session and re-login as required, so just keep calling methods as needed and don't worry about the session expiring away from under you.
• in ZKDescribeSObject there's a helper method to get the ZKDescribeField given the fields name.
• In ZKSObject the fieldsToNull collection is managed for you, if you add a field to the fieldsToNull collection (via setFieldToNull) it'll automatically remove any field value, also you can just set the field value directly to nil (aka null) in setFieldValue:field: and it'll automatically translate that into a fieldsToNull call for you.
• ZKQueryResult implements the NSTableView informal data source interface, so you can easily show a queries results in a table view (just like SoqlX does)
• You can ask the ZKSforceClient object to automatically cache describe results for you by calling setCacheDescribes

Usage is really straight forward, create an instance of the ZKSforceClient class, login, then call the other operations as needed, e.g.

ZKSforceClient *sforce = [[ZKSforceClient alloc] init];
[sforce login:username password:password];
ZKDescribeSObject *taskDescribe = [sforce describeSObject:@"Task"];
NSLog(@"url for the new Task page is %@", [taskDescribe urlNew]);	
[sforce release];

Download

Download zkSforce_v0.80.zip (44k) and give it a go.

Release History

v0.80 Jan 25, 2007

• Updated for the Salesforce.com Winter '07 release (aka API v8.0).
• DescribeSObject results and userInfoResult updated with all the new 8.0 properties.
• Support for auto describe caching added.
• query / ZKSObject updated to support SOQL-r.
• Search method added.
• support for setting a partner clientId added.

v0.60 Nov 21, 2006

• Initial release