Writing the contents of an EDI document to an ERP system
Whilst many organizations are moving towards more modern RESTful APIs that process data in a data format such as JSON/YAML/XML the reality is that many organizations continue to use systems that process documents using EDI.
Sometimes it may even be a prerequisite to doing business with a major supplier or customer that you can demonstrate the capability to communicate electronically with them via EDI.
This demo will show you how to process an EDI document and write its contents to an ERP system.
The demo will demonstrate a use case for processing a purchase order that was created using the Edifact EDI standard, however, it can equally apply to processing other EDI documents that use the X12 standard.
Watch this downloadable demo in action
Line by Line: How this "EDI to ERP" demo works
Upon startup the following services will initialize the database and create the endpoints:
This demo shows how EDI document contents can be integrated with APIs. To eliminate the need of setting up an external API, a premade one has been included in this package. In order for the demo to do this, the premade API will require a database to store the EDI data being consumed in which it will be using the built-in database server in Martini. InitializeDatabase will be executed during the package startup, creating a database connection pool this demo requires.
Due to the nature of the Directory Watcher endpoint requiring a location in your file system to monitor, this service was also added to execute during package startup. This service automatically sets up the installation directory of the Martini Runtime, and sets the location of the folders it will monitor in the resources folder of this demo package. With this, it eliminates the need to set up the Martini Endpoint manually allowing users to focus on what this demo is all about.
Processing the EDI document
The Directory Watcher endpoint \\demo002-edi-to-erpl\Endpoints\edi-dropbox-directory-watcher is configured to listen for new files written to the folder \\demo002-edi-to-erpl\resources\edi-dropbox. When a new file is detected in this folder it will run the service located at \\demo-edi-to-sql\code\main\ConsumeEdi.
When the \\demo-edi-to-sq\code\demo002\services\directory_watcher\ConsumeEdi service is triggered by the Directory Watcher endpoint, an input stream containing the contents of the EDI document will be passed to it.The service \\demo-edi-to-sq\code\demo002\services\directory_watcher\ConsumeEdi uses two Functions to convert the EDI document to XML:
- Line 8: File.outputStream \ Double click the function to see its inputs and outputs. The file input of this Function creates an empty XML file to be saved in \\demo-edi-to-sql\resources\processed-edi-docs. The output of the function is mapped to a fileToSave and is passed to the next line.
- Line 14: EdiToXml.convertToXmlFile \ This is a custom Function written in Groovy. The Groovy class is located at \\demo002-edi-to-erp\code\demo002\groovy\EdiToXml. The Groovy class uses a Java library located at \\demo002-edi-to-erp\lib\staedi-1.16.2.jar. The Jar contains resources that convert an EDI document to XML. The custom Function EdiToXml.convertToXmlFile from the Groovy class EdiToXml is then used in our service to write the contents of the EDI document to the XML file that was created by the File.outputStream function from Line 3.
As a result of the service above an XML representation of the EDI document will be created in \\demo-edi-to-sql\resources\processed-edi-docs.
Martini Online usersLine 3: FileMethods.listFiles
The service \\demo002-edi-to-erp\code\demo002\services\ProcessEdiDropbox combines all the Functions from the services being triggered by the Directory Watcher into a single service. The difference between this service and the services used by the Directory Watcher endpoint is instead of creating an XML file representing the EDI Document, this service uses an XML string instead and passes it directly to a Function that converts the XML to an object, which is then mapped to a model. The following Functions are as follows:
Double click the function to see its inputs and outputs. This function accepts 3 inputs. directory, extensions, and recursive. These inputs refer to the location of the directory that contains the list of files we will process( in this case, the edi-dropbox ), the types of file to filter, and to make the function list the files of a subdirectory if it has one, respectively. The output of this function is a collection of files that matches the given filter which is then mapped to a property called fileList
Line 4: Iterate Step
In this line, we are telling our service to iterate through the fileList and with each iteration, process the conversion of the EDI documents, converting them to an XML string, and finally, saving them to the database. The child functions under the Iterate Step are as follows.
Line 5: EdiToXml.convertToXmlString
This is a custom Function written in Groovy. The Groovy class is located at \\demo-edi-to-sql\code\groovy\EdiToXml. The Groovy class uses a Java library located at \\demo-edi-to-sql\lib\staedi-1.16.2.jar. The Jar contains resources that convert an EDI document to XML string. The Function EdiToXml.convertToXmlString from the Groovy class EdiToXml returns an XML string representation of the EDI document processed from the resources\edi-dropbox folder which is then converted to a an object and finally mapping it to a model so we can pick and map the data we want to save in the database.
Line 6: XmlMethods.streamToGloopObject
This function is used to create an object which can be mapped to a model. This service accepts an XML string and returns a object which is then mapped to purchaseOrder model.
Line 7: Map Step
Maps the data we need from purchaseOrder model to erpInput which will be the request body that will be sent to the APILine 8: HttpMethods.http \ This function sends an HTTP request to the API, sending the erpInput that was mapped in the previous line.If this service is invoked, it will pull all the EDI Documents with a txt file extension under the resources\edi-dropbox folder.It will then iterate on each file, converting them to an XML string, then to a model, and finally, saved to the database.
Saving the EDI data to the API
Martini Desktop users only:
- When the EDI document has been converted to XML and then written to the folder \\demo002-edi-to-erp\resources\processed-edi-docs, the Directory Watcher endpoint \\demo002-edi-to-erp\Endpoints\processed-edi-docs-directory-watcher will detect the file and send it as an inputStream to the service \\demo002-edi-to-erp\code\demo002\services\diretory_watcher\SendToErpApi.
- The service SendToErpApi reads the XML and sends it to the _ERP _API:
- Line 8: Xml.streamToGloopObject \ This Function will receive the inputStream sent by the Directory Watcher endpoint \\demo-edi-to-sql\Endpoints\processed-edi-docs-directory-watcher.
- Line 9: Map Step \ Maps the data to be sent in the API.
- Line 14: HttpMethods.http \ This function sends an HTTP request to the API, sending the erpInput that was mapped in the previous line.
- When SendToErpApi service is triggered, the inputStream will be mapped to XmlMethods.streamToGloopObject this Function will convert a Java InputStream to an object.
- The object will be then mapped to a model representation of the XML data from the EDI document that was processed previously called purchaseOrders.
- In the next step, parts of the XML representation of the EDI Document will be mapped to a model called `erpInput. In this demo, we are going to get the shipment details of a purchase order, and send it to the ERP API.
- When the service finishes executing this function, the shipment data for the purchase order received will be saved to the database.
Martini Online users:
Refer to the Martini Online section under Processing The EDI Document step above.
Logging the transaction to Tracker
- Logging endpoint transactions are added to the services used for this demo by enabling the Log to Tracker checkbox in the Directory Watcher endpoint configuration in this package.
- These logs can be used for auditing what took place during the execution of the service triggered by the Directory Watcher endpoint and can be found in the Tracker UI.
- To access the Tracker UI, look for a magnifying glass icon in the menu bar on the top-right corner of the Martini Desktop UI.
- When enabling the Tracker logging for a Martini Endpoint, only the initial invocation, and service termination are being logged. In order to give us a better, more meaningful view of what took place during a service execution, several functions were added to log every step of what’s happening when one of the Directory Watcher endpoints of this demo is triggered.
- Tracker.addDocumentState - This function is used for adding States in a Tracker document.
- Tracker.addDocumentLog - This function is used to add log messages to a Tracker document. This serves as additional information to the transaction being added in the Tracker document.
- Sample usage:
- Open the ConsumeEdi service located in \\code\demo002\services\directory_watcher\.
- In the ConsumeEdi service, you will see three Fork steps that check if the EDI Tracker document exists. Under these fork steps, there are Block steps added to group one service logic together.
- These blocks contain the same service logic group, that is logging what took place during this service’s execution.
- Take note that these blocks are only executed if the Log to Tracker option is enabled in the Directory Watcher endpoint configuration for this package. The input $trackerId will be the reference if the Tracker logging is enabled or not. If the Tracker logging is enabled, the Directory Watcher will supply the id of the Tracker document that was created for the current transaction.
- In order to have a visualization of what took place during the service execution, these blocks are placed before and after the main functions described in the application flow for this service.