Octopus Deploy and Episerver's deployment API - Quickstart guide

There are of course much more you can do such as customizing your lifecycle and environments.

Using project variables as values instead of the predefined ones that the template offers.

You can also build in your own checks and reset process steps between the phases. These templates are just the tip of the iceberg and a foundation to get you started.

Known limitations

• When including database and blobs, the time it takes depends on the amount of blobs and size of database(s) that has to be copied. 
• You can only run one deployment at a time within the same DXP project.
• You can't use an empty environment as source environment (must contain code).
• You can't include database and/or blobs to production more than once.

Content Synchronization between environments

Import the following step template into Library > Step Templates

{
  "Id": "ad099926-f0ae-47c8-8ce9-263cea491eb2",
  "Name": "Episerver DXP - Content Sync",
  "Description": "Allows you to content sync from production to lower environments",
  "ActionType": "Octopus.Script",
  "Version": 1,
  "CommunityActionTemplateId": null,
  "Packages": [],
  "Properties": {
    "Octopus.Action.Script.ScriptSource": "Inline",
    "Octopus.Action.Script.Syntax": "PowerShell",
    "Octopus.Action.Script.ScriptBody": "if (-not (Get-Module -Name EpiCloud -ListAvailable)) {\n    Install-Module EpiCloud -Scope CurrentUser -Force\n}\n\nConnect-EpiCloud -ClientKey $ClientKey -ClientSecret $ClientSecret -ProjectId $ProjectId\n$deployments = Get-EpiDeployment -ProjectId $ProjectId\n$ongoingdeployid = 0\nForeach ($deployment in $deployments) {\n    if ($deployment.parameters.targetEnvironment -eq $targetenvironment ) {\n    \tif ($deployment.status -eq 'AwaitingVerification' -Or $deployment.status -eq 'InProgress' ) {\n          $ongoingdeployid = $deployment.id\n          Write-Host $deployment\n          break\n      \t}\n    }\n}\nWrite-Host \"You can see further progress by changing log level to Verbose\"\nif ($ongoingdeployid -eq 0) {\n\t$deployment = Start-EpiDeployment -ProjectId $ProjectId -SourceEnvironment $sourceenvironment -TargetEnvironment $targetenvironment -IncludeBlob -IncludeDb -Wait\n}\nelse {\n\tWrite-Warning \"There is already an ongoing deployment in progress ($ongoingdeployid). Complete or reset the ongoing deployment then try this again.\" \n}"
  },
  "Parameters": [
    {
      "Id": "22d4e3d6-0beb-4418-9728-6310919f7399",
      "Name": "ProjectId",
      "Label": "Project ID",
      "HelpText": "Your DXP project ID can easily be found in the API tab within the PaaS portal.",
      "DefaultValue": "",
      "DisplaySettings": {
        "Octopus.ControlType": "SingleLineText"
      }
    },
    {
      "Id": "be323764-e188-408b-b976-99d430872bbc",
      "Name": "ClientKey",
      "Label": "Client Key",
      "HelpText": "Your Client/API Key can be generated in the API tab within the PaaS portal.",
      "DefaultValue": "",
      "DisplaySettings": {
        "Octopus.ControlType": "SingleLineText"
      }
    },
    {
      "Id": "66abd295-3e03-4868-94b1-7c19e793b999",
      "Name": "ClientSecret",
      "Label": "Client Secret",
      "HelpText": "Your Client/API Key can be generated in the API tab within the PaaS portal.",
      "DefaultValue": "",
      "DisplaySettings": {
        "Octopus.ControlType": "Sensitive"
      }
    },
    {
      "Id": "ba515efc-b780-40f7-8bd7-101052cccb42",
      "Name": "sourceenvironment",
      "Label": "Source Environment",
      "HelpText": "Select the environment that has the database and blobs you want to synchronize from.",
      "DefaultValue": "",
      "DisplaySettings": {
        "Octopus.ControlType": "Select",
        "Octopus.SelectOptions": "Integration|Integration\nPreproduction|Preproduction\nProduction|Production"
      }
    },
    {
      "Id": "38449672-477e-48e3-aa99-efada447fad9",
      "Name": "targetenvironment",
      "Label": "Target Environment",
      "HelpText": "Select the environment that has the database and blobs you want to synchronize from.",
      "DefaultValue": "",
      "DisplaySettings": {
        "Octopus.ControlType": "Select",
        "Octopus.SelectOptions": "Integration|Integration\nPreproduction|Preproduction"
      }
    }
  ],
  "$Meta": {
    "ExportedAt": "2020-12-28T15:38:02.708Z",
    "OctopusVersion": "2020.4.11",
    "Type": "ActionTemplate"
  },
  "LastModifiedBy": "Your GitHub Username",
  "Category": "other"
}

You can then use it in a project process where all you have to do is specify the following properties:

1. Executed on the Octopus Server.
2. Project ID which you can find in the PaaS portal API tab.
3. Your client key.
4. Your client secret.
5. What environment you want to copy database and blobs from.
6. What environment you want to copy database and blobs to.

Once you run this step it will start the content synchronization between the selected environments.

The content synchronization process counts as a deployment. This process will restart the app service on the target environment.

Known limitations

• The time it takes depends on the amount of blobs and size of database(s) that has to be copied. 
• You can only run one deployment at a time within the same DXP project.
• You can't synchronize content to production, only from.

Exporting a DXP-hosted database to .bacpac file

Import the following step template into Library > Step Templates

{
  "Id": "054ebb26-4b9d-4636-a6e1-18d50afaad6c",
  "Name": "Episerver DXP - Export Database",
  "Description": "Description\nExports a database hosted in your DXP project as a .bacpac file which you can download and restore on a local environment.",
  "ActionType": "Octopus.Script",
  "Version": 1,
  "CommunityActionTemplateId": null,
  "Packages": [],
  "Properties": {
    "Octopus.Action.Script.ScriptSource": "Inline",
    "Octopus.Action.Script.Syntax": "PowerShell",
    "Octopus.Action.Script.ScriptBody": "if (-not (Get-Module -Name EpiCloud -ListAvailable)) {\n    Install-Module EpiCloud -Scope CurrentUser -Force\n}\n\nConnect-EpiCloud -ClientKey $ClientKey -ClientSecret $ClientSecret -ProjectId $ProjectId\n\n$startEpiExportmentSplat = @{\n    ProjectId = \"$ProjectId\"\n    Wait = $false\n    Environment = \"$sourceenvironment\"\n    DatabaseName = \"$databasename\"\n    ClientSecret = \"$ClientSecret\"\n    ClientKey = \"$ClientKey\"\n}\n \nWrite-Host \"Starting the Export. Environment: $sourceenvironment | DB Name: $databasename\"\n \n$export = Start-EpiDatabaseExport -RetentionHours $retentionhours @startEpiExportmentSplat\n\n$exportId = $export | Select -ExpandProperty \"id\"\n \n$getEpiExportSplat = @{\n    ProjectId = \"$ProjectID\"\n    ClientSecret = \"$ClientSecret\"\n    ClientKey = \"$ClientKey\"\n    Id = \"$exportId\"\n    Environment = \"$sourceenvironment\"\n    DatabaseName = \"$databasename\"\n}\n \n$timesRun = 0\n$currExport = Get-EpiDatabaseExport @getEpiExportSplat | Select-Object -First 1\n$status = $currExport | Select -ExpandProperty \"status\"\n$exit = 0\n\nwhile($exit -ne 1){\n \n$currExport = Get-EpiDatabaseExport @getEpiExportSplat | Select-Object -First 1\n \n$status = $currExport | Select -ExpandProperty \"status\"\n \nWrite-Host \"Exporting In Progress. Elapsed time - \"$timesRun\":00\"\n \nif($status -ne 'InProgress'){\n    $exit = 1\n}\n$timesRun = $timesRun + 1;\n \nstart-sleep -Milliseconds 60000\n \n}\n\nif($status -eq \"Failed\"){\n    throw \"Export Failed.\"\n}\n \n$downloadLink = $currExport | Select -ExpandProperty \"downloadLink\"\n \nWrite-Host \"Export Finished. The download URL is available for $retentionhours hours:`n $downloadLink `n`n\""
  },
  "Parameters": [
    {
      "Id": "22d4e3d6-0beb-4418-9728-6310919f7399",
      "Name": "ProjectId",
      "Label": "Project ID",
      "HelpText": "Your DXP project ID can easily be found in the API tab within the PaaS portal.",
      "DefaultValue": "",
      "DisplaySettings": {
        "Octopus.ControlType": "SingleLineText"
      }
    },
    {
      "Id": "be323764-e188-408b-b976-99d430872bbc",
      "Name": "ClientKey",
      "Label": "Client Key",
      "HelpText": "Your Client/API Key can be generated in the API tab within the PaaS portal.",
      "DefaultValue": "",
      "DisplaySettings": {
        "Octopus.ControlType": "SingleLineText"
      }
    },
    {
      "Id": "66abd295-3e03-4868-94b1-7c19e793b999",
      "Name": "ClientSecret",
      "Label": "Client Secret",
      "HelpText": "Your Client/API Key can be generated in the API tab within the PaaS portal.",
      "DefaultValue": "",
      "DisplaySettings": {
        "Octopus.ControlType": "Sensitive"
      }
    },
    {
      "Id": "ba515efc-b780-40f7-8bd7-101052cccb42",
      "Name": "sourceenvironment",
      "Label": "Source Environment",
      "HelpText": "Select the environment that has the database and blobs you want to synchronize from.",
      "DefaultValue": "",
      "DisplaySettings": {
        "Octopus.ControlType": "Select",
        "Octopus.SelectOptions": "Integration|Integration\nPreproduction|Preproduction\nProduction|Production"
      }
    },
    {
      "Id": "cb458a22-6232-4b1c-8151-08808c30cc84",
      "Name": "databasename",
      "Label": "Database",
      "HelpText": "Select the database you want to export. Commerce is only available for commerce projects.",
      "DefaultValue": "",
      "DisplaySettings": {
        "Octopus.ControlType": "Select",
        "Octopus.SelectOptions": "epicms|CMS (epicms)\nepicommerce|Commerce (epicommerce)"
      }
    },
    {
      "Id": "5b56305d-0d8b-4ec6-af41-5b65ea3db1d3",
      "Name": "retentionhours",
      "Label": "Retention Hours",
      "HelpText": "Specify how many hours the download link should be available for.\nMinimum is 1 hour. Maximum is 168 hours.",
      "DefaultValue": "24",
      "DisplaySettings": {
        "Octopus.ControlType": "SingleLineText"
      }
    }
  ],
  "$Meta": {
    "ExportedAt": "2020-12-19T12:31:30.222Z",
    "OctopusVersion": "2020.4.11",
    "Type": "ActionTemplate"
  },
  "LastModifiedBy": "Your GitHub Username",
  "Category": "other"
}

You can then use it in a project process where all you have to do is specify the following properties:

1. Executed on the Octopus Server.
2. Project ID which you can find in the PaaS portal API tab.
3. Your client key.
4. Your client secret.
5. What environment the database is hosted on.
6. What database to export, CMS or Commerce. If you do not have a commerce project in DXP then you will not have a commerce database.
7. How many hours the download link should be available.

Once you run this step it will export the database of your choice to a .bacpac file and return a URL where you can download it from.

Known limitations

• The Export Database process can take a long time from a few hours and up to four days (in extreme cases). 
• You can export only one database at a time within the same DXP project.

Exporting BLOBs to local path

Import the following step template into Library > Step Templates

{
  "Id": "a9daca16-6427-4246-9067-4b2f22863b06",
  "Name": "Episerver DXP - Export Blobs",
  "Description": "Exports a blobs hosted in your DXP project to a local path.",
  "ActionType": "Octopus.Script",
  "Version": 1,
  "CommunityActionTemplateId": null,
  "Packages": [],
  "Properties": {
    "Octopus.Action.Script.ScriptSource": "Inline",
    "Octopus.Action.Script.Syntax": "PowerShell",
    "Octopus.Action.Script.ScriptBody": "function ImportAzureStorageModule {\n    $azModuleLoaded = Get-Module -Name \"Az.Storage\"\n\n    if (-not ($azureModuleLoaded -or $azModuleLoaded)) {\n        try {\n            $null = Import-Module -Name \"Az.Storage\" -ErrorAction Stop\n            $azModuleLoaded = $true\n        }\n        catch {\n            Write-Verbose \"Tried to find 'Az.Storage', module couldn't be imported.\"\n        }\n    }\n\n    if ($azModuleLoaded) {\n        \"Az\"\n    }\n    else {\n        throw \"'Az.Storage' module is required to run this cmdlet.\"\n    }\n}\n\nfunction AddTlsSecurityProtocolSupport {\n    <#\n    .SYNOPSIS\n    This helper function adds support for TLS protocol 1.1 and/or TLS 1.2\n    .DESCRIPTION\n    This helper function adds support for TLS protocol 1.1 and/or TLS 1.2\n    #>\n\n    [CmdletBinding()]\n    param(\n        [Parameter(Mandatory=$false)]\n        [Bool] $EnableTls11 = $true,\n        [Parameter(Mandatory=$false)]\n        [Bool] $EnableTls12 = $true\n    )\n\n    # Add support for TLS 1.1 and TLS 1.2\n    if (-not [Net.ServicePointManager]::SecurityProtocol.HasFlag([Net.SecurityProtocolType]::Tls11) -AND $EnableTls11) {\n        [Net.ServicePointManager]::SecurityProtocol += [Net.SecurityProtocolType]::Tls11\n    }\n\n    if (-not [Net.ServicePointManager]::SecurityProtocol.HasFlag([Net.SecurityProtocolType]::Tls12) -AND $EnableTls12) {\n        [Net.ServicePointManager]::SecurityProtocol += [Net.SecurityProtocolType]::Tls12\n    }\n}\n\nfunction Join-Parts {\n    param\n    (\n        $Parts = $null,\n        $Separator = ''\n    )\n\n    ($Parts | Where-Object { $_ } | ForEach-Object { ([string]$_).trim($Separator) } | Where-Object { $_ } ) -join $Separator \n}\n  ####################################################################################\n  \n  If(!(test-path $downloaddestination))\n{\n      New-Item -ItemType Directory -Force -Path $downloaddestination\n}\n  \n  ####################################################################################\n  \nif ($PSVersionTable.PSEdition -eq 'Desktop' -and (Get-Module -Name AzureRM -ListAvailable)) {\n        Write-Warning -Message ('Az module not installed. Having both the AzureRM and ' +\n            'Az modules installed at the same time is not supported.')\n    } else {\n\t$env:PSModulePath = \"{0};{1}\" -f $env:PSModulePath, \"C:\\AzPowerShell\\Modules\"\n        Install-Module -Name Az -AllowClobber -Scope CurrentUser -Force\n    }\nif (-not (Get-Module -Name EpiCloud -ListAvailable)) {\n    Install-Module EpiCloud -Scope CurrentUser -Force\n}\n\nConnect-EpiCloud -ClientKey $ClientKey -ClientSecret $ClientSecret -ProjectId $ProjectId\n\t\n  ####################################################################################\n  \n     $linkSplat = @{\n        ProjectId = $ProjectId\n        Environment = $sourceenvironment\n        StorageContainer = $container\n\t\tRetentionHours = $retentionHours\n    }\n\n    $linkResult = Get-EpiStorageContainerSasLink @linkSplat\n\n    foreach ($link in $linkResult){\n        if ($link.containerName -eq $container) {\n\n            Write-Host \"Sas link           : $($link.sasLink)\"\n\n            $fullSasLink = $link.sasLink\n            $fullSasLink -match \"https:\\/\\/(.*).blob.core\" | Out-Null\n            $storageAccountName = $Matches[1]\n            Write-Host \"StorageAccountName : $storageAccountName\"\n\n            $fullSasLink -match \"(\\?.*)\" | Out-Null\n            $sasToken = $Matches[0]\n            Write-Host \"SAS token          : $sasToken\"\n        } else {\n            Write-Host \"Ignore container   : $($link.containerName)\"\n        }\n    }\n    \n    if ($null -eq $sasToken -or $sasToken.Length -eq 0) {\n        Write-Warning \"Did not found container $container in the list. Look in the log and see if your blob container have another name then mysitemedia. If so, specify that name as param -container. Example: Ignore container: projectname-assets. Then set -container 'projectname-assets'\"\n        exit\n    }\n\n\nAddTlsSecurityProtocolSupport\n\nImportAzureStorageModule\n\n$ctx = New-AzStorageContext -StorageAccountName $storageAccountName -SASToken $sasToken -ErrorAction Stop\n\nif ($null -eq $ctx){\n    Write-Error \"No context. The provided SASToken is not valid.\"\n    exit\n}\nelse {\n   $blobContents = Get-AzStorageBlob -Container $container  -Context $ctx | Sort-Object -Property LastModified -Descending\n\n    Write-Host \"Found $($blobContents.Length) BlobContent.\"\n\n    if ($blobContents.Length -eq 0) {\n        Write-Warning \"No blob/files found in the container '$container'\"\n        exit\n    }\n\n    if ($maxfiles -eq 0) {\n        $maxfiles = [int]$blobContents.Length\n    }\n    $downloadedFiles = 0\n    Write-Host \"---------------------------------------------------\"\n    foreach($blobContent in $blobContents)  \n    {  \n        if ($downloadedFiles -ge $maxfiles){\n            Write-Host \"Hit max files to download ($maxfiles)\"\n            break\n        }\n\n       $filePath = Join-Parts -Separator '\\' -Parts $downloaddestination, $blobContent.Name\n       $fileExist = Test-Path $downloaddestination -PathType Leaf\n\n       if ($fileExist -eq $false){\n            ## Download the blob content \n            Write-Host \"Download #$($downloadedFiles + 1) - $($blobContent.Name) $(if ($fileExist -eq $true) {\"overwrite\"} else {\"to\"}) $filePath\" \n            Get-AzStorageBlobContent -Container $container  -Context $ctx -Blob $blobContent.Name -Destination $downloaddestination -Force  \n            $downloadedFiles++\n       }\n       else\n       {\n            Write-Host \"File exist on disc: $filePath.\" \n       }\n\n        $procentage = [int](($downloadedFiles / $maxfiles) * 100)\n        Write-Progress -Activity \"Download files\" -Status \"$procentage% Complete:\" -PercentComplete $procentage;\n    }\n    Write-Host \"---------------------------------------------------\"\n}"
  },
  "Parameters": [
    {
      "Id": "22d4e3d6-0beb-4418-9728-6310919f7399",
      "Name": "ProjectId",
      "Label": "Project ID",
      "HelpText": "Your DXP project ID can easily be found in the API tab within the PaaS portal.",
      "DefaultValue": "",
      "DisplaySettings": {
        "Octopus.ControlType": "SingleLineText"
      }
    },
    {
      "Id": "be323764-e188-408b-b976-99d430872bbc",
      "Name": "ClientKey",
      "Label": "Client Key",
      "HelpText": "Your Client/API Key can be generated in the API tab within the PaaS portal.",
      "DefaultValue": "",
      "DisplaySettings": {
        "Octopus.ControlType": "SingleLineText"
      }
    },
    {
      "Id": "66abd295-3e03-4868-94b1-7c19e793b999",
      "Name": "ClientSecret",
      "Label": "Client Secret",
      "HelpText": "Your Client/API Key can be generated in the API tab within the PaaS portal.",
      "DefaultValue": "",
      "DisplaySettings": {
        "Octopus.ControlType": "Sensitive"
      }
    },
    {
      "Id": "ba515efc-b780-40f7-8bd7-101052cccb42",
      "Name": "sourceenvironment",
      "Label": "Source Environment",
      "HelpText": "Select the environment that has the database and blobs you want to synchronize from.",
      "DefaultValue": "",
      "DisplaySettings": {
        "Octopus.ControlType": "Select",
        "Octopus.SelectOptions": "Integration|Integration\nPreproduction|Preproduction\nProduction|Production"
      }
    },
    {
      "Id": "cb458a22-6232-4b1c-8151-08808c30cc84",
      "Name": "container",
      "Label": "Storage Container",
      "HelpText": "Name of the storage container you want to download blobs from.",
      "DefaultValue": "mysitemedia",
      "DisplaySettings": {
        "Octopus.ControlType": "SingleLineText",
        "Octopus.SelectOptions": "epicms|CMS (epicms)\nepicommerce|Commerce (epicommerce)"
      }
    },
    {
      "Id": "1996bf35-de57-4a5e-9147-20b4445e0998",
      "Name": "downloaddestination",
      "Label": "Destination Folder",
      "HelpText": "Path where the files should be downloaded to, for example C:\\temp",
      "DefaultValue": "",
      "DisplaySettings": {
        "Octopus.ControlType": "SingleLineText"
      }
    },
    {
      "Id": "9a29b2c0-025a-41f0-8433-b5559436309d",
      "Name": "maxfiles",
      "Label": "Maximum amount of files to download",
      "HelpText": "Specify how many files you want to download. Use 0 for all.",
      "DefaultValue": "0",
      "DisplaySettings": {
        "Octopus.ControlType": "SingleLineText"
      }
    },
    {
      "Id": "5b56305d-0d8b-4ec6-af41-5b65ea3db1d3",
      "Name": "retentionHours",
      "Label": "Retention Hours",
      "HelpText": "Specify how many hours the download link should be available for.\nDefault is 24 hours.",
      "DefaultValue": "24",
      "DisplaySettings": {
        "Octopus.ControlType": "SingleLineText"
      }
    }
  ],
  "$Meta": {
    "ExportedAt": "2020-12-20T14:23:16.161Z",
    "OctopusVersion": "2020.4.11",
    "Type": "ActionTemplate"
  },
  "LastModifiedBy": "Your GitHub Username",
  "Category": "other"
}

You can then use it in a project process where all you have to do is specify the following properties:

1. Executed on the Octopus Server.
2. Project ID which you can find in the PaaS portal API tab.
3. Your client key.
4. Your client secret.
5. What environment the blobs are hosted on.
6. The container name.
7. Destination folder where your blobs should be downloaded to.
8. Amount of files it should download (0 to download all).
9. How many hours the generated download link used to download the blobs should be available.

Once you run this step it will export (download) the blobs within the specified container to the local path you've specified.