Quick CAM tutorial - OASIS · PDF fileTutorial -Making your ... Produce spreadsheet workbooks....
Transcript of Quick CAM tutorial - OASIS · PDF fileTutorial -Making your ... Produce spreadsheet workbooks....
Quick XML Content Exchange
Tutorial
- Making your exchange structure
- Creating template and rules
- Exporting test examples
- Documentation, schema and more
- Advanced features
David RR Webber
Chair OASIS CAM TC
(Content Assembly Mechanism)
E-mail: [email protected]
http://wiki.oasis-open.org/cam
slide 2
Overview
� Aim is to show how to quickly put together a content assembly package for an information exchange using XML
� Build all the pieces needed to manage, document and validate your information
� Cool stuff and tips on making your exchange successful
� Summary and Resources
(Note: this is NOT the XSD schema tutorial – if you want that one go here:
http://www.oasis-open.org/committees/download.php/30607/XSD%20and%20jCAM%20tutorial.pdf )
slide 3
Use Case
� Inauguration tickets exchange� XML structure for ticket availability, location and price
� Allows websites to pull latest details in XML, or post new ticket and
event details
� How to develop a CAM template for ticket
exchanges
� Open sourced world is facilitated when
people collaborate using common
mechanisms and definitions
slide 4
Approach
� Iteratively build the content assembly� Create a base XML structure
� Add your rules and constraints
� Generate some working examples
� Refine with hints, documentation and extensions
� Complete the exchange package� Documentation
� Test cases
� Generate XSD schema
� Dictionary
� Advanced features� International code lists
� Extended content handling rules
� Wiki output
slide 5
How it works in a nutshell
GenerateGenerate
Structure
Rules
Documentation
XSLT toolsprocesstemplate
XSLT toolsprocesstemplate
CAM = Content Assembly Mechanism
Exchange DefinitionCAM Template
1
2
Documentation -
(Excel / HTML)
Collaboration -
components
dictionary
checklist
Samples –
build
examples &
test cases
Programming -
exchange
XSD schema
XSD
3
4
5
slide 6
7 Steps to Success!
� Step 1 – Create XML layout of content
� Step 2 - Select & detail your use model in visual
editor
� Step 3 - Generate your documentation for
structure elements and rules
� Step 4 - Generate test data examples and
check with validator
� Step 5 – Output the programmer XSD schema
� Step 6 – Build dictionary of core components
� Step 7 - Package and share with community
Tutorial – Step 1
Introducing the XML
Tickets Example
Creating the base template
slide 8
Tickets XML
slide 9
Load in XML and save results template
1
Select template from XML option
2
Load completed,
Save template
Tutorial – Step 2
Select and detail model
Add use pattern rules
Refine content model
Template Validator
slide 11
Reviewing and Enhancing Model
1
Select duplicate item(s)
2
Open pop-up menu (right click)
Select Delete item action
Template contains all the
default content model
and structure rules
loaded from the XML.
You can now proceed to
clean up and refine the
model – deleting
redundant items, then
adding new items as
desired.
Completed template is shown
in the structure navigator panel
for review and editing
slide 12
Add use pattern rules
3
Select and assign use pattern
rules as needed
Each component in the
model may be optional,
required or repeatable.
Each of these rules can
be quickly assigned
accordingly.
slide 13
Adding content type constraint rules
Select Event Date – add date
mask constraint rule
XPath target
automatically made by
wizard
Pick desired date format
details – MM/DD/YYYY
4
slide 14
Restrict ZIP code to 5 digits
Select Event Zip – add
number mask constraint
rule
XPath target
automatically
made by wizard
Pick desired
number
format details
5
slide 15
Limit State code values
Select Event State – add
restrictValues()
constraint rule
XPath target
automatically
made by wizard
Add desired values
6
slide 16
Adding New Domain Elements
Select root element node in
structure; right mouse click for
context menu; select “Add
Namespace”;
then enter prefix and URI
7
Select element node in
structure; right mouse click for
context menu; select “Add
Child Attribute / Element”;
then enter prefix and name
8
This example is for a
XML that makes heavy
use of namespaces (not
the tickets XML)
slide 17
Run Template Validator – checks for errors
Tools Menu Option
• This option runs an analysis of your template and
reports potential problems that it finds
• Also shows useful statistics about your template
Tutorial – Step 3
Add annotation notes
Generate documentation
Inspect and verify
slide 19
Adding annotation notes
Select focus on structure
item; invoke action menu
(right mouse click)
1
2
3
Choose “Edit Annotations”
Enter text into Definition tab
slide 20
Documentation Layouts
� Layout options� Source XML
� Component details (XML)
� Tabular format (HTML)
� Interactive web page (wiki)
� Tabular format page layout for data analyst
use and designed to make rules and use
patterns clear
� Wiki format for collaborative web use
� Each documentation layout XSLT script can
be customized as desired
slide 21
Tabular DocumentationDocumentation Menu Option
Select Format, resulting
HTML opens in browser
viewer
slide 22
Tabular HTML Content Details
EnhancedData typeLogic
Extended Code listhandling
Clear use pattern
XPath referencesandfunctions
Annotations
slide 23
Open Documentation Mechanism
� Visual editor runs XSLT on template to output
results as HTML document
� External CSS style sheet controls HTML
content formatting, colors, fonts.
� Editor Preferences menu allows overriding of
default documentation style sheets
CAM
Template
XML (CXF)Documentation
Generator
HTML
Report
Pages
CSS
style sheet
XSLT
script customizable
Tutorial – Step 4
Generate test data examples
Run validation checker
Add content hints
slide 25
Test Case Generation Quick Start
File Menu Option Default directory to write examples into
Name to be used for the examples
How many examples to create
Repeating elements count
for Quick Test – just click “OK” to use default settings
slide 26
Test Case Results
Active links to
view the
generated
examples
slide 27
Advanced Generation Options
How to handle optional items: all | random | none
If you want deliberate errors for fail testing; (will give variety of data and structure errors)
Use namespaces or not; if ‘false’ is selected – then
XML instances are created with
minimized namespace
usage.
Optional content hints (explained next )
Use slider to pick a specific seed value – or leave blank for random seed
Optional schema file validation link; use this to have example validate with schema or sub-set schema
Use content type or item name (name is useful for checking backend transform processing)
slide 28
Test Case Generator Feature Summary
� Make both Pass / Fail testing examples
� Content hinting so examples use real not fake data
� Test optional item logic with: all / random / none
� Uses exclude() assertions so does not include those
items – makes realistic examples of your use pattern
� Can pass in seed value – use when adding and testing
hints (each test case is labelled with its seed value)
� Make hundreds of test cases without manual editing
� Can link test case to XSD schema for structure tests
� You can modify XSLT to meet own testing needs
slide 29
Run Validation Checker on Examples
Pick Test Case Example to
VALIDATE; click Finish to run
validation rules
Review validation results
Run Menu Option / JCAM validation engine
1
3
2
slide 30
Content Hinting Mechanisms
� Designed to create realistic data examples
� Hints can be provided in two ways
� SIMPLE (shown next)� using ‘Value’ notes in annotations on specific items in the structure
editor
� ADVANCED (see advanced section)� create your own Hints XML file and add matching rules to apply to
your template(s) – e.g. FirstName, LastName, Address, BirthDate,
etc.
� Can export from one template, import into
another
slide 31
First Approach: annotation Value Hints
Select focus on structure
item
Invoke action menu (right
mouse click)
Choose “Edit Annotations”
[ This example is for
EDXL Hospital Status
reporting (not the
tickets XML) ]
slide 32
Then add Value annotation item
Click on “Add New”, then
enter “Value” as Type and
confirm “OK”
Select “Value” tab
Enter values terminated with “|”
character
1
2
3
4
5 Re-run Example export to see results
Tutorial – Step 5
Output programmer XSD schema
slide 34
Generating XSD schema
Select Export CAM as XSD
menu option
1
File Menu Option
2
Confirm the location and
filename, and namespace
mode.
Select ‘false’ for namespace
use will minimize the use and
requirement for namespaces
in the subset schema and
corresponding XML instance
documents.
slide 35
Schema XSD generatedSet of XSD files with filename and
namespace suffix
Each namespace file is import for
those specific type definitions
Reviewing XSD results in
a schema editor tool
3
Tickets information
model output in
XSD schema syntax
Tutorial – Step 6
Build component dictionary
Load as Excel spreadsheet
slide 37
Dictionary Tools
� Generate a dictionary of components used
by your template
� Merges annotations and type definitions
from template into dictionary
� Separate dictionary content by namespace
� Produce spreadsheet workbooks
slide 38
Create Dictionary
Select Dictionary; empty
for new create, or existing
for merge
Output dictionary
filename
Select template
content
namespace to
match with
Merge mode; use true to
combine content
slide 39
Open Dictionary as Spreadsheet
slide 40
Format, Edit and Save Spreadsheet
� Use spreadsheet tools to format columns as
desired
� Manually review and confirm details
� Make updates and edits as needed
� Save from Excel to XML; update to dictionary
Tutorial – Step 7
Package and Share
Conformance Testing
slide 42
Package Contents Review
Templates
Structure
Rules
Context
Vocabulary
Dictionary
XML Schema
2
1
3
CAM Template
4
Documentation(Word / PDF / OpenDoc
Excel / HTML)
Dictionary(XML / Excel)
Examples &
Test Cases
5
����
����
����
����
slide 43
Partner Conformance Testing
Testing,
Agreement /
Alignment.
Validate
Templates
Report
Partner
Uses &
Creates
Results
Test
Pass / Fail
XMLhtml
32
4
Test Cases
XML
Package
Structure
Rules
Context
Examples
Documentation
Dictionary
Publish
1
Verify Result Outcomes
XML
Localization
Content
Hints
Summary
Review of capabilities
slide 45
Summary
� Capabilities covered� Loading XML structure
� Refining structure and content model rules
� Generating documentation
� Generating test examples
� Hints system
� Generate XSD schema
� Running tests
� Generating component dictionary
� Applicable to board range of domains and schemas
� Enhanced interoperability through consistent
method, testing and shared clear exchange
package definitions
� Enables SOA implementations
Advanced Features
Using Hints file mechanisms
Using Code Lists lookup
Using Extended Rules
slide 47
Hints File Mechanism (XML file)
like / with partial name matching
key matching on tag name
key / parent path matching
use when same name occurs within different parents – e.g. Country and Person / NameElement with different content and context
use for exact match of items
3
2
1
use for component match on items – e.g. first with name matches <nxnl:first_name>
Note: matching is case sensitive but ignores namespaces
TIP: can use Export Hints to create initial XML file for editing
slide 48
A- Using Examples Generator with Hints
Select XML hints file to be used here
slide 49
B- Import Hints into Annotations (merge)
set and select as
needed
Option to auto-
reload new anno
file into current
template
slide 50
External Code list lookupAccess External
Lists tool
Import or Create
New code list
Review, filter or
update list values
Add lookup()
action to structure
item and
reference code list
name
1
2
3
4
slide 51
Advanced Rule Considerations
� The CAM template allows full use of XPath
conditional expressions and a rich set of
over 30 functions including:� setNumberRange(), setLength(), setValue(), setLimit(),
setDateMask(), makeRepeatable(),restrictValues(),excludeTree()
� Those that are compatible with XSD
constraints will cause constraint schema
assertions to be written out when exporting
to schema
� Mapping business functional rules to XPath
constraint rules
slide 52
Illustrative EDXL requirements
� When AdultICU Bed type > 0
- AND Triage Quantity > 5
� Require Facility State = CA, NV, NM
� When Admissions Total > 50- AND Deaths > 0
Outbreak alerting
Facility Matching
Region Restriction
slide 53
Template rules syntax
<as:BusinessUseContext>
<as:Rules>
<as:default>
<as:context>
<as:constraint condition="//Activity24Hr /Admissions > ‘50’
and( // Activity24Hr /Deaths > ‘0’)" action="restrictValues(// Activity24Hr /Admissions, ‘Alert – possible outbreak’) "/>
<as:constraint action="restrictValues(//ns5:AdministrativeArea /ns5:NameElement , 'CA|NV|NM')"/>
</as:context>
</as:default>
</as:Rules>
</as:BusinessUseContext>
slide 54
XPath selector wizard
Check boxes allow user
to select scope of rule
action
Conditional context rules
can be optionally used
Documentation notes
can be added here
XPath syntax is
automatically generated
for you
Resources / Software
Selection of useful links and additional technical details
slide 56
www.jcam.org.uk
wiki.oasis-open.org/cam
www.oasis-open.org/committees/cam
docs.oasis-open.org/cam
www.oasis-open.org/committees/emergency
www.niem.gov
Resources:
slide 57
SourceForge XSLT svn repository
� Using any svn client the XSLT scripts can be
retrieved from:� https://camprocessor.svn.sourceforge.net/svnroot/camprocessor/
camed/uk.org.jcam.camed/trunk/xsl/
slide 58
“CAM Kit” of XSLT tools used
� XSD 2 Schema � expands original target schema resolving imports and includes
� XSD 2 CAM � extracts structure and rules and builds template from schema
� XML 2 Wantlist� builds want list from any XML instance (uses Level Depth setting)
� CAM 2 Examples� Generates a collection of XML instance test cases
� Import/Export Hints� Manage and apply content hinting across CAM templates
� CAM 2 XSD export� Creates a subset XSD from CAM template (applies want list)
� CAM 2 Dictionary� Merge core components into dictionary by namespace
slide 59
A special mention for our contributors to the CAM and jCAM work:
UK - Martin Roberts and team from BTplcUS - Michael Sorens for review and testing
Credits: