# Connect-ERP

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

## Syntax

```{code-block} powershell
:linenos: true

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

## Parameters

| Type                                                                      | Name               | Description                                                                                        | Default value                              | Optional |
|---------------------------------------------------------------------------|--------------------|----------------------------------------------------------------------------------------------------|--------------------------------------------|----------|
| [Url](<https://msdn.microsoft.com/en-us/library/system.uri(v=vs.110).aspx>) | Service            | Url to the catalog service or directly to the required service                                     | [CatalogService](<http://localhost:8080/PGS/CatalogService>) | yes      |
| String                                                                    | User               | Username which should have permisson to read the Service                                           |                                            | yes      |
| String                                                                    | Password           | Password which matches with username                                                               |                                            | yes      |
| SwitchParameter                                                           | IgnoreCertificates | If Flag is set the connection is set up in order to trust all certificates                         | False                                      | yes      |
| Scriptblock / String                                                      | OnConnect          | This Scriptblock or function will be executed before connecting to the service. More details below |                                            | yes      |


## Return type

**Bool**:\
**\$true** ← on success.\
**\$false** ← on failure. Exception/ErrorMessage can be accessed using [\$Error](<https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_automatic_variables?view=powershell-5.1#error>).\
If the cmdlet fails due to error responses returned by the ERP system, the \$Error variable provides a [WebRequestException](</code_reference/net_library/webrequestexception>) .

## Remarks

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.

### OnConnect

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](</code_reference/net_library/erpclientsettings>) 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.

## Examples

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

**Connect to the NorthwindService**

```{code-block} powershell
:linenos: true

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

[Connect to a SAP service](</code_reference/commandlets/objects/sapconnect>) **that requires authentication**

```{code-block} powershell
:linenos: true

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**

```{code-block} powershell
:linenos: true

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

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

```{code-block} powershell
:linenos: true

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 scriptblocks in -OnConnect parameter**

```{code-block} powershell
:linenos: true

$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](</code_reference/net_library/webrequestexception>) **why the connection to server could not be established, using \$Error**:

```{code-block} powershell
:linenos: true

$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."
}
```