DevOps Automation

 View Only

Salesforce Integration with IBM UrbanCode Deploy

By Laurel Dickson-Bull posted Wed July 27, 2022 10:15 AM

  

This article was originaly published in 2017.05.02

IBM offers an Automation Plug-in for integrating Salesforce with UrbanCode Deploy. In this post, we will examine the different steps and their use-cases, as well as best practices for configuring deployments to Salesforce. Force.com is a platform-as-a-service (PaaS) offering for creating and deploying secure, scalable, extendable, and backed-up cloud applications. The driving component of the UrbanCode Deploy Salesforce integration is the Force.com Migration Tool. With the plug-in, all of the benefits of the migration tool are available within UrbanCode Deploy, as well as:

  • Versioning of metadata changes as deployable artifacts
  • A graphical process designer for calling migration tool commands alongside any other command
  • The ability to define and reference properties in retrieve and deploy commands
  • Visibility into environment inventory for an application
  • Integration and consistency with broader deployment policies in the organization
  • Deployment of metadata directly from SCM via CodeStation

Contents

Getting Started

Compatibility

The following software products and versions are required for running the Salesforce integration on an IBM UrbanCode Deploy server:

  • IBM UrbanCode Deploy 6.0+
  • Apache Ant 1.6+
  • SalesForce.com Force Migration Tool 34.0+
The plug-in can be downloaded here. The Force Migration Tool jar can be downloaded here. Once the Force Migration Tool is downloaded, the archive can be unzipped to disclose the ant-salesforce.jar. This file must then be placed on the agent machine, to be referenced by the Jar Path property in each plug-in step. It is easiest to set this value as a property on the agent resource, such as sfdc.jarPath which can be referenced as ${p:resource/sfdc.jarPath}.

Plugin Capabilities

Beginning with Version 5, the plug-in offers the following steps:


 Salesforce Automation Plug-in Steps

For a detailed breakdown of plug-in steps, properties, and descriptions, refer to the Salesforce Plug-in Steps documentation page.

Application, Environment, and Component Configuration

Modeling of the application, environment, and components can be done in a variety of ways, depending on specific user goals. As a basic example, one application can be created which contains all of the Salesforce Orgs as environments, with different code packages represented as components. In the example below, I will be using one application, environment, and component. The application will have two processes, one which will retrieve the package from my unpackaged directory and store it as a version on my component. The other application process will install the component as a Deployment Process, which will be deploying to Salesforce.

Properties can be used by UrbanCode Deploy to simplify process configuration. Required fields, such as the Salesforce URL, Username, Password, and Token should always be defined at the property level to make things easier. See the below example of our salesforce component resource property definitions:

 Salesforce fields as Component Resource Property Definitions

Authenticating to Salesforce Force Migration Tool

Authenticating within the Salesforce plug-in involves using the proper credentials to authenticate to the Force Migration Tool. This is slightly different from that of the Salesforce Web UI. Using Web UI credentials will likely result in the error: Caused by: LoginFault [ApiFault exceptionCode='LOGIN_MUST_USE_SECURITY_TOKEN']. To get a security token, go to the Salesforce Web UI, click on Username -> My Settings -> Personal -> Reset My Security Token. This will send an email with a 25-character security token which can then be appended to the end of the Salesforce password within the plugin. If using properties, this can be automatically referenced in the password field as ${p:resource/sfdc.password}${p:resource/sfdc.token}.

Example Retrieval and Deployment

Before deploying, we must have a salesforce code package which can be deployed. There are many ways to go about this with UrbanCode Deploy. To Deploy directly from a repository managed outside of UrbanCode Deploy, please skip ahead to the deploy step configuration for how to deploy these files.


Retrieving a Salesforce Codepkg into Codestation

Since the 'retrieve' step in the Force Migration Tool overwrites all contents of the directory it is retrieving to, one option is that we can retrieve those files and create a component version immediately after, with the directory contents as version artifacts. The packages must be located in folders which are accessible by the agent machine. Another option is configuring the component to use Source Configuration Management (SCM) which stores the package.xml. These can be imported as component versions and downloaded with 'Download Artifacts' on your component process. The next step can retrieve the code package with 'Retrieve', and then the package can be uploaded back to the Component Version with the 'Upload Artifacts' step. The Bulk Retrieve step allows the user to download many packages at once that share a common metadata type. The Retrieve step gives us the option to pull packaged or unpackaged contents into a directory, which we can reference at deploy time. The following is my example component process configuration for retrieving unpackaged code and placing it in a folder, where it is uploaded to codestation where it can be deployed from later.

 Example Package Retrieval and Version Storage

Taking a look inside the steps, we can see that the unpackaged contents are pulled from /ibm/sample/unpackaged/package.xml, placed in my deployment codepkg folder location /ibm/sample/codepkg. This target folder is set to the same location that I will upload my version artifacts from.

Example Retrieve Step getting unpackaged contents

For the Version creation, the name will need to be updated each time a package is retrieve to differentiate the versions. This can be done with incremental naming or random IDs as needed. For this example, I am simply using the static name 'sample-codepkg'.


Example Version Creation with Code Package Artifact Upload

This method is advantageous because every time we retrieve the unpackaged contents into our ibm/sample/codepkg folder, they are overwritten. Since we are creating a version with the artifacts every time we retrieve and overwrite them, all of the older versions can always be conveniently referenced at any time in UrbanCode Deploy.

 Example of codepkg artifacts uploaded as component version artifacts

Deploying to Salesforce

Now that the package has been retrieved and stored as a Component Version, we will have a Deployment Process for deployment to our environments. The following component process configuration can be implemented to download the version artifacts that we have stored in codestation, and deploy them to the Salesforce platform:


 Example Component Process Configuration for Salesforce Deployment

For the Download Artifacts step, we can use the default configuration for downloading from the version of the component which we are installing, as such:


 Default Configuration for Download Artifacts

The Deploy step will then look something like the following screenshot once the artifacts are downloaded. Notice the 'Test Level' field. This feature allows us to run tests in our organization. For this case, NoTestRun is selected, since we don't have any tests associated with our deployment. However, the following options are available:

  • NoTestRun - No tests are run.
  • RunSpecifiedTests - Run only tests specified in the 'Test Names' field.
  • RunLocalTests - All tests in your organization are run, except the ones that originate from installed managed packages.
  • RunAllTestsInOrg - All tests are run. The tests include all tests in your organization, including tests of managed packages.

 Example Deploy Step Configuration

Once we have successfully deployed our codepkg to Salesforce, we can see the successful deployment on the Salesforce Web UI, within Deploy -> Deployment Status.

 Example UCD Deployment Execution


 Example of Successful Deployment from UCD in the Salesforce Web UI

Deploy Recent Validation

The Salesforce plug-in also contains the ability to Deploy Recent Validation, meaning that the deployment tests are not re-run and deployments can be done faster by giving it the ID of a recently validated deployment. This ID can be obtained by simply checking 'Check Only' property on the Deploy step. The ID is stored as an output property on this step, and can be referenced later by the Deploy Recent Validation step as ${p:DeployStepName/recentValidationID}. For further documentation on how to implement this, see this page.


#UrbanCodeDeploy
#Salesforce
0 comments
10 views

Permalink