Skip to main content

protocols.xml (Android only)

This extension allows to configure protocols for mobile application. It is used for correct handling of protocols component in light-forms definition. This configuration determines how the list of protocols is populated in that component and how the menu for creating new protocol is filled in.

Standard feature type must be added to model.xml for each protocol type with set of feature attributes modelled for all protocol fields.

Light form for each protocol feature type should be prepared in light-forms.xml extension.

Hint: More forms can be defined for protocol feature type. Forms for creating new protocol, for changing the protocol (edit usage) and for displaying the readonly detail (detail usage) can be different if necessary.

Attribute values can be pre-filled in each protocol before it is created. Values can be taken from the base feature, which the protocol is created for.

This configuration connects protocol feature type, protocol form and pre-fill configuration together and determines in which case the protocol can be created.

In configuration, there are two main sections:

  • protocolInputArray - defines all possible protocol inputs that can be used for pre-filling protocol attribute values from the base feature attributes. Each protocol input can be used in more protocol definitions, so it has mandatory attribute id.

  • protocolDefinitionArray - defines in which case (for which base feature type and for which base feature attribute values) the particular protocol types defined in previous section can be created.

Example:

<ber:modelProtocols xmlns:ber="http://www.berit.com/ber" xmlns:xlink="http://www.w3.org/1999/xlink">
  <ber:version>
  ...
  </ber:version>
  <ber:protocolInputArray>
    <ber:protocolInput id="asseblyValues">
      <ber:copyValueArray>
        <ber:copyValue>
          ...
        </ber:copyValue>
      </ber:copyValueArray>
      <ber:copyRelatedValuesArray>
        <ber:copyRelatedValues relationPath="..." orderBy="...">
          <ber:copyValue>
            ...
          </ber:copyValue>
        </ber:copyRelatedValues>
      </ber:copyRelatedValuesArray>
    </ber:protocolInput>
    ...
  </ber:protocolInputArray>
  <ber:protocolDefinitionArray>
    <ber:protocolDefinition>
      ...
    </ber:protocolDefinition>
    ...
  </ber:protocolDefinitionArray>
</ber:modelProtocols>


Protocol Definition​

Each protocol definition contains reference to protocol feature type, reference to light form used for creating new protocol feature and set of protocol inputs used for pre-filling protocol attribute values. It also contains definition of base feature type and optional conditions for base feature attributes. The protocol can be created for the base feature when all conditions are fulfilled.

Example:

   <ber:protocolDefinition>
      <ber:protocolSource>
        <ber:featureTypeArray>
          <!-- Definition of one base feature type for which the protocols defined below can be created -->
          <ber:featureType xlink:href="model.xml#ft_boWorkOrder"/>
        </ber:featureTypeArray>
        <!-- Not used for now -->
        <ber:sourceTemplate>
        </ber:sourceTemplate>
      </ber:protocolSource>
      <ber:protocolArray>
        <!-- Definition of one protocol type that can be created for the base feature type defined above. 
             Attribute singleInstance can define that this protocol type can be created only one  -->
        <ber:protocol singleInstance="true">
          <!-- Reference to protocol feature type -->
          <ber:featureType xlink:href="model.xml#ft_prtDisassembly"/>
          <!-- Reference to light form used for creating new protocol feature -->
          <ber:form type="lightForm" xlink:href="light-forms.xml#fd_prtDisassembly"/>
          <!-- Reference to protocol input defined in protocolInputArray section above -->
          <ber:input refId="disasseblyValues"/>
        </ber:protocol>
        <ber:protocol singleInstance="false">
          <ber:featureType xlink:href="model.xml#ft_prtRealizCheck"/>
          <ber:form type="lightForm" xlink:href="light-forms.xml#fd_prtRealizCheck"/>
          <ber:input refId="setCountDowns"/>
          <!-- Condition for base feature attributes that must be fulfilled to be able to create this protocol 
               for the base feature (and show this protocol in list in (+) button) -->
          <ber:condition>
            'at_boWO_cl_boClassEM' = 0 OR 'at_boWO_cl_boClassEM' = 6 OR 'at_boWO_cl_boClassEM' = 8
          </ber:condition>
        </ber:protocol>
      </ber:protocolArray>
    </ber:protocolDefinition>

Protocol Input​

Each protocol input contains two optional sections:

  • copyValueArray - set of copyValue definitions for copying values from the base feature (or features related via featureRef). Each copyValue definition defines from which base feature attribute the value is taken (inputAttribute) and to which protocol attribute the value is copied (outputAttribute). It’s possible to use featureRef attributes as well.

  • copyRelatedValuesArray - set of copyRelatedValues definitions for copying values from subordinate features reachable via a relation path. This allows prefilling protocol attributes with values from features that are not directly accessible via featureRef from the base feature (e.g. subordinate assets of a master asset).

copyValueArray​

Example of copyValueArray:

    <ber:protocolInput id="asseblyValues">
      <ber:copyValueArray>
        <ber:copyValue>
          <ber:inputAttribute xlink:href="model.xml#at_boWorkRealiz_elMeterNew/at_elMeter_serialNumber"/>
          <ber:outputAttribute xlink:href="model.xml#at_mobilePrt_serialNumber"/>
        </ber:copyValue>
        <ber:copyValue>
          <ber:inputAttribute xlink:href="model.xml#at_boWorkRealiz_elMeterNew/at_elMeter_material"/>
          <ber:outputAttribute xlink:href="model.xml#at_mobilePrt_material"/>
        </ber:copyValue>
        ...
      </ber:copyValueArray>
    </ber:protocolInput>

copyRelatedValuesArray​

In addition to the standard copyValueArray, protocol input can contain a copyRelatedValuesArray section. This section allows copying attribute values from subordinate features that are reachable through a chain of relations from the base feature.

Each copyRelatedValues block must contain:

  • relationPath – defines the path to subordinate features. It contains a comma-separated sequence of association types / role types (or a featureRef attribute). The application traverses the relation tree according to this path and collects all features at the last level as the input set.

  • orderBy – optional attribute defining the ordering of the collected features in the input set.

  • one or more copyValue definitions – each copyValue inside copyRelatedValues must define a featureIndex attribute on the inputAttribute element. The featureIndex refers to the index of a feature instance in the collected input set (0-based). Special values id and ftid can be used as xlink:href to copy the feature ID or feature type ID respectively.

Note: This configuration works in both online and offline modes. In offline mode, all subordinate features referenced by the relationPath must be available in the device cache. Use the relationOfflineMetaGroup attribute in the screen definition to ensure related assets are downloaded for offline use.

Example of copyRelatedValuesArray:

    <ber:protocolInput id="copyValues2">
      <ber:copyValueArray>
        ...
      </ber:copyValueArray>
      <ber:copyRelatedValuesArray>
        <ber:copyRelatedValues
          relationPath="at_boWorkRealAsset__asset,r_asset_subassetL1/rt_subassetL1,r_subassetL1_subassetL2/rt_subassetL2"
          orderBy="at_subassetL2_order">
          <ber:copyValue>
            <ber:inputAttribute featureIndex="0" xlink:href="at_subassetL2_note"/>
            <ber:outputAttribute xlink:href="model.xml#at_protocol_asset01_note"/>
          </ber:copyValue>
          <ber:copyValue>
            <ber:inputAttribute featureIndex="0" xlink:href="at_subassetL2_someValue"/>
            <ber:outputAttribute xlink:href="model.xml#at_protocol_asset01_someValue"/>
          </ber:copyValue>
          <ber:copyValue>
            <ber:inputAttribute featureIndex="0" xlink:href="id"/>
            <ber:outputAttribute xlink:href="model.xml#at_protocol_asset01_fid"/>
          </ber:copyValue>
          <ber:copyValue>
            <ber:inputAttribute featureIndex="0" xlink:href="ftid"/>
            <ber:outputAttribute xlink:href="model.xml#at_protocol_asset01_ftid"/>
          </ber:copyValue>
          <ber:copyValue>
            <ber:inputAttribute featureIndex="1" xlink:href="at_subassetL2_note"/>
            <ber:outputAttribute xlink:href="model.xml#at_protocol_asset02_note"/>
          </ber:copyValue>
          <ber:copyValue>
            <ber:inputAttribute featureIndex="1" xlink:href="at_subassetL2_someValue"/>
            <ber:outputAttribute xlink:href="model.xml#at_protocol_asset02_someValue"/>
          </ber:copyValue>
          <ber:copyValue>
            <ber:inputAttribute featureIndex="1" xlink:href="id"/>
            <ber:outputAttribute xlink:href="model.xml#at_protocol_asset02_fid"/>
          </ber:copyValue>
          <ber:copyValue>
            <ber:inputAttribute featureIndex="1" xlink:href="ftid"/>
            <ber:outputAttribute xlink:href="model.xml#at_protocol_asset02_ftid"/>
          </ber:copyValue>
        </ber:copyRelatedValues>
        <ber:copyRelatedValues relationPath="...">
          ...
        </ber:copyRelatedValues>
      </ber:copyRelatedValuesArray>
    </ber:protocolInput>