// ==================================================================
// Title:       Metrics MOF Specification 2.7, Unit of Work Metrics
// Author:      DMTF Application Working Group
// Filename:    Metrics27_UnitofWork.MOF
// Version      2.7.0
// Status:      Final
// Date:        13 April 2003
// ===================================================================
// 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.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
//
//    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.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.7.1 Preliminary (12 November 2002)
//       CR 920: Add missing parenthesis to the Description for 
//           TraceLevelType.BaseType
//
//    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
// ==================================================================

#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, MaxLen (16),
       Description (
          "A 16 byte value that uniquely identifies the UnitOfWork"
          "Definition. The use of OSF UUID/GUIDs is recommended.") ]
   string Id;

      [MaxLen (16),
       ModelCorrespondence {"CIM_TraceLevelType.InstanceId"},
       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.") ] 
   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"), MaxLen (16),
       Description (
          "A 16 byte value that uniquely identifies the Metric"
          "Definition. The use of OSF UUID/GUIDs is recommended.") ]
   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, MaxLen (16), 
       ModelCorrespondence {"CIM_UnitOfWorkDefinition.TraceLevelTypeId"},
       Description ( 
          "A 16 byte value that uniquely identifies the trace level "
          "type. The use of OSF UUID/GUIDs is recommended.") ] 
   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)."), 
       Values{"Other", "Bitmap", "Number"}, 
       ValueMap{"1", "2", "3"} ] 
   uint16 BaseType; 

      [ArrayType("Indexed"), 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'.") ] 
   uint32 TraceValues[]; 

      [ArrayType("Indexed"), 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.") ] 
   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, MaxLen (16), 
       Propagated ("CIM_UnitOfWorkDefinition.Id"),
       Description (
          "A 16 byte value that uniquely identifies the UnitOfWork"
          "Definition. The use of OSF UUID/GUIDs is recommended.") ]
   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
// ===================================================================
