FAQ

This is a list of questions frequently asked when starting with Zymonic. If your question isn’t answered here though, don’t be afraid to ask someone (and why not add it to the FAQ?).

FAQ

Getting started

Check out a copy of the source code from https://svn.zednax.com/public-svn/zymonic

Then follow the readme : https://svn.zednax.com/public-svn/zymonic/trunk/modules/Zymonic/README

How does the user interface work for Zymonic systems?

Using the menus

Zymonic systems feature simple menus that can be opened from the ‘Virtual Desktops’ icon, top left of the screen. This will give a menu allowing you to open any process or filter relevant to that task.

Admin Area

If you are on an admin account, there is also an ‘Admin Area’ menu that gives you access to all the processes and filters in the current system. You can also search the menus by name in the search bar.

Using a filter

Filters are opened from the menu. They will open in their own block and contain search fields, sorted into tabs, to enter data to search on. You can mouse-over the menu icon to give you the option to show results, which will search the database and display the results in report fields underneath. The reset button at the top right of the filter can be used to reset all the search fields.

Using a process

Processes are opened by mousing-over the menu icon on a filter and clicking on the ‘new’ icon. This will open the process connected to that filter in its own block. It will contain fields, sorted into tabs, which can be used to enter data to be sent to the database table. Clicking a transition button at the bottom of the process will change the state and send the data to the table.

How do I commit changes to Zymonic?

Make the changes to the .pm file

Make your changes to the Perl code of a .pm file in Eclipse, asking other developers opinions on your ideas as necessary. Save what you have done.

Zymotidy (UNIX line endings)

All Zymonic XML and Perl code needs tidying before it can be committed; we're currently using HTML Tidy for Linux released on 25 March 2009 and perltidy v20160302.

Perl tidy may need to be installed as a specific version this can be done by doing 'sudo cpan SHANCOCK/Perl-Tidy-20160302.tar.gz'.

Before your code can be committed it must be tidied, using zymotidy. This is a program that will ensure all the code has a ‘correct’ style, it will also sometimes find syntax errors, but it won’t correct them. With correct versions of ‘Perltidy’ installed, go to your Zymonic eclipse folder from the command line and do “perl scripts\zymotidy.pl”.

Commit

Right click on your code and select ‘team’ then ‘commit’. Enter a summary of the changes you have made including reference to the SR it relates to e.g. “SR: 6903 - added a loop to print ‘I love Zymonic’. ”. Press ok and this will add this change to everybody’s code, once they ‘update to head’.

Zymobuild

To add these changes to a system start a Linux terminal and type “sudo zymobuild” and follow the instructions given by zymobuild.

Local changes

In cases where you don’t think a commit is necessary changes can be made locally to .pm files simply by doing “sudo vi /usr/local/lib64/perl5/5.24.3/Zymonic/[filename].pm”. Just reload and the changes will be in affect when you load the system, doing a zymobuild will revert the changes. Changes can also be made in a similar ways to XML files by doing "sudo vi /etc/zymonic/[system]/[file]", and doing a config build, but these changes won't necessarily revert when you zymobuild.

How do I create an admin user for a Zymonic system?

Linux terminal then…

Type “sudo zymonic_toolkit.pl System create_admin --system [system] --username [username]”.

Where is a Zymonic system stored?

In…

/etc/zymonic/[system name]

How do I find the XML definition for something in the UI?

Find the ZName

First thing you need to find is the ZName, as this is the only bit of information that is unique to every Zymonic Object. A good way of finding this is by inspecting the UI element in your browser and this should show the ZName as "zname=’[zname]’.

Alternatively if the 'zname' of the element is not obvious then the 'id' can help you to guess the correct zname; ids are usually of the form:

[Block ID]_[Process or Filter ZName]_[Report / Form (optional)]_[record identifier (numeric with underscores)][ Field Zname ][display element type suffix]

e.g.

99_test_filter_zname_49_55485354_494957field_zname_display_only_value

[Block ID]=99

[Process or Filter ZName]=test_filter

[Report / Form ZName (optional)]=zname

[record identifier (numeric with underscores)]=49_55485354_494957

[ Field Zname ]=field_zname

[display element type suffix]=display_only_value

Use get_def

Once you have the Zname, you can find the XML definition Linux terminal using get_def “zymonic_toolkit.pl Definition get_def --definition [system name] --zname [zname]”. This will show not only the definition of the object, but it also recursively shows the definitions of what the object is based on.

Search Eclipse

You can also find the XML definition in Eclipse if you want to edit the code. Use the ZName, in Eclipse’s search function to locate it in the XML (you can use *.xml as the file name pattern to speed it up).

What is the Zymonic Toolkit?

Within Zymonic exists a set of useful scripts called the Zymonic Toolkit.

How do I use Toolkit commands?

The is run using the zymonic_toolkit.pl script and includes many options picked using command line arguments. The module must be specified along with the command within that module and any arguments that command takes e.g. zymonic_toolkit.pl Definition get_def --definition export_test --zname pay_methods (where Definition is the module, get_def is the command within that module and --definition and --zname are both arguments used by that command).

Where is the code found?

Script for running toolkit (zymonic_toolkit.pl) is found in modules\Zymonic\bin, and the modules can be found in Zymonic::Toolkit e.g. Zymonic::Toolkit::Definition.

What happens to saved and deleted entries in Zymonic?

What happens when I save an entry with a process?

When you press save, an entry with data matching what you entered is created in the database table that is linked with that process. When data matching this is searched on the filter the same DB is accessed, and hence it will return matching entries that have been added.

What happens when I delete and entry with a process

When you delete an entry in Zymonic it will be marked in the DB as deleted by setting the value for the deleted column to 'Y'. This will mean that it is skipped when searched for.

How can I create an entry that I searched for that doesn't yet exist?

If you search with a filter for an entry and don't find one, you can click 'new' in the filter and it will open the process with the fields already automatically filled with what you entered into the search fields in the filter.

Why am I getting a primary key error with config build?

Occasionally primary key SQL query errors can occur similar to:
<sql_err>Incorrect table definition; there can be only one auto column and it must be defined as a key</sql_err>

Why does this happen?

This can occur when there are multiple definitions of the same table, for example if they are in different modules, and you link multiple modules into one system. When config build runs, it first caches all of the tables already in the database. Then it goes through the XML updating the tables in the cache by comparing the xml and the tables for differences. However because the DB is not rechecked between reading different xml files, when there are multiple definitions, the second xmldef will be checked against the DB after it has been changed. This can cause issues if it tries to change a primary key.

What is the fix?

More long term the solution will be a change to the way config build works so that it either by re-reading the DB between each table or by modifying the in-memory definition of the DB’s table. Before this however tables with different definitions should have different SQLNames.

How to install wkhtmltopdf

Generating PDF reports requires wkhtmltopdf - but specifically the 'static' version which can run without an X11 server. The easiest way to do this is to download the appropriate binary from https://wkhtmltopdf.org/downloads.html and install it (and any dependencies).