API improvements


I spent ages trying to get a Powershell script to work with the REST API and I came across a quirk which you might want to improve in future versions. Some of the element names have dots in them which makes it confusing trying to access them.

This is from the GET response for a deployment process

  "Id": "deploymentprocess-projects-1",
  "ProjectId": "projects-1",
  "Steps": [
      "Id": "d8beb16d-c728-4c12-8fb9-365ecb77878a",
      "Name": "Deploy NetDAService",
      "RequiresPackagesToBeAcquired": false,
      "Properties": {
        "Octopus.Action.TargetRoles": "application-server"
      "Condition": "Success",
      "Actions": [
          "Id": "action-d8beb16d-c728-4c12-8fb9-365ecb77878a",
          "Name": "Deploy NetDAService",
          "ActionType": "Octopus.TentaclePackage",
          "Environments": [],
          "Properties": {
            "Octopus.Action.Package.NuGetPackageId": "MyService",
            "Octopus.Action.Package.NuGetFeedId": "feeds-1",
            "Octopus.Action.Package.CustomInstallationDirectory": "",
            "Octopus.Action.Package.CustomInstallationDirectoryShouldBePurgedBeforeDeployment": "False",
            "Octopus.Action.Package.AutomaticallyUpdateAppSettingsAndConnectionStrings": "True",
            "Octopus.Action.Package.AutomaticallyRunConfigurationTransformationFiles": "True",
            "Octopus.Action.Package.AdditionalXmlConfigurationTransforms": "",
            "Octopus.Action.Package.UpdateIisWebsite": "False",
            "Octopus.Action.Package.UpdateIisWebsiteName": "",
            "Octopus.Action.Package.DownloadOnTentacle": "False",
            "Octopus.Action.EnabledFeatures": "Octopus.Features.ConfigurationTransforms,Octopus.Features.ConfigurationVariables,Octopus.Features.CustomDirectory,Octopus.Features.IisHome"
          "SensitiveProperties": {}
      "SensitiveProperties": {}

Notice all the elements with name Octopus.Action.Package.Something. When I try to reference these with, e.g.,


it always returns null.

After much anguish, I finally worked out that instead, I have to do


with quotes, because the name of the element is Octopus.Action.TargetRoles otherwise Powershell assumes each bit between the dots is a separate object.

Thanks for sharing this. The reason those properties have dots is that the Properties property is actually a Dictionary<string,string>, and it’s designed to hold a variable number of properties. In C#/JavaScript we usually access it as Properties[“X.Y.Z”] - it’s good to know how to do it from PowerShell. Hopefully anyone looking for how to use the Octopus REST API from PowerShell will find this page.


Thank you for sharing this info!