powergate:code_reference:commandlets:connect-erp

Connect-ERP

Allows you to connect either to a CatalogService with all its known services or directly to a single service.

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

Type Name Description Default value Optional
UriServiceUrl to the catalog service or directly to the required servicehttp://localhost:8080/PGS/CatalogServiceyes
StringUserUsername which should have permisson to read the Service yes
StringPasswordPassword which matches with username yes
SwitchParameterIgnoreCertificatesIf Flag is set the connection is set up in order to trust all certificatesFalseyes
Scriptblock / StringOnConnectThis Scriptblock or function will be executed before connecting to the service. More details below yes

Bool:
$true ← on success.
$false ← on failure with an additional property 'Error' containing the Exception/ErrorMessage.

The cmdlet is able to connect to a CatalogService or directly to a Service.
When calling Connect-Erp by passing the url to a CatalogService, the cmdlet automatically connects all the registered services with the same authentication as used for the login to the CatalogService.
In addition, the cmdlet can be recalled for a single service with different authentication if that service is not available by using the authentication of the CatalogService.

When passing Credentials the cmdlet is using Basic Authenticaion to connect to the specified service.

The Scriptblock or the function name that is passed to the -OnConnect parameter will be executed before connecting to the service.

In case of the CatalogService, the specified scriptblock or function will be invoked for each contained service that will be connected automatically.
A parameter $settings containing the connection settings will be passed, which allows to manipulate certain settings or even attaching to the BeforeRequest/AfterResponse handler.

When an exception is thrown within the Scriptblock or function no connection to the services gets established.

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

Connect to the NorthwindService

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 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")
  }
}

Accessing the last server response

Connect-ERP "http://services.odata.org/V3/OData/OData.svc" -OnConnect {
   param($settings)
     $settings.AfterResponse = [System.Delegate]::Combine([Action[System.Net.Http.HttpResponseMessage]] {
      param($response)
          $global:powerGate_lastResponse = New-Object PSObject @{
            'RequestUri'=$response.RequestMessage.RequestUri
            'Code'=[int]$response.StatusCode
            'Status'=$response.StatusCode.ToString()
            'Protocol'= 'HTTP/'+$response.Version
            'Headers'= @{}
            'Body' = $null
          } 
          $response.Headers | foreach { $powerGate_lastResponse.Headers[$_.Key] = $_.Value }
          if($response.Content -ne $null) {
              $body = $response.Content.ReadAsStringAsync().Result
             try {
                $powerGate_lastResponse.Body = $body | ConvertFrom-Json
             } catch {
                $powerGate_lastResponse.Body = [xml]$body
             }
             $response.Content.Headers  | foreach { $powerGate_lastResponse.Headers[$_.Key] = $_.Value }
          }
      }, $settings.AfterResponse)
}

$person = Add-ERPObject -EntitySet Persons -Properties @{ID=-1}
if(-not $person -and $powerGate_lastResponse.Code -eq 403) {
   write-error $powerGate_lastResponse.Body.error.message.'#text'
   #You are connected to a read-only data session. Update operations are not permitted for your session
}

Using multiple scriptblocks 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 why the connection could not be established

$result = Connect-ERP -Service "http://services.odata.org/V4/Northwind/Northwind.svc"
$result #Returns $false
$result.Error #Returns "An error occurred while sending the request."
$result.Error.InnerException #Returns "Unable to connect to the remote server."