With the CData Cmdlets users can install a data module, set the connection properties, and start scripting. This section provides examples of using our Domino Cmdlets with native PowerShell cmdlets, like the CSV import and export cmdlets.

Installing and Connecting

If you have PSGet, installing the cmdlets can be accomplished from the PowerShell Gallery with the following command. You can also obtain a setup from the CData site.

Install-Module DominoCmdlets

The following line is then added to your profile, loading the cmdlets on the next session:

Import-Module DominoCmdlets;

You can then use the Connect-Domino cmdlet to create a connection object that can be passed to other cmdlets:

$conn = Connect-Domino -Server 'https://domino.corp.com' -DataSource 'names' -Port '3002'

Connecting to Domino

To connect to Domino data, set the following properties:

• URL: The host name or IP of the server hosting the Domino database. Include the port of the server hosting the Domino database.
• DataSource: The datasource to connect to on the Domino URL.

Notes

1. DataSource: is the scope name found in your Domino Admin UI. Go to your Domino Admin UI, navigate to the Scope Management page, and obtain the scope name you want to connect to.

Authenticating to Domino

Domino supports the following types of authentication:

• OAuthJWT
• AzureAD

OAuthJWT

This authentication method exchanges Domino user credentials for a JWT token. This method uses Domino's internal JWT provider. To authenticate using OAuthJWT authentication, set AuthScheme to OAuthJWT and set the following properties:

• User: The username of the authenticating Domino user.
• Password: The password associated with the authenticating Domino user.

AzureAD

This authentication method uses Azure Active Directory as an IdP to obtain a JWT token. This method is used as an external JWT provider. You need to create a custom OAuth application in Azure Active Directory and configure it as an IdP. To do so, follow the instructions here: https://opensource.hcltechsw.com/Domino-rest-api/howto/IdP/configuringAD.html. To authenticate using AzureAD authentication, set AuthScheme to AzureAD and set the following properties:

• OAuthClientId: Set this to the Client ID obtained when setting up the custom OAuth application.
• OAuthClientSecret: Set this to the Client secret obtained when setting up the custom OAuth application.
• CallbackURL : Set this to the redirect URI defined when you registered your app. For example: https://localhost:33333

Notes

1. AzureTenant is generally supplied in the form companyname.microsoft.com, but it is also acceptable to specify the tenant Id. (The tenant Id is the same as the directory Id shown in the Azure Portal Azure Active Directory > Properties page.)

   When OAuthGrantType is set to CODE (the default), AzureTenant is usually not needed unless the user belongs to multiple tenants. When OAuthGrantType is set to CLIENT, AzureTenant is required.

2. The AzureAD AuthScheme is generally used with a custom OAuth application to establish the required OAuth credentials. These usually take the form of an account identifier or cllient ID, and the account password or client secret.

Retrieving Data

The Select-Domino cmdlet provides a native PowerShell interface for retrieving data:

$results = Select-Domino -Connection $conn -Table "Person" -Columns @("unid, FirstName") -Where "City='Miami'"

The Invoke-Domino cmdlet provides an SQL interface. This cmdlet can be used to execute an SQL query via the Query parameter.

Piping Cmdlet Output

The cmdlets return row objects to the pipeline one row at a time. The following line exports results to a CSV file:

Select-Domino -Connection $conn -Table Person -Where "City = 'Miami'" | Select -Property * -ExcludeProperty Connection,Table,Columns | Export-Csv -Path c:\myPersonData.csv -NoTypeInformation

You will notice that we piped the results from Select-Domino into a Select-Object cmdlet and excluded some properties before piping them into an Export-CSV cmdlet. We do this because the CData Cmdlets append Connection, Table, and Columns information onto each row object in the result set, and we do not necessarily want that information in our CSV file.

However, this makes it easy to pipe the output of one cmdlet to another. The following is an example of converting a result set to JSON:

 
PS C:\> $conn  = Connect-Domino -Server 'https://domino.corp.com' -DataSource 'names' -Port '3002'
PS C:\> $row = Select-Domino -Connection $conn -Table "Person" -Columns (unid, FirstName) -Where "City = 'Miami'" | select -first 1
PS C:\> $row | ConvertTo-Json
{
  "Connection":  {

  },
  "Table":  "Person",
  "Columns":  [

  ],
  "unid":  "Myunid",
  "FirstName":  "MyFirstName"
}