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 configurations 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 configurations will be updated successfully.
19. Click on Accounts tab
20. Click on ‘+ Register New Account Credentials’ button
21. Create New Jenkins Account form will open
23. Select Platform [Select your source code management tool from the drop down - Gitlab/Github/Bitbucket], Then drop down for “tools” will be enabled - Select the tool that you just created.
Platform - Select your Source code management platform from the dropdown. Choose from Gitlab, Github and Bitbucket.
Tool - Select the recently created tool from the dropdown.
24. Enter Name and Description of credentials to be added in Jenkins and click ‘Save’ button. The Jenkins Job is now linked to your source code repository.
SFDC Jenkins Jobs creation in Tools
Each job represents an SFDC Process:
SFDC Jenkins Jobs:
SFDC Create XML Package
Profile Migration
SFDC Validate XML Package
SFDC Backup
SFDC Deploy
SFDC Unit Test
SFDC Push Artifacts
25. In the Opsera portal - Navigate to Tool Registry and select the Jenkins tool you just created. Navigate to the Jobs tab and click on + Create Job button (as shown below)
26. Make the following selections:
Job Type - SFDC Jobs
Build Step - SFDC Validate XML Package
Enter a Name and Description.
27. Click Create button to finish creating the job.
28. The job has now been created in the Jenkins Tool which will be used in Pipelines to successfully create builds inside Jenkins.
29. Repeat the job process for creating other jobs for --> SFDC Backup, SFDC Unit Test and SFDC 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.
Pipeline Creation and Configuration
30. On the Opsera portal navigate to Pipelines from the left navigation panel. Click on ‘Catalog’ Tab (found at the right top panel as shown below)
31. In the Marketplace in Pipeline Templates, locate Salesforce Template, and click + Create Pipeline to create a pipeline using this template.
32. To rename the pipeline, navigate to Summary tab and click on the pencil icon. Next to the pipeline template name - “SalesForce Template”.
33. Edit the pipeline by editing any additional details. Click the Save icon to save the new name.
Create Package XML job & Configuration
34. Navigate to Workflow tab.
A default step ‘SFDC Jenkins Create Package Job’ will be available
35. Click the gear icon on the SFDC Jenkins Create Package Job step to view the Step Configuration form.
36. Enter the below fields and click Save
Tool - From the dropdown, select the Jenkins tool created in Tool Registry;
Job Type - The default Job Type for Package creation job is ‘SFDC Package Generation Job’. For other steps, it is ‘Opsera managed jobs’.
Salesforce Credentials - Source Org from which modified files will be fetched
Account - Select the source control management credentials that were added in the Tool Registry. Choose from Gitlab, Github or Bitbucket.
Workspace/Project - Select the Workspace or Project in the the source control management account.
Repository - All the repositories available will be fetched from the selected Workspace.
37. Click Save → all the configurations made to the step will be saved.
SFDC process includes the following steps in the pipeline:
Create Package XML
Validate XML
Backup
Unit Test
Deploy
Each can be used based upon the organization need and each can be plugged in/out based upon necessity.
Add a Validate XML pipeline step to the workflow
38. Click on ‘Edit workflow’ on the pipeline as shown below.
39. Click on ‘+' icon present below the SFDC Jenkins Create Package Job.
A new step called 'Unconfigured step’ will be added to the workflow.
40. Click on Done Editing then click on the pencil icon on ‘Unconfigured Step’
Step Setup will open.
41. Enter values for the fields:
Step Name - Enter a unique step name.
Tool - Select Jenkins. Note: Tool cannot be changed after form is saved. To change the tool, delete the step and create a new one.
Tags - Select any tags to be applied at this level.
42. Click Save button to save the step.
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.