Creating import/export processes in CRM.COM software gives a developer the ability to import/export data from/into the system using three supported file types: XML, CSV and EXCEL.
What does this section cover?
This section describes the importing and exporting mechanism. Importing and exporting are both considered process runs. For more information on implementing process runs, go to Implement Process Run Definition.
Create Import Processes
To create an import process, you need to:
- Define the import process in the imports.xml metadata file.
- Create the template file defined in the imports.xml metadata file for the import process.
- Create a process class extending com.crm.process.CRMImportBean, responsible for parsing the file and processing its records and define this process in modules.xml metadata file.
The import process must be defined in the imports.xml metadata file, as shown in the example below. The metadata file can be located under the <custom_project>/src/main/resources/metadata/ directory. Note that all of the information except importdescription must be defined in the file.
<importsconfig xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../xsd/imports.xsd">
<imports>
...
<import>
<importname>Custom Import</importname>
<importdescription>Custom Import in CRM.COM.</importdescription>
<importprocess>CUSTOM_IMPORT</importprocess>
<importmodule>CUSTOM</importmodule>
<importtemplatefilepath>imports/customTemplateFile.csv</importtemplatefilepath>
</import>
...
</imports>
</importsconfig>
2. Template File
The template file will be used as an example for the file used by the import process and can be downloaded from the import data entry page. The file must be placed under the directory defined in the imports.xml metadata file, with the importtemplatefilepath tag.
3. Import Process class
A process class must be created for the import process, extending com.crm.process.CRMImportBean. Below, you can see the implementation of an example import process class. It is recommended to use the LogTextFile method to log the import process results for easier debugging of the process.
public class EXAMPLEImportBean extends CRMImportBean {
...
public void import(String processRunLogID) throws Exception{
CallList.LogTextFile(getCRMSession(), "Example Import start processing (" + processRunLogID + ")", "importExample","");
CRMDOProcessRunLog processRun = (CRMDOProcessRunLog)processRunLogBean.load(processRunLogID);
ArrayList<CRMDO> attachments = attachmentBean.load(processRun);
processRun.setStatus(ProcessRunLogStatus.IN_PROGRESS);
processRun.setStartDate(getCurrentDate());
processRunLogBean.save(processRun);
Boolean processComplete = new Boolean(false);
ProcessRunLogStatus processRunLogStatus = null;
try
{
for (int i=0;i<attachents.size();i++)
{
CRMDOAttachment attachment = (CRMDOAttachment)attachments.get(i);
String[] tokens = StringUtil.split(attachment.getFileName(),".");
String extension = tokens[tokens.length-1];
SupportedImportFileExtensions[] supportedImportFileExtensions = SupportedImportFileExtensions.values();
for (int j=0; j<supportedImportFileExtensions.length; j++)
{
SupportedImportFileExtensions supportedImportFileExtension = supportedImportFileExtensions[j];
if (supportedImportFileExtension.isSupported(extension))
{
if (supportedImportFileExtension.equals(SupportedImportFileExtensions.EXCEL))
{
importEXCEL(attachment,processRun,extension);
}
else if (supportedImportFileExtension.equals(SupportedImportFileExtensions.CSV))
{
importCSV(attachment,processRun);
}
else if (supportedImportFileExtension.equals(SupportedImportFileExtensions.XML))
{
importXML(attachment,processRun);
}
}
}
}
processComplete = new Boolean(true);
}
catch (Exception e)
{
CallList.LogTextFile(getCRMSession(), "Error on processing import (" + processRunLogID + ")" + ExceptionUtil.getStackTrace(e), "importExample","");
saveEntityLogRecord(processRun,"", "",ProcessRunLogEntityStatus.FAILED,e.getClass().getSimpleName(),ExceptionUtil.getStackTrace(e));
processRun.setStatus(ProcessRunLogStatus.FAILED);
processRunLogBean.save(processRun);
}
if (processComplete)
{
processRun.setStatus(processRunLogStatus);
processRun.setEndDate(getCurrentDate());
processRunLogBean.save(processRun);
}
CallList.LogTextFile(getCRMSession(), "Example Import end processing (" + processRunLogID + ")", "importExample","");
}
...
}
Next, you must define this process class and the method that will be called for the import in the modules.xml metadata file, which can be found under the <custom_project>/src/main/resources/metadata/ directory. Note that the <importprocess> and <importmodule> defined in the imports.xml file will be used in the modules.xml metadata file to correcty define the process class. The <importprocess> will be used as the process id and the <importmodule> as the module id, as shown below.
<?xml version="1.0" encoding="UTF-8"?>
<moduleconfig xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="../xsd/modules.xsd">
<modules>
...
<module>
<moduleid>CUSTOM</moduleid>
<modulename>key_custom_import</modulename>
<moduledescription>key_custom_import</moduledescription>
...
<features>
<feature>
...
<commonprocesses/>
<additionalprocesses>
<process>
<id>CUSTOM_IMPORT</id>
<name>key_custom_import</name>
<description>key_custom_import</description>
<methods>
<method>
<ejbname>EXAMPLEImportBean</ejbname>
<methodname>import</methodname>
<scheduled>false</scheduled>
</method>
</methods>
<batch>true</batch>
<csrincluded>true</csrincluded>
</process>
...
</additionalprocesses>
</feature>
</features>
<leftmenuoptions>
<id>CUSTOM_IMPORT_MERCHANT</id>
<id>CUSTOM_IMPORT_BIN</id>
</leftmenuoptions>
</module>
...
</modules>
</moduleconfig>
Create Export Processes
To create an export process, you need to create:
- A process class extending com.crm.process.CRMExportBean, responsible for parsing the file and processing its records.
- A user interface class extending com.crm.process.processrun.CRMUIProcessRunDefinitionBean, responsible for handling the process run definition's page.
- A summary page to display the export process definitions.
- A data entry page to give the user the ability to create, view, edit, delete, save and run an export process definition.
In the following example, we will implement a mechanism to export vouchers. In order to do so, we create CRMExportVoucherBean.java and implement exportVoucher method, which retrieves the vouchers to be exported based on the given lot and writes them to a file of a given type (EXCEL, CSV, XML).
public class CRMExportVoucherBean extends CRMExportBean {
...
public void exportVoucher(String processRunLogID) throws Exception{
CRMDOProcessRunLog processRun = (CRMDOProcessRunLog)processRunLogBean.load(processRunLogID);
ExportVoucherDefinition exportVoucherDefinition = new ExportVoucherDefinition();
exportVoucherDefinition.setProcessRunDefinition(processRun.getProcessRunDefinition());
exportVoucherDefinition = exportVoucherXMLUtilBean.loadFromXML(exportVoucherDefinition);
processRun.setStatus(ProcessRunLogStatus.IN_PROGRESS);
processRun.setStartDate(getCurrentDate());
processRunLogBean.save(processRun);
Boolean processComplete = new Boolean(false);
try
{
CRMDOLot lot = exportVoucherDefinition.getLot();
VoucherFileFormat fileFormat = exportVoucherDefinition.getVoucherFileFormat();
if (lot != null && fileFormat != null)
{
if (fileFormat.equals(VoucherFileFormat.EXCEL))
{
exportVoucherInExcelFormat(exportVoucherDefinition, lot, processRun);
}
else if (fileFormat.equals(VoucherFileFormat.CSV))
{
exportVoucherInCSVFormat(exportVoucherDefinition, lot, processRun);
}
else if (fileFormat.equals(VoucherFileFormat.XML))
{
exportVoucherInXMLFormat(exportVoucherDefinition, lot, processRun);
}
processComplete = new Boolean(true);
}
}
catch (Exception e)
{
processRun.setStatus(ProcessRunLogStatus.FAILED);
processRunLogBean.save(processRun);
}
if (processComplete)
{
processRun.setStatus(ProcessRunLogStatus.COMPLETED);
processRun.setEndDate(getCurrentDate());
processRunLogBean.save(processRun);
}
}
public void exportVoucherInExcelFormat(ExportVoucherDefinition exportVoucherDefinition, CRMDOLot lot, CRMDOProcessRunLog processRun) throws Exception{
ResultSetUtil vouchers = processVoucherBean.getVouchersToBeExported(lot.getId());
if (vouchers!=null && vouchers.getRowCount()>0)
{
ArrayList<String[]> excelRecords = new ArrayList<String[]>();
while(vouchers.next())
{
String voucherID = vouchers.getString("VOUCHERID");
CRMDOVoucher voucher = (CRMDOVoucher) voucherBean.load(voucherID);
try
{
excelRecords.add(constructRecord(voucher));
}
catch (Exception e)
{
Entity voucherEntity = MetadataUtil.getEntityByClass(CRMDOVoucher.class.getName(), getCRMSession().getRealPath(), getOrganisationID());
processLogBean.createEntityLogRecord(
processRun.getId(),
voucher.getId(),
voucherEntity.getId(),
ProcessRunLogEntityStatus.FAILED.toString(),
e.getClass().getSimpleName(),
ExceptionUtil.getStackTrace(e));
}
}
storeEXCELRows(excelRecords, processRun, getFileHeaders());
}
else
{
throw new VoucherNotFoundToBeExportedException(getCRMSession());
}
}
...