Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "COSMOS UG SML"

(→‎Documents section)
(→‎Exporting SML resources from the repository)
 
(19 intermediate revisions by the same user not shown)
Line 78: Line 78:
 
<tr>
 
<tr>
 
<td>Definition
 
<td>Definition
−
 
−
 
 
<td>A definition is one of two types of documents supported by SML-IF. A definition document is used to describe the structure and constraints of the model
 
<td>A definition is one of two types of documents supported by SML-IF. A definition document is used to describe the structure and constraints of the model
 
</td></tr>
 
</td></tr>
Line 87: Line 85:
 
<td>
 
<td>
 
An instance is one of two types of documents supported by SML-IF. An instance document describes a model entity
 
An instance is one of two types of documents supported by SML-IF. An instance document describes a model entity
 +
</td></tr>
 +
<tr><td>
 +
SML repository
 +
</td>
 +
<td>
 +
In the SML tooling, this is a flat-file based directory structure.  Each file in the structure contains an SML document.  The Import operation creates SML document files based on the top level resources found in an input SML-IF document.
 
</td></tr>
 
</td></tr>
 
<tr><td>
 
<tr><td>
Line 113: Line 117:
 
*        W3C SML Version 1.0 submission — http://www.w3.org/Submission/sml/
 
*        W3C SML Version 1.0 submission — http://www.w3.org/Submission/sml/
 
*        W3C SML Interchange Format Version 1.0 submission — http://www.w3.org/Submission/sml-if/
 
*        W3C SML Interchange Format Version 1.0 submission — http://www.w3.org/Submission/sml-if/
 +
* Schematron - http://www.schematron.com/
 +
* XML Schema - http://www.w3.org/XML/Schema
  
 
=== Opening an SML-IF document in an editor ===
 
=== Opening an SML-IF document in an editor ===
Line 218: Line 224:
 
Figure 3 shows the SML-IF editor Documents window for the file <code>Valid.xml</code>, with the ''Course1'' instance selected.<br/>
 
Figure 3 shows the SML-IF editor Documents window for the file <code>Valid.xml</code>, with the ''Course1'' instance selected.<br/>
 
[[Image:COSMOS UG SML Editor Documents.jpg]]<br/>
 
[[Image:COSMOS UG SML Editor Documents.jpg]]<br/>
−
''Figure 3. Documents section of the SML-IF editor''
+
''Figure 3. Documents section of the SML-IF editor''<br/>
 +
 
 +
<table border="1">
 +
<tr>
 +
<th>
 +
Field
 +
</th>
 +
<th>
 +
Description
 +
</th>
 +
</tr>
 +
<tr>
 +
<td>
 +
Documents
 +
</td>
 +
<td>
 +
There are two types of documents that are supported by SML-IF:
 +
 
 +
* Definition documents that describe the structure (schema) and constraints (Schematron rule) of the model
 +
* Instance documents that describe a model entity
 +
</td>
 +
</tr>
 +
<tr>
 +
<td>
 +
Logical Representation
 +
</td>
 +
<td>
 +
There are two types of logical representations contained in an SML-IF document:
 +
 
 +
* Alias is an alternative and usually easier-to-understand or more significant name for a defined data object.
 +
* Logical Tree is a logical representation of the relevant structure specified by the tags and attributes in the document
 +
</td>
 +
</tr>
 +
<tr>
 +
<td>
 +
XML Representation
 +
</td>
 +
<td>
 +
XML source of the selected element
 +
</td>
 +
</tr>
 +
</table>
 +
 
 +
==== Source section ====
 +
 
 +
The Source section of the editor is displayed by clicking the Source tab. The Source section displays the text content of the SML-IF document with color syntax highlighting as shown in Figure 5.<br/>
 +
[[Image:COSMOS UG SML Editor Source.gif]]<br/>
 +
''Figure 4. The Source section within the SML-IF editor''
  
 
=== Validating an SML-IF document ===
 
=== Validating an SML-IF document ===
−
Validate from editor, or from context menu
+
An SML model is a set of inter-related XML documents. Each SML model contains a special subset of documents that describe the schema and rules governing the structure and content of the model's documents.
 +
 
 +
SML model validation is the process of verifying that all documents in a model are valid with respect to this special subset.  The key contribution of SML to validation lies in its handling of inter-document constraints, which are layered on top of the single-document validation of XML Schema and Schematron.
 +
 
 +
To validate an SML-IF document:
 +
# From the Navigator window, select a desired document to be validated.
 +
# Do one of the following to Validate the document:
 +
## Right-click the document and select '''Validate SML-IF'''
 +
## Alternatively, open the file with the SML-IF editor, select the '''Overview''' tab and click '''Validate entire document''' as shown in Figure 5.
 +
 
 +
[[Image:COSMOS UG SML Editor Overview Validate Link.jpg]]<br/>
 +
''Figure 5. Validating a document in the SML-IF editor''<br/>
 +
 
 +
All errors/warnings/information are reported in the problems view. If there is no warning, error or information to be displayed, then the following Validation Passed message dialog appears to notify you that the document is valid and well formed.
 +
 
 +
[[Image:COSMOS UG SML Editor Validation Passed.jpg]]<br/>
 +
''Figure 6. Validation passed message''<br/>
 +
 
 
==== Navigating and fixing a problem ====
 
==== Navigating and fixing a problem ====
−
Locating validation errors in editor, correcting them, and revalidating.
+
If you have a validation problem, the errors are displayed in the Problems view as shown in Figure 7.
 +
 
 +
To view a validation error:
 +
 
 +
#    Double-click an error/warning entry in the problems view to navigate to the Source section of the SML-IF editor and the appropriate line number that is in violation, if line number information is available for that entry.
 +
#      The line-number of the SML-IF document is marked with an error or warning icon. [[Image:COSMOS UG SML Editor Validation Error Highlight.gif]]
 +
#      After resolving the error in the SML-IF document, save and re-validate the document
 +
 
 +
[[Image:COSMOS UG SML Editor Validation Problems View.jpg]]<br/>
 +
''Figure 7. Problems view window''<br/>
  
 
=== Importing an SML-IF document into the repository ===
 
=== Importing an SML-IF document into the repository ===
−
* Talk about what importing means (SML-IF > SML resources).
+
Import operation divides an SML-IF document into individual separate SML model documents and stores them in a desired target repository.  Remember that the SML repository is directory structure of flat files, each containing an SML resource.
−
* Import using link on editor, or using File > Import...
+
 
 +
The following import procedure is based on the assumption that you already have an SML-IF document. 
 +
 
 +
<table border="1">
 +
<tr>
 +
<th>
 +
Steps
 +
</th>
 +
<th>
 +
Figure
 +
</th>
 +
<th>
 +
Import instructions
 +
</th>
 +
</tr>
 +
<tr>
 +
<td>
 +
Step 1.
 +
</td>
 +
<td>
 +
8
 +
</td>
 +
<td>
 +
Start the Import wizard using one of the following three methods:
 +
 
 +
* Select '''File -> Import'''   
 +
* Right-click within the Eclipse Navigator and click '''Import'''
 +
* Or click the '''Import model into repository''' option in the Overview section of the SML-IF editor
 +
</td>
 +
</tr>
 +
<tr>
 +
<td>
 +
Step 2.
 +
</td>
 +
<td>
 +
9
 +
</td>
 +
<td>
 +
From the '''Import Select''' window:
 +
 
 +
# Expand the '''Service Modeling Language''' category
 +
# Select '''Interchange Format'''
 +
# Click '''Next'''
 +
</td>
 +
</tr>
 +
<tr>
 +
<td>
 +
Step 3.
 +
</td>
 +
<td>
 +
10
 +
</td>
 +
<td>
 +
From the '''Import-Interchange Format''' window:
 +
 
 +
# Select the SML-IF document to import
 +
# Select the Destination folder to store the SML documents
 +
# Click '''Finish'''
 +
</td>
 +
</tr>
 +
</table>
 +
 
 +
After the SML documents are created, refresh the Eclipse workspace to display the files in the Navigator.
 +
 
 +
[[Image:COSMOS_UG_SML_Editor_Import_Option1.jpg]]<br/>
 +
''Figure 8. '''Step 1''' – '''Import''' option on the Overview window''<br/>
 +
 
 +
[[Image:COSMOS UG SML Editor Import Figure2.jpg]]<br/>
 +
''Figure 9. '''Step 2''' - Import window''<br/>
 +
 
 +
[[Image:COSMOS UG SML Editor Import Figure3.jpg]]<br/>
 +
''Figure 10. '''Step 3''' – Import-Interchange Format window''
  
 
=== Exporting SML resources from the repository ===
 
=== Exporting SML resources from the repository ===
−
* Why export? (transmit to another COSMOS SML repository or systems management application)
+
The export operation creates an SML-IF document from an SML repository. The export operation is integrated with Eclipse’s export wizard under the '''Service Modeling Language''' category as shown in Figure 11.
−
* File > Export...
+
 
 +
An SML-IF document can be formed by selecting '''Export...''' from the context menu of one or more SML resources that appears under a project.
 +
 
 +
The following export procedure is based on the assumption that you already have an SML document. Use the export wizard to create an SML-IF document.
 +
 
 +
<table border="1">
 +
<tr>
 +
<th>
 +
Steps
 +
</th>
 +
<th>
 +
Figure
 +
</th>
 +
<th>
 +
Export instructions
 +
</th>
 +
</tr>
 +
<tr>
 +
<td>
 +
Step 1.
 +
</td>
 +
<td>
 +
n/a
 +
</td>
 +
<td>
 +
To start the Export wizard:
 +
# Select the folders or model units that are to be included in the interchange document.
 +
# Right-click on the items and select '''Export'''
 +
</td>
 +
</tr>
 +
<tr>
 +
<td>
 +
Step 2.
 +
</td>
 +
<td>
 +
11
 +
</td>
 +
<td>
 +
From the Export Select window:
 +
# Expand the '''Service Modeling Language''' category
 +
# Click '''Interchange Format'''
 +
# Click '''Next'''
 +
</td>
 +
</tr>
 +
<tr>
 +
<td>
 +
Step 3.
 +
</td>
 +
<td>
 +
12
 +
</td>
 +
<td>
 +
From the Export Interchange Format window:
 +
 
 +
# Select the resources to export
 +
# Click '''Next'''
 +
</td>
 +
</tr>
 +
<tr>
 +
<td>
 +
Step 4.
 +
</td>
 +
<td>
 +
13
 +
</td>
 +
<td>
 +
From the Export Interchange Format window, page 2.  Specify aliases, if desired, for document and SML-IF identity information.
 +
<ol>
 +
<li>(Optional) Add an alias to a Detected Document
 +
<ol>
 +
<li>Click the Detected Document
 +
<li>Click '''Add''', enter the new aliases name in the pop-up window
 +
<li>Click '''OK'''.
 +
</ol>
 +
<li>Add identity information
 +
* Enter name, display name, description, and base URI</li>
 +
<li>Click '''Next'''
 +
</ol>
 +
</td>
 +
</tr>
 +
<tr>
 +
<td>
 +
Step 5.
 +
</td>
 +
<td>
 +
14
 +
</td>
 +
<td>
 +
(Optional) Add rule bindings to bind a named Schematron rule to an SML instance.
 +
 
 +
# Click '''Add'''
 +
# Click '''Documents''' dropdown arrow to select document
 +
# Click '''Alias''' dropdown arrow to select the alias to be bound for the selected document
 +
# Click '''Rule''' dropdown arrow to bind the document to an existing Schematron rule
 +
# Click '''Finish'''
 +
</td>
 +
</tr>
 +
</table>
 +
 
 +
After the SML-IF document is created, open the document in the SML-IF editor to display the document source. See figure 15 for an example of an SML-IF document.
 +
 
 +
The following figures correspond with above Export instruction table.  
  
−
== Content ==
+
[[Image:COSMOS UG SML Editor Export Figure11.jpg]]<br/>
 +
<br/>
 +
''Figure 11. Step 2 – Starting the Export wizard'' <br/>
 +
<br/>
 +
[[Image:COSMOS UG SML Editor Export Figure12.jpg]]<br/>
 +
<br/>
 +
''Figure 12. Step 3 – Selecting the resources to export in the Export wizard''<br/>
 +
<br/>
 +
[[Image:COSMOS UG SML Editor Export Figure13.jpg]]<br/>
 +
<br/>
 +
''Figure 13. Step 4 – Specifying a documents aliases and identity information''<br/>
 +
<br/>
 +
[[Image:COSMOS UG SML Editor Export Figure14.jpg]]<br/>
 +
<br/>
 +
''Figure 14. Step 5 - Modify the content to bind a rule to a document''
  
 +
Figure 15 shows the contents of an exported SML-IF document.
 +
<br/>
 +
[[Image:COSMOS UG SML Editor Export Figure15.jpg]]<br/>
 +
<br/>
 +
''Figure 15. Contents of the new SML-IF document''
  
  
 
[[Category:COSMOS_Users_Guide]]
 
[[Category:COSMOS_Users_Guide]]

Latest revision as of 14:01, 10 March 2008

COSMOS Wiki > COSMOS Document Plan > COSMOS Manual Guide

COSMOS User's Guide Service Modeling Language

Category: User's Guide

Owner David Whiteman
Bug # 218871
Due dates Schedule

Outline

Overview

This section covers how to use the Service Modeling Language (SML) tooling on the Eclipse SDK Platform.

Purpose

The purpose of the SML tooling is to view and edit SML-IF documents, and to validate the content of SML and SML-IF documents. The SML-IF tooling plug-in also provides export and import wizards that are integrated into the Eclipse SDK Platform.

  • Export operation creates an SML-IF document from the repository
  • Import operation parses an SML-IF document into individual separate SML model documents and stores them in the repository (which can be a workspace folder).

The export operation packages and validates a set of documents representing an SML model to be interchanged into a single XML=based document in a standard way. The set of documents to be interchanged is called the SML-IF document’s interchange set. The documents in the interchange set constitute the SML model being interchanged.

Note: During the import operation, there would normally be some loss of data when an SML-IF document is broken into its respective SML model units. For example, the aliases associated with a document or schematron rule binding are not preserved in SML model units. To preserve this information, a meta-data file is generated with every SML-IF document import.

The SML-IF validator helps to ensure an SML-IF document:

  • Conforms to XML 1.0 (Second Edition)
  • Conforms to Schematron rules bound to documents
  • Is valid under the SML-IF and SML schemas
  • Conforms to the SML-IF and SML specifications

The SML-IF specification defines the format for a single XML-based document that can be used to exchange SML models between other consumers of SML models.

Figure 1 shows the SML-IF editor open in the Eclipse SDK Platform.
COSMOS UG SML 001.jpg

The SML-IF tooling plug-in includes a multi-page editor that contains three tabs:

  • Overview - The overview window displays general information about the SML-IF document.
  • Documents – The documents window displays definitions, instances, logical representation, alias names and logical tree, and a source representation of the selected document section.
  • Source view – Source view window shows the raw source of the SML-IF file, color coded with syntax highlighting.

Summary

SML is an important step to drive significant, cross-platform business modeling improvements for IT professionals and their business platforms. SML provides an industry-agreed foundation for model-based management. SML allows developers to build modeling information for applications, devices and services that can be used during all stages of applications or service lifecycle including configuration, problem, change and release management.

As a common modeling language, SML simplifies IT management in multi-vendor environments. This provides a way for information to be shared across diverse tools and applications. It reduces both the cost and complexity associated with delivering the levels of service and responsiveness businesses need from IT today.

The SML tooling provides an editor for an SML-IF document. The tool also provides the ability to import SML-IF document into a project and export SML model units to an SML-IF document. A SML-IF document packages the collection of SML documents to be interchanged as a single XML document. All exported SML-IF documents conform to the schema defined by the SML-IF specification.

Terms you should know

The following table contains some basic terms you should know to make using this documentation easier.

Term Definition
SML Service Modeling Language (SML) is an XML-based specification that is used to model complex IT resources, services and systems, including their structure, constraints, policies and best practices. An SML model defines a consistent way for computer networks, applications, servers and other IT resources are described or modeled to assist businesses to manage their services that are built on these. The SML specification leverages Schematron and unique XML Schema extensions to implement these models.
SML-IF Service Modeling Language – Interchange Format (SML-IF) defines an implementation-neutral interchange format that preserves the content and interrelationships among documents.
Definition A definition is one of two types of documents supported by SML-IF. A definition document is used to describe the structure and constraints of the model

Instance

An instance is one of two types of documents supported by SML-IF. An instance document describes a model entity

SML repository

In the SML tooling, this is a flat-file based directory structure. Each file in the structure contains an SML document. The Import operation creates SML document files based on the top level resources found in an input SML-IF document.

SML validation

Validating an SML model in accordance with the SML specification

SML-IF validation

Validating an SML-IF document in accordance with the SML-Interchange Format specification

Domain model

The root of an SML-IF document. Contains a set of definition an instance documents

SML resources

Opening an SML-IF document in an editor

The SML tooling provides an editor that allows you to view and edit an SML-IF file. There are two ways to open an SML-IF document in this editor:

  • Select File > Open... from the menu bar, and choose the file from the file system
  • Double click on an SML-IF file that exists in the Eclipse workspace

The SML-IF editor has three main sections:

To view a specific section, select one of the tabs located at the bottom of the editor.

Overview section

COSMOS UG SML Editor Overview.jpg
Figure 2. Overview window of the SML-IF editor

Field

Required

Description

Name

Yes

Name field is the namespace for the SML-IF document.

Version

No

Specifies the version level of the model.

Display name

No

Descriptive name of the model intended for display.

Base URI

No

The base Uniform Resource Identifier (URI) provides a simple and extensible means for identifying a resource. For example, the URL http://www.eclipse.org/ is a URI that identifies a resource.

Description

No

This is a detailed textual description of a model.

Table 1. List of General Information fields

Validate the entire document function

To validate the SML-IF document, click Validate the entire document. This function validates the entire SML-IF document and reports any errors in the Problems view of your workbench. See Validating an SML-IF document for more information on validation.

Import model into repository function

To import the SML-IF document, click Import model into repository. This function imports the SML resources represented in the SML-IF document into the SML repository. See Importing an SML-IF document for more information on importing.

Documents section

The SML-IF editor Documents window displays an SML-IF document's definition and instance elements and their aliases, with elements organized in a logical tree.

You can view a tree display of definition and instance documents, and change the aliases of an individual document by selecting a resource and clicking the Add or Remove button. You can also view the subset of the SML-IF file that defines a document or instance element by selecting that element in the tree view, and that element's source will be displayed in the XML Representation field.

Figure 3 shows the SML-IF editor Documents window for the file Valid.xml, with the Course1 instance selected.
COSMOS UG SML Editor Documents.jpg
Figure 3. Documents section of the SML-IF editor

Field

Description

Documents

There are two types of documents that are supported by SML-IF:

  • Definition documents that describe the structure (schema) and constraints (Schematron rule) of the model
  • Instance documents that describe a model entity

Logical Representation

There are two types of logical representations contained in an SML-IF document:

  • Alias is an alternative and usually easier-to-understand or more significant name for a defined data object.
  • Logical Tree is a logical representation of the relevant structure specified by the tags and attributes in the document

XML Representation

XML source of the selected element

Source section

The Source section of the editor is displayed by clicking the Source tab. The Source section displays the text content of the SML-IF document with color syntax highlighting as shown in Figure 5.
COSMOS UG SML Editor Source.gif
Figure 4. The Source section within the SML-IF editor

Validating an SML-IF document

An SML model is a set of inter-related XML documents. Each SML model contains a special subset of documents that describe the schema and rules governing the structure and content of the model's documents.

SML model validation is the process of verifying that all documents in a model are valid with respect to this special subset. The key contribution of SML to validation lies in its handling of inter-document constraints, which are layered on top of the single-document validation of XML Schema and Schematron.

To validate an SML-IF document:

  1. From the Navigator window, select a desired document to be validated.
  2. Do one of the following to Validate the document:
    1. Right-click the document and select Validate SML-IF
    2. Alternatively, open the file with the SML-IF editor, select the Overview tab and click Validate entire document as shown in Figure 5.

COSMOS UG SML Editor Overview Validate Link.jpg
Figure 5. Validating a document in the SML-IF editor

All errors/warnings/information are reported in the problems view. If there is no warning, error or information to be displayed, then the following Validation Passed message dialog appears to notify you that the document is valid and well formed.

COSMOS UG SML Editor Validation Passed.jpg
Figure 6. Validation passed message

Navigating and fixing a problem

If you have a validation problem, the errors are displayed in the Problems view as shown in Figure 7.

To view a validation error:

  1. Double-click an error/warning entry in the problems view to navigate to the Source section of the SML-IF editor and the appropriate line number that is in violation, if line number information is available for that entry.
  2. The line-number of the SML-IF document is marked with an error or warning icon. COSMOS UG SML Editor Validation Error Highlight.gif
  3. After resolving the error in the SML-IF document, save and re-validate the document

COSMOS UG SML Editor Validation Problems View.jpg
Figure 7. Problems view window

Importing an SML-IF document into the repository

Import operation divides an SML-IF document into individual separate SML model documents and stores them in a desired target repository. Remember that the SML repository is directory structure of flat files, each containing an SML resource.

The following import procedure is based on the assumption that you already have an SML-IF document.

Steps

Figure

Import instructions

Step 1.

8

Start the Import wizard using one of the following three methods:

  • Select File -> Import
  • Right-click within the Eclipse Navigator and click Import
  • Or click the Import model into repository option in the Overview section of the SML-IF editor

Step 2.

9

From the Import Select window:

  1. Expand the Service Modeling Language category
  2. Select Interchange Format
  3. Click Next

Step 3.

10

From the Import-Interchange Format window:

  1. Select the SML-IF document to import
  2. Select the Destination folder to store the SML documents
  3. Click Finish

After the SML documents are created, refresh the Eclipse workspace to display the files in the Navigator.

COSMOS UG SML Editor Import Option1.jpg
Figure 8. Step 1 – Import option on the Overview window

COSMOS UG SML Editor Import Figure2.jpg
Figure 9. Step 2 - Import window

COSMOS UG SML Editor Import Figure3.jpg
Figure 10. Step 3 – Import-Interchange Format window

Exporting SML resources from the repository

The export operation creates an SML-IF document from an SML repository. The export operation is integrated with Eclipse’s export wizard under the Service Modeling Language category as shown in Figure 11.

An SML-IF document can be formed by selecting Export... from the context menu of one or more SML resources that appears under a project.

The following export procedure is based on the assumption that you already have an SML document. Use the export wizard to create an SML-IF document.

Steps

Figure

Export instructions

Step 1.

n/a

To start the Export wizard:

  1. Select the folders or model units that are to be included in the interchange document.
  2. Right-click on the items and select Export

Step 2.

11

From the Export Select window:

  1. Expand the Service Modeling Language category
  2. Click Interchange Format
  3. Click Next

Step 3.

12

From the Export Interchange Format window:

  1. Select the resources to export
  2. Click Next

Step 4.

13

From the Export Interchange Format window, page 2. Specify aliases, if desired, for document and SML-IF identity information.

  1. (Optional) Add an alias to a Detected Document
    1. Click the Detected Document
    2. Click Add, enter the new aliases name in the pop-up window
    3. Click OK.
  2. Add identity information
    • Enter name, display name, description, and base URI
  3. Click Next

Step 5.

14

(Optional) Add rule bindings to bind a named Schematron rule to an SML instance.

  1. Click Add
  2. Click Documents dropdown arrow to select document
  3. Click Alias dropdown arrow to select the alias to be bound for the selected document
  4. Click Rule dropdown arrow to bind the document to an existing Schematron rule
  5. Click Finish

After the SML-IF document is created, open the document in the SML-IF editor to display the document source. See figure 15 for an example of an SML-IF document.

The following figures correspond with above Export instruction table.

COSMOS UG SML Editor Export Figure11.jpg

Figure 11. Step 2 – Starting the Export wizard

COSMOS UG SML Editor Export Figure12.jpg

Figure 12. Step 3 – Selecting the resources to export in the Export wizard

COSMOS UG SML Editor Export Figure13.jpg

Figure 13. Step 4 – Specifying a documents aliases and identity information

COSMOS UG SML Editor Export Figure14.jpg

Figure 14. Step 5 - Modify the content to bind a rule to a document

Figure 15 shows the contents of an exported SML-IF document.
COSMOS UG SML Editor Export Figure15.jpg

Figure 15. Contents of the new SML-IF document

Retrieved from "https://wiki.eclipse.org/index.php?title=COSMOS_UG_SML&oldid=86746"

This page was last modified 14:01, 10 March 2008 by David Whiteman. Based on work by Richard Vasconi.

Back to the top