Scarab XML Format

Scarab has the ability to support multiple issue types, each with its own set of attributes, representing data and user associations with issues. Because each issue type can be different in structure, the Scarab team elected to use a ?reflective? XML structure, using the Apache Jakarta Commons Betwixt engine. Betwixt is a ?bean serializer?, which can turn Java objects into XML and vice-versa based on property accessor naming conventions. While making the XML somewhat more verbose, the XML is consistent in general layout between issue types.

Overall Model

In the XML, you have the following tree:

  • There is an <issues> element containing a series of <issue> elements. On export, there is on <issue> element per exported issue. On import, there should be one <issue> element per issue you wish to insert or update.
  • Each issue contains <activity-sets>, containing one or more <activity-set> elements. An activity set represents a set of actions applied at one time. You can think of an <activity-set> as representing one operation using the Scarab Web forms for editing an issue.
  • Each activity set contains <activities>, containing one or more <activity> elements. Each activity represents a change to a single attribute of the issue, whether that attribute be a regular data attribute, a user attribute, an attached file, etc.

From the Scarab issue import FAQ:

You'd start a new activity-set when:

  1. Importing an issue and its initial state.
  2. Adding physical attachments to an issue.
  3. Adding comments to an issue (Scarab treats attachments and comments as roughly equivalent).
  4. Adding an activity entry: e.g., one or more state changes such as 'Changed from NEW to STARTED', or issue dependencies.

Annotated XPath Roster

The safest way to deal with issues in your site is to do an XML export (perhaps manually first, before you get into automation), and use it as the basis for developing the XML blobs for imports, etc.

The following table documents each of the discrete bits of information stored in the XML. Use this table to support the analysis of your own issue types? XML, so you can understand how the XML is assembled.

Where an ellipsis (...) is shown in the XPath, that is shorthand for /scarab-issues/issues/issue/activity-sets/activity-set. Where a double ellipsis (.../...) is shown, that is shorthand for /scarab-issues/issues/issue/activity-sets/activity-set/activities/activity.

XPathDescriptionSample Value

/scarab-issues/import-type

Should be create-different-db for an insert and create-same-db for an update

create-different-db

/scarab-issues/module/name

Name of Scarab module into which this issue should go

training

/scarab-issues/module/domain

Domain name of Scarab site into which this issue should go

scdemo.net

/scarab-issues/module/code

Issue prefix used by the Scarab module for this issue

TRN

/scarab-issues/issues/issue/id

Numeric portion of ID for this issue (i.e., without the code prefix). Found on exported issues and issue update import XML.

1

/scarab-issues/issues/issue/artifact-type

Name of artifact type this issue is formatted in

Issue Tracker artifact

.../type

Should be Create Issue for the first activity-set for an issue insert. All others should be Edit Issue.

Create Issue

.../created-by

User ID of person who did these activities

mmurphy

.../created-date/format

Format used for the created-date/timestamp element. ?yyyy-MM-dd HH:mm:ss z? is known to work.

yyyy-MM-dd HH:mm:ss z

.../created-date/timestamp

Timestamp of when this activity-set occurred. This timestamp will be used in issue imports, not the actual time the import occurred.

2003-03-22 10:01:46 PST

.../.../attribute

Name of the attribute being set or modified.

Component

.../.../new-option

Sets the value for a drop-down data attribute. Also set the value using new-value.

Component 1

.../.../new-value

Sets the value for any data attribute.

Component 1

.../.../new-user

Sets the new user ID for a user attribute. Also set the value using new-value.

mmurphy

.../.../description

Explains the nature of the change to this attribute. With system-generated descriptions being boilerplate, you might consider a different structure to highlight changes made in an import operation (e.g., ?Imported new value?)

Component set to 'Component 1'

.../.../attachment/name

For comments, should be ?comment?. For attached files/URLs, should be the natural language label for the attachment.

Yahoo! home page

.../.../attachment/type

One of: COMMENT, URL, ATTACHMENT (latter for attached files)

ATTACHMENT

.../.../attachment/data

For comments, the text of the comment. For attached URLs, the URL itself. For attached files, the name of the attached file.

http://www.yahoo.com

.../.../attachment/mimetype

MIME type to use for the attached data. Use text/plain for comments and URLs

text/plain

.../.../attachment/created-date/format

Format used for the created-date/timestamp element. ?yyyy-MM-dd HH:mm:ss z? is known to work.

yyyy-MM-dd HH:mm:ss z

.../.../attachment/created-date/timestamp

Timestamp of when this attachment was attached. This timestamp will be used in issue imports, not the actual time the import occurred.

2003-03-22 10:01:46 PST

.../.../attachment/modified-date/format

Format used for the modified-date/timestamp element. ?yyyy-MM-dd HH:mm:ss z? is known to work.

yyyy-MM-dd HH:mm:ss z

.../.../attachment/modified-date/timestamp

Timestamp of when this attachment was last modified. This timestamp will be used in issue imports, not the actual time the import occurred.

2003-03-22 10:01:46 PST

.../.../attachment/created-by

User ID of person who attached the attachment

mmurphy

.../.../attachment/deleted

false, indicating that this has not been deleted

false