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: drrwebber@acm.org

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: