COOLORANGE powerGate is a software solution that connects the Autodesk PDM systems Vault Professional or Vault Workgroup to ERP system that expose a web API.
This document describes the minimal required technical specifications to the ERP system, in particular the web API of the ERP system. This information can be used by ERP vendors or service contractors to provide and/or create a web service which is needed to consume ERP data in an integration project.
Integration projects are typically created individually for customers to suite the customer’s needs and to adopt with the different ERP systems workflows and APIs.
Web API technologies
The web API can be exposed as one of the following web service technologies:
- SOAP
- REST
- OData (Open Data Protocol)
Security and authentication
Restrict communication
The recommended way to secure SOAP and REST web services is to restrict the web service API of the ERP system to only accept calls from the machine where the middleware is running. This way complicated authentication can be avoided which improves performance and lowers complexity.
Authentication
If restricting the communication is not possible, a simple authentication is needed to authenticate with the ERP system. Preferably basic authentication with username and password or any other persistent information used to authenticate. This information must be passed to the web API in every single call (For example inside the HTML header).
For OData basic authentication is recommended, not only because of the reasons mentioned above, but also because the clients will consume the web service directly without the need to let the middleware translate the requests. SAP Gateway or Microsoft Dynamics 365 and many other ERP systems are exposing REST with OData web services.
REST APIs sometimes use OAuth 2.0 with a three-legged authentication flow. This is not supported by powerGate Server because it runs as a service without the possibility for users to confirm an authentication attempt. Two-legged OAuth at the other hand is supported.
In any case a detailed description and an example is needed how to establish a connection to the ERP system’s web service.
Users
System ERP user
For SOAP and RESTful web services one single user is needed that can be used by the middleware to connect to the ERP system. This user is used to create or update entities and – depending on the ERP system – would also show up on the records as “create user” or “modified user”.
Pass through ERP user
For REST/OData, users can be passed through from the client machine. This can either be a single system ERP user commonly for all clients or a named ERP user, individually for each client.
Authentication Lifespan
Whenever an authentication is used to secure the communication, the web service must accept a username and password in the header for every single call.
Some web services are secured by a token which needs to be generated once by sending username and password to a specific web service endpoint. With this token all further calls are secured. The problem with such tokens is that they have a limited lifespan and expire after a certain time.
Data
Vault Professional or Vault Workgroup is usually connected to ERP systems, to exchange Items, BOMs and Documents between the systems. In some cases, also related information such as look up tables e.g. a list of Projects, Suppliers, Vendors, or active Change Numbers must be gathered from the ERP system and shown in Vault to enrich the Vault data before it gets transferred to the ERP system.
Actions
The following table lists all entities, and the typical actions need for an integration project:
| Create | Read | Search | Update | Delete | Binary Upload | |
| Item | x | x | x | x | ||
| BOM Header | x | x | x | |||
| BOM Row | x | x | x | x | ||
| Document | x | x | x | x | ||
| Lookup | x | |||||
| Tables |
The combination of entities and actions as listed above need to be supported by the ERP system’s web service! In addition, a documentation as well as samples for every single action is needed!
If any of the actions listed in the table above does not work without additional information (e.g., an item can only be updated if a valid Change Number is passed along with the item) this needs to be documented and an addition web service is needed to get all the necessary data
Entities
The entities and all the actions described above must be exposed by the ERP system’s web service.
Items
-
Read one ERP item
- Query multiple ERP items with search criteria (e.g., “equals” or “contains”)
- Create a new ERP item
- Optional: Generating a new number based on an ERP numbering scheme
- Update an existing ERP item
Items must be created immediately in the ERP system and must return the item number when they are created in case the ERP system is the leading system for item numbers. Otherwise, it is not possible to create a link in Vault to the matching ERP item!
Bill of Materials (BOMs)
- Read one ERP BOM header including ERP BOM rows
- Only the first level of the BOM rows must be considered
- Create a new ERP BOM header including ERP BOM rows
- The header and all rows (children) must be created with a single call
- Only the first level of the BOM rows must be considered
- Update an existing ERP BOM header
- Add one ERP BOM row to an existing ERP BOM header
- Update one ERP BOM row of an existing ERP BOM header
- Delete one ERP BOM row from an existing ERP BOM header
Documents / Binaries
- Read the metadata of an ERP document
- Create the metadata of an ERP document
- Update the metadata of an ERP document
- Upload the binaries of an ERP document
- Update (re-upload) the binaries of an ERP document
Lookup tables
Look up tables are optional! If the data doesn’t change it can be hardcoded on the client side instead
- Read lookup tables such as active Change Orders, Unit of Measures, Vendors, Suppliers, or the like
Samples and testing
Tools
Postman
For all actions on the various ERP entities mentioned above, samples must be available - preferably as Postman collection. https://www.getpostman.com/collection
Besides REST, Postman can also be used to execute SOAP calls. The following link explains what needs to be done to do so:
https://blogs.sap.com/2021/08/04/calling-a-soap-api-using-postman/
SoapUI
In case of SOAP, also SoapUI can be used to demonstrate how the ERP system’s web service API must be used. https://www.soapui.org/downloads/soapui.html
All samples must contain a working authentication including username and password or similar login information if applicable
Project initialization
Acceptance Tests
All samples are used prior to an implementation project to verify the web services. If any action fails, the Vault-ERP connection project cannot begin.
Performance tests
In addition to the functional test, performance tests are executed to make sure the user experience is good. Typically, the benchmarks are:
- Items are created and updated in less than 0.5 seconds
- BOMs with 50 rows are created in less than 5 seconds
- BOM rows are added, deleted, or updated in less than 0.5 seconds
Test environment
For the acceptance tests to be executed, a test environment must be present and accessible. The test system (sandbox) must have the same version and the same configuration as the production system and would ideally mirror the data of production ERP system.