Skip to content

Enumeration value in XML criteria

Enumeration value in XML criteria published on 5 Comments on Enumeration value in XML criteria

If you often using the XML criteria in SCSM (with SDK or in view with Advanced View Editor) then you can faced with two different notation used as value for properties of enumeration type (like Status, Category, Area and so on): $MPElement[Name=’’]$ and Guid format (xxxxxxxx-xxxx-xxx-xxxx-xxxxxxxxxxxx, or uniqueidentifier in T-SQL). In this article I will describe the deference and will explain why XML validation can fail when $MPElement$ notation used.

First of all, let’s talk about what is $MPElement$ notation. This features (with may other) came to SCSM from SCOM. Each element in management pack (class, relationship, enumeration and so on) has a two independent key property when used in SDK: Name and ID. And it can be little confusing here, because there is no Name attribute in management pack schema. The answer is simple: the ID attribute in management pack is equal to Name property in SDK. For instance, here is definition of the Active status enumeration for Incident class in management pack:

<EnumerationValue ID="IncidentStatusEnum.Active" Accessibility="Public" Parent="IncidentStatusEnum" Ordinal="1" />

and we must use ID attribute value as Name in SDK..

The SDK’s ID property aren’t stored in management pack but in database only and it’s calculated at moment when management pack imported into SCSM. The ID calculated using the SHA algorithm based on management pack name, management pack public key (only if MP is sealed) and name of the object. This means that management pack elements will have same ID in any SCSM installation. You can calculate ID for any object in management pack by yourself by execute the fn_MPObjectId function from Service Manager database. For instance, the Active status enumeration for Incident class defined in sealed management pack with name “System.WorkItem.Incident.Library” and have a public key 31bf3856ad364e35:
image

If you will execute fn_MPObjectId with those parameters you will get next ID:
image
and you can compare it with real ID. As you see, they are the same:
image

But the problem with ID property what value is not human readable. And the hash calculated using SHA algorithm can not be calculated back to original value. That’s why some time you need to use Name instead of ID. But SDK use the ID to working with objects. For instance, if you want to select all incidents with status equal to Active you must use query “Status = ‘5e2d3932-ca6d-1515-7310-6f58584df73e’” or, in XML format:

<QueryCriteria xmlns="http://tempuri.org/Criteria.xsd" Adapter="omsdk://Adapters/Criteria"> <Criteria> <FreeformCriteria> <Freeform><Criteria  xmlns="http://Microsoft.EnterpriseManagement.Core.Criteria/">
  <Expression>
    <SimpleExpression>
      <ValueExpressionLeft>
        <Property>$Context/Property[Type='CoreIncident!System.WorkItem.Incident']/Status$</Property>
      </ValueExpressionLeft>
      <Operator>Equal</Operator>
      <ValueExpressionRight>
        <Value>{5e2d3932-ca6d-1515-7310-6f58584df73e}</Value>
      </ValueExpressionRight>
    </SimpleExpression>
  </Expression>
</Criteria> </Freeform> </FreeformCriteria> </Criteria> </QueryCriteria>

This is good somewhere deep in the code, where you can leave the comments, but in view’s criteria this is not very user-friendly (in fact, you can leave XML comments <!– –> inside of the criteria, but they will lost when you will import management pack to SCSM).

To solve that problem SDK support the $MPElement$ token. This token can be used in queries, as parameter for workflow and in other places. This token will replaced by ID of management pack object.

This token can exist in two forms: $MPElement$ and $MPElement[Name=’full_element_name’]$. In first case, token will be replaced with ID of the current element. The current element is depend from context. For instance, if $MPElement$ used in view’ criteria, the ID of the view will be used (but this is absolutely no sense in criteria). If token used as parameter of the workflow, the ID of the workflow will be used (this is more useful because sometime you need to get workflow’s object inside of your code).

In second case, the token will be replaced with ID of element which full name set in Name attribute. By “full name” I mean name of the element with alias, in case if target element defined in other, sealed management pack. For instance, if your view defined in your custom management pack, and you want to select all incidents with Status = Active then you must add reference to management pack where enumeration Active is defined (System.WorkItem.Incident.Library management pack in this case) and set criteria like this (the CoreIncident is Alias for System.WorkItem.Incident.Library  reference):

<QueryCriteria xmlns="http://tempuri.org/Criteria.xsd" Adapter="omsdk://Adapters/Criteria"> <Criteria> <FreeformCriteria> <Freeform><Criteria  xmlns="http://Microsoft.EnterpriseManagement.Core.Criteria/">
  <Expression>
    <SimpleExpression>
      <ValueExpressionLeft>
        <Property>$Context/Property[Type='CoreIncident!System.WorkItem.Incident']/Status$</Property>
      </ValueExpressionLeft>
      <Operator>Equal</Operator>
      <ValueExpressionRight>
        <Value>$MPElement[Name='CoreIncident!IncidentStatusEnum.Active']$</Value>
      </ValueExpressionRight>
    </SimpleExpression>
  </Expression>
</Criteria> </Freeform> </FreeformCriteria> </Criteria> </QueryCriteria>

The SDK will do all job for you: the $MPElement[Name=”CoreIncident!IncidentStatusEnum.Active”]$ will be replaced with real ID during execution of the query.

If you read all above carefully then you note that $MPElement$ can not be used against elements defined in unsealed management pack (except cases when both elements, target and source, located in same MP). Imagine situation when you define new enumeration for Status in unsealed management pack A and want to use in view’s criteria defined in management pack B. The reference can be created only against sealed management packs, so you can’t use $MPElement$ token in this case, but you still able to use ID in Guid format. But if you want to create view in management pack A then you can use $MPElement$, just skip the alias part in name.

If you are using the AVE 2 Pro then you note that you have two options two insert enumeration value. Now you know why :)
image

The last thing is criteria validation. If you using AVE 2 and try to validate some criteria with $MPElement$ token inside, the validation can fails with exception:

The http://Microsoft.EnterpriseManaement.Core.Criteria/:Value element is invalid – The value $MPElement[Name=”Incident!lncidentStatusEnum.Active”]$ is invalid according to its datatype ‘http://Microsoft.EnterpriseManagement.Core.Criteria/:UniqueIdentifierType’ – The Pattern constraint failed.

The answer in datatype: it expect the UniqueIdentifierType, Guid, but has a $MPElement$ in fact. As you know, the $MPElement$ will be replaced with real guid, so you can safely ignore this exception.

Share

%d bloggers like this: