On this page you can find detailed information about filtering and configuring the Device Item. The device item filtering may contain the device item UID, object-class, name, tags and attributes. As an additional restriction for filtering the device items is a quantifier. It specifies the number or range of the device items matched by the constructed filter. It is also possible to change the name, add new tags to the existing device item tags, modify the device item attributes, change device item properties and invoke device item operations. There is an order for configuring Device Item properties and operations. The properties are configured first and then the operations are invoked.

These properties and operations belong to the Device Item that matches the created filter. For example when it is necessary to change some property or to invoke some operation with specific arguments of some Device Item, then it is a good practice to crate a filter by the Device Item object class.

Device Item XML Representation

The <items> element is optional and it is used to represent the device item or set of device items. The <items> element has one or many <item> elements. The <item> element represent one item configuration and it has the following child elements - <item-filter> and <item-config>. The item filtering and the device filtering specify if the configuration should be applied to the device.

Filter Device Items

<item-filter>

The <item-filter> is an optional element and it is used to filter device item/s to which the configuration is to be applied. The possible ways to filter the device items are by LDAP filter or by item properties. For this reason the <item-filter> has two child elements - <ldap> and <item-properties>. Only one of these child elements should be available. The <item-filter> tag has optional attribute "quantifier" that is used to restrict the number of items that match the filter. The valid quantifiers are:

• + – for one or more matches. This is used as a default.
• ? – for zero or one matches.
• * – for zero or many matches.
• {n} – for exactly n match.
• {n, m} – for minimum n up to m matches inclusive.

<ldap>

The <ldap> child element is an optional element, but if this element is not provided, then the <item-properties> element should be provided. The <ldap> tag has required attribute "value", that contains the LDAP filter. This value must be encoded according to the LDAP specification.

The following example matches those devices that have only one device item with name "Device Item Test Name" and object class demo.da.items.StepperMotor. If the device has two device items with object class demo.da.items.StepperMotor this must not match on the item filter (the name of the device item does not mater). If the device have 2 device items with the following object classes: demo.da.items.StepperMotor and demo.da.items.LEDStrip and the device item with object class demo.da.items.StepperMotor has name "Device Item Test Name" this means that the device must be matched.

<items>

  <item>

    <item-filter quantifier="{1}">

      <ldap value="(&amp;(objectClass=demo.da.items.StepperMotor)(name=Device Item Test Name))" />

    </item-filter>

  </item>

</items>

<item-properties>

The <item-properties> child element is an optional element, but if not provided, then the <ldap> element should be. It is used to represent the restriction for the device items. From the content of the <device-properties>, LDAP filter is constructed by using AND operator. The <item-properties> element has the following child elements – <uid>, <object-class>, <name>, <tags> and <attributes>.

• <uid> – an optional child element with a required attribute "value" that holds the UID of the device item.

  <items>

    <item>

      <item-filter>

        <item-properties>

          <uid value="Device Item Test UID" />

        </item-properties>

      </item-filter>

    </item>

  </items>

• <object-class> – an optional child element with a required attribute "value" that holds the object class of the device item.

  <items>

    <item>

      <item-filter>

        <item-properties>

          <object-class value="com.prosyst.mbs.services.da.items.Actuator" />

        </item-properties>

      </item-filter>

    </item>

  </items>

• <name> – an optional child element with an optional attribute "value" that holds the name of the device item. If the device item name is null, then the attribute xsi:nil with value true is provided. Only one of these attributes should be provided.

  <items>

    <item>

      <item-filter>

        <item-properties>

          <name value="Device Item Test Name" />

        </item-properties>

      </item-filter>

    </item>

  </items>

• <tags> – an optional child element with one or many <tag> child elements. Every child element represents a tag of the device items. The <tag> has required attribute "value" that holds the value of the device item tag.

  <items>

    <item>

      <item-filter>

        <item-properties>

          <tags>

            <tag value="Device Item Test Tag"/>

          </tags>

        </item-properties>

      </item-filter>

    </item>

  </items>

• <attributes> – an optional child element with one or many <attribute> child elements . In XML Object Representation there is detailed information about the representation of the Device Item attributes.

The following example shows the restriction of the Device Items that have attribute with key "Int array" and two value elements in the array – 3 and 4.

<items>

  <item>

    <item-filter quantifier="*">

      <item-properties>

        <attributes>

          <attribute name="Int array">

            <array-value>

              <element value="3" />

              <element value="4" />

            </array-value>

            <class value="[I" />

          </attribute>

        </attributes>

      </item-properties>

    </item-filter>

  </item>

</items>

Configuring Device Items

<item-config>

The <item-config> element is an optional one. It is used to configure device items that match the <item-filter>. The device item configuration is applied after the device filtering and item filtering have matched. If there is no <item-filter> then the default item filtering is used. It includes a quantifier "+" to restrict the number of matches – one or more device items. The <item-config> element configures:

• device item name
• device item tags
• device item attributes
• device item properties
• device item operations

of the filtered device items. The <item-config> has the following child elements – <name>, <tags>, <attributes>, <properties> and <operations>:

• <name>

The <name> element is optional and it has optional attribute "value" that holds the new name with which the device item should be configured. If the device item name is null then the xsi:nil should be provided with value null. Only one of these attributes is possible to be provided.

Here is an example of how to configure the device item with name null:

<items>

  <item>

    <item-config>

      <name xsi:nil="true" />

    </item-config>

  </item>

</items>

• <tags>

The <tags> element is optional and it has one or many <tag> child elements . The <tag> has required attribute "value" that holds the value of the device item tag which should be added to the existing device item tags.

The following example configures the device item name to "Device Item New Name" and adds new "Device Item New Tag" to the existing tags.

<items>

  <item>

    <item-config>

      <name value="Device Item New Name" />

      <tags>

        <tag value="Device Item New Tag" />

      </tags>

    </item-config>

  </item>

</items>

• <attributes>

The <attributes> element is optional and it has one or many <attribute> child elements . On XML Object Representation page there is detailed information about the representation of the Device Item attributes.

By configuring the device item attribute it is possible to:

• add new device item attribute to already existing ones;
• change existing device item attribute;
• remove exiting device item attribute.

When in the configuration XML file the device item attribute is set to null , this attribute should be deleted from the device item attributes. If an attribute with the same key is already specified in the device item attributes, then its value is overridden.

<items>

  <item>

    <item-config>

      <attributes>

        <attribute name="attribute1" value="true">

          <class value="java.lang.Boolean" />

        </attribute>

        <attribute name="Empty Map">

          <map-value>

          </map-value>

          <class value="java.util.HashMap">

            <class value="java.lang.String" />

          </class>

        </attribute>

        <attribute name="deleted_attribute" xsi:nil="true" />

      </attributes>

    </item-config>

  </item>

</items>

• <properties>

The <properties> element is optional and it has one or many <property> child elements. The <properties> element holds the device item properties that have to be configured. They are applied in the same order as they are defined as child elements. The <property> element represents the configuration data of device item property. The <property> tag has:

• a required attribute "name" that holds the name of the device item property;
• an optional attribute "value" that holds the value of the property. This attribute is used when the property value is a simple one. If it is a complex object value, then it should be represented with the corresponding child elements of the <property> attribute – <map-value> and <array-value>. Detailed information about the XML representation of simple and complex object values can be found XML Object Representation.

The following example configures the "wakeUpInterval" device item property to the new value of 20000:

<items>

  <item>

    <item-config>

      <properties>

        <property name="wakeUpInterval" value="20000" />

      </properties>

    </item-config>

  </item>

</items>

• <operations>

The <operations> element is optional element and it has one or many child element <operation>. The <operations> element holds device item operations that have to be configured, i.e. the operations that should be invoked. They are invoked in the same order as they are defined as a child elements. The <operation> tag has required attribute "name" that holds the name of the device item operation. Also the <operation> elements has zero or one element <args> that holds operation parameters. The <args> element has zero or many elements <arg>.

The <arg> element contains representation of the parameter value. The <arg> has optional attribute "value" that holds the value of the property. If the argument value is null, the the attribute xsi:nil with value true should be provided. Only one of these attribute should be provided. The attribute "value" is used when the value of the parameter is a simple value. If the parameter value is a complex object value, then this value should be represented with the corresponding child elements on <arg> attribute - <map-value> and <array-value>. Refer to XML Object Representation for detailis about the simple and complex object values representation.

The following example configures device item by invoking the "rotate" device item operation:

<items>

  <item>

    <item-config>

      <operations>

        <operation name="rotate" />

      </operations>

    </item-config>

  </item>

</items>