Top 10 Force.com Metadata API Lessons Learned - February 19, 2009 at 11:18 am

You can follow Reid Carlberg on Twitter.

Developing Cloud Converter has been a great excuse for me to get deeper into the Salesforce.com / Force.com Metadata API.  Although working with it isn’t rocket science, I’ve come across a few interesting tidbits I thought I would share.  Before I get too deep into this, I should encourage you to read the docs – they’re pretty useful and contain some very useful sample code.

1. Know when to use the standard API’s “Describe” functionality instead of the Metadata API.  In general, the various “describe” calls will give you a great READ ONLY view into your metadata.  If you don’t need to create, update or delete, use Describe.  Otherwise, use the Metadata API. Oh and you’ll want the Metadata API for developer stuff – Apex, Visualforce, etc.

2. Keep in mind that the Metadata API has a different set of limitations and conventions than the standard API.  For example, the standard API is generally synchronous while the Metadata API is asynchronous.  The standard API lets you do several hundred operations at once.  The Metadata API, 10. 

3. Object types matter.  In the Partner WSDL with the standard API, you use generic SObjects and can often combine object types into a single operation.  Not so in the Metadata API.  In the Metadata API, when you’re working with Custom Objects, you can only work with Custom Objects.  You can’t, for example, mix in Custom Fields.

4.  Sequence matters.  For example, you have to create a Custom Object before you can create Custom Fields or a Custom Tab. 

5.  Naming conventions matter.  For example, some object use Dot Notation in the name, others use Hyphen Notation – the same as Dot but with a Hyphen.  For example, if you want to specify that a custom field should be on a particular custom object, MyField on MyObject, for example, you specify a name of “MyObject__c.MyField__c” and the Metadata API will handle it.  On the other hand, if you want to create a Layout called “My Object Layout” for MyObject__c, you would give it a full name of “MyObject__c-My Object Layout”.

6.  The Metadata API is hackable.  No, not in the War Games way (to be honest, I haven’t tried) – hackable in that you can force it to do some interesting things in ways other than specified in the docs if you get stuck.  For example, in Cloud Converter, I decided I didn’t want to go through the trouble of editing the default layout.  Instead, I created a new one and used the Metadata API’s “update” method.  Worked great!

7. Use the source.  I only figured out the hackable part after I spent some time looking at the Metadata XML files you can download from Force.com.  They’re pretty easy to read and will very likely clear up any trouble you’re having figuring out how to do what you want to do.

8.  The Metadata API appreciates some TLC.  You will occasionally need to do things other than the core “create”, “update” and “delete” functions.  For example, I found that I had to bounce my Metadata API session from time to time.  Once was when I was finished creating the fields and needed to then build a layout. The Metadata API was unaware of those fields until I bounced it.  Another example is that I needed to let the system sleep for a bit between creating the custom tab and loading data.  A third example was when I wanted to create Lookup fields.  When I created those in the same call as the regular fields, it failed.  When I segmented them out to their own create call, it worked.  None of these were big deals – just something to keep in mind.

9.  The Metadata API is very literal.  For example, if you create a new custom tab, it will create a tab.  And that tab will be hidden from all profiles until you tell it otherwise.  There are probably a few other things like this.  I’ve been updating this profile setting manually when testing required me to.  See #10 for how stupid this was.

10. The Metadata API is powerful.  If you’re doing something manually that’s vaguely related to metadata, stop.  You can probably do it with the Metadata API and save yourself a bunch of time.  For example, if you, unlike me, read the docs when you ran into the profile / custom tab issue in #9, you would have found the “ProfileTabVisibility” object designed to handle just that. 

That should get you started.  If you run into any other hints or lessons learned I’d love to hear about them.  Feel free to email or comment.

Good luck!

RSS

Tags: API, force.com, lessons learned, metadata