Connecting Autodesk & ERP

../_images/powergate_workflow.png

ERP integrations

Vault Clients, Inventor and AutoCAD applications can be easily connected to ERP systems using the powerGate Cmdlets or the .NET library.
Depending on whether data synchronizations must be fully automated, partially automated or performed manually, an ERP integration can be realized using powerEvents, Autodesk Vault Data Standard and additionally with powerJobs Processor.

Configuration

Vault administrators can configure settings for their entire ERP integration, and these settings are specific to each Vault.

To do this, start the Vault Client and login to the respective Vault.
Afterwards, the “ERP Integration Settings” dialog can be opened in the Tools → powerGate Settings… menu (see Sample.ConnectToERP).

../_images/settings_dialog_tools_menu.png

Within the dialog it is possible to configure the necessary Services required for connecting to the ERP system.

../_images/settings_dialog_adding_removing_pgs_connections.png

For some ERP systems, a single service can be configured that provides all the necessary functionalities for the transfer of Items and BOMs.
Other ERP systems, such as SAP Gateway, however requires multiple URL endpoints for this purpose.

Connection Types:

  • Direct connection to an OData-capable ERP:
    ERP systems that provide an OData interface can be directly connected from Vault applications.

  • Connection to any ERP via powerGateServer:
    Also ERP systems which doesn’t expose a web API can be connected using powerGateServer, who then acts as a middleman and translator.
    New Services can be configured quickly because Host Name, Port and Service paths are proposed based on the following recommendations.

    💡 Recommendations:
    If you are using a test-Vault, then the services from local ERP plugins should be configured (they may still be under development). Please ensure they actually connect to the test-ERP system!
    For production Vaults, on the other hand, the powerGateServer should be installed directly on the Vault Server machine.

    Note that powerGateServer installations include an ERP Plugin by default, but it’s not needed for real ERP integrations; thus, install the powerGateServer without ‘ERP Plugin’ on test and productive environments!
    Then, a single CatalogService connection can be configured, allowing workstations to automatically connect to all installed services, regardless of their names.

    Otherwise, please configure the individual services separately to avoid name-conflicts with the services of the ERP Plugin.

Additionally, the dialog provides the option to configure mappings between Vault and ERP entity types.
Each mapping allows you to specify, for each ERP field, whether data from Vault properties or fixed-values should to be transferred.

../_images/settings_dialog_entity_type_and_field_mappings.png

Once settings are changed, the changes can be saved across the entire Vault by clicking the Save button.

Requirements

In order to change settings, the logged-in Vault user must have the respective permissions to edit the $/powerGate.settings file.
Otherwise, the Save button is disabled and the status bar of the dialog provides according information.

When applying the same configuration to other Vaults, be sure to check all settings (e.g. Service URLs) for correctness.
Potential errors must then be resolved, especially if a Vault Property or an ERP Field is missing (perhaps it has been renamed), or when mapped value types suddenly no longer match.

Scripts

Several PowerShell scripts are delivered with the product, all starting with the name ‘Sample.’.
Their purpose is mainly to help getting started with implementing a new ERP integration for the Vault Client and Inventor.

For this purpose, powerEvents is used on the workstations to execute the individual Client Customizations in %ProgramData%\coolOrange\Client Customizations:

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

When starting Vault applications and logging into Vault, the Sample.ConnectToERP script automatically connects to the configured services of the ERP system.
To be able to evaluate the individual functions of our sample ERP integration, our public Demo ERP system is used.

../_images/settings_dialog_demo_erp_connections.png

In the Vault Client, additional “ERP Item” and “ERP BOM” tabs are displayed for selected files and items.
For files, the Sample.Tab-File-ErpItem script displays the information of the corresponding ERP Item and the Sample.Tab-Item-ErpItem script displays the current bill of materials from the ERP.
For items, the Sample.Tab-File-ErpBom and Sample.Tab-Item-ErpBom scripts display the corresponding information from the ERP system.
In addition, data can also be created or changed live in the ERP system, considering all configurations made.

Since normally either Vault Items or Vault Files are used, the PowerShell scripts that are not needed should be disabled.

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.).

Note

For all sample scripts and the according xaml files it is recommended to create a copy when they need to be modified.
Then disable the particular sample script by simply moving it to the %PROGRAMDATA%\coolOrange\Client Customizations\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.

  • The $demoErpConnect variable for connecting to the Demo ERP system.

  • The $global:Host.PrivateData.OnNonTerminatingError extension ensures that Vault users are notified about connection problems and can better understand whether the problem is caused by their client-machine, by powerGateServer or directly triggered by the ERP system.

In addition, the powerGate_Configuration.psm1 module provides an $ERPSettings variable and ERP Cmdlet extensions, necessary for working with configurations made for the ERP integration in the current Vault.

Import powerGate module

Before the global variables can be used in -OnConnect 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 developers and Vault users in different ways about Terminating Errors that arise during script or module executions :

  • powerEvents displays Error Message Boxes

  • BOM Window displays Error Dialogs during Check- and Transfer operations or failure Icons while loading the BOM tree

  • powerJobs Processor jobs fail

  • Autodesk Vault Data Standard 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 occur within Cmdlets, the script execution is not stopped by default (see -ErrorAction:Continue parameter) and further information is available in the global $Error variable.
Only with ERP integrations, which are loaded as powerEvents Client Customizations, many errors are also managed automatically and no additional error handling needs to be implemented:

  • In applications such as Vault Client, Inventor or AutoCAD, dialogs are displayed that provide information about the nature of the problem.

    For connection problems, these would be WebRequestExceptions occurring in ERP cmdlets, a Connection Error Dialog is displayed to the Vault user.
    This helps to understand whether the problem was caused by the client-machine (no request was send), the powerGateServer or directly by the ERP system (error response):

    ../_images/connection_errordialog.png

    Other types of Non-Terminating Errors are incorrectly used ERP cmdlets or problematic parameters where no web requests are sent at all.
    In this case, the developer can see all the details of the exception in an Error Message Box, which helps him to quickly identify the erroneous line:

    ../_images/pe_errormessagebox_exception.png

  • Such modal error dialogs are not displayed in the BOM Window when problems with ERP cmdlets occur during Check- or Transfer functions.
    Instead, the current processed $bom, $bomRow and $item objects are automatically assigned with an Error Status:

    ../_images/bomwindow_connections_errors.png

    The automatically set _StatusDetails help the Vault user to localize the cause of connection problems more precisely.
    Unfortunately the operations are not automatically terminated 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.

  • All Vault Restriction events that encounter ERP cmdlet errors are automatically restricted to prevent the configured process from passing successfully, after connection or cmdlet problems have occurred:

    ../_images/pe_restriction_dialog_pgs_license_expired.png

    Unfortunately, the executed Restrictions event actions are not automatically aborted 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.

Autodesk Vault Data Standard - Non-Terminating Errors

For ERP integrations implemented via Vault Data Standard, non-terminating errors in ERP cmdlets are only logged in the Log Window.
To prevent connection or cmdlet issues beeing swallowed, the customization should therefore check for non-terminating errors after ERP cmdlet invocations and handle them if necessary. See the “Error handling” examples of the individual cmdlets for this.

Please note that debugging such customizations within PowerShell IDE’s may also be affected, as the observed error behavior may differ from that in the Vault Client or Inventor.
Just execute the following line in the debugging session to ensure that no modal dialogs etc. are displayed in the PowerShell IDE either:

$global:Host.PrivateData.OnNonTerminatingError = [Action[System.Management.Automation.RuntimeException]] { }

However, the automatic handling of errors can also be suppressed for individual ERP cmdlet invocations by passing the -ErrorAction SilentlyContinue parameter.
This allows the script execution to continue so that special error handling can be implemented. For example, personalized messages can be displayed to the Vault user or specific 4xx responses can be intercepted (see example “Check SAP Material does not exist or other 400 response occurred”).
Error responses can then be handled as desired using the information provided by the WebRequestException, which is stored in the global $Error variable.

In any case, all error details are logged and can be found in the logfile.