Welcome to the AskSam Free-form Import Plugin!

The askSam import plugin allows you to import documents from an askSam file (*.ask) into a MyInfo Topic file (*.mio).

The plugin does not directly access the *.ask file, because the format is not publicly documented. You have to first export the documents from the *.ask file to a text file and import that file into MyInfo.

The export capabilities of askSam are excellent, so you should have no problems selecting the documents you want. As of today you can only do this in text format which means you will lose all formatting. A later release of the plugin is planned which will offer you the same functionality for rich text (RTF) exports.

During import MyInfo is usually working with UTF-8 strings. The plugin, however, is configured for ASCII/ANSI strings as they are produced by askSam. In case you need an UTF-8 import plugin, please let me know.

While importing to MyInfo you can map any askSam field you have to MyInfo's attributes. This even works for multiline fields.

The format that is used by askSam is a structured free form format that is easy to create and edit. There are many other programs around that are able to create a file with this structure, so you can use this plugin to import these files into MyInfo. I've included some examples for this, they show how you can import your mails from theBat! email client, from Lotus Notes or from PDF Files.

Please read the following documents to understand in detail how to configure your import.

Exporting from askSam

Use one of the export possibilities from the File Menu:

Specify a file name of your choice and set a string as the document delimiter (called "Trennzeichen" in my installation):

The document delimiter has to be unique string that does not occur otherwise in your documents. I usually use something of the kind ***_EOD_***  (which means end of document to me).

At the end of the export process you should have a text file that contains all desired askSam documents separated by the document delimiter string.

Configuring the plugin

The import plugin reads its configuration from a configuration file that you create.

The file name of the config file has to be the same name as the import file, but gets a ".ini" extension appended.

Example:

import file is called "emails.txt"  ==> config file has to named "emails.txt.ini"

There is an empty template called "asksam_import.ini" that you should use as a starting point.

The template contains full documentation on all the configuration settings. Please consult it for full details.

Here I will explain the overall concept and the most crucial settings:

Each line beginning with a hash sign (#) is treated as a comment line. The hash has to be in the first column !

Empty lines are possible as well.

The settings are grouped into several sections, the most important ones are:

• General import settings
• MyInfo built-in attributes
• MyInfo custom attributes

There are some other settings that are only documented in the template file. Please contact me, if you have any questions.

General import settings

All of the settings in this section are important. Please make sure to set them correctly in order to get correct results.

To askSam users most of the settings should be familiar so I won't go into much details. Please have a look at the commentary in the ini file :

#------------------------------------------------------------------------------
# General import settings
#
#     DocType           The document type of the import file. Currently only
#                       text files (TXT) are supported
#     DocSeparator      Each document in the import file has to be separated
#                       by a separator string. Specify it here.
#     FieldCharacter    The askSam field character, typically a square bracket
#                       or a colon.
#     FieldOccurence    How to handle multiple occurence of a field within a
#                       document. Possible values are:
#                       First ¦ Last
#                       'First' will keep the first field value found even
#                       if the field occurs multiple times within the file.
#                       'Last' will continously overwrite the field value
#                       thus storing the last value found.
#                       Default is set to 'First'.
#     TrimSpaces        Yes ¦ No
#                       If set to 'Yes', any spaces following the field char
#                       will be skipped, i.e. Field1[   Contents] will become
#                       'Contents' in the Myinfo attribute field
#                       If set to 'No' only the first space after the field
#                       char is skipped. This is the default.
#     DateFormat        askSam date formats that do NOT include a month name
#                       (e.g. 24/12/2010 instead of Dec 24, 2010) can only be
#                       interpreted correctly if you specify the correct sequence
#                       of day, month and year. Possible values are:
#                       DMY ¦ MDY ¦ YMD
#                       You do not have to specify the a date separator. The
#                       following separatorsare currently automatically supported:
#                       . ¦ - ¦ / (dot / dash slash).
#                       Date formats that contain a month name are also auutomatically
#                       detected, but currently only for the following languages:
#                       English ¦ German (please let me know if you need something else)
#                       Be aware that if you specify year numbers with two digits only
#                       they are interpreted as 19xx.
#------------------------------------------------------------------------------
DocType=TXT
DocSeparator=***_EOD_***
FieldCharacter=[
FieldOccurence=First
DateFormat=DMY

MyInfo built-in attributes

In this section you map fields in your askSam documents to MyInfo built-in attributes. After the import the fields will still be shown in the document text jsut like they were in askSam, but they are also set within the binary attributes of the MyInfo document. Mapping should be straightforward, just make sure to read below how multi line fields in askSam are handled:

#------------------------------------------------------------------------------
# MyInfo built-in attributes
#
# There is a set of attributes that is defined for each topic in MyInfo.
# Here you can specify which field in the import field maps to which attribute.
# All supported attributes are defined below and you can leave them empty
# if you don't have a field to map.
# Please let me know if you need support for additional attributes, I
# just added the ones that made sense for my databases.
#
# You should be able to identify all the attributes by their names, so just
# a few notes:
#
#     Attrib_Title      is the most important, it contains the title of the
#                       document, in MyInfo often called "Documents".
#                       If you don't map this field, or if the field you map to
#                       is not contained within a document, the import
#                       plugin will take the first 255 characters of the
#                       document as title.
#
#     Attrib_Priority   You can specify any string that begins with
#                       L(OW) ¦ N(ORMAL) ¦ H(IGH) or alternatively
#                        0    ¦    1     ¦   2
#                       Only the first character is taken into account,
#                       case doesn't matter.
#                       If you use other values, do a global exchange
#                       in askSam before you create the export file.
#
#     Attrib_Tags       You can specify tags be attached to a document
#                       The tags in the askSam field have to be separated
#                       by a space to be recognised. 1024 characters
#                       are supported, the rest is discarded.
#                       If this is a multi line field in askSam, i.e.
#                       the field is spread over several lines then
#                       attach "MULTI" as field type, e.g.
#                       Attrib_Tags=Tags;MULTI
#
#     Attrib_Comment    You can specify a field that is attached as a
#                       comment to a MyInfo article. 1024 characters
#                       are supported, the rest is discarded.
#                       If this is a multi line field in askSam, i.e.
#                       the field is spread over several lines then
#                       attach "MULTI" as field type, e.g.
#                       Attrib_Comment=Comment;MULTI
#
# Don't include the askSam field character when specifying a field name !
#
#------------------------------------------------------------------------------
Attrib_Title=Title

MyInfo custom attributes

This were things get interesting: map your askSam fields into newly created MyInfo attributes. It works about the same as with the built-in attributes, the syntax in the ini file is just a little bit different:

#------------------------------------------------------------------------------
# MyInfo custom attributes
#
# These attributes can be freely defined for each MyInfo topic.
# Currently, MyInfo (version 6.02) supports up to 64 columns in the topic
# (including the built-in). Since the plugin has a limitation of 64 keys
# within the ini file you should never reached the limit within MyInfo.
# The values of all the attributes you define cannot currently exceed
# 10000 characters per document. This limitation is checked within the plugin
# and the import is aborted when the size is exceeded. In this case you would
# have to omit some attributes.
#
# The following syntax is used to define a custom attribute:
#
# CustomAttrib_NAME=FIELDNAME;TYPE
#
# "CustomAttrib_" is mandatory, replace "NAME" with the name of the attribute.
#  "FIELDNAME" has to be replaced with the askSam field name that you want to
#  map. Don't include the field closing character, i.e. "[".
#  Currently only "TEXT" and "DATE" are supported as "TYPE".
#  For "TEXT" you can specify a multiline field mapping by using "MULTI_TEXT".
#  Please let me know if you need support for further field types.
#  N.B.: You have to specify a "TYPE" value since the import plugin has to
#  create the field within MyInfo, whereas MyInfo built-in attributes already
#  exist with a pre-defined type.
#
# I've limited custom attributes to 1024 characters (like the standard
# MyInfo strings attributes).
# Theoretically you could stored custom attributes that are bigger than that
# but that makes no sense in my opinion, because you cannot really use them
# and there is a limit of 10000 characters for all custom attributes together).
#------------------------------------------------------------------------------
CustomAttrib_Owner=Owner;TEXT

Importing into MyInfo

Select File/Import and choose the askSam plugin:

Choose the export file you've created. I'd suggest you'd stick with using ".txt" as an extension for this file. The plugin will simply attache ".ini" to the file you simport has felect and look for this file as your ini file for the import.

If the file you've selected is called "export.txt", please make sure the ini file  you create is called "export.txt.ini" and is stored in the same directory.

When import has finished you get a message box that looks like this:

In case you have warnings or errors please have a look at the log file mentioned.

The log file should be understandable without a lot of documentation. You can search for "WARNING:" or "ERROR:" if you have a big file. You can change the amount of information written to the log file, but the information gets a lot mor technical. In case you run into errors please let me know an I will help you setting up the log file for debug information.

As a result of the import you get a new top level document called something like "Imported 05/15/11 - 22:10:18".

All documents are below this root element. Move them around as you like.

You will probably notice that the date format is a bit weird, but I cannot get it to work correctly in my old compiler. The date is specified in "Month-Day-Year" format, the year has only two digits. The same format is used within the log file.

Release History

Contacting the author

In case you run into problems, have questions or ideas, don´t hesitate to contact me.

You will find me at the MyInfo forums (http://www.milenix.com/forums), my user name is "mfelix".

Simply open a new thread or send me a private message.

Just in case you intend to further distribute this plugin: you can, but please adhere to the license under which I`ve published it:

This work is licensed under the Creative Commons Attribution-ShareAlike 3.0 Unported License. To view a copy of this license, visit http://creativecommons.org/licenses/by-sa/3.0/ or send a letter to Creative Commons, 171 Second Street, Suite 300, San Francisco, California, 94105, USA.

Michael "Felix" Riebschläger