Home

Awesome

nforce-metadata

An nforce plugin that facilitates working with the metadata api

Installation

First, install nforce-metadata with npm

$ npm install nforce-metadata

Load the plugin

var nforce = require('nforce');

// load the nforce-metadata plugin
require('nforce-metadata')(nforce);

var org = nforce.createConnection({
  clientId: '<client_id>',
  clientSecret: '<client_secret>',
  redirectUri: '<redirect_uri>',
  username: process.env.SFUSER,
  password: process.env.SFPASS,
  metaOpts: {       // options for nforce-metadata
    interval: 2000  // poll interval can be specified (optional)
  },
  plugins: ['meta'] // loads the plugin in this connection
});

Usage

nforce-metadata allows you to make requests to the Salesforce Metadata API just as easily as you can make requests to the REST API using the nforce base module.

The methods are all under the meta namespace in the connection object. Here is an example call.

org.authenticate().then(function(){
  return org.meta.listMetadata({
    queries: [
      { type: 'CustomObject' },
      { type: 'CustomField' },
      { type: 'ApexClass' }
    ]
  });
}).then(function(meta) {
  _.each(meta, function(r) {
    console.log(r.type + ': ' + r.fullName + ' (' + r.fileName + ')');
  });
}).error(function(err) {
  console.error(err);
});

Just like nforce v1.0.0 and higher, you can either supply a callback to the api methods or you can omit the callback and use the returned Promise for async control flow.

See, callbacks work too...

var md = [
  { 
    fullName: 'Test_Obj__c.Foo__c',
    label: 'Foo Bar',
    length: 100,
    type: 'Text'
  }
];

org.meta.createMetadata({ type: 'CustomField', metadata: md }, function(err, res) {
  if(err) return console.error(err);
  console.log(res);
});

Pollers

deployAndPoll() and retrieveAndPoll() calls automatically poll for status updates. A poller EventEmitter object is returned that provides and evented interface the the polling. Using the poller is quite easy. Here is an example.

org.authenticate().then(function(){
  var archive = archiver('zip')
    .directory('examples/src', 'src')
    .finalize();

  var promise = org.meta.deployAndPoll({
    zipFile: archive
  });

  promise.poller.on('poll', function(res) {
    console.log('poll status: ' + res.status);
  });

  return promise;
}).then(function(res) {
  console.log('completed: ' + res.status);
}).error(function(err) {
  console.error(err);
});

Examples

Many example files are included in the examples/ directory. To run the examples, make sure that you have your SFUSER and SFPASS environment variables set to your Salesforce username and password respectively.

Connection API

meta.deploy(opts, [callback])

Deploy metadata to a Salesforce organization.

[Salesforce Documentation] (https://www.salesforce.com/us/developer/docs/api_meta/Content/meta_deploy.htm)

opts:

meta.deployAndPoll(opts, [callback])

Performs a deploy() and also returns a poller that polls checkDeployStatus().

opts:

poller events:

meta.checkDeployStatus(opts, [callback])

Checks the status of declarative metadata call deploy().

[Salesforce Documentation] (https://www.salesforce.com/us/developer/docs/api_meta/Content/meta_checkdeploystatus.htm)

opts:

meta.cancelDeploy(opts, [callback])

Cancels a deployment that hasn’t completed yet.

[Salesforce Documentation] (https://www.salesforce.com/us/developer/docs/api_meta/Content/meta_canceldeploy.htm)

opts:

meta.cancelDeployAndPoll(opts, [callback])

Performs a cancelDeploy() and also returns a poller that polls checkDeployStatus().

opts:

meta.retrieve(opts, [callback])

This call retrieves XML file representations of components in an organization.

[Salesforce Documentation] (https://www.salesforce.com/us/developer/docs/api_meta/Content/meta_retrieve.htm)

opts:

meta.retrieveAndPoll(opts, [callback])

Performs a retrieve() and also returns a poller that polls checkRetrieveStatus().

opts:

poller events:

meta.checkRetrieveStatus(opts, [callback])

Checks the status of declarative metadata call retrieve() and returns the zip file contents.

[Salesforce Documentation] (https://www.salesforce.com/us/developer/docs/api_meta/Content/meta_checkretrievestatus.htm)

opts:

meta.createMetadata(opts, [callback])

Adds one or more new metadata components to your organization synchronously.

[Salesforce Documentation] (https://www.salesforce.com/us/developer/docs/api_meta/Content/meta_createMetadata.htm)

opts:

meta.readMetadata(opts, [callback])

Returns one or more metadata components from your organization synchronously.

[Salesforce Documentation] (https://www.salesforce.com/us/developer/docs/api_meta/Content/meta_readMetadata.htm)

opts:

meta.updateMetadata(opts, [callback])

Updates one or more metadata components in your organization synchronously.

[Salesforce Documentation] (https://www.salesforce.com/us/developer/docs/api_meta/Content/meta_updateMetadata.htm)

opts:

meta.upsertMetadata(opts, [callback])

Creates or updates one or more metadata components in your organization synchronously.

[Salesforce Documentation] (https://www.salesforce.com/us/developer/docs/api_meta/Content/meta_upsertMetadata.htm)

opts:

meta.deleteMetadata(opts, [callback])

Deletes one or more metadata components from your organization synchronously.

[Salesforce Documentation] (https://www.salesforce.com/us/developer/docs/api_meta/Content/meta_deleteMetadata.htm)

opts:

meta.renameMetadata(opts, [callback])

Renames a metadata component in your organization synchronously.

[Salesforce Documentation] (https://www.salesforce.com/us/developer/docs/api_meta/Content/meta_renameMetadata.htm)

opts:

meta.describeMetadata(opts, [callback])

This call retrieves the metadata which describes your organization. This information includes Apex classes and triggers, custom objects, custom fields on standard objects, tab sets that define an app, and many other components.

[Salesforce Documentation] (https://www.salesforce.com/us/developer/docs/api_meta/Content/meta_describe.htm)

opts:

meta.listMetadata(opts, [callback])

This call retrieves property information about metadata components in your organization. Data is returned for the components that match the criteria specified in the queries parameter. The queries array can contain up to three ListMetadataQuery queries for each call. This call supports every metadata type: both top-level, such as CustomObject and ApexClass, and child types, such as CustomField and RecordType.

[Salesforce Documentation] (https://www.salesforce.com/us/developer/docs/api_meta/Content/meta_listmetadata.htm)

opts: