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.


     
     

    About | Contact | Browser Compatibility | Privacy Policy | Terms and Conditions
    1999-2017 ftlog.org. All Rights Reserved.