This Version
Latest Version
PreviousVersion
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
- crtv:hostid, crtv:vmid {#rule1}
- crtv:hostid, NOT crtv:vmid {#rule2}
- (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.
- 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.
- 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 and 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.
crtv:ServiceInstance
The following set of RDFS classes can be used to define categories of ServiceInstances
crtv:SoftwareServer
The following set of RDFS classes can be used to define categories of SoftwareServers
crtv:SoftwareModule
The following set of RDFS classes can be used to define categories of SoftwareModules
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.
