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 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.9 and up, and iOS 9.0 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 v45.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). All of the Partner API is supported, including the various soap headers.

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 describeGlobal & describeSObject 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
	failBlock:^(NSError *err) {
		[[NSAlert alertWithError:err] runModal];
	}
	CompleteBlock:^(ZKLoginResult *result) {
		NSLog(@"Hello %@", result.userInfo.userFullName);
		[sforce describeSObject:@"Task"
			failBlock:^(NSError *err) {
				[[NSAlert alertWithError:err] runModal];
			}
			CompleteBlock:^(ZKDescribeSObject *result) {
				NSLog(@"url for the new Task page is %@", [result urlNew]);	
			}];
}];

ZKSObject *contact = [ZKSObject withType:@"Contact"];
[contact setFieldValue:@"Fell" field:@"LastName"];
[contact setFieldValue:@"Simon" field:@"FirstName"];
[sforce create:@[contact]
		failBlock:^(NSError *err) {
			[[NSAlert alertWithError:err] runModal];
		}
		CompleteBlock:^(NSArray *result) {
	        ZKSaveResult *sr = result[0];
			if ([sr success])
				NSLog(@"new contact id %@", [sr id]);
			else
				NSLog(@"error creating contact %@ %@", [sr statusCode], [sr message]);
		}
	];

As you can see, methods that call the Salesforce API endpoints are asynchronous with block based callbacks. By default callbacks are on the main thread/queue.

ZKSforceClient.h documents the core features of the client, in addition many of the API calls are contained in ZKSforceBaseClient+Operations.h

If you're not familiar 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 & SoqlX.

Download

You can now download the source code from its new home on GitGub.

Project setup

In order to support usage on both OSX & iPhone OS (so iPhone, iPod Touch, iPad), the library now uses libxml as its XML parser rather than NSXML, which isn't fully implemented on iOS. Once you've added all the .h & .m files to your project, you'll need to goto the build settings and add /usr/include/libxml2 to the Header Search Paths, and add libxml2.dylib to the linked frameworks section, and then you should be good to go. Also on OSX you'll need to add the Security.Framework to the list of frameworks to link against.

Alternatively you can use Cocoapods to automatically set this up for you.