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 the abstract class com.crm.process.CRMCustomImportBean, and implement the three abstract methods of this class. Also, define this class in the modules.xml 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. The tags that can be used to define an import process are:

importname: This is the name of the import process and it is mandatory
importdescription: This is the description of the import process and it is optional
importprocess: This is the process id, as defined in the modules.xml file and it is mandatory
importmodule: This is the module id, as defined in the modules.xml file and it is mandatory
importtemplatefilepath: This is the path where the import file template can be found and it is mandatory
importfileheaders: This is a string which contains the import file headers, comma separated and it is mandatory
importparameters: These are the import parameters and it is optional to define them.

a. Import parameters

The import parameters can 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_PROCESS</importprocess>
			<importmodule>CUSTOM_IMPORT</importmodule>
			<importtemplatefilepath>imports/customTemplateFile.csv</importtemplatefilepath>
			<importfileheaders>header1,header2,etc</importfileheaders>
			<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 with the importtemplatefilepath tag in the imports.xml metadata file.

3. Import Process class

A process class must be created for the import process, extending com.crm.process.CRMCustomImportBean and the three abstract methods defined in this class must be implemented. These methods are called with the order shown below for each line of the import file and they are used to construct the data object to be imported from the file line, validate that the object's information is correct and save the dataobject. In more detail, the methods are:

constructData. This method accepts the import parameters and the record values as parameters and returns a data object. The import parameters are a HashMap containing the parameters defined in the imports.xml metadata file with their values. The record values are a HashMap containing the headers of the import file with their corresponding values. as defined in the file line. The method must construct a dataobject from the given values and return it.
validateData. This method accepts a dataobject, validates it and returns it. If the dataobject is not valid the method must throw the relevant Exceptions.
saveData. This method accepts a dataobject, saves it and returns it.

Note that the process class must be bean managed. Below, you can see the implementation of an example import process class.

EXAMPLEImportBean

...
@Stateless(mappedName = "ejb/EXAMPLEImport")
@LocalBean
@TransactionManagement(TransactionManagementType.BEAN)
public class EXAMPLEImportBean extends CRMCustomImportBean { 
 
	private static final long serialVersionUID = 1L;

	@EJB private EXAMPLEObjectBean exampleDataObjectBean;

	...

 	@Override
 	public CRMDO constructData(HashMap<String, String> importParameters, HashMap<String, String> recordValues) throws Exception {
    	    
		//get all values either from import parameters or from record values	
    	if (recordValues.get("name")==null) 
		{
    		throw new MandatoryFieldException(getCRMSession(), "name");
		}
    	
    	if (recordValues.get("alt_code")==null) 
		{
    		throw new MandatoryFieldException(getCRMSession(), "alt_code");
		}
    	
    	String type = null;
    	if(importParameters!=null && importParameters.containsKey("type"))
    	{
    		type = importParameters.get("type");
    	}
    	else 
    	{
    		type = recordValues.get("type");
    		
    	}
    	if (type==null) 
		{
    		throw new MandatoryFieldException(getCRMSession(), "type");
		}  

		String name = recordValues.get("name");
		String alt_code = recordValues.get("alt_code"); 	

		...
			
    	  		
		//construct dataobject and set the values on it
		CRMDO exampleDataObject = exampleDataObjectBean.construct();
		exampleDataObject.setName(name);
		exampleDataObject.setAltCode(alt_code);
		exampleDataObject.setType(customerEventType);
		...

		return exampleDataObject;
	}

	@Override
	public CRMDO validateData(CRMDO data) throws Exception {
		return exampleDataObjectBean.validateOnSave(data);
	}


	@Override
	public CRMDO saveData(CRMDO data) throws Exception {
		return exampleDataObjectBean.save(data);
	}  
}

Next, you must define this process class 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 correctly define the process class. The <importprocess> will be used as the process id and the <importmodule> as the module id, as shown below. It is mandatory to define the importProcess method, as shown below. This is the method that is called on submitting the import and it is implemented in the abstract CRMCustomImportBean class.

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_IMPORT</moduleid>
			<modulename>key_custom_import</modulename>
			<moduledescription>key_custom_import</moduledescription>
			
			...
						
			<features>		
				<feature>
					...

					<commonprocesses/>
					
					<additionalprocesses>
						<process>
							<id>CUSTOM_IMPORT_PROCESS</id>
							<name>key_custom_import</name>
							<description>key_custom_import</description>
							<methods>
								<method>
									<ejbname>EXAMPLEImportBean</ejbname>
									<methodname>importProcess</methodname>
									<scheduled>false</scheduled>
								</method>
							</methods>
							<batch>true</batch>
							<csrincluded>true</csrincluded>
						</process>
						...
					</additionalprocesses>
				</feature>
			</features>
			
			...
		</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.CRMCustomExportBean, 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. The tags that can be used to define an export process are:

exportname: This is the name of the export process and it is mandatory
exportdescription: This is the description of the exportprocess and it is optional
exportprocess: This is the process id, as defined in the modules.xml file and it is mandatory
exportmodule: This is the module id, as defined in the modules.xml file and it is mandatory
importtemplatefilepath: This is the path where the import file template can be found and it is mandatory
exportfileheaders: This is a string which contains the headers of the export file that will be created, comma separated and it is mandatory
exportcriteria: These are the export criteria and it is optional to define them.

a. Export Criteria

The export criteria can 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.

Note that the fileFormat export criterion must be defined, as shown below, if you want to enable the user to choose the format of the file that will be exported.

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_PROCESS</exportprocess>
			<exportmodule>CUSTOM_EXPORT</exportmodule>
			<exportfileheaders>header1,header2,etc</exportfileheaders>
			<exportcriteria>
				<exportcriterion>
					<exportcriterionname>fileFormat</exportcriterionname>
					<exportcriterionkey>key_file_format</exportcriterionkey>
					<exportcriteriontype>enum</exportcriteriontype>
					<exportcriterionclassname>com.crm.dataobject.ExportFileFormat</exportcriterionclassname>
				</exportcriterion>				
				<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.CRMCustomExportBean and the two abstract methods defined in this class must be implemented. The methods are:

getEntitiesToBeExported. This method accepts the export criteria and returns an ArrayList of the dataObjects to be exported. The export criteria are a HashMap containing the criteria defined in the exports.xml metadata file with their values. The method must retrieve the objects that fulfill these criteria and return them.
constructRecord. This method accepts the entity to be exported and returns a String array which represents the values of a line of the export file. The method must construct the String array using the string values of the entity's fields that correspond to the headers of the export file.

Note that the process class must be bean managed. Below, you can see the implementation of an example export process class.

EXAMPLEExportBean

...

@Stateless(mappedName = "ejb/EXAMPLEExport")
@LocalBean
@TransactionManagement(TransactionManagementType.BEAN)
public class EXAMPLEExportBean extends CRMCustomExportBean {   

	private static final long serialVersionUID = 1L;

	@EJB private CRMBOExampleDataObjectBean exampleDataObjectBean;
	
	...

 	@Override
	public ArrayList<CRMDO> getEntitiesToBeExported(HashMap<String, String> exportCriteria) throws Exception {
		
		ArrayList<CRMDO> entitiesToBeExported = new ArrayList<CRMDO>();
		ArrayList<Object> criteria = new ArrayList<Object>();

		//get the export criteria from the exportCriteria parameter
		if(exportCriteria!=null && exportCriteria.size()>0)
		{			
	    	if(exportCriteria!=null && exportCriteria.containsKey("criterion1"))
	    	{
	    		String criterion1 = exportCriteria.get("criterion1");
	    		criteria.add(criterion1);
	    	}
			
			..
		}
		
		//retrieve the entities that fulfill the export criteria
		entitiesToBeExported = exampleDataObjectBean.load(criteria);
		
		return entitiesToBeExported;
	}

	@Override
	public String[] constructRecord(CRMDO entityToExport) throws Exception {
		String[] record = new String[]{};
			
		String name = entityToExport.getName();
		String altCode = entityToExport.getAltCode();
		...
		
		record = new String[] {name, altCode, ...};
		
		return record;
	}
	
...
}

Next, you must define this process class 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. It is mandatory to define the exportProcess method, as shown below. This is the method that is called on submitting the export and it is implemented in the abstract CRMCustomExportBean class.