Promotion Overview

By the end of this module, you’ll be able to:

 Describe the ways you can promote User Stories.

 Define what is a Promotion and the Promotion Process.
 Identify the different fields and sections of the promotion page.

The Promotion Process

You have applied some changes in a lower environment and committed them in a
user story. Now, you want to move your development up to the Production
environment. Therefore, you need a Promotion then.

What is a promotion? A promotion is basically a container used to deploy one or

multiple user stories following a specific pipeline. The promotion process has an
impact both in the destination Salesforce Org through the deployment execution,
and in the Git Server using auxiliary branches called promotion branches.

The Promotion Branch

A promotion branch is a copy of the destination environment branch where all the
related user stories feature branches are merged. Copado will use this promotion
branch to deploy the metadata changes into the destination environment.

Case: Imagine that, as part of a Release Process, you have to deploy to the
Integration environment the changes developed in 3 User Stories that modified
multiple components, including the System Administrator Profile and the Account
Object.

Challenge: The development process was performed by different users in

independent sandboxes. You need to merge them all, without overwriting the
existing changes in the destination.

Solution: In order to achieve this, first create a Promotion record and add the
required user stories, already in Completed status. Once the promotion is ready,
create a Deployment from the Promotion that will orchestrate the Git merge and
the deployment of the components committed in the user stories.
When running a promotion with user stories containing metadata changes, a
promotion branch is created by Copado’s back-end out of the destination branch in
your git repository. This branch will be named promotion/{promotion.name-
deployment.name}.

The reason why the promotion branch is created out of the destination branch is to
keep the existing changes in the destination while adding new contributions of
developers to it. This is achieved by merging the User Story feature branches into
the promotion branch.

As mentioned in Copado Branching Strategy module, the merge order of the User
Stories into the Promotion branch is based on the User Story Reference field in
ascending order yet you can override this behavior and define a custom merge
order.
By default, a promotion with metadata changes will have at least one related
promotion branch. However, in some situations, you can have multiple promotion
branches associated with the same promotion record. These scenarios include a
failed deployment where you may need to recreate the promotion branch more than
once.

It can happen that our git promotion has some merge conflicts, in that case,
Copado can use its Auto Resolve Engine to resolve the conflicts and proceed with
the deployment while keeping the collaboration provided in the different user
stories.

After a successful deployment, there is a final merge of the promotion branch

against the destination org's Branch. Copado applies this mechanism to “update”
the destination branch with the changes delivered to the destination Org and keep
them both in sync, branch and Org.

Important:

Whenever you promote a user story, Copado will locate the destination
environment based on the pipeline configured in the project or the release’s
record.
 Promotion Page
To better understand the basic functioning of a Promotion, let’s take a peek at the
Promotion record page.

More detailed information of some relevant fields and sections:

Relevant fields

 Release: Release linked to the user story. A release allows you to group user
stories to promote them together as well as to keep track of the version of changes
that your Salesforce application experiences after every deployment.
 Project: Project that will designate the Pipeline to which the user story belongs.
 Source Environment and Source Org Credentials: The credentials of the Source
Environment that should be used when creating a deployment.
 Destination Environment and Destination Org Credentials: Destination
Environment and destination Org Credentials will be auto-populated based on the
pipeline related to the project/project's release and the available credentials owned
by the running user.

Note: If an Org Credential is marked as Default Credential, this will be the Org
Credential used in the promotion process, regardless of the owner. However, you
can still override this behavior at the environment level by using the functionality
mentioned here.
 Order User Stories By: Lets you override the default User Story Reference
ordering to a different user story field with asc or desc ordering. This field is also
present in Pipeline.

Case: Suppose you want your feature branches to be merged into the Promotion
Branch following its Close Date value.
Solution: In Order User Stories By define the API name of the field in ascending
order (copado__Close_Date__c asc). If you set this at Pipeline level, all the
Promotions inherit this value. If you want this to apply only to specific Promotions,
use the field in the Promotion record instead.

 Status: As the deployment process moves forward, the status of the promotion will
be updated following the changes of the deployment record.
 Create Full Permission Sets Step and Create Full Profiles Step: When checked,
Copado will verify if permissions sets or profiles have been added as metadata and
will generate a full profile/full permission Set metadata step.

Promotion Sections

 Available User Stories: Under the Add User Stories tab. You can find user stories
marked as Ready to Promote and whose Environment matches the Source
Environment of the promotion. You can add the user stories you need to deploy to
your promotion by clicking on the Add selected User Stories button.
 Selected User Stories: User Stories already included in the promotion. They can
be moved back to the Available User Stories section by selecting them and clicking
on the Remove selected User Stories button.

Tips:

Type the User Story number in the search box to quickly filter the results.
You have a Field Set named Promotion Related List available in User Story
object that allows you to customize the information shown in the user stories
related list in the promotion record

 Promotion User Story Metadata: Under Promotion Metadata tab. When there
are two or more user stories in a Promotion with the same component committed,
and the last commit date of the component is more recent in a user story with a
lower number, a warning listing the API names of the components will be
displayed.
 Also, the Create User Story button will allow you to create a new user story with
the highest number to commit the components again, so an older version of the
component won’t override the version the latest one in the lower user story
number.

The Promotion Flow

Introduction
There are different ways in which you can promote changes within your pipeline.
According to your needs, you may find one way more convenient than others.

In this Module we will cover:

 Promote and Deploy for one User Story.

 Manual Promotion of one or multiple User Stories.

Promote and Deploy Flow

When using Promote and Deploy, Copado will automatically execute most of the
tasks related to the promotion process.
The following diagram shows the stages of the process. Let’s take a look at it to
understand the Promote and Deploy Flow Flow.

Manual Promotion Flow

You will find yourself following this process when promoting multiple user
stories. In the Manual Promotion Flow, the user creates the promotion record,
which gives more flexibility while defining the promotion details.

The diagram below outlines the behavior of the Manual Promotion Flow.
 Promotion Flow Steps Details
Let’s review in further detail the previously mentioned Promotion Flows steps and
what actions are involved in each step.

1. Promotion Definition:

 Selection of the Project linked to the pipeline that will automatically set the
destination environment.
 Selection of the Source Environment holding the user stories ready to be promoted.
 Selection of the user stories to deploy.

2. Deployment Record Creation:

 Creation of a deployment record along with its corresponding deployment steps.

The deployment steps are the steps that are executed during the deployment of the
changes to the destination Org.

3. Creation of a Promotion Branch:

 The creation of a promotion branch out of the destination environment guarantees

that existing changes in the destination environment are not accidentally
overwritten by peers.
 4. Merge of the User Stories Feature Branches into the Promotion Branch:

 By merging the changes of the user stories into the promotion branch, we ensure
that existing changes and new changes can integrate properly into the destination
environment.

5. Execution of the Deployment Steps:

 Creation of a Job that reads metadata changes on the promotion branch and
deploys them to the destination salesforce environment.

6. Merge of the Promotion Branch into the Destination Branch:

 This secures that metadata changes deployed to the destination environment are
reflected as well in the destination branch.

7. Final Records Update:

 Promotion and deployment records status are updated to Completed.

 Since the user stories are now sitting on a new environment, the Source
Environment field of each user story is updated.

Important:

 The promotion branch creation and metadata deployment is orchestrated by the

deployment record. A deployment record must be created for these actions to be
triggered.
 A promotion branch will be created ONLY if the related user stories in the
promotion record have associated metadata changes through a Git operation.
 A Git promotion will always deploy from the promotion branch.
Manual Promotion
Introduction
User Stories can be also moved to upper environments in bulk. Instead of using
the Promote and Deploy option to migrate user stories separately from one
environment to another, you can mark them as Ready to Promote and group them
together in one promotion.

Case: After approving the User Acceptance Testing phase in the UAT Org, Rob
the Release Manager has to deploy the entire release to Production. For this
purpose, he needs to move all the approved User Stories together.
Solution: Rob checked that all the approved User Stories were marked as Ready to
Promote and were in the UAT Environment. He created a Promotion record with
the approved User Stories and deployed the Promotion.
Action Overview: By following the Promotion Process, Rob was able to deploy
his entire release to Production.

Creating a Promotion
1. Start by checking the required user stories as Ready to Promote.
2. Open the Promotion tab and press New.
3. Fill in all the fields marked as required and save.
4. Locate the Add User Stories tab. In this tab, you can find all the user stories in the
promotion Source Environment where Ready to Promote checkbox is set to
true.
5. Select the desired user stories and click the Add Selected User Stories button.

6. Navigate back to the Details tab and scroll down to the Selected User
Stories related list. You will see that now the user stories are listed here. You can
continue adding user stories as you complete them.

7. Once your promotion is ready, you will need to manually create the deployment
record. The steps to accomplish this will be later explained in this Module.

Important:
Remember that at this point, the promotion branch does not exist in your repository
yet. It will ONLY be created when you create the deployment of the promotion.

Tips:
Missing a User Story from the Available User Stories? Ensure the Ready to
Promote checkbox is flagged for the required user story and that its Source
Environment matches the promotion Source Environment.
Creating a Deployment from a Promotion
As your promotion is ready, you can go ahead and create a deployment. In order to
do this, just click on the Create Deployment button located in the Selected User
Stories panel.

Important:

Manually creating a deployment record is not a required step when using Promote
and Deploy. The deployment record creation will be handled by Copado when
using this functionality. Refer to the previous unit Promoting a User Story to
know more.

Relevant Fields of the Create Deployment Details Modal

 Deployment Name: By default, the name given to the deployment is “Deploy -
{Promotion Name} => {Destination Environment Name}”. This can be edited
afterwards.
 Validation Only: If checked, Copado will also create a promotion branch in your
repository, however the deployment step will be set as Check Only.

In the next unit, Creating a Validation Deployment, you will learn how you
can launch a validation deployment with Copado.

 Test Level: It will define the test level for this deployment. If you want to know
more about test levels, take a look at the article Apex Tests Run While Deploying in
the Resources section at the end of this unit.

After submitting the deployment details, you will see a notification “Promotion in
Progress” on your screen. This is just alerting you that Copado is creating the
promotion branch.
Refresh the page to validate that a newly created deployment record has been
added under the Deployments promotion’s related list.
Starting a Deployment
In the previous topic, you have learned how to create a deployment record out of a
promotion, so what’s next?

Open the deployment record to inspect it. Scroll down to the Steps section to
verify that the deployment contains a git promotion step.

Important

When manually creating the deployment, Copado won’t auto start the deployment
process. To execute it, click on Deploy.
This will launch the Deployment Wizard. Click on Deploy All to start the
deployment job. The Deploy Outstanding option is intended only to restart a
deployment job from the first failed step.

Immediately after launching the deployment, the status will be set

to Scheduled and, as the deployment is being executed, the promotion status will
be updated to mirror the deployment’s current status.
 Promoting a User Story
Suppose you just want to migrate a single user story. For instance, you have
applied a minor fix to a bug which does not share any dependency to another user
story, or you just discovered that one of the profiles in Production does not have
the proper access to a particular component.

For this use case, you can leverage the Promote and Deploy checkbox in the User
Story record. When this checkbox is selected, Copado triggers the creation of a
promotion and deployment records and then executes the deployment.

Case: Dave has completed the development process and committed his changes to
his assigned User Story. This User Story is critical for the sales team since they’re
locked out due to the lack of permissions in the Opportunity object. We need to
quickly promote and deploy this User Story so that it can be tested.
Solution:

1. Locate Dave’s completed User Story.

2. Check that the metadata components associated with the user story correspond to
the related change.
3. Select the Promote and Deploy checkbox in the User Story and Save.

Actions Overview: Since we used the Promote and Deploy functionality, Copado
will execute all the required actions following the Promotion Flow to deliver the
related changes to the next environment in the pipeline.

Tips:

You can locate the promotion record from the User Story Promotions related
list. User Story Promotion is a junction object between User Story and
Promotion.

Actions After the Promotion Execution:

 Once the deployment has been completed successfully, the User Story
credentials and the Environment will be updated to the next stage of your
Pipeline.
 The Promote and Deploy checkbox will be unchecked.
 Creating a Validation Deployment
Introduction
In some situations, you may not want to deploy your changes straightaway.
Instead, you want to check if your deployment will succeed or fail. A validation
deployment is used to check the results of deploying components to the destination
environment. If there is a potential conflict, you can review the errors and fix them
before actually deploying the changes.

During a validation deployment, Copado creates a promotion branch

named promotion/{PromotionName}-
CDValidate{UserStoryName}{DestinationEnvironmentName}, but no changes are
merged towards the destination branch. This action will not lead to any updates in
the environment of the user stories, and changes will not be deployed to the
destination environment.
To validate a user Story

1. From the User Story record, click on Validate Changes.

2. This will open an intermediary page to display the progress of this action is
displayed. During this process, Copado will create a Promotion and Deployment
records in Salesforce and a Promotion branch in Git. Once the validation job is
completed, you will be redirected to the user story.
3. In the User Story layout, there’s a section Validation Deployment Results, from
where you can navigate to the latest validation promotion and deployment records.
Also, you can view from the same User Story whether the deployment completed
successfully or with failures.

To validate a Promotion with multiple User Stories

1. From the Promotion record, click on Create Deployment. In the deployment

modal, flag the Validation Only checkbox:
2. When clicking on Submit, Copado will create a Deployment record in Salesforce
and a Promotion branch in Git.
3. The deployment will be added under the Deployments Promotion’s Related List,
from where you can open the record and execute the validation deployment.

Promotion Results
Introduction
The promotion’s execution can throw different results such as:

 Completed.
 Completed with Errors.
 Merge Conflict.
 Validated.
 Validation Failed.

Note: The Merge Conflict status will be discussed in the Conflict

Resolution module.

In this module, we will focus on the other possible status, where the status of the
promotion is determined by the outcome of the Salesforce deployment.
Reviewing a Successful Promotion
In order to guarantee your changes have been delivered, it is important to review
the promotion’s outcome.
 After a successful deployment, several actions will take place in order to reflect the
changes that happened.

1. The promotion branch will be merged into the destination branch.

2. The deployment and promotion status will be set to Completed Successfully and
Completed respectively.
3. All the user stories included in the promotion will be moved to the next
environment in the pipeline.
4. The previous org credential will be replaced by the org credential of the following
environment.

Note: After a completed promotion, Ready to Promote and Promote and

Deploy checkboxes in the User Story will be automatically unchecked.

Reviewing a Promotion with Errors

Oops! It can happen that your deployment ends with deployment errors. In this
case:

1. No changes will be pushed to the destination branch in Git.

2. The deployment status will be set to Completed with Errors.
3. Further, the user stories included in the deployment will remain in the same
environment.
 How to review Deployment Errors:

1. From the user story, open the related promotion record.

2. Locate the deployment under the Deployment related list in the promotion.
3. Review your deployment errors by clicking on the red flag icon in the deployment
step. This will open the Results tab where all the deployment results are listed.

How to proceed after a failed Deployment:

After you have reviewed and understood the deployment errors, you can go ahead
and recommit the required changes. There is no need to create a new user story
record, you can reuse the same user story if desired. Committing the components
will update the feature branch with the latest version of the files.

Then, you would like to retry the deployment. You can recreate a new promotion
branch to incorporate the changes by clicking on the Create Deployment button in
the promotion.
Validated
 You have performed a validation deployment and it ended successfully,
congratulations! You can perform a quick-deploy of a recent validation:
1. Open the Deployment record and locate the Git Promotion step.
2. Open the Git Promotion step, uncheck the CheckOnly checkbox and Save.
3. Click on Deploy and then Deploy All to start the deployment job.

Copado will get the validation key from the validation deployment and will
execute a second deployment without running the test classes. If the validation key
is not available or is not valid, Copado will fall back to the regular deployment
option.
Validation Failed
Your validation deployment has returned some failure messages. Follow the same
steps as in How to proceed after a failed Deployment in order to fix your
deployment errors. From there you can launch a new validation deployment to
confirm the output of the new deployment after your corrections.