This user guide will walk you through how to create and configure Salesforce CI/CD pipeline in Opsera
Prerequisites for setting up the pipeline:
Below information are needed before setting up a pipeline,
Salesforce Credentials , Salesforce Org URL, Client ID, Secret Key, Token and Password
Jenkins - URL, Token Description & actual token. (from the tool chain automation)
Provide Jenkins URL (Jenkins URL would have been received from the email from support@opsera.io
Login to Jenkins using the Jenkins admin user Id and password (You would have received an email for these credentials)
Generate token by following below steps,
Click on Admin (Found at right top corner)
Then, Click on Configure from the left list of options
In the list of configure options in the screen, you will see “ API Token “ - click on “ Add me Token “ . Give a name for the token and click on generate.
You will see the token in the screen. Copy the token for further use. (Copy this token now, because it cannot be recovered in the future. If you forget, you will need to generate a new one then. )
3. Credentials of Source code Repository such as Gitlab/Github/Bitbucket
Steps to configure Salesforce pipeline in Opsera
Login into the Opsera Portal (https://portal.opsera.io/) and sign in with your registered email.
Add Salesforce Org to the Opsera portal
click on Tool Registry (found at the left panel of options as shown below)
2. Click on ‘New Tool’ (as shown below) - To add SFDC Org to establish an initiation.
3. Enter tool details as explained below,
Tool Name - Give a meaningful name for the tool
Tool Identifier- Select ‘SFDC Configurator’ from the drop down
Description - Give a description for the tool
4. Click Create
6. Once the tool is created, Click on ‘Connection’ tab to enter the details.
Enter Salesforce URL, Username, Client ID, Client Secret, Token and Password. Also select the Build Type from following two options: Ant Migration or Salesforce DX (SFDX).
7. Click Save. This will save the tool Configuration will be updated successfully and Salesforce org has been successfully added to Opsera portal.
Next - Create Source Code repository for your pipeline (Gitlab/github/bitbucket)
8. Click on Tool Registry on left navigation panel and click on ‘New Tool’.
9. Enter Tool Name, Tool Identifier (Select the repository tool from the drop down) & Description
10. Click Create
12. Click on the Tool → Click on ‘Connection’ tab → Enter URL, Username, and Personal Access Token.
13. Click ‘Save’ → Tool Configuration will be updated successfully. This would successfully add the repository tool to the Opsera portal. After saving the tool, ensure the Connection is successful but clicking ‘Test Connection’
Next, Jenkins tool to be added, and integrated with source code repository
14. Click on Tool Registry on left navigation panel and click on ‘+New Tool’.
15. Enter Tool Name, Tool Identifier (From the drop down - Select Jenkins), Description
16. Click Create
17. Click on the Tool → Click on ‘Connections’ tab → Enter Jenkins URL, UserID, Jenkins Token
18. Save tool and then click ‘Test Configuration’ to ensure connection succeeds.→ Tool Configuration will be updated successfully.
19. Click on Accounts tab
20. Click on ‘Register New Account Credentials’
21. New Jenkins Account adding form will open
23. Select Platform [Select your source code repository tool from the drop down - Gitlab/Github/Bitbucket], Then drop down for “tools” will be enabled - Select the tool that you just created.
24. Enter Name and Description of credentials to be added in Jenkins and click on ‘Save’. The Jenkins job is now linked to your source code repository.
Next, Creation of SFDC Jenkins jobs in Opsera Portal
(each one represents the SFDC Process such as Validate Package XML, Backup of an Org, Unit Test, Deploy to an Org)
25. On the Opsera portal - click on Tool Registry, Click on the “Jenkins” tool you just created. Then Click on Jobs tab and click on ‘+Create Job’ button (as shown below)
26. Select Job Type as ‘SFDC Jobs’ and Build Step as ‘SFDC Validate XML Package’. Enter a Name and Description.
27. Click ‘Save Job’ to finish creating the job.
28. Job has been created on Jenkins Tool which will be used on Pipelines to successfully create builds inside Jenkins.
29. Repeat the above process for creating other jobs for --> Backup, Unit Test and Deploy
Jobs have been created and configured and all ready for use. This is a one time configuration activity & can be used repeatedly for “n” number of pipelines.
Next, Creation of pipeline and its configuration.
30. On the Opsera portal, Click on Pipelines from the left navigation panel to open the catalog to create pipeline. Click on ‘Catalog’ Tab (found at the right top panel as shown below)
31. From the below list of pipeline templates, Under the ‘Salesforce Template’, click on “ Create Pipeline “ to add the pipeline successfully.
32.To give a meaningful name for the pipeline, On Summary tab, click on the pencil icon (next to SalesForce Template name).
33. Edit the pipeline. Click the Save icon to save the new name.
Create Package XML job & Configuration
34. Click on Workflow tab → A default step ‘Create Package Job’ will be available
35. Click on the ‘Configuration icon’ on the ‘Create Package Job’ step → It will open the fields for adding the configuration.
36. Enter the below fields and click Save
Tool → From the dropdown, select the Jenkins tool created in Tool Registry;
Job Type → default for Package creation job is ‘SFDC Package generation job’, for other steps, it should be ‘Opsera managed jobs’
SalesForce Credentials → Source Org from which modified files will be fetched
Account → [gitlab/github/bitbucket] credentials added inside Jenkins tool in tool registry
Workspace/Project → Based upon the Account - All Projects will be fetched [Select one]
Repository → Based upon the Project - All the repositories available will be fetched [Select one]
37. Click Save → all the configurations made to the step will be saved.
SFDC process includes, ‘Create Package XML’, ‘Validate XML’, ‘Backup’, ‘Unit Test’ and ‘Deploy’ steps in pipeline, where each one can be used based upon the organization need and each can be plugged in/out based upon necessity.
Next add another Pipeline step configuration for Validate XML Step
38. Click on ‘Edit workflow’ option on the pipeline as shown below.
39. Click on ‘+' icon present below the ‘Jenkins Create Package Job’ → It will add a new step called 'Unconfigured step’
40. Click on ‘Done Editing’ and click on ‘Pencil’ icon on ‘Unconfigured Step’ → Step detail fields will be opened.
41. Enter a ‘Step name’ and select the tool as ‘Jenkins’. Note: Tool cannot be changed after form is saved. To change the tool, delete the step and create a new one.
42. Click Save to save the step level details
43. Click the gear icon (⚙️)→ Configuration fields will open
44. Enter Tool, Job Type, Job, Salesforce Credentials and Unit Test Type field values and click on ‘Create Job and Save’.
45. Configuration section will be closed and the given details will be saved
46. Next Pipeline Step Configuration - Backup → The entire SFDC Org components will be taken as a backup and pushed to Git/Bitbucket Repository based upon the step configuration.
Next, Backup of an Org - Step to be Configured
47. Repeat the steps above to create a new step for Backup to be added
48. Click on Save to save the step details
49. Click the gear icon (⚙️) → Enter the configuration details
Enter Tool, Job Type, Job, Salesforce Credentials, Account, Workspace/Project and Repository field values.
50. Click on Create Job and Save button
51. Configuration section will be closed and the given details will be saved
Next Pipeline Step Configuration for Unit Test
(All the test classes will be executed for this step)
52. Similar to above steps - New step for Unit test can be added
53. Click on the pencil icon (✎) on Unconfigured step and add Step level details
54. Click on Save to save the step details
55. Click the gear icon (⚙️)’ → configuration fields will open
56. Enter Tool, Job Type, Job, Salesforce Credentials field values and Click on 'Create Job and Save button’
57. Configuration section will be closed and the given details will be saved
Next Pipeline Step Configuration for “ Deploy”
(Destination SFDC Org to be configured where the modified files created as part of ‘Create Package XML’ step will be deployed )
58. Similar to above steps - New step for Deploy can be added
59. Click on ‘Pencil icon’ on Unconfigured step and add Step level details
60. Click on Save to save the step details
61. Click ‘Configuration icon’ → configuration fields will open
62. Enter Tool, Job Type, Job, Salesforce Credentials field values and Click on 'Create Job and Save button’
63. Configuration section will be closed and the given details will be saved
The necessary steps of SFDC Process has been configured successfully. Now the pipeline can be started / initiated to run.
Sample Pipeline Run / Execution
Sample pipeline run has been shown below to explain the process and its successful deployment on Git to SFDC Org.
Source can be Git or SFDC, based on the user selection (Example shown here if for Git)
67. Custom Object ‘SFGA__Ad_Group_ID__c’ is taken as an example here [image taken before deployment in SFDC]
64. On Git, Same custom object File ‘SFGA__Ad_Group_ID__c’ is modified for ‘Inline help text’ field and committed.
65. In the Opsera Portal → Navigate to the configured pipeline → Click on ‘Start Pipeline’. as shown below.
66. Pipeline Start Wizard will be opened → where components of modified files need to be selected.
On the wizard, you have the option to select/deselect modified files, view/edit the package XML and use a past run’s XML .
Manual Pipeline Wizard Run
Use Past Run’s XML and XML/File Upload Process
Choose from Source Org:
If From Git is selected, you may include dependencies. By default, all CustomObject dependencies are included in the deployment while selecting components from the Git Side. By disabling this toggle, dependencies will be excluded from Git to SFDC merge unless explicitly selected. This can also be selected in a manual pipeline run on the following Component Type selection screen:
If dependencies are included in the pipeline run, verify their details in the Console log after the pipeline has run from Git to SFDC:
XML/File Upload Process
67. Select the date & components and click on ‘Proceed with Selected Components’
68. Modified files for selected components will be displayed from both Git/Bitbucket as well as SFDC.
Select the respective files & click on “Proceed with selected SFDC files” - Either Select the components from the list or upload components as a csv file to use for deployment.
69. This will open the necessary steps to be executed. In this example, “ Unit testing “ - Click on the “unit testing “ box to open up the the testing classes. This needs to be specified . Please select each step below and then apply the required testing classes before proceeding. Please note, without this step, the pipeline cannot complete successfully. Once the necessary files are selected → Click on Next → To view the package XML
** Easier and simpler UI framework for enhancing Unit Test class selection.
** Bulk addition of Apex Test Classes can be made by multi-selecting the test classes displayed on the left-side table and clicking on Add Selected Button on top of the corresponding table.
** Bulk removal of selected Apex Test Classes can be made by multi-selecting the test classes displayed on the right-side table and clicking on Remove Selected Button on top of the corresponding table.
70. Modified files will be converted to package XML for deployment → Click on Proceed to start the Opsera pipeline
71. Opsera Pipeline process started as shown below
72. Create Package Job is successful as shown below. Once Create Package job is successful, next pipeline step will be automatically taken for processing.
73. Validate XML step is successful → which indicates modified files and its related objects are available in Package XML.
74. Backup step is successful → This indicates a ‘Rollback branch’ created in Git repository tool and all the SFDC Components are backed up.
75. Output of Backup Step - Git branch created.
76. All the components and files of Source SFDC Org mentioned in Pipeline Backup step is backed up here.
77. Unit test step is successful → which indicates all the test classes are successfully executed in respective SFDC Org mentioned in Pipeline step.
78. Deploy step is successful → which indicates the modified files from Git are successfully deployed to Salesforce Destination Org as mentioned in pipeline step.
79. Salesforce Destination Org has been updated with modified content from modified file in Git
On the above steps, SFDC Configuration in Opsera as well as SFDC Functional workflow is shown. Any Pipeline steps can be plugged in/out based upon the need and SFDC process also works based upon the pipeline configuration.