From wiki.ginstr.com
Jump to: navigation, search

configuration.xml

configuration.xml will be used by Android client and server to provide information to execute all necessary initialisation procedures.
It is part of every ginstr app and is located in folder ginstrAppId/database/configuration.xml

XML Attributes Description

Attribute Description
generate defines if tables/columns should be built based on information in configuration.xml

Can be

  • true - tables/columns will be built base on configuration.xml
  • false - tables/columns will be built base on layout XML files and configuration.xml will be used only for getting localized table/column names (default value)

Sub nodes

configuration.xml consists of the following sub-nodes:

<tables> node

This is an example of how <tables> node should look like within configuration.xml.
<?xml version="1.0" encoding="UTF-8"?>
<configuration xmlns="http://www.ginstr.com/schema/configuration" 
               xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
               xsi:schemaLocation="http://www.ginstr.com/schema/configuration http://iwdev.enaikoon.de/schema/configuration/configuration.xsd" 
               generate="true|false">
    <tables>
        <table id="tableOneId" name="tblOneName" replicate="true|false" replicateFromServer="all|table|none" noErasableContent="true|false">
            <columnText id="colOneId" name="colOneName" unique="true|false" required="true|false|client" visibility="visible|invisible|hidden">
               <len>15</len>
               <horizontalAlignment>left</horizontalAlignment>
               <multiline>true|false</multiline>
            </columnText>
            <columnNumber id="colTwoId" name="colTwoName" unique="true|false" required="true|false|client" visibility="visible|invisible|hidden">
               <decimalPlaces>2</decimalPlaces>
               <natural>true</natural>
               <percentage>false</percentage>
               <notNegative>false</notNegative>
            </columnNumber>
        </table>
        ....
        ....
        <table id="tableTwoId" name="tblTwoName" noErasableContent="true|false">
            <columnText id="colOneId" name="colOneName" unique="true|false" required="true|false|client" visibility="visible|invisible|hidden">
                <len>15</len>
                <horizontalAlignment>left</horizontalAlignment>
                <multiline>true|false</multiline>
            </columnText>
            ...
            ...
            <columnNumber id="colTwoId" name="colTwoName" unique="true|false" required="true|false|client" visibility="visible|invisible|hidden">
                <decimalPlaces>2</decimalPlaces>
                <natural>true</natural>
                <percentage>false</percentage>
                <notNegative>false</notNegative>
            </columnNumber>
        </table>
        ...
        ...
        <table id="tableEmployees" name="tableEmployeesName">
            <columnText id="ssoUserIdColumn" name="ssoUserIdName" unique="true" required="true" visibility="visible"/>
            <columnEmail id="emailColumn" name="emailName"/>
            <columnText id="firstNameColumn" name="firstNameName"/>
            <columnText id="lastNameColumn" name="lastNameName"/>
            <columnText id="nfcColumn" name="nfcName"/>
            <columnStatus id="activeColumn" name="activeName"/>
            <ssoUser id="ssoUserIdColumn" email="emailColumn" firstName="firstNameColumn" lastName="lastNameColumn" nfc="nfcColumn" active="activeColumn"/>
        </table>
    </tables>
</configuration>

Table

ginstr app can have multiple tables and each table is defined with node element <table>.
Each table has columns which can be of different types <column*>
XML Attributes Description
Attribute Description
id

represents internal name of the table, this attribute is not changeable.

name

name that is displayed and visible for user, it should be hardcoded string or pointer string to strings.xml

replicateFromServer

defines what from table should be replicated to client.

Can be:

  • all - table and it's rows should be replicated to client (default value)
  • table - table should be replicated to client without rows. This option should be used when statistic records should be only created on launcher side without further access.
  • none - neither table nor rows should be replicated to client
replicate deprecated: use replicateFromServer instead

defines if table will get replicated to client.

  • true (default value)
  • false
noErasableContent if attribute value is false then data will get deleted by "delete all old data" function. Otherwise, data will not get deleted

Can be

  • true
  • false (default value)
hidden specifies that table should be hidden (not possible to show to users via ginstr web except developers)

Can be

  • true
  • false (default value)
mode defines mode in which table should be shown on UI.

Can be

  • bigData - table should be shown in big data mode. This mode should be selected for tables with history data which in most cases are inserted periodically but not updated. Typical cases when this mode should be enabled: logs, gps tracking history
  • smallData - table should be shown in standard mode. This mode should be usually selected for tables with not big amount of records or which should be always actual. For example: Employees which are working in company, Organization rooms. (default value)

Column

Columns can be of different datatypes.
XML Attributes Description
Attribute Description
id represents internal name of the column, this attribute is not changeable.
name

name that is displayed and visible for user, it should be hardcoded string or pointer string to strings.xml.

unique defines if column values are unique

Can be

  • true - column unique value will automatically be set to true.
  • false - (default value)
required defines if column is required.

Can be

  • true - column required value will automatically be set to true.
  • false - (default value)
visibility

defines if column is displayed in the ginstr web UI or not.

Can be

  • visible - column will be shown in ginstr web after table is generated, later user can hide it if desired (default value)
  • invisible - column will not be shown in ginstr web after table is generated, later user can un-hide it if desired
  • hidden - column can be made visible by account with developer flag. Standard user will not be able to make this column visible or see it in table options
uniqueInsideList

list of other columns and tables inside which current column value should be unique.

Column datatypes are defined by node name which uniquely defines it:
    <columnText>
    <columnNumber>
    <columnDate>
    <columnListOfDate>
    <columnTime>
    <columnListOfTime>
    <columnDateTime>
    <columnListOfDateTime>
    <columnAssignment>
    <columnPointer>
    <columnWeekDay>
    <columnEmail>
    <columnPhoneNumber>
    <columnGps>
    <columnStatus>
    <columnPicture>
    <columnVideo>
    <columnAudio>
    <columnDocument>
    <columnSignature>
    <columnIBeacon>
    <columnDateTimeDiff>
    <columnEnum>
    <columnCounter>
    <columnBanking>
    <columnFrequency>
Each column datatype has certain settings which are defined by custom behaviour of that dataype:
i.e.
    <columnText>
        <len></len>
        <horizontalAlignment></horizontalAlignment>
        <multiline>true|false</multiline>
    </columnText>

    <columnDateTime>
        <minDate></minDate>
        <maxDate></maxDate>
        <minTime></minTime>
        <maxTime></maxTime>
        <defaultFilter></defaultFilter>
        <preset></preset>
        <setCurrent></setCurrent>
        <notEditable></notEditable>
    </columnDateTime>
Replication of certain column types is controlled in column settings of that column. Replication can be enabled or disabled for following columns:
  • audio
  • video
  • picture
  • signature
  • document
More details about datatypes and which syntax to use can be found here
Column order will be defined by the order in which the columns appear in the configuration.xml file from top of the file to the bottom
Combined key for a group of columns

The element uniqueKeys is a sub element of column.

uniqueKeys
define a combined key for a group of columns. ('unique group' of columns) The combination of values of this columns are unique. The element holds a list of names, each column holding the same uniqueKey name is part of the group.

Element of uniqueKeys:

name
the name of the unique key

Sample:

 <uniqueKeys>
  <name>key1</name>
  <name>key2</name>
 </uniqueKeys>

Sample where the combination text/number1 is unique and also the combination text/number2 is unique

 <columnText id="text">
  <uniqueKeys>
   <name>key1</name>
   <name>key2</name>
  </uniqueKeys>
 </columnText>
 <columnNumber id="number1">
  <uniqueKeys>
   <name>key2</name>
  </uniqueKeys>
 </columnText>
 <columnNumber id="number2">
  <uniqueKeys>
   <name>key1</name>
  </uniqueKeys>
 </columnText>

The element uniqueKeys is illegal for columnGps, columnAssignment and columnPointer Column datatypes are defined by node name which uniquely defines it:

    <columnText>
    <columnNumber>
    <columnDate>
    <columnListOfDate>
    <columnTime>
    <columnListOfTime>
    <columnDateTime>
    <columnListOfDateTime>
    <columnAssignment>
    <columnPointer>
    <columnWeekDay>
    <columnEmail>
    <columnPhoneNumber>
    <columnGps>
    <columnStatus>
    <columnPicture>
    <columnVideo>
    <columnAudio>
    <columnDocument>
    <columnSignature>
    <columnIBeacon>
    <columnDateTimeDiff>
    <columnEnum>
    <columnCounter>
    <columnBanking>

Each column datatype has certain settings which are defined by custom behavior of that datatype: i.e.

    <columnText>
        <len></len>
        <horizontalAlignment></horizontalAlignment>
        <multiline>true|false</multiline>
    </columnText>

    <columnDateTime>
        <minDate></minDate>
        <maxDate></maxDate>
        <minTime></minTime>
        <maxTime></maxTime>
        <defaultFilter></defaultFilter>
        <preset></preset>
        <setCurrent></setCurrent>
        <notEditable></notEditable>
    </columnDateTime>

Replication of certain column types is controlled in column settings of that column. Replication can be enabled or disabled for following columns:

  • audio
  • video
  • picture
  • signature
  • document

Column order will be defined by the order in which the columns appear in the configuration.xml file from top of the file to the bottom

Synchronization of table with SSO accountsssoUser is used to enable synchronization of table rows with sso. It contains the following attributes:

id
(text) (required) - id of column where sso user id should be stored
email
(email) (optional) - id of column where user's email should be stored
firstName
(text) (optional) - id of column where user's first name should be stored
lastName
(text) (optional) - id of column where user's last name should be stored
nfc
(text) (optional) - id of column where user's nfc should be stored
active
(status) (required) - id of column where flag if user is active should be stored

Naming convention of table id's, columns XML notation: - When writing xml nodes if node does not contain children end it with "/>" and not "</nodeName>"

<roles> node

This is an example of how <roles> node should look like within configuration.xml:
<?xml version="1.0" encoding="UTF-8"?>
<configuration xmlns="http://www.ginstr.com/schema/configuration" 
               xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
               xsi:schemaLocation="http://www.ginstr.com/schema/configuration http://iwdev.enaikoon.de/schema/configuration/configuration.xsd" 
               generate="true|false">
    <roles>
        <role id="admin" name="adminRoleName" platform="all">
            <table id="tableA" create="true" read="true" update="true" delete="true"/>
            <table id="tableB" create="true" read="true" update="true" delete="true"/>
        </role>
        <role id="user" name="userRoleName" platform="launcher">
            <table id="tableA" create="true" read="true"/>
            <table id="tableB" read="true"/>
        </role>
    </roles>
</configuration>

Roles

Each application can have several roles. Base on the roles ginstr launcher can provide access to different pages.
Role contain list of tables with appropriate permissions: create, read, update, delete. By default, permissions will be denied (not required by android side).
On android side, the role defined in configuration.xml will be used as minimum required table permission to allow user to enter the ginstr app. If some right is not defined for specific table, on android side it will be allowed.
XML Attributes Description
Attribute Description
id represents internal name of the role, this attribute is not changeable.
name name that is displayed and visible for user, it should be hardcoded string or pointer string to strings.xml
platform defines platform on which role should be used.

Can be

  • all - table and it's rows should be replicated to client
  • launcher - table should be replicated to client without rows. This option should be used when statistic records should be only created on launcher side without further access.
In future, other platforms can be added; for example web.

<replicationFilters> node

Replication filters are sets of rules which define what data will get replicated from server to client and from client to server.
ginstr launcher currently implements limited rules on the server side for filtering replication of data.

Attributes

id - unique replication filter id
appId - optional attribute which is used to define replication filter for external app tables, if not defined only data for the main app will be replicated
tableId - optional attribute, table id of table for which the replication filter rules will be applied, if not defined the data from all tables which belong to the main app will be replicated
condition - optional attribute, rules for the data which will be replicated, if not defined all data from defined tables will be replicated
replicateFromServer - optional attribute which is used to define if data from defined tables will be replicated, if not defined all data will be replicated

Condition keywords

$DAYSINPAST_X - X represents a number of days in the past from today
$USERID - represents a user id, e.g. mainUser111222
$NULL
$TRUE
$FALSE
@columnId/columnId

Condition operators

AND
OR
==
!=
>=
<=
<
>

Signature

<configuration>
<tables>....</tables>
<replicationFilters>
  <replicationFilter id="replicationFilterId">
    <appId id="appId"/>
    <tables>
      <tableId>tableId1</tableId>
      <tableId>tableId2</tableId>
      <tableId>tableId...</tableId>
    </tables>
    <condition>condition_statement</condition>
    <replicateFromServer>all|table|none</replicateFromServer>
  </replicationFilter>
</replicationFilters>
</configuration>

Example

<replicationFilter id="rf3">
  <appId id="fairparkenParkingManager"/>
  <tables>
    <tableId>bookingsPerParkings</tableId>
    <tableId>pauseTimes</tableId>
  </tables>
  <condition>@columnId/$createdOn $DAYSINPAST_2 AND @columnId/$createdBy == $USERID</condition>
</replicationFilter>

<purgeFilters> node

Purge filters are sets of rules which define what data will purged from the client.
ginstr launcher currently implements limited rules on the client side for filtering purging of data.

Attributes

appId - optional attribute which is used to define purge filter for external app tables, if not defined only data for the main app will be purged
tableId - optional attribute, table id of table for which the purge filter rules will be applied, if not defined the data from all tables which belong to the main app will be purged
condition - optional attribute, rules for the data which will be purged, if not defined all data from defined tables will be purged

Condition keywords

$DAYSINPAST_X - X represents a number of days in the past from today
$USERID - represents a user id, e.g. mainUser111222
$NULL
$TRUE
$FALSE
@columnId/columnId

Condition operators

AND
OR
==
!=
>=
<=
<
>

Signature

<configuration>
<tables>....</tables>
<purgeFilters>
  <purgeFilter>
    <appId id="appId"/>
    <tables>
      <tableId>tableId1</tableId>
      <tableId>tableId2</tableId>
      <tableId>tableId...</tableId>
    </tables>
    <condition>condition_statement</condition>
  </purgeFilter>
</purgeFilters>
</configuration>

Example

<purgeFilter>
  <tables>
    <tableId>bookingsPerParkings</tableId>
    <tableId>pauseTimes</tableId>
  </tables>
  <condition>@columnId/$createdOn $DAYSINPAST_2 AND @columnId/$createdBy == $USERID</condition>
</purgeFilter>

<plugins> node

LEFT FOR SPECIFICATION

<permissions> node

LEFT FOR SPECIFICATION
Understand if expression calculation should be included into configuration.xml (Maybe this feature will be required in Bebra)