Implementation Guidelines

UX/UI

User experience and user interface in mobile app is very important. SAMO Mobile application uses standard mobile platform elements and design patterns derived from material design guidelines. Some UI parts are fixed and hardcoded in the application, but there are many parts that can be customized by configuration.

Please, think about the customizing and extending the application by configuration the way, that is consistent with the overall application design.

Colors

Application does not use many colors - we do not want "rainbow" in the app - please, use colors carefully and consistently. There are main application colors used in the app:

main gray RGB-455A64 - it is not recommended to use full black color for texts and icons in mobile app - so main gray color is used instead of black - e.g. for tool icons
main blue RGB-2196F3 - used in headers of forms / browses and other GUI components
other colors used
- dark blue RGB-1976D2
- main green RGB-8BC34A
- dark green RGB-5A9216

When you need to use some other colors in the app (e.g. for coloring the cards in the feature list) please, base them on the ones mentioned above.

Hint: Good practice can be to derive new colors from the main blue color the way, that in HSB (Hue, Saturation, Brightness) color scheme only Hue value is changing while the Saturation and Brightness remain the same. Moreover there are some online tools for generating color palettes based on one or two main colors. E.g. https://coolors.co/. You can try to add and fix application main blue and green colors and let the tool to generate the palette.

Icons

Always use the vector format (SVG) for icons in mobile app. Icons must be simple and clear. Do not use too many details in the icons. Hardcoded application icons are always in "outline" version (not filled). You can try to use icons from material design: https://fonts.google.com/icons?icon.set=Material+Symbols (filter - material symbols / outlined).

Application always uses the main gray color for icons. Please use the same color for unified application look. If you need colored icons use colors according to previous chapter.

Forms in Mobile

At many places in mobile app, form for displaying feature details is used. This chapter describes the application logic for using the appropriate form in particular functions.

Forms can be defined using specific configuration for mobile forms in configuration extension light-forms.xml. This is the preferred approach, because this configuration can use full mobile app potential.

⚠️ Warning: light-forms.xml is not supported in LIDS Mobile for iOS app yet.

Form definition from model.xml can also be re-used in mobile app.

More form definitions for one feature type can exist in both configurations.

Appropriate form to use can be determined automatically by the application in some cases or it can be specified by configuration in other cases.

Forms Specified by Configuration

Only light-forms can be used. Every light form definition has some id. Form definition can be referred by this id. Typically in some tools configuration there is a optional formId parameter, which can be used for specifying the particular form when the tool is used. See Toolbars in Mobile for more info about tools.

Forms Determined Automatically

Application always works with feature type and with usage when looking for the right form in particular situation. Usage can be defined both in light form definition and also in model.xml form definition. More usage keywords can be specified for one form definition. Each function in mobile app, which uses form for displaying feature details has a designated usage.

Basic usage keywords:

detail - used in light-forms.xml - usage for functions that opens feature detail in readonly mode
edit - used in light-forms.xml - usage for functions that opens feature detail in edit mode
default - used in model.xml - standard usage also for LIDS Edit/Explorer which can be used by mobile app also
mobileFull – used in model.xml - usage for mobile form definition in model.xml forms
(mobileSimple – used in model.xml - this usage is not for displaying feature details - it is used mainly on the cards in the list of features)

There are more usages that can be used for special cases. These usages are described in relevant chapters.

Application form searching process:

use light form defined for the given feature type with the usage required by particular function
if it is not found, use form definition for the given feature type from model.xml with usage "mobileFull"
if is is not found, use form definition for the given feature type from model.xml with usage "default"
if it is not found, generate form from all feature attributes of the given feature type with random order

When light form is not used and the form is created using model.xml configuration, the form is generated as tab control with 3 tabs:

attributes - containing all feature attributes with usage "mobileFull" or "default" or all attributes
relations - containing related features of the feature type (see more in Relationships chapter)
attachments - containing attachments of the feature type

Toolbars in Mobile

Toolbars in mobile app can be configured at many places. Each toolbar can contain several tools. Each tool has its own functionality. There are three types of tools:

featureTool – function, which needs some source feature as a context. Usually featureTool do "something" with this source feature.
browseTool – function, which needs some list of features as a context. Usually browseTool do "something" with these features.
tool – common function without any context

Tools can be integrated into various places:

browses (Android only)
- browseTools and tools can be added to browseToolbar via browseConfig
- featureTools and tools can be added to individual cards of the browse via featureToolbar in browseConfig
light forms (Android only)
- featureTools and tools can be added to toolbar in simpleLayout or section toolbar
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

Last two bullet points are described in Project tools chapter where the tools are enclosed in toolArray common for the whole project.

But the syntax for defining the tools is nearly the same in all places.

This chapter describes configuration for toolbars.

Note: When the toolbar is configured for the browse, featureToolbar or browseToolbar must be used instead of toolbar, because both browse and feature tools are allowed to be defined for the browse. See Browse configuration for more info.

toolbar element should be used on all other places in configuration.

Example:

<ber:toolbar>
  <ber:tool name="Tool name" offline="true">
    <ber:icon xlink:href="resource.xml#ic_1"/>
    <ber:visibility visible="true">
      <ber:condition>'at_1' = 20335 AND 'at_2' = '%%USERID%%'</ber:condition>
    </ber:visibility>
    <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" offline="false">
    <ber:icon xlink:href="resource.xml#ic_2"/>
    <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:toolbar>

toolbar or browseToolbar or featureToolbar - main element for toolbar definition

Note: browseTool can be included only in browseToolbar. featureTool can be included in featureToolbar or in toolbar. tool can be included in any toolbar / browseToolbar / featureToolbar.
tool / featureTool / browseTool offline - true / false attribute. If true, the tool can be used in offline mode. Default value is false. It is always necessary to consider, whether particular tool can work in offline mode or not.
tool / featureTool / browseTool name - optional name of the tool
icon – optional reference to tool icon - see Icons in mobile

Note: Both name and icon definition is optional, but one of them should be defined. When both name and icon definition exists - it depends on the space available for the tool button in the device. When there is enough space, both name and icon is displayed on the tool button. When there is not enough space, only icon is visible.
visibility - optional visibility definition for the tool. Defines when the tool is visible and when it is not.
visibility visible - true / false attribute. If true, the tool is visible when the condition result is true. If false, the tool is hidden when the condition result is true.
condition - condition syntax is described in Attribute conditions in mobile.
functionid - id of the tool function. Description of available tools can be found in Mobile tools chapter.
parameterArray - set of parameters for the tool. Possible values and parameters depend on particular tool function. You can find parameters description in the mobile tools link above.

Fonts in Mobile

Mobile app is working with standard TTF fonts for text and point geometries displayed in map as all other LIDS/SAMO clients. However, there are some specific requirements for fonts which will be used in Mobile app:

⚠️ Warning: Platform list (menu Format →Platform Manager) need to be expanded by adding Microsoft Unicode BMP (UCS-2).

⚠️ Warning: Fonts used for text geometries need to be registered in the application server resources the same way as all the other symbol fonts. Even the well-known Windows fonts like e.g., Arial don’t exist on Android by default, so they need to be loaded from the application server. The server-based way of installation incl. file registration is necessary.

Icons in Mobile

There are several places in mobile app, where icons can be used:

in screen menu for screens - see Screens
in browse cards for notification icons - see Feature Presentation
in toolbars for tools - see Toolbars in Mobile
in light forms for tabs headers, etc. - see Light Forms
other places

There is always icon reference to resource.xml metadata extension. Icon must be defined in resource.xml as a vector graphic (SVG) or as a raster graphic (PNG). Icon then must be uploaded to application server. Raster icons are not recommended, because they do not scale well on devices with different screen resolutions.

Example of icon reference in mobile configuration:

<ber:icon xlink:href="resource.xml#ic_1"/>

Example of icon definition in resource.xml:

<ber:iconArray>
  ...
  <ber:icon id="ic_1" name="icon1 name">
    <ber:formatArray>
      <ber:format file="ic_1.png" name="png"/>
    </ber:formatArray>
  </ber:icon>
  <ber:icon id="ic_2" name="icon2 name">
    <ber:formatArray>
      <ber:format file="ic_2.svg" name="svg"/>
    </ber:formatArray>
  </ber:icon>
  ...
</ber:iconArray>

Hint: Optimization for mobile icon download is available. All mobile icons can be uploaded to application server zipped in one file. Mobile app then downloads only this one zip file instead of many small icon files.

Example of icon definition in resource.xml in case of zipped icons:

<ber:iconArray>
  ...
  <ber:icon id="ic_3" name="icon 3 name">
    <ber:formatArray>
      <ber:format file="mobileIcons.zip" name="svg"/>
    </ber:formatArray>
  </ber:icon>
  <ber:icon id="ic_4" name="icon 4 name">
    <ber:formatArray>
      <ber:format file="mobileIcons.zip" name="svg"/>
    </ber:formatArray>
  </ber:icon>
  ...
</ber:iconArray>

Note: In that case, icon file name in zip must be exactly the same as the icon id in the configuration with proper file extension (ic_3.svg and ic_4.svg for example above).

Attribute Conditions in Mobile

Attribute conditions can be used in more places in mobile configuration. The syntax is common for all these places.

The condition is a logical expression with references to feature attributes. The expression can contain:

references to feature attributes in single quotes - e.g. 'at_1', 'at_2' - where at_1, at_2 are attribute ids
comparison operators: =, !=, <, <=, >, >=
arithmetic operators: +, -. Can be used only in expressions with CURRENTDATE variable
LIKE operator - for checking if string attribute contains some text - e.g. 'at_1' LIKE 'text'
IN operator - for checking if attribute value is in some set of values - e.g. 'at_1' IN (1,2,3) or 'at_2' IN ('text1','text2','text3'). Can be used in all possible conditions (e.g. for visibility of some attribute in form or that are used for creating filter for request to server). It can be also used in conditions that are used for filtering features in browses or related browses.
logical operators: AND, OR
parentheses for grouping the expression parts
string values in single quotes - e.g. 'some text'
numeric values - e.g. 123, 45.67
date values recomputed to Long (miliseconds since 1970) - e.g. 1724665440000
boolean values - true, false
NULL value - for checking if attribute is empty
Codelist column reference - for checking value in codelist column - e.g. 'at_5010001.ca_103_color' = '#C040EA' - where at_501000 is attribute id, ca_103_color is codelist column id
FeatureRef attribute reference - for checking value in FeatureRef attribute - e.g. 'at_woAlloc_employee.at_employee__personalNo' = 123 - where at_woAlloc_employee is FeatureRef attribute id, at_employee__personalNo is attribute id in referenced feature type
RELATION_EXISTS(relationType/roleType, condition) - logical function that evaluates to true if a related feature linked by the specified relationType/roleType exists and satisfies the given condition. The condition parameter is optional — if omitted, only the existence of the related feature is checked. Counterpart function RELATION_NOT_EXISTS works inversely. These functions can be used in offline workflow conditions and offline rule constraints.

Note: Attribute conditions are always evaluated for particular feature type. The attribute ids used in the condition must be from the same feature type or from its parent feature type in case of shared semantics. In case of some configuration parts, the feature type is defined directly in the configuration part (e.g. featurePresentation, user). In other cases, the feature type is defined indirectly by context - e.g. in browse, the feature types are defined in filter/featureTypeArray; in tool, the feature types are defined in featureTypeArray; in relationship, the feature type is defined by the context of displayed relationships.

The basic condition syntax can be extended with two optional constructs that can be used together or independently — they are described in the following sections.

Type Constraint via Meta Group

<ber:condition> accepts an optional attribute typeConstraintMetaGroup. When present, the condition is only evaluated if the feature's feature type ID is contained in the specified metadata group. If the feature type is not in the metadata group, the condition evaluates to false — the attribute expression itself is not evaluated.

If typeConstraintMetaGroup is present and the condition has no expression content, the condition acts as a pure type filter — it evaluates to true if and only if the feature type is in the metadata group.

Note: The typeConstraintMetaGroup attribute accepts a single metadata group id. If filtering by multiple groups is needed, those types should be combined into a single metadata group.

Note: The metadata group check is based on the concrete feature type of the feature instance. If the metadata group should match all subtypes of an abstract feature type, the metadata group must explicitly list all concrete subtypes.

Examples:

Condition restricted to feature types in metadata group mg_pipes:

<ber:condition typeConstraintMetaGroup="mg_pipes">
  'at_pipe_diameter' > 100
</ber:condition>

Pure type filter — no attribute expression:

<ber:condition typeConstraintMetaGroup="mg_pipes"/>

Interface Condition

<ber:interfaceCondition> is an alternative to <ber:condition> that allows writing the expression using interface attribute names instead of concrete feature type attribute ids. It is particularly useful for forms or browses shared across multiple feature types implementing a common interface.

interfaceId - mandatory attribute - id of the interface (defined in model.xml) used for attribute mapping
typeConstraintMetaGroup - optional attribute - same meaning as on <ber:condition>
Element content is a condition expression with the same syntax as <ber:condition>. Attribute names refer to interface attribute names and are mapped to concrete attribute ids of the evaluated feature type before the expression is parsed.

If the feature type does not implement the specified interface, the interfaceCondition evaluates to false.

Note: RELATION_EXISTS and RELATION_NOT_EXISTS functions are not supported inside <ber:interfaceCondition> in the initial implementation. The interface attribute mapping applies only to the primary feature, not to features resolved via relations.

Note: If the interface attribute mapping does not contain a mapping for an attribute name used in the expression, a warning is logged and the interfaceCondition evaluates to false.

Examples:

Interface condition using interface attribute names:

<ber:interfaceCondition interfaceId="if_measurable">
  'lastMeasurementDate' < '%%CURRENTDATE%%'
</ber:interfaceCondition>

Interface condition combined with type constraint — evaluated only for features that are in mg_primaryAssets AND implement if_inspectable:

<ber:interfaceCondition interfaceId="if_inspectable" typeConstraintMetaGroup="mg_primaryAssets">
  'inspectionStatus' = 'overdue'
</ber:interfaceCondition>

Combining `<ber:condition>` and `<ber:interfaceCondition>`

The typeConstraintMetaGroup attribute can be used on both <ber:condition> and <ber:interfaceCondition>. However, using both <ber:condition> and <ber:interfaceCondition> on the same parent element at the same time is not supported. Each parent element should use either <ber:condition> or <ber:interfaceCondition>, but not both.

typeConstraintMetaGroup (and <ber:interfaceCondition>) can be used in any place that accepts <ber:condition>. They are particularly useful in: browse filter (<ber:filter> in Browse Definition), browse icons (<ber:browseIcon> in Feature Presentation), light form visibility and accessibility, condition in <ber:relatedBrowse> and condition in <ber:featureRefEditor>.

Places where the condition can be used in light-forms.xml:

showing/hiding (visibility) and enabling/disabling (accessibility) attributes, tabs, steps and sections in light forms
filtering features in browses and related browses (condition in filter in dataSource)
showing/hiding (visibility) tools in toolbars (featureToolBar/browseToolBar/toolBar)
attributeConstraints in inputs in forms

Examples:

<ber:filter>
  <ber:featureTypeArray>
    <ber:featureType xlink:href="model.xml#ft_01"/>
  </ber:featureTypeArray>
  <ber:condition>
    'at_01' = '%%THIS.at_01%%' AND 'at_02' = '%%THIS.at_02%%' AND 'at_03' = '%%THIS.at_03%%'
  </ber:condition>
</ber:filter>

<ber:attributeInput xlink:href="model.xml#at_manuYear" label="Year manu./check" readOnly="true">
  <ber:visibility visible="true">
    <ber:condition>
      ('at_01_cl_kind' = 4 OR 'at_01_cl_kind' = 5) AND 'at_02_cl_status' = 0
    </ber:condition>
  </ber:visibility>
</ber:attributeInput>

<ber:attributeInput xlink:href="model.xml#at_countDownNew">
  <ber:annotation>
    <ber:content>
      Last value: %%at_countDownOld%%
    </ber:content>
  </ber:annotation>
  <ber:attributeConstraint>
    <ber:condition>
      ('at_countDownNew' >= 'at_countDownOld') OR 'at_countDownNew' = null
    </ber:condition>
    <ber:message>
      The value of the new countDown is less than the old one!
    </ber:message>
  </ber:attributeConstraint>
</ber:attributeInput>

<ber:featureTool name="Construction" offline="true">
  <ber:visibility visible="true">
    <ber:condition>
      'at_workOrder_N01' != 1 AND 'at_workOrder_unready' != 1 AND 'at_workOrder_T06' != 1 AND 
      ('at_workOrder_cl_electrometerClass' = 1 OR 'at_workOrder_cl_electrometerClass' = 2 OR 
       'at_workOrder_cl_electrometerClass' = 3 OR 'at_workOrder_cl_electrometerClass' = 4) AND 
      'at_wo_fr_countDownNew' != NULL AND 'at_wo_fr_electometer' != NULL AND 'at_wo_protocolState' != 2
    </ber:condition>
  </ber:visibility>
  <ber:script>
    <ber:function id="createProtocol"/>
      <ber:parameterArray>
      <ber:parameter name="featureType" value="ft_prtConstruction"/>
      <ber:parameter name="form" value="fd_prtConstruction"/>
      <ber:parameter name="input" value="setCountDownConstruction"/>
      <ber:parameter name="singleInstance" value="true"/>
    </ber:parameterArray>
  </ber:script>
</ber:featureTool>

Places where can be condition used in samo-mobile.xml:

filtering features in browse defintion (filter in dataSource)
conditional displaying of notification icons on feature cards (condition in browseIcon in featurePresentation)
showing/hiding (visibility) tools in toolbars (featureToolBar/browseToolBar in browseConfig)
conditional workflow transition in offline workflow configuration
constraint validation in offline rule configuration (constraint in rule in offlineRuleArray)

Examples:

<ber:filter>
  <ber:featureTypeArray>
    <ber:featureType xlink:href="model.xml#ft_allocation"/>
  </ber:featureTypeArray>
  <ber:condition>
    ('at_allocation_cl_allocationState' = '1' OR 'at_allocation_cl_allocationState' = '2' OR 
     'at_allocation_cl_allocationState' = '3' OR 'at_allocation_cl_allocationState' = '4') AND 
    'at_allocation_fr_boEmployee.at_boEmployee_userIdProperty' = '%%USERID%%'
  </ber:condition>
</ber:filter>

<ber:filter>
  <ber:featureTypeArray>
    <ber:featureType xlink:href="model.xml#ft_boVirtTimeTable"/>
  </ber:featureTypeArray>
  <ber:condition>
    'at_boVirtTT_fr_boEmployee.at_boEmployee_userIdProperty' = '%%USERID%%' AND 
    'at_boVirtTT_dateTime' > '%%CURRENTDATE%% - 86400' AND 'at_boVirtTT_dateTime' <= '%%CURRENTDATE%% + 86400'
  </ber:condition>
</ber:filter>

<ber:browseIconArray>
  <ber:browseIcon>
    <ber:condition>'at_boWorkRealiz_is_outageNeeded' = 1</ber:condition>
    <ber:conditionMetIcon xlink:href="resource.xml#exclamation-red"/>
    <ber:conditionNotMetIcon xlink:href="resource.xml#exclamation-green"/>
  </ber:browseIcon>
  ...
</ber:browseIconArray>

<ber:stateArray>
  ...
  <ber:state id="inRealization" label="Realization">
    <ber:transitionArray>
      <ber:transition targetState="interrupted" workflowAction="interrupted" label="Interrupt work"/>
      <ber:transition targetState="finished" workflowAction="finished" label="Finish work">
        <ber:condition>
          ('at_boAllocation_fr_boWR.at_boPP_fr_boRecapitulation' != NULL AND 
           'at_boAllocation_fr_boWR.at_boPP_fr_boRecapitulation.at_boRecapitulation_cl_isFinished' != 0)
        </ber:condition>
      </ber:transition>
    </ber:transitionArray>
  </ber:state>
  ...
</ber:stateArray>

<!-- Offline rule constraint with RELATION_EXISTS -->
<ber:rule>
  <ber:condition>'at_status' = 1</ber:condition>
  <ber:constraint>RELATION_EXISTS(as_1/rt_1, 'at_1' = 3)</ber:constraint>
  <ber:message>Cannot set status to 1 without related feature.</ber:message>
</ber:rule>

Variables for Conditions and Tool Parameters

Some application variables can be used in mobile app configuration:

in conditions described in previous chapter
in tool parameters (see Mobile Tools attributes parameter)

Variables syntax is common. System variables always must always be enclosed in double percent characters (e.g %%USERID%%).

System variables:

USERID - variable is replaced by ID of currently logged user. E.g.: 'at_woAlloc_employee.at_employee__userIdProperty' = '%%USERID%%'
CURRENTDATE - variable is replaced by current date (time 00:00:00). E.g.: 'at_woAllocation_dateFrom' > '%%CURRENTDATE%% - 86400'. +/- values are in seconds
USER.ATTRIBUTEID - variable is replaced by value of attribute ATTRIBUTEID of of the feature that is representing currently logged user. E.g.: 'at_woAlloc_employee.at_employee__personalNo' = '%%USER.at_employee__personalNo%%')

Note: To make such condition work, user configuration must exists in samo-mobile.xml

THIS.ATTRIBUTEID - variable is replaced by value of attribute ATTRIBUTEID of the feature that is currently processed in the context. This variable can be used in some light form component where the context is the feature that is being displayed in the form or in some parameter of feature tool. Example is in List of Features chapter.

Note: Additional placeholder %%GPS%% (device's last known location) is recognized only inside the attributes tool parameter, not in conditions. See attributes for details.

Browse Configuration (Android only)

Each browse in mobile app contains cards representing features. Each card contains:

featureInfo - user readable feature identification defined in model.xml for each feature type
set of important attributes - set is specified by form definition in model.xml with usage "mobileSimple"
optional feature icon - there is always default icon displayed specified by application. It can be hidden or changed by configuration - see itemIcon in example below
optional color stripe - can be specified in feature presentation for particular feature type
optional indication icons - can be specified in feature presentation for particular feature type
optional set of tools - can be configured by featureToolbar see example below

Browse presentation can be controlled by browse configuration. It can be defined for each browse in mobile app. There are several places with browses in mobile app:

screen browse - samo-mobile.xml - browse included in some screen definition
browse component - light-forms.xml - browse component included in some light form
related browse component - light-forms.xml - component for related features included in some light form
protocols component - light-forms.xml - component for protocols included in some light form

Browse configuration contains settings for browse presentation and behavior. It also can contain definition of toolbars and their tools.

Example:

<ber:browseConfig header="Browse Heading" allowFilter="true" allowSendToMap="true" allowDetail="false" allowModification="true" allowDelete="false" allowNavigate="true">
  <ber:mobileSimpleForm xlink:href="model.xml#fmd_mobile_basic"/>
  <ber:groupByAttribute xlink:href="model.xml#ft_1/at_1"/>
  <ber:featureToolBar>
  ...
  </ber:featureToolBar>
  <ber:browseToolBar>
  ...
  </ber:browseToolBar>
  <ber:itemIcon iconType="none"/>
<!--  <ber:itemIcon iconType="direct" xlink:href="resource.xml#icon1"/> -->
  <ber:summary>Max date: ##max(at_date)##, Min date: ##min(at_date)##, Quantity: ##sum(at_quantity)##</ber:summary>
</ber:browseConfig>

Note: All tags inside browseConfig must be specified in the right order as in example above. All of them are optional.

browseConfig – main tag for browse configuration
- header – optional header text displayed in the browse header
- allowFilter – true/false When true, filter button for simple browse filtering is displayed in the browse header
- allowSendToMap – true/false When true, send to map button is displayed in the browse header. Selected features are located in the full map screen.
- allowDetail – true/false When true, feature detail can be displayed in form by clicking the card - see Forms in mobile (light form usage detail).
- allowModification – true/false When true, modification of features is allowed in the browse. Edit icon is added to each card in the list of features. Form for editing is opened when the icon is clicked - see Forms in mobile (light form usage edit).
- allowDelete – true/false When true, delete icon is added to each card in the list of features. Feature is deleted when the icon is clicked (after user confirmation).
- allowNavigate – true/false When true, navigation button is displayed on each card in the list of features. If the feature represented by the card has no geometry, navigation button is not visible. Navigation to the position represented by selected feature geometry is started in external navigation application.
  
  Note: Navigation functionality is not implemented by SAMO Mobile app, some third party navigation application must be installed in the device for this functionality.
mobileSimpleForm – reference to form in model.xml used for displaying feature attributes on the cards in the list of features. Mobile app uses form definition with usage mobileSimple automatically. This configuration should be used only when it is necessary to override the default form definition in the particular browse. e.g. when there are more places in mobile app where the browse with same feature type is presented and in each browse it is necessary to show another set of attributes on the card.
groupByAttribute – optional reference to feature attribute. When specified, the list of features is grouped by this attribute. Each group can be collapsed or expanded.
featureToolBar – optional definition of toolbar with tools displayed on each card in the list of features. See Toolbars in Mobile for more info.
browseToolBar – optional definition of toolbar with tools for the browse. Tools in such toolbar are working with features in the list (either with all of them or with selected ones). See Toolbars in Mobile for more info.
itemIcon – optional configuration of feature icon displayed on each card in the list of features. Possible values of iconType attribute are:
- default – default icon defined by application is displayed
- none – no icon is displayed
- direct – custom icon is displayed. Icon must be defined by xlink:href reference to resource.xml icon definition. See Icons in mobile for more info.
summary – optional text displayed in the browse header below the header text. It can contain attribute values of all features in the list processed by some functions. Syntax for including attribute values is:

##function(at_attribute)## where:
- function – possible values are: min, max, sum, avg for numeric attributes and min, max for date attributes
- at_attribute – reference to feature attribute

Multiple functions can be included in the summary text. Example of summary text is in the example above.

Mobile Tools

There are many tools implemented in mobile app. Each tool has its own functionality and its own set of parameters. Tools can be integrated into various parts of the mobile application:

in toolbars in screen browses - see Browse configuration
in toolbars in light forms - see Light forms
in context menu in map selected features list - see Project tools
in project menu in full map component - see Project tools

This chapter describes available tools and their parameters.

There are three types of mobile tools:

FeatureTool - can only be used with context of some source feature (toolbar in lightform, card of feature in feature browse)
BrowseTool - can only be used with context of some list of source features (browseConfig toolbar)
Tool - common tool that can be used without any context

FeatureTools

phoneCall

Take phone number from source feature attribute and send this number to device operating system to use it for phone call.

Parameters	Description	Mandatory	Android	iOS
phoneAttribute	Feature attribute with phone number	✅	✅	✅

navigate

Take address from source feature attribute and send this text string to device operating system to use it for navigation app. When the addressAttribute is not specified, then the feature geometry is used for navigating to.

Parameters	Description	Mandatory	Android	iOS
addressAttribute	Feature attribute with address	❌	✅	✅

editForm

Open new form for source feature for editing.

Parameters	Description	Mandatory	Android	iOS
formId	Id of light-form to open for edit. More	❌	✅	✅
attributes	Some attributes can be predefined and prefilled in opened form. Only attributes with null value are predefined by this parameter. Not null values are preserved. More	❌	✅	❌
formSize	Size of the form. Possible values: auto, fullScreen. More	❌	✅	❌
mode	Opening mode of the form. Possible values: readonly, detail, edit. Default is "edit". More	❌	✅	❌

constructNewRelatedFeature

Construct new feature in map with relation to source feature. Can't be used in lightform yet.

Parameters	Description	Mandatory	Android	iOS
relationType	Type of relation to source feature	✅	✅	✅
roleType	Role of the new feature	✅	✅	✅
featureType	Feature type to be constructed	✅	✅	✅
formSize	Size of the form. Possible values: auto, fullScreen. More	❌	✅	❌
attributes	Some attributes can be predefined and prefilled for constructed feature. More	❌	✅	❌

showRelatedFeatures

Show list of related features to source feature.

Parameters	Description	Mandatory	Android	iOS
relationType	Type of relation to source feature	✅	✅	✅
roleType	Role of the new feature	✅	✅	✅

editSuperior

Open edit form for superior feature specified by featureRef attribute of source feature.

Parameters	Description	Mandatory	Android	iOS
featureRefAttribute	FeatureRef attribute for superior feature.	✅	✅	❌
formId	Id of light-form to open for edit. More	❌	✅	❌
attributes	Some attributes can be predefined and prefilled in opened form. Only attributes with null value are predefined by this parameter. Not null values are preserved. More	❌	✅	❌
formSize	Size of the form. Possible values: auto, fullScreen. More	❌	✅	❌
mode	Opening mode of the form. Possible values: readonly, detail, edit. Default is "edit". More	❌	✅	❌

createProtocol

Open form for new protocol, which will be related to source feature.

Note: When the protocols component is used in some light form, protocols functionality is managed completely by this component and this tool is not needed. This tool can be used outside the protocols component to start the particular protocol creation from other place.

Parameters	Description	Mandatory	Android	iOS
featureType	Feature type of the protocol.	✅	✅	❌
form	Id of light-form for protocol.	✅	✅	❌
input	Id of definition from protocols.xml for prefilling the protocol attributes	❌	✅	❌
formSize	Size of the form. Possible values: auto, fullScreen. More	❌	✅	❌
singleInstance	See below	❌	✅	❌

Allowed values for singleInstance parameter:

"false" - more instances of this protocol type can be created for source feature
"true" - only one instance of this protocol type can be created for source feature
"replace" - if there is already created protocol of the same type, it will be replaced by the new one

createNewRelatedFeature

Create a new feature with relation to source feature. When opening light-form, the default usage is "edit".

Parameters	Description	Mandatory	Android	iOS
featureType	Feature type to be created.	✅	✅	❌
formId	Id of light-form to use for the new feature. More	❌	✅	❌
relationType	Type of relation to source feature	✅	✅	❌
roleType	Role of the new feature	✅	✅	❌
attributes	Some attributes can be predefined and prefilled for created feature. More	❌	✅	❌
formSize	Size of the form. Possible values: auto, fullScreen. More	❌	✅	❌
reloadParent	true - reload parent feature after the relation is created.	❌	✅	❌
skipBackgroundCreate	If true, the new feature is inserted on the server only when the form is saved. Default behavior may insert it before the form opens when no mandatory attribute is unfilled, so that server-side triggers fire early.	❌	✅	❌

changeFeatureAttributes

Change source feature attributes.

Parameters	Description	Mandatory	Android	iOS
attributes	List of attributes and new values. More	✅	✅	❌
tryClose	Possible values: true, false.	❌	✅	❌

updateAndShowDetail

Update specified attributes automatically and then open detail form. When opening light-form, the default usage is "detail".

Parameters	Description	Mandatory	Android	iOS
formId	Id of light-form to open. More	❌	✅	❌
formSize	Size of the form. Possible values: auto, fullScreen. More	❌	✅	❌
attributes	Some attributes can be updated automatically before the form is opened. More	❌	✅	❌

createNewConnectedObject

Create new feature and connect it to source via connection feature (e.g. create new business object for asset). Source is feature which the tool is defined for, by default. Optionally, source can be another feature which FT and FID is stored in some attributes of source feature. When opening light-form, the default usage is "edit".

Parameters	Description	Mandatory	Android	iOS
targetFeatureType	Feature type to be created	✅	✅	❌
formId	Id of light-form to use for the new feature. More	❌	✅	❌
attributes	Some attributes can be predefined and prefilled for created feature. More	❌	✅	❌
formSize	Size of the form. Possible values: auto, fullScreen. More	❌	✅	❌
connectionFeatureType	This feature will be created to connect source feature with target feature.	✅	✅	❌
connectionToSourceFeatureRef	Connection feature featureRef attribute for source feature value.	✅	✅	❌
sourceFeatureRefToConnect	Another source feature can be specified by featureRef attribute id of current source feature.	❌	✅	❌
sourceAttributeForFeatureType	Target feature can be connected to another source feature which FT is stored in source attribute specified by this parameter.	❌	✅	❌
sourceAttributeForFID	Target feature can be connected to another source feature which FID is stored in source attribute specified by this parameter.	❌	✅	❌

sendRelatedToMap

Find related features to source feature (even recursively) and send them to the list in full map.

Parameters	Description	Mandatory	Android	iOS
relationPath	Optionally recursive path of relation types - list of tuples delimited by comma - each tuple must contain relation type and target role type delimited by slash. Example: "relationType1/roleType1,relationType2/roleType2". FeatureRef attribute can also be used in this path instead of tuple relationType/roleType to get the master feature via featureRef. Example:"relationType1/roleType1, featureRefAttribute1, relationType2/roleType2"	✅	✅	❌

sendToMap

Send feature to the list in full map for locating. Only available for Android. Tool is without parameters.

deleteSuperior

Delete superior feature specified by featureRef.

Parameters	Description	Mandatory	Android	iOS
featureRefAttribute	FeatureRef attribute for superior feature.	✅	✅	❌

saveGPS

Save device location to feature attribute specified by gpsAttribute.

Parameters	Description	Mandatory	Android	iOS
gpsAttribute	Feature attribute in which location will be saved.	✅	✅	❌

overtakeGPS

Opens the Google Maps application with the location taken from the feature attribute value of the element specified by the gps parameter and prepares to receive a shared updated location to update this attribute. In our application is opened information dialog with a Cancel button that stops receiving the shared location.

If the optional originalGPS parameter is used, then value of attribute specified by this parameter is used as the initial location in Google Maps.

Parameters	Description	Mandatory	Android	iOS
gps	Feature attribute in which location will be saved.	✅	✅	❌
originalGPS	Feature attribute which value is used as location in Google Maps	❌	✅	❌

BrowseTools

Browse tools can be used only in context of some list of features. It is possible to select some features from the list in the app and to apply the tool only to selected features. There are two modes of tool behavior when browseTool is activated and when there are no selected features in the list:

enabledForEntireList = "true" - tool is applied to all features in the list
enabledForEntireList = "warning" - user is warned that no features are selected and he can choose to apply the tool to all features in the list or to cancel the tool execution
enabledForEntireList = "false" - tool is not executed when there are no selected features in the list

Each tool has its own default value for enabledForEntireList parameter. It can be overridden in the particular tool configuration by this parameter. This parameter can be used for every browseTool, so it is not included in the tables below. There is information about default value for each tool in the description of the tool.

changeFeatureAttribute

Change one attribute for all features in list. Default value for enabledForEntireList is "warning".

Parameters	Description	Mandatory	Android	iOS
targetAttributeId	Feature attribute id.	✅	✅	❌
targetValue	New value for attribute.	✅	✅	❌

changeFeatureAttributes

Change attributes for all features in list. Default value for enabledForEntireList is "warning".

Parameters	Description	Mandatory	Android	iOS
attributes	List of attributes and new values. More	✅	✅	❌
parallelProcessing	true (default) - send parallel requests, false - serial procesing	❌	✅	❌

bulkEdit

Change feature attributes in bulk using form. Default value for enabledForEntireList is "warning".

Parameters	Description	Mandatory	Android	iOS
formId	Id of light-form to use for changing attributes.	✅	✅	❌
attributes	Optional list of attributes and values to predefine suggested values in form. More	❌	✅	❌
formSize	Size of the form. Possible values: auto, fullScreen. More	❌	✅	❌

createNewRelatedFeature

Create new related feature in relatedBrowse component. Default value for enabledForEntireList is "true". Default usage for opened form is "edit".

Parameters	Description	Mandatory	Android	iOS
featureType	Feature type to be created.	✅	✅	❌
formId	Id of light-form to use for the new feature. More	❌	✅	❌
formSize	Size of the form. Possible values: auto, fullScreen. More	❌	✅	❌
skipBackgroundCreate	If true, the new feature is inserted on the server only when the form is saved. Default behavior may insert it before the form opens when no mandatory attribute is unfilled, so that server-side triggers fire early.	❌	✅	❌

changeFeatureState

Change workflow state for all features in list. Default value for enabledForEntireList is "warning".

Parameters	Description	Mandatory	Android	iOS
targetStateId	Target workflow state id.	✅	✅	❌

changeFeatureStateAndAttributes

Change workflow state for all features in list and some feature attributes in one step. Default value for enabledForEntireList is "warning".

Parameters	Description	Mandatory	Android	iOS
targetStateId	Target workflow state id.	✅	✅	❌
formId	Id of light-form to use for changing attributes. More	✅	✅	❌
formSize	Size of the form. Possible values: auto, fullScreen. More	❌	✅	❌

sendRelatedToMap

Find related features to all source features (even recursively) and send them to the list in full map. Default value for enabledForEntireList is "true".

Parameters	Description	Mandatory	Android	iOS
relationPath	Optionally recursive path of relation types - list of tuples delimited by comma - each tuple must contain relation type and target role type delimited by slash. Example: "relationType1/roleType1,relationType2/roleType2". FeatureRef attribute can also be used in this path instead of tuple relationType/roleType to get the master feature via featureRef. Example: "relationType1/roleType1, featureRefAttribute1, relationType2/roleType2"	✅	✅	❌

Tools

constructNewFeature

Construct new feature in map.

Parameters	Description	Mandatory	Android	iOS
featureType	Feature type to be constructed.	✅	✅	✅

createNewFeature

Create new feature. If attributes parameter is specified, new feature is created and saved without using any form. If attributes parameter is not specified and formId is also not specified, form is searched.

Parameters	Description	Mandatory	Android	iOS
featureType	Feature type to be created.	✅	✅	❌
attributes	Some attributes can be predefined and prefilled for created feature. More	❌	✅	❌
formId	Id of light-form to use for the new feature. More	❌	✅	❌
formSize	Size of the form. Possible values: auto, fullScreen. More	❌	✅	❌

Common Parameters

These parameters can be used in more tools and the syntax is always the same.

formId

The value for this parameter is id of light-form to be used. This parameter is not mandatory. When it is not specified, application finds appropriate form by itself using the following procedure:

use light-form with the right usage ("detail" for readonly tools, "edit" for edit tools), if not found
use form from model.xml with "mobileFull" usage, if not found
use form from model.xml with "default" usage, if not found
generate form for all feature attributes

attributes

Some attributes and their values can be specified in a tool parameter. Parameter value is represented by tuples separated by commas. Each tuple contains attribute id and a value separated by colon. Example: "attributeId1:value1,attributeId2:value2". Value can be:

constant - direct value for attribute (for null value use empty space - *"attributeId1:,attributeId2...")
variable - must be enclosed in doubled percent characters - supported variables:
- %%CURRENTDATE%% - actual date time
- %%USERID%% - actual logged user id from security
- %%USER%% - feature instance, representing actual logged user - can be used only on featureRef attribute related to user feature defined in mobile. see User Configuration in Mobile
- %%USER.attributeId%% - value of the given attribute of the user feature (requires user configuration)
- %%GPS%% - device's last known location as plain string in lat,lon format (decimal degrees, dot as decimal separator, 6 decimal places, no whitespace, locale-independent). Example: 50.123456,14.567890. Android only. If the location is unavailable (missing permission, no cached fix, GPS disabled, etc.), the placeholder is not substituted, the resulting attribute value is effectively empty, a warning is logged and processing of the remaining tuples continues. %%GPS%% is resolved once per tool invocation, so multiple occurrences within the same call share the same coordinates. Intended only for text attributes.
attribute - value can be taken over from another feature attribute - attribute id must be enclosed in in doubled hash characters
function - structured constructor for composite values, prefixed with $. Currently supported:
- $FEATURE(<ft>/<fid>) - constructs a featureRef value for a target attribute of type featureRef by composing feature type and feature ID from independently resolved parts. The two parts are separated by /. Each part may independently be a constant, a variable in %%...%%, or a source attribute reference in ##...##. Examples:
  - at_employeeRef:$FEATURE(ft_employee/##at_employeeId##) - constant FT, FID from a source attribute
  - at_employeeRef:$FEATURE(ft_employee/12345) - both constant
  - at_targetRef:$FEATURE(##at_kindCl/cl_targetFt##/%%USER.at_uid%%) - FT from a codelist column of a source attribute, FID from a user variable
  Note: Copying a whole featureRef value from another featureRef source attribute does not require this function — the simpler at_targetRef:##at_srcRef## form is sufficient.

Complex example: "attributeId1:1,attributeId2:abc,attributeId3:,at_attribute4:%%CURRENTDATE%%,at_attribute5:##at_sourceAttribute1##,at_attribute6:%%GPS%%,at_attribute7_FR:$FEATURE(ft_employee/##at_employeeId##)"

mode

Opening mode for the light-form. Possible values:

"readonly" - every light-form component is in readonly mode, all tool buttons are invisible
"detail" - all attributeField components are in readonly mode, all other components are editable (if it is not readonly in light-form definition), all tool buttons are visible
"edit" - default value - all components are editable, all tool buttons are visible

formSize

Every tool which uses some feature form can specify whether the form should be opened over the full device screen or if the form will be opened smaller in the center of the screen if the device screen is big enough. Possible values:

"auto" - default value, if the display is big enough, form is smaller in the center of the screen. If the display is smaller, form is opened in full screen mode
"fullScreen" - form is opened always in full screen mode

UX/UI​

Colors​

Icons​

Forms in Mobile​

Forms Specified by Configuration​

Forms Determined Automatically​

Toolbars in Mobile​

Fonts in Mobile​

Icons in Mobile​

Attribute Conditions in Mobile​

Type Constraint via Meta Group​

Interface Condition​

Combining <ber:condition> and <ber:interfaceCondition>​

Variables for Conditions and Tool Parameters​

Browse Configuration (Android only)​

Mobile Tools​

FeatureTools​

phoneCall​

navigate​

editForm​

constructNewRelatedFeature​

showRelatedFeatures​

editSuperior​

createProtocol​

createNewRelatedFeature​

changeFeatureAttributes​

updateAndShowDetail​

createNewConnectedObject​

sendRelatedToMap​

sendToMap​

deleteSuperior​

saveGPS​

overtakeGPS​

BrowseTools​

changeFeatureAttribute​

changeFeatureAttributes​

bulkEdit​

createNewRelatedFeature​

changeFeatureState​

changeFeatureStateAndAttributes​

sendRelatedToMap​

Tools​

constructNewFeature​

createNewFeature​

Common Parameters​

formId​

attributes​

mode​

formSize​

UX/UI

Colors

Icons

Forms in Mobile

Forms Specified by Configuration

Forms Determined Automatically

Toolbars in Mobile

Fonts in Mobile

Icons in Mobile

Attribute Conditions in Mobile

Type Constraint via Meta Group

Interface Condition

Combining `<ber:condition>` and `<ber:interfaceCondition>`

Variables for Conditions and Tool Parameters

Browse Configuration (Android only)

Mobile Tools

FeatureTools

phoneCall

navigate

editForm

constructNewRelatedFeature

showRelatedFeatures

editSuperior

createProtocol

createNewRelatedFeature

changeFeatureAttributes

updateAndShowDetail

createNewConnectedObject

sendRelatedToMap

sendToMap

deleteSuperior

saveGPS

overtakeGPS

BrowseTools

changeFeatureAttribute

changeFeatureAttributes

bulkEdit

createNewRelatedFeature

changeFeatureState

changeFeatureStateAndAttributes

sendRelatedToMap

Tools

constructNewFeature

createNewFeature

Common Parameters

formId

attributes

mode

formSize