Skip to content

1.1 How It Works

Jump to bottom
Patrick Connelly edited this page Nov 12, 2013 · 14 revisions

This page describes how Solenopsis works and various concepts.

Environments

Solenopsis views your orgs in terms of environments. Why environments versus org? If you happen to be a developer, its conceivable you are working locally on your file system. By using the concept of an environment, this encapsulates the notion of an org and your local file system - both are a type of environment.

Master/Dependent Environments?

The idea of a master and dependent environment depends upon the actions being performed:

  • When pushing to an org, you push from a master to a dependent. Master can either be a local development directory or an org. If you are using an org, you may want to pull-full from the master org prior to pushing out to the dependent as the master org may have changes on it that are not reflected locally (please see Org Representation below for further information). As a side note, you never push from a master org to a local file system, instead you consider your local file system as master and pull to it.
  • When pulling, you are always pulling from a dependent org - period. There is no way to denote your local file system as a dependent environment!

Operations

This section describes operations used within Solenopsis

Folder vs Non Folder

Salesforce distinguishes between folder and non-folder based operations. When retrieving or pushing files to an org you must define them differently them differently within your package.xml:

  • Folder based operations require all the files to be spelled out.
  • Non-folder based operations allow you to use the wildercard *.

Pull vs Full Pull

When performing a pull vs a full pull equates to non-folder vs folder based operations. However, the MASTER environment's files are used to compute those. For example, for folder based operations, the files are consulted and used to populate the package.xml appropriately.

Push vs Full Push

When performing a push vs a full-push equates to non-folder vs folder based operations. For full pushes, the folder based files are computed and denoted in the generated package.xml. For pushes, only those members that support asterisks will be included in the generated package.xml.

Variable Substitution

Solenopsis supports the notion of variable substitution when performing pushes.

Built-in Variables

There are currently two built-in variables that can be placed within your source tree:

  • @{siteAdmin} - if the property solenopsis.deploy.env.siteAdmin is defined, the value will be used for replacement. If not, the depdendent org's user name will be chosen.
  • @{senderAddress} - if the property solenopsis.deploy.env.senderAddress is defined, the value will be used for replacement. If not, the dependent org's user name will be chosen.

You may define both properties siteAdmin and senderAddress in your individual credentials files. Those values will be used if you do so.

siteAdmin is useful for scenarios where you have sites and need to provide a user name as the site admin. For example:

<CustomSite xmlns="http://soap.sforce.com/2006/04/metadata">
    ...
    <siteAdmin>@{siteAdmin}</siteAdmin>
    ...
</CustomSite>

senderAddress is useful for scenarious where you need an email address (for example in workflows):

<senderAddress>@{senderAddress}<senderAddress/>

All you need to do is denote the above variables names in the appropriate files and a replace will be performed for you on push. Please note that the variable names must be contained within @{ and }.

User Defined Variables

Any properties defined within your credentials file(s) can also be used for variable substitution within your local files. To do so, use the property name within a @{ and }.

For example, assume you have this property denoted in your credentials file:

MyMessage = Hello World!!!

Also assume you have the following fictitious class FooBar containing the following:

public class FooBar {
    public static void emitHello() {
        System.debug("I am saying @{MyMessage}");
    }
}

Upon push, the class will resemble:

public class FooBar {
    public static void emitHello() {
        System.debug("I am saying Hello World!!!");
    }
}

Org Representation

Local Files

Solenopsis operates on representations of your org, which are stored locally in the directory found in the property solenopsis.env.HOME/env/[name]. The bracketed name represents a value in the space delimited list of values contained in the property solenopsis.ENVIRONMENTS which serves two purposes:

  1. As a name for the properties file containing your credentials for an org. All credentials can be found in the directory as denoted in the property solenopsis.env.credentials.HOME and named [name].properties. The key/values of the credentials properties can be found below.
  2. As the name of the directory to store the contents of your org. All local copies of orgs are stored in the base directory name found in solenopsis.env.HOME - the org copy will be in a child directory entitled [name].

Explicitly Denote Where to Store Files

When Solenopsis looks for the files of an environment, it will refer to the property solenopsis.env.[name].HOME. If this property is not defined, it defaults to [solenopsis.env.HOME]/env/[name].

You may notice that we refer to an environment entitled local. This just happens to be the name we chose to denote our local development directory, which becomes our master environment. You can choose any name you wish - but local seemed appropriate.

When are Properties Loaded?

When you kick off any Solenopsis command, properties are applied in the following order:

  • Load those from command line arguments (via -D Ant options).
  • Load those from ~/solenopsis.properties.
  • Load those from the operating system.
  • Load those from [solenopsis install dir]/ant/solenopsis-setup.xml.
  • Load those from [solenopsis install dir]/ant/rh-util.xml.
  • Load those from [solenopsis install dir]/ant/sfdc-util.xml.

Properties will not be overridden - so if you define your intention in ~/solenopsis.properties, your value will "stick."

Please note: some Ant properties will not be settable in operating systems as the notation may not adhere to acceptable standards - for example solenopsis.env.HOME is not settable in Linux.

Credentials Property Structure

All credentials files use the following properties:

  • username: your username for that org.
  • password: your password for that org.
  • token: your security token for that org.
  • url: the URL for login

Example

Building upon the information above, below is an example representation of a Solenopsis setup/configuration. You will notice:

  • A solenopsis properties file denoting the environments: one sandbox (mydev), a production instance (prod) and a local environment (development environment local).
  • Solenopsis will store both the production org in the directory /home/myuser/.solenopsis/env/prod and sandbox in /home/myuser/.solenopsis/env/mydev.
  • The development directory is /home/myuser/dev/sfdc/src and is denoted as the local environment and master.
  • There are two credentials files for the sandbox and production orgs as denoted in the directory /home/myuser/.solenopsis/credentials: prod.credentials and mydev.credenitals.
/
+- home/
   +- myuser/
      +- solenopsis.properties
         +- solenopsis.ENVIRONMENTS   = mydev prod local
            solenopsis.env.HOME       = /home/myuser/.solenopsis
            solenopsis.env.MASTER     = local
            solenopsis.env.DEPENDENT  = mydev
            solenopsis.env.local.HOME = /home/myuser/dev/sfdc/src

      +- .solenopsis/
         +- env/
            +- mydev/
            +- prod/

         +- credentials/
            +- mydev.credentials
               +- username  = [email protected]
                  password  = my-bad-password
                  token     = abCdEfGhIjKlMnOpQrStUv123
                  url       = https://test.salesforce.com

            +- prod.credentials
               +- username  = [email protected]
                  password  = my-extra-bad-password
                  token     = 1234567890AbCdEfGhIjKlMnO
                  url       = https://login.salesforce.com

      +- dev/
         +- sfdc/
            +- src/

Adding more orgs is as simple as creating a new credentials property file and adding the name to the solenopsis.ENVIRONMENTS property!

Please click here for more information on configuration.

Clone this wiki locally