Difference between revisions of "Using the import servlet"

 
(8 intermediate revisions by 3 users not shown)
Line 1: Line 1:
= An example for using the module to import or export contact data as CSV ==
+
== Basics ==
 +
There are two things to do with the import servlet:
  
Importing and exporting is done by the servlet ImportExport.java in the package com.openexchange.ajax. The path to this servlet is stored in servletmapping.properties, usually it is [serveraddress]/ajax/importexport.
+
* You can use it to import data into Open-Xchange Server
 +
** Example: ''Importing your Outlook data by exporting it as CSV and then importing it''.
 +
* you can extend it to import new formats
 +
** Example: ''Currently, the CSV format can only be used to import contacts. You can extend it to import appointments''.
  
Whether you do an import or an export is decided quite simply: If you send a PUT request, you're importing (because you are sending data), if you send a GET request, you're exporting (because you are requesting data). So no parameter is needed to indicate what you're doing. This has the additional advantage that you can use the same kind of URL to import and export (which also means: I only have to describe this only once ;-)). So, let's construct an URL:
+
Importing data using existing importers is done using the API, as explained in [https://documentation.open-xchange.com/ HTTP API (import module)].
  
  StringBuilder bob = new StringBuilder();
+
== Details ==
  bob.append("http://");
+
A collection of details about the importer
  bob.append(getHostName());
 
you probably know your hostname better than I do. ;-)
 
  
  bob.append("/ajax/importexport?session=");
+
=== Date formats in CSV files===
  bob.append(getSessionId()); 
+
While the date formats of both iCal and vCard are pretty clear, csv can be defined freely (insert "of course" or "sadly" as you like).
how you get the session depends on whether use write another servlet or work from the GUI.
 
  
  addParam(bob, ImportExport.PARAMETER_FOLDERID, folderId ) ;
+
Microsoft Outlook does as it likes:
folderID = the ID of the folder you want to export from or import into.
+
* the German version uses DD.MM.YYYY
 +
* the English version uses MM-DD-YYYY
  
  addParam(bob, ImportExport.AJAX_TYPE, type);
+
Our own format uses the timestamp format. Advantage: You can use hours and minutes. Disadvantage: You'll have to use negative numbers for dates before 1-1-1970.
type = the type of folder (Contact, Task, Appointment or whatever), as defined in com.openexchange.groupware.Types. Now, if you are stuck with another number (yeah, the OX design is a bit incongruent there...), you might want to take a look at com.openexchange.groupware.importexport.ModuleTypeTranslator, which was written to solve this problem.
 
  
  addParam(bob, ImportExport.PARAMETER_CONTENT_TYPE, format.getMimeType());
+
Information for developers: The date format interpreters are build to be exchangeable, you can use your own format there.
format is usually of type com.openexchange.groupware.importexport.Format - you can use a selfmade MIME-type if you're sure you have a converter for that.
 
  
  addParam(bob, ImportExport.PARAMETER_COLUMNS, ContactField.GIVEN_NAME.getNumber());
+
== Other ==
  addParam(bob, ImportExport.PARAMETER_COLUMNS, ContactField.EMAIL1.getNumber());
+
Adding a new importer is explained in [[Building an importer]].
This parameter is optional. If you have a format that allows for a variable number of data fields to be exported or imported, this is the way to pass them to the servlet. It currently is used only for CSV Contacts. The parameter contains an array (as in the example, you can use this parameter more than one to create an array). Now you just need the numbers for the columns, right? For Contacts, the way to identify a field is to use the enum ContactField of the package com.openexchange.groupware.contact.helpers.
 
  
If you want to import data, you must add your data as InputStream to your request.
+
See also: [[Using the export servlet]].
  
Now send this URL to the servlet.
 
  
See also: [[HTTP API]]
+
 
 +
[[Category:OX6]]

Latest revision as of 13:42, 29 June 2016

Basics

There are two things to do with the import servlet:

  • You can use it to import data into Open-Xchange Server
    • Example: Importing your Outlook data by exporting it as CSV and then importing it.
  • you can extend it to import new formats
    • Example: Currently, the CSV format can only be used to import contacts. You can extend it to import appointments.

Importing data using existing importers is done using the API, as explained in HTTP API (import module).

Details

A collection of details about the importer

Date formats in CSV files

While the date formats of both iCal and vCard are pretty clear, csv can be defined freely (insert "of course" or "sadly" as you like).

Microsoft Outlook does as it likes:

  • the German version uses DD.MM.YYYY
  • the English version uses MM-DD-YYYY

Our own format uses the timestamp format. Advantage: You can use hours and minutes. Disadvantage: You'll have to use negative numbers for dates before 1-1-1970.

Information for developers: The date format interpreters are build to be exchangeable, you can use your own format there.

Other

Adding a new importer is explained in Building an importer.

See also: Using the export servlet.