Projects:External data loading process/Technical Specifications Module
Introduction
In this document are described the technical specifications of the EDL module to load and extract data from external resources.
Module Definition
- Name
- External data integration in the ERP
- DB Prefix
- OBEDL
- Java Package
- org.openbravo.externaldata.integration
- License
- Openbravo Commercial
Module Windows and Tabs
EDL Process
System window where available EDL Processes are defined. The EDL Processes must belong to a third party module where the process logic is implemented.
Fields:
- Name
- Name of the EDL Process.
- Search Key
- Code of the EDL Processes. Used to identify the Java classes implementing the process with Qualifiers.
- Type of Data
- Determines the type of the data to be processed.
- Storage Location
- How is stored the Data that needs to be processed.
- Has Input
- Flag that determines if the process needs to receive the data.
- Has Output
- Flag that determines if the process produces data that needs to be send or stored by a Output process.
- Synchronous
- Flag that determines if Requests of this process are run synchronously or asynchronously.
- Record Size
- On asynchronous Processes determines the number of items that are included on each batch process.
- Commit Items
- On asynchronous Processes determines the number of items that are processes before doing a commit.
Constraints:
- Search Key must be unique in the system.
- If the process is asynchronous the Record Size and Commit Items fields must be populated.
EDL Output Type
System window where available Output Types are defined. The Output Types can belong to third party modules.
Fields:
- Search Key
- Code of the Output Type. Used to identify the Java classes implementing the output process with Qualifiers.
- Requires Flag
- Several flags to show the corresponding field on the output configuration when the output process needs some of them.
Constraints:
- Search Key must be unique in the system.
Debug Output Type
Output type included in the EDL Module. It prints the output content on the Openbravo log file. Implemented by OutputDebuggerProcessor class.
WSRest Output Type
Output type included in the EDL Module. It sends the output content using Rest Web Services. It requires to configure the Path, User, Password and the Web Service Method to be used on the Web Service request. This Output Type implements the storeSendingData() method so all the content send by this output is stored and visible on the EDL Request window. Implemented by OutputWSRestProcessor class.
EDL Configuration
Client/System window where the available EDL Processes on each client is configured.
Header Fields:
- EDL Process
- The process to be configured.
- Other fields
- Depending on the selected process other fields might be included by the module where the EDL Process is defined.
Output tab Fields:
- Sequence Number
- To determine the order of the Output processes execution.
- Output Type
- The output process to be executed.
- User, Password, Path, Filename, Web Service Method
- configuration fields only visible based on the selected Output Type.
- Other fields
- Depending on the selected process or Output Type other fields might be included by the module where the EDL Process is defined.
EDL Request
Client/System window where all the EDL Requests are shown. All the requests are automatically processed when they are added. In this window it is possible to view the status of each one and reprocess them in case it is needed. If the request is asynchronous it is also possible to check the request lines with the batches and their process status. Some output types can store the output that has been generated for each request or request line if it is asynchronous. This content is also visible on this tab.
Header Fields:
- Status
- The status of the request: Initial, Processing, Error, Success and Voided
- Organization
- The organization owner of the request.
- EDL Process
- The process of the request.
- Request Date
- The time-stamp when the Request was added to the system.
- Execution Date
- The time-stamp when the Request process was finished.
- Request Data
- The raw input data in case the Database Location is selected as Storage Location.
- Context Data
- JSON String with the context data in case the EDL Process implements it.
- Response
- Text with the response of the EDL Process.
Request Line tab fields:
- Status
- The status of the line: Initial, Processing, Error, Success and Voided
- Import Entry and Archive Import Entry
- The Import Entry used to schedule the execution of the request line.
- Error Msg
- Text with the error message in case of failure.
- Linedata
- Text with the batch of items to be processed on the request line.
Ouput Content tab fields:
- Request Line
- The Request Line that has originated this output content.
- Execution Date
- The time-stamp when the content was generated.
- Content
- The text with the output content.
Processes
- Process (header)
- Reprocess the selected Request.
- Discard (header)
- Cancel the selected Requests in Error status. If a request fails and it is not desired to reprocess it again it is possible to void it by this button.
- Process (Request Line)
- Reprocess the selected Request Lines.
JSON Type of Data
Basic implementation of a type of data to manage items received as a JSONObjects in a JSONArray. Available for Asynchronous and Synchronous EDL Processes.
Implemented by following classes:
- JSONAsynchProcessor
- JSONDataProcessor
- JSONSynchProcessor
Public Classes
org.openbravo.externaldata.integration.process.ProcessRequest
Main class to manage requests. It implements the following public methods:
- getProcessRequestInstance()
- Used to load an instance of the ProcessRequest class.
- addRequest(String processId, Object data)
- Adds a new EDL Request that does not have any response writer.
- addRequest(String processId, Object data, Writer responseWriter)
- Adds and executes a new EDL Request
- reprocessRequest(String requestId, boolean onlyErrors)
- Method to reprocess a Request. It loads the stored input data and tries to process again the request.
- processRequestLine(OBEDLRequestLine _requestLine)
- Method that processes a EDL Request Line. Processes the batch of items stored in the request. If the result is success it executes the configured output processes.
- cancelRequest(String requestId)
- Cancels a request in Error status by updating it and its request lines, in case it is asynchronous, to Void status.
Abstract Classes
T and U types are defined by the Type of Data implementation. T is the type of each item and U is the type of a collection of items. In case of JSON type of data each item (T) is dafeined as a JSONObject and the items are received and batched (U) as JSONArray objects.
org.openbravo.externaldata.integration.process.DataProcessor< U>
Implemented by the Type of Data. Implementations must define a Qualifier with the search key of the Type of Data that are implementing.
It has to implement a method to convert the raw data as it is received to the U type. The abstract method has available several fields to get the needed information to retrieve the data.
- Object rawData: Is the data as it is passed in the data parameter of the addRequest() method.
- JSONObject contextData: In case the Type of Data or the EDL Process implements it this field contains a JSONObject with context information.
- OBEDLRequest request: The EDL Request record that it is being processed.
- ProcessDataProcessor< U> processDataProcessor: Instance of the ProcessDataProcessor class that will execute all the items on this EDL Request.
org.openbravo.externaldata.integration.process.AsynchronousProcessor<T, U>
Class to implement by any Type of Data available to be executed asynchronously. Each implementer has to define the getDataBatcher(), getBatchFromList() and getItemIterator() abstract methods.
The items to be processed are grouped in batches of the type defined by the Type of Data. The size of the batch is defined by the EDL Process. Each batch is stored as a String in a Request Line that it is processed asynchronously. When the request line is processed the batch has to be iterated to retrieve the items in the type defined by the Type of Data.
- getDataBatcher() method: Creates a Iterator of String based on the rawdata of the EDL Request. Each element of the iterator should be a String representation of the type defined by the Type of Data for the batches. The raw data is retrieved by calling dataProcessor.getDataFromRaw().
- getBatchFromList(List<T> items) method: Converts a List of items to a batch String.
- getItemIterator() method: Creates a Iterator of items of the type defined by the Type of Data based on the batch being processed. The batch String is retrieved from the requestLine field by executing requestLine.getLinedata().
org.openbravo.externaldata.integration.process.SynchronousProcessor<T, U>
Class to implement by any Type of Data available to be executed synchronously. Each implementer has to define the getItemIterator() abstract method.
- getItemIterator() method: Gets the data to be processed and returns a Iterator of items. The batch of items can be retrieved by executing dataProcessor.getDataFromRaw() method.
org.openbravo.externaldata.integration.process.CustomStorageLocation
By default the module provides 3 different Storage Locations where the data to be processed on each request is stored.
- Not Stored (NS): The data is not stored.
- Database (DB): The data is stored in a column of the EDL Request table.
- Attachment (A): The data is stored in a file named Attachment and attached to the corresponding EDL Request.
Any module can add additional Storage Locations by adding a new option on the list reference OBEDL Storage Location and extending this class with a Qualifier with the code of the new option.
org.openbravo.externaldata.integration.process.CustomValidation
When a request is added some validations are executed. Extending this class it is possible to add new custom validations. There are 2 methods to implement:
- doProcessValidations(): Validations executed when the addRequest is called before the EDL Request is created. If any of these validations fail no EDL Request is created.
- doConfigurationValidations(): Validations executed when the EDL Request is going to be processed. If any of these validations fail the process is stopped and the EDL Request is updated to Error status.
org.openbravo.externaldata.integration.process.ItemProcessor<T>
Class to be extended by each EDL Process. It is in charge of implementing the logic needed to process each item.
It has to implement 2 abstract methods:
- processItem(T item): Implement the logic to process a single item.
- reprocessNotCommitedItemsOnException(): Asynchronous execution process a number of items configured in the EDL Process before committing them. In case of exception a rollback is done. This method determines if the processes that have not been committed need to be processed again or not.
The class also have 3 other methods that can be overridden to execute additional logic:
- updateCustomImportEntry(ImportEntry importEntry, OBEDLRequestLine newRequestLine): this method is executed on asynchronous processes just after the ImportEntryManager.createImportEntry() and before the import entry is processed. By implementing this method it is possible to update the importEntry with additional information.
- outputExtraActions(OutputDataProcessor outputDataProcessor, OBEDLConfigOutput output): Method called from the OutputDataProcessor when there is something more to do with the output, for example reading the response of a webservice request.
- writeResponse(Writer writer, OBEDLConfigOutput configOutput): Method called from the OutputDataProcessor to write the response. This method is executed at the end of the EDL Request process. In the processItem() method some fields can be implemented and set with response messages or statistics so when the this method is executed the can be included in the response. Note that all the items included on one request are executed by calling the processItem() on the same instance of the ItemProcessor call but the writeResponse() method is called only once at the end of the processing.
org.openbravo.externaldata.integration.process.OutputDataProcessor
Class to be overwritten in order to implement different output data processes. These processes are executed when all the items of a request are successfully executed. Each class implementation is identified with the corresponding record added in the EDL Output Type window by a Qualifier and its value.
Each implementer has to implement 2 abstract method:
- obtainWriter(OBEDLConfigOutput output): It returns a Writer where the ItemProcessor of the EDL Process writes the response.
- closeWriter(Writer writer): It closes the Writer and any other needed resource. This method is called after the response is written and before the itemProcessor.outputExtraActions(this, output) is executed.
There are other 2 methods that can be overridden if needed:
- closeResources(): Method to close all the remaining resources. It is executed after the outputExtraActions(). Useful in case it is required to leave something open so the outputExtraActions can read it. See the OutputWSRestProcessor implementation for a case use of this method.
- storeSendingData(): Override this method in case it is required to save in the Output Content tab of the EDL Request the same content that has been sent in the output process.
org.openbravo.externaldata.integration.process.ProcessDataProcessor< U>
Class implemented by each EDL Process to customize how the data is stored and managed.
It includes a single abstract method:
- getDataFromRaw(): Method that it's called by the TypeOfData implementation of DataProcessor.getDataFromRaw(). It returns the received data transformed to a U object with the batch of items. The raw data in the original format can be retrieved from the dataProcessor field. For example the JSON type of data included in the module assumes that the raw data is a JSONObject with a unique item or a JSONArray with several items. In case the EDL Process receives the items as a JSONArray included in a bigger JSONObject this class should be implemented to load the received JSONObject and return the corresponding JSONArray.
This class includes other methods that can be overridden to cover other scenarios where the default Type Of Data implementation needs to be modified:
- initializeRawData(): It receives the data as it is set in the addRequest method. This method can be overridden if it is required to transform it by the EDL Process to get the rawData with the items to be processed.
- loadContextData(): Method to be overridden in case the process has some context data shared on all items to be processed.
- isWriteRawDataToFileImplemented(): Method to be overridden to return true in case the writeRawDataToFile() method is implemented.
- writeRawDataToFile(File attFile): Writes in the attFile parameter the raw data. This method has to be implemented in case the raw data is not an instance of File, String, InputStream, JSONObject or JSONArray and the Storage Location is Attachment.
- isGetRawDataAsStringImplemented(): Method to be overridden to return true in case the getRawDataAsString() method is implemented.
- getRawDataAsString(): Returns the rawData converted to String. This method has to be implemented in case the initial data is not a String, JSONObject or JSONArray and the Storage Location is Database.