Introduction

This article was originally created for Iguana 5 and may contain outdated references.

If you want to create an Action Plan for errors when they occur in the Iguana Log, then this FAQ should help you.

This FAQ explains how to document Iguana Errors and annotate then with Comments and Actions.

This is accomplished by (surprise) using a Translator channel to process lists of error messages and store them to a SQLite database. The lists of errors can be exported from the Iguana Logs or compiled manually. The Errors and annotations are then output into CSV files so you can view them in Excel (or a text editor etc) or import to a database. We supply a SQLite database which contains some errors we have already documented. You can use this as a base and add your own errors, or you can start with an empty database and document only your own errors.

Here are some Iguana error list examples. You may want to view our list of common Iguana errors in the reference section.

Prerequisites

• You need a Windows Iguana Instance to work on, ideally this should not be a production server.

  Note: The code is easy to modify for Mac and Linux etc.

  There are a couple of calls using os.execute() that are Windows specific.

• You need access to your Iguana Servers so you can export logged errors.

  Note: You do not need run this code on the server(s) you are documenting.

• You need to know how to export messages from the Iguana Logs as a CSV file.
• You need to know how to create a channel in Iguana.
• You need to know how to import a project file to an Iguana Channel.
• You need to know how to run code interactively in the Translator.
  • This is very easy, any change in the code will do it – e.g., just add or remove a space.
• It will be helpful if you are comfortable using Lua scripts in the Translator.
  • If necessary have a look this at our Iguana Tutorials.

Preparation

• Create the error message directory:
  • Create directory C:\temp\ErrorMsg.
  • To use a different change the WORKING_DIR above main() in the code.
• Copy the SQLite database file Errors.sqlite into the message directory.

  Note: if you do not copy this file a new empty database file will be created.

• GOTCHA: do not put any newlines (\n) in the Message field:
  • You can do this in Excel, by using alt+enter to wrap data within a cell – but it will not be imported correctly.
  • The code uses io.read() to read the CSV file line by line – so the newline (\n) “ends” the line prematurely.

    Note: you could read the whole file with io.read("*all") and write a better line parser using Lua code.

    If you decide to do this please share your code with us.

  • If you have “newline issue” you can revert to a backup copy of the Errors.sqlite in the message directory.

Install the project

• Create a new channel called Export Errors (you can use a different name).
  • Use a From Translator component and a To Translator.
• Import the Export_Errors_From_Translator.zip into the From Translator.

Background

What do the fields in the Error table and the CSV file mean?

• First the fields in the output files are the same as in the database Error table.
• Message: this is the text of the error message.
• Type: this is the type of error message.
  • debug: this is a development coding error (for a programmer).
  • Lua debug: this is a Lua coding error (for a programmer).
  • error: this a legitimate production error (for an administrator).
  • warning: production warning (for an administrator).
  • info: information message
• Status: this is used to decide which errors are shown in the filtered output (ErrorsOutShow.csv).
  • show: indicates to show in the ErrorsOutShow.csv file.
    • currently I am using show to indicate unique messages.
  • Other codes like hide and duplicate are just descriptive.
• Source: where the error into the was sourced from, e.g.,
  • Interfaceware – log export
  • Interfaceware – manual entry
  • If you document your own errors you may want to extend this, e.g.,
    • <your company> – log export
    • <your company> – manual entry
    • <other custom entry that has meaning to you>
• DateTime: date/time that the error was written to the Iguana Logs.
  • For entries with no date/time (manual etc) *** is entered.
• LogSource: source of the error from the Iguana Logs.
  • For entries with no date/time (manual etc) *** is entered.
  • This data is copied from the Source Name field in the Iguana Logs.
• Location: this is where the error is found in Iguana, e.g.,
  • Iguana Logs
  • ServiceErrorLog.txt
  • Iguana System
• Description: state briefly/precisely what the error means.
• Comment: use to describe the error.
  • longer brain dump of potential issues solutions etc etc…
  • You might have a particular circumstance specific to you installation you want to describe.
• Action: state briefly/precisely the action to be taken when the error occurs.
  • You may require specific action(s) for your installation.

Why we keep duplicate error records in the database

• As placeholders to prevent them from being re-imported.
• Saves time as you only need to document them once (when they are first imported).

Backup of Errors.sqlite can be annoying – creates a lot of copies

• If you are tempted to comment out this code – don’t do it!
  • Just delete ErrorsIn.csv and ErrorsDoc.csv from the message directory = no backups.
  • I added the backup after making a mistake I could not recover from (had to rebuild DB from scratch).
• The backup codebackupSqlite() only runs when the database is changed, e.g.,
  • When rows are inserted – in the insertErrors() function.
  • When rows are updated – in the updateErrors() function.
  • If there is no ErrorsIn.csv or ErrorsDoc.csv in the message directory this code does not run.

Procedures

How to view the Errors already in the database

• Make sure Errors.sqlite is the only file in the message directory.
• Run the code interactively
• Open the CSV output files to view the results:
  • ErrorsOutAll.csv – view all the errors.
  • ErrorsOutShow.csv – view only the errors with status of show.

    Note: If there are no errors you need to copy Errors.sqlite to the message directory (step 2 of preparation).

How to add errors to the database

• Export the errors from your Iguana Server as a CSV file.
  • You may wish to export two files one for marked errors, and another for unmarked errors.
• Copy the error file(s) to the message directory.
• Name the file ErrorsIn.csv.
• Run the code interactively.
• View the ErrorsOutAll.csv file to confirm your errors were added.
• To import multiple error files, simply repeat the process with each file.
  • Name the first file as ErrorsIn.csv and run the code.
  • Delete or rename the first ErrorsIn.csv file.
  • Name the 2nd file as ErrorsIn.csv and run the code.
  • Repeat for all your error files.

How to use the output data files

• Use them as the basis for an action plan when errors occur.
  • The Action field can be used to tell support staff what to do.
  • The Comment field should contain descriptive information.
• Or simply use them as documentation so you understand errors better.

How to document only the Errors from your own Iguana Server

• You need to start with an empty Errors.sqlite database file.
• To achieve this simply delete the Errors.sqlite file, and an empty one will be created.
  • You will need to stop the Iguana service to be able to delete the file.
• Then add your own errors to the database as described below.

How to annotate Errors with Comments and Actions etc

• Copy the ErrorsOutAll.csv file.
• Edit the file in Excel (or similar) and update the following fields:
  • Status
  • Source
  • Location
  • Description
  • Comment
  • Action

    Note: Do not leave fields blank/empty “***” as “intentionally entered no data”.

    This shows that you chose intentionally not to enter anything (rather than just forgetting).

    Also the way SQLite handles NULL values makes queries much more difficult.