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:

``shell
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:

`js
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

$3


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

`js
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
},
},
})
`

$3

#### 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.

$3

#### Single Org Deploy
In this example, we will deploy all static resources to a single org

`js
grunt.initConfig({
antdeploy: {
options: {},
// specify one deploy target
dev1: {
options: {
user: 'myusername@test.com',
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

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

The "antretrieve" task

$3


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

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

$3

#### 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

$3

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

`js
grunt.initConfig({
antretrieve: {
options: {
user: 'myusername@gmail.com',
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

`js
grunt.initConfig({
antretrieve: {
options: {
root: 'metadata/',
version: '27.0'
},
// specify one deploy target
dev1all: {
options: {
user: 'myusername@gmail.com',
pass: 'mypassword',
token: 'myauthtoken',
},
pkg: {
staticresource: ['*'],
apexclass: ['*'],
apexpage: ['*']
}
},
dev1classes: {
options: {
user: 'myusername@gmail.com',
pass: 'mypassword',
token: 'myauthtoken'
},
pkg: {
apexclass: ['*']
}
},
dev1module: {
options: {
user: 'myusername@gmail.com',
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)_