How to Create and Refresh Scratch Orgs using Automation

The first step to weaponizing a Saleforce scratch org is to automate its creation and maintenance. Since scratch orgs expire every few days, automation needs to do a few key operations:

Detect when a scratch org either does not exist or exists and has expired.
Delete a scratch org.
Create a scratch org.

The rest of this post describes how we automate our scratch org creation maintenance using Apache/Ant and Jenkins.

This post is the second post in this series.

Introduction: How to Weaponize Scratch and Developer Orgs
How to Populate a Scratch Org Using Automation

Step 1: Build Apache/Ant Macros for sfdx Actions

To create and and maintain scratch orgs, only three basic sfdx functions are needed:

Determine if a scratch org is active.
Create a scratch org given a definition file and user alias.
Delete a scratch org (if it exists)

The following ant script creates the needed macros and the only tricky part is that it depends on another Apache/Ant file to load Apache/Ant contribution libraries.

Copy to Clipboard

<project name="SfdxTools" default="sfdxToolsBuild" >
<!--
Tools for working with sfdx.

IsScratchOrgActive  : determine if a scratch org is active.
CreateScratchOrg : create a scratch org given an alias and a json definition file.
DeleteScratchOrg : drop a scratch org (if it exists)

Assumptions:

+ The sfdx command is in your command line search path.
+ the AntContrib.xml can find and install the ant contrib library.
-->
	
	<dirname property="sfdx.tools.home" file="${ant.file.SfdxTools}" />
	
	<include file="${sfdx.tools.home}/../tools/AntContrib.xml" />

<macrodef name="IsScratchOrgActive">
		<attribute name="username" />
		<attribute name="status" />
		
		<sequential>
			
			<exec executable="sfdx" outputproperty="displayStatus" failonerror="false">
				<arg value="force:org:display" />
				<arg value="-u" /> <arg value="@{username}" />
						
			</exec>
		
			<exec executable="awk" inputstring="${displayStatus}" outputproperty="orgStatus">
				<arg value="$$1 == "Status" {print $2}" />
			</exec>
			
			<condition property="@{status}" value="true" else="false">
				<equals arg1="${orgStatus}" arg2="Active" />
			</condition>
			
		</sequential>
	
		
	</macrodef>
		
	<macrodef name="CreateScratchOrg">
		<attribute name="alias" />
		<attribute name="jsonFile" />
		
		<sequential>
			<exec executable="sfdx" failonerror="true">
				<arg value="force:org:create" />
				<arg value="-s" />
				<arg value="-f" />
				<arg value="@{jsonFile}" />
				<arg value="-a" />
				<arg value="@{alias}" />

</exec>
		</sequential>
	</macrodef>
	
	<macrodef name="DeleteScratchOrg">
			<attribute name="alias" />
			
			<sequential>
				<exec executable="sfdx">
					<arg value="force:org:delete" />
					<arg value="-u" />
					<arg value="@{alias}" />
					<arg value="--noprompt" />
				</exec>
			</sequential>
		</macrodef>
	<target name="sfdxToolsBuild" >

</target>
</project>

The previous script depends on another Apache/Ant script for loading Ant Contrib libraries. It also, is a pretty simple script.

Copy to Clipboard

Step 2: Create a Scratch Org Automation Apache/Ant Script

Now that you have the basic Apache/Ant tasks in place, the next step is to build your first scratch org. What you will need is:

A scratch org json configuration file.
A user alias to assigned to the scratch org.

The following example Apache/Ant script builds a scratch org we use for unit testing. Note that the tasks which install custom meta data and populate the scratch org with data are left out. They are discussed in another post.

In the example:

The sfdx configuration file is CopyStormUnitTest.json
The user alias for the scratch org will be CopyStormUnitTest.

Copy to Clipboard

<project name="buildCopyStormUnitTest" default="build" >
<!--
Build a salesforce scratch org suitable for testing CopyStorm core capabilities.

-->
	
	<dirname property="build.home" file="${ant.file.buildCopyStormUnitTest}" />
	<property name="scratchOrg.json" value="${build.home}/CopyStormUnitTest.json" />
	<property name="scratchOrg.alias" value="CopyStormUnitTest" />
	
	<include file="${build.home}/../SfdxTools.xml"/>
	
	<target name="deleteScratchOrg">
		<DeleteScratchOrg alias="${scratchOrg.alias}" />
	</target>
		
	<target name="buildScratchOrg" depends="deleteScratchOrg">	
		<CreateScratchOrg alias="${scratchOrg.alias}" jsonFile="${scratchOrg.json}" />
	</target>
	
	<target name="installSchema" >
		
	</target>
	
	<target name="populateSchema" >
		
	</target>
	
	<target name="rebuildOrg">
		<antcall target="buildScratchOrg" />
		<antcall target="installSchema" />
		<antcall target="populateSchema" />
	</target>
	
	<target name="validateOrg">

</target>

</target>

</project>

Since you are reading this post, I suspect that you know how to create a scratch org configuration file already. However, for the record, here is the CopyStormUnitTest.json file used in the example.

Copy to Clipboard