grunt-ant-sfdc

Add salesforce and force.com ANT tasks to your grunt builds

Getting Started

This plugin requires Grunt ~0.4.0

If you haven't used Grunt before, be sure to check out the Getting Started guide, as it explains how to create a Gruntfile as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin with this command:

npm install grunt-ant-sfdc --save-dev

One the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:

grunt.loadNpmTasks('grunt-ant-sfdc');

Options for all tasks

The following are options that can be defined for all tasks...

options.user

Type: String Required: true Your Salesforce.com username

options.pass

Type: String Required: true Your Salesforce.com password

options.token

Type: String Your Salesforce.com password

options.sessionid

Type: String Your Salesforce.com session id

options.serverurl

Type: String Default value: 'https://login.salesforce.com' This option sets the api version to use for the package deployment

options.pollWaitMillis

Type: Integer Default value: 10000 This option sets the number of milliseconds to wait between polls for retrieve/deploy results.

options.maxPoll

Type: Integer Default value: 20 This option sets the number of polling attempts to be performed before aborting.

options.apiVersion

Type: String Default value: '29.0' This option sets the api version to use for the package deployment

options.useEnv

Type: Boolean Default value: false This option will tell the task to look in environment variables for your Salesforce authentication details. This is really handy for making things secure and not having to put your login details in the Gruntfile. Make sure you set your username SFUSER, password SFPASS, and optionally your token SFTOKEN

options.sessionConfig

Type: Object Default value: null If you develop using sublime text and mavensmate then you can share your session data with the grunt-ant-sfdc plugin. Simply set your options configuration like so: sessionConfig: grunt.file.readJSON('config/.session')

options.proxy_http

Type: String This options will set the proxyhost of ant before running any of the tasks. See https://ant.apache.org/manual/Tasks/setproxy.html

options.proxy_port

Type: Integer Default value: 80 This option will see the proxyport of ant befor running any of the tasks. If no proxy_http is set, then the port is not set. See https://ant.apache.org/manual/Tasks/setproxy.html

The "antdeploy" task

Overview

In your project's Gruntfile, add a section named antdeploy to the data object passed into grunt.initConfig().

grunt.initConfig({
  antdeploy: {
    options: {
      // Task-specific options go here.
    },
    your_target: {
      // Target-specific file lists and/or options go here.
      pkg: {   // Package to deploy
        apexclass: ['*'],
        staticresource: ['*']
      },
      tests: ['TestClass1', 'TestClass2'] // Optional tests to run
    },
  },
})

Task-specific options

options.root

Type: String Default value: 'build/' The root options sets the base directory where metadata lives

options.checkOnly

Type: Boolean Default value: false This option sets whether this is a checkOnly deploy or not

options.runAllTests

Type: Boolean Default value: false This option sets whether or not to run all tests

options.rollbackOnError

Type: Boolean Default value: true This option sets whether or not to roll back changes on test error

options.existingPackage

Type: Boolean Default value: false This option will tell the task to assume a package.xml file exists in the root folder. If this option is true the pkg data provided to the task will be ignored and a new package.xml file will not be generated. This allows you to reuse a package.xml file that may be present in your project.

Usage Examples

Single Org Deploy

In this example, we will deploy all static resources to a single org

grunt.initConfig({
  antdeploy: {
    options: {},
    // specify one deploy target
    dev1: {
      options: {
        user:      '[email protected]',
        pass:      'mypassword',
        token:     'mytoken',
        serverurl: 'https://test.salesforce.com' // default => https://login.salesforce.com
      },
      pkg: {
        staticresource: ['*']
      }
    }
  }
})

Multiple Org Deploy w/ Default Options

In this example, we specify two different org deploy targets with different metadata for each

grunt.initConfig({
  antdeploy: {
    options: {
      root: 'my/metadata/', // note trailing slash is important
      version: '27.0'
    },
    // specify one deploy target
    dev1: {
      options: {
        user:  '[email protected]',
        pass:  'mypassword',
        token: 'mytoken'
      },
      pkg: {
        staticresource: ['*']
      }
    },
    dev2: {
      options: {
        user:  '[email protected]',
        pass:  'mypassword2',
        token: 'mytoken2'
      },
      pkg: {
        staticresource: ['*']
      }
    }
  }
})

The "antretrieve" task

Overview

In your project's Gruntfile, add a section named antretrieve to the data object passed into grunt.initConfig().

grunt.initConfig({
  antretrieve: {
    options: {
      // Task-specific options go here.
    },
    your_target: {
      // Target-specific file lists and/or options go here.
      pkg: {
        // Package to retrieve
      }
    },
  },
})

Task-specific options

options.root

Type: String Default value: 'build/' The root option sets the base directory where metadata lives

options.retrieveTarget

Type: String Default value: root This sets the target directory for the retrieve. This will default to the root if not set.

options.unzip

Type: Boolean Default value: true This set whether or not the retrieve should be unzipped upon completion

options.existingPackage

Type: Boolean Default value: false This option will tell the task to assume a package.xml file exists in the root folder. If this option is true the pkg data provided to the task will be ignored and a new package.xml file will not be generated. This allows you to reuse a package.xml file that may be present in your project.

options.packageNames

Type: String This options will retrieve all components from a package from Salesforce with the same name. If populated, options.existingPackage and pkg will be ignored. See https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/apex_deploying_ant_retrieveCode.htm

Usage Examples

Single Org Retrieve

In this example, we will retrieve all static resources, classes, and apexpages from a single org

grunt.initConfig({
  antretrieve: {
    options: {
      user: '[email protected]',
      pass: 'mypass'
    },
    // specify one retrieve target
    dev1: {
      serverurl:  'https://test.salesforce.com' // default => https://login.salesforce.com
      pkg: {
        staticresource: ['*'],
        apexclass:      ['*'],
        apexpage:       ['*']
      }
    }
  }
})

Single Org, multiple retrieve example

In this example, we specify one org but multiple retrieve targets

grunt.initConfig({
  antretrieve: {
    options: {
      root:    'metadata/',
      version: '27.0'
    },
    // specify one deploy target
    dev1all: {
      options: {
        user:  '[email protected]',
        pass:  'mypassword',
        token: 'myauthtoken',
      },
      pkg: {
        staticresource: ['*'],
        apexclass:      ['*'],
        apexpage:       ['*']
      }
    },
    dev1classes: {
      options: {
        user:  '[email protected]',
        pass:  'mypassword',
        token: 'myauthtoken'
      },
      pkg: {
        apexclass: ['*']
      }
    },
    dev1module: {
      options: {
        user:  '[email protected]',
        pass:  'mypassword',
        token: 'myauthtoken'
      },
      pkg: {
        apexclass:      ['MyClass', 'MyClassTest'],
        apexpage:       ['MyPage'],
        staticresource: ['MyPageResource'],
        apextrigger:    ['MyObjectTrigger']
      }
    }
  }
})

Contributing

In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using Grunt.

Release History

(Nothing yet)