Flosum Configuration
Now that the Jenkins server is set up for Automation test execution, we can begin setting up the Salesforce org with the Flosum installation to queue the Jenkins job that we just created.
Prior to setting up the webhook to trigger our Automation job on another end system, a pipeline has to be created in Flosum. Before you can initiate a pipeline, you need to have a valid branch in Flosum to run it from. The entire process is detailed in the following steps.
- Registering your Organization
- Creating a Snapshot
- Committing to Branch
- Creating a Webhook
- Creating a Pipeline
Registering your Organization
The first step in setting up the pipeline in Flosum is to add an organization. Navigate to the Orgs tab in your Flosum org and click New.
Enter the Organization Name, Authentication Type (automatic is easier), and Organization Type. This needs to be an org that you are connecting to from Flosum to trigger the pipeline. In practice, this would be whatever org you are making deployments/triggering changes on that triggers your Automation tests elsewhere. In other words, if you want to run Automation tests following a deployment/change in a Developer org, your setup might look like the screenshot given below.
Once you enter these field details in, you’ll have to authorize Flosum to connect to this org by clicking Authorize in the top right corner and following the Salesforce authentication there.
Success! Your org has been added to Flosum and we can continue on to the next step of creating a snapshot.
Creating a Snapshot
In order to create a snapshot, navigate to the org we just created and select Create Snapshot.
First, you will enter a name for your Snapshot. A snapshot is essentially a specific capture of metadata that you wish to deploy or validate. You can create a partial or complete snapshot. You can configure a lot of options for the snapshot.
For example, you can select the number of days that you want to retrieve changes for the selected components. You can also filter the components based on component type, component name, or changed by fields.
The operator can be set to a wide variety of options, depending on which components you are trying to filter for.
Once you’ve selected a field and an operator, you can use the search icon on the far right to search for specific components by value. You can add each individual component you want by checking the boxes next to the relevant item.
For testing purposes, we’ve kept it simple and changed the retrieval date to ‘0’ days to retrieve all components.
Once you are satisfied with the snapshot, click create snapshot in the top right corner.
Give Flosum a minute or so to complete the snapshot process. You can track the status by refreshing the snapshot screen and checking the Is Completed? checkbox. Additionally, you’ll want to make sure that the No. of Metadata Items is greater than ‘0’.
That’s it! Your snapshot is created from the Org we registered previously and we are ready to commit it.
Committing to Branch
Once you are on the snapshot screen, the commit to branch step will open the next screen to select all components you’d like to commit.
A note here that all of this is being committed to the Flosum’s native Version Control System, and not your personal/company’s repository. It’s a great feature for storing all of this metadata information directly in your Flosum org and not having to set up your own Git repository just for this process.
If you do not have an existing branch in Flosum (which you can check by selecting the search icon next to the Commit to Branch field), then you can enter a name in the Branch Name field and Flosum will automatically create that branch for you.
Next, you will select all of the components from the snapshot that you’d like to commit to the branch.
From there, select Continue Commit to Branch.
On the next screen, you need to verify all of the components you’d like to commit based on which components are considered safe to commit.
In this example, we’ve selected everything from our org snapshot. Once you’re happy with it, select Continue Commit to Branch to officially commit these components to the branch in Flosum.
It will take Flosum a minute to process the commit, and then it will navigate you to the Branch view as shown below.
Now that you have a branch, we can begin setting up your Flosum Pipeline.
Creating a Webhook
To create a webhook in Flosum, navigate to the Settings tab and select webhooks.
Click Add Webhook and enter in the Webhook Name, URL, and your Jenkins authentication. For the Jenkins authentication, the password must be replaced with a valid Jenkins API Token generated by the same user you are using to authenticate. This has to be set up properly from the Jenkins server prior to adding the webhook here.
The URL needs to be the build URL pointing to a specific Jenkins job. Please see the example given below.
Jenkins URL: https://demojenkins.com:8080
Job Name: FlosumTrigger
Build Parameters: TEST_PLAN=Regression, BUILD_FILE=build.xml
API Token Name: FlosumToken
Then the webhook URL would be the following:
https://demojenkins.com:8080/job/FlosumTrigger/buildWithParameters?token=FlosumToken&TEST_PLAN=Regression&BUILD_FILE=build.xml
You can also find this URL underneath the Build Triggers section on your Jenkins job.
A reminder here that the URL of the Jenkins server must be reachable from your Salesforce Org. If your Jenkins server is behind a proxy or firewall, then it needs to be opened up to allow traffic from Salesforce IP ranges.
Also, remember to check the Wait callback response from service to wait for the Jenkins webhook to return successfully before continuing to the next Pipeline step.
Now that the webhook is created, you can continue on to the pipeline creation.
Creating a Pipeline
To create a Pipeline in Flosum, navigate to the Pipelines tab and select New.
Enter the Pipeline Name, and leave the rest as the default.
Next, you need to add some Pipeline steps. Select Pipeline Steps and once it loads, click New.
We’ve named our webhook Jenkins, so this is what the step looks like.
Since there is no next step here, the On Pass and On Fail fields can be left as Stop for now.
For the purposes of this integration, our pipeline only has a single step that will trigger our webhook to kick off our Automation tests. For a practical pipeline, you would have multiple pipeline steps that include deployment, validation, and rollback.
Once you’ve added all of the necessary Pipeline steps, click Save Steps.
The Pipeline is set up and is ready to be queued from the Branch we created earlier. Navigate to the Branch view screen for the branch we committed to earlier. From the branch, we can run the Pipeline directly.
Select the Pipeline you just created.
You can view the Pipeline results from the Pipeline Executions related list from the Pipeline view, or you can view the Deployment History from the branch view.
If you navigate to the Deployment History >Metadata Logs you’ll see the result of each Pipeline execution.
Navigate to one of these Metadata Logs, and the Related tab will show any relevant error logs in the Notes & Attachments related list.
Note: This webhook step does not wait for the Jenkins job itself to complete, but rather just the callback response to return. Currently, there is an error in Flosum that shows the deployment step as failed if the callback response is a 201 (which is what Jenkins returns when successfully triggering a job).
This will be the attached log, and the deployment history and pipeline step execution will both show as failed, even though the call was successful.
If you are queuing your pipeline and do not see anything occur on the Jenkins side, then you might be getting a timeout due to a network firewall blocking the connection. If it is blocked, you can check the deployment history metadata logs for a similar message.
You may also see the following error if your webhook URL is malformed or not sending properly: webhook error: Read timed out.
For a more detailed view of the results of the tests, you’ll have to navigate to the Jenkins job itself. You can also configure your build.xml in Automation to email test reports once completed.