HistoryViewLinks to this page 2013 March 27 | 02:29 pm

This Version

Latest Version

PreviousVersion

  • N/A

Authors

Contributors

Contents


Overview

In an attempt to aid implementers in adopting the OSLC Reconciliation specification, the OSLC Reconciliation workgroup will evolve this document to gather guidance, best practices, tips and other aids. The content here is not intended to be the basis for a toolkit or validation test suite. There may be some references to toolkits to illustrate some specification aspects, though implementers are free to use whatever toolkit or technology for their needs.

Although this documentation is for implementers’guidance only, we will maintain consistency with the specification in the use of key words. That is, the key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC2119.

Interpreting the NOT operator

In some of the requirements for reconciling resources, we define rules that use a NOT operator. For example, crtv:ComputerSystem, we have the following

  1. crtv:hostid, crtv:vmid
  2. crtv:hostid, NOT crtv:vmid
  3. (There are other requirements for crtv:ComputerSystem but for this example, we restrict ourselves to these two rules)

Interpret this as there being 2 ways to reconcile crtv:ComputerSystem instances.

  1. If two or more crtv:ComputerSystem instances have the same value for property crtv:hostid AND the same value for property crtv:vmid then all instances can be set as members of the same reconciled resource collection.
  2. If two or more crtv:ComputerSystem instances have the same value for property crtv:hostid AND no instance has a value for property crtv:vmid then all instances as members of the same reconciled resource collection.

Consider this example

@prefix dcterms: <http://purl.org/dc/terms/> .
@prefix oslc: <http://open-services.net/ns/core#> .
@prefix owl: <http://www.w3.org/2002/07/owl#> .
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
@prefix vs: <http://www.w3.org/2003/06/sw-vocab-status/ns#> .
@prefix crtv: <http://open-services.net/ns/crtv#> .


@base <http://reconciliation.example.org/> .


<cs001>   # a crtv:ComputerSystem record ( 1 of 4 )
    a crtv:ComputerSystem ;
    crtv:hostid         "Host ABC" ;
    crtv:vmid           10 ;
    crtv:serialNumber   "1234a" ;
.
#    
<cs002>   # a crtv:ComputerSystem record ( 2 of 4 )
    a crtv:ComputerSystem ;
    crtv:hostid         "Host ABC" ;
    crtv:vmid           10 ;
    crtv:serialNumber   "1234b" ;
.
#
<cs003>   # a crtv:ComputerSystem record ( 3 of 4 )
    a crtv:ComputerSystem ;
    crtv:hostid         "Host ABC" ;
    crtv:serialNumber   "1234c" ;
.
#
<cs004>   # a crtv:ComputerSystem record ( 4 of 4 )
    a crtv:ComputerSystem ;
    crtv:hostid         "Host ABC" ;
    crtv:serialNumber   "1234d" ;
.

We can use rule 1 to reconcile cs001 and cs002 since both instances have properties crtv:hostid and crtv:vmid.

We can use rule 2 to reconcile cs003 and cs004 since both instances have property crtv:hostid and do NOT have property crtv:vmid.

Note though that we CAN NOT reconcile cs001 and cs003 since we can apply neither rule 1 nor rule 2 to both instances. cs001 can use rule 1 but not rule 2 and cs003 can use rule 2 but not rule 1.

Categorizing Resources

In cases where you want to further detail a resource ( e.g. indicate that a SoftwareServer is a web server ), populate the rdf:type property. You can use the URIs defined in the Common IT Resource Type vocabulary but are not restricted to only these.

Resource pools

You SHOULD use rdfs:Container to represent pools of resources.

The following set of RDFS classes can be used to define resource pool categories

URI Description
http://open-services.net/ns/crtv#ThreadPool A pool of shared operating system threads
http://open-services.net/ns/crtv#DatabaseConnectionPool A pool of shared database connections
http://open-services.net/ns/crtv#J2CConnectorPool A pool of shared J2C connectors

crtv:ServiceInstance

The following set of RDFS classes can be used to define categories of ServiceInstances

URI Description
http://open-services.net/ns/crtv#Network The ServiceInstance represent a network service.
http://open-services.net/ns/crtv#Storage The ServiceInstance represent a storage service.
http://open-services.net/ns/crtv#Compute The ServiceInstance represent a computational or processing service.
http://open-services.net/ns/crtv#Application The ServiceInstance represent a business application.
http://open-services.net/ns/crtv#Transaction The ServiceInstance represent a transactional service.

crtv:SoftwareServer

The following set of RDFS classes can be used to define categories of SoftwareServers

URI Description
http://open-services.net/ns/crtv#J2EEServer This SoftwareServer is a J2EE server.
http://open-services.net/ns/crtv#WebSphereServer This SoftwareServer is an IBM WebSphere Application Server®.
http://open-services.net/ns/crtv#WebServer This SoftwareServer is a web server.
http://open-services.net/ns/crtv#IBMHTTPServer This SoftwareServer is an IBM HTTP® server.
http://open-services.net/ns/crtv#DatabaseInstance This SoftwareServer is a database instance.
http://open-services.net/ns/crtv#DB2Instance This SoftwareServer is a IBM DB2® server.
http://open-services.net/ns/crtv#OracleInstance This SoftwareServer is an Oracle® database server.
http://open-services.net/ns/crtv#MessagingServer This SoftwareServer is a messaging server.
http://open-services.net/ns/crtv#MQQueueManager This SoftwareServer is an IBM MQ® server.

crtv:SoftwareModule

The following set of RDFS classes can be used to define categories of SoftwareModules

URI Description
http://open-services.net/ns/crtv#J2EEApplication A SoftwareModule which functions as a J2EE application.
http://open-services.net/ns/crtv#MQQueue A SoftwareModule representing an IBM MQ® Queue.

Populating properties used in reconciliation

crtv:ComputerSystem

crtv:manufacturer

This attribute SHOULD be from a publicly available manufacturer name vocabulary. If the manufacturer name cannot be mapped to a value in a list, you SHOULD apply the following transformations to the value before setting this attribute: do not use punctuation if the company name is an acronym; do not use the model type or any characteristics other than the commonly understood name of a manufacturer; and do not use terms such as: LLC, Inc., Corporation, Incorporated, GmbH, AG, SRL, Ltd., sp. z o.o., or sarl. Do not include leading or trailing spaces. On Windows systems, use the raw output from WMI Win32_ComputerSystemProduct (attribute Vendor). On Linux Intel machines, use the raw output from dmidecode (value of Manufacturer: field). For Windows and Linux Intel machines that are running VMware virtual machines, use string “VMware” as the manufacturer value.

crtv:model

For system z machines, use the 4-digit “Machine type” value with no embedded special characters or blanks. Do not use the “Model ID” value as this can change when a hardware component is replaced. In all cases, the model number must be normalized according to the following rules: use the string provided by the system and apply the following: if the string returned by the system command contains \\[\\], extract the value within \\[\\];remove all non-alphanumeric characters including spaces;convert remaining characters to upper case. An example valid model value is “7978K8G” from a Windows machine via a call to Windows WMI class Win32_ComputerSystemProduct (Name) Example: the output from the system call is “IBM,9133-55A”, apply transformation rules and populate model with value “913355A”. Example: the output from the system call is “IBM eServer 325 \\-\\[88355EX\\]-“, apply the transformation rules and populate model with “88355EX”.

crtv:serialNumber

You SHOULD use the value as it is provided by the manufacturer of the resource, with the following transformations applied: remove everything before a comma ( for example, when the value is “…IBM,123456…”); remove string “VMware-” ( this is to handle cases where the serial number is automatically generated for virtual machines, e.g. “…VMware-123456…”; remove all non-alphanumeric characters including blanks; convert the remaining characters to upper case. An example valid serialNumber value is “KDFDXTT” from a Windows machine via a call to Win32_ComputerSystemProduct(IdentifyingNumber). Example: the output from the system call is “VMware-56 4d c6 9e d1 37 ff 34-a6 72 b0 ae d2 62 c5 64”. Apply the transformation rules and populate serialNumber with “564DC69ED137FF34A672B0AED262C564”. For AIX machines, if you are using the Object Data Manager to retrieve the serial number then you MUST apply the following transformation : remove all characters before the first comma, the comma itself and the first character after the comma. This is so that the value will match the output of the lsconf command which returns the true serial number of the machine. Example: odm returns “IBM,0310DD5AG”. Apply the transformation rules and populate serialNumber with “10DD5AG”

crtv:systemBoardUUID

Provide the SystemBoardUUID in human-readable string format, in the form 8-4-4-4-12, where there are 8 hexadecimal values separated by a hyphen, followed by 4 hexadecimal values separated by a hyphen, and so forth; the hexadecimal values from ‘a’ to ‘f’ are to be given as lower-case characters; do not include the manufacturer, model or serial number of the machine in this attribute. Do not include leading or trailing spaces. An example valid systemBoardUUID is “62f05081-40d1-b238-98fd-d418846eaebe” from a Windows machine via a call to WMI class Win32_ComputerSystemProduct (UUID attribute). If the machine type you are working with has a designated system board UUID that has the correct number of digits (32) but does not have the ‘-’ characters, transform the UUID string to the 8-4-4-4-12 format. For example, VMware returns “56 4d c6 9e d1 37 ff 34-a6 72 b0 ae d2 62 c5 64”. Populate systemBoardUUID with “564dc69e-d137-ff34-a672-b0aed262c564”. If the machine type you are working with has a designated system board UUID that does not have the correct number of hexadecimal characters then use the raw output from the system command. For example, the AIX unamex() command returns “36e2374d20f2e00”. Populate systemBoardUUID as “36e2374d20f2e00”

crtv:vmid

You SHOULD do the following when setting the vmid property : remove leading and trailing blanks. Otherwise leave the string value as-is. Non alphanumeric characters are valid. Case is significant as well since some manufacturers differentiate between upper and lower case. An example valid vmid is “5” from an AIX machine via command uname -L

crtv:hostid

The value SHOULD be normalized according to the following rules: remove leading and trailing blanks;remove non-alphanumeric characters;convert all remaining characters to upper case. An example valid hostd is “84FB046F” from a Solaris machine via command hostid

crtv:shortHostName

The value SHOULD be in lower case. If the value contains the DNS domain name then you SHOULD use the property crtv:fqdn instead.

crtv: fqdn

The value SHOULD be in lower case. You MUST NOT populate this property with IP addresses or short hostnames.

crtv:Database

crtv:name

If you are representing a DB2 or Oracle database, you SHOULD populate this property with the database name.

crtv:IPAddress

crtv:address

For IPv6 addresses, you SHOULD use the form x:x:x:x:x:x:x:x, where: x represents one to four hexadecimal digits of the eight 16-bit pieces of the address. Any hexadecimal letters are in lower case. Do not write the leading zeros in an individual field. There must be at least one numeral in every field. When the address is an IPv4-mapped address ( e.g. ::ffff:10.43.1.101) or a tunneling address (e.g. fe80::5efe:10.43.1.101) then you MUST populate the property with the IPv4 portion of the address in dotted decimal format.

For IPv4 addresses, you SHOULD use the form y.y.y.y, where: y represents an integer ranging from “0” to “255”.

crtv:ServiceInstance

A ServiceInstance represents a service and the individual processes and/or activities supporting that service. In the case where the processes and/or activities are viewed as independent and capable of supporting multiple services, you SHOULD create a hierachy of ServiceInstances, one instance to represent the main service and others to represent each process and/or activity.

crtv:name

This value SHOULD be unique within the organization that owns and supports the ServiceInstance

crtv:SoftwareServer

crtv:name

Depending on its rdf:type, a SoftwareServer SHOULD have accompanying and mutually agreed-upon rules for constructing the value of this property in order to help with reconciliation. For MQ servers, you SHOULD use the queue manager name. For databases, you SHOULD use the db instance name. For WebSphere, you SHOULD use the concatenation of Cell Name, NodeName and AppServer name (e.g. “CELL0:NODE0:appserver 1”) with “:” as the delimiter. For HTTP servers, you SHOULD use the web server name

crtv:instancePath

For MQ and databases servers, you SHOULD use the file directory path for the instance. For WebSphere servers, you SHOULD use the file directory path to the profile.

crtv:SoftwareModule

crtv:fileName

You SHOULD use the syntax specified in RFC 1630 and 1738, for example [file:///inst1.config] . For MQ, you SHOULD use the MQ queue name. For Websphere, you SHOULD use the application module name.

crtv:name

For MQ, you SHOULD use the MQ queue name. For WebSphere, you SHOULD use the app name.