# Connecting Autodesk & ERP

```{toctree}
:hidden:
:glob:

erp_integrations/demo_erp_system
erp_integrations/*
```

ERP systems that provide an [OData](<https://www.odata.org/>) interface can be directly connected to applications such as Vault Client, Inventor or AutoCAD.\
But also ERP systems which doesn’t expose a web API can be connected using [powerGateServer](<powergateserver:index>), who then acts as a middleman and translator.

```{image} /img/powergate_workflow.png
:width: 600px
```

## ERP integrations

Vault Clients and CAD applications can be easily connected to ERP systems using the powerGate [Cmdlets](</getting_started/using_the_powergate.cmdlets/>) or the [.NET library](</getting_started/using_the_powergate.sdk/>).\
Depending on whether data synchronizations must be fully automated, partially automated or performed manually, an ERP integration can be realized using [powerJobs Processor](<powerjobs_processor:index>), [powerEvents](<powerevents:index>) and [Autodesk Vault Data Standard](<https://knowledge.autodesk.com/support/vault-products/learn-explore/caas/CloudHelp/cloudhelp/2022/ENU/Vault-Admin/files/GUID-D7A81AE0-7CB0-4428-961C-A5E0F8B791D8-htm.html>).

### Scripts

Some PowerShell scripts are delivered with the product, all starting with the name *'Sample.'*.\
Their purpose is mainly to help getting started with implementing an ERP integration based on [powerEvents](<powerevents:index>).

The following sample scripts are installed to *%ProgramData%\coolOrange\powerEvents\Events*:
* [Sample.ConnectToPowerGateServer.ps1](</erp_integrations/Sample.ConnectToPowerGateServer>) (disabled per default and therefore installed in the *.\Disabled* subdirectory)
* [Sample.SyncERPTabConfiguration.ps1](</erp_integrations/Sample.SyncERPTabConfiguration>) & *Sample.DefaultERPTabConfiguration.xml*
* [Sample.TransferERPItemViaFileTab.ps1](</erp_integrations/Sample.TransferERPItemViaFileTab>) & [Sample.TransferERPItemViaItemTab.ps1](</erp_integrations/Sample.TransferERPItemViaItemTab>)
* [Sample.TransferERPBOMViaFileTab.ps1](</erp_integrations/Sample.TransferERPBOMViaFileTab>) & [Sample.TransferERPBOMViaItemTab.ps1](</erp_integrations/Sample.TransferERPBOMViaItemTab>)

These samples cover the most common scenarios for connecting and exchanging data between Vault and an ERP system.

When starting Vault applications and logging into Vault, the [](</erp_integrations/Sample.ConnectToPowerGateServer>) script automatically connects to the correct [powerGateServer](<powergateserver:index>) (test or productive system). For this the script must first be [enabled](<erp_integrations/Sample.ConnectToPowerGateServer:Enabling the script>).\
The [](</erp_integrations/Sample.SyncERPTabConfiguration>) provides Tools Menu items for downloading and uploading a configuration for ERP Tabs. When no configuration was previosuly uploaded, a default configuration is uploaded on the first log into Vault.

Afterwards, an "ERP Item" tab and an "ERP BOM" tab are displayed in the Vault Client for selected files and items.
- For files, the [](</erp_integrations/Sample.TransferERPItemViaFileTab>) script displays the information of the corresponding ERP Item and
the [](</erp_integrations/Sample.TransferERPBOMViaFileTab>) script displays the current bill of materials from the ERP. Both tabs also allow data to be created or changed live in the ERP system.
- For items, the [](</erp_integrations/Sample.TransferERPItemViaItemTab>) and [](</erp_integrations/Sample.TransferERPBOMViaItemTab>) scripts display the corresponding information from the ERP system and both also allow creating or changing such data.

For evaluation purposes, the mentioned tabs automatically connect to a [](</erp_integrations/demo_erp_system>), which means that only demo data is displayed and can be modified.\
Therefore, lines such as the following must not be used when implementing ERP integrations and should simply be removed:
```{code-block} powershell

Connect-ERP -Service 'http://demo.powergate.online/PGS/ERP/MaterialService' -OnConnect $global:demoERPconnect -ErrorAction Stop
```

The Tabs are delivered with corresponding .xaml files (Extensible Application Markup Language) which describe their layout, including the controls used (label, text field, combo box, etc.).

:::{admonition} Customizations

For all sample scripts and the according xaml files it is recommended to create a **copy** when they need to be **customized**.\
[Disable](<powerevents:getting_started:activating a sample script>) the used sample script by simply moving it to the *%PROGRAMDATA%\coolOrange\powerEvents\Events\Disabled* directory.
:::

### Modules

The *powerGate_Connections.psm1* module is delivered in the Cmdlets installation directory *%ProgramFiles%\coolOrange\Modules\powerGate*.\
It gets automatically imported with the *powerGate module* and provides global variables and extensions:
 - The **$sapConnect** variable for [connecting to SAP systems](</code_reference/commandlets/objects/sapconnect>).
 - The **$demoErpConnect** variable for [connecting to the Demo ERP system](</erp_integrations/demo_erp_system>).
 - The **$global:Host.PrivateData.OnNonTerminatingError** extension ensures that Vault users are notified about [connection problems](<#errors>) and can better understand whether the problem is caused by their client-machine, by powerGateServer or directly triggered by the ERP system.

 :::{admonition} Import powerGate module
:class: note

Before the global variables can be used in [-OnConnect](<code_reference/commandlets/connect-erp:remarks>) of the *Connect-ERP*, they must be imported using `Import-Module powerGate`.\
Otherwise it may happen that no successful connection to the ERP system can be established.

:::

 ## Errors

Powershell hosting applications inform scripting guys and Vault users in different ways about [Terminating Errors](<https://docs.microsoft.com/en-us/powershell/scripting/developer/cmdlet/terminating-errors>) that arise during script or module executions :

* [powerEvents](<powerevents:event_scripts:errors>) displays Error Message Boxes
* [BOM Window](<bom_window:errors>) displays Error Dialogs during Check- and Transfer operations or failure Icons while loading the BOM tree
* [powerJobs Processor](<powerjobs_processor:jobprocessor/jobs:errors>) jobs fail
* [Autodesk Vault Data Standard](<https://knowledge.autodesk.com/support/vault-products/learn-explore/caas/CloudHelp/cloudhelp/2022/ENU/Vault-Admin/files/GUID-F0F7A520-5765-4FA5-A533-FEDB456B90F8-htm.html>) writes to the Log File and shows Message Boxes in several customization areas
* PowerShell IDE's display the error message and its stack trace with red text in the terminal when the script execution stops

Instead, when [Non-Terminating Errors](<https://docs.microsoft.com/en-us/powershell/scripting/developer/cmdlet/non-terminating-errors>) occur within [](</code_reference/commandlets/>), the script execution is not stopped by default (see `-ErrorAction:Continue` parameter) and further information is available in the global `$Error` variable.\
For **connection problems**, these would be the [WebRequestException](</code_reference/net_library/webrequestexception>) details provided by [ERP cmdlets](</code_reference/commandlets/>).\
By default, Vault users are informed about connection troubles in all types of ERP integrations using the *powerGate_Connections.psm1* module.\
In applications such as the Vault Client, Inventor or AutoCAD a Connection Error Dialog will be displayed, which helps to understand whether the connection problem was caused by the client-machine (no request was send), the powerGateServer or directly by the ERP system (error response):

```{image} /img/connection_errordialog.png
  :width: 300px
```

All **other types** of [Non-Terminating Errors](<https://docs.microsoft.com/en-us/powershell/scripting/developer/cmdlet/non-terminating-errors>) are displayed using an [Error Message Box](<powerevents:event_scripts:errors>) which helps to identify incorrectly used [ERP cmdlets](</code_reference/commandlets/>) or problematic parameters:

```{image} /img/pe_errormessagebox_exception.png
  :width: 500px
```

:::{admonition}  BOM Window - Non-Terminating Errors

Such modal error dialogs are not displayed during the BOM Window [Check- and Transfer functions](</code_reference/commandlets/show-bomwindow/required-functions/>) where problems with ERP cmdlets occur.\
Instead, the current processed [$bom](</code_reference/commandlets/show-bomwindow/objects/bom/>), [$bomRow](</code_reference/commandlets/show-bomwindow/objects/bomrow/>) and [$item](</code_reference/commandlets/show-bomwindow/objects/item/>) objects are automatically assigned with an [Error Status](</bom_window/status/>):

```{image} /img/bomwindow_connections_errors.png
  :width: 410px
```

\
The automatically set `_StatusDetails` help the Vault user to localize the cause of connection problems more precisely.\
Unfortunately the operations are not automatically [terminated](<bom_window:errors>) after problematic ERP cmdlet usages or incorrect parameter values, but also in this case additional stack trace information allows the scripting guy to find the problematic line faster.
:::

:::{admonition}  Vault Restriction events - Non-Terminating Errors
All [Vault Restriction events](<powerevents:code_reference/objects/event_mappings>) that encounter ERP cmdlet errors are automatically [restricted](<powerevents:code_reference/commandlets/register-vaultevent>) to prevent the configured process from passing successfully even though connection or cmdlet problems have occurred:

```{image} /img/pe_restriction_dialog_pgs_license_expired.png
  :width: 400px
```

\
Unfortunately, the executed *Restrictions event* actions are not automatically [aborted](<powerevents:event_scripts:errors>) directly after problematic ERP cmdlet usages or incorrect parameter values.\
Still, additional stack trace information helps the script guy to quickly find and correct the affected ERP cmdlet line.
:::

In any case, all error details are logged and can be found in the [logfile](<logging:logfile>).