Sergii Vorushylo
Oct 29, 2019
(9 votes)

Getting started with deployment API in DXC

We just have released Deployment API in DXC-S as an Open Beta program. This feature allows partners and customers to automate deployment to DXC environments via API. 

There are two ways to deploy code changes via API: 

  1. Using a source environment - this is a traditional way to push changes in DXC. The application code is deployed to the Integration environment using any preferred tool supported by Azure Web Apps, and then get promoted to the Preproduction environment, and after that to the Production environment. The deployment flow is sequential.
  2. Using code packages - this is a new method. It requires to package your application code as a NuGet package first, and then it can be deployed to any environment. The deployment flow is much more flexible, but with great powers comes great responsibility, so we highly recommend to deploy your package to any non-production environment first before deploying it to Production.

It is possible to mix both ways, but it worth mentioning that we see the code packages as a primary way of doing deployments in the future.

How do I get started?

First, you will need to get Deployment API credentials. You can generate it using the DXC-S Management portal. The API credentials are specific per target environment. So if you are planning to deploy from Integration to Preproduction environment, you need to provide API credentials for Preproduction.

Next, install EpiCloud PowerShell module.

Now we are ready to start our first deployment via API. Let's deploy a CMS site from Integration to Preproduction. Open a PowerShell prompt and use the commands listed below.

The Import-Module command makes EpiCloud cmdlets available in the current PowerShell prompt:

Import-Module EPiCloud

The Connect-EpiCloud command stores API credentials in the console session, so we don't need to specify it again with every command:

Connect-EpiCloud -ClientKey <...> -ClientSecret <...>

And the Start-EpiDeployment will kick-off a deployment process:

Start-EpiDeployment -ProjectId ae874a90-08de-4a03-a865-aaf500f4830e -SourceApp cms -SourceEnvironment Integration -TargetEnvironment Preproduction

The command will respond with the current deployment status and deployment id:

id                 : 5eec46c4-df99-47e6-a6b9-aaf5010874f8
projectId          : ae874a90-08de-4a03-a865-aaf500f4830e
status             : InProgress
startTime          : 2019-10-29T16:00:51.123Z
endTime            :
percentComplete    : 0
validationLinks    : {}
deploymentWarnings : {}
deploymentErrors   : {}
parameters         : @{targetEnvironment=Preproduction; sourceEnvironment=Integration; sourceApps=System.Object[]; maintenancePage=False; includeBlob=False; includeDb=False}

The deployment id is needed to get the deployment status and to complete or reset the deployment. In order to get the deployment status use Get-EpiDeployment command:

Get-EpiDeployment -ProjectId ae874a90-08de-4a03-a865-aaf500f4830e -Id 5eec46c4-df99-47e6-a6b9-aaf5010874f8

Once the first stage of the deployment is finished, we can validate the site on the deployment slot. The URL to the slot can be found in the validationLinks property in the Get-Deployment command response:

id                 : 5eec46c4-df99-47e6-a6b9-aaf5010874f8
projectId          : ae874a90-08de-4a03-a865-aaf500f4830e
status             : AwaitingVerification
startTime          : 2019-10-29T16:10:14.198Z
endTime            :
percentComplete    : 100
validationLinks    : {}
deploymentWarnings : {}
deploymentErrors   : {}
parameters         : @{targetEnvironment=Preproduction; sourceEnvironment=Integration; sourceApps=System.Object[]; maintenancePage=False; includeBlob=False; includeDb=False}

Now we can either complete or reset the deployment. There are two corresponding commands for that:

Complete-EpiDeployment -ProjectId ae874a90-08de-4a03-a865-aaf500f4830e -Id 5eec46c4-df99-47e6-a6b9-aaf5010874f8 


Reset-EpiDeployment -ProjectId ae874a90-08de-4a03-a865-aaf500f4830e -Id 5eec46c4-df99-47e6-a6b9-aaf5010874f8

After running the Complete-EpiDeployment command we get the deployment status displayed:

id                 : 5eec46c4-df99-47e6-a6b9-aaf5010874f8
projectId          : ae874a90-08de-4a03-a865-aaf500f4830e
status             : Completing
startTime          : 2019-10-29T16:20:51.123Z
endTime            :
percentComplete    : 0
validationLinks    : {}
deploymentWarnings : {}
deploymentErrors   : {}
parameters         : @{targetEnvironment=Preproduction; sourceEnvironment=Integration; sourceApps=System.Object[]; maintenancePage=False; includeBlob=False; includeDb=False}

The Complete-EpiDeployment command swaps the slot and deployment is now completed!

If you want to learn more, you can find a detailed description of all commands provided with the EpiCloud module in the documentation.

Using Azure DevOps? This blog post describes how to configure a continuous delivery pipeline with DXC-S.

Oct 29, 2019


Eric Markson
Eric Markson Oct 29, 2019 07:19 PM

This is absolutely awesome. I cannot wait to start using this! 

Ravindra S. Rathore
Ravindra S. Rathore Oct 30, 2019 05:50 AM

Great, very excited to use this in future. 

Stefan Holm Olsen
Stefan Holm Olsen Oct 30, 2019 06:53 AM

This so cool!

For the code package approach, do you think it would be possible to integrate it with TeamCity or Octopus Deploy?

Darren Stahlhut
Darren Stahlhut Oct 30, 2019 07:11 AM

Awesome! Thank you Episerver! 

Sergii Vorushylo
Sergii Vorushylo Oct 30, 2019 07:58 AM

@Stefan yes, of course, it is possible. And we are planning to provide more examples of how to do it. 

Tien Quach
Tien Quach Oct 31, 2019 05:16 AM

Nice feature!

Darren Sunderland
Darren Sunderland Nov 1, 2019 12:06 PM

I have had a play with this in our integration site but after running the command Complete-EpiDeployment, I get the status displayed as specified but the process never completes - or at least hasn't completed after 2 hours! 

Checking the status with Get-EpiDeployment shows that the deployment is still in the completing phase, leaving the maintenance page being displayed for the site.

Running either of the commands Complete-EpiDeployment or Reset-EpiDeployment, and I get an error stating that a prior deployment is in progress. Thus leaving me unable to progress any further.

I got our integration site back up by publishing from Visual Studio, but due to the status being stuck we are currently not able to deploy to pre-production or production via the PaaS portal.

Sergii Vorushylo
Sergii Vorushylo Nov 3, 2019 07:57 PM

@Darren sorry, this is definitely not the experience we are aiming for. I have checked the logs, and it seems there was an issue with the underlying infrastructure - the Complete job hasn't started for several hours for some reason, we will investigate a possible cause. Regarding the deployment status, it will timeout after about two hours so that a new deployment can be started. I checked your project, and it is not blocked anymore, the deployment to integration is marked as failed due timeout as expected. Please, do not hesitate to contact Episerver support in order to get help if you face with deployment issues again. 

Darren Sunderland
Darren Sunderland Nov 6, 2019 09:26 AM

@Sergii ths issue is now resolved and the deployment pipeline works all the way through the stack to production.

Stian L-S
Stian L-S Feb 13, 2020 09:15 AM

Hi, this is a great feature for sure - but I'm having similar issues to Darren here.

My current pipeline deploys a regular web deploy .zip package to the app directly, using about a minute. 

The DXC API pipeline spent 35 minutes waiting at 80% completed in "InProgress" state. Any way of improving that? Should I raise a support case?

Anders Wahlqvist
Anders Wahlqvist Feb 14, 2020 03:11 PM

@Stian - Sounds like your site is having warmup issues of some sort, especially if it happens on every deployment. If you download the detailed deployment log through PaaS portal for that deployment, you'll find more information on what took so much time, or feel free to raise a support ticket if you need help with checking out the root cause for that.

Some links on the subject that might also be of help:

Ove Lartelius
Ove Lartelius May 14, 2020 11:00 PM

Thx Sergii! Your post has been a great source.

At Epinova we have created a Azure DevOps extension that contains tasks so that is very simple to use the DXP deployment API. No powershell is needed. (Repo/Documentation)

Please login to comment.
Latest blogs
How to Write an xUnit Test to Verify Unique Content Type Guids in Content Management

When developing an Optimizely CMS solution, it is important to ensure that each content type has a unique GUID. If two or more content types share...

Minesh Shah (Netcel) | Mar 27, 2023

Extend TinyMCE in Optimizely CMS 12

Since technologies are upgraded to newer versions the ways to extend or override the out-of-the-box functionality are also changed a little bit so...

Ravindra S. Rathore | Mar 27, 2023 | Syndicated blog

Telemetry correlation for Scheduled Jobs in Optimizely

I previously demonstrated how to correlate telemetry to Azure Application Insights within a Hangfire job. But how about those jobs that are built a...

Stefan Holm Olsen | Mar 23, 2023 | Syndicated blog

Fixing Optimizely Content Syncing/Caching Issues on the DXP pre CMS.Core 12.13.0

Hi all, With our recent deployments to the DXP for .NET 6 projects (one a new build and one an upgrade) our clients had raised issues where there...

Scott Reed | Mar 23, 2023