How to keep a stable KwaMoja/webERP installation updated

There has been a lot of discussion recently on the webERP forums about how to keep a stable version of your implementation, so I thought it might be a good moment to write an article on how to do this.

Firstly Web ERP Africa Ltd keeps a stable branch of the webERP code. This takes the last release (4.10.1 at the moment I write this) and then just adds in any bug fixes that have been applied to the main line. Obviously this does not include any bug fix to any new functionality, as that functionality does not exist in the stable branch. We also apply our regression tests to these fixes, to ensure that they are not re-introducing any previous bugs. This branch should then get progressively more stable, but anybody  who wants the latest features can use the main trunk. I have made this stable branch publicly available from my github repository and can be found here. You can download a zip file containing this code from here. This zip file is automatically updated when a new bug fix is applied.

Exactly the same is true for KwaMoja, it's stable branch can be found by using the master branch here.

So if you are using a KwaMoja/webERP that has no customisations in it then all you have to do, is to keep an eye on this repository, and download new versions as and when it is updated.

However there are potential problems when you have customised scripts in your installation. I will assume that if the user has the knowledge to change the files then they will have a small knowledge of IT, and you will need the application Git installed.
 
What we wish is to avoid the code being over written when updating from the stable branch. I have created a small git repository here to represent the stable branch, and have uploaded the following script to it, calling it HelloWorld.php:

<?php
include('includes/session.inc');
$Title = _('Hello World');
include('includes/header.inc');
echo '<p class="page_title_text noPrint" ><img src="'.$RootPath.'/css/'.$Theme.'/images/user.png" width="24px" title="' . _('Hello World') . '" alt="" />' . _('Hello World') . '</p>';
if (isset($_POST['Submit'])) {
    /* Get clients IP address */
    $IPAddress = $_SERVER['REMOTE_ADDR'];
    /* Has user been here before? */
    $SQL = "SELECT count(name) as names
                FROM helloworld
                WHERE name='" . $_POST['Name'] . "'
                    AND ipaddress='" . $IPAddress . "'";
    $Result = DB_query($SQL, $db);
    $MyRow = DB_fetch_array($Result);
    if ($MyRow['names'] > 0) {
        prnMsg( _('Welcome back') . ' ' . $_POST['Name'], 'info');
    } else {
        $SQL = "INSERT INTO helloworld (ipaddress,
                                        name)
                                    VALUES (
                                        '" . $IPAddress . "',
                                        '" . $_POST['Name'] . "'
                                    )";
        $Result = DB_query($SQL, $db);
        prnMsg( _('Hi') . ' ' . $_POST['Name'], 'info');
    }
} else {
    echo '<div class="page_help_text noPrint">' . _('Enter your name in the box below.') . '</div>';
    echo '<form enctype="multipart/form-data" action="' . htmlspecialchars($_SERVER['PHP_SELF'],ENT_QUOTES,'UTF-8') . '" method="post" class="noPrint">';
    echo '<input type="hidden" name="FormID" value="' . $_SESSION['FormID'] . '" />';
    echo '<div class="centre">
            <input type="text" name="Name" />
        </div>
        <div class="centre">
            <input type="submit" name="Submit" value="Submit" />
        </div>';
    echo '</form>';
}
include('includes/footer.inc');
?>

Now you can pull this code to your own machine by issuing the command:

git clone git@github.com:timschofield/Example1.git

Now we make a local change to our code. We will change the word 'Hi' to 'Hello'. Now if we wish to update our code to the latest from the repository we would issue the command:

git pull git@github.com:timschofield/Example1.git

and this will update any changes - if there were any new bug fixes applied for instance. However you will notice that Git is smart enough not to try and overwrite your code that you changed locally.

So by using Git we can update our code to the latest stable branch, whilst keeping our local changes in place.

#KwaMoja IRC channel is launched!

Please see the following announcement from Fahad about the launch of the new IRC channel.:

https://sourceforge.net/p/kwamoja/blog/2013/05/kwamoja-irc-channel-is-launched/

ABC inventory ranking system is completed

As detailed in this blog post we have been working on a system for ranking inventory items by the standard ABC classification system.

I am happy to announce that this new system has just been uploaded to the KwaMoja repositories and those who wish to try it can download our development snapshot from here.

The only change from the original blog post was a suggestion from Francis that we use a consumption value system as our default ranking method rather than the proposed sales value method - thanks Francis.

The next step in warehouse management system is to setup the warehouse storage definitions as outlined in the excellent document prepared by Buz and Mary Beth (sorry I don't know more details of these people) that can be downloaded from here. Then we are into the cycle count code.

This code was offered to Phil Daintree at webERP but appears to have been rejected.

New Work Order Entry script

I have never liked the old method of entering work orders in webERP and now I am no longer allowed to help people on the mailing lists and forums I have more time to devote to correcting it.

The old script didn't follow the normal webERP conventions, for instance it allocated a work order number, as soon as user clicked on that menu option, even if they didn't go on to enter an order, and this meant tracking order numbers was impossible. Sales and purchase orders both use a class to hold the order details in but Work orders didn't. The code was messy, and didn't abide by the coding guidelines.

In fact I am surprised it was ever allowed to corrupt the code base. I have just uploaded a revised script, which has more functionality, but in a lot less code. "Do more with less" is a good motto for these types of things.

Unfortunately I am not allowed to push this new functionality to the webERP svn repository, so you need to get it from here https://github.com/timschofield/KwaMoja/archive/develop.zip if you wish to test it. Hopefully someone who is still allowed to commit to svn will push it to webERP.

Any issues or bugs please let me know.

Phil Daintree and his "hate pages"

This page is written in response to the lies that +Phil Daintree has written about me, and spread on the internet. Despite years of searching he has been unable to find anything I have written that is untrue, and he has had to resort to vague generalities, faked emails, and badly fabricated screenshots (you can see the joins if you zoom in using any bit mapped image editor). +Phil Daintree is welcome to make any comments to these pages, as he has done in the past. If I agree with what he says I will amend my writings, if I do not agree I have allowed his comments to stand next to mine so that people can make their own judgements. I have every confidence in the intelligence of readers to make a sensible judgement based on the facts. +Phil Daintree will not allow me the right of reply to any of the lies he has told about me. It seems to me significant that he realises that if people see both sides of the argument they will see through his lies.


Writing "Hate Pages" about fellow developers and then denying them the right to reply has always been Phil Daintree's weapon of choice when trying to bully developers out of the project. Back on 11 September 2007 when Phil was trying to bully most of the early webERP developers out of the project, he wrote to me telling me he had written one of his hate pages about them and was going to publish it on weberp.org. 

At the time I dissuaded him from this action. He again brought the subject on the following day, and again I had to dissuade him. Unfortunately when he came to writing his "hate page" about me there was nobody left to dissuade him.

These are used to force developers to leave quietly, as Phil maintains personal control over the mailing lists, the forums, the wiki and the web site, meaning that it is not possible to dispute any of the lies he writes within the project. What really annoys him about me is that I refuse to be intimidated off the project.

I received many warnings about this behaviour when I was first getting deeply involved in the project. Unfortunately I really didn't believe them. Obviously I should have, and have since apologised to those whose warnings I ignored.

Only by taking the stand I have can I hope to save current and future developers being treated in this way.

ABC analysis of stock items.

One of the most important methods of keeping accurate stock levels - though by no means the most widely used, especially in Africa - is cyclical stock checking. That is the constant checking of the stock throughout a financial period, rather than leaving stock checks to the period end.

This has two big advantages in the control of an organisations stock. Firstly the stock levels are kept in a much more accurate state as they are checked more frequently, and secondly any variances are far easier to track down if the period between checking the item is much shorter.

A necessary prerequisite of cyclical stock checking is an ABC analysis of the organisations stock. By ABC analysis I mean to rank the items by:

A - The most important items to the organisation

B - Important to the organisation but not critical

C - Slow moving or non important stock items.

At the moment we have no ABC analysis. This is a proposal to rectify that.

ABC classification is a way of grouping your stock items. There are a few different ways to set up an ABC Ranking, such as Velocity (times sold), Quantity sold/Consumed or by Margin. But the most common method is the Annual Sales Volume ranking. This method will allow you to identify the small number of items that usually account for most of your sales value (think 80/20 rule).

My plan is to first implement Annual Sales Volume Ranking method, but to do it in such a way as to make adding other methods easy in the future. To do this I propose to setup a table to hold the methods to be used. This table will have the following structure:

CREATE TABLE `abcmethods` (
     `methodid` TINYINT NOT NULL DEFAULT 0,
     `methodname` VARCHAR(40) NOT NULL DEFAULT '',
     PRIMARY KEY (`methodid`)
);

Initially this will have just one record in, 
methodid=>0 
methodname=>Annual Sales Volume Ranking

The next table will contain the groups that are being used. This will specify the criteria used. Each method can have several groups. I propose the following table:

CREATE TABLE `abcgroups`(
     `groupid` INT(11) NOT NULL DEFAULT 0,
     `groupname` VARCHAR(40) NOT NULL DEFAULT '',
     `methodid` TINYINT NOT NULL DEFAULT 0,
     `apercentage` TINYINT NOT NULL DEFAULT 0,
     `bpercentage` TINYINT NOT NULL DEFAULT 0,
     `cpercentage` TINYINT NOT NULL DEFAULT 0,
     `zerousage` CHAR(1) NOT NULL DEFAULT 'D',
     `months` TINYINT NOT NULL DEFAULT 12,
     PRIMARY KEY (`groupid`),
     CONSTRAINT `abcgroups_ibfk_1` FOREIGN KEY (`methodid`) REFERENCES `abcmethods` (`methodid`) 
);

The zerousage field is intended to hold the category into which items that have no usage at all should be put. This would normally be C or D. The months field is the number of prior months movements that should be analysed.
Finally I propose a separate table to hold the ABC category for each item and group. This would look like:

CREATE TABLE `abcstock` (
     `groupid` INT(11) NOT NULL DEFAULT 0,
     `stockid` VARCHAR(20) NOT NULL DEFAULT '',
     `abccategory` CHAR(1) NOT NULL DEFAULT 'C',
     PRIMARY KEY (`groupid`, `stockid`), 
     CONSTRAINT `abcstock_ibfk_1` FOREIGN KEY (`groupid`) REFERENCES `abcgroups` (`groupid`),
     CONSTRAINT `abcstock_ibfk_2` FOREIGN KEY (`stockid`) REFERENCES `stockmaster` (`stockid`) 
);   

Using these three tables should provide for a very flexible system, easily changed in the future.

The function to actually assign the categories would work something like this:

1.  Calculate the 12 month value usage for all of the stock items.

2.  Rank the items in descending order by value.

3.  The "A" items are the top 80%.

4.  The "B" items make up the next 15%.

5.  The "C" items are the remaining items that have any usage in the period being looked at.

6.  Label zero-usage items as "D".

Comments and constructive (yes Phil I am looking at you!) criticisms would be very much appreciated.

The anatomy of a KwaMoja plugin

As promised in my previous post regarding KwaMoja plugins, here is a tutorial on constructing a plugin.

Each plugin is a zip file. For this tutorial we will use the demo plugin that is available from http://www.kwamoja.com/demo_plugin.zip.

This demo takes the form of a standard "Hello World" type application, as used in most programming tutorials. The plugin will present the user with a text box asking for the users name. If that user has not used the plugin before from that IP address they will get a message saying "Hello John" or "Hello Jane" or whatever his or her name is. If they are returning, they will get a welcome back message.

If you unzip this file you will see it contains 5 files:

HelloWorld.php
HelloWorldDB.php
HelloWorldDBRemoval.php
HelloWorldLinks.txt
summary.xml

ALL KwaMoja plugins must have a summary.xml file. This is the file that tells KwaMoja how to install the plugin. Here is the xml contained in this examples summary.xml:

<plugin>
    <name>Demo Plugin</name>
    <installed>0</installed>
    <license>gpl</license>
    <scripts>
        <script>
            <name>HelloWorld.php</name>
            <pagesecurity>1</pagesecurity>
        </script>
    </scripts>
    <menulinks>HelloWorldLinks.txt</menulinks>
    <dbupdates>HelloWorldDB.php</dbupdates>
    <dbremoval>HelloWorldDBRemoval.php</dbremoval>
</plugin>

The first attribute is a descriptive name for the plugin. I have just called this one "Demo Plugin" .

The next attribute shows whether the plugin has been installed. KwaMoja will automatically set this to 1 when the plugin is installed. This should be set to zero when writing the plugin, and then never manually changed.

Then there follows the name of the license that this plugin is covered by. In this case, the GPL.

Next is an array of scripts that will be installed and a security token for each script. HelloWorld.php is a KwaMoja script. The plugin can contain any number of these scripts. In this simple example we only need the one, and I have given it a security token of one meaning any user can use it. I will go through this script and how to write a KwaMoja script in my next post.

The next attribute is called "menulinks" and contains the name of the file containing details of what new menu items are required to be added, and if any new modules are to be added to the menus. The full contents of this file for our example are:

$ModuleLink[] = 'Test';
$ReportList['Test'] = 'test';
$ModuleList[] = 'Test';

$MenuItems['Test']['Transactions']['Caption'][] = 'Hello World';
$MenuItems['Test']['Transactions']['URL'][] = '/HelloWorld.php';

The first three items on the list will setup a new module called "Test" to appear on the main menu. This is not obligatory. For instance if your plugin fits best in the Manufacturing module, then there is no need to have these lines. The next two lines are necessary for every script that you want the user to have access too via the main menu. These take the form of $MenuItems[Module][Section][Caption] and $MenuItems[Module][Section][URL] where "Module" is the name of the module, either one that you have just created or from the following list:

'orders', 
'AR', 
'AP', 
'PO', 
'stock', 
'manuf',  
'GL', 
'FA', 
'PC', 
'system', 
'Utilities'

The section is either "Transactions", "Reports", or "Maintenance" and determines whether the item appears in the left, centre, or right section of the menu. The Caption is the string that will appear in the menu, and the URL is the path to that menu, which must include a "/" at the beginning, as in "/HelloWorld.php".

Penultimately there is an attribute called dbupdates. This provides a link to a file containing the following:

<?php
CreateTable('helloworld',
"CREATE TABLE helloworld (
ipaddress char(13),
name varchar(30),
PRIMARY KEY  (`ipaddress`, `name`)
)", $db);

$SQL = "UPDATE www_users SET modulesallowed=modulesallowed+'1, WHERE userid='" . $_SESSION['UserID'] . "'";
executeSQL($SQL, $db);
?>

These are commands used to make any necessary changes to the database for your plugin to work. If it doesn't need any changes there should still be a file that just contains the <?php ?> tags in it. KwaMoja comes with an api to allow you to access the database, and facilitates the use of different DBMS's. You can find the functions here. The first call is to the CreateTable() function. Secondly there is some sql to update the users modulesallowed field and finally there is a call to the executeSQL() function to run this SQL.


The final attribute in the summary.xml file is called dbremoval. This is a reference to the file that contains the commands required to remove the database changes when the user uninstalls the plugin. Our demo file contains the following:

<?php
DropTable('helloworld', 'name', $db);

$SQL = "SELECT modulesallowed FROM www_users WHERE userid='" . $_SESSION['UserID'] . "'";
$Result = DB_query($SQL, $db);
$MyRow = DB_fetch_array($Result);

$SQL = "UPDATE www_users SET modulesallowed='" . substr($MyRow['modulesallowed'], 0, strlen($MyRow['modulesallowed'])-2) . "' WHERE userid='" . $_SESSION['UserID'] . "'";
executeSQL($SQL, $db);
?>
As you can see above, both the dbupdates and the dbremoval files can contain php code to verify information before updating the database.




So that is a simple KwaMoja plugin. This zip file can be imported into KwaMoja, and you can see and use this plugin directly from the menu.
The next post will cover actually writing the script.