Glossary

This is a glossary of terms relating to Zymonic. Search the terms you want, or navigate using the links. Feel free to add information about any terms that are absent.

Glossary

Zymonic Toolkit

The Zymonic Toolkit is a collection of useful scripts written in perl to enable you to manage existing systems and create new ones.

Zymonic Objects and Redeclarables

Zymonic objects are unique definitions that provide the building blocks for the Zymonic front end. Redeclarables are similar in as far as they have unique definitions, however they do not have to be a Perl object.

XML Definition/{xmldef}

What

All the information needed in the XML to define a Zymonic object.

Purpose

To include all the information Zymonic needs to create a Zymonic object and allow Zymonic code to easily access these elements.

Usage Accessed in the Perl code using object->{xmldef}->{SomeElement}->{content}. Can also be accessed in the Linux terminal using get_def (see FAQ).

Example

• Perl

my $class_options       =   $self->{xmldef}->{ClassOptions}

• XML

    <ClassOptions>
         <CaptureDate>true</CaptureDate>
         <DateFormat>%d/%m/%Y</DateFormat>
         <CaptureTime>true</CaptureTime>
    </ClassOptions>

Field ref

What

A hash ref of data about a field, stored in the Perl code including information from the XML.

Purpose

Used by methods within Zymonic for referring to a field such as when creating searchmaps.

Usage

Stored as a hash ref in Zymonic::FieldFactory::get_field_ref_details.

Relevant modules

• Base.pm
• FieldFactory.pm
• Field.pm

ZName (pronounced zed-name)

What

Unique identifier for Zymonic objects and for redeclarables.

Purpose

For referring to something specifically, it can be used to redeclare objects and redeclarables, and refer to them within the code.

Usage

Usually set in the XML or created automatically in the Perl, it is stored in a hash as part of the Field Ref. It can then be used by Zymonic through ->{ZName} to locate a specific object, check for an objects existence, or used in the debugger.

Example

<ZName>test_zname</ZName>

Display name

What

Name of a Zymonic object that is displayed to the end user.

Purpose

To allow a user friendly name to be displayed that doesn’t have to be unique, unlike the ZName, which must be unique.

Usage

Set in the XML inside a field element. It is then displayed in the UI for the user, in both the menu and on the block or search field or etc.

Example

<DisplayName>test_display_name</DisplayName>

Manifest

What

A Zymonic Manifest is a Perl module sub-classed from Zymonic::Manifest and used by the Installer Toolkit to install the components required for some aspect of Zymonic functionality.

Purpose

Zymonic is designed such that components can be installed separately e.g. the Decryptor, the Scheduler, the Core, a Project Management system, an Order Fulfillment system etc.

It will contain a list of files of directories and where those should be installed, additionally it can contain actions that will occur on install or update.

Once a manifest has been installed by the Installer then it will be updated at every update (unless specific manifests are being updated separately - see the Installer documentation for how to do this).

Usage

 zymonic_toolkit.pl Installer install --manifests [Manifest Name - the part after Zymonic::Manifest::]

Example

The core for example has the following in its 'get_contents' method:

    my %Manifest = (

        # bin - move contents to modules/[correct module]/bin
        cgi_bin => {
            destination  => 'cgi-bin',
            files        => ["$Working_copy/cgi-bin/"],
            user         => $self->{app_server}->{options}->{apache_user},
            group        => $self->{app_server}->{options}->{apache_group},
            post_install => [ sub { my $app_server = shift; $app_server->restart_webserver(); } ]
        },
        ui_stylesheets => {
            destination  => 'stylesheets',
            files        => ["$Working_copy/stylesheets/"],
            user         => $self->{app_server}->{options}->{apache_user},
            group        => $self->{app_server}->{options}->{apache_group},
            post_install => [ sub { my $app_server = shift; $app_server->combine_stylesheet(); } ]
        },
        images => {
            destination  => 'images',
            files        => ["$Working_copy/images/"],
            user         => $self->{app_server}->{options}->{apache_user},
            group        => $self->{app_server}->{options}->{apache_group},
            post_install => []
        },
        javascript => {
            destination => 'javascript',
            files       => ["$Working_copy/javascript/"],
            user        => $self->{app_server}->{options}->{apache_user},
            group       => $self->{app_server}->{options}->{apache_group},

            post_install => []
        },
        perl_modules => {
            destination  => '',
            files        => ["$Working_copy/modules/Zymonic/"],
            post_install => [
                sub {
                    my $app_server      = shift;
                    my $zymonic_version = "Z" . $self->current_revision('with_type');

                    $app_server->install_perl_module( "Zymonic Core", "$Working_copy/modules/Zymonic/" );
                    $app_server->set_versions($zymonic_version);
                }
            ]
        },
        xml => {
            destination  => '',
            files        => ["$Working_copy/xml/"],
            post_install => [
                sub {
                    my $app_server    = shift;
                    my @changed_files = $self->get_changed_files('xml');
                    $app_server->offer_config_build( "$Working_copy/xml/", @changed_files );

                    # this relies on changes to AppServer, however manifests are updated first
                    # so wrap this in an eval so we don't get errors when this change appears
                    # before the AppServer ones
                    eval {

                        # run build cache command on any systems which contain one of the changed
                        # files, and one of those files has the flag to build caches
                        map { $app_server->run_toolkit_command( 'System', 'build_object_caches', { system => $_ } ); }
                          $app_server->get_systems_by_xml( 'build_cache="true"', \@changed_files );
                        1;
                    } or do
                    {
                        my $exception = $@;
                        $app_server->write_log(
                            "Error checking whether to rebuild caches: " . $self->ll_exception($exception) );
                    };
                }
            ]
        },
    );

Pod

What

Section of comment at the top of methods and modules with a standard format.

Purpose

Describes the properties of the code within the code block, and how it should be used.

Usage

Copied and pasted from other similar code, it should include the method’s name, usage, what it returns, arguments, and any exceptions it throws.

Example

#################### subroutine header begin ####################

=head2 load_search_field

 Usage     : $filter->load_search_field($zname)
 Purpose   : Loads single search_field for the filter.
 Returns   : field ref, or nothing is not loaded
 Argument  : zname of search field
 Throws    : nothing
 Comment   : Will not load SubForm or MultipleChoiceLinkedField type fields

See Also   : 

=cut

#################### subroutine header end ####################

Parents

What

The class in which a Perl object was created. This is Separate from the built in Perl concept.

Purpose

To refer to attributes and methods of the parent.

Usage

Set as a key in the object ref when the object is created so that parent can be referenced from $self->{parent}.

Example

Seen below, adding the parent key when creating a Perl object allows calling of methods from the parent.

Zymonic::SearchMap->new(
                xmldef           => $_,
                config           => $self->{config},
                zname            => $_->{ZName}->{content},
                parent           => $self,
                report_field_ref => $report_field_ref->{ref}
              )

$self->{parent}->get_search_field()

System

What

Database interfaces that use Zymonic to build and run them and are described in the XML.

Purpose

Product sold to customers.

Usage

Can be accessed on the web.

Example

http://test_site/zymonic/test_system

Condition

What

An SQL style rule optionally put in by the XML author, to be used in a where clause of an SQL query.

Purpose

Put into the XML manually inside a searchmap to specify how the database should be searched.

Usage

Placed in a condition element including ZZRF as a placeholder for the database record and ? as a placeholder for the value input to the searchfield. These placeholders are then replaced with the appropriate values later, for security reasons (google prepared statements). If no condition is specified by the XML author, ZZRF == ? is used.

Example

<Condition>ZZRF <= ?</Condition>

Conditional format

What

Conditional formatting in Zymonic allows CSS styles to be applied to a field dependant on the value of a field.

Purpose

Conditional formatting allows the UI to change dynamically depending on what the user is doing. An example might be highlighting fields that are not filled in, or hiding fields that are not needed/shouldn't be used.

Usage

Can be set in the XML using <ConditionalFormat> tags and has a ZName. A condition should be defined within the conditional format definition that specifies the field to be tested and the conditions for the test to pass. A "condition combination" can also be defined to specify how multiple conditions should be applied.

Example

Below, the conditional format hides a field when the test_zname_3 field equals "test_static_value". Below that is an example of including the conditional format in a field definition, so the test_zname_4 field would now hide if test_zname_3 has the value "test_static_value" except that there is also a condition combination, that in this case it specifies that the condition should be applied when the test is not met. In other cases "and" or "or" can be used in condition combinations between multiple conditions.

 <ConditionalFormat>
   <ZName>test_zname</ZName>
   <classes>hidden</classes>
   <Condition>
     <ZName>test_zname_2</ZName>
     <DisplayName>test_display_name</DisplayName>
     <Field>
       <ZName>test_zname_3</ZName>
     </Field>
     <Test>Equals</Test>
     <DesiredValue>
       <StaticValue>test_static_value</StaticValue>
     </DesiredValue>
   </Condition>
 </ConditionalFormat>

<Field>
   <ZName>test_zname_4</ZName>
   <DisplayName>test_display_name_2</DisplayName>
   <ConditionalFormat>
     <ZName>test_zname</ZName>
   </ConditionalFormat>
   <ConditionCombination>!Clause[test_mode]</ConditionCombination>
 </Field>

SubForm

What

A SubForm is a special field class that allows a separate form to be defined within another form (the parent or outer form). The SubForm contains its own fields and a link to a database table.

Purpose

SubForms can be used to have multiple of the same type of record in the same parent form, the user can click the 'add' transition to add. This allows them to enter more data in the next record, and thus populate a table - the parent form record and SubForm records will be 'linked' (foreign key) in the database by having the same 'parent_process_id'.

This might occur in processes where you have some header information and then multiple lines of information - an order for example would contain: date, time, delivery address etc. at the 'parent' form level and then have a SubForm field to contain each line of the order - each line of the order might have a catalogue code, description, price, quantity etc.

Usage

Can be set in the XML using <SubForm> tags and writing the definition inside a field definition that has the SubForm class set.

Example

Below, is an example of setting up a subform that has 2 fields, and referencing the defintion inside a field definition:

  <Form>
    <ZName>test_zname</ZName>
    <DisplayName>test_display_name</DisplayName>
    <Table>
      <ZName>test_zname_2</ZName>
    </Table>
    <Field >
      <ZName>test_zname_3</ZName>
      <DisplayName>test_display_name_2</DisplayName>
      <Base>test_base</Base>
    </Field>
    <Field ">
      <ZName>test_zname_4</ZName>
      <DisplayName>test_display_name_3</DisplayName>
      <Base>test_base_2</Base>
    </Field>
  </Form>

  <Field class="SubForm">
    <ZName>test_zname</ZName>
    <DisplayName>test_display_name</DisplayName>
    <SubForm>
      <Form>
        <ZName>test_zname_2</ZName>
      </Form>
    </SubForm>
  </Field>

SourceFilter

What

A SourceFilter is a filter used for the 'background' task of extracting data from a database table and passing it to a subform. The subform can then be automatically populated with records based on the records passed in by the SourceFilter.

Purpose

This allows a multiple record form to be set up for use in a process based on data already in the system saving time over having to set up many records manually in the GUI.

Usage

The SourceFilter can be set up in the ordinary way for a filter, with a base table and reportfields that are desired to be passed on. This filter is then referenced within a form using the <SourceFilter> tags.

Example

  <Form>
    <ZName>test_zname</ZName>
    <DisplayName>test_display_name</DisplayName>
    <SourceFilter>
      <ZName>test_zname_2</ZName>
    </SourceFilter>
  <Form>

  <Filter>
    <ZName>test_zname</ZName>
    <DisplayName>test_display_name</DisplayName>
    <BaseFilter>
      <BaseTable>
        <ZName>test_table</ZName>
      </BaseTable>
      <ReportField>
        <ZName>test_field</ZName>
        <Field>
          <ZName>test_zname_2</ZName>
        </Field>
      </ReportField>
  </Filter>

Autoadded Fields

In Zymonic systems there are several autoadded hidden fields that are added to every table. They often start with 'zz'.

parent_process_id

The parent_process_id is a hidden field present in every record of every table in a Zymonic database. It contains a value that corresponds to the entry in the zz_process table's processid field.

Purpose

It determines how data in a table should be presented and maintained i.e. which process the user will be shown when they click on the 'edit' link in a filter for the record in question. This is because different processes may write data to the same table - for example in a project management system both a 'programming task' and a 'helpdesk triaging' process might have a mechanism to write to a 'booked time' table that is used for timesheet generation. If someone is reviewing the timesheet filter and wants to understand what reason the time was booked for, they would click on the entry in the filter and be presented with either a 'programming task' or 'helpdesk triaging' entry depending on which sort of process created the entry in the table.

sec_id

The security ID field links a record to the matching record security table.

See Permissions System for further details.

has_field_permissions

True or false whether there are personalised per-field permissions for a record.

deleted

The deleted field is set to true on entries that have been deleted. The entry is then archived instead of actually deleting them.

autocreated

Flag set on auto-created records, set to -1 if Zymonic has autocreated it.

posix_process_id

Contains the posix process id, useful when debugging.

zzlu

Last update time...see zzluts.

zzluts

A more precise last update time stored as a double, showing the time of the last update to the record.

zza

Time the record was created.

zz_source

Identification of the source if one exists for the system. This allows remote instances of the systems to update intermittently from the source. For example a system could be on a ferry, and update from a source when it docks and has internet access.

zz_remote_keyfields

Identification of the remote system if one exists for the system. This allows remote instances of the systems to update intermittently from the source. For example a system could be on a ferry, and update from a source when it docks and has internet access.

Permissions

What

Permissions are used in Zymonic to restrict access to certain actions dependant on the user, and the role of the user. They are set up using relationship permissions, and when set on a table can restrict a groups ability to: read records, change records, delete records, secure records, and add new records.

Purpose

Permissions can be used for example, to restrict access for lower authority employees to certain menus, such as the Admin area (where you can change passwords etc.), or to allow only higher authority employees to delete entries from system.

Usage

Relationship permissions can be added to a table using <RelationshipPermissions> tags and containing any permissions that are desired like so <deleteable>false</deleteable>. Role permissions can be specified inside the relationship permission definition using <RolePermission> tags, role permissions are then turned on or off for a certain user group using the 'roles list' Process in the GUI.

Example

Below: "test_zname" affects users in any user group with the "test_zname_2" role permission set to "yes" in the GUI. They will be allowed to read, change and secure records, but not delete or create records, on any table this relationship permission is set on.

  <RelationshipPermissions>
    <ZName>test_zname</ZName>
    <DisplayName>test_display_name</DisplayName>
    <RolePermission>
      <ZName>test_zname_2</ZName>
      <DisplayName>Change Pay Methods</DisplayName>
      <ShortDescription>This is a short description</ShortDescription>
    </RolePermission>
    <IPList>any</IPList>
    <PermissionHolderType>authenticated</PermissionHolderType>
    <readable>true</readable>
    <changeable>true</changeable>
    <deleteable>false</deleteable>
    <secureable>true</secureable>
    <appendable>false</appendable>
  </RelationshipPermissions>

Linked fields

What

A linked field in Zymonic is a type of field that will display a list of options for the user drawn from a filter (and hence from a table). This field can be placed in any filter or process in the GUI and draw from the same options.

Purpose

This allows the set of options to be dynamic and changed in the GUI/Database, rather than hardcoding classoptions in the XML.

Usage

A linked field can be defined or referenced inside of a field in the desired filter/process using <LinkedField> tags. A sourcefield and displayfield must also be included in the definition. The sourcefield is used to specify which column should be used to specify which row is selected, and is usually the pk of the base table. The displayfield is then which coloumn will be displayed for a given row, and so what value will be used in the field.

Linked fields can also be created automatically by Zymonic by adding

 
<AutoCreateLinkedField source_field_zname "" display_field_zname "">true</AutoCreateLinkedField> 

to a table definition. It can then be referenced using the automatically created ZName, [table]_autolinkedfield.

Example

Below: a linked field definition for the test_zname table. The sourcefield is the pk of the table and the displayfield is the name column. Given the DB further below, the options given in the field would be:

• test1
• test2
• test3

<Field>
  <ZName>test_zname</ZName>
  <LinkedField>
      <Filter>
        <ZName>test_zname_2</ZName>
      </Filter>
      <SourceField>
        <Field>
          <ZName>test_zname_3</ZName>
        </Field>
      </SourceField>
      <DisplayField>
        <Field>
          <ZName>test_zname_4</ZName>
        </Field>
      </DisplayField>
  </LinkedField>
</Field>

+----+---------+--------+---------+
| id | name    | sec_id | deleted |
+----+---------+--------+---------+
|  1 | test1   | 246    | NULL    |
|  2 | test2   | 246    | NULL    |
|  3 | test3   | 246    | NULL    |
+----+---------+--------+---------+

TableInclude

What

TableInclude in Zymonic allows the XML author to join two tables.

Purpose

This allows for table joins to be written in the XML instead of writing custom SQL.

Usage

A tableinclude in Zymonic is done similarly to a join in SQL, and will later be converted into one, when it is used, by Zymonic. Table includes can be defined in the XML using <TableInclude> tags. Inside the definition should be a table to join from and a table to join to, a join type (LEFT,RIGHT,INNER etc.) and a join condition which is similar to a ON in SQL.

Example

Below: the tableinclude definition below would be the same as the SQL statement further below.

<TableInclude>
  <ZName>test_zname</ZName>
  <JoinFrom>
    <Table>
      <ZName>test_zname_2</ZName>
    </Table>
  </JoinFrom>
  <JoinTo>
    <Table>
      <ZName>test_zname_3</ZName>
    </Table>
  </JoinTo>
  <JoinType>LEFT</JoinType>
  <JoinCondition>test_zname_4.[ztsm_size_types_autolinkedfield] = sizes_to_size_types.[test_zname_5]</JoinCondition>
</TableInclude>

SELECT * FROM test_zname LEFT JOIN test_zname_2 ON test_zname_3.id = test_zname_4.id;

$self

What

$self is a hashref used in nearly every Zymonic method to store data about an object, and can call Zymonic methods.

Purpose

$self gives a large degree of flexibility to allow Zymonic to link itself between various modules.

Usage

$self can be used to store definitions - such as data on a filter (what states associate with it, it's zname etc) - it can call Zymonic methods - such as get_def - and stores data about the object currently active in the code - such as it's zname ($self->{ZName}->{content}.

Example

Below: $self calls a method to get the definition of a process to then get it's related transitions by using a method called get_array and get_def - it then stores it in an array which contains each transition's definition. From there, you can use a foreach loop to go through each definition to pick out the data that you need.

my @process_transitions = get_array( ( $self->get_def( 'Process', 'test_zname' ) )->{Transition} )

Config Build

What

The config build is used to prepare the system definition for the program.

Purpose

The config build provides xml definitions for objects, reads through the XML and updates tables.

Usage

It is used after a zymobuild to collate the updated code pulled from the repository in the zymobuild and creates the backbone for the entire system.

Examples

Below: This command is inputted into the linux terminal of the host server to do a config build. This is a basic version; more variants are below. The system is the program you want to run the config build on.

sudo zymonic_toolkit.pl System config_build --system test_system

This next one initiates a full config build - this is usually unnecessary and very time-consuming, but can be useful in diagnosing errors.

sudo zymonic_toolkit.pl System config_build --system test_system --full yes

Finally, this one debugs the config build, so if there is an error in the build you can go through it, line by line, in the perl debugger and usually narrow down the problem to one or two lines.

sudo perl -d `which zymonic_toolkit.pl` System config_build --system test_system