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:
- elog_accl
- elog_pep
- elog_mcc
- elog_nlcta
- elog_pack
- elog_rf
- elog_bic
- elog_spps
- elog_swlog
- 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:
- png
- gif
- jpeg
- ps
- 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:
105
tlog
rdh
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:
- accelerator
- pep
- mcc
- nlcta
- 8-pack
- rf
- bic
- spps
- sw_log
- 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:
- text
- priority
- notify
- attachment
- reference
- timestamp
- hostname
- os_user
- program_name
- 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:
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:
VIP
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:
rdh
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):
- image/png
- image/gif
- image/jpeg
- application/postscript
- 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:
20030924_142859_15620.attach_1.png
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:
1067
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:
2003/10/23 17:15:16
hostname
The hostname tag contains the name of the machine on which the E-log
entry XML file was generated.
An example:
mccelog
os_user
The os_user tag contains the username which generated the E-log entry
XML file.
An example:
cddev
program_name
The program_name tag contains the name of the program which generated the
E-log entry XML file.
An example:
Channel Archiver
segment
A segment tag contains the name of a SLAC area. A segment tag may contain
one of the following values:
- INJECTOR
- DAMPING_RINGS
- LINAC
- POSITRON_SRC
- BSY
- HER
- LER
- COLLISIONS
- INJECTION
- BACKGROUNDS
There may be more than one segment tag per E-log entry XML file (one tag
per area name).
An example:
INJECTOR