Quick CAM Tutorial

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

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 2

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 3

Approach


Iteratively build the content assembly    




Complete the exchange package    




Create a base XML structure Add your rules and constraints Generate some working examples Refine with hints, documentation and extensions Documentation Test cases Generate XSD schema Dictionary

Advanced features  International code lists  Extended content handling rules  Wiki output slide 4

How it works in a nutshell Exchange Definition

CAM Template

Structure XSLT XSLTtools tools process process template template

Rules

2

Samples – build examples & test cases

3

Documentation (Excel / HTML)

4

Collaboration components dictionary checklist

1 Generate Generate

Documentation

5

Programming exchange XSD schema

XSD CAM = Content Assembly Mechanism

slide 5

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 slide 6

Tutorial – Step 1

Introducing the XML Tickets Example Creating the base template

Tickets XML

slide 8

Load in XML and save results template 1 Select template from XML option

2

Load completed, Save template

slide 9

Tutorial – Step 2

Select and detail model Add use pattern rules Refine content model Template Validator

Reviewing and Enhancing Model Completed template is shown in the structure navigator panel for review and editing

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.

slide 11

Add use pattern rules Select and assign use pattern rules as needed

3

Each component in the model may be optional, required or repeatable. Each of these rules can be quickly assigned accordingly.

slide 12

Adding content type constraint rules Select Event Date – add date mask constraint rule

4 XPath target automatically made by wizard Pick desired date format details – MM/DD/YYYY

slide 13

Restrict ZIP code to 5 digits Select Event Zip – add number mask constraint rule

5 XPath target automatically made by wizard Pick desired number format details

slide 14

Limit State code values Select Event State – add restrictValues() constraint rule

6 XPath target automatically made by wizard Add desired values

slide 15

Adding New Domain Elements 7 Select root element node in structure; right mouse click for context menu; select “Add Namespace”; then enter prefix and URI

8

Select element node in structure; right mouse click for context menu; select “Add Child Attribute / Element”; then enter prefix and name

This example is for a XML that makes heavy use of namespaces (not the tickets XML)

slide 16

Run Template Validator – checks for errors • •

This option runs an analysis of your template and reports potential problems that it finds Also shows useful statistics about your template

Tools Menu Option

slide 17

Tutorial – Step 3

Add annotation notes Generate documentation Inspect and verify

Adding annotation notes

Select focus on structure item; invoke action menu (right mouse click)

1 3

Enter text into Definition tab

2 Choose “Edit Annotations”

slide 19

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 20

Tabular Documentation Documentation Menu Option Select Format, resulting HTML opens in browser viewer

slide 21

Tabular HTML Content Details Clear use pattern

Extended Code list handling Annotations

XPath references and functions

Enhanced Data type Logic slide 22

Open Documentation Mechanism CAM Template XML (CXF)

Documentation Generator XSLT script






customizable

HTML Report Pages

CSS style sheet

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 slide 23

Tutorial – Step 4

Generate test data examples Run validation checker Add content hints

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 25

Test Case Results

Active links to view the generated examples

slide 26

Advanced Generation Options 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)

Use namespaces or not; if ‘false’ is selected – then XML instances are created with minimized namespace usage.

How to handle optional items: all | random | none If you want deliberate errors for fail testing; (will give variety of data and structure errors)

Optional content hints (explained next )

Use slider to pick a specific seed value – or leave blank for random seed slide 27

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 28

Run Validation Checker on Examples Run Menu Option / JCAM validation engine

1 Pick Test Case Example to VALIDATE; click Finish to run validation rules

2

Review validation results

3

slide 29

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 30

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 31

Then add Value annotation item 3

Select “Value” tab

2 4 Enter values terminated with “|” character

1

Click on “Add New”, then enter “Value” as Type and confirm “OK”

5

Re-run Example export to see results

slide 32

Tutorial – Step 5

Output programmer XSD schema

Generating XSD schema File Menu Option Select Export CAM as XSD menu option

Confirm the location and filename, and namespace mode.

1

2

Select ‘false’ for namespace use will minimize the use and requirement for namespaces in the subset schema and corresponding XML instance documents. slide 34

Schema XSD generated Set 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

slide 35

Tutorial – Step 6

Build component dictionary Load as Excel spreadsheet

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 37

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 38

Open Dictionary as Spreadsheet

slide 39

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

slide 40

Tutorial – Step 7

Package and Share Conformance Testing

Package Contents Review XML Schema

1

5




2

Documentation (Word / PDF / OpenDoc Excel / HTML)




3

Dictionary




4

Examples & Test Cases

(XML / Excel)

CAM Template

Structure Rules Context Vocabulary Dictionary




Templates slide 42

Partner Conformance Testing Publish

Structure Rules Context Examples Documentation Dictionary

XML Templates Package

Test Cases

2

3

1 Validate

Report html

4

XML

Test

Localization Content Hints

Testing, Agreement / Alignment.

Results

Verify Result Outcomes

Partner Uses & Creates

XML Pass / Fail slide 43

Summary

Review of capabilities

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 slide 45

Advanced Features

Using Hints file mechanisms Using Code Lists lookup Using Extended Rules

Hints File Mechanism (XML file) 1

like / with partial name matching use for component match on items – e.g. first with name matches

2

key matching on tag name use for exact match of items

3

key / parent path matching use when same name occurs within different parents – e.g. Country and Person / NameElement with different content and context

Note: matching is case sensitive but ignores namespaces TIP: can use Export Hints to create initial XML file for editing

slide 47

A- Using Examples Generator with Hints

Select XML hints file to be used here slide 48

B- Import Hints into Annotations (merge)

set and select as needed Option to autoreload new anno file into current template slide 49

External Code list lookup Access External Lists tool

1

Import or Create New code list

2

Review, filter or 3 update list values

4

Add lookup() action to structure item and reference code list name

slide 50

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 51

Illustrative EDXL requirements


When AdultICU Bed type > 0 Facility Matching - AND Triage Quantity > 5




Require Facility State = CA, NV, NM Region Restriction




When Admissions Total > 50 - AND Deaths > 0 Outbreak alerting

slide 52

Template rules syntax



slide 53

XPath selector wizard XPath syntax is automatically generated for you

Check boxes allow user to select scope of rule action Conditional context rules can be optionally used

Documentation notes can be added here

slide 54

Resources / Software

Selection of useful links and additional technical details

Resources: 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

slide 56

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 57

“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 58

Credits: A special mention for our contributors to the CAM and jCAM work: UK US

-

Martin Roberts and team from BTplc Michael Sorens for review and testing

slide 59