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.
1. Define import parameters.
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.

1. Imports 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 and importparameters must be defined in the file. The processes defined in this file will appear in the Imports page, under Foundation > Utilities and you can view and edit their process run definition through this page.

a. Import parameters

The import parameters should be defined in the metadata file to enable the user to give some default values to the respective parameters of the template file. If import parameters are defined, the user will be able to set their values through the import definition data entry page. The import parameters are mapped to the template file's parameters through the <importparametername>, which must be the same as the name of the header of the respective parameter in the template file. So, based on the example below, the template file must have columns with headers custom_parameter1 and custom_parameter2. When defining the import parameters, it is mandatory to define all the information for them. The <importparameterkey> is the label that will appear for the parameter in the data entry page and the <importparametertype> is the type of the parameter and it can be one of the following: java.lang.String, text, java.lang.Integer, java.math.BigDecimal, java.util.Date, password, java.lang.Boolean and enum. If enum is defined as the type, then an additional tag must be defined, the <importparameterclassname>, which indicates the class of the import parameter.

imports.xml

<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>
			<importparameters>
				<importparameter>
					<importparametername>custom_parameter1</importparametername>
					<importparameterkey>key_custom_parameter1</importparameterkey>
					<importparametertype>java.math.BigDecimal</importparametertype>
				</importparameter>
				<importparameter>
					<importparametername>custom_parameter2</importparametername>
					<importparameterkey>key_custom_parameter2</importparameterkey>
					<importparametertype>enum</importparametertype>
					<importparameterclassname>com.crm.dataobject.contactinfo.AddressTypes</importparameterclassname>
				</importparameter>
				...
			</importparameters>
		</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.

If import parameters where defined in the imports.xml metadata file, then their values can be retrieved and used from the process run log's process run definition, using the loadCustomImportActionInputsFromXML method of the ProcessRunDefinitionXMLUtilBean class.

EXAMPLEImportBean

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.

modules.xml

<?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:

Define the export process in the exports.xml metadata file.
1. Define export criteria.
Create a process class extending com.crm.process.CRMExportBean, responsible for creating the export file.

1. Exports Metadata File

The export process must be defined in the exports.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 exportdescription and exportcriteria must be defined in the file. The processes defined in this file will appear in the Exports page, under Foundation > Utilities and you can view their process run logs and submit them through this page.

a. Export Criteria

The export criteria should be defined in the metadata file to enable the user to use some criteria that the entities that will be exported must meet. If export criteria are defined in the metadata file, these criteria will appear on the export's data entry page and the user will be able to define values for that criteria. When defining the export criteria, it is mandatory to define all the information for them. The <exportcriterionname> is the criterion name, the <exportcriterionkey> is the label that will appear for the criterion in the data entry page and the <exportcriteriontype> is the type of the criterion and it can be one of the following: java.lang.String, text, java.lang.Integer, java.math.BigDecimal, java.util.Date, password, java.lang.Boolean and enum. If enum is defined as the type, then an additional tag must be defined, the <exportcriterionclassname>, which indicates the class of the export criterion.

exports.xml

<exportsconfig xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../xsd/exports.xsd">
	<exports>
		...

		<export>
			<exportname>Custom Export</exportname>
			<exportdescription>Custom Export in CRM.COM.</exportdescription>
			<exportprocess>CUSTOM_EXPORT</exportprocess>
			<exportmodule>CUSTOM</exportmodule>
			<exportcriteria>
				<exportcriterion>
					<exportcriterionname>custom_criterion1</exportcriterionname>
					<exportcriterionkey>key_custom_criterion1</exportcriterionkey>
					<exportcriteriontype>java.lang.String</exportcriteriontype>
				</exportcriterion>
				<exportcriterion>
					<exportcriterionname>custom_criterion2</exportcriterionname>
					<exportcriterionkey>key_custom_criterion2</exportcriterionkey>
					<exportcriteriontype>enum</exportcriteriontype>
					<exportcriterionclassname>com.crm.dataobject.contactinfo.AddressTypes</exportcriterionclassname>
				</exportcriterion>
				...
			</exportcriteria>
		</export>

		...
	</exports>
</exportsconfig>

2. Export Process class

A process class must be created for the export process, extending com.crm.process.CRMExportBean. Below, you can see the implementation of an example export process class. It is recommended to use the LogTextFile method to log the export process results for easier debugging of the process.

exportVoucher method

public class EXAMPLEExportBean extends CRMExportBean {   

...
 	public void export(String processRunLogID) throws Exception {
        
		CallList.LogTextFile(getCRMSession(), "Example Export start processing (" + processRunLogID + ")", "exportExample","");

		CRMDOProcessRunLog processRun = (CRMDOProcessRunLog)processRunLogBean.load(processRunLogID);
    
        processRun.setStatus(ProcessRunLogStatus.IN_PROGRESS);
    	processRun.setStartDate(getCurrentDate());
    	processRunLogBean.save(processRun);
        
        Boolean processComplete = new Boolean(false);
    
        try
        {
			exportInExcelFormat(processRun);
               
            processComplete = new Boolean(true);
            
        }
        catch (Exception e)
        {
			CallList.LogTextFile(getCRMSession(), "Error on processing export (" + processRunLogID + ")" + ExceptionUtil.getStackTrace(e), "exportExample","");

            processRun.setStatus(ProcessRunLogStatus.FAILED);
            processRunLogBean.save(processRun);
        }
        
        if (processComplete)   
        {
            processRun.setStatus(ProcessRunLogStatus.COMPLETED);
            processRun.setEndDate(getCurrentDate());
            processRunLogBean.save(processRun);
        }

		CallList.LogTextFile(getCRMSession(), "Example Export end processing (" + processRunLogID + ")", "exportExample","");
    }
	
...
}

Next, you must define this process class and the method that will be called for the export in the modules.xml metadata file, which can be found under the <custom_project>/src/main/resources/metadata/ directory. Note that the <exportprocess> and <exportmodule> defined in the exports.xml file will be used in the modules.xml metadata file to correcty define the process class. The <exportprocess> will be used as the process id and the <exportmodule> as the module id. The process can be defined in the same way as the import process, shown above.

Create Import/Export Processes