With the CData Cmdlets users can install a data module, set the connection properties, and start scripting. This section provides examples of using our HubSpot 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 HubSpotCmdlets

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

Import-Module HubSpotCmdlets;

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

$conn = Connect-HubSpot

Authenticating to HubSpot

HubSpot supports OAuth authentication and PrivateAppToken-based authentication.

Note: The HubspotV3 schema contains two tables that only work with PrivateAppToken authentication: QuoteAssociations and Quotes. For further information, see Data Model > HubSpot V3 Data Model > Tables.

OAuth

HubSpot provides embedded OAuth credentials that simplify connection from a Desktop application or a Headless machine. To connect from a Web application, you must create a custom OAuth application, as described in Creating a Custom OAuth Application.

To connect via OAuth from all authentication flows, you must set AuthScheme to OAuth.

The following subsections describe how to authenticate to HubSpot from the available OAuth flows. For information about how to create a custom OAuth aplication, and why you might want to create one even for auth flows that already have embedded OAuth credentials, see Creating a Custom OAuth Application.

For a complete list of connection string properties available in HubSpot, see Connection.

Desktop Applications

CData provides an embedded OAuth application that simplifies authentication at the desktop;.

You can also authenticate from the desktop via a custom OAuth application, which you configure and register at the HubSpot console. For further information, see Creating a Custom OAuth Application.

Get and Refresh the OAuth Access Token

After setting the following, you are ready to connect:

• OAuthClientId (custom applications only): The client Id assigned when you registered your custom OAuth application.
• OAuthClientSecret (custom applications only): The client secret assigned when you registered your custom OAuth application.
• CallbackURL (custom applications only): The redirect URI defined when you registered your custom OAuth application.

When you connect, the cmdlet opens HubSpot's OAuth endpoint in your default browser. Log in and grant permissions to the application. The cmdlet refreshes the access token automatically when it expires.

Headless Machines

To configure the driver to use OAuth with a user account on a headless machine, you must authenticate on another device that has an internet browser.

Do one of the following:

• Option 1: Obtain the OAuthVerifier value as described below in "Obtain and Exchange a Verifier Code".
• Option 2: Install the cmdlet on a machine with an internet browser and transfer the OAuth authentication values after you authenticate through the usual browser-based flow, as described below in "Transfer OAuth Settings".

Option 1: Obtain and Exchange a Verifier Code

To obtain a verifier code, you must authenticate at the OAuth authorization URL.

To authenticate from the machine with an internet browser and obtain the OAuthVerifier connection property, follow the steps below.

1. Do either of the following actions:
   • If you are using the Embedded OAuth Application, call the GetOAuthAuthorizationURL stored procedure. Open the URL returned by the stored procedure in a browser.
   • If you are using a custom OAuth application, set these properties:
     • InitiateOAuth: OFF.
     • OAuthClientId: The client Id assigned when you registered your custom OAuth application.
     • OAuthClientSecret: The client secret assigned when you registered your custom OAuth application.
     Then call the GetOAuthAuthorizationURL stored procedure with the appropriate CallbackURL. Open the URL returned by the stored procedure in a browser.
2. Log in and grant permissions to the cmdlet. You are redirected to the redirect URI. A parameter called code is appended to the redirect URI. Note the value of this parameter. You will need it later, to set the OAuthVerifier connection property.

Next, you must exchange the OAuth verifier code for OAuth refresh and access tokens.

On the headless machine, set the following connection properties to obtain the OAuth authentication values:

• InitiateOAuth: REFRESH.
• OAuthSettingsLocation: Persist the encrypted OAuth authentication values to the specified location.
• OAuthVerifier: The noted verifier code (the value of the code parameter in the redirect URI).
• OAuthClientId (custom applications only): The client Id in your custom OAuth application settings.
• OAuthClientSecret (custom applications only): The client secret in the custom OAuth application settings.

Test the connection to generate the OAuth settings file, then re-set the following properties to connect:

• InitiateOAuth: REFRESH.
• OAuthSettingsLocation: The location containing the encrypted OAuth authentication values. Make sure this location gives read and write permissions to the cmdlet to enable the automatic refreshing of the access token.
• OAuthClientId (custom applications only): The client Id assigned when you registered your custom OAuth application.
• OAuthClientSecret (custom applications only): The client secret assigned when you registered your custom OAuth application.

Option 2: Transfer OAuth Settings

Prior to connecting on a headless machine, you must install and create a connection with the driver on a device that supports an internet browser. Set the connection properties as described above in "Desktop Applications".

After completing the instructions in "Desktop Applications", the resulting authentication values are encrypted and written to the location specified by OAuthSettingsLocation. The default filename is OAuthSettings.txt.

Test the connection to generate the OAuth settings file, then copy the OAuth settings file to your headless machine.

On the headless machine, set these properties:

• InitiateOAuth: REFRESH.
• OAuthSettingsLocation: The location of the OAuth settings file you copied from the machine with the browser. Make sure this location gives read and write permissions to the cmdlet to enable the automatic refreshing of the access token.
• OAuthClientId (custom applications only): The client Id assigned when you registered your custom OAuth application.
• OAuthClientSecret (custom applications only): The client secret assigned when you registered your custom OAuth application.

Private App Token

To connect using a Hubspot Private App Token, set the AuthScheme property to PrivateAppToken and OAuthAccessToken to the value of your application's access token.

To generate a HubSpot Private App Token:

1. In your HubSpot account, click the settings icon in the main navigation bar.
2. In the left sidebar menu, navigate to Integrations > Private Apps.
3. Click Create private app.
4. On the Basic Info tab, configure the details of your application (name, logo, and description).
5. On the Scopes tab, select Read or Write for each scope you want your private application to be able to access. This determines the data the driver has access to retrieve. Refer to the OAuthRequiredScopes and OAuthOptionalScopes properties for recommended scopes to select.
6. After you are done configuring your application, click create app in the top right.
7. Review the information about your application's access token, click Continue creating, and then click Show token.

You can now set the retrieved token in the OAuthAccessToken property. (OAuthAccessToken is used for Private App Access Tokens and OAuth Access Tokens.)

Retrieving Data

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

$results = Select-HubSpot -Connection $conn -Table "Contacts" -Columns @("City, Country") -Where "VID='123456789'"

The Invoke-HubSpot 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-HubSpot -Connection $conn -Table Contacts -Where "VID = '123456789'" | Select -Property * -ExcludeProperty Connection,Table,Columns | Export-Csv -Path c:\myContactsData.csv -NoTypeInformation

You will notice that we piped the results from Select-HubSpot 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-HubSpot
PS C:\> $row = Select-HubSpot -Connection $conn -Table "Contacts" -Columns (City, Country) -Where "VID = '123456789'" | select -first 1
PS C:\> $row | ConvertTo-Json
{
  "Connection":  {

  },
  "Table":  "Contacts",
  "Columns":  [

  ],
  "City":  "MyCity",
  "Country":  "MyCountry"
} 

Deleting Data

The following line deletes any records that match the criteria:

Select-HubSpot -Connection $conn -Table Contacts -Where "VID = '123456789'" | Remove-HubSpot

Modifying Data

The cmdlets make data transformation easy as well as data cleansing. The following example loads data from a CSV file into HubSpot, checking first whether a record already exists and needs to be updated instead of inserted.

Import-Csv -Path C:\MyContactsUpdates.csv | %{
  $record = Select-HubSpot -Connection $conn -Table Contacts -Where ("Id = `'"+$_.Id+"`'")
  if($record){
    Update-HubSpot -Connection $conn -Table Contacts -Columns @("City","Country") -Values @($_.City, $_.Country) -Where "Id  = `'$_.Id`'"
  }else{
    Add-HubSpot -Connection $conn -Table Contacts -Columns @("City","Country") -Values @($_.City, $_.Country)
  }
}