EpiCloud Powershell module

To simplify usage of the Deployment API, a PowerShell module EpiCloud is available, which contains the following cmdlets:

Connect-EpiCloud – Supplies the required credentials to other commands in the module, simplifying overall cmdlet usage.
Get-EpiDeploymentPackageLocation – Returns a SAS link to upload deployment packages using Add-EpiDeploymentPackage.
Add-EpiDeploymentPackage – Upload a deployment package to the DXP environment to use for deployments; requires the Azure PowerShell modules (Azure.Storage or Az.Storage) to run.
Start-EpiDeployment – Starts a deployment.
Get-EpiDeployment – Fetches information about deployments (ongoing or finished).
Complete-EpiDeployment – Completes a deployment that is in the verification stage. (Same as Complete/Go Live in the management portal)
Reset-EpiDeployment – Resets or Complete Reset a deployment in the verification or reset-verification stages. (Same as Reset/Complete Reset in the management portal.)

📘
Note
You can restore the database if you used UseMaintenancePage parameter for the deployment.
Start-EpiDatabaseExport – Starts a database export. You can specify the wait parameter to wait until the export has finished.
Get-EpiDatabaseExport – Get the status of the database export and return a link to the exported database if it is finished.

For examples of how to use the commands and descriptions on parameters, enter the Get-Help cmdlet in the PowerShell console.

Get-Help Start-EpiDeployment -Full

Or, if you want a graphical interface to access the help:

Get-Help Start-EpiDeployment -ShowWindow

Install the module

Get the module from the PowerShell Gallery. To install it, open PowerShell and run the following command:

Install-Module -Name EpiCloud -Scope CurrentUser

This installs the module for the current user (and does not require Administrator privileges). For instructions about using the PowerShell Gallery and the related PowerShell cmdlets for managing modules and scripts, see Get started with the PowerShell Gallery by Microsoft.

Import the module

If you install the module from the PowerShell Gallery, the module is automatically loaded when you call a cmdlet. To explicitly import the module, use the following command:

Import-Module EpiCloud

Add credentials to the PowerShell scope

Optionally, you can add your credentials to the current PowerShell scope by calling the Connect-EpiCloud cmdlet with your ClientKey, ClientSecret, and ProjectId, after which you do not have to specify the ClientKey, ClientSecret, or ProjectId for any other of the cmdlets in the module during the session. For example, you can also specify these for each cmdlet if it is running on a build server.

Connect-EpiCloud -ClientKey <ClientKey> -ClientSecret <ClientSecret> -ProjectId <ProjectId>

Upload a code package to DXP

To upload a code package to your DXP project, run Get-EpiDeploymentPackageLocation to get the SAS link where the package should be uploaded, and then Add-EpiDeploymentPackage to upload that package, as follows. See Create code packages for details on what the package should look like.

$saslink = Get-EpiDeploymentPackageLocation
Add-EpiDeploymentPackage -SasUrl $saslink -Path C:\MyDeploymentPackages\cms.app.1.0.0.nupkg

The code package is now available for deployment.

📘
Note
If you change the content you have to update the package version. If you attempt to upload a code package with the same name as one already uploaded, the system compares their checksums. If the checksums match, it does not upload the file. However, if the checksums differ, you receive an error because you cannot overwrite an existing package.

Deploy code and content

You can use code packages, source environment, or smooth deploy approaches to start the code deployment.

Deploy from the code package

To deploy this package to the Preproduction environment, use the following command:

Start-EpiDeployment -DeploymentPackage cms.app.1.0.0.nupkg -TargetEnvironment Preproduction

Deploy directly to Web App without a slot swap

To speed up deployments, use DirectDeploy to deploy directly to the target Web App without performing a swap. You can apply DirectDeploy for Integration, Development, and Testing target environments:

Start-EpiDeployment -DeploymentPackage cms.app.1.0.0.nupkg -TargetEnvironment Integration -DirectDeploy

Deploy from a source environment

To deploy code from a source environment, use the following command:

Start-EpiDeployment -SourceEnvironment Integration -TargetEnvironment Preproduction -SourceApp cms,commerce

-SourceApp accepts app type names CMS and Commerce (PaaS) to specify which app from a source environment to copy.
To deploy content, use the following command:
```
Start-EpiDeployment -SourceEnvironment Integration -TargetEnvironment Preproduction -IncludeBlob -IncludeDb
```
-IncludeBlob copies BLOBs from source to target environment.
-IncludeDb copies the DB from source to target environment.

❗️
Warning
To deploy from a source environment to a target environment, create an API credential through the DXP Management Portal that has permission to both environments.
Overwriting content in production is not recommended. However, the deployment API permits copying BLOBs and databases to production if you specified a -SourceApp and a maintenance option (-ZeroDownTimeMode or -UseMaintenancePage). Be aware that this overwrites ALL content in the production environment. After the initial deployment to production, specifying a -SourceApp is mandatory, and a maintenance option must be chosen for subsequent deployments.

Deploy with smooth deployment

You can use Smooth deploy/Zero Downtime deployment (ZDD) for code packages and a source environment. See Smooth deployment and use the following command:

Start-EpiDeployment -SourceEnvironment Integration -TargetEnvironment Preproduction -ZeroDowntimeMode ReadOnly

-ZeroDowntimeMode accepts values ReadOnly and ReadWrite. For sites that do not support ZDD (such as Commerce Manager), a maintenance page is used instead (if those sites are part of the deployment).

Start the deployment

The deployment starts immediately, and the cmdlet returns an object containing the deployment's Id. If you specify the -Wait switch the cmdlet waits for the deployment to finish before it returns. You can use the -UseMaintenancePage switch to enable a maintenance page during the deployment if there are DB changes.

Use -Verbose for additional logging information. (This switch can be added to any cmdlet.)

If you want to check the status of deployment or list deployments made through the API for the project, use the following command:

Get-EpiDeployment

To get the details of a specific deployment, specify the Id of that deployment (it returns the same type of object as Start-EpiDeployment):

PS> Get-EpiDeployment -Id 2a52c873-b39c-4f44-b842-aab5009c3060
 
id                 : 2a52c873-b39c-4f44-b842-aab5009c3060
projectId          : 2a561398-d517-4634-9bc4-aab5008a8e1a
status             : InProgress
startTime          : 2019-08-26T09:28:39.479Z
endTime            :
percentComplete    : 2
validationLinks    : {}
deploymentErrors   : {}
deploymentWarnings : {}
parameters         : @{targetEnvironment=Preproduction; packages=System.Object[]; maintenancePage=False}

To see details, expand the parameters property. You can also get the output as JSON:

Get-EpiDeployment -Id 2a52c873-b39c-4f44-b842-aab5009c3060 | ConvertTo-Json

After the deployment finishes, run Reset or Complete using the respective functions such as in the following examples:

Complete

Complete-EpiDeployment -Id 2a52c873-b39c-4f44-b842-aab5009c3060

Reset

Reset-EpiDeployment -Id 2a52c873-b39c-4f44-b842-aab5009c3060

If UseMaintenancePage parameter was used for the deployment, you can use RollbackDatabase and ValidateBeforeSwap options when you reset a deployment. Use ValidateBeforeSwap option to validate the reset progress before completing the reset.

Complete Reset

Reset-EpiDeployment -Id 2a52c873-b39c-4f44-b842-aab5009c3060 -Complete

Reset-EpiDeployment and Complete-EpiDeployment also have a -Wait switch if you want the cmdlets to return after the action has finished.

Most of the cmdlets in the module also support pipelining, such as the following example:

Get-EpiDeployment -Id 2a52c873-b39c-4f44-b842-aab5009c3060 | Complete-EpiDeployment

Start-EpiDatabaseExport

Start-EpiDatabaseExport -Environment Integration -DatabaseName epicms -Wait

See also: Optimizely Cloud REST API