ftlog free forum network - Using ftlogIMP

ftlog: the free forum network: using ftlogimp

home | citizens | network | donate | help

Using ftlogIMP

NOTE: Generally speaking, ftlogIMP's results are not reversible. There is no undo option, and mass-delete within a forum is not yet supported. Please be sure you have read all of these details before proceeding with it's use. It is highly recommended that you import your data into a temporary room should the worst happen.

File Format Basics
The Command Line
The Message Body
The End Of Message Marker
Validating your Text File
Running the Text File in ftlogIMP
If you want to import data for multiple rooms or recreate the room structure from the previous forum
Doing a Last Minute Test
Sending the Data
Logfiles and Assessing the Success of the Upload
Notes and Tips

This information details how to use the ftlogIMP utility to parse a text file to create topics and messages in your forum, typically from another source such as other forum engines. It is envisaged that you will have either created this text file yourself, or used another utility to extract the data from a common forum format.

File Format Basics

The file format is a very simple text format. This is to make it easy for many different people to use it or create conversion tools.

The text file is based around a pipe-separated command line detailing the type of message to be posted in the forum, and then the text itself and an "end of message" marker.

Example:

0|N||This is a subject||Barry
hi there!
FTLOGIMPORT_MESSEND
1|R|0||this would be a comment!|Gavin
This is a reply to the first topic in the message.

New lines in a message body are simply new lines!
FTLOGIMPORT_MESSEND
2|R|1|||Michael Adams
Note the end of message marker below.
FTLOGIMPORT_MESSEND
0|N||Another new topic||Barry
This represents a second new topic, with no replies.
FTLOGIMPORT_MESSEND

A summary of the information required to post a message is thus:

# command line #
# message line(s) #
# end of line marker #

Please note that a new line throughout the text file is donated by carriage return and line feed characters. i.e. "CRLF" or in ASCII, character code #13 followed by code #10.

The Command Line

The "command line" is the first line and consists of fields separated by the "pipe" character... |

It is vitally important that any information you insert to make up these fields has the pipe character stripped out. To be safe, it is recommended that you use a routine to strip out these characters for each field regardless of if you believe the data will be safe or not. Failure to do so will often result in the message being rejected, or worse - the message being posted incorrectly.

Each field in the command line is as follows:

i) Local Message Number
ii) Topic/Reply Indicator
iii) "Replying to" Message Number
iv) Subject Field
v) Comment Field
vi) Message Author / Poster name

These will now be explained separatly:

i) Local Message Number
This can be any number. You can use this to reference a particular message when you add a reply message instruction. This is useful if your existing data consists of threaded messages. If not (e.g. where the source data was from a flat forum), this number can always be the same (use 0 or leave blank). All local message number must be unique per topic, although you can use duplicate id's for separate topics.

ii) Topic/Reply Indicator
This field should be either "N" or "R", and in uppercase. "N" indicates a new topic - any other characters will denote a reply.

iii) "Replying to" Message Number
Here is where you specify which message you are replying to. The number must correspond with a local message number you posted earlier, and within the same topic. For source data from flat forums, you can just leave this as zero or blank.

iv) Subject Field
This is simply a string and is the subject of the topic. Please note, that for replies - this field is ignored. If your source data allowed "subjects" for reply messages, use the comment field instead.

v) Comment Field
Each message can have a "comment", which is essentially a "mini-subject" of it's own. If the message is a new topic, this is in addition to the topic's subject. Otherwise, it is the only way to add a "subject" to a reply message. See above.

vi) Message Author / Poster name
This is the name of the person that posted the message.

The Message Body

The message body is added on the next line immediatly after the command line. As shown in the example, the message can contain new lines itself.

The End Of Message Marker

It is very important that you include the End Of Message marker. Otherwise, all successive lines (including command lines) will be considered to be part of the message body. The marker is...

FTLOGIMPORT_MESSEND

...on a line all by itself. If you want to be extra careful you might just want to check that this text does not appear in any of your message bodies! Unlikely, but you never can be sure - particulary if you were discussing this importing utility in your previous forum, or copy/pasted it there!

Note that just as in the example there should be no blank lines between the end of message marker and the next command line.

Validating your Text File

ftlogIMP includes a very simple text file checker, which should point out the most obvious faults. Because the file format is so very simple, generally there is less to go wrong. However - you are recommended to have a small 10kb-30kb or so portion of your text file checked. Create either a support ticket or post on our support forum.

Running the Text File in ftlogIMP

Open the executable and complete the following fields:

Server
This is the address of the server which your forum is on.
e.g. pow.ftlog.org
There is no need to include the http:// part.

Forum username
This is the forum username of your server.

Username and Password
This is the username and password of the user that owns the forum, or somebody who has the "administrator" permission enabled. They will also need permissions "write" and "reply" enabled in the target room for the message instructions to be accepted.

Target Room ID
This is the room number your messages from the text file will be delivered into. Go into your forum admin, enter the Rooms menu and you will see the id's listed. Incidentally, -1 is the root room id - although you are highly recommended to create a special room to post your messages into.

Source File
Click Browse and select your text file.

Automatic Link Detection
If the text "http://" is discovered in a message body, it will converted into a hyper link. However, be careful that the source text has not already been converted into HTML (or users were able to post raw html in your previous forum) otherwise the link will become unclickable. To play it safe, leave this option off.

Automatic Resource Embedding
This assumes Automatic Link Detection is enabled, and will convert any hyper links which are images, videos, flash files or sounds into embedded HTML. The previous issues apply here too, so to play it safe - leave it off.

Post HTML
If this option is off, raw HTML will be converted into text - otherwise it will act as HTML. Having this option on or off will depend on if there is any HTML code in your source files, and how relevant it is when contained within the ftlog forum pages. To play it safe, leave this option off.

Convert Smilies
This will convert all smilie codes into ftlog smilies. It will not necessarily convert smiles from your old forum into the new smilies, unless the smilies are stored as there plain untouched smilie codes in the message bodies. To play it safe, leave this option off.

If you want to import data for multiple rooms or recreate the room structure from the previous forum

The normal course of action is to create each room separatly in the admin interface, then create a separate text file for each room.

You then run the ftlogIMP software separatly for each room until the process is complete.

Doing a Last Minute Test

Click "1. Test" before you begin. This will scan the text file briefly and highlight any failings you may have overlooked.

Again, note that you are recommended to have somebody check a small part (10-30kb or so) of one your text files prior to execution, either via the ftlog support forums or a support ticket.

Sending the Data

Click "2. Send".

The file will be parsed as with the previous test operation, but this time the messages will begin to be uploaded one by one to the server. There is nothing for you to do here except wait.

Logfiles and Assessing the Success of the Upload

For each message successfully uploaded, an entry will be added into a "success" log file. This is located in a "logs" folder in the sub directory of the ftlogIMP program. The file name is based on when the upload operation begun.

Failed message uploads will be stored within an error file. This is useful in case you want to modify the individual messages so they can be successfully uploaded. Note that if you do choose to do this, it will be impossible to reply to any specific messages which were uploaded in the previous batch because the local message numbers are only current per batch session.

A copy of the status window display is also saved to a "report" file in the same directory. This is useful for finding out why a particular message failed.

Notes and Tips

The following snippets should be read before using ftlogIMP or creating your own text files.

Replies to a particular topic MUST always follow a new message. You CANNOT create two new topics, then add replies to each of them. You MUST create the first topic first, add all of it's replies, THEN add the second topic, and all of it's replies.
It sounds obvious - but if you are adding a reply to a message, the message you are replying to must have been posted first!
Messages will have a post date the same as when the files are uploaded. If you wish to reference the original post date or any other original information, append it in the text form to the end or start of the message. Remember to add a couple of linebreaks to separate it from the message!
Be aware that the maximum size of an ftlog thread is 512 posts, this is because the forum engine is primarily threaded-message based unlike flat forums. If this is a problem, break a large thread up into multiple threads.
If your source messages are threaded but you do not want the hassle of having to detail the thread structure, you could simply reply each message to the the first message in the thread. This depends on how important your original thread structure is to a topic discussion, and how often the thread structure formed part of the regular forum use.
If you are not supply the number of a message to reply to (e.g. if your source data is from a "flat" forum), you have two options to control the formatting of your replies:

Increment the local index number for each message to make the replies format downwards. i.e. each reply will be to the first message in a topic.
Keep the local index number as either "0" or empty to make each reply appear as a reponse to the previous message (so the messages will scroll diagonally outwards).

It is recommended that you upload all messages into a separate room (such as "Archive" or "Old Messages"). You can always move them later via the admin interface.

For further help, goto our help pages or check out the support forums.