1 Quick Guide to CAM Blueprints Using blueprints to develop XML exchange templates and schema (CAM – Content Assembly Mechanism Specification) Author: David RR Webber Chair OASIS CAM TC January,

2 January, 2010 – CAM Draft Specification Development Related Materials 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 January, 2010 – CAM Draft Specification Development Related Materials Web based Desktop Excel Search tools Exchange Assembly Process Overview Project Inception Project Inception dictionaries Exchange Content Modelling Blueprints Dictionary Expand and Evaluate Results Review / Tailor Exchange Structures Generate Package Artifacts and Test them Generate Package Artifacts and Test them Package Exchange Complete d Exchange Structures NDR Evalu - ation Dictionary Generation / Selection Completed Exchange artifacts Test Cases Validation Engine XML examples XSD schemas Subset Schema Crosswalk Mapping Spreadsheet Rules Report Rendering Stylesheet Import XSD Naming / NDR / spell check Generat e Dictionar y Import EDM Test Examples and Rules Model Exchange Expand, Review, Refine CAM Enabled Business Modelling Requirements Charter Work Group Cross Referenc e Mapping XSD Schema Writer Schema Generation

4 January, 2010 – CAM Draft Specification Development Related Materials Leveraging Re-use : Canonical XML Dictionaries What is a canonical dictionary How do I obtain one How do I use it with CAM?

5 January, 2010 – CAM Draft Specification Development Related Materials 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:

6 January, 2010 – CAM Draft Specification Development Related Materials Available XML Dictionaries LEXS 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 Available from download site direct link: XML + includes spreadsheets and sample blueprint Packaged with CAM editor see dictionary folder of install + spreadsheet + blueprint samples XML

7 January, 2010 – CAM Draft Specification Development Related Materials Viewing Dictionary in Excel Drag and Drop XML dictionary format into Microsoft Excel Item names Child item indicator List of Child items Parent item indicator Unique ID Item Properties

8 January, 2010 – CAM Draft Specification Development Related Materials 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

9 January, 2010 – CAM Draft Specification Development Related Materials 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 January, 2010 – CAM Draft Specification Development Related Materials 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 January, 2010 – CAM Draft Specification Development Related Materials 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 January, 2010 – CAM Draft Specification Development Related Materials Example Blueprints LEXS messaging blueprint Reusable messaging envelope constructs OASIS EDXL HAVE message Business functional components Message handling, delivery and control Payload goes here Top level sets of business information components Individual component

13 January, 2010 – CAM Draft Specification Development Related Materials Blueprint Tools Overview Expander Tool Expander Tool Industry dictionary Domain dictionary Component Definitions 4 4 Web tool Excel Searc h Tools Searc h Tools 2 2 Blueprint Designer Blueprint Designer 1 1 Insert Dictionary Parent Components Insert Dictionary Parent Components 3 3 Completed Exchange Template Completed Exchange Template 5 5

14 January, 2010 – CAM Draft Specification Development Related Materials 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 January, 2010 – CAM Draft Specification Development Related Materials Blueprint Structure Overview

16 January, 2010 – CAM Draft Specification Development Related Materials 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 January, 2010 – CAM Draft Specification Development Related Materials 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 January, 2010 – CAM Draft Specification Development Related Materials Running Blueprint Expander Using Expander tool dialogue Reviewing results Hints and Tips

19 January, 2010 – CAM Draft Specification Development Related Materials Running Blueprint Expander

20 January, 2010 – CAM Draft Specification Development Related Materials Blueprint follows model Console Log detail Blueprint Expander Example Exchange components outline EXCHANGE BLUEPRINT COMPLETED EXCHANGE TEMPLATE Structure Details Expanded Expander Tool Expander Tool 2 2 Dictionary Lookups

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 January, 2010 – CAM Draft Specification Development Related Materials Exchange Template Editor Exchange Structure items Rules for each item Domain Components Namespaces Can add new custom domain Items

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

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

25 January, 2010 – CAM Draft Specification Development Related Materials 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 January, 2010 – CAM Draft Specification Development Related Materials Evaluation Report (NDR) example Part of an example report for LEXS getDataItemRequest template displayed in toolkit HTML viewer

27 January, 2010 – CAM Draft Specification Development Related Materials 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 January, 2010 – CAM Draft Specification Development Related Materials Example cross-reference spreadsheet Formatted view in Microsoft Excel of import of cross- reference report details (from generated XML file)

29 January, 2010 – CAM Draft Specification Development Related Materials 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 January, 2010 – CAM Draft Specification Development Related Materials Business Rules Documentation Part of the example rules for LEXS getDataItemRequest template displayed in toolkit HTML viewer

31 January, 2010 – CAM Draft Specification Development Related Materials Export Exchange to XSD Schema Completed Exchange Structure Set Exchange Options Complete set of exchange schemas generated Export Template to Exchange XSD:

32 January, 2010 – CAM Draft Specification Development Related Materials Exchange Schema Generated Each namespace file is import for those specific type definitions Reviewing XSD results in a schema editor tool Set of XSD files with filename and namespace suffix

33 January, 2010 – CAM Draft Specification Development Related Materials 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 January, 2010 – CAM Draft Specification Development Related Materials XML example generation wizard View of CAM toolkit with LEXS getDataItemRequest and dialogue for XML test example generator tool

35 January, 2010 – CAM Draft Specification Development Related Materials 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 January, 2010 – CAM Draft Specification Development Related Materials Run Exchange Template Pick XML test case to validate Run validation Review results in visual editor

37 January, 2010 – CAM Draft Specification Development Related Materials Example Exchange Packaging Details Package ArtefactDescription Exchange Files Subset SchemaSubset of the full exchange schema—a reduced set of components only used in this exchange, not every possible component. Crosswalk XMLItemized list of each dictionary component element and attribute included in the exchange. Exchange SchemaBase document schema that defines the full XML structure for the exchange and is generally named after the exchange itself. Constraint SchemaOptional schema that includes additional constraints and code values for the main exchange schema Extension SchemaSpecification for extended components—separate local name-spaces of components not contained in dictionary Sample XML InstanceExample instance(s) – may reference optional stylesheet. StylesheetExample stylesheet for display of instance(s). Documentation Master Documentation The Master Document is the main document for which all of the context and details around the exchange are explained. This document includes, the overview, as well as details surrounding the exchange, business drivers and requirements Exchange model Exchange model in standard open format (xmi, vsd, zargo) and standard open graphic (jpg, pdf, etc.) preferably a Unified Modeling Language (UML) model. Business rules Business rules in one of the following formats: (1) plain or structured English, (2) written into master documentation, (3) generated by a development tool. Mapping to DictionaryMapping of domain components, tagged with constraints (i.e., cardinality, etc.) to dictionary components as a spreadsheet. Extended components Components created because they were not in dictionary—may be part of mapping spreadsheet and include structure and definitions of new components. Change logRecord of cumulative changes from previous exchange versions. The initial exchange simple records its creation date. Catalog Catalog XML fileA machine-readable list of artifacts provided in this exchange package. Metadata XML fileAll metadata of owner and domain to be associated with the exchange.

38 January, 2010 – CAM Draft Specification Development Related Materials Summary Dictionary driven exchanges Blueprint enabled reuse Automated exchange package generation Alignment to NDR Principles and Rules Testing and validation support

39 January, 2010 – CAM Draft Specification Development Related Materials 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 January, 2010 – CAM Draft Specification Development Related Materials Links and Resources DOWNLOADS - CAM Toolkit download SUPPORTING MATERIALS - NIEM Naming and Design Rules (NDR) RESOURCES – Additional support slides (following)

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

43 January, 2010 – CAM Draft Specification Development Related Materials Template Wizard runtime configuration Library Object templates/Components design time Facets Questions / Data Technology Targeting Syntax specific production rules Exchange Interface / Blueprints Visual editor + review / test / completion steps XML 2 2 Domain Dictionary Details Stored XML Solution Specific Syntax 5 5

44 January, 2010 – CAM Draft Specification Development Related Materials 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 ( 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 January, 2010 – CAM Draft Specification Development Related Materials Example Governance Structure

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