// ==================================================================
// Title:       Metrics MOF Specification 2.8, Unit of Work Metrics
// Author:      DMTF Application Working Group
// Filename:    Metrics28_UnitofWork.MOF
// Version      2.8.0
// Status:      Final
// Date:        Jan 26, 2004
// ===================================================================
// Copyright 2001-2003 Distributed Management Task Force, Inc. (DMTF).
// All rights reserved.
// DMTF is a not-for-profit association of industry members dedicated
// to promoting enterprise and systems management and interoperability.
// DMTF specifications and documents may be reproduced for uses
// consistent with this purpose by members and non-members,
// provided that correct attribution is given.
// As DMTF specifications may be revised from time to time,
// the particular version and release date should always be noted.
// 
// Implementation of certain elements of this standard or proposed
// standard may be subject to third party patent rights, including
// provisional patent rights (herein "patent rights"). DMTF makes
// no representations to users of the standard as to the existence
// of such rights, and is not responsible to recognize, disclose, or
// identify any or all such third party patent right, owners or
// claimants, nor for any incomplete or inaccurate identification or
// disclosure of such rights, owners or claimants. DMTF shall have no
// liability to any party, in any manner or circumstance, under any
// legal theory whatsoever, for failure to recognize, disclose, or
// identify any such third party patent rights, or for such party's
// reliance on the standard or incorporation thereof in its product,
// protocols or testing procedures. DMTF shall have no liability to
// any party implementing such standard, whether such implementation
// is foreseeable or not, nor to any patent owner or claimant, and shall
// have no liability or responsibility for costs or losses incurred if
// a standard is withdrawn or modified after publication, and shall be
// indemnified and held harmless by any party implementing the
// standard from any and all claims of infringement by a patent owner
// for such implementations.
// 
// For information about patents held by third-parties which have
// notified the DMTF that, in their opinion, such patent may relate to
// or impact implementations of DMTF standards, visit
// http://www.dmtf.org/about/policies/disclosures.php.
// ===================================================================
// Description: This Schema includes the object classes required to
// model
//          CIM's Unit of Work Metrics, specifically the concepts
//          of UnitOfWork (executing and definitional), the metrics
//          associated with UnitsOfWork, and the relationships necessary
//          to associate definitions and metrics to an executing
//          UnitOfWork and to associate UnitsOfWork to
//          LogicalElements.
// 
//          The object classes below are listed in an order that
//          avoids forward references. Required objects, defined
//          by other working groups, are omitted.
// ===================================================================
// CHANGE HISTORY
//    CIM 2.8 (Final) - None
//    CIM 2.8 (Preliminary) - None
// 
//    CIM 2.7.0 Final (12 February 2003)
//       CR 987: remove experimental qualifier from
//          -CIM_UnitOfWorkDefinition.TraceLevelTypeId
//          -CIM_TraceLevelType
//          -CIM_UnitOfWork.TraceLevel
//          -CIM_UnitOfWork.MutualContextId
//          -CIM_UoWDefTraceLevelType
// 
//    CIM 2.7.1 Preliminary (12 November 2002)
//       CR 920: Add missing parenthesis to the Description for
//           TraceLevelType.BaseType
// 
//    CIM 2.7.0 Preliminary ( 6 June 2002)
//       CR 818: Add TraceLevel functionality with following changes:
//           uint16 CIM_UnitOfWork.TraceLevel
//           string CIM_UnifOfWorkDefinition.TraceLevelTypeId
//           class CIM_TraceLevelType
//           Association between UnitOfWorkDefinition and TraceLevelType
//       CR 819: Add MutualContextID to UnitOfWork. The context
//           is defined as an individual action several UnitOfWork
//           instances participate in.
//       CR 820: MetricDefinition: inheritance changed to
//           BaseMetricDefinition, deleted inherited properties and
//           restricted inherited key to MaxLen(16) for compatibility
//       CR 864: Change the superclassing and reference names of the
//           UoWDefTraceLevelType association
// 
//    CIM 2.6.0 (Final) Feb 15 2002
//       CR636 - Replaced the Weak Qualifier from the association
//          StartedUoW that was removed in error in Version 2.5
//       CR746- Add Version Qualifier to all classes with version 2.6.0
//              per TC agreement to start versioning in 2.6 Final.
// 
//    CIM 2.6.0 Preliminary and earlier change definitions (May 2001)
//         Fixed UnitOfWork.UoWDefId Propagated qualifier class name
//         Removed the Weak qualifier from the association StartedUoW
//         Fixed some descriptions
//         Removed Required qualifier from MetricDefinition.Name,
//              UnitOfWorkDefinition.Name, UnitOfWorkDefinition.Context
//         --> (the rest of this list were changes made 01 Feb 2000 but
//         -->  not incorporated into DAP24.MOF due to an oversight)
//         Fixed pragma Locale string
//         Corrected subclassing of CIM_MetricDefinition and
//              CIM_UnitOfWork (now subclassed from CIM_ManagedElement)
//         Fixed grammatical and formatting errors in Descriptions
//         Provided information in Descriptions on why associations
//              were defined as Dependencies
//         Provided Descriptions where they were missing
//         Added MaxLen (16) to String Id in UnitOfWorkDefinition
//              and in MetricDefinition, to enforce the semantics of
//              the Description
//         Also added MaxLen (16) to UoWDefId, where the UnitOf
//              WorkDefinition Id property is propagated to UnitOfWork
//         Removed the Weak qualifier from the association,
//              UoWMetricDefinition, and also the Max (1) restriction
//              (the latter allows reuse of Metrics)
//         Removed Min (0) from the association, SubUoW, since this
//              is the default definition
// 
// ==================================================================

#pragma Locale ("en_US")


// ==================================================================
// UnitOfWorkDefinition
// ==================================================================
   [Version ( "2.7.0" ), Description (
       "A LogicalElement that describes units of work (e.g. "
       "transactions). This class represents the definitional "
       "components of a unit of work, and not the unit itself.")]
class CIM_UnitOfWorkDefinition : CIM_LogicalElement {

      [Override ( "Name" ), Description (
          "The name of the Definition. This name does not have to be "
          "unique, but should be descriptive. It may contain blanks.")]
   string Name;

      [Description (
          "A free format string describing the context of the defined "
          "UnitOfWork. For example an 'Add Order' Unit could be "
          "defined in the context of a book ordering application, "
          "whereas another 'Add Order' UnitOfWork could be defined for "
          "a computer ordering application. It may contain blanks.")]
   string Context;

      [Key, Description (
          "A 16 byte value that uniquely identifies the UnitOfWork "
          "Definition. The use of OSF UUID/GUIDs is recommended."), 
       MaxLen ( 16 )]
   string Id;

      [Description (
          "A 16 byte value that uniquely identifies the applied "
          "semantics and format of the trace levels used in the "
          "instances of UnitOfWork. The use of OSF UUID/GUIDs is "
          "recommended. \n"
          "TraceLevelTypeId allows management applications to "
          "efficiently discriminate between different trace level "
          "semantics of different UnitOfWorkDefinitions. I.E., "
          "CIM_UnitOfWork.TraceLevel = 1 may have different semantics "
          "if TraceLevelTypeId is different for the respective "
          "instances of UnitOfWork. \n"
          "It is not assumed that different trace level semantics are "
          "used within the same UnitOfWorkDefinition in order to "
          "promote uniform trace level encodings. (Keep in mind: At "
          "least the developers of the business actions represented by "
          "the same UnitOfWorkDefinition instance should strive to use "
          "the same trace level encoding, otherwise the administrator "
          "will have a hard time to figure out what detailed "
          "information to expect.) \n"
          "If the string is empty no traces are expected to be "
          "produced. If the string is not empty, an associated "
          "instance of TraceLevelType may be attached to the "
          "UnitOfWorkDefinition instance. Still, it is useful to "
          "incorporate TraceLevelTypeId into UnitOfWorkDefinition, to "
          "relate to an instance of TraceLevelType. The management "
          "application can more easily detect different trace level "
          "types."), 
       MaxLen ( 16 ), 
       ModelCorrespondence { "CIM_TraceLevelType.InstanceId" }]
   string TraceLevelTypeId;
};


// ==================================================================
// MetricDefinition
// ==================================================================
   [Version ( "2.7.0" ), Description (
       "The metrics that are associated with a UnitOfWork. These "
       "metrics usually describe some aspect of a UnitOfWork such as "
       "how much work was done, or the size of the UnitOfWork. For "
       "example, the size of a print job or the number of pages "
       "printed could be metrics of a 'print' UnitOfWork.")]
class CIM_MetricDefinition : CIM_BaseMetricDefinition {

      [Override ( "Id" ), Description (
          "A 16 byte value that uniquely identifies the Metric "
          "Definition. The use of OSF UUID/GUIDs is recommended."), 
       MaxLen ( 16 )]
   string Id;

      [Description (
          "An enumerated value describing when the Metric may be "
          "considered valid. Some metrics are valid only at the "
          "beginning of a transaction (e.g., bytes to print), while "
          "the transaction is running (e.g., percent complete), or "
          "when the transaction is finished (e.g., pages printed). If "
          "a metric is valid at more than one of the enumerated "
          "values, such as both when the unit of work starts and when "
          "it stops, it is recommended to not use Validity."), 
       ValueMap { "1", "2", "3" }, 
       Values { "At Start", "In Middle", "At Stop" }]
   uint16 Validity;
};


// ==================================================================
// TraceLevelType
// ==================================================================
   [Version ( "2.7.0" ), Description (
       "TraceLevelType defines the encoding and semantics of trace "
       "levels. A trace is data that is produced during the execution "
       "of program code in order to provide information on the "
       "behaviour of the code (e.g. textual data written to files). "
       "Traces may be used for error detection/analysis or debugging. "
       "Trace levels define the granularity and/or type of the traces "
       "that are to be produced by the program code. Depending on the "
       "program implementation, levels may be applied on the fly. The "
       "possible levels are also implementation dependent, since no "
       "general rules or standards exist. In consequence, program "
       "developers could reuse their existing trace level scheme. \n"
       "Traces are valuable information sources for management "
       "applications in cases of error detection/analysis. In order to "
       "correctly set trace levels to the level needed (exciting "
       "exhaustive tracing by accident may result in significant "
       "system resources consumption in terms of processing time and "
       "storage) and to efficiently interpret which level of detail to "
       "expect from traces already produced by some resource, the "
       "possible trace level values and their meaning (semantics) must "
       "be known by the user and/or the management application. The "
       "type does not define the location or access method of the "
       "traces, since traces of a particular type can have multiple "
       "locations as well as multiple access methods.")]
class CIM_TraceLevelType : CIM_ManagedElement {

      [Key, Description (
          "A 16 byte value that uniquely identifies the trace level "
          "type. The use of OSF UUID/GUIDs is recommended."), 
       MaxLen ( 16 ), 
       ModelCorrespondence { 
          "CIM_UnitOfWorkDefinition.TraceLevelTypeId" }]
   string InstanceId;

      [Description (
          "Describes the technical encoding of the trace level. \n"
          "0: bit map = switches to turn on/off appropriate trace "
          "production (e.g. 0x00000010, 0x0000F000); the use of bit "
          "maps implies that the switches can be or-ed bitwise: "
          "Values[1] | Values[2] | ... . \n"
          "1: number = plain numbers that define levels (e.g. 1, 2, "
          "7); the recommended and most common encoding scheme \n"
          "2: any other encoding scheme you could think of (e.g. "
          "mixture of bit maps and numbers)."), 
       ValueMap { "1", "2", "3" }, 
       Values { "Other", "Bitmap", "Number" }]
   uint16 BaseType;

      [Required, Description (
          "Each entry in the array is one possible value of the trace "
          "level of this type. Depending on the base type, these are "
          "either switches defined as bit maps (e.g. 0x00000001, "
          "0x000000F0, ...) or plain numbers (1, 2, 3, ...). In either "
          "encoding, the value 0 is reserved for the equivalent of 'no "
          "trace'."), 
       ArrayType ( "Indexed" )]
   uint32 TraceValues[];

      [Required, Description (
          "The index corresponds to TraceLevelType.TraceValues[]. The "
          "array provides human-readable descriptions of the semantics "
          "of each value entered in the TraceValues array."), 
       ArrayType ( "Indexed" )]
   string ValueDescriptions[];
};


// ==================================================================
// UoWMetricDefinition
// ==================================================================
   [Association, Version ( "2.6.0" ), Description (
       "An association that describes the Metrics related to a "
       "UnitOfWorkDefinition. This is a Dependency relationship since "
       "the MetricDefinition relies on the UnitOfWorkDefinition for "
       "context. At least one context must be defined for a "
       "MetricDefinition, hence the Min (1) qualifier is placed on the "
       "UnitOfWorkDefinition reference.")]
class CIM_UoWMetricDefinition : CIM_Dependency {

      [Override ( "Antecedent" ), Min ( 1 ), Description (
          "The UnitOfWorkDefinition where the Metric applies.")]
   CIM_UnitOfWorkDefinition REF Antecedent;

      [Override ( "Dependent" ), Description (
          "The MetricDefinition for a particular UnitOfWork.")]
   CIM_MetricDefinition REF Dependent;
};


// ==================================================================
// UnitOfWork
// ==================================================================
   [Version ( "2.7.0" ), Description (
       "Each instance of UnitOfWork identifies a transaction that is "
       "either in-process or already completed. Because instances of "
       "'in-process' UnitsOfWork can be very short-lived and there can "
       "be a great number of active ones, use of this class as an "
       "instrumentation source for determining response time may be "
       "incorrect or inefficient, unless the rate and duration of the "
       "UnitsOfWork are known. The intended use is to respond to "
       "queries about currently active or recently completed "
       "UnitsOfWork. The length of time that a UnitOfWork instance "
       "exists after the UnitOfWork completes is not defined and "
       "should be assumed to be implementation-dependent. This class "
       "is weak to its definition (CIM_UnitOfWorkDefintion).")]
class CIM_UnitOfWork : CIM_ManagedElement {

      [Override ( "Description" ), Description (
          "Since UnitOfWork is designed to be an extremely lightweight "
          "object, it is recommended that this property not be used. "
          "The Description specified for the instance's associated "
          "CIM_UnitOfWorkDefintion should apply.")]
   string Description;

      [Key, Description (
          "The identifier of the UnitOfWork, within the context of the "
          "UnitOfWorkDefinition.")]
   sint64 Id;

      [Key, Propagated ( "CIM_UnitOfWorkDefinition.Id" ), Description (
          "A 16 byte value that uniquely identifies the UnitOfWork "
          "Definition. The use of OSF UUID/GUIDs is recommended."), 
       MaxLen ( 16 )]
   string UoWDefId;

      [Description (
          "The name of the user who initiated the UnitOfWork. This may "
          "be a real user's login name or a logical name representing "
          "an application.")]
   string UserName;

      [Description (
          "The time that the UnitOfWork was started.")]
   datetime StartTime;

      [Description (
          "The elapsed time since the UnitOfWork was started. Upon "
          "completion of the UnitOfWork, this property contains the "
          "total amount of time taken in processing the entire "
          "UnitOfWork.")]
   datetime ElapsedTime;

      [Description (
          "An enumeration identifing the status of the UnitOfWork. "
          "Most of the property values are self-explanatory, but a few "
          "need additional text: \n"
          "3=\"Completed\" - Should be used to represent a 'completed' "
          "transaction whose status ('good', 'failed' or 'aborted') is "
          "unknown. \n"
          "6=\"Completed Aborted\" - Should be used when a UnitOfWork "
          "has completed but was not allowed to end normally. An "
          "example would be when the Stop or Back buttons are selected "
          "from a web browser, before a page is fully loaded."), 
       ValueMap { "1", "2", "3", "4", "5", "6" }, 
       Values { "Active", "Suspended", "Completed", "Completed Good",
          "Completed Failed", "Completed Aborted" }]
   uint16 Status;

      [Description (
          "Indicates the granularity at which traces are written for "
          "this particular instance of UnitOfWork. Traces allow "
          "providing more detailed information on the course of the "
          "execution of the UnitOfWork than just the status and the "
          "elapsed time. The trace level does not indicate where the "
          "traces are found (i.e. in which file or CIM instances). "
          "TraceLevel cannot be set (i.e. written) since an instance "
          "of UnitOfWork only publishes information. So, the "
          "application code that executes the unit of work must "
          "receive the desired trace level by its caller (e.g. the "
          "parent module, the user or some remote system that "
          "initiates the unit of work). \n"
          "If its value is 0, no traces are available. If its value is "
          "> 0, traces are available. Except 0, the possible values "
          "and their semantics are implementation dependent. Two "
          "instances of UnitOfWork (even with the same definition) may "
          "have different trace levels since the desired or required "
          "granularity of traces may be dependent on the execution "
          "context (detection of an error, analysis of an error, etc.) "
          "of the unit of work. \n"
          "The trace level can be encoded as a bit map (each "
          "individual bit indicates a certain trace type and/or level "
          "of detail) or numbers (that are further defined by a value "
          "map). No encoding scheme is imposed since no general rules "
          "or standards exist and in consequence, application "
          "developers could reuse their existing trace level scheme.")]
   uint32 TraceLevel;

      [Description (
          "A string that uniquely identifies the mutual context of "
          "UnitOfWork instances. The context is defined as an "
          "individual action that several UnitOfWork instances "
          "participate in. The use of Ids such as OSF UUID/GUIDs is "
          "recommended, although some implementations may require "
          "longer Ids. (This is the reason why no maxlen(16) qualifier "
          "has been used.) \n"
          "MutualContextId explicitly identifies the context for "
          "instances of UnitOfWork, that is otherwise provided "
          "implicitly by SubUoW association instances. In addition, "
          "one can query directly (i.e. without following the "
          "associations) for UnitOfWork instances that participate in "
          "some individual action (i.e., the mutual context). If no "
          "mutual context is needed or if it is not supported by the "
          "implementation, the value is NULL. \n"
          "Note that the MutualContextId value is to be transferred "
          "internally between the participating UnitOfWork "
          "implementations such that each UnitOfWork instance "
          "implementation receives its value from its "
          "predecessor/parent or initially creates the value if it is "
          "the first instance of the context.")]
   string MutualContextId;
};


// ==================================================================
// UoWMetric
// ==================================================================
   [Association, Version ( "2.6.0" ), Description (
       "This association ties a MetricDefinition to an instance of a "
       "UnitOfWork. Its primary purpose is to specify the value of the "
       "Metric for the instance of UnitOfWork. It is defined as a "
       "Dependency since the Metric value relies on the specific "
       "UnitOfWork for context.")]
class CIM_UoWMetric : CIM_Dependency {

      [Override ( "Antecedent" ), Description (
          "The UnitOfWork whose Metric value is specified.")]
   CIM_UnitOfWork REF Antecedent;

      [Override ( "Dependent" ), Description (
          "The MetricDefinition for this particular UnitOfWork and "
          "value. Note that the MetricDefinition must be associated "
          "(via UoWMetricDefinition) to the same UnitOfWorkDefinition "
          "to which the UnitOfWork is weakly associated.")]
   CIM_MetricDefinition REF Dependent;

      [Description (
          "The value of the Metric for the referenced UnitOfWork. Note "
          "that the type of the data and other information are defined "
          "by the properties of MetricDefinition.")]
   string Value;
};


// ==================================================================
// StartedUoW
// ==================================================================
   [Association, Version ( "2.6.0" ), Description (
       "This association links a UnitOfWork (which is a 'started' "
       "transaction) to its Definition.")]
class CIM_StartedUoW : CIM_Dependency {

      [Override ( "Antecedent" ), Min ( 1 ), Max ( 1 ), Description (
          "The Definition object for the UnitOfWork.")]
   CIM_UnitOfWorkDefinition REF Antecedent;

      [Override ( "Dependent" ), Weak, Description (
          "An instance of a UnitOfWork that has started executing.")]
   CIM_UnitOfWork REF Dependent;
};


// ==================================================================
// LogicalElementUnitOfWorkDef
// ==================================================================
   [Association, Version ( "2.6.0" ), Description (
       "This association links a LogicalElement to the UnitsOfWork "
       "that it can perform. For example, a Printer Device may have "
       "associated UnitOfWorkDefinitions representing PrintJobs. This "
       "is a Dependency relationship since the Definitions are given "
       "context by the LogicalElement.")]
class CIM_LogicalElementUnitOfWorkDef : CIM_Dependency {

      [Override ( "Antecedent" ), Description (
          "The LogicalElement that is providing the UnitOfWork.")]
   CIM_LogicalElement REF Antecedent;

      [Override ( "Dependent" ), Description (
          "The UnitOfWorkDefinition associated with the "
          "LogicalElement.")]
   CIM_UnitOfWorkDefinition REF Dependent;
};


// ==================================================================
// SubUoWDef
// ==================================================================
   [Association, Version ( "2.6.0" ), Description (
       "This association defines the sub-UnitsOfWork (the sub- "
       "transactions) for a particular UnitOfWorkDefinition. For "
       "example, an 'AddOrder' UnitOfWork could have sub-Units of "
       "'ValidateCustomer', 'ValidatePartNumber', 'UpdateDatabase', "
       "etc. This is a Dependency relationship since the sub-UnitsOf "
       "Work are put in context relative to the parent Unit. It is not "
       "an aggregation relationship - since (using another example) a "
       "'DatabaseWrite' transaction is likely to be dependent upon a "
       "'DiskWrite', but the two transactions are separate concepts "
       "and one is not 'contained' by the other.")]
class CIM_SubUoWDef : CIM_Dependency {

      [Override ( "Antecedent" ), Description (
          "The parent UnitOfWorkDefinition.")]
   CIM_UnitOfWorkDefinition REF Antecedent;

      [Override ( "Dependent" ), Description (
          "The sub-UnitOfWorkDefinition.")]
   CIM_UnitOfWorkDefinition REF Dependent;
};


// ==================================================================
// LogicalElementPerformsUoW
// ==================================================================
   [Association, Version ( "2.6.0" ), Description (
       "This association identifies a specific execution of a UnitOf "
       "Work with the specific LogicalElement that is performing/ has "
       "performed it. Where the LogicalElementUnitOfWorkDef "
       "association describes what an Element can do, this "
       "relationship describes what a particular Element is doing or "
       "has done.")]
class CIM_LogicalElementPerformsUoW : CIM_Dependency {

      [Override ( "Antecedent" ), Description (
          "The LogicalElement performing the UnitOfWork.")]
   CIM_LogicalElement REF Antecedent;

      [Override ( "Dependent" ), Description (
          "The UnitOfWork being performed.")]
   CIM_UnitOfWork REF Dependent;
};

// ==================================================================
// SubUoW
// ==================================================================
   [Association, Version ( "2.6.0" ), Description (
       "Similar to the SubUoWDef association (which describes the "
       "relationship between definitional UnitsOfWork), this "
       "association identifies the executional UnitOfWork "
       "Dependencies. It associates executing/executed UnitsOfWork "
       "with their parent Units. In most cases, the SubUoW reflects "
       "the execution side of the relationship defined in SubUoWDef. "
       "However, there may be cases where the SubUoWDef is not "
       "defined, but for a particular UnitOfWork, the SubUoW "
       "relationship is valid. Therefore, it is not a requirement (but "
       "it is desirable) that there be a corresponding SubUoWDef for "
       "each instance of SubUoW.")]
class CIM_SubUoW : CIM_Dependency {

      [Override ( "Antecedent" ), Max ( 1 ), Description (
          "The parent executing/executed UnitOfWork. On the execution "
          "side, it is expected that a sub-Unit is associated with "
          "only one parent UnitOfWork.")]
   CIM_UnitOfWork REF Antecedent;

      [Override ( "Dependent" ), Description (
          "The sub-UnitOfWork. On the execution side, it is expected "
          "that a sub-Unit is associated with only one parent "
          "UnitOfWork.")]
   CIM_UnitOfWork REF Dependent;
};


// ==================================================================
// UoWDefTraceLevelType
// ==================================================================
   [Association, Version ( "2.7.0" ), Description (
       "Refers to the refinement of the UnitOfWorkDefinition: the "
       "trace level type. It is not required that a UnitOfWork be "
       "associated to a TraceLevelType. But if it is associated, only "
       "one Type can be specified for the Definition. In contrast, "
       "TraceLevelTypes can be reused for multiple Definitions.")]
class CIM_UoWDefTraceLevelType {

      [Key, Max ( 1 ), Description (
          "The trace level type description that is implemented by the "
          "UnitOfWorkDefinition.")]
   CIM_TraceLevelType REF TraceLevelType;

      [Key, Description (
          "The UnitOfWorkDefinition which is refined by the instance "
          "of TraceLevelType.")]
   CIM_UnitOfWorkDefinition REF UoWDefn;
};


// ===================================================================
// end of file
// ===================================================================
