Quick Guide to CAM Blueprints

1. Quick Guide to CAM Blueprints Using blueprints to develop XML exchange templates and schema Author: David RR Webber Chair OASIS CAM TC January, 2010 http://www.oasis-open.org/committees/cam (CAM – Content Assembly Mechanism Specification)

2. Agenda • Blueprints and Dictionaries • Exchange Assembly Process Steps Overview • Leveraging re-use – canonical XML dictionaries • Introducing Exchange Assembly Blueprints • Modelling information structures in XML • Using namespaces and prefixes • Constructing your Blueprint templates • Running the Expander • Finishing your Exchange Template • Generating Exchange Artifacts • NDR evaluation, Exchange schema, mapping crosswalk, XML instances, realistic data use, business rules documentation • Summary

3. Business Modelling Charter Requirements Work Group CAM Enabled Import XSD Import EDM Naming / NDR / spell check Search tools Desktop Web based Blueprints Dictionary Generate Dictionary Excel Dictionary Completed Exchange Structures NDR Evalu- ation Rules Report XML examples XSD schemas Validation Engine Subset Schema Crosswalk Test Cases Mapping Spreadsheet Rendering Stylesheet Exchange Assembly Process Overview 1 Project Inception Dictionary Generation / Selection Model Exchange 2 Exchange Content Modelling 3 Expand, Review, Refine Expand and Evaluate Results dictionaries 4 Review / Tailor Exchange Structures Completed Exchange artifacts Test Examples and Rules 5 Schema Generation Generate Package Artifacts and Test them XSD Schema Writer Cross Reference Mapping 6 Package Exchange

4. Leveraging Re-use :Canonical XML Dictionaries What is a canonical dictionary How do I obtain one How do I use it with CAM?

5. Canonical XML dictionary • A collection of distinct components that represent discreet business information entities for an application domain • Includes singleton components and combinations of related components together as sub-assemblies • Entities are represented in a simple neutral conceptual data format that captures the critical concepts about the entity e.g. name, description, content type, usage pattern, hierarchy • Wikipedia definition: http://en.wikipedia.org/wiki/Canonical#Computer_science

6. Available XML Dictionaries LEXS 3.1.4 dictionary OASIS EDXL dictionary OASIS EML dictionary NIEM 2.1 dictionaries CBRN dictionary Emergency dictionary Family dictionary Immigration dictionary Infrastructure dictionary Intelligence dictionary Justice dictionary Maritime dictionary Screening dictionary Trade dictionary NIEM core dictionary Immigration blueprint • Packaged with CAM editor see dictionary folder of install + spreadsheet + blueprint samples XML XML XML Available from download site direct link: http://sourceforge.net/projects/camprocessor/files + includes spreadsheets and sample blueprint XML XML XML XML XML XML

7. Viewing Dictionary in Excel Item names Parent item indicator List of Child items Drag and Drop XML dictionary format into Microsoft Excel Child item indicator Item Properties Unique ID

8. Creating your own Dictionaries • The CAM toolkit includes dictionary generation tools • can harvest components from existing exchange schema • will import model components from ERwin modelling tool • can ingest and use subset schema or component schema • The list is sequenced from easiest to most work to do • A separate companion Quick Guide describes the dictionary creation processes and tools • Look for existing dictionary packs from Sourceforge files location of CAM download http://www.sourceforge.net/projects/camprocessor/files

9. Using Dictionaries • Dictionary components can be referenced individually or as collections by an assembly blueprint that puts them all together to create a complete information exchange • Components can be selected from multiple dictionaries • A control file configures which physical dictionary files to reference and associates one or more particular namespace prefixes with each dictionary

10. Introducing Exchange Assembly Blueprints What is a blueprint template Example blueprints Blueprint tools overview How do I create a blueprint? How do I use it with CAM?

11. Introducing Blueprints • A blueprint is the outline of your information exchange and the top level sets of components needed • Allows rapid iterative exchange structure design • Start with a basic idea of what is needed, extend and refine as you clarify groups of components and their relationships • Can import components from one or more domain dictionary collections • Allows you to focus on the conceptual and hierarchical information model components and their purpose • The low level specific information details will be filled in for you by the expander tool • Review results and add local extensions / exclusions as needed • Blueprints themselves also have high re-use value • Can be sub-assemblies and patterns not just exchange models

12. Example Blueprints • LEXS messaging blueprint Reusable messaging envelope constructs • OASIS EDXL HAVE message Business functional components Message handling, delivery and control Individual component Payload goes here Top level sets of business information components

13. Component Definitions Component Definitions Blueprint Tools Overview Excel Domain dictionary Web tool 1 Blueprint Designer Industry dictionary 2 Search Tools Expander Tool 3 Insert Dictionary Parent Components 4 5 Completed Exchange Template

14. How do I create a blueprint? • Use CAM Eclipse visual editor • create basic blueprint from scratch or from XML instance • Clone and edit an existing blueprint • use a XML editor to manipulate raw XML of blueprint (e.g. search and replace namespace details) • modify blueprint using CAM Eclipse visual editor • Beware of namespaces! • You need to pre-declare namespaces in the blueprint – that may appear later in the finished expanded exchange • Use CAM Eclipse visual editor root node menu to add namespace definitions • Use your XML editor to cut and paste namespaces into blueprint directly

15. Blueprint Structure Overview

16. Adding Components from a Dictionary • Understanding the 4 basic types of component referencing available • Direct component (BBIE) • Direct collection (ABIE) • Indirect type • Indirect sub-component • Control of the XML structure hierarchy • Grouping collections of components • Extending an existing component • Building new extension from existing components • Namespaces – when to use them

17. Using Your Blueprints • What you need - • CAM Eclipse visual editor • Blueprint template • Dictionary or dictionaries of components • Dictionary control file • Contains linkage of namespace prefix to each dictionary • Contains physical filename path of each dictionary

18. Running Blueprint Expander Using Expander tool dialogue Reviewing results Hints and Tips

19. Running Blueprint Expander

20. Blueprint Expander Example COMPLETED EXCHANGE TEMPLATE 2 Expander Tool Structure Details Expanded 1 Dictionary Lookups Exchange components outline 3 EXCHANGE BLUEPRINT Blueprint follows model Console Log detail

21. Completing the Exchange Template Leveraging re-use – dictionaries from industry standards Creating your own domain dictionary from XSD or UML Constructing your exchange and blueprints

22. Exchange Template Editor Exchange Structure items 2 1 Rules for each item Can add new custom domain Items 3 Domain Components Namespaces 4

23. Generating Exchange Artifacts NDR evaluation, crosswalk mapping, Exchange Schema, Subset schema, XML instances, business rules documentation

24. Exchange Generation Steps Structure Rules CAM Template Documentation EXCHANGE TEMPLATE Toolkit for exchange artifacts generation • Run template Evaluation Report • Compare to industry dictionary - create mapping spreadsheet - create crosswalk xml Generate business rules report • Generate exchange XSD schema • Generate XML test instance(s) 1 2 3 Suite of menu options and tools in desktop CAM toolkit editor (each run custom xslt scripts on the exchange CAM template xml) 4 5

25. NDR Evaluation Report • Provides scoring, alerts, warnings and potential issues including: • Naming and content model conventions • Naming and restriction consistency checks • Interoperability enablers/inhibitors checks • Rules integrity and duplicates • Statistics on exchange size • Spell checking on component names

26. Evaluation Report (NDR) example Part of an example report for LEXS getDataItemRequest template displayed in toolkit HTML viewer

27. Compare to industry dictionary • References industry dictionary of names and properties • Matches on physical names • Reports mapping details • Compatible with Microsoft Excel • Report can be used to do spell checking • Generates crosswalk xml file

28. Example cross-reference spreadsheet Formatted view in Microsoft Excel of import of cross-reference report details (from generated XML file)

29. Generate Documentation and Schema • Documentation: • Create HTML report of exchange schema details and associated content and business rules • Report layout and content designed to be reviewed by business analysts • Schema: • Generate XSD schema for exchange • Customizable exchange folder layout management by namespace for extension, subset and exchange schema components • Writes XSD schema in syntax that is clear, simple and compatible with deployment tooling environments

30. Business Rules Documentation Part of the example rules for LEXS getDataItemRequest template displayed in toolkit HTML viewer

31. Export Exchange to XSD Schema Export Template to Exchange XSD: Completed Exchange Structure Set Exchange Options Complete set of exchange schemas generated

32. Exchange Schema Generated Each namespace file is import for those specific type definitions Set of XSD files with filename and namespace suffix Reviewing XSD results in a schema editor tool

33. XML Testing Examples Generation • Support for software development testing process • Designed to allow creation of concrete realistic examples not just random value based • Hinting system allows insertion of actual test system values into XML examples • Can create both valid and invalid examples to support unit testing of application software • Exclude capability allows generator to create examples that contain only a portion of the entire exchange • Control over random seed value used allows re-generation of identical test cases

34. XML example generation wizard View of CAM toolkit with LEXS getDataItemRequest and dialogue for XML test example generator tool

35. Running validation rules tests • Built-in CAM validation engine allows testing of XML instances against actual exchange rules (CAMV). • Critical to ensure that the exchange validates actual live production example scenarios correctly • Allows deployed solution to match exchange schema details • Errors can be reviewed interactively in exchange visual interface • Post-processing of validation results allows unit regression tests to be created with reporting of errors, warnings and information level notes

36. Run Exchange Template Pick XML test case to validate Run validation Review results in visual editor

37. Example Exchange Packaging Details

38. Summary Dictionary driven exchanges Blueprint enabled reuse Automated exchange package generation Alignment to NDR Principles and Rules Testing and validation support

39. Review • Top Down development • Reference dictionary components • Create exchange blueprint • Run Expander tool • Refine desired structure in visual editor • NDR Principles and Rules • Best practices for interoperability and schema techniques • Dictionary driven reuse • Enterprise Data Model and industry components • Ensures consistency of definition and use • Automated exchange package generation • Schemas, XML, documentation, mapping crosswalk • Test generated example XML with rules validation

40. Reference Materials References and Links

41. Links and Resources • DOWNLOADS - • CAM Toolkit download • https://sourceforge.net/projects/camprocessor • SUPPORTING MATERIALS - • NIEM Naming and Design Rules (NDR) 1.3 • http://www.niem.gov/pdf/NIEM-NDR-1-3.pdf • RESOURCES – • Additional support slides (following)

42. Static Conventional Models, Artefacts, Code WSDL,XSD,UML,XML Blueprint Driven Approach Data models Excel spreadsheet Blueprint Templates XML visualization XML artifacts XSD schema Agile Dynamic Components TEMPLATES BUSINESS USERS Needs Requirements Procurement Implementation /Use Dynamic Installation Adoption, integration Coding Maintenance Test Design Specification Analysis Software code Compilers Deployment servers XSD schema XML artifacts SW DEVELOPERS

43. Technology Targeting • Syntax specific production rules 4 XML 2 • Domain Dictionary Details Stored 1 • Wizard • runtime configuration • Template 3 • design time • Exchange Interface / Blueprints • Visual editor + review / test / completion steps 5 • Library • Object templates/Components XML XML XML XML • Facets • Questions / Data • Solution Specific Syntax

44. Domain Exchange Development Steps • Adopt formal Naming and Design Rules (NDR) • UN/CEFACT – NDR • OASIS UBL – Universal Business Language • OASIS EML – Election Markup Language • NIEM – National Information Exchange Model approach (http://www.niem.gov) • OASIS EM - Emergency Management joint initiative with NIEM • Develop data models of core components for use in exchanges • Build Dictionary of Core Components • Provide Principles and Rules guidance to schema team • Use namespaces, Yes / No? • Camel case naming convention? • Schema constructs and restrictions on use? • Information Exchange Package Documentation (IEPD) • Describes formal exchange that conforms to NDR and principles and rules • Provides schema, example XML, supporting artifacts • Re-uses core components • Defines domain specific components

45. Example Governance Structure

46. OASIS Content Assembly Mechanism (CAM) & Integration Technologies Guide W3C XSD Schema Ontology Classification Discovery Machine Based Reasoning Shared Semantics Registry OASIS CAM Templates Domain Dictionaries NDR - WHEN? • Alerts • Process control • Workflow • Automated interfacing • Business Intelligence - WHERE? • Domain classification systems • Ontology and reasoning definitions • Associations and linkages • Search and drilldown • Modelling tools • HOW? WHY? • Provides actual use patterns (templates) • Supports context handling and rules • Rendering outputs and documentation for verification • Enables integration testing / certification • Versioning - WHERE? • Shared resources of semantic definitions • Code lists • Dynamic rendering • Distributed versioning control • Role and access security management • WHAT? • Provides lexicon of information content • Describes structure constructs • Arranges groups of information • Simple content typing • Software tooling interfaces - WHO? • - Alignment of meaning and terms • - Consistent domain definitions • Modelling methods and practice • Business information content building blocks