PowerShell scripting documentation

Hello Marcel,

Thank you for your feedback. We will coordinate with the support team to see how we can address this in our documentation. We’ll get back to you once we have an update.

Best regards,

Hello Marcel,

We apologize for this delayed reply.

Regarding PowerShell sample scripts that use the DVLS cmdlets, you can find a few samples on our GitHub repository for managing entries. You can also find a few samples in our Devolutions PowerShell forum section.

For creating data sources using RDM cmdlets, Method 1 in this article explains that we can use an Application identity to connect to a DVLS data source automatically without providing a password. The sample script below is an improved version to avoid creating a new data source each time we run it. Make sure the application identity you use has all the required permissions on the object you want to manage. And instead of storing the application identity key and secret in the script, it's possible to use parameters or environment variables.

$dsname = "DVLS PowerShell"
$ds = Get-RDMDataSource -Name $dsname

if ([string]::IsNullOrEmpty($ds))
{
  $dsname = "DVLS PowerShell"
  $dsurl = "https<area>://your_dvls_url"
  $appkey = "your_appkey"
  $appsecret = "your_appsecret"

  $ds = New-RDMDataSource -DVLS -Name $dsname -Server $dsurl -ScriptingTenantID $appkey -ScriptingApplicationPassword $appsecret -SetDatasource -WarningAction SilentlyContinue
  Set-RDMDataSource $ds
}

Set-RDMCurrentDataSource $ds

If you get an authentication prompt when running the above script, it's because a data source already exists on the machine you are running this script on, and it's the default one. In that case, we recommend overriding the PowerShell configuration with the Use an override configuration method to isolate the newly created data source from the existing ones.

Regarding how we can verify if the connection is active when using DVLS cmdlets, when the token expires, we get the following error on any cmdlet we try to run. I have asked the developer team if we have a method to get the token state and/or refresh it regularly. I'll get back to you on this one.

PS C:\Users\administrator.WINDJAMMER> $v = Get-DSVault -All
Get-DSVault: Result: WebApiRedirectToLogin

Let me know if that answers most of your questions regarding how we can use the Devolutions PowerShell module.

Thank you for your collaboration.

Best regards,

Hello.

Thanks for your reply.
I will have to dive into this again at some point, but for now I don't have a use case anymore.
But generally, I would appreciate having more examples on how to code with PS and how to use the various sets of commands.
They all seem to work differently, and their usage is not very straightforward.
For me, automation mostly means non-interactive, so authentication also needs to be non-interactive, and I was having difficulties setting up something, because it's not documented in an easy to find way on your website.

Best regards.
Marcel

Hello,

Thank you for your feedback.

About the non-interactive authentication, when using it in an isolated environment where no other RDM data sources are configured, it should be non-interactive. We will update our documentation to provide a clearer example of this configuration.

Regarding the cmdlets' usage, most of them contain documentation from PowerShell using the Get-Help <Devolutions cmdlet>, like the following command. It should list the parameters and a few sample methods to use the given cmdlet.

Get-Help Get-RDMDataSource -Full

I hope this helps!

Best regards,

Hello Érica.

Yes every commandlet has its own documentation.
But there is no documentation / example about relationship of these commandlets.
More specifically, the authentication / connection to a DS and then the use of subsequent cmdlets.
Saying what a cmdlt does is good, but it can also be useful to describe some use cases and example on how to use them.

Best regards.
Marcel

Hello Marcel,

Thank you for your feedback.

We have opened an internal ticket as a project to improve the PowerShell online documentation to describe use cases and provide other sample scripts on our GitHub. This is a long-term project, but we will still inform you in this thread when any improvements are released.

Thank you for your collaboration and for being so patient.

Best regards,

Hi Erica,

I'm having the same issues as Marcel.
The official documentation does not really explain anything about actual use cases.
Searching in your forums is very time consuming. Forums aren't meant to be documentation anyway.
The github is lacking examples.

For instance, I would need a full working example on how to create new RDP entries, running non-interactively, for an automation process.

Best regards,
Damien

Hello.

Here's a working example with using application identity and DVLS Server commandlets.

$env:DS_URL= "https://<your-dvls-server>/dvls"
$env:DS_USER = "<application-id>"
$env:DS_PASSWORD = "<application-password>"

[string]$Username = $env:DS_USER
[string]$Password = $env:DS_PASSWORD
[string]$DVLSUrl = $env:DS_URL

[securestring]$SecPassword = ConvertTo-SecureString $Password -AsPlainText -Force
[pscredential]$Creds = New-Object System.Management.Automation.PSCredential ($Username, $SecPassword)

$Response = New-DSSession -Credential $Creds -BaseURI $DVLSUrl -AsApplication
$entries = Get-DSEntries -All

# do whatever with the entries.

Cheers.
Marcel

Hello,

Thank you for your sample, Marcel.

Damien, following the connection, you can use the following method to create an entry based on an existing one.

$entryId = 'aab16c59-4108-4558-9010-12a086e769dc'
$e = Get-DSEntry -EntryId $entryId -AsRDMConnection

$p = Convert-XMLToPSCustomObject -XML $e.ConnectionInfo.data
$p.Connection | Add-Member -MemberType NoteProperty -Name Description -Value 'New Description' # Added description property
$p.Connection.Name = 'MyNewName' # Updated name property

$xml = Convert-PSCustomObjectToXML -Object $p
$e.ConnectionInfo.Data = $xml.OuterXml

# update the properties of the $e.Connection.Data here

New-DSEntryBase -FromRDMConnection $e.ConnectionInfo

Let me know if that helps.

Best regards,