The PowerShell module for the Public API enables developers and administrators to use the PowerShell scripting environment to manage data and execute actions on the interworks.cloud Platform. The module is built on the interworks.cloud Platform .NET SDK for the Public API.

Installation

This section explains how to download and install the PowerShell module for the Public API on your environment.

Prerequisites

The following software is necessary for the installation and use of the PowerShell module for the Public API on your environment:

Install PowerShell 7

• Windows
• Linux
• MacOS

You can verify the PowerShell version by executing the command:

$psversiontable

Install ASP.NET Core Runtime 6.0
Select the installer for your operating system from https://dotnet.microsoft.com/en-us/download/dotnet/6.0

Generate interworks.cloud API Credentials
The following information is necessary to authenticate the PowerShell module for the Public API

• BSS Portal Url <baseUrl>
• OAuth 2.0 Key
  • Client Key <clientKey>
  • Client Secret
• Application User
  • Username <username>
  • Password

More details on how to generate the information above are available on the Authorization_Authentication page.

Valid License

In the Preview edition of PowerShell Module for Public API there is no licensing restriction. This edition provides a limited set of Cmdlets that can be used for evaluation purposes.

A valid license for PowerShell Module will be required in later releases for unrestricted use and the full functionality with regards to the interworks.cloud Platform API.

Installing on Windows

Download the latest stable version of the PowerShell module here.

To install the PowerShell module on your environment, you may select either of the following options:

Automatic Module Detection

If you want PowerShell to automatically detect the module, place the files inside one of the available PowerShell module directories that are currently in your PowerShell PSModulePath environment variable. You can access that list by executing this command:

$env:PSModulePath

Go to one of the directories returned by the PSModulePath environment variable and unzip the files there.

To check that the module is detected, run the following command:

Get-Module -List -Name iwcp.Platform.API.SDK.PowerShell

Finally, import the module using the following command:

Import-Module iwcp.Platform.API.SDK.PowerShell

Use a Custom Directory

If you want to import the module from a custom directory, use the Import-Module cmdlet, providing the full path to the module’s files.

Import-Module <Full-Path-To-iwcp.Platform.API.SDK.PowerShell>

Getting Started

This section provides fundamental information on how to use the PowerShell module, such as configuring credentials, getting help for a specific cmdlet or discovering available cmdlets.

Configuring Credentials

The module provides two commands to manage the credentials configuration required to make API calls. Their usage is described below.

Set-IwcProfile

Creates a configuration file to use for making the API calls.

Create in current directory

Execute the cmdlet:

Set-IwcProfile -Name <filename> -Username <username> -ClientKey <clientKey> -BaseURL <baseURL>

After the execution, you will be prompted to provide the Password and the Client Secret. This will create the configuration file in your current working directory.

Create in specified directory

Optionally specify a path to create the configuration file there instead.

Execute the cmdlet:

Set-IwcProfile -Name <filename> -Path <path> -Username <username> -ClientKey <clientKey> -BaseURL <baseURL>

After the execution, you will be prompted to provide the Password and the Client Secret. This will create the configuration file in the specified path.

About the Password & ClientSecret

The Password and ClientSecret values are entered manually and not passed as parameters because this allows interworks.cloud to handle them as secure strings, and they are not stored in your command history or visible in your terminal as plaintext values. Your input is encrypted using the Data Protection API (DPAPI) before it is written to the configuration file.

Configuration file format

The configuration JSON file has the following structure:

{
  "Version": "3",
  "Username": "powershelluser",
  "Password": "01000000d08c9ddf0115d1118c7a00c04fc297eb010000003402a46901bd4e4e9ca81561a794e8b70000000002000000000003660000c000000010000000bdc2e652ba31f7460fc613cb1a330fee0000000004800000a000000010000000a290163cbdb438cf1ffb2ebdd60b605d180000008c919e7dd29c8c988b9cefa7acb44f256b151d5d584bc190140000004110ff516ee115ea054140e355ab852d1b8f06ba",
  "ClientKey": "c85f6f7c-1b27-4140-bb83-bebd573a10e5",
  "ClientSecret": "01000000d08c9ddf0115d1118c7a00c04fc297eb010000003402a46901bd4e4e9ca81561a794e8b70000000002000000000003660000c000000010000000873a10e7c14f8ecc75b72b245650aed10000000004800000a0000000100000000fb3f2b191d2cba114f3bc832d147ae860000000a8dd90812ca729fdb529a67140cedb4c6d9ea416eda42f0ecb7c15d96429e14796b8f31be802735a7189cfe4605eea8d42c2deed227f02411aa1a3bc0a3c4b3e1aa271ad6d1f5e7c8b422cdfdd38941e0600fc7f517d9451b3ba4cdf4e7d7b2914000000cd59a76490e1123decd555e5bbfbfa2706f321f5",
  "BaseURL": "https://bss.interworks.cloud"
}

Use-IwcProfile

Specifies a configuration file to use for making API calls.

Use file in current directory

Execute the cmdlet:

Use-IwcProfile -Name <filename>

This will look for and return the file with the specified filename in your current directory as the configuration for the session.

Use file in specified directory

Execute the cmdlet:

Use-IwcProfile -Name <filename> -Path <path>

This will look for and return the file with the given filename in the provided path as the configuration for the session.

Cmdlet Discovery

To find all cmdlets that are supported by your currently installed version of the PowerShell module, you can use the Get-IwcCommand cmdlet after importing the module:

Get-IwcCommand

This will return all available cmdlet names and descriptions, sorted and separated by noun.
An example output of this cmdlet follows:

Name                     Description
----                     -----------
Get-IwcAccount           Retrieves all accounts.
Get-IwcAccountById       Retrieves a single account that corresponds to an account ID.
Get-IwcCommand           Returns all available commands with their descriptions.
Get-IwcToolDocumentation This cmdlet generates an HTML documentation file of all cmdlets of the iwcp.Platform.API.SDK.…
Get-IwcVersion           Retrieves the module's version.
New-IwcAccount           Creates an account and returns the account ID.
Set-IwcProfile           Creates a configuration file to use for making the API calls.
Use-IwcProfile           Specifies a configuration file to use for making the API calls.

Getting Help

The PowerShell module supports PowerShell Help System. The Get-Help cmdlet displays information about the cmdlets provided.

Basic Cmdlet Help

Specify the Cmdlet-Name to receive information about:

Get-Help <Cmdlet-Name>

This returns the following information about the cmdlet:

• Name
• Synopsis
• Syntax
• Description
• Related Links
• Remarks

Detailed Cmdlet Help

Specify the Cmdlet-Name to receive information about:

Get-Help <Cmdlet-Name> -Detailed

This returns the following information about the cmdlet:

• Name
• Synopsis
• Syntax
• Description
• Parameters
• Remarks

Full Cmdlet Help

Specify the Cmdlet-Name to receive information about:

Get-Help <Cmdlet-Name> -Full

This returns the following information about the cmdlet:

• Name
• Synopsis
• Syntax
• Description
• Parameters
• Inputs
• Outputs
• Notes
• Examples
• Related Links

Online Cmdlet Help

Specify the Cmdlet-Name to receive information about:

Get-Help <Cmdlet-Name> -Online

This opens any links related to the cmdlet in your default browser.

Specific Parameter Help

Specify the <Cmdlet-Name> and <Parameter-Name> to receive information about:

Get-Help <Cmdlet-Name> -Parameter <Parameter-Name>

This returns information about the specified parameter only.

The -Parameter supports lists as well, so you can provide multiple values in the <Parameter-Name>, separated by a comma to return information about all of them.