|This page describes the COI Resource Registry. Please also check Resource and Object Model for context and see all child pages.|
The COI Resource Registry provides services to describes resources under OOI governance as introduced here. Capabilities include:
- Identifying resources uniquely in the system
- Defining types of resources
- Relating types of resources, such as to create inheritance trees or versions of type definitions
- Defining the structure of resource descriptions
- Persisting resource descriptions flexibly and efficiently
- Cross referencing resources
- Enabling flexible search and query of resources
- Managing the life cycle of resources uniformly with extensibility for specific types of resources
The figure below illustrates how resources are kept in the resource registry. Every resource in the system has a unique identifier. Resources have current state. The underlying datastore maintains previous revisions of the resource objects. Associations are used to reference resources by unique ID. It is either possible to reference the head revision of a resource or a specific revision of a resource.
Figure 1. Illustration of Resource Registry Concepts (OV-1)
Resource identifiers (IDs) are uniquely identifying a resource instance in the system.
|In R2 LCA, resource IDs are uuid4 strings, hex encoded, with lowercase letters and no additional separators.|
The goal is to have resource identifiers that are
- unique: every resource instance has a different resource identifier
- unambigous: there are no 2 identifiers or identifier representations for the same resource instance
- indicate the type of resource: ID verification should be possible by type without a registry lookup
- indicate the instance of the system: ID verification should be possible by type without a registry lookup
- can be looked up by URL: a user can use the resource ID as a valid URL in a browser
See here for an overview.
Associations are first class information objects in the system that reference 2 resources. Associations belong to neither of the two resources they associate and can be managed (i.e. defined, created, owned, manipulated and deleted) independently.
Associations provide the following information:
- A subject resource. The resource from which the association logically originates from
- An object resource. The resource to which the association logically points at
- A predicate. A verb determining the interpretation of the association, e.g. "hasModel" or "ownedBy"
- Additional association metadata, including creation timestamp, keywords and ordinal
Associations are immutable once created. They can be retired if no longer needed, leaving the association intact, but rendering it invisible for all user purposes of the system.
Associations follow a schema definition. The system will only create permissible associations. The schema defines:
- Permissible types of subject resources for a predicate. Base types can be used, enabling the association for all specializations of this base type.
- Permissible types of object resources for a predicate. Base types can be used, enabling the association for all specializations of this base type.
- Multiplicity of associations for a predicate, e.g. 1:1, 1:n, n:1, n:n etc.
- CIAD COI OV Associations - for details about associations.
Every resource has one of the visibility levels listed in the table below. Visibility affects which actors can find a resource by metadata or association through the resource registry or higher level services such as discovery. System superusers (ION_MANAGER role and system actors can always see all resources, independent of the visibility level.
|Level name||Level code||Description|
|PUBLIC||1||The resource is visible to any actor in the system, including anonymous (unregistered or not signed in) users|
|REGISTERED||2||The resource is visible to any registered and signed in actor|
|FACILITY||3||The resource is visible to all actors that are member in at lease one facility (Org) that the resource is shared in|
|OWNER||4||The resource is visible to the actor that owns the resource (and to superusers)|
See here for overview respectively details:
- CIAD OV Resource and Object Model - general overview
- CIAD COI OV Resource Lifecycle - resource lifecycle details
Resources can be manipulated directly through the Capability Container's resource registry datastore interface.
Services that operate on resources remotely, and provide higher level functions include:
- The CIAD COI OV Resource Registry Service provides a service API for the resource registry, accessible remotely, where no direct connection to the resource registry datastore exists or is not permissible.
- The CIAD COI OV Resource Management Service provides higher level functions to operate on resources, such as the capabilities to define new resource types, or new resource type lifecycle workflows. This service also provides generic interfaces to manipulate resources of any type, without knowing details about their type. In particular, it provides an agent interface on any kind of resource.
A resource represents a physical or electronic entity within the system. This entity is characterized by metadata. Other information can be computed about a resource. Metadata is persisted in the datastore, computed attributes are evaluated and set when a resource is read by a specific service. Both persisted and computed attributes are represented as attributes in the resource specification.
Computed attributes will be calculated by the service responsible for the underlying associated resource, for example, the Instrument Management Service is responsible for managing the InstrumentDevice persisted resource, so therefore the associated calculated attributes would be fulfilled by the same service but the underlying resource framework will handle the mechanics. The set of computed attributes are defined in a standard YAML object and must extend from the object ComputedAttributes and will be associated to the underlying resource using an extended resource object defined in YAML which must extend from the ResourceContainer object. Both objects utilize decorators within the YAML definition which specify how the values are determined, either from a method or based off an association specified in the YAML as well.
The base ResourceContainer object contains the fields resource and computed which will be set to the underlying resource object and specific computed attribute object, respectively.
The following illustrates the fields which are common to all extended resources which are considered ExtendedInformationResource or ExtendedTaskableResource objects.
The following is an example of a computed attribute object:
The following is an example of an extended resource object used to contain the persisted resource, the computed attributes and can also include other extended attributes based on associations or other information provided by the service.
The service will use the underlying ExtendedResourceContainer class which is available in the container which has a single factory type method:
which returns the extended resource object containing the underlying persisted resource and optional computed attributes as well as any other extensions specified in the yaml files.
And a comparable version for submitting a list of IDs of the same extended resource type, which returns a list of the resultant extended resources:
The Extended Resource framework supports the following yaml decorators:
|| This decorator is used to set the value of a field to a list of objects, a single object or the count of associations, depending on the default value of the field; a list, resource object or int, respectively. This decorator requires a valid association to be specified.
If this decorator is a compound association, meaning a set of associations, then one or two filters can be specified which will be used to limit the number of associations to the ones that match the specified types.
|| This decorator is used to set the value of a field to the value of a function, which must be implemented by the resource framework or the service calling the resource framework. If the name of the method is not specified as a name/value pair then the name of the function will be the name of the field appended to "get_"; for example, get_software_version. A method name using dot notation implies a remote method call using messaging.
All methods specified in the YAML code should be prepared to take a resource id as a parameter for the underlying reference and must return the value as specified in the yaml file. For example:
| YAML Definition
| def get_location(self, resource_id):
| This version requires that the local method must be named the same as the field name.
data_produced: "" # the URL of the data location
| def get_data_url(self,resource_id):
return "http://iontest/data/" + instrument_device_id
| This version allows local method can be named differently than the field name.
user_subscriptions:  # Users subscribed to this resource
| def get_subscription(self,resource_id, user_id):
| This version means the method is not local to the process but will use messaging to make the request to the remote method. It uses the standard <process name>.<method name>
| N/A - handled by framework - sets the field to the first associated object found or to None if no associated object found
|| This should only be used for 1:1 or 1:0..1 associations. For 1..n associations it non-deterministically chooses one of the associated resources and ignores the rest (a warning will be logged). In most cases this is not anticipated
Order in which the associations are processed:
policies:  # A list of policies associated with the underlying resource
|N/A - handled by framework - sets the field to the list of associated objects.|
policy_count: 0 # The number of associated policies
|N/A - handled by framework - sets the field to the count of associated objects.|
| N/A - handled by framework - sets the field to the first associated object found that is of type PlatformSite or InstrumentSite
||One or more specific resource types can be listed here. These must be the actual types of associated resources, not base types.|
|N/A - handled by framework - sets the field to the first associated object found when traversing associations in object/child direction (">") or subject/parent direction ("<")||Can be combined with types|
Any methods returning data as Computed Attributes must have a signature where the first parameter is the id of the specified resource. Additional parameters can be passed to computed methods, but they must follow the first parameter: for example:
The extended resource framework will pass the resource_id of the requested resource as the first parameter to any computed method and all subsequent parameters must be passed in as name=value pairs as the trailing parameters to the create_extended_resource_container() method call as the last parameter(s). An example is as follows: