|
User's Guide:
CMM Validator Release 1.1
Contents:
- Overview
- Functionality
- User Interface
- Using the Validator
- Selecting Processing Options
- Running the Validator and
Interpreting Output
- Editing a Manifest
- Overview
- 2.3.2) Launching the
Editor
- User Interface
- Saving Changes and
Re-Validating
- Running Scripts
- Functionality
- Writing Command Scripts
- User Interface
1) Overview
1.1) Functionality
The
Validator
is intended to be used during the pre-processing of a Common
Media Manifest (CMM) file. When validating a manifest with this
tool, the user may select what level of validation checks will
be applied. The levels are, in increasing level of rigor:
- Common Media Manifest (CMM):
- At a minimum, all manifests will be checked for
conformance with the CMM Schema (i.e., does the Manifest XML
comply with the schema XSD).
- When the 'Constraints' option is enabled the
manifest will also be checked for conformance with all
additional constraints and requirements that are not
specified via XSD but are identified in the full specification. This includes
checking the internal consistency of the manifest to verify
that all internal references are valid (e.g., if a PictureGroupID
is referenced by an Experience then a PictureGroup
with that ID value is also defined). Checks of external
references (i.e., URLs of content staged on a CDN) are
considered out of scope for the Validator and are not
tested.
- Manifest Information Model: Validates a
Manifest file as conforming to the specified structure (a.k.a.
'model') as defined by a specification's Information Model.
Validation against a Manifest Information Model is only
performed on Manifests that have passed all CMM validation
checks without any errors.
- CMM Profile: A Manifest that has passed the IM
validation stage may also be checked for conformance with a
specific profile. Profile validation requires the
selection of a specific profile (see Step #4 of Selecting Processing Options for
details).
1.2) User Interface
Figure 1: Validator UI
The user interface is shown in Figure 1. From top to bottom, the
main components are:
- Menus providing access to generic capabilities. The
primary one is the "Processing" menu. This allows the user to
select the types of validation checks to be performed and the
level of logging output desired.
- The Manifest Tool Bar, which is used for:
- selection of one or more manifest files to be
validated,
- selection of a Profile the manifest(s) are intended
to support, and
- access to the integrated Manifest Editor.
- The Logging panel used to display and filter the
messages resulting from the validation process
2) Using the Validator
2.1) Selecting Processing
Options
- The first step is to select the types of validation
tests to be performed. This is done via the check boxes in the
Processing/Validation menu (Fig 2).
Figure 2: Validation Criteria Menu
- The next step is to select which CMM files will be
validated. A left-click on the 'Source' text area will
pop open a File Chooser dialog. If a directory is selected, all
manifest files found in the directory will be processed.
Alternatively a single file may be selected. NOTE: if the selected source is a
directory containing multiple CMM files, then all files will
be validated against the same set of options
- Next the user may optionally identify an
Interactivity Profile that the manifest is intended to support.
Note that for a Manifest compliant with CMM V1.5 or later, any
profiles specified are in addition to any Profile
specified in the Manifest file itself.
2.2) Running the Validator
and Interpreting Output
Once all validation options have been set, the validation
process may be executed via the
RUN
button. When the validation process completes, the results will
be displayed in the Logging panel (see Figure 3).
Figure 3: Validation Results
The navigation pane on the left side allows the user to
select a sub-set of messages to be displayed on the right side.
Messages are hierarchically grouped first by the Manifest they
apply to, then by the severity level (i.e., Warning, Error,
etc.), and finally by the type of validation check resulting in
the message (e.g., CPE Model). Icons are used to indicate the
most severe problem found in any branch of the message
hierarchy. For example, Figure 3b shows that only one of the
three manifests that were processed contains errors.
Figure 3b: Severity of Log Messages
The message display pane on the right provides a table
showing all the messages in which ever branch of the message
hierarchy has been selected in the navigation pane. Some log
messages will provide additional information via tool
tips. Where possible, this will include references to specific
sections of the documentation that cover the identified problem.
The displayed log messages may be sorted by means of a left-click
on any of the column headers (to sort by line number click on
the 'Line' column header). Subsequent left-clicks will reverse
the sort order.
By right-clicking on the message display pane, a pop-up
menu may be accessed (see Figure 4). Available actions are:
- show the XML associated with the error in an Editor
window,
- clear the entire contents of the message log, or
- save to a file the currently displayed group of
messages in CSV format
Figure 4: Message Log Pop-up Menu
The saving and/or clearing of the log file are simple
operations and the user interface for both of these is
self-explanatory. Usage of the Editor is covered in detail in
the next section.
2.3) Editing a Manifest
2.3.1) Overview
The CMM Validator includes a built-in XML Editor that may be
used to correct any errors found during the validation process.
Note that this is not intended to provide a full-featured XML
authoring capability similar to those provided by tools such as
XML
Spy or Oxygen-XML. Rather it is focused on
providing an easy-to-use and integrated capability for quickly
correcting errors and then re-running the validation tests.
The Editor UI is implemented as a separate window (see
Figure 5). Multiple Editor windows may be opened at the same
time, with each displaying a different Manifest file. Note,
however, that there may only be one Editor window for any given
file.
Figure 5: Manifest Editor
2.3.2) Launching the
Editor
As described in Section 2..2, an Editor may be launched by the
context menu displayed when the user right-clicks on a log
entry. Selecting the
Show in Editor
item will cause an Editor for the associated file to be
displayed. The location (i.e., line) in the file associated with
the log entry will become the current line and will therefore be
indicated by the line number being highlighted in red. For
example, in Figure 5, the Editor window shown was accessed by
clicking on a log entry linked to line 208 in manifest file
CMM_BBB_v0.1.xml
.
An Editor may also be launched using the button in the tool bar:
.
When an editor is launched for a specific Manifest:
- if an editor window for the Manifest file has not been
previously accessed, a new Editor will be created and
displayed.
- if an editor for the Manifest file already exists but
has been minimized (i.e., iconified) by the user, it will be
opened and brought to the foreground.
- if an editor for the Manifest file already exists, it
will scroll to display the selected line in that file.
- if the log message used to access the editor does not
have a specific location associated with it, or the editor was
launched using the Menu Bar, the current line will be set to
the first line in the Manifest.
2.3.3) User Interface
The Editor window has the following components:
- a text pane which uses colors for syntax highlighting,
- a menu bar providing access to the available editing
functions
- line numbers displayed on the left edge that includes
markers indicating errors and warnings, and
- display of status messages across the bottom of the
editor window.
These are shown in Figure 6.
Figure 6: Editor UI
The status messages are linked to the marker icons
displayed along side the line numbers. A single left or right
click on a marker will result in the associate log entry being
displayed in the status panel.
2.3.4) Saving Changes and
Re-Validating
To save changes, simply use either the pull down menu or the
<Ctrl>S
shortcut. Once the Manifest file has been saved the file may be
re-validated.
The changed manifest may also be saved under a new name using
the
Save As
menu option. If the Manifest is saved under a new name then the
user must explicitly identify the new manifest as the
Validator's
Source
before it can be validated. Also it is important to remember
that the existing Editor window will still be displaying
the original Manifest file. In order to edit the newly saved
file, the user must:
- select the new manifest as the source file to
validate,
- run the validation, and then
- select one of the resulting log messages to open an
Editor window for the new manifest file.
3) Running Scripts
3.1) Functionality
Validation of multiple Manifests may be performed using scripts
that can specify any of same options and settings available thru
the user interface. A script may easily be used to process a set
of manifests with specified sub-sets being handled using
different options. All results are automatically displayed in
the GUI's log display but the script engine supports the option
of also writing the log to a file.
3.2) Writing Command Scripts
A script file is written using the JSON syntax.
The structure for a validation script is as follows:
The following is an example of script that validates two
Manifest files plus any Manifests found in a specific folder
and then saves the message log in an output file:
{
"validate":{
"pathPrefix":"./MediaManifests/",
"checks":{
"contraints":"Y",
"bestPrac":"N"
},
"logging":{
"level":"Warning",
"output":"./scriptLog01.xml"
},
"manifests":[
{
"file":"si_tests/CMM_BBB_v0.1.xml",
"schema":"1.5",
"profile":"DemVal"
},
{
"file":"si_tests/CMM_Sita_v0.1.xml",
"schema":"1.4",
"profile":"none"
},
{
"file":"studio",
"schema":"1.4",
"profile":"IP-1"
}
]
}
}
3.3) User Interface
Selection and execution of a script is via the
Run Script..
menu entry. Once a script file has been selected the execution
is automatic. It is recommended that the contents of the log
display be cleared prior to executing a script. Failure to do
so will result in any previous messages being included in the
saved log file.
Figure 7: Script Selection and
Execution
|