History   View   Links to this page Revision from: 2013 February 8 | 01:39 pm
This is the revision from 2013 February 8 at 01:39 pm   View the current live version of the article.
OSLC_logo.png

Open Services for Lifecycle Collaboration
Reconciliation Specification Version 2.0

Status: 2.0 Draft Specification

NOTE: This version of the specification has version 2.0 to indicate that it is an OSLC Core 2.0 compliant specification. This specification is the initial version of an OSLC Reconciliation specification.

This Version

Latest Version

PreviousVersion

  • N/A

Authors

Contributors

Table of Contents

Contents

License

Creative Commons Attribution license
This work is licensed under a Creative Commons Attribution License.

Notation and Conventions

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.

Domain name examples use RFC2606.

Introduction

(this section is informative)

Reconciliation, as referenced in this specification, refers to the case where there exists a need to combine (that is, reconcile) the perspectives from multiple observations on the same resource instance. See the Reconciliation Scenarios page for several specific examples.

This specification builds on the OSLC Core Specification to define the resources and operations supported by Open Services for Lifecycle Collaboration (OSLC) providers who have a need to reconcile resource instance information with other providers.

The goal of this effort is to define resources, methods and constraints such that disparate tools can identify and reconcile their data. Reconciliation resources represent individual resources as well as their relationships to other resources and to other linked resources outside of the Reconciliation domain.

Terminology

Reconciliation Service Provider - an OSLC Service Provider that exposes reconcilable and/or reconciled resources.

Reconcilable resource - a resource that conforms to this specification, especially the “additional requirements” section for each resource definition. It can be matched to another resource instance based on the values of a set of properties as defined in this specification

Reconciled resource - A collection of reconcilable resources that the Reconciliation Service Provider has determined to be representations of the same object.

NOT - When used in the Resource Definitions section of this specification, indicates that the absence of a property is required.

Base Requirements

Compliance

This specification is based on OSLC Core Specification. OSLC Reconciliation domain consumers and service providers MUST be compliant with both the core specification and this Reconciliation Workgroup specification, and SHOULD follow all the guidelines and recommendations in both these specifications.

The following table summarizes the requirements from OSLC Core Specification as well as additional requirements specific to the Reconciliation domain.

Note that this specification further restricts some of the requirements from the OSLC Core Specification as noted in the Origin column of the compliance table. See further sections in this specification or the OSLC Core Specification to get further details on each of these requirements.

Any consumer or service provider behaviors are allowed unless explicitly prohibited by this or dependent specifications; conditional permissive requirements, especially those qualified with MAY, are implicitly covered by the preceding clause. While technically redundant in light of that broad permission, OSLC specifications do still make explicit MAY-qualified statements in cases where the editors believe doing so is likely to add clarity.

Requirements on OSLC Consumers

Requirement Level Origin(s) Meaning
Unknown properties and content MUST Core OSLC clients MUST preserve unknown content

Requirements on OSLC Service Providers

Requirement Level Origin(s) Meaning
Unknown properties and content MAY Core OSLC service providers MAY ignore unknown content
Unknown properties and content MUST Core OSLC service providers MUST return an error code if recognized content is invalid.
Unknown properties and content SHOULD Core OSLC service providers SHOULD NOT return an error code for unrecognized content.
Resource Operations MUST Core OSLC service providers MUST support resource operations via standard HTTP operations
Resource Paging MAY Core OSLC services MAY provide paging for resources
Partial Resource Representations MAY Core OSLC service providers MAY support HTTP GET requests for retrieval of a subset of a resource’s properties via the oslc.properties URL parameter
Partial Resource Representations MAY Core OSLC service providers MAY support HTTP PUT requests for updating a subset of a resource’s properties via the oslc.properties URL parameter
Service Provider Resources MAY Core OSLC service providers MAY provide a Service Provider Catalog resource
Service Provider Resources MUST Core OSLC service providers MUST provide a Service Provider resource
Creation Factories MAY Core OSLC service providers MAY provide creation factories to enable resource creation via HTTP POST
Query Capabilities SHOULD1 Reconciliation, Core OSLC service providers SHOULD provide query capabilities to enable clients to query for resources
Query Syntax MUST2 Reconciliation, Core If a service provider supports OSLC query capabilities, the query capabilities MUST support the OSLC Core Query Syntax
Query Syntax MAY Core OSLC query capabilities MAY support other query syntaxes
Delegated UI Dialogs SHOULD Core OSLC service providers SHOULD allow clients to discover, via their service provider resources, any Delegated UI Dialogs they offer.
Delegated UI Dialogs SHOULD Core OSLC service providers SHOULD offer delegated UI dialogs for resource creation
Delegated UI Dialogs SHOULD Core OSLC service providers SHOULD offer delegated UI dialogs for resource selection
UI Preview SHOULD Core OSLC Services SHOULD offer UI previews for resources that may be referenced by other resources
HTTP Basic Authentication MAY Core OSLC Services MAY support Basic Auth
HTTP Basic Authentication SHOULD Core OSLC Services SHOULD support Basic Auth only over HTTPS
OAuth Authentication MAY Core OSLC service providers MAY support OAuth
OAuth Authentication SHOULD Core OSLC service providers that support OAuth SHOULD allow clients to discover the required OAuth URLs via their service provider resource
Error Responses MAY Core OSLC service providers MAY provide error responses using Core-defined error formats
RDF/XML Representations MUST3 Reconciliation, Core OSLC service providers MUST offer an RDF/XML representation for HTTP GET responses
RDF/XML Representations MUST3 Reconciliation, Core OSLC service providers MUST accept RDF/XML representations on PUT requests.
RDF/XML Representations MUST3 Reconciliation, Core RDF/XML representations on POST requests whose semantic intent is to create a new resource instance.
XML Representations MAY3 Reconciliation, Core OSLC service providers MAY provide a XML representation for HTTP GET, POST and PUT requests that conform to the Core Guidelines for XML.
JSON Representations MAY3 Reconciliation, Core OSLC service providers MAY provide JSON representations for HTTP GET, POST and PUT requests that conform to the Core Guidelines for JSON
HTML Representations SHOULD3 Reconciliation, Core OSLC service providers SHOULD provide HTML representations for HTTP GET requests
  • 1The OSLC Core Specification indicates service providers MAY provide Query Capabilities. This specification strengthens the requirement.
  • 2The OSLC Core Specification indicates service providers MAY support the OSLC Query Syntax. This specification makes OSLC Query Syntax support a MUST requirement for service providers providing query capabilities.
  • 3Support for all common HTTP methods is not required for all resources defined by this specification. See the HTTP Method support table for details.

Specification Versioning

See OSLC Core Specification Versioning section.

Namespaces

In addition to the namespace URIs and namespace prefixes defined in the OSLC Core specification, OSLC Reconciliation Workgroup defines a namespace

  • http://open-services.net/ns/crtv# with a default namespace prefix of crtv. This namespace URI and prefix are used to designate the resources defined by the Common IT Resource Type vocabulary. The namespace prefix is used in this specification for consistency but client and provider implementations might use others.

The OSLC Reconciliation workgroup MAY also re-use vocabulary terms from other namespaces as needed after agreement on domain scenarios.

Resource Formats

In addition to the requirements for OSLC Defined Resource Representations, this section outlines further refinements and restrictions.

See HTTP Method support table for further clarification on support for HTTP methods and media types for each OSLC resource.

For HTTP GET requests on all OSLC Reconciliation and OSLC Core defined resource types,

  • Reconciliation Providers MUST provide RDF/XML representations. The RDF/XML representation SHOULD follow the guidelines outlined in the OSLC Core Representations Guidance for RDF/XML.
  • Reconciliation Providers MAY provide other representations. Other representations SHOULD follow the guidelines outlined in the OSLC Core Representations Guidance.
  • Reconciliation Consumers requesting RDF/XML SHOULD be prepared for any valid RDF/XML document. Reconciliation Consumers requesting XML SHOULD be prepared for representations that follow the guidelines outlined in the OSLC Core Representations Guidance.
  • Reconciliation Providers SHOULD support an [X]HTML representation and a user interface (UI) preview as defined by UI Preview Guidance

For HTTP PUT/POST request formats for Reconciliation resources,

  • Reconcliation Providers MUST accept RDF/XML representations and MAY accept XML representations. Reconciliation Providers accepting RDF/XML SHOULD be prepared for any valid RDF/XML document. If XML is accepted, Reconciliation Providers SHOULD be prepared for representations that follow the guidelines outlined in the OSLC Core Representations Guidance.
  • Reconciliation Providers MAY accept XML and JSON representations. Reconciliation Providers accepting XML or JSON SHOULD be prepared for representations that follow the guidelines outlined in the OSLC Core Representations Guidance.

For HTTP GET response formats for Query requests,

  • Reconciliation Providers MUST provide RDF/XML and MAY provide other representations such as JSON, XML, and Atom Syndication Format XML.

When Reconciliation Consumers request:

  • application/rdf+xml Reconciliation Providers MUST respond with RDF/XML representation without restrictions.
  • application/xml Reconciliation Providers SHOULD respond with OSLC-defined abbreviated XML representation as defined in the OSLC Core Representations Guidance
  • application/atom+xml Reconciliation Providers SHOULD respond with Atom Syndication Format XML representation as defined in the OSLC Core Representations Guidance
  • If supported, the Atom Syndication Format XML representation SHOULD use RDF/XML representation without restrictions for the atom:content entries representing the resource representations.

Authentication

See OSLC Core Authentication section. This specification puts no additional constraints on authentication.

Error Responses

See OSLC Core Error Responses section. This specification puts no additional constraints on error responses.

Pagination

Reconciliation Providers SHOULD support pagination of query results and MAY support pagination of a single resource’s properties as defined by the OSLC Core Specification.

Labels for Relationships

Relationships to other resources are represented as properties whose values are the URI of the object or target resource. When a relationship property is to be presented in a user interface, it may be helpful to provide an informative and useful textual label for that relationship instance. (This in addition to the relationship property URI and the object resource URI, which are also candidates for presentation to a user.) OSLC Core Links Guidance allows OSLC providers to support a dcterms:title link property in resource representations, using the anchor approach (reification), but this specification discourages its use (providers SHOULD NOT use it, and consumers SHOULD NOT depend on it). At the time this specification was written, the W3C RDF working group was on a path to remove reification from the next version of RDF, and it was noted that reification never was normatively defined even in the RDF/XML syntax W3C Recommendation, where it occurs informatively.

Resource Definitions

Resources defined by this specification can have properties other than those described here, in any namespace. It is RECOMMENDED that any additional properties exist in their own unique namespace and not use the namespaces defined in this specification.

A list of properties is defined for each type of resource. Most of these properties are identified in OSLC Core Appendix A: Common Properties and in the Common IT Resource Type vocabulary. Any exceptions are noted. Relationship properties refer to other resources. These resources may be in any OSLC domain (including the Reconciliation domain).

For all resource types defined in this specification, all required properties (those defined with an occurrence of exactly-one or one-or-many) MUST exist for each resource and must be provided when requested. All other properties are optional, and might not exist on some or any resources; those that do not exist will not be present in the returned representation even if requested, while those that do exist MUST be provided if requested. Providers MAY define additional provider-specific properties; providers SHOULD use their own namespaces for such properties, or use standard Dublin Core or RDF namespaces and properties where appropriate.

If no specific set of properties is requested, all properties MUST be returned - both those defined in this specification as well as any provider-specific ones. See Selective Property Values in the OSLC Core Specification.

Consumers should note that some resources may have a very large number of related resources, and that some resources may be very large and/or expensive to compute. For this reason, consumers are strongly RECOMMENDED to use the oslc.properties parameter to limit the properties returned from a request to the subset required. See Selective Property Values in the OSLC Core Specification.

Resource: Asset

  • Name: Asset
  • Description: Any artifact that is viewed as having economic value and as property of a person, association, corporation or estate.
  • Type URI http://open-services.net/ns/crtv#Asset

Asset Properties

Prefixed Name Occurs Read-only Value-type Representation Range Description
OSLC Reconciliation: Start of additional properties
crtv:assetTag zero-or-one False String n/a n/a Specifies the asset tag for a physical piece of equipment. Asset tags are typically human readable labels that are durable and securely attached to equipment. Asset tags may also be readable by barcode and/or RFID.
crtv:manufacturer zero-or-one False String n/a n/a Name of the equipment manufacturer.
crtv:model zero-or-one False String n/a n/a Value of the device model. The model number as provided by the equipment manufacturer.
crtv:serialNumber zero-or-one False String n/a n/a Serial number assigned by the manufacturer.

Additional requirements

Reconcilable resources of this type MUST contain at least 1 set of properties in the bulleted list below. All properties within a single bullet point (row) must contain a value in order to be valid. Multiple bullet points (rows) MAY be satisfied.

  • crtv:assetTag, crtv:manufacturer, crtv:model, crtv:serialNumber

You MUST NOT use an informational value such as “Unknown” or “Not Available” for any of these bulleted properties. Populate a property only from administrative or configuration information read from the device itself. If you are unable to obtain such information, do not populate the property at all.

crtv:assetTag

You SHOULD provide the value of the asset tag as it is shown on the physical device. Do not include leading or trailing spaces.

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.

crtv:model

The model number SHOULD be normalized according to the following rules: use alphanumeric characters only; provide alphabetic characters in upper-case; do not use punctuation or special characters, including spaces and hyphens; do not use the manufacturer name;d o not include leading or trailing spaces.

crtv:serialNumber

The value SHOULD be as it is provided by the manufacturer of the resource, with the following transformations applied: do not use any punctuation or special characters (including spaces); use all alphanumeric characters in uppercase; and do not include the manufacturer or model number with this property value. Do not include leading or trailing spaces.

Resource: ComputerSystem

  • Name: ComputerSystem
  • Description: An intelligent device, such as a computer, that can perform computing, data collection, and/or communication operations. This category includes ( but is not limited to ) general purpose computers, such as laptops, servers, and virtual machines; computers with specific functions, such as Networking and Storage hardware, Voice over IP Telephony devices, HVAC systems; monitoring data collection devices in buildings, automobiles, or electronic grids.
  • Type URI http://open-services.net/ns/crtv#ComputerSystem

ComputerSystem Properties

Prefixed Name Occurs Read-only Value-type Representation Range Description
OSLC Reconciliation: Start of additional properties
crtv:manufacturer zero-or-one False String n/a n/a Name of the device manufacturer.
crtv:model zero-or-one False String n/a n/a Value of the device model. The model number as provided by the device manufacturer.
crtv:serialNumber zero-or-one False String n/a n/a Serial number assigned by the manufacturer. The value should be provided by the manufacturer of the resource.
crtv:systemBoardUUID zero-or-one False String n/a n/a The unique identifier of the system board.
crtv:vmid zero-or-one False String n/a n/a The VMID is a unique identifier for a virtual machine.
crtv:hostid zero-or-one False String n/a n/a A globally unique ID assigned to their machines by some manufacturers (.e.g Sun Solaris).
crtv:shortHostname zero-or-many unspecified String n/a n/a A label assigned to a machine and used for communications on the local network.
crtv:fqdn zero-or-many unspecified String n/a n/a The fully qualified domain name (FQDN). In Internet communications, the name of a host system that includes all of the subnames of the domain name.
crtv:ipAddress zero-or-many unspecified Resource Reference any an IP address assigned to this system. Typically refers to a resource of type crtv:IPAddress but it MAY refer to other resource types.

Additional requirements

Reconcilable resources of this type MUST contain at least 1 set of properties in the bulleted list below. All properties within a single bullet point (row) must contain a value in order to be valid. Multiple bullet points (rows) MAY be satisfied.

  • crtv:hostid, crtv:vmid
  • crtv_hostid, NOT vmid
  • crtv:manufacturer, crtv:model,crtv:serialNumber, crtv:vmid
  • crtv:manufacturer, crtv:model,crtv:serialNumber, NOT crtv:vmid
  • crtv:systemBoardUUID
  • (set of) crtv:fqdn
  • (set of) crtv:ipAddress

You MUST NOT use an informational value such as “Unknown” or “Not Available” for any of these bulleted properties. Populate a property only from administrative or configuration information returned from the system itself. If you are unable to obtain such information, do not populate the property at all.

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). If you do not have access to WMI, use the list of manufacturers from CRTV. On Linux Intel machines, use the raw output from dmidecode (value of Manufacturer: field). If you do not have access to dmidecode, use the list of manufacturers from CRTV. 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.

Resource: Database

  • Name: Database
  • Description: An organized collection of digital data that is managed by a database management system (DBMS).
  • Type URI http://open-services.net/ns/crtv#Database

Database Properties

Prefixed Name Occurs Read-only Value-type Representation Range Description
OSLC Reconciliation: Start of additional properties
crtv:name zero-or-one False String n/a n/a The name assigned to the database by the database administrator.
crtv:dbInstance zero-or-many False Resource Reference any The database instance that manages this database. Typically refers to a resource of type crtv:SoftwareServer but it MAY refer to other resource types.

Additional requirements

Reconcilable resources of this type MUST contain at least 1 set of properties in the bulleted list below. All properties within a single bullet point (row) must contain a value in order to be valid. Multiple bullets may be satisfied.

  • name, (set of) dbInstance
crtv:name

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

Resource: IPAddress

  • Name: IPAddress
  • Description: Represents an IP address, either IPv4-based or IPv6-based.
  • Type URI http://open-services.net/ns/crtv#IPAddress

IPAddress Properties

Prefixed Name Occurs Read-only Value-type Representation Range Description
OSLC Reconciliation: Start of additional properties
crtv:address exactly-one False String n/a n/a The canonical string representation of the IP address.
crtv:contextAddressSpace zero-or-one False Resource Reference any the anchor IP address for an IPAddress in a Network Address Translation (NAT) scenario, that is IPv4 addresses within the set of IANA privately defined address ranges of 10.0.0.0 - 10.255.255.255, 172.16.0.0 - 172.31.255.255, 192.168.0.0 - 192.168.255.255 . Typically refers to a resource of type crtv:IPAddress but it MAY refer to other resource types.

Additional Requirements

Reconcilable resources of this type MUST contain at least 1 set of properties in the bulleted list below. All properties within a single bullet point (row) must contain a value in order to be valid. Multiple bullets may be satisfied.

  • crtv:address, crtv:contextAddressSpace
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 a 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 tunnelling 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”.

Resource: Path

  • Name: Path
  • Description: Path represents individual components of a directed graph of resources, where specific ordering is necessary to preserve a graph. Examples of such directed graphs are the representation of workflows or processes.
  • Type URI http://open-services.net/ns/crtv#Path

Path Properties

Prefixed Name Occurs Read-only Value-type Representation Range Description
OSLC Reconciliation: Start of additional properties
crtv:elementFrom exactly-one False Resource Reference any The resource acting as the origination point in the ordered path.
crtv:elementTo exactly-one False Resource Reference any The resource acting as the destination point in the ordered path.
crtv:occursBefore zero-or-one False Resource Reference any If there is a temporal order between other Path or ServiceInstance Resource Definitions, the Resource Definition action that occur after this Resource Instance are listed here.

Additional Requirements

Reconcilable resources of this type MUST contain at least 1 set of properties in the bulleted list below. All properties within a single bullet point (row) must contain a value in order to be valid. Multiple bullets may be satisfied.

  • crtv:elementFrom, crtv:elementTo, crtv:occursBefore

Resource: ServiceInstance

  • Name: ServiceInstance

  • Description: A Service Instance is the representation of a service offering that was selected by the customer and then instantiated for that specific customer. Service Instances are supported by definite and measurable warranties or guarantees that the expected level of service/value will be met. It is common to group or nest ServiceInstances together to form a service hierarchy.

  • Type URI http://open-services.net/ns/crtv#ServiceInstance

ServiceInstance Properties

Prefixed Name Occurs Read-only Value-type Representation Range Description
OSLC Reconciliation: Start of additional properties
crtv:name exactly-one False String n/a n/a The name assigned by the organization that owns and supports this ServiceInstance.
crtv:parentServiceInstance zero-or-one unspecified Resource Reference any In cases where services are organized in a hierarchy, this refers to the service that is immediately higher in the hierarchy. Typically refers to a resource of type crtv:ServiceInstance but it MAY refer to other resource types.

Additional Requirements

Reconcilable resources of this type MUST contain at least 1 set of properties in the bulleted list below. All properties within a single bullet point (row) must contain a value in order to be valid. Multiple bullets may be satisfied.

  • crtv:parentServiceInstance, crtv:name
crtv:name

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

Guidance

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.

ServiceInstance category URIs

The following set of RDFS classes serve 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.

Resource: ServerAccessPoint

  • Name: ServerAccessPoint
  • Description: A network endpoint, i.e. the combination of IP address and port number that clients connect to when accessing a server.
  • Type URI http://open-services.net/ns/crtv#ServerAccessPoint

ServerAccessPoint Properties

Prefixed Name Occurs Read-only Value-type Representation Range Description
OSLC Reconciliation: Start of additional properties
crtv:ipAddress zero-or-one False Resource Reference any The specific IP address which the ServerAccessPoint uses. Typically refers to a resource of type crtv:IPAddress but it MAY refer to other resource types.
crtv:portNumber zero-or-one False String n/a n/a the port number as defined by IETF and IANA

Additional Requirements

Reconcilable resources of this type MUST contain at least 1 set of properties in the bulleted list below. All properties within a single bullet point (row) must contain a value in order to be valid. Multiple bullets may be satisfied.

  • crtv:portNumber, crtv:ipAddress

Resource: SoftwareServer

  • Name: SoftwareServer
  • Description: Represents an instance of software that participates in hosting a particular application.
  • Type URI http://open-services.net/ns/crtv#SoftwareServer

SoftwareServer Properties

Prefixed Name Occurs Read-only Value-type Representation Range Description
OSLC Reconciliation: Start of additional properties
crtv:name zero-or-one False String n/a n/a The name assigned by an administrator .
crtv:serverAccessPoint zero-or-many False Resource Reference any The Server Access Point clients use for communications with this resource. Typically refers to a resource of type crtv:ServerAccessPoint but it MAY refer to other resource types.
crtv:instancePath zero-or-one False String n/a n/a The directory where the files for this SoftwareServer are stored.
crtv:runsOn zero-or-one False Resource Reference any The system this SoftwareServer instance is running on. Typically refers to a resource of type crtv:ComputerSystem but it MAY refer to other resource types.

Additional Requirements

Reconcilable instances of this type MUST contain at least 1 set of properties in the bulleted list below. All properties within a single bullet point (row) must contain a value in order to be valid. Multiple bullets may be satisfied.

  • crtv:name, crtv:instancePath, crtv:runsOn
  • crtv:name, (set of) crtv:serverAccessPoint
  • crtv:name, crtv:runsOn
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.

SoftwareServer category URIs

The following set of RDFS classes serve 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 a 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 DB2 server.
http://open-services.net/ns/crtv#OracleInstance This SoftwareServer is a 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.

Resource: SoftwareModule

  • Name: SoftwareModule
  • Description: Represents packaged components that are deployed to a SoftwareServer.
  • Type URI http://open-services.net/ns/crtv#SoftwareModule

SoftwareModule Properties

Prefixed Name Occurs Read-only Value-type Representation Range Description
OSLC Reconciliation: Start of additional properties
crtv:deployedTo zero-or-one False Resource Reference any The application server on which this SoftwareModule is deployed. Typically refers to a resource of type crtv:SoftwareServer but it MAY refer to other resource types.
crtv:fileName zero-or-one False String n/a n/a The file name of the package containing the SoftwareModule.
crtv:name zero-or-one False String n/a n/a The name of the SoftwareModule.

Additional Requirements

Reconcilable resources of this type MUST contain at least 1 set of properties in the bulleted list below. All properties within a single bullet point (row) must contain a value in order to be valid. Multiple bullets may be satisfied.

  • crtv:deployedTo, crtv:name, crtv:fileName
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.

SoftwareModule category URIs

The following set of RDFS classes serve 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 MQ Queue

Resource pool categories

OSLC services providers can represent pools of shared resources (e.g. a set of shared database connections) using the rdfs:Container resource definition. To help in categorizing these pools, the following RDFS classes are defined

URI Description
http://open-services.net/ns/crtv#ThreadPool a set of shared threads
http://open-services.net/ns/crtv#DatabasePool a set of shared database connections
http://open-services.net/ns/crtv#J2CConnectorPool a set of shared J2C connections

Reconciliation Service Provider Capabilities

Service Discovery and Description

Resource Shapes

Reconciliation service providers MAY support Resource Shapes as defined in OSLC Core Specification Appendix A

Service Provider Resource

Reconciliation service providers MUST provide a Service Provider Resource that can be retrieved at a implementation dependent URI.

Reconciliation service providers MAY provide a Service Provider Catalog Resource that can be retrieved at a implementation dependent URI.

Reconciliation service providers MUST provide a oslc:serviceProvider property for their defined resources that will be the URI to a Service Provider Resource.

Creation Factories

If an OSLC Reconciliation service provider supports the creation of resources, there MUST be at least one Creation Factory entry in its Services definition.

See the HTTP Method support table for further clarification on support for HTTP methods and media types for each OSLC resource.

Query Capabilities

There SHOULD be at least one Query Capability entry in the Services definition.

If provided, the Query Capability MUST support the oslc:where parameter and SHOULD support the oslc:select parameter:

If shape information is NOT present with the Query Capability, service providers SHOULD use the default properties defined in OSLC Core RDF/XML Examples to contain the result.

Delegated UIs

Reconciliation service providers MAY support the selection of reconcilable and reconciled resources as defined by Delegated UIs in OSLC Core.

Service Provider HTTP Method Support

Support for all HTTP methods in the compliance table is not required for all resources. The following table summarizes the requirements for each HTTP method, and media type combination. A value of N/A means this specification does not impose any constraints on it.

Resource RDF/XML XML JSON HTML Compact XML Other
GET MUST MAY SHOULD SHOULD N/A N/A
PUT MAY MAY MAY N/A N/A N/A
POST MAY MAY MAY N/A N/A N/A
DELETE N/A N/A N/A N/A N/A N/A

Reconciliation service providers SHOULD support deletion of any resources for which they allow creation.

Appendix A: Samples

(this section is informative)

See OSLC Reconciliation Version 2.0 Appendix A: Samples

Appendix B: Resource Shapes

(this section is informative)

See OSLC Reconciliation Version 2.0 Appendix B: Resource Shapes

Appendix C: Notices and References

Contributors

Reporting Issues on the Specification

The working group participants who author and maintain this working draft specification, monitor a distribution list where issues or questions can be raised, see Reconciliation Workgroup Mailing List

Also the issues found with this specification and their resolution can be found at OSLC Reconciliation Version 2.0 Issues.

Authors and Contact Information

Intellectual Property Covenant

The members of the Working Group (or as appropriate, their employers) have documented a Patent Non-Assertion Covenant and/or Patent License for implementations of the Reconciliation Workgroup 2.0 Specification, as described in the open-services.net Terms of Use.

References