While developing SoqlXplorer and SF3 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 open source 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). The latest version supports both OSX 10.5 and up, and iPhone OS 3.2 (and up)
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 v19.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,
- describeGlobal, describeSObject & describeLayout
- search, query, queryAll, queryMore & retrieve
- create, update & delete (including support for the MruHeader)
- you can send up a partner clientId, by calling setClientId: on the ZKSforceClient object.
- describeTabs or describeSObjects
- 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];
ZKSforceClient *sforce = [[ZKSforceClient alloc] init]; [sforce login:username password:password]; ZKSObject *contact = [ZKSObject withType:@"Contact"]; [contact setFieldValue:@"Fell" field:@"LastName"]; [contact setFieldValue:@"Simon" field:@"FirstName"]; NSArray *results = [sforce create:[NSArray arrayWithObject:contact]]; ZKSaveResult *sr = [results objectAtIndex:0]; if ([sr success]) NSLog(@"new contact id %@", [sr id]); else NSLog(@"error creating contact %@ %@", [sr statusCode], [sr message]); [sforce release];
ZKSforceClient.h documents all the methods available on the client stub, this largely map directly on the Salesforce.com web services API. If you're not familar with the web services API, you should start by reading the web services API documentation. If you're not familiar with Objective-C and/or Cocoa, then I'd recommend the Aaron Hillegass book Cocoa Programming for Mac OSX. There are also examples of using ZKSforce in the open source projects maildrop, sf3 & apexmate.