samo-mobile.xml

⚠️ Warning: For LIDS Mobile for iOS there is still only mobile.xml configuration supported. It has common parts with samo-mobile.xml, but not all parts are supported in iOS app yet (you can see "Android only" warning at some chapters). ber:configurationArray described in this chapter is supported only for SAMO Mobile for Android application. LIDS Mobile for iOS configuration should start with tags inside one ber:configuration tag in the example below.

SAMO Mobile can be configured to support multiple customer agendas. More independent configurations (referred as contexts) can be prepared. One of the prepared agendas is selected during login to the project. samo-mobile.xml must always contain at least one valid configuration.

Example: Top level structure of samo-mobile.xml.

<?xml version="1.0" encoding="UTF-8"?>
<ber:modelSamoMobile xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:ber="http://www.berit.com/ber">
  <ber:version>
    <ber:metadata>1</ber:metadata>
    <ber:minClient>2754</ber:minClient>
    <ber:minAS>11904</ber:minAS>
  </ber:version>
  <ber:configurationArray>
    <ber:configuration contextId="workforce">
    ...
    </ber:configuration>

    <ber:configuration contextId="warehouseManagement">
    ...
    </ber:configuration>

    <ber:configuration>
    ...
    </ber:configuration>
  </ber:configurationArray>
</ber:modelSamoMobile>

configurationArray - mandatory element - at least one "configuration" tag must be inside.
configuration - main configuration element. Entire agenda configuration must be inside. No configuration parts can be shared among configurations in this array.
configuration contextId - context id of the configuration can be used to start mobile application with particular agenda directly. When there is no contextId - it means, that this is the default configuration (agenda) for the project. Only one configuration can be without contextId.

Example: Top level structure of ber:configuration.

<ber:configuration contextId="wfm1">
  <ber:projectInfo>
  ...
  </ber:projectInfo>
  <ber:screenArray>
  ...
  </ber:screenArray>
  <ber:browseArray>
  ...
  </ber:browseArray>
  <ber:serverArray>
  ...
  </ber:serverArray>
  <ber:mapComponentArray>
  ...
  </ber:mapComponentArray>
  <ber:offlineMap>
  ...
  </ber:offlineMap>
  <ber:offlineWorkflowArray>
  ...
  </ber:offlineWorkflowArray>
  <ber:offlineRuleArray>
  ...
  </ber:offlineRuleArray>
  <ber:sketchTaskArray>
  ...
  </ber:sketchTaskArray>
  <ber:groupArray>
  ...
  </ber:groupArray>
  <ber:offlineSearchArray>
  ...
  </ber:offlineSearchArray>
  <ber:toolArray>
  ...
  </ber:toolArray>
  <ber:featurePresentation>
  ...
  </ber:featurePresentation>
  <ber:workOrderArray>
  ...
  </ber:workOrderArray>
  <ber:allocationArray>
  ...
  </ber:allocationArray>
  <ber:user>
  ...
  </ber:user>
  <ber:parameterArray>
  ...
  </ber:parameterArray>
</ber:configuration>

Project Info

Defines general properties of the agenda.

Example:

<ber:projectInfo name="Workforce Management">
  <ber:icon xlink:href="resource.xml#projectIco"/>
  <ber:spatialInfo srs="EPSG:31467">
    <!-- Optional zoom level according to http://wiki.openstreetmap.org/wiki/Zoom_levels -->
    <ber:initialSituation zoomLevel="18.75">3451628.500000 5481750.586765</ber:initialSituation>
  </ber:spatialInfo>
</ber:projectInfo>

name – agenda name displayed in the application main menu
icon – optional agenda icon displayed in the application main menu. When icon is not set, default SAMO icon is displayed - see Icons in mobile
srs – coordinate system
initialSituation – default position of map window centre (if map component is used)
zoomLevel – optional default zoom level according to <http://wiki.openstreetmap.org/wiki/Zoom_levels>

Screens (Android only)

screenArray configuration defines the main application menu for particular configuration (agenda). There are several screen types that can be used. All of them are optional.

Example:

<ber:screenArray>
  <ber:screen name="Screen name" type="screenType..." default="true">
    <ber:icon xlink:href="resource.xml#auxiliary-devices"/>
      <ber:parameterArray>
      </ber:parameterArray>
  </ber:screen>
</ber:screenArray>

screen - screen definition - each screen is represented by one menu item in main application menu
screen name – name of the screen is used as a label for menu item
screen type – enumeration type - one of allowed keywords must be used "map", "standardBrowse", "workOrders", "allocations" - detailed description below
screen default - true/false, true - default screen which is displayed when application connects to project. This attribute can be set to true only in one of the screens in screenArray.
icon - icon is used in menu item - see Icons in mobile
parameterArray - optional section with parameters - allowed parameter names depend on the screen type

Screen definition can contain other parts depending on the screen type.

Screen Types

map - this type of screen contains full map component with all map functionalities. Maximum one screen of this type can be included in screenArray.
standardBrowse - this type of screen contains list of features defined by some browse configuration (feature types, conditions, ordering, filters, tools, etc.)
workOrders - this is special screen, derived from the standardBrowse. It contains the list of work orders with calendar component for filtering. It is intended to use only for workforce work order functionalities.
allocations - also special screen, derived from the standardBrowse. It contains the list of allocations with calendar component for filtering. It is intended to use only for workforce allocation functionalities

map screen type example:

<ber:screen name="Map" type="map">
  <ber:icon xlink:href="resource.xml#map"/>
  <ber:mapComponent refId="mainMap"/>
</ber:screen>

mapComponent - optional reference to map component definition. Map component defines the set of layers for this map screen (see Map Components). If "mapComponent" is missing in this screen definition - all layers defined in serverArray is included in this map screen (see Map Layers)

standardBrowse screen type example:

<ber:screen loadOnStartUp="true" name="Screen name" type="standardBrowse">
  <ber:icon xlink:href="resource.xml#browse"/>
  <ber:browseRefArray>
    <ber:browseRef refId="browseDef1" default="true" offline="true" relationOfflineMetaGroup="browse1Relations"/>
  </ber:browseRefArray>
  <ber:mapComponent defaultVisible="true" refId="browseMap1">
    <ber:parameterArray>
      <ber:parameter name="layerSelection" value="true"/>
    </ber:parameterArray>
  </ber:mapComponent>
  <ber:parameterArray>
    <ber:parameter name="newItemAllowed" value="true"/>
    <ber:parameter name="locationAllowed" value="false"/>
    <ber:parameter name="useBigDetail" value="true"/>
    <ber:parameter name="allowModification" value="false"/>
    <ber:parameter name="allowDelete" value="false"/>
  </ber:parameterArray>
</ber:screen>

screen loadOnStartUp - true/false, false - do not load data of this screen when application is connecting to the project, load the data when user selects this screen in main application menu. It can make the project loading faster. When the contents of this screen must be accessible in offline mode, this option must be set to true.
browseRefArray - definition of the screen browses. There is typically one browse definition in the screen. Data are loaded to the list depending on the browse definition. User can use filtering functionality. When you need to predefine more filters for one screen, more browse definitions can be included in this array. User can select one of the browses inside the screen.
browseRef - definition of a browse
- refId - reference to browse defintion - see Browse definition
- default - true/false, true - default browse which is displayed when screen is active. This attribute can be set to true only in one of the browseRefs in browseRefArray. Optional parameter - use only when there is more than onebrowseRef definiton.
- offline - true/false, true - this browse must be available in offline. Each browse with this offline attribute set to true, must be downloaded and saved to cache when connecting to project.
- relationOfflineMetaGroup - when offline attribute is set to true - all features of the browse are downloaded and saved to device cache. When there is a need to work with features related to cached browse features in offline, this attribute can be used. The value is the id of metadata group where all needed relation types are included. Caching of related features works recursively also.
mapComponent - optional definition - simple browse map component can be included into this type of screen. Browse map component functionality is limited compared to the full map component. It is intended "only" for locating browse items in map.
- refId - reference to map component definition. Map component defines the set of layers for this browse map (see Map Components).
- defaultVisible - true/false - map component is visible/collapsed by default
- parameter - several parameters can be defined for browse map component:
  - layerSelection - true/false, true - allow user to switch on/off layers in this map component
parameter - several parameters can be defined for this type of screen:
- newItemAllowed - true/false, true - icon for adding new feature to the list is added to the screen
- locationAllowed - true/false, true - icon for locating feature is added to each card in list, if the feature contains some graphics. Tapping the icon locates the feature in map in full map component - map screen type must be included in screenArray
- useBigDetail - true/false, true - when the detail is opened for one of the features in the list, form is stretched to the full screen. false - detail form is opened in a separate window above the list
- allowModification - true/false, true - icon for modification is added to each card in list. Tapping the icon opens modification form for the feature.
- allowDelete - true/false, true - icon for delete is added to each card in list. Tapping the icon deletes the feature from the system (with confirmation dialog).

workOrders screen type example:

<ber:screen name="Screen name" type="workOrders">
  <ber:icon xlink:href="resource.xml#wo"/>
  <ber:browseRefArray>
    <ber:browseRef refId="wo1" offline="true" />
  </ber:browseRefArray>
  <ber:parameterArray>
    <ber:parameter name="newItemAllowed" value="false"/>
    <ber:parameter name="locationAllowed" value="true"/>
    <ber:parameter name="useBigDetail" value="true"/>
    <ber:parameter name="allowModification" value="true"/>
    <ber:parameter name="allowDelete" value="false"/>
  </ber:parameterArray>
</ber:screen>

Configuration options for work order screen are the same as for standardBrowse definition (except type="workOrders"). Calendar filtering component is added automatically to this screen. When this type of screen is used, workOrderArray configuration part is mandatory - see Work Orders.

allocations screen type example:

<ber:screen default="true" name="Screen name" type="allocations">
  <ber:icon xlink:href="resource.xml#alloc"/>
  <ber:mapComponent defaultVisible="false" refId="allocMap"/>
  <ber:browseRefArray>
    <ber:browseRef default="true" offline="true" refId="alloc"/>
  </ber:browseRefArray>
  <ber:parameterArray>
    <ber:parameter name="newItemAllowed" value="false"/>
    <ber:parameter name="locationAllowed" value="false"/>
    <ber:parameter name="useBigDetail" value="true"/>
    <ber:parameter name="modificationAllowed" value="true"/>
    <ber:parameter name="deleteAllowed" value="false"/>
  </ber:parameterArray>
</ber:screen>

Configuration options for allocation screen are the same as for standardBrowse/workOrders definition (except type="allocation"). Calendar filtering component is also added automatically to this screen. When the detail of allocation is displayed from the list of allocations, form with work order related to the allocation is opened instead of allocation detail automatically. When this type of screen is used, allocationArray configuration part is mandatory - see Allocations.

Browse Definition (Android only)

This section defines preconfigured selection sets, which can be displayed in full featured lists – browses in defined screens (with screen types: standardBrowse, workOrders, allocations) see Screens. The browse content is defined by filter directly in this section. More than just filter can be defined for the browse. Browse can be extended by:

sorting
grouping
tools - browse toolbar and tools on cards can be included
card customization - card icon definition, card attribute set

Example:

<ber:browse id="browse1" name="Browse name">
  <ber:description>
    Browse description
  </ber:description>
  <ber:dataSource>
    <ber:filter>
      <ber:featureTypeArray>
        <ber:featureType xlink:href="model.xml#ft_1"/>
      </ber:featureTypeArray>
      <ber:condition>'at_1' = 1</ber:condition>
      <!-- Deprecated for SAMO Mobile 10.0 and higher, use filterForm only instead -->
      <ber:filterFormArray>
        <ber:filterForm formId="filterSimple"/>
        <ber:filterForm formId="filterComplex"/>
      </ber:filterFormArray>
      <!-- Supported only for SAMO Mobile 10.0 and higher, use filterFormArray for versions 9 and 8 -->
      <ber:filterForm formId="filterSimple"/>
      <ber:calendarDefinition defaultView="day">
        <ber:attribute id="startDate" xlink:href="model.xml#at_start"/>
        <ber:attribute id="endDate" xlink:href="model.xml#at_end"/>
      </ber:calendarDefinition>
    </ber:filter>
    <ber:orderByArray>
      <ber:orderBy xlink:href="model.xml#at_state/ca_state_stateOrder"/>
      <ber:orderBy direction="descending" xlink:href="model.xml#at_dateFrom"/>
    </ber:orderByArray>
  </ber:dataSource>
  <ber:browseConfig>
  ...
  </ber:browseConfig>
</ber:browse>

browse id - identification of the browse definition
browse name - name of the browse - it is used when there are more browses in one screen
description - browse description
dataSource - mandatory definition - contains mandatory filter and optional ordering configuration
filter - mandatory filter definition - it contains:
- featureTypeArray - mandatory list of browse feature types. There is typically one feature type, but more than one can be specified. Then it makes sense to include only feature types with common attributes, because other browse configuration is common for all of them (condition, sorting, grouping, etc..).
- condition - optional attribute condition. Condition can be included in more places in mobile configuration and it has common syntax for all mobile configuration parts. For more info see Attribute conditions in mobile.
- filterFormArray - optional part - browse can be extended by filter forms menu, where user can specify additional condition interactively. This array can contain references to one or more filter forms defined in light-forms.xml. This functionality is supported for SAMO Mobile versions 9 and 8. It is deprecated for SAMO Mobile 10.0 and higher.
- filterForm - optional part - browse can be extended by one filter form, where user can specify additional condition interactively. This tag contains reference to one filter form defined in light-forms.xml. This functionality is supported only for SAMO Mobile version 10.0 and higher. For versions 9 and 8 use filterFormArray instead.
- calendarDefinition - optional part - browse can be extended by interactive calendar filter component. User can select date range for features in browse and condition for this date range is added to condition by AND clause.
  - attribute "startDate" - feature attribute for start date range condition
  - attribute "endDate" - feature attribute for end date range condition
  Note: This calendar filter can be defined only for "standardBrowse" screen type. "workOrders" and "allocations" screen types includes this filtering component automatically and startDate/endDate attributes are configured in other configuration sections: Work Orders, Allocations.
orderByArray - optional configuration for ordering the features in browse. More order clauses can be included. They are applied in the same order as in this array
- orderBy - reference to feature attribute that should be used for ordering. In the case of attribute codelist type, codelist column can be used with slash syntax
- orderBy direction - optional attribute for specifying ordering direction. ascending is the default value.
browseConfig - browse config is a common definition for any browse in the application. It can be included in more places in mobile configuration and it has common syntax for all mobile configuration parts. For more info see Browse configuration.

Filtering

Browse filter is always based on feature type collection and on preconfigured condition - if it is specified.

The condition can be replacednd with the <ber:interfaceCondition> alternative for feature types implementing a common interface. For full syntax see Attribute conditions in mobile.

It is possible to add the option for quick filtering the browse. allowFilter attribute can be set in browseConfig. Then quick filter icon is added to browse header and user can enter some phrase to search within the browse items. Search phrase is applied to attributes, that are displayed on cards in the browse list.

It is possible to add the option for complex filtering the browse. filterFormArray can be added to data source definition of the browse - see above description. Then filter forms menu is added to browse header and user can fill in filter form and apply it to the browse items. Filter form can contain feature attributes with compare and logical operators and values where some additional condition can be created by user interactively.

Map Layers

Optional definition of map layers contain graphical data available for displaying in map window, if any map component is used in the agenda. List of layers can contain data from LIDS project or from external map services. Individual layers are sorted by groups called servers. Agenda can contain more map components with different map layers available. All map layers for all map components of the agenda must be defined at this place.

Example:

  <ber:serverArray>
    <ber:server name="LIDS WMS" defaultTurnOn="false" showAsOneLayer="false" defaultQueryLayer="true" type="LIDS-WMS" xlink:href="address">
      <ber:layerArray>
        <ber:layer id="l_1" name="" defaultTurnOn="true"/>
        <ber:layer id="l_2" name="" defaultTurnOn="false"/>
        <ber:layer id="l_3" name="" defaultTurnOn="false"/>
      </ber:layerArray>
    </ber:server>

    <ber:server defaultTurnOn="true" name="Orthophoto" showAsOneLayer="true" type="LIDS-WMTS" xlink:href="WMTS?SERVICE=WMTS&amp;VERSION=1.0.0&amp;REQUEST=GetCapabilities">
      <ber:layerArray>
        <ber:layer id="tms_orthophoto"/>
      </ber:layerArray>
    </ber:server>

    <ber:server defaultQueryLayer="false" defaultTurnOn="false" name="Utility networks" showAsOneLayer="false" type="LIDS-VECTOR">
      <ber:layerArray>
        <ber:layer defaultTurnOn="true" id="cat_5010000" name="Water"/>
        <ber:layer defaultTurnOn="false" id="cat_5020000" name="Electricity"/>
      </ber:layerArray>
    </ber:server>

    <ber:server name="External WMS" defaultTurnOn="false" showAsOneLayer="false" opacity="0.8" defaultQueryLayer="false" type="WMS" xlink:href="http://server.com/map?SERVICE=WMS&amp;REQUEST=GetCapabilities&amp;VERSION=1.1.1">
      <ber:layerArray>
        <ber:layer id="l_7" name="" defaultTurnOn="true"/>
        <ber:layer id="l_8" name="" defaultTurnOn="false"/>
        <ber:layer id="l_9" name="" defaultTurnOn="true"/>
      </ber:layerArray>
      <ber:paramsArray>
        <ber:srs>EPSG:5514</ber:srs>
        <ber:format>image/jpeg</ber:format>
        <ber:additionalParamsArray>
          <ber:param key="STYLES" value="default"/>
        </ber:additionalParamsArray>
      </ber:paramsArray>
    </ber:server>

    <ber:server name="External WMTS with additional parameters" defaultTurnOn="false" showAsOneLayer="true" opacity="0.7" defaultQueryLayer="false" type="WMTS" featureInfoOutput="text/html" xlink:href="http://adddress.com/pl?service=WMTS&request=GetCapabilities">
      <ber:layerArray>
        <ber:layer id="orto" defaultTurnOn="true" params="STYLES:abc"/>
        <ber:layer id="tes" defaultTurnOn="true" params"STYLES:def,AAA:bb,XXX:yy"/>
        <ber:layer id="terrain" defaultTurnOn="true" params="STYLES:abc"/>
      </ber:layerArray>
      <ber:paramsArray>
        <ber:srs>EPSG:5514</ber:srs>
        <ber:format>image/jpeg</ber:format>
        <ber:login>username</ber:login>
        <ber:password>password</ber:password>
        <ber:additionalParamsArray>
          <ber:param key="STYLES"/>
          <ber:param key="TIME" value="1234"/>
        </ber:additionalParamsArray>
      </ber:paramsArray>
    </ber:server>
  </ber:serverArray>

name – layer name displayed in the application
id – optional identifier. Needed if layer is referred by e.g. mapComponentArray, offlineServerRefArray
type – server type depends (apart from the providers capability) on the usage in the application.
- LIDS-WMS
  - good for frequently changed data
  - symbology evaluated by application server
  - can't be used in offline mode
- LIDS-WMTS
  - good performance
  - data can be out-of-date
  - symbology evaluated by application server
  - can be used in offline mode, but a lot of raster tiles can be downloaded
- LIDS-VECTOR
  - good for frequently changed data
  - symbology limited - evaluated by client
  - optimal for offline mode
- WMS, WMTS
  - Used for accessing external map services
xlink:href – URL for sending GetCapabilities request. Relative path should be used for LIDS-WMS and LIDS-WMTS, not used at all for LIDS-VECTOR
defaultTurnOn – true / false attribute. Defines, if the layer is turned on by default
showAsOneLayer – true / false attribute. If true, it’s not possible to display list of individual layers in client application
defaultQueryLayer – true / false attribute. If true, the layer is used for selecting features in graphics by default. Several layers can be set to true. Default value is true; it makes sense to define this attribute just for the false case
queryLayer – true / false attribute, defines, if the layer can be set as queryable. Default value is true; it makes sense to define this attribute just for the false case, especially in case of backdrop layers
defaultSnapLayer – true / false attribute. If true, the layer is activated for snapping. Just one layer can be set to true. Default value is false
snappable – true / false attribute, defines, if the layer can be set as snappable. Default value is true; it makes sense to define this attribute just for the false case
maxScaleDenominator, minScaleDenominator – optional values defining visibility range
opacity – optional transparency setting
featureInfoOutput – format of feature info; used only for external WMS / WMTS
layerArray – list of individual layers provided by particular server
paramsArray – optional array of parameters included in the WMS / WMTS request. The possible parameters include srs, format, login, password and any other value specified in additionalParams element. If value of parameter is excluded, the parameter can be defined for each layer independently

Map Components (Android only)

Particular agenda can contain more map components with different map layers available. Map components can be included to these applications parts:

main map - full map component defined for "map" type screen definition
browse map - browse map component with limited functionality used mainly for locating features of some browse
- can be included in some browse screen definition
- can be included in browse config definition of some browse (light-forms.xml)

Hint: If the agenda uses only one map component as the full map in map screen (or no map component at all), this map components definition can be omitted.

All map layers must be configured in serverArray. Map components defines its own set of layers by references to map layers definition. Map component can override layers order, layer name, layer default turn on.

Example:

<ber:mapComponentArray>
  <ber:mapComponent id="allocationScreen">
    <ber:serverRefArray>
      <ber:serverRef defaultTurnOn="false" name="Assets" refId="wmts"/>
      <ber:serverRef defaultTurnOn="true" name="Satellite" refId="orthophoto"/>
    </ber:serverRefArray>
  </ber:mapComponent>
  <ber:mapComponent id="lightFormRelated">
    <ber:serverRefArray>
      <ber:serverRef defaultTurnOn="true" name="Assets" refId="wmts"/>
      <ber:serverRef defaultTurnOn="true" name="City" refId="cityMap"/>
    </ber:serverRefArray>
  </ber:mapComponent>
  <ber:mapComponent id="mainMap">
    <ber:serverRefArray>
      <ber:serverRef defaultTurnOn="true" refId="wms"/>
      <ber:serverRef defaultTurnOn="false" refId="wmts"/>
      <ber:serverRef defaultTurnOn="false" refId="vector"/>
      <ber:serverRef defaultTurnOn="false" refId="detailPlan"/>
      <ber:serverRef defaultTurnOn="false" name="Satellite" refId="orthophoto"/>
    </ber:serverRefArray>
  </ber:mapComponent>
</ber:mapComponentArray>

mapComponent id – map component identifier. It is used for referencing map component from other configuration parts
serverRef refId – reference to map layer definition
serverRef name, defaultTurnOn – optional attributes - can be used to override map layer properties

Offline Map (Android only)

The list of layers cached for offline mode can be preconfigured. If the configuration exists, the window for selecting layers for caching is not displayed and the data is cached according to this definition and the current map range.

Example:

  <ber:offlineMap>
    <ber:offlineServerRefArray>
      <ber:offlineServerRef refId="wmts" includeSemantics="true"/>
      <ber:offlineServerRef refId="orthophoto"/>
      <ber:offlineServerRef refId="vector"/>
    </ber:offlineServerRefArray>
  </ber:offlineMap>

mapComponent id – map component identifier. It is used for referencing map component from other configuration parts
offlineServerRef refId – reference to map layer definition
offlineServerRef includeSemantics – false - only map data are stored - selecting features from the map in offline is not available for such layer

Offline Workflow (Android only)

Workflow is primarily defined by business server configuration. Mobile app is able to work with such workflow in online mode using business server services. However, mobile app can also work in offline mode. In such case, business server services are not available, and the workflow must be defined in mobile configuration.

Note: Offline workflow configuration for mobile app must always be consistent with the workflow defined in business server configuration. It means, that all steps and transitions defined in offline workflow must exist in business server workflow configuration. However, not all steps and transitions from business server workflow configuration must be included in offline workflow. Workflow can be limited for mobile app in offline mode.

Note: When there is some backend business script triggered by workflow transition, it cannot be processed in offline mode by mobile app immediately. This script takes action when the offline changes synchronization is done and the workflow transition is processed in online mode.

Hint: It is possible to add conditional transition in offline workflow configuration. There are two types of conditions — visibility conditions that hide the transition when not met, and transition conditions that show an error message when not met. See below.

Hint: It is possible to define light form to be used when some transition is performed by mobile configuration. Such form can be used to fill some feature attributes by user during the state change. Such form is used in mobile app in online and offline mode. See Light forms usage description.

Example:

<ber:offlineWorkflowArray>
  <ber:workflow>
    <ber:featureTypeArray>
      <ber:featureType xlink:href="model.xml#ft_1"/>
    </ber:featureTypeArray>
    <ber:stateAttribute xlink:href="model.xml#at_state/ca_state_code"/>
    <ber:stateArray>
      <ber:state id="accepted" label="Accepted">
        <ber:transitionArray>
          <ber:transition targetState="inRealization" workflowAction="toRealization" label="Start"/>
        </ber:transitionArray>
      </ber:state>
      <ber:state id="inRealization" label="Started">
        <ber:transitionArray>
          <ber:transition targetState="interrupted" workflowAction="toInterrupted" label="Iterrupt"/>
          <ber:transition targetState="finished" workflowAction="toFinished" label="Finish">
            <ber:visibilityCondition>'at_canFinish' != NULL</ber:visibilityCondition>
            <ber:transitionCondition errorMessage="Attribute 'at_description' must be filled in before finishing">
              'at_description' != NULL
            </ber:transitionCondition>
          </ber:transition>
        </ber:transitionArray>
      </ber:state>
      <ber:state id="interrupted" label="Interrupted">
        <ber:transitionArray>
          <ber:transition targetState="inRealization" workflowAction="toRealization" label="Start again"/>
        </ber:transitionArray>
      </ber:state>
      <ber:state id="finished" label="Finished"/>
    </ber:stateArray>
  </ber:workflow>
</ber:offlineWorkflowArray>

offlineWorkflowArray – collection of all offline workflows defined for the agenda. There can be more than one workflow defined.
workflow – definition of one workflow for one or more feature types with common attributes
featureTypeArray – collection of all feature types using this workflow. All feature types must have common state attribute.

stateAttribute – mandatory definition - reference to feature attribute used as a state attribute. Attribute must be of codelist type. And codelist must contain all state ids defined in this workflow in column referenced in this configuration.

stateArray – collection of all states defined in this offline workflow
state id – state identifier - must be consistent with codelist values of the state attribute and business server workflow configuration
state label – state name displayed in the application in offline mode
transitionArray – collection of all transitions available from this state in offline mode
transition targetState – target state of the transition - must be consistent with codelist values of the state attribute and business server workflow configuration
transition workflowAction – action name of the transition - must be consistent with business server workflow configuration
transition label – transition name displayed in the application in offline mode
visibilityCondition – optional condition that controls transition visibility. The condition is evaluated when the list of available transitions is displayed. If the condition is not fulfilled, the transition is hidden — the user does not see it at all. Condition syntax is the same as for attribute conditions used in other mobile configuration parts. For more info see Attribute conditions in mobile. Condition can also use RELATION_EXISTS and RELATION_NOT_EXISTS logical functions for checking conditions based on related features.
transitionCondition – optional condition that validates the transition before it is executed. The transition is always visible to the user. When the user clicks on the transition and the condition is not fulfilled, an error message is displayed and the transition is not performed. The condition expression is placed as the text content of the element.
- transitionCondition errorMessage – optional attribute. Text of the error message displayed when the condition is not met. Supports variable placeholders (%%THIS.attribute%%, %%USERID%%, %%USER.attribute%%, %%CURRENTDATE%%). If not specified, a generic error message is displayed (e.g. "Transition cannot be performed — condition is not met.").
condition – ⚠️ Deprecated. Use visibilityCondition instead. Still supported for backward compatibility — if present, it is evaluated as a visibility condition (hides the transition when not met). If both condition and visibilityCondition are defined on the same transition, visibilityCondition takes precedence and a warning is logged.

Note: Both visibilityCondition and transitionCondition can be combined on a single transition. In that case, the visibility condition is evaluated first — if it returns false, the transition is hidden. If it returns true (or is not defined), the transition is displayed. When the user clicks on the transition, the transition condition is evaluated — if it returns false, the error message is shown and the transition is not performed.

Example of visibility condition with RELATION_EXISTS:

<ber:transition targetState="finished" workflowAction="toFinished" label="Finish">
  <ber:visibilityCondition>'at_canFinish' != NULL AND RELATION_EXISTS(as_1/rt_1, 'at_1' = 3)</ber:visibilityCondition>
</ber:transition>

Example of transition condition with error message:

<ber:transition targetState="finished" workflowAction="toFinished" label="Finish">
  <ber:transitionCondition errorMessage="Field diameter (%%THIS.at_diameter%%) must be greater than 0">
    'at_diameter' > 0
  </ber:transitionCondition>
</ber:transition>

Example of combining both conditions:

<ber:transition targetState="finished" workflowAction="toFinished" label="Finish">
  <ber:visibilityCondition>'at_canFinish' != NULL</ber:visibilityCondition>
  <ber:transitionCondition errorMessage="Description must be filled in before finishing">
    'at_description' != NULL
  </ber:transitionCondition>
</ber:transition>

Example of deprecated condition (still works, evaluated as visibility condition):

<ber:transition targetState="finished" workflowAction="toFinished" label="Finish">
  <ber:condition>'at_canFinish' != NULL</ber:condition>
</ber:transition>

Offline Rules (Android only)

Offline rules provide a mechanism to validate attribute changes in offline mode. Rules are evaluated when a user attempts to modify feature attributes. If a rule's condition is met and the corresponding constraint is not satisfied, the change is denied and a configured message is displayed.

Note: In the first version, only attribute changes are validated. Relation insert/delete operations are not guarded by offline rules.

Note: Related features referenced in constraints 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:

<ber:offlineRuleArray>
  <ber:ruleSet>
    <ber:featureTypeArray>
      <ber:featureType xlink:href="model.xml#ft_1" />
    </ber:featureTypeArray>
    <ber:ruleArray>
      <ber:rule>
        <ber:condition>'ft1_at_1' = 1</ber:condition>
        <ber:constraint>RELATION_EXISTS(as_1/rt_1)</ber:constraint>
        <ber:message>
          Attribute ft1_at_1 cannot be set to 1 because no related feature of relation type as_1 exists.
        </ber:message>
      </ber:rule>
      <ber:rule>
        <ber:condition>'ft1_at_2' != NULL</ber:condition>
        <ber:constraint>RELATION_EXISTS(as_2/rt_2, 'ft2_at_1' = 1)</ber:constraint>
        <ber:message>
          Attribute ft1_at_2 cannot be set because no related feature of relation type as_2
          with attribute ft2_at_1 = 1 exists.
        </ber:message>
      </ber:rule>
    </ber:ruleArray>
  </ber:ruleSet>
</ber:offlineRuleArray>

offlineRuleArray – collection of rule sets for offline attribute validation
ruleSet – groups rules for specific feature types
featureTypeArray – mandatory list of feature types to which the rules apply
ruleArray – collection of rules within a rule set
rule – single validation rule containing a condition, one or more constraints, and a message
condition – attribute condition that triggers the rule evaluation. Condition is optional. When omitted, constraints are always evaluated. Uses the same syntax as Attribute conditions in mobile
constraint – logical expression that must evaluate to true when the condition is met. Can use RELATION_EXISTS and RELATION_NOT_EXISTS functions (see Attribute conditions in mobile)
message – text displayed to the user when the rule is violated (condition is true but constraint is false)

For each feature type in a ruleSet, all rules in the ruleArray are evaluated. When a rule's condition evaluates to true, the corresponding constraint must also evaluate to true. If a user's change would cause the condition to be true while the constraint is false, the change is denied.

Sketch Tasks

Section defines list of feature types offered for construction in full map component. List can be organized into groups.

⚠️ Warning: In case of shared semantics, the definition must include the shared semantics parent.

Example:

  <ber:sketchTaskArray>
    <ber:group name="Group1">
      <ber:sketchTask>
        <ber:featureType xlink:href="model.xml#ft_1"/>
        <ber:featureType xlink:href="model.xml#ft_2"/>
        <!—Example of feature type with shared semantics -->
        <ber:featureType xlink:href="model.xml#ft_s3/ft_3"/>
      </ber:sketchTask>
    </ber:group>

    <ber:group name="Group2">
      <ber:sketchTask>
        <ber:featureType xlink:href="model.xml#ft_4"/>
        <ber:featureType xlink:href="model.xml#ft_5"/>
      </ber:sketchTask>
    </ber:group>
  </ber:sketchTaskArray>

group - construction feature types can be organized into groups
group name - name of the group
sketchTask - contains set of feature types for construction within one group

Relationships

In some cases, component for displaying all related features of some feature is used in form. Content of this component is generated automatically by the application based on the relation types defined in the project model. This component is used:

in generated form when there is no suitable light form definition - see Forms in Mobile
in light form when relations component is included in the form definition - see relations

The component displaying related features shows all possible relationship types defined for particular feature type. It’s possible to limit the displayed relationship types by configuring relationViewMetaGroup in groupArray. More comma separated metadata groups can be defined.

if relationViewMetaGroup definition doesn’t exist, all relationship types are displayed
if relationViewMetaGroup definition exists, only the relationship types from these groups are displayed

Example:

<ber:groupArray>
  <group key="relationViewMetaGroup" value="group_1,group_2"/>
</ber:groupArray>

Relationships in Offline

There are two data caching mechanisms in mobile app:

caching map layers for offline - see Offline Map
caching screen browses for offline - see Screens

More info about offline mode in mobile app is in Offline in Mobile chapter.

When caching map layers for offline only relationship types defined in relationOfflineMetaGroup are cached into offline and can be displayed in offline mode when working with map layer features. Related features are cached only for features, that are downloaded to cache for particular map layer and map space. Related features are cached even recursively. More comma separated metadata groups can be defined in this way.

Example:

<ber:groupArray>
  <group key="relationOfflineMetaGroup" value="group_1,group_2"/>
</ber:groupArray>

Search Configuration

Search configuration can be specified for search functionality in full map component. List of feature types queried by the application can be limited by specifying comma separated metadata groups ids in groupArray. If this configuration exists, only feature types included in the specified groups will be evaluated during search.

when this configuration is missing, search is performed for all feature types indexed in elastic search in current project
when there is only one metadata group in this configuration, feature types included in this group is used for searching
when there are more metadata groups in this configuration, user can select which group should be used for particular search

Hint: Feature types included in search meta groups must be correctly indexed in elastic search. For mobile app, you only need to index the attributes that should be used for searching. After the data is found by this search function, it's displayed in the simple list with feature type name and feature info only. The other attributes in the detail form are downloaded from LIDS AS directly, so they don't need to be indexed. The Search extension is not used for:

displaying geometry of layers

displaying attributes in forms

displaying attributes in list of features

Attributes needed to be included in the index:

"type"

"id"

"featureInfo"

attributes needed for evaluating the query

Indexing of feature geometry and indexing of codelists is not necessary for LIDS Mobile.

Example:

  <ber:groupArray>
    <group key="searchMetaGroup" value="group_1,group_2"/>
  </ber:groupArray>

Offline Search

Mobile app is capable of using search functionality in full map component also in offline mode. Such data has to be indexed specific way. This definition is independent on the standard Elastic Search configuration.

It’s necessary to specify feature types and their attributes which will be evaluated when executing the attribute search in offline mode. Only the specified attributes of the specified feature types are indexed.

Note: Indexing is done during caching map layers for offline. Only features downloaded to cache for some map layer can be found by this functionality in offline.

Example:

  <ber:offlineSearchArray>
    <ber:indexedFeatureTypes>
      <ber:indexedFeatureType xlink:href="model.xml#ft_1"/>
      <ber:indexedFeatureType xlink:href="model.xml#ft_2"/>
      <ber:indexedFeatureType xlink:href="model.xml#ft_3"/>
    </ber:indexedFeatureTypes>

    <ber:indexedFeatureAttributes>
      <ber:indexedFeatureAttribute xlink:href="model.xml#at_1"/>
      <ber:indexedFeatureAttribute xlink:href="model.xml#at_2"/>
      <ber:indexedFeatureAttribute xlink:href="model.xml#at_3"/>
      <ber:indexedFeatureAttribute xlink:href="model.xml#at_4"/>
    </ber:indexedFeatureAttributes>
  </ber:offlineSearchArray>

indexedFeatureTypes - collection of all feature types to be indexed for offline search in map
indexedFeatureAttributes - collection of feature attributes to be indexed for search. Union of all attributes for all feature types is in one collection.

Project Tools

Tools can be integrated into various places in mobile app. See Tools in mobile chapter for more info.

This chapter describes configuration of tools for these two places:

context menu in map selected features list (featureTools) via toolArray in samo-mobile.xml
project menu in full map component (tools) via toolArray in samo-mobile.xml

Example:

<ber:toolArray>
...

  <ber:tool name="Tool name">
    <ber:icon xlink:href="resource.xml#ic_1"/>
    <ber:script>
      <ber:function id="toolId1"/>
      <ber:parameterArray>
        <ber:parameter name="parameter1" value="value1"/>
      </ber:parameterArray>
    </ber:script>
  </ber:tool>
...

  <ber:featureTool name="Feature tool name">
    <ber:icon xlink:href="resource.xml#ic_2"/>
    <ber:featureTypeArray>
      <ber:featureType xlink:href="model.xml#ft_1"/>
      <ber:featureType xlink:href="model.xml#ft_2"/>
    </ber:featureTypeArray>
    <ber:script>
      <ber:function id="featureToolId1"/>
      <ber:parameterArray>
        <ber:parameter name="parameter1" value="value1"/>
        <ber:parameter name="parameter2" value="value2"/>
      </ber:parameterArray>
    </ber:script>
  </ber:featureTool>
...

</ber:toolArray>

All tools at all configuration places uses nearly same common syntax. Common description is in chapter referenced above. Description below explains only differences.

Note: Conditional tools visibility cannot be used in this toolArray configuration.

toolArray - this array in samo-mobile.xml configuration can contain tool or featureTool definitions.
All featureTools from this section are automatically added to context menu on the cards (to corresponding feature types) in the list of features selected from map in full map component.
All tools from this section are automatically added to project menu located in the lower right corner of the full map component above the main map menu
featureTypeArray – list of feature types, whose the function is intended for.

**Note:**This array is mandatory only for featureTool and only in the toolArray in samo-mobile.xml. When the featureTool is configured within the toolbar at other places in configuration, this feature type collection is unnecessary

Feature Presentation

It’s possible to specify for a feature type:

color - attribute containing RGB color code can be set for coloring the cards in the browse of features
icon - set of icons with conditional visibility can be defined for displaying on the cards in the browse of features
formPicture – link to resource containing raster image. The image will be displayed in the editing form header

Example:

<ber:featurePresentation>
  <!—- Resource containing the picture -->
  <ber:formPicture xlink:href="resource.xml#formPicture1"/>
  <ber:featureType xlink:href="model.xml#ft_1">
    <ber:attributeArray>
      <!—- Attribute containing color -->
      <ber:attribute id="color" xlink:href="model.xml#at_color"/>
    </ber:attributeArray>
    <ber:browseIconArray>
      <ber:browseIcon>
        <ber:condition>'at_1' = 1</ber:condition>
        <ber:conditionMetIcon xlink:href="resource.xml#exclamation-red"/>
        <ber:conditionNotMetIcon xlink:href="resource.xml#exclamation-green"/>
      </ber:browseIcon>
      <ber:browseIcon>
        <ber:condition>'at_2' = 1</ber:condition>
        <ber:conditionMetIcon xlink:href="resource.xml#on-off-green"/>
      </ber:browseIcon>
    </ber:browseIconArray>
  </ber:featureType>

  <ber:featureType xlink:href="model.xml#ft_bbb">
    <ber:attributeArray>
      <!—- Attribute containing color code in related codelist column -->
      <ber:attribute id="color" xlink:href="model.xml#at_456/ca_010_color "/>
    </ber:attributeArray>
  </ber:featureType>
</ber:featurePresentation>

featureType - reference to feature type that the configuration is intended for
formPicture - optional configuration - reference to picture in resource.xml
attribute - reference to feature attribute with specific meaning for mobile application
attribute id - keyword explaining the attribute meaning - only possible value for now is "color"
browseIconArray - set of rules with icon definitions - each browseIcon is evaluated independently
browseIcon - each browseIcon contains condition and one or two references to icon definition
condition - condition for evaluating the icon visibility. Condition can be included in more places in mobile configuration and it has common syntax for all mobile configuration parts. For more info see Attribute conditions in mobile.
conditionMetIcon - optional reference to icon that is displayed on the card when the condition result is true - see Icons in mobile
conditionNotMetIcon - optional reference to icon that is displayed on the card when the condition result is false - see Icons in mobile

Work Orders (Android only)

Section defines work orders configuration for "workforce" functionality in mobile app. This section is mandatory when there is "workOrders" screen type defined in screens. Otherwise, this section can be omitted.

Example:

<ber:workOrderArray>
  <ber:workOrder>
    <ber:featureTypeArray>
      <ber:featureType xlink:href="model.xml#ft_WO"/>
    </ber:featureTypeArray>
    <ber:attributeArray>
      <ber:attribute id="woStartDate" xlink:href="model.xml#at_start"/>
      <ber:attribute id="woEndDate" xlink:href="model.xml#at_end"/>
    </ber:attributeArray>
  </ber:workOrder>
</ber:workOrderArray>

workOrderArray - this array can contain one or more work order definitions. Typically, there is just one definition for the project. More definitions can be used when there are more feature types representing work orders with different feature attributes.
workOrder - each workOrder contains set of feature types and feature attributes used for work orders functionality in mobile app
featureTypeArray - list of feature types representing work orders. More feature types can be defined here, if they have common feature attributes used for work orders functionality
attributeArray - list of feature attributes used for work orders functionality
attribute - reference to feature attribute with specific meaning for mobile application
attribute id - keyword explaining the attribute meaning - possible values are:
- woStartDate - attribute representing start date of the work order
- woEndDate - attribute representing end date of the work order

Allocations (Android only)

Section defines allocations configuration for "workforce" functionality in mobile app. This section is mandatory when there is "allocations" screen type defined in screens. Otherwise, this section can be omitted.

Example:

<ber:allocationArray>
  <ber:allocation>
    <ber:featureTypeArray>
      <ber:featureType xlink:href="model.xml#ft_alloc"/>
    </ber:featureTypeArray>
    <ber:attributeArray>
      <ber:attribute id="alStartDate" xlink:href="model.xml#at_start"/>
      <ber:attribute id="alEndDate" xlink:href="model.xml#at_end"/>
      <ber:attribute id="alWorkOrder" xlink:href="model.xml#at_workOrderRef"/>
    </ber:attributeArray>
  </ber:allocation>
</ber:allocationArray>

allocationArray - this array can contain one or more allocation definitions. Typically, there is just one definition for the project. More definitions can be used when there are more feature types representing allocations with different feature attributes.
allocation - each allocation contains set of feature types and feature attributes used for allocations functionality in mobile app
featureTypeArray - list of feature types representing allocations. More feature types can be defined here, if they have common feature attributes used for allocations functionality
attributeArray - list of feature attributes used for allocations functionality
attribute - reference to feature attribute with specific meaning for mobile application
attribute id - keyword explaining the attribute meaning - possible values are:
- alStartDate - attribute representing starting date for the allocation
- alEndDate - attribute representing finishing date for the allocation
- alWorkOrder - featureRef attribute referencing related work order

User Configuration in Mobile (Android only)

Note: User configuration is mandatory when the application includes "workforce" functionality. It means when there is "workOrders" screen or "allocations" screen defined or when there are %%USER%% variables used in configuration.

Moreover, saving user position to system can be enabled by this user configuration. When this is enabled, mobile app updates geometry of a feature representing logged user according to the real position of the device in defined interval.

Example:

<ber:user updatePositionInterval="20">
  <ber:featureType xlink:href="model.xml#ft_employee">
    <ber:graphicComponentType xlink:href="model.xml#ft_g_employee_curPos"/>
  </ber:featureType>
  <ber:attributeArray>
    <ber:attribute id="userId" xlink:href="model.xml#at_employee_userId"/>
  </ber:attributeArray>
</ber:user>

user updatePositionInterval – optional time in seconds. If the position changed after given time, update is sent. If the position should not be saved at all, this attribute can be omitted.
featureType – feature type that represents mobile app users. If the position should be saved, this feature type must be as point graphic feature defined in model.xml.
graphicComponentType – optional graphical child feature type to be updated in case of feature type with shared semantics
attribute userId – attribute which includes ID of the user (corresponding to SEC_USER.USER_ID)

TELCO in SAMO Mobile

SAMO Mobile application is able to show the telco connections. List of feature types containing TELCO structure considered by mobile application must be defined by specifying metadata group id in groupArray of samo-mobile.xml.

Example:

  <ber:groupArray>
    <group key="telcoNodeElements" value="telcoDevices"/>
  </ber:groupArray>

Parameters

There is a section in samo-mobile.xml with the set of common parameters. Possible parameter names are described in this section.

Example:

<ber:parameterArray>
  <ber:parameter name="tenant" value="business"/>
  <ber:parameter name="offlineChangesTimeLimit" value="24"/>
  <ber:parameter name="myPlacesFolder" value="8888888888"/>
  <ber:parameter name="offlineSignalLimit" value="60s:4G:50%"/>
</ber:parameterArray>

tenant - optional parameter for calling Business server; default value is asseco-ce
offlineChangesTimeLimit – optional parameter [hours] setting the oldest possible change done in offline which can be synchronized when switching to online. If the oldest change is older than the parameter, the synchronizing is rejected
myPlacesFolder – optional parameter includes folder id in store. If defined, My Places settings are saved in this folder instead of the root folder
offlineSignalLimit – optional parameter. (Android only) If defined, application checks signal quality for specified time interval. If the application is in online mode and signal is worse quality than defined for the whole defined interval, the application switches to offline mode automatically. If the application is in offline mode and signal is better quality than defined for the whole defined interval, the application switches to online mode automatically. Syntax of the value: "XXs:YG:ZZ%" where:
- XX is interval length in seconds
- YG is minimal acceptable signal quality - possible values are 2G, 3G, 4G, 5G
- ZZ is minimal acceptable signal strength - possible values are 25, 50, 75

Project Info​

Screens (Android only)​

Screen Types​

Browse Definition (Android only)​

Filtering​

Map Layers​

Map Components (Android only)​

Offline Map (Android only)​

Offline Workflow (Android only)​

Offline Rules (Android only)​

Sketch Tasks​

Relationships​

Relationships in Offline​

Search Configuration​

Offline Search​

Project Tools​

Feature Presentation​

Work Orders (Android only)​

Allocations (Android only)​

User Configuration in Mobile (Android only)​

TELCO in SAMO Mobile​

Parameters​

Project Info

Screens (Android only)

Screen Types

Browse Definition (Android only)

Filtering

Map Layers

Map Components (Android only)

Offline Map (Android only)

Offline Workflow (Android only)

Offline Rules (Android only)

Sketch Tasks

Relationships

Relationships in Offline

Search Configuration

Offline Search

Project Tools

Feature Presentation

Work Orders (Android only)

Allocations (Android only)

User Configuration in Mobile (Android only)

TELCO in SAMO Mobile

Parameters