E-Log XML Format

  This web page describes the XML format of the SLAC version of the Electronic Logbook system ported from Jefferson Labs. It is intended for the use of software developers in generating E-log entries from programs or scripts.

Overview

To make an E-log entry, a XML file in a specified format and any referenced graphics attachment files are copied into a specified directory. A continually running script examines this directory periodically (e.g., every 3 minutes) for new E-log entry files to process. This script processes each E-log entry XML file and any associated attachment files by moving the files to another directory, validating the XML file, checking the existance of referenced attachment files, and creating rows in Oracle database tables. The data stored in the Oracle database from the contents of the E-log entry XML file and referenced attachment files constitute an E-log entry that may be viewed by web pages.

Location of XML files

An E-log XML file generated by a program or script should be copied to the following directory for processing:

    /nfs/slac/g/cd/mccelog/logxml/new
The file should have the extension ".xml".

Instead of copying an E-log XML file into the above directory, it may be put into this directory using the E-log "print queue" feature. From SLAC VAX/VMS machines or UNIX machines, an E-log XML file may be printed using one of the following queues:

  1. elog_accl
  2. elog_pep
  3. elog_mcc
  4. elog_nlcta
  5. elog_pack
  6. elog_rf
  7. elog_bic
  8. elog_spps
  9. elog_swlog
  10. elog_tlog
The following is an example command from a UNIX machine:
    lpr -Pelog_tlog 20031211_132045_12345.xml
In order not to overwhelm the E-log "print queue" mechanism, it is suggested to only use this mechanism when there is a compelling reason to do so (e.g., the above directory is not accessable from the system where the E-log XML file is created). Also at present the E-log "print queue" mechanism cannot be used to send E-log attachments to the above directory.

XML file names

Each E-log XML file should have a unique name since all such files are stored in a common directory after being processed and stored into Oracle. The E-log web interface creates XML filenames with the following format:

    date_time_number.xml
where date is yyyymmdd, time is hhmmss, and number is a sequence number. For example, a XML file generated December 11, 2003 at 13:20:45 might have the name:
    20031211_132045_12345.xml
It is recommended that programs or scripts generating E-log XML files use this or a similar naming convension to insure that E-log XML filenames are unique. For XML files generated from a program or script, a name associated with the program or script may be included in the filename (e.g., 20031211_132045_swrelease01.xml).

Attachment file names

If the XML file references any graphics attachment files they should also be copied to the above directory and have the same base name as the XML file (if the XML file is 20031211_132045_swrelease01.xml the base name is "20031211_132045_swrelease01"). The attachment files have extensions of the following form:

    .attach_n.file_type
where the "n" in "attach_n" is an integer: 1 for the first referenced attachment, 2 for the second referenced attachment, and so forth. The string "file_type" refers to the type of the graphics file. The following "file_type" strings are supported:
  1. png
  2. gif
  3. jpeg
  4. ps
  5. pdf

For example, if the XML file 20031211_132045_swrelease01.xml references two graphics files (a png and a gif file), the first graphics file 20031211_132045_swrelease01.attach_1.png and the second is named 20031211_132045_swrelease01.attach_2.gif.

Required XML tags

The simplest E-log entry XML file contains the log_entry, title, program, logbook, and log_user tags. An example is as follows:

    <?xml version="1.0" encoding="ISO-8859-1"?> <log_entry type="LOGENTRY"> <title><![CDATA[Sample title]]></title> <program>105</program> <logbook>tlog</logbook> <log_user>rdh</log_user> </log_entry>

log_entry tag

The log_entry tag encapsulates the other E-log entry XML tags. The type must be specified: "LOGENTRY" is currently the only supported type.

title

The title tag is used to specify a title used for identification of an E-log entry. It may contain up to 255 characters.

program

The program tag identifies the source of an E-log entry. For E-log entry XML files generated from a VAX/VMS program the contents of this tag should be 104. For files generated from a UNIX program the contents of this tag should be 105. For files generated by a user through a GUI interface the contents of this tag should be 152. For files generated through the MCC Tk interface the contents of this tag should be 153. The first two tag values (104 and 105) are associated with "auto" entries when filtering using the "Source" pull-down menu on the main E-log web page. The last two tag values (152 and 153) are associated with "user" entries when filtering using the "Source" pull-down menu.

logbook

A logbook tag specifies a logbook name where the E-log entry will be inserted. There may be more than one logbook tag in an E-log entry XML file when it is desired to insert the E-log entry into more than one logbook (one tag per logbook name). Currently the contents of a logbook tag may be one of the following:
  1. accelerator
  2. pep
  3. mcc
  4. nlcta
  5. 8-pack
  6. rf
  7. bic
  8. spps
  9. sw_log
  10. tlog

log_user

A log_user tag specifies the Unix username of the name of a person to be associated with the log entry. There may be more than one log_user tag per E-log entry XML file (one tag per username). The first log_user tag in the XML file specifies the primary person associated with the log entry. This person must be authorized to make entries into each of the specified logbooks (the user access control list is in an Oracle table). Each specified username must be in an Oracle table containing the list of authorized E-log users that are allowed to make entries.

Optional XML tags

The following XML tags are optional in an E-log entry XML file:

  1. text
  2. priority
  3. notify
  4. attachment
  5. reference
  6. timestamp
  7. hostname
  8. os_user
  9. program_name
  10. segment

text

Although optional, the vast majority of E-log entry XML files will have a text tag. The text tag contents describe the E-log entry. There is virtually no limit to the number of characters that may be contained within the tag. However, no line may contain more than 132 characters. If the contents is entered through a GUI text widget, the wrap mode is useful to break lines between words and ensure that lines are no longer than a specified limit.

A type field containing the value "text/plain" (as shown in the example below) must be specified.

An example:

    <text type="text/plain"><![CDATA[Sample text.]]></text>

priority

The priority tag may contain one of two possible values: NORMAL or VIP. The value VIP is for E-log entries that are considered to be high importance. The title of such entries will appear in red when viewing them with a browser. If a priority tag is not present, the default priority of an E-log entry is NORMAL.

An example:

    <priority>VIP</priority>

notify

A notify tag contains an email address. The contents of the E-log entry will be sent to this email address after the entry is processed. If the email should be sent to someone at SLAC, the email address suffix ("@slac.stanford.edu") may be omitted. There may be more than one notify tag in an E-log entry XML file (one tag per email address).

An example:

    <notify>rdh</notify>

attachment

An attachment tag contains the name (title), type, and filename of a graphics attachment file. The name field provides a title displayed above the attachment graphics in an E-log entry. The type field describes the type of attachment file. The following are the supported values for the type field, corresponding to the graphics attachment file types supported (as described in the "Attachment file names" section above):
  1. image/png
  2. image/gif
  3. image/jpeg
  4. application/postscript
  5. application/pdf
The filename specifies the filename of an attachment file, whose naming convention conforms to the rules specified in the "Attachment file names" section above.

There may be more than one attachment tag in an E-log entry XML file (one tag per attachment file).

An example:

    <attachment name="Figure 1" type="image/png">20030924_142859_15620.attach_1.png</attachment>

reference

A reference tag contains the E-log identification number of an E-log entry to which the current entry is a follow-up. There may be more than one reference tag in an E-log entry XML file (one tag per reference number).

An example:

    <reference>1067</reference>

timestamp

The timestamp tag contains a program timestamp for E-log entries generated by a program. It is in yyyy/mm/dd hh:mm:ss format. If present it may be displayed when the E-log entry is viewed by a browser. The timestamp tag does not specify the primary timestamp. The primary timestamp for program generated E-log entries is the time the XML file was processed.

An example:

    <timestamp>2003/10/23 17:15:16</timestamp>

hostname

The hostname tag contains the name of the machine on which the E-log entry XML file was generated.

An example:

    <hostname>mccelog</hostname>

os_user

The os_user tag contains the username which generated the E-log entry XML file.

An example:

    <os_user>cddev</os_user>

program_name

The program_name tag contains the name of the program which generated the E-log entry XML file.

An example:

    <program_name>Channel Archiver</program_name>

segment

A segment tag contains the name of a SLAC area. A segment tag may contain one of the following values:
  1. INJECTOR
  2. DAMPING_RINGS
  3. LINAC
  4. POSITRON_SRC
  5. BSY
  6. HER
  7. LER
  8. COLLISIONS
  9. INJECTION
  10. BACKGROUNDS

There may be more than one segment tag per E-log entry XML file (one tag per area name).

An example:

    <segment>INJECTOR</segment>