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
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 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 4
How it works in a nutshell CAM Template Exchange Definition Structure XSLT XSLT tools tools process process template template 2 Samples build examples & test cases Rules 1 3 Documentation - (Excel / HTML) Generate 4 Collaboration - components dictionary checklist 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 4 Select Event Date add date mask constraint rule 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 This example is for a XML that makes heavy use of namespaces (not the tickets XML) 8 Select element node in structure; right mouse click for context menu; select Add Child Attribute / Element ; then enter prefix and name 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 HTML Report Pages XSLT script customizable 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 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. Optional content hints (explained next ) Optional schema file validation link; use this to have example validate with schema or sub-set schema 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 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 Review validation results 2 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 1 Enter values terminated with character 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 1 Confirm the location and filename, and namespace mode. 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 Tickets information model output in XSD schema syntax 3 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 1 2 3 XML Schema Documentation (Word / PDF / OpenDoc Excel / HTML) Dictionary (XML / Excel) 4 Examples & Test Cases 5 CAM Template Structure Rules Context Vocabulary Dictionary Templates slide 42
Partner Conformance Testing Publish XML Structure Rules Context Examples Documentation Dictionary 1 Package 2 Report Templates Results Validate Test Cases Test Testing, Agreement / Alignment. Partner Uses & Creates 3 XML Localization Content Hints Verify Result Outcomes html 4 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 <nxnl:first_name> 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 update list values 3 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 - AND Triage Quantity > 5 Require Facility State = CA, NV, NM When Admissions Total > 50 - AND Deaths > 0 Outbreak alerting Facility Matching Region Restriction slide 52
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 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 - Martin Roberts and team from BTplc US - Michael Sorens for review and testing slide 59