Connect-ERP

Allows to connect to powerGateServer services or directly to the OData endpoints of ERP systems.

These can be either the services configured in the Vault within the ERP Integration Settings dialog, or alternatively all the necessary connection details can be provided via parameters.

Syntax

Configuration from Vault:

Connect-ERP -UseSettingsFromVault [-OnConnect <Scriptblock | String>] [<CommonParameters>]
<#
PARAMETER
    -UseSettingsFromVault
        Required                true

    -OnConnect
        Required                false

    <CommonParameters>
        This cmdlet supports the common parameters: ErrorAction, ErrorVariable
#>

Providing connection details directly:

Connect-ERP [[-Service] <Uri>] [[-User] <String>] [[-Password] <String>] [-IgnoreCertificates] [-OnConnect <Scriptblock | String>] [<CommonParameters>]
<#
PARAMETER
    -Service
        Required                false

    -User
        Required                false

    -Password
        Required                false

    -IgnoreCertificates
        Required                false

    -OnConnect
        Required                false

    <CommonParameters>
        This cmdlet supports the common parameters: ErrorAction, ErrorVariable
#>

Parameters

Type	Name	Description	Default value
SwitchParameter	UseSettingsFromVault	Connect to services configured in ERP Integration Settings dialog for the currently connected Vault	False
Scriptblock / String	OnConnect	This script block or function will be executed before connecting to the service. More details below
Url	Service	Url to a specific OData service	http://localhost:8080/PGS/CatalogService
String	User	Username which should have permission to read the Service
String	Password	Password which matches with username
SwitchParameter	IgnoreCertificates	If Flag is set the connection is set up in order to trust all certificates	False

Return type

Bool:
$true ← on success.
$false ← on failure. Exception/ErrorMessage can be accessed using $Error.
If the cmdlet fails due to error responses returned by the ERP system, the $Error variable provides a WebRequestException .

Remarks

If the service to be connected is a CatalogService (available with powerGateServer or SAP), then all its known services are automatically connected too.
Thereby the same connection details are used as for the CatalogService itself, e.g. the same authentication.

OnConnect

The script block or the function name that is passed to the -OnConnect parameter enables connections to services that have very specific requirements.
The $settings parameter (see connection settings) allows to manipulate certain settings or even attaching to the BeforeRequest/AfterResponse handler.
Please note that when connecting to a CatalogService, the specified script block or function is also invoked for all contained services that will be connected automatically.
When an exception is thrown no connection to the services is established.

Configuration from Vault

When using the -UseSettingsFromVault switch, the cmdlet connects to all services that are configured for the currently connected Vault via the $ERPSettings variable.
The connection settings can be changed for each Vault individually using the ERP Integration Settings dialog.

The cmdlet fails when the connected Vault is not properly configured:
For instance, in production Vaults, it’s essential to manually setup the connection to the correct ERP system.
When working with test-Vaults, administrators often overlook to add the necessary configurations to their productive Vaults, which leads to ERP integration issues after go-live.
However, problems can also arise from sudden changes to the ERP-endpoint itself.

During the trial period or evaluation phase - when no specific configuration has been made - the default settings for a connection to a public Demo ERP system are used.
This allows all the delivered ERP integration samples to be used out of the box.

Settings File

The cmdlet relies on a hidden Vault file ‘$/powerGate.settings’ which stores all settings of the ERP integration.
A Vault administrator can set the file permissions so that only selected users can check-in changes.
Read and download permissions are required by all Vault users working with the ERP integration in Vault Client, Inventor or the Job Server.

The the cmdlet downloads the current settings to C:\ProgramData\coolOrange\powerGate.settings.

Providing connection details directly:

The cmdlet can connect directly to a specified -Service URL.
Basic Authentication is used for the connection when passing -User and -Password credentials.

The cmdlet can also be called again for an individual service using different authentication details, e.g. if this service requires different authentication than the CatalogService.

Examples

In the following examples we are using public OData Services (http://services.odata.org) for demonstration purposes:

Connect to the Northwind Service

Connect-ERP -Service "http://services.odata.org/V4/Northwind/Northwind.svc"

Connect to a SAP service that requires authentication

Connect-ERP -Service "http://sap.coolorange.com" -User "EX_DEMO" -Password "secret" -OnConnect $global:sapConnect

Connect to all services which are configured for the connected Vault

Import-Module powerVault
Open-VaultConnection

Connect-ERP -UseSettingsFromVault

Note: When using the cmdlet in applications that may connect to different Vaults, ensure only ERP connections configured for the current Vault are utilized, such as in the following powerJobs Processor script:

Import-Module powerGate
Disconnect-ERP
Connect-ERP -UseSettingsFromVault -ErrorAction Stop

Connect to a service via secured SSL connection and trust all certificates

Connect-ERP -Service "https://services.odata.org/V4/Northwind/Northwind.svc" -IgnoreCertificates

Using the -OnConnect parameter to add a header to each request

Connect-ERP -Service "http://services.odata.org/V4/Northwind/Northwind.svc" -OnConnect {
param($settings)
$settings.BeforeRequest = [Action[System.Net.Http.HttpRequestMessage]] {
        param($request)
        $request.Headers.Add("Accept","application/json")
}
}

Using multiple script blocks in -OnConnect parameter

$outputService = {
        param($settings)
        Write-host "Connecting to the Service $($settings.BaseUri)"
}

$outputPreferredUpdateMethod = {
        param($settings)
        Write-host "Current PreferredUpdateMethod is $($settings.PreferredUpdateMethod)"
}

Connect-ERP -Service "http://services.odata.org/V4/Northwind/Northwind.svc" -OnConnect {
        param($settings)
        $outputService.Invoke($settings)
        $outputPreferredUpdateMethod.Invoke($settings)
        $sapConnect.Invoke($settings)
}

Error handling, analyze the WebRequestException why the connection to server could not be established, using $Error:

$result = Connect-ERP "https://services.odata.org/NotExisting.svsc"

if(-not $result){
        $Error[0].Exception.StatusCode #404
        $Error[0].Exception.Source #Local computer
        $Error[0].Exception.Message #"The service is not available or could not be found on the server."
        $Error[0].Exception.RawResponse #"The resource you are looking for has been removed, had its name changed, or is temporarily unavailable."
}