Use CircleCI version 2.1 at the top of your .circleci/config.yml file.
1
version: 2.1
Add the orbs
stanza below your version, invoking the orb:
1
2
orbs:
salesforce-apex: circleci/salesforce-apex@1.0.1
Use salesforce-apex
elements in your existing workflows and jobs.
Simple example showing how to install the CLI, authenticate and test against a scratch org.
1
2
3
4
5
6
7
8
9
10
11
12
13
orbs:
apex: circleci/salesforce-apex@x.y
version: 2.1
workflows:
deploy_test:
jobs:
- apex/scratch-deploy-and-test:
defaultusername: circleci
deploydir: ./src
permset: circleci
sampledata-path: ./sampledata
scratch-alias: circleci
scratch-def: ./config/project-scratch-def.json
Example showing how to set up the CLI and authenticate with SFDC with the Apex Orb.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
jobs:
install_autheticate:
docker:
- image: cimg/node:12.6
steps:
- apex/setup:
defaultusername: sample@email.com
orbs:
apex: circleci/salesforce-apex@x.y
version: 2.1
workflows:
basic_test:
jobs:
- install_authenticate
An opinionated automation job for deploying your salesforce application to a scratch organization, executing apex unit testing, and finally removing the scratch org. Check this job's source for the full list of commands ran.
PARAMETER | DESCRIPTION | REQUIRED | DEFAULT | TYPE |
---|---|---|---|---|
cli-version | By default, the latest version of the standalone CLI will be installed. To install via npm, supply a version tag such as "latest" or "6". | No | '' | string |
defaultusername | The username for an org that all commands run against by default. | Yes | - | string |
deploydir | The root of the directory tree that contains the files to deploy. The root must contain a valid package.xml file describing the entities in the directory structure. | Yes | - | string |
mdapi-wait-time | Maximum amount of time to complete mdapi deployment. | No | -1 | integer |
permset | Assign a pre-defined permission set to the default user. Learn more: https://help.salesforce.com/articleView?id=perm_sets_create.htm&type=5 | Yes | - | string |
sampledata-path | Path location to sample data json file. Example: ./data/sample-data-plan.json | Yes | - | string |
scratch-alias | Sets an alias for the scratch org to ensure commands are run against the correct org. | Yes | - | string |
scratch-def | Full path to scratch org definition json file. Example:'./config/project-scratch-def.json' | Yes | - | string |
tag | Version tag for the SFDX executor. | No | '12.6' | string |
test-wait-time | Maximum amount of time to complete tests. | No | 10 | integer |
'Deploy MDAPI data.'
PARAMETER | DESCRIPTION | REQUIRED | DEFAULT | TYPE |
---|---|---|---|---|
checkonly | Validate deploy, but don't save to org. | No | false | boolean |
deploy-dir | Deploy directory containing metadata. | No | '' | string |
deploy-zip | Deploy zip file containing metadata. | No | '' | string |
scratch-alias | The alias of the scratch Org. | No | '' | string |
wait-time | Maximum amount of time to complete deployment. | No | -1 | integer |
Removes a scratch organization.
PARAMETER | DESCRIPTION | REQUIRED | DEFAULT | TYPE |
---|---|---|---|---|
scratch-alias | The alias of the scratch Org. | Yes | - | string |
Creates a scratch organization and opens it in the default browser (if available). Also provides a link to open the organization in your own browser.
PARAMETER | DESCRIPTION | REQUIRED | DEFAULT | TYPE |
---|---|---|---|---|
overrides | Overrides for scratch organization. | No | '' | string |
scratch-alias | The alias of the scratch Org. | Yes | - | string |
scratch-config | The scratch JSON definition. | Yes | - | string |
Install CLI and autheticate with SFDC using CLI orb. This assumes some defaults, and requires the SFDX_JWT_KEY and SFDX_CONSUMER_KEY enviornment variables to be set to function. If you need more control over authentication with Salesforce, consider using the sfdx Orb's auth command directly.
PARAMETER | DESCRIPTION | REQUIRED | DEFAULT | TYPE |
---|---|---|---|---|
defaultusername | Username for an organization that all commands will run against. | Yes | - | string |
version | CLI version to install. Leave blank for latest. | No | '' | string |
Pushes the APEX application to the scratch org and sets up mock data & permission sets.
PARAMETER | DESCRIPTION | REQUIRED | DEFAULT | TYPE |
---|---|---|---|---|
force | Force overwriting scratch org and deploy even if warnings are present. | No | false | boolean |
permset | Permissions set to assign to the user for the organization. | No | '' | string |
sample-data | Path to sample data for the organization. | No | '' | string |
scratch-alias | The name of the scratch Org, can either be the alias or target username. | No | '' | string |
Run unit tests for an APEX application with improved code coverage. Automatically stores the test results under the "Artifacts" and "Test Results" tabs.
PARAMETER | DESCRIPTION | REQUIRED | DEFAULT | TYPE |
---|---|---|---|---|
result-format | Format results should be returned as - defaults to junit, can be one of human, tap, junit or json. | No | junit | string |
scratch-alias | The alias of the scratch Org. | No | '' | string |
test-result-output | Directory to save test results to. | No | /tmp/apex-test-results | string |
wait-time | Maximum amount of time to complete tests. | No | 10 | integer |
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
# This code is licensed from CircleCI to the user under the MIT license.
# See here for details: https://circleci.com/developer/orbs/licensing
commands:
mdapi-deploy:
description: |
'Deploy MDAPI data.'
parameters:
checkonly:
default: false
description: Validate deploy, but don't save to org.
type: boolean
deploy-dir:
default: ""
description: Deploy directory containing metadata.
type: string
deploy-zip:
default: ""
description: Deploy zip file containing metadata.
type: string
scratch-alias:
default: ""
description: The alias of the scratch Org.
type: string
wait-time:
default: -1
description: Maximum amount of time to complete deployment.
type: integer
steps:
- run:
command: sfdx force:mdapi:deploy <<#parameters.scratch-alias>> -u <<parameters.scratch-alias>> <</parameters.scratch-alias>> <<#parameters.deploy-dir>> --deploydir <<parameters.deploy-dir>> <</parameters.deploy-dir>> <<#parameters.deploy-zip>> --zipfile <<parameters.deploy-zip>> <</parameters.deploy-zip>> <<#parameters.checkonly>> --checkonly <</parameters.checkonly>> -w << parameters.wait-time >>
name: Deploy Community metadata
scratch-down:
description: |
Removes a scratch organization.
parameters:
scratch-alias:
description: The alias of the scratch Org.
type: string
steps:
- sfdx/scratch-delete:
scratch-alias: <<parameters.scratch-alias>>
scratch-up:
description: |
Creates a scratch organization and opens it in the default browser (if available). Also provides a link to open the organization in your own browser.
parameters:
overrides:
default: ""
description: Overrides for scratch organization.
type: string
scratch-alias:
description: The alias of the scratch Org.
type: string
scratch-config:
description: The scratch JSON definition.
type: string
steps:
- sfdx/scratch-create:
overrides: <<parameters.overrides>>
scratch-alias: <<parameters.scratch-alias>>
scratch-config: <<parameters.scratch-config>>
- sfdx/scratch-open:
scratch-alias: <<parameters.scratch-alias>>
setup:
description: |
Install CLI and autheticate with SFDC using CLI orb. This assumes some defaults, and requires the SFDX_JWT_KEY and SFDX_CONSUMER_KEY enviornment variables to be set to function. If you need more control over authentication with Salesforce, consider using the sfdx Orb's auth command directly.
parameters:
defaultusername:
description: Username for an organization that all commands will run against.
type: string
version:
default: ""
description: CLI version to install. Leave blank for latest.
type: string
steps:
- sfdx/install:
version: <<parameters.version>>
- sfdx/auth:
defaultusername: <<parameters.defaultusername>>
source-push:
description: |
Pushes the APEX application to the scratch org and sets up mock data & permission sets.
parameters:
force:
default: false
description: Force overwriting scratch org and deploy even if warnings are present.
type: boolean
permset:
default: ""
description: Permissions set to assign to the user for the organization.
type: string
sample-data:
default: ""
description: Path to sample data for the organization.
type: string
scratch-alias:
default: ""
description: The name of the scratch Org, can either be the alias or target username.
type: string
steps:
- run:
command: sfdx force:source:push <<# parameters.scratch-alias >> -u << parameters.scratch-alias >> <</ parameters.scratch-alias >> <<# parameters.force >> --forceoverwrite --ignorewarnings <</ parameters.force >>
name: Push App To Scratch Org
- when:
condition: << parameters.permset >>
steps:
- run:
command: sfdx force:user:permset:assign -n << parameters.permset >> -u <<parameters.scratch-alias>>
name: Assign << parameters.permset >> permset for organization
- when:
condition: << parameters.sample-data >>
steps:
- run:
command: sfdx force:data:tree:import --plan << parameters.sample-data >> -u <<parameters.scratch-alias>>
name: Import sample data plan from << parameters.sample-data >>
test:
description: |
Run unit tests for an APEX application with improved code coverage. Automatically stores the test results under the "Artifacts" and "Test Results" tabs.
parameters:
result-format:
default: junit
description: Format results should be returned as - defaults to junit, can be one of human, tap, junit or json.
type: string
scratch-alias:
default: ""
description: The alias of the scratch Org.
type: string
test-result-output:
default: /tmp/apex-test-results
description: Directory to save test results to.
type: string
wait-time:
default: 10
description: Maximum amount of time to complete tests.
type: integer
steps:
- run:
command: |
mkdir -p << parameters.test-result-output >>
sfdx force:apex:test:run --wait << parameters.wait-time >> --resultformat << parameters.result-format >> --codecoverage --testlevel RunLocalTests \
-d << parameters.test-result-output >> \
<<# parameters.scratch-alias >> -u << parameters.scratch-alias >> <</ parameters.scratch-alias >>
environment:
SFDX_IMPROVED_CODE_COVERAGE: true
name: Run Unit Tests
- store_artifacts:
destination: apex-test-results
path: << parameters.test-result-output >>
- store_test_results:
path: << parameters.test-result-output >>
description: |
Test and deploy APEX applications to Salesforce. This is a wrapper around the circleci/salesforce-sfdx orb which provides commonly used defaults - It's recommend to use the sfdx orb alongside this one if you require more flexibility.
display:
home_url: https://developer.salesforce.com
source_url: https://github.com/CircleCI-Public/salesforce-apex-orb
examples:
scratch-deploy-and-test:
description: |
Simple example showing how to install the CLI, authenticate and test against a scratch org.
usage:
orbs:
apex: circleci/salesforce-apex@x.y
version: 2.1
workflows:
deploy_test:
jobs:
- apex/scratch-deploy-and-test:
defaultusername: circleci
deploydir: ./src
permset: circleci
sampledata-path: ./sampledata
scratch-alias: circleci
scratch-def: ./config/project-scratch-def.json
setup-environment:
description: |
Example showing how to set up the CLI and authenticate with SFDC with the Apex Orb.
usage:
jobs:
install_autheticate:
docker:
- image: cimg/node:12.6
steps:
- apex/setup:
defaultusername: sample@email.com
orbs:
apex: circleci/salesforce-apex@x.y
version: 2.1
workflows:
basic_test:
jobs:
- install_authenticate
jobs:
scratch-deploy-and-test:
description: |
An opinionated automation job for deploying your salesforce application to a scratch organization, executing apex unit testing, and finally removing the scratch org. Check this job's source for the full list of commands ran.
executor:
name: sfdx/default
tag: << parameters.tag >>
parameters:
cli-version:
default: ""
description: By default, the latest version of the standalone CLI will be installed. To install via npm, supply a version tag such as "latest" or "6".
type: string
defaultusername:
description: The username for an org that all commands run against by default.
type: string
deploydir:
description: The root of the directory tree that contains the files to deploy. The root must contain a valid package.xml file describing the entities in the directory structure.
type: string
mdapi-wait-time:
default: -1
description: Maximum amount of time to complete mdapi deployment.
type: integer
permset:
description: 'Assign a pre-defined permission set to the default user. Learn more: https://help.salesforce.com/articleView?id=perm_sets_create.htm&type=5'
type: string
sampledata-path:
description: 'Path location to sample data json file. Example: ./data/sample-data-plan.json'
type: string
scratch-alias:
description: Sets an alias for the scratch org to ensure commands are run against the correct org.
type: string
scratch-def:
description: Full path to scratch org definition json file. Example:'./config/project-scratch-def.json'
type: string
tag:
default: "12.6"
description: Version tag for the SFDX executor.
type: string
test-wait-time:
default: 10
description: Maximum amount of time to complete tests.
type: integer
steps:
- checkout
- setup:
defaultusername: <<parameters.defaultusername>>
version: <<parameters.cli-version>>
- scratch-up:
scratch-alias: <<parameters.scratch-alias>>
scratch-config: <<parameters.scratch-def>>
- source-push:
scratch-alias: <<parameters.scratch-alias>>
- run:
command: sfdx force:user:permset:assign -n <<parameters.permset>>
name: Assign Permissions
- run:
command: sfdx force:data:tree:import --plan <<parameters.sampledata-path>>
name: Load Sample Data
- mdapi-deploy:
deploy-dir: <<parameters.deploydir>>
scratch-alias: <<parameters.scratch-alias>>
wait-time: <<parameters.mdapi-wait-time>>
- test:
scratch-alias: <<parameters.scratch-alias>>
wait-time: <<parameters.test-wait-time>>
- scratch-down:
scratch-alias: <<parameters.scratch-alias>>
orbs:
sfdx: circleci/salesforce-sfdx@2.0.0
version: 2.1