Tool to index a Salesforce org and create a package.xml - with additional perks & benefits
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
docs Rename README.md to index.md Feb 15, 2019
properties Added back test class for command line with additional parameters. Feb 19, 2019
src Removed SimpleXMLDoc wrapper from project, replaced with DOMBuilder Feb 19, 2019
.gitignore Added code to fetch user data from org Nov 30, 2018
PackageBuilder.jar
README.md Updated Readme.MD after filter parameter changes Feb 13, 2019
buildPackageBuilder.xml Update of build locations for new workstation Oct 19, 2018
pom.xml

README.md

PackageBuilder

This is a tool for salesforce.com. It can do one of two things:

  • connect to an org and generate a package.xml that can subsequently be used with the Force.com Migration Tool to extract code and metadata from an org.
  • examine a directory containing an unzipped Force.com Migration Tool package and generate a package.xml

Usage:

java -jar PackageBuilder.jar [-o <parameter file1>,<parameterfile2>,...] [-u <SF username>] [-p <SF password>] [-s <SF url>] [-a <apiversion>] [-mi <metadataType1>,<metadataType2>,...] [-sp <pattern1>,<pattern2>,...] [-d <destinationpath>] [-v]

or

java -jar PackageBuilder.jar -d <destinationpath> -b <packagePath>
  • -o,--orgfile <arg>
    file containing org parameters (see below)
  • -u,--username <arg>
    username for the org (someuser@someorg.com)
  • -p,--password <arg>
    password for the org (t0pSecr3t)
  • -s,--serverurl <arg>
    server URL for the org (https://login.salesforce.com)
  • -a,--apiversion <arg> api version to use, will default to 38.0
  • -mi,--metadataitems <arg>
    metadata items to fetch (commaseparated list of metadata types in package.xml naming). If this parameter is not provided, PackageBuilder will query the org and inventory everything a Metadata Describe returns to it.
  • -d,--destination <arg>
    directory where the generated package.xml will be written
  • -b,--basedirectory <arg>
    directory where the the code will look for a SFDC package structure (e.g. classes folder, objects folder, etc.)
  • -v,--verbose output verbose logging instead of just core output
  • -c,--includechangedata include data on who last changed the item directly in the members tag of every item of the package.xml
  • -mx,--maxitems <arg>
    max number of items to put into a single package.xml (10000 is current max enforced by SF platform, for API 33 and higher, 5000 before)

Filtering what goes in the package

  • -sp,--skippatterns <arg>
    name patterns to skip when fetching.
  • -ip,--includepatterns <arg>
    name patterns to skip when fetching

When filtering by item name, the PackageBuilder will create an artificial name by prepending the metadata type to the actual item name, so e.g. the Opportunity field My_field__c will be represented internally as CustomField:Opportunity.My_field__c. This enables writing more precise patterns like CustomField:Opportunity.* which will filter all custom fields on the Opportunity object, as opposed to the pattern .*Opportunity.* which would match anything and everything associated with the Opportunity object and beyond (e.g. an Account field called Parent_Opportunity__c).

Multiple patterns can be provided separated by commas. Unpredictable behavior if your pattern includes commas.

  • -se,--skipemail <arg>
    email patterns to skip when fetching.
  • -ie,--includeemail <arg>
    email patterns to skip when fetching
  • -su,--skipusername <arg>
    email patterns to skip when fetching.
  • -iu,--includeusername <arg>
    email patterns to skip when fetching

This filter works against the email/name of the user who is the last to have modified a given item.

  • -fd,--fromdate <arg>
    date (YYYY-[M]M-[D]D). All items modified on or after this date (and respecting the td flag) will be included in the result
  • -td,--todate <arg>
    date (YYYY-[M]M-[D]D). All items modified before or on this date (and respecting the fd flag) will be included in the result

All parameters can be provided in parameter files specified with the -o parameter. More than one file can be provided (as in the example below, where one file would define what to fetch, skippatterns, etc., and the other where to fetch from). If any parameters are provided both in files and on the command line, the command line ones will be used.

Property file format

The property files use standard Java property file format, i.e. parameter=value. E.g.

# equivalent to -a commandline parameter
apiversion=44.0
# equivalent to -mi commandline parameter
metadataitems=ApexClass, ApexComponent, ApexPage
# equivalent to -s commandline parameter
sf.serverurl=https://login.salesforce.com
# equivalent to -u commandline parameter
sf.username=my@user.name
# equivalent to -p commandline parameter
sf.password=t0ps3cr3t
# equivalent to -sp commandline parameter
skipItems=.*fflib_.*,.*Class:AWS.*,ApexPage.*
# equivalent to -d commandline parameter
targetdirectory=src
Yes, I know that the property file parameters should be better aligned to the longnames of the commandline parameters. Coming in a future version!

Example:

java -jar PackageBuilder.jar -d src -o packagebuilder.properties,org.properties -a 39.0

Will run the packagebuilder outputting package.xml to the src folder, using parameters specified in the packagebuilder.properties and org.properties

java -jar PackageBuilder.jar -d src -o packagebuilder.properties,org.properties -a 44.0 -c

Will run the packagebuilder outputting package.xml to the src folder, using parameters specified in the packagebuilder.properties and org.properties.

In addition, instead of outputting e.g. <members>ChangePasswordController</members>

will output

<members lastmodifiedby="John Doe" lastmodified="2018-10-14T20:45:13"" lastmodifiedemail="johndoe@example.com">ChangePasswordController</members>

java -jar PackageBuilder.jar -d dst -b src

Will run the packagebuilder, inventory the src directory and write a dst/package.xml file corresponding to the (recognized) content in the directory

See properties files for additional detail - should be self-explanatory

Use of changedata parameter

The changedata parameter will augment the generated package.xml file with data about who/when last changed the given metadata item. So instead of getting

<name>CustomField</name>
<members>Account.Active__c</members>
<members>Account.CustomerPriority__c</members>

you will get

<name>CustomField</name>
<members lastmodified="2018-08-30T09:28:58" lastmodifiedby="Kim Galant"  lastmodifiedemail="kim.galant@salesforce.com">Account.Active__c</members>
<members lastmodified="2018-08-30T09:28:58" lastmodifiedby="Kim Galant"  lastmodifiedemail="kim.galant@salesforce.com">Account.CustomerPriority__c</members>

Note that this adds a lastmodified attribute which contains the last change date of that item, the name and email of the user who changed it (from the SF User table). If this package.xml file is used for a retrieve, Salesforce (as of API 44) will happily ignore the additional attributes. They are added to help provide additional insight about who last touched each individual item.