Counters

Technical notes about the counters implementation.

• Implementation
  • Single counter description
  • Field description
• Other attributes
• Counters pre-processing
  • Duplicity

Counters defined by the frm module are described in the subordinated section – frm counters.

Client-defined counters have different implementation. They are described in the section – Client-defined counters.

System counters are unchangeable for customers using the SaaS model with shared system (aka www.aymine.com) but changeable for those who have private installation.

Counter fields are generally not listed in the documentation. See the frm/enum file for actual values of each counter.

Implementation

Counters are defined by the enum.json file. They are loaded and stored by the application so that the json file is loaded only after the system restart.

Single counter description

Each counter has description in the following structure:

{ 
   "name":"<name of the counter>",  
   "type":"<enum type>
   "fields":[
      {
         "name":"<name of the field>",
         "icon":"<icon used with field>"
         "short":"<field shortcut>", 
         "default":true, "systemOnly":true, "enumLimit":"..." ,
         "duplicity":true
      }
   ]
},

Name of the counter

Counter name should be without spaces and not longer than 30 characters.

The recommended structure is smallLetersWithFirstCapital However, it is only recommendation

enum type

Currently the following types are suppoted:

• trans – Translated counter is default. It's name is translated using the translation module linked with the counter definitions.
• icon – Counter contains only icons. User selects from icons not from texts. Counter is used to offer the list of icons. Fields for counter of the type icon does not contain names and they are not translated. Icon-only counters are used internally to select icon for some object state or other information.
• object – Counter contains name of the objects. It is used to select object from list. Objects have default translation and self-defined icons used everywhere in the system. The object-type counter don't use its own translation. Objects are always sorted when user gets list to select.
• noTrans – Counter without translation. User gets directly name from the counter fields. Counters without translation offer user directly the fields name for selection.

This type is used for selection from generally knows shorcuts (e.g. academical titles). Enum name could be up to 32 characters long so that noTrans enums could be easily used for modules that is implemented only in a single language.

Field description

Single counter can contain as many field as necessary. Eeach field can contain values according to the example.

Field Name

Name is used for the field description. It also links the field with its translation.

Name is optional. If not used, values from the short serves as the name. However, name if more clearness and is important part of the documentation. So that their usage is strongly recommended.

Icon used with field

Icon is used in the AyMINE application together with name for better clearness. They are also used by back-end when object field with counter values is placed to the report.

Icon is optional for all counter types except the icon type.

Short

Short is the value stored in the database.

AyMINE always uses 2 char char(2) type to store counters and it is recommended to use that size for all short values.

System also supports numerical short values, however number value in the counter should also be defined as string, e.g. "short":"1". They are stored as numbers to the objects fields.

If counter does not provide data stored in the database, their short values might be longer. Internally system does not create any limits for the short field length. When database field accept longer short values, it can be used

Example

{ 
"name":"PersonAfterTitle", 
"type":"noTrans", 
"fields":[
      {"name":"Ph.D."},
      {"name":"PhD"},
      {"name":"Th.D."},
      {"name":"CSc."},
      {"name":"MBA"}
   ]
},

In the example titles are stored to the field with sufficient length so that counter does not define name and short. There is neither translation of the fields "type":"noTrans", persons select directly values stored lately to the object.

Short field might be omitted if name field is defined. In that case, name value is used instead of short.

Other field attributes

Fields might have other attributes. System-defined are:

• default – value is used as default for new objects
• systemOnly – value can be set only by system. User cannot set the value. System only fields are visible in the list of field but greyed during selection.
• hidden – Hidden fields are always system-only values but they are even invisible in the lists. User cannot select them neither in the filters when filtering the table with values. Nevertheless, hidden values might be visible as value of the field in the object detail.
• enumLimit – Limits the values that are used. Limitation is used when single counter is used in various situations. Using the limits describes the subordinated section.

Counter field translation

Translation is loaded and used for field of the counter with type trans. Translation strings are stored in the language module named in the counter definition headline. It could define more translation modules, if necessary. (Although it is not clear why that might be useful)

Each line from the counter should have the translation for all supported languages. The translation should be a line

"<counter name>:<filed name>":"<field translation>"

Other attributes

Counters create open structure that accept additional values. They might be used by client as necessary.

Counters pre-processing

Counters are pre-processed during the module loading to the system.

• All counter definitions are checked and if they are not syntactically valid, operation fails
• Translation are stored to be available for faster usage by backend (for reports as well as message generation and operation record storage.)
• Pre-processing warns developers, if translation of some fields is missing.
• System develops data structure that allows generation of the back-and code to use the counters by back-end as a constants defined by object.

Duplicity

Optional attribute duplicity is used in case that counter contains several definition of the same short value with different translation. Duplicity field confirms, that counter short value duplicity is not an error but intended definition.

If counter contains more times used the short values, AyMINE raises exception during the module load (translation loads).

Several times defined counter filed with the same values stored in the database is used only in pair with conditional counter fields.

Example

The same counter is used for active and passive object. Translation active for active object could be Running but for passive object Active. Using field definition for passive and active object is distinguished using the counter conditions defined by enumLimit field.

Counter definition:

{  
   "name":"ActionStatus", 
   "fields": [
      . . . 
      {
         "name":"active", 
         "icon":"active", 
         "short":"RU",
         // Allowed only for Action object:
         "systemObject":"=['tskAction'].includes(obj.systemObject)"  
      },
      {
         "name":"running", 
         "icon":"active", 
         "short":"RU", 
         // Second field with short "RU" marked as duplicit – stops the error message
         "duplicity":true,  
         // Allowed only for Meeting object:
         "systemObject":"=['tskMeeting'].includes(obj.systemObject)"  
      },
      . . . 
   ]
}