This is technical documentation for system integrators
This article presents some sample code from this file:
| View file | ||
|---|---|---|
|
Open the table of contents of the samples via this URL: _plugins/LABS_EXAMPLE_EXPORTEXCEL/page/examples.jspz
| Table of Contents | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|
|
...
the integration of a simplified data export button to an Excel 2007 file in a datalist, not intended to be re-imported.
performing exports or imports of data to or from an Excel 2007 file
...
The Excel Import / Export can be used as a translation tool, to export and reimport strings that need to be exported by an external tool. you may use the dedicated plugin here:
https://drive.google.com/file/d/1PBjiqItJ2jsI4v9BXNX1Eq8PQoo03l8A/view
Plugin Configuration
tempdir
Working directory: indicates the temp of the directory to store temporary files created by the plugin. If the path is relative, it is relative to the SAN directory.
...
Exporting a calculated field
(TBD)
Excel Automatic Import
Documents exported by the button are not normally intended to be imported. However, under certain conditions, and with reduced performance, this is possible.
Documents exported by the export feature can be imported.
By request
The import URL is /_plugins/WXM_EIEXCEL/page/importexcel.jspz
Parameters:
reporting
dryRun
failfast/diehard
append
create => use of the default callback
Attributes (use by include)
importxls_reporting
importxls_callback
Example
Example JSP: EXAMPLE_EXPORTEXCEL/page/exampleImportByRequest.jsp
By tag:
importxls: adds a button that displays a standard import page that uses the standard system (configuration comes from the file)
importxls_append: allows the addition of an instance
By API
exportexcel.jar is an API that you can use directly in your plugin code.
The jar is retrievable in the lib folder of the plugin EXAMPLE_EXPORTEXCEL.
Different examples of invocation are visible in the class fr.wedia.excel.importer.examples.ImportExamples.
Callback
General operation
During import, it is possible to respond to import errors and conflicts through a callback. This is a reflection implementation of an interface.
Creation of the callback
By API:
| Code Block | ||
|---|---|---|
| ||
IImportCallback callback = new IImportCallback() {
public int callback(int code, CallbackContext context, Throwable exception) throws Throwable {
return IImportCallback.EXCEPTION;
}
public boolean canImport(CTSurfer surfer, String objectName) {
return !”activated”.equalsIgnoreCase(objectName);
}
public boolean canImport(CTSurfer surfer, String objectName, String fieldName) {
if ( “status”.equalsIgnoreCase(fieldName) ) {
return IMPORT_FIELD_IGNORE;
}
else if ( “parent”.equalsIgnoreCase(fieldName) ) {
return IMPORT_FIELD_FALSE; // interdit
}
return IMPORT_FIELD_TRUE;
}
} |
By reflection, in a JSP for example:
| Code Block |
|---|
final InvocationHandler callback = new InvocationHandler() {
@SuppressWarnings("unchecked")
@Override
public Object invoke(Object proxy, Method method, Object[] args) throws Throwable {
if ( “callback”.equals(method.getName() ) {
return callback((Integer)args[0],(Map<String, Object>)args[2], (Throwable)args[3]);
}
else if ( “canImport”.equals(method.getName()) {
if ( args.length==3 ) {
return canImport((CTSurfer)args[0], (String)args[1], (String)args[2]);
}
return canImport((CTSurfer)args[0], (String)args[1]);
}
}
protected int callback(int code, Map<String, Object> context, Throwable exception) {
return -4; // EXCEPTION
}
protected boolean canImport(CTSurfer surfer, String objectName) {
return !”activated”.equalsIgnoreCase(objectName); // allows import of all objects except “activated”
}
protected int canImport(CTSurfer surfer, String objectName, String fieldName) {
return 1; // all allowed
}
}
|
Context
The context is a set of properties (in the form of Map<String, Object>) containing information related to the context of the code.
The properties are:
LOCALE: the locale (java.util.Locale)
FILENAME: the name of the file (java.lang.String)
FILE: the file (java.io.File)
APPEND_MODE: the import mode (Boolean)
OBJECT_NAME: the object name (java.lang.String)
FIELD_NAME: the object field name (java.lang.String)
CELL_VALUE: the value read in an Excel cell (java.lang.Object)
VALUE: a value (java.lang.Object)
FIELD: a field (wsnoheto.engine.IObjectField)
ACTION: the localized name of a workflow action (java.lang.String) input, output can be an action (noheto.workflow.IAction)
OBJECT: an object (wsnoheto.engine.IObjectReadOnly)
OBJECT_ID: an object identifier (java.lang.String)
Callback Codes
Return codes
EXCEPTION: -4
throws an exception (and thus stops the import as it is, without rollback)
STOP: -3
immediately stops the import as it is (without rollback)
SKIP_ROW: 4
ignores the spreadsheet row, or the object instance, or action
SKIP_SHEET: 5
ignores the spreadsheet, or object, or action
SKIP_COLUMN: 3
ignores the column, or object, or action
DEFAULT: 1
attempts a default action when possible
CHANGE_VALUE = 2
indicates a replacement value (via the context)
Reports
Simulate an import without modifying the database
This mode allows you to perform the import without making any changes to the database. When combined with a report, it allows you to see potential results and conflicts and debug the callback without modifying object data in the database or creating unnecessary objects. The simulation does not operate in fail-fast mode: in case of exception, the exception is ignored, and the import tries to go to the end, except for insurmountable exceptions (unreadable file for example).
Fail-fast / diehard mode
During the simulation, by default, as soon as the first exception occurs, the process is stopped (fail-fast mode). It is possible to force the simulation to go to the end by using diehard mode.
Import a document that has not been exported
During export, tags are added to the document to allow an import. It is possible to manually tag a document to take advantage of the automatic import.
It is useful to simulate the import to check that the tagging is complete before attempting a definitive import.
The tagging uses Excel names.
Metadata
Global tagging uses a special spreadsheet that must be called __metadata.
The first cell at the top left must be called __DOCUMENT.
The first cell below __DOCUMENT contains the import locale. If the cell is empty, the surfer's locale is used.
The second column contains the version (1.0) (or nothing for version 1.0).
Spreadsheet tagging (object)
For a spreadsheet to target an object,
either the sheet is tagged: the header line is named by the tag _objectname followed by the object's name (for example __objectname_damelement for the object damelement. The name of the sheet can then be anything.
if no object in the database corresponds to the tag, the callback is called with the code UNKNOWN_OBJECT (5)
during import, if the object is not determinable by tag, the callback is called:
if no object tag is found, first the code NO_OBJECT_NAMES (4)
then if there are sheets that are not tagged, the code REMAINING_SHEETS (7)
then for each untagged sheet, the sheet name is used as the object name
if no object corresponds, we call the callback with the code UNKNOWN_OBJECT_IN_SHEET (6).
Column tagging (property)
For a column to target a field:
either the column title is tagged: the cell is named by the tag _fieldname followed by the field name
if the field does not exist the callback is called with the code UNKNOWN_FIELD (10).
during import, if the field corresponding to a column is not determinable, the callback is called
if no field tag is found, first the code NO_FIELD_NAMES (11)
then if there are columns that are not tagged, the code REMAINING_COLUMNS (8)
then for each column, the value in the cell is used as the field name
if no field corresponds, we call the callback with the code UNKNOWN_FIELD_IN_SHEET (12).
Import functionality by template
Problems during import, errors, conflicts, disputes: understanding how we report “issues”.
Introduction
When a problem occurs during the import, an exception is raised. It is possible to intercept this exception in order to indicate to the import process an alternative to solve the problem. This allows:
to stop the process silently (without exception)
to ignore objects, object instances, fields, etc.
to propose replacement values in case of erroneous values, or to activate auto-correction procedures
etc.
Every problem is characterized by an issue. An issue is:
an identification code
an exception
a context that allows knowing and/or modifying certain information
The resolution of the issues is done by a callback method which will be invoked for any issue. The return value of the callback determines how the process will handle the conflict:
the value -4 (EXCEPTION) indicates that the planned exception is raised. The process then stops, except in diehard simulation mode, where the process will continue as much as it can;
the value -3 (STOP) indicates that the process is stopped without raising the exception
the value 4 (SKIP_ROW) indicates that the import of the current object instance is cancelled
the value 5 (SKIP_SHEET) indicates that the import of the current object (of all instances of the object) is cancelled
the value 3 (SKIP_COLUMN) indicates that the import of the current field is cancelled
the value 2 (CHANGE_VALUE) indicates that a replacement value is proposed for a problematic value, or a lack of mandatory value, or any hindrance. If the proposed value continues to cause trouble, the original exception will be raised.
the value 1 (DEFAULT) allows to select a default automatic operation
any other value corresponds to a default behavior depending on the issue. Generally, it is EXCEPTION or DEFAULT.
List of issues
NO_METADATA_LOCALE
Use the API in your own plug-in