CI Development

These instructions are for the OpFocus Continuous Integration process.

[TOC]

Part 1: Installation

npm install -g @jpipkinopfocus/oci

Part 2: Project Setup

Connect to an empty Bitbucket repository

• oci start -n my_project
• cd my_project
• oci connect -s [ssh]

Connect to existing Bitbucket repository

1. oci clone -s [ssh]

Setup Bitbucket Pipelines

Configure JWT Authentication

The authentication mechanism for pipelines is JWT so setup is required for each SF org before pipelines will run properly. Please use this password when creating self-signed certificates: https://opfocus.my.salesforce.com/a060g00001lySMQ

Create Self-Signed Certificate

1. On project root: oci create-jwt -p [password] -o [org_type]
   • password => the password for self-signed certificate
   • org_type => "integration", "uat", "staging", "prod"
2. This will create a new folder in your local branch called "jwt".

Create Connected App

1. In Salesforce Setup, create a new connected app
   1. Enable OAuth Settings
   2. Set callback url to "http://localhost:1717/OauthRedirect"
   3. Select "Use digital signatures" and upload the .crt file in your local jwt/ directory
   4. OAuth Scopes:
      1. Access and manage your data (api)
      2. Provide access to your data via the Web (web)
      3. Perform requests on your behalf at any time (refresh_token, offline_access)
   5. Save "consumer key" for Bitbucket Pipelines configuration
   6. Click "Manage"
   7. Click "Edit Policies"
   8. Under "OAuth policies", change Permitted Users to "Admin approved users are pre-authorized".
   9. Click "Save"
   10. Add relevant profiles and/or permission sets that determine if a user can authorize with this connected app

Turn on Pipelines

1. Go to repository settings
2. Go to Pipelines > Settings
3. Enable Pipelines

Set up environment variables

1. Go to repository settings
2. Go to Pipelines > Repository Variables
3. Create variables for each branch. If the project does not have UAT, you do not need to create the uat variables
   1. int_un => integration username
   2. int_url => integration login url
   3. int_client_id => integration connected app's consumer key. SECURED VARIABLE
   4. uat_un => UAT username
   5. uat_url => UAT login url
   6. uat_client_id => UAT connected appe's consumer key
   7. staging_un => staging username
   8. staging_url => staging login url
   9. staging_client_id => staging connected app's consumer key. SECURED VARIABLE
   10. prod_un => production username
   11. prod_url => production login url
   12. prod_client_id => production connected app's consumer key. SECURED VARIABLE

Configure the project manifest

The package.xml is located at ./config/package.xml.

Configure the CI configurations

In the ./build/ci.config, there are settings for the Continuous Integration job.

• apiVersion => the platform API version you want to use for retrieving and deploying

Configure the user configurations

In the ./build/user.config, there are settings for your local machine.

• os => Mac or Windows

Part 3: Project commands

Authorize a SF Org

If you use an IDE that utilizes SFDX, you do not need to do anything in this section sfdx force:auth:web:login --instanceurl [login url] --setalias [org alias]

Retrieve from SF Org

oci retrieve

arguments

• -u (--alias) (String): The org alias

• -m (--metadata) (String): List of specific metadata to retrieve. See sfdx force:source:retrieve

• -p (--package) (Boolean): Indicator to use the package.xml file in the config directory

Examples

oci retrieve -u MyOrg -m ApexClass:Class1,ApexTrigger:Trigger1

oci retrieve -u MyOrg -p

oci retrieve -u MyOrg **this will retrieve any components in the force-app directory

Deploy to SF Org

oci deploy

oci validate

arguments

• -u (--alias) (String): The org alias

• -m (--metadata) (String): List of specific metadata to retrieve. See sfdx force:source:retrieve

• -f (--zipfile) (String): zipped file to deploy

• -l (--testlevel) (String): Test level for deployment

• -r (--runtests) (String): List of tests to run

Examples

oci deploy -u MyOrg -m ApexClass:Class1,ApexTrigger:Trigger1 -l RunSpecifiedTests -r MyTestClass,MyOtherTest

oci deploy -u MyOrg -f ./Archive.zip

oci deploy ** This will deploy everything in the force-app directory

NOTE: running oci validate will perform a checkonly deployment

Part 4: All Functions

start: creates an sfdx directory for a new project

• -n (--name) (String): required The name of the project

retrieve: retrieves metadata from salesforce

• -u (--alias) (String): The org alias

• -m (--metadata) (String): List of specific metadata to retrieve. See sfdx force:source:retrieve

• -p (--package) (Boolean): Indicator to use the package.xml file in the config directory

deploy: deploys metadata to salesforce

• -u (--alias) (String): The org alias

• -m (--metadata) (String): List of specific metadata to retrieve. See sfdx force:source:retrieve

• -f (--zipfile) (String): zipped file to deploy

• -l (--testlevel) (String): Test level for deployment

• -r (--runtests) (String): List of tests to run

validate: validates a deployment to salesforce

• -u (--alias) (String): The org alias

• -m (--metadata) (String): List of specific metadata to retrieve. See sfdx force:source:retrieve

• -f (--zipfile) (String): zipped file to deploy

• -l (--testlevel) (String): Test level for deployment

• -r (--runtests) (String): List of tests to run

open: opens a salesforce org in the browser

• -u (--alias) (String): The org alias to open

• -p (--page) (String): The landing page. Possible values are Lightning Setup, Lightning Home, Classic Setup, Classic Home

• -a (--ask) (Boolean): Indicates to ask which landing page to go to

connect: connects to a new git repo

• -s (--ssh) (String) Required: the ssh of the git repository

• -m (--message) (String): the initial commit message. Defaults to "initial commit"

clone: connects to an existing git repo

• -s (--ssh) (String) Required: the ssh of the git repository

• -m (--message) (String): the initial commit message. Defaults to "initial commit"

clean: purges any untracked files in your working git directory and fetches the latest from the remote

• -b (--branch) (String): the git branch to clean directory from

push: pushes commits to the repo (git push)

• no arguments

sort-package: alphabetically sorts the package.xml in the config directory

• no arguments

create-jwt: create jwt for bitbucket pipeline deployment authentication

• -p (--pw) (String): passcode for certificate

• -o (--org) (String): the sf org type. possible values are: integration, uat, staging, prod

feature: creates a feature branch

• -n (--name) (String): the name of the feature branch. "feature/" is prepended automatically to the name of the git branch created

update: updates the package version to the latest published version

verison: prints the current package version

cmdt-records: creates custom metadata type records from csv, or imports type and records from custom setting or custom object

• -u (--alias) (String): Used only for importing. The alias of the source org for custom setting or custom object transformation
• -f (--csv) (String): The path to the csv file containing record information. If this is set, you cannot import from object
• -n (--typename) (String): The custom metadata type developer name
• -d (--namecolumn) (String): Used only for CSV. The DeveloperName csv header. Defaults to "Name"
• -s (--sobjectname) (String): Used only for importing. The API Name of the object to transform into new metadata type
• -p (--plural) (String): Used only for importing. The plural label of the new metadata type
• -l (--label) (String): Used only for importing. The label of the new metadata type
• -v (--visibility) (String): Used only for importing. The visibility of the new metadata type
• -i (--ignoreunsupported) (Boolean): Used only for importing. Ignores unsupported field data types from transformation

new-cmdt: generates new custom metadata type

• -n (--typename) (String): The custom metadata type developer name
• -p (--plural) (String): The plural label of the new metadata type
• -l (--label) (String): The label of the new metadata type
• -v (--visibility) (String): The visibility of the new metadata type

cmdt-fields: creates new field for custom metadata type

• -o (--cmdt) (String): The api name of the custom metadata type
• -n (--name) (String): The field developer name
• -l (--label) (String): The field label
• -t (--type) (String): The field data type
• -p (--picklist) (String): Comma-separated list of picklist values. Only for Picklist data type
• -s (--scale) (Number): The number of decimal points. Only for Number and Percent data types

auth: Creates a new web authorization to a Salesforce org

• -n (--alias) (String): The connection name
• -s (--sandbox) (Boolean): Indicates that the auth url should be test.salesforce.com.
• -r (--instanceurl) (String): The custom login url of the org. If this argument is omitted and -s flag is not used, the connection will point to login.salesforce.com
• -i (--clientid) (String): The client key of the connected app