Plugins authors should adhere to the following guidelines when developing plugins.

Name

The plugin name should be concise and convey some meaning as to what the purpose of the plugin is.

If you find it difficult to name because the plugin functions are so varied then you should consider splitting the plugin into several plugins.

Ideally, plugins should perform their own discrete functions specific to a purpose.

Meaningful Description

Place a meaningful description in the plugin description.

The description should explain the following:

Purpose of the plugin

A brief summary of what the plugin does. Even if there is an external link to a documentation page, the plugin description should still offer a summary of purpose.

System Settings

If the plugin defines any System Settings, the plugin description should at the very least alert the reader to this fact. The System Setting descriptions can explain each setting, but the plugin description should mention that there are System Settings so the reader can know to examine and set them.

Custom Fields

If the plugin defines any Custom Fields, the plugin description should at the very least alert the reader to this fact. The Custom Field descriptions can explain each setting, but the plugin description should mention that there are Custom Fields so the reader can know to examine and set them.

Deployment Instructions

If there are deployment steps beyond just importing the plugin, then these should be listed in numbered order.

Author

The Author should identify the organisation or individual who authored the plugin.

Versioning

The plugin version should use a dotted version number, with the last number incrementing with each published change.

For example, if a plugin is first published as version 1.0.0, then this should be incremented to 1.0.1 when next published.

Exception Policy

The Exception Policy should be set to Abort if it performs critical business processes, otherwise the default Exception Policy of Report should be used.

A plugin with an Abort Exception Policy will not allow processes (such as the REST API or Plugin Scheduler) to logon if the plugin is unable to be loaded.

Execution Order

Plugins are compiled and loaded in the order of Execution Order, then plugin Name.

If you add a Plugin Reference (a reference to another plugin) then the Execution Order is automatically set to the Execution Order of the referenced plugin, incremented by one.

Forms

The Forms tab of the plugin is a register of forms that, when loaded will result in the SetupBeforeHandlers and Setup methods of the FormPlugin class being invoked.

You should only add forms to this list which your plugin has an interest in.

Business Logic

The Business Logic tab of the plugin is a register of business logic objects that, when loaded will result in the Setup method of the BusinessLogicPlugin class being invoked.

You should only add business logic to this list which your plugin has an interest in.

Assembly References

The Assembly References tab contains all the external assemblies the plugin is referencing.

Unused references should be deleted.

When a plugin is created, to be helpful and reduce the friction in getting a plugin working out of the box, we add all the references from the JiwaApplication.dll assembly. A lot of these references will not be needed and can be deleted.

References are also automatically added when a Form or Business Logic is added to their respective tabs - the assembly of the Form or Business Logic itself, as well as all references that the added Form or Assembly was referencing. A lot of these references will not be needed and can be deleted.

Removing unused Assembly References will improve performance.

Plugin References

The Plugin Reference tab allows the logic in another plugin to be accessible to the plugin the Plugin Reference is added to.

The referenced plugin should be enabled and in a compilable state.

When a plugin is added to the Plugin References tab, the Execution Order of the plugin is set to the execution order of the referenced plugin, and incremented by one to ensure that the plugins are compiled in an order able to satisfy the dependency requirements.

Embedded References

Third part assemblies can be attached to plugins on the Embedded References tab. When a plugin is compiled, the Embedded References are saved to the folder %ProgramData%\Jiwa Financials\Jiwa 7\{Jiwa Version}\{WindowsUser}\{SQL Server Name}\{Jiwa Database Name}\Plugins\{Jiwa username}\Compile and then loaded.

Custom Fields

Custom fields are defined on the Custom Fields tab.

Use meaningful names and descriptions.

Avoid abbreviating.

Use casing to help readability.

System Settings

System Settings are defined on the System Settings tab.

Use meaningful names and descriptions.

Avoid abbreviating.

Use casing to help readability.

Schedule

Schedules can be defined on the Schedule tab - these are only used by the ScheduledExecutionPlugin class, when the Jiwa Plugin Scheduler service is configured and running.

Use a meaningful name. If the schedule is daily at midnight, then “Daily Midnight” would be a reasonable name.

Double-right mouse click the Description to open the Schedule details dialog.

Schedules are not Enabled by default when added, so be sure to Enable the schedule.

Code

The code of a plugin by default is populated with several template classes.

Delete any classes automatically created that you are not using
Delete any using (or Imports in VB) statements you are not using

It is important to understand that some plugin classes are created and instantiated at logon time, and the same instance is used to invoke the methods within the class.

These classes are those implementing these interfaces:

IJiwaFormPlugin
IJiwaBusinessLogicPlugin
IJiwaApplicationManagerPlugin
IJiwaCustomFieldPlugin
IJiwaLineCustomFieldPlugin
IJiwaSystemSettingPlugin
IJiwaScheduledExecutionPlugin

So, as an example, consider the following code:

public class FormPlugin : System.MarshalByRefObject, JiwaFinancials.Jiwa.JiwaApplication.IJiwaFormPlugin
{
	public int Counter = 0;
	
    public override object InitializeLifetimeService()
    {
        // returning null here will prevent the lease manager
        // from deleting the Object.
        return null;
    }

    public void SetupBeforeHandlers(JiwaFinancials.Jiwa.JiwaApplication.IJiwaForm JiwaForm, JiwaFinancials.Jiwa.JiwaApplication.Plugin.Plugin Plugin)
    {
		Counter++;
    }

    public void Setup(JiwaFinancials.Jiwa.JiwaApplication.IJiwaForm JiwaForm, JiwaFinancials.Jiwa.JiwaApplication.Plugin.Plugin Plugin)
    {
		System.Windows.Forms.MessageBox.Show(Counter.ToString());
    }
}

And with the following Forms registered:

Each time the sales order form or quote form is loaded, a messagebox displays an incrementing number - illustrating that the variable Counter and hence the class is not created when the form is, but the same class instance is invoked when forms are loaded.

FormPlugin class

The FormPlugin class implements the IJiwaFormPlugin interface - it contains two methods of interest - SetupBeforeHandlers and Setup.

SetupBeforeHandlers

When a form is created via the FormFactory (as all forms in Jiwa are), if the form is registered on the Forms tab of the plugin, then the SetupBeforeHandlers method of the FormPlugin class is invoked after the form is created, but before the form has added any event handlers for the control or business logic.

The SetupBeforeHandlers method can be used to add handlers to control events and business logic before the form itself handles these events.

This is often useful in overriding the built-in behaviour - for example, adding a button click handler here will cause your code to respond to the event before the form does, and you can also short-circuit the event so the form doesn’t receive the event at all afterwards by throwing a JiwaApplication.Exceptions.ClientCancelledException which will silently fail, resulting in your plugin handling the event and the form not handling it with its built-in handler.

The JiwaForm parameter passed to the SetupBeforeHandlers method is the form being loaded - if you have registered multiple forms on the Forms tab on the plugin then the type of the JiwaForm parameter should be inspected to determine the code to execute.

public void SetupBeforeHandlers(JiwaFinancials.Jiwa.JiwaApplication.IJiwaForm JiwaForm, JiwaFinancials.Jiwa.JiwaApplication.Plugin.Plugin Plugin)
{
  if (JiwaForm is JiwaFinancials.Jiwa.JiwaPurchaseOrdersUI.MainForm)
  {
		// the Purchase Order form
  }
  else
  {
		// some other form
  }		
}

Setup

The Setup method, like the SetupBeforeHandlers method, is only invoked if the form is registered on the Forms tab of the plugin, but the Setup method is invoked after the form has added its event handlers for controls and business logic.

Typically this is where custom controls are defined and added to the form, and where handlers to business logic or form control events are added.

BusinessLogicPlugin class

The BusinessLogicPlugin class implements the IJiwaBusinessLogicPlugin interface, and has only one method of interest - Setup.

When a business logic object is created via the BusinessLogicFactory (as all business logic objects in Jiwa are), if the business logic is registered on the Business Logic tab of the plugin, then the Setup method of the BusinessLogicPlugin class is invoked after the business logic object is created.

Typically this is where you would add handlers to business logic events, and instantiate and setup your own objects.

The JiwaBusinessLogic parameter passed to the Setup method is the business logic that has been created - if you have registered multiple business logic objects on the Business Logic tab on the plugin then the type of the JiwaBusinessLogic parameter should be inspected to determine the code to execute.

Care must be taken if interacting with the User Interface within handlers of business logic objects added from the Setup method of the BusinessLogicPlugin class.

You must not assume there is a user to respond to or dismiss message boxes or dialogs - events may be raised from services such as the REST API which are using the business logic.

User interaction should be performed in the FormPlugin class, which is guaranteed a user interface - add the handlers to business logic events there, not in the BusinessLogicPlugin class.

Common Mistakes

Some of the more common mistakes which can cause significant issues are:

Blocking a SQL Transaction with a UI prompt

An entire organisation can be ground to a halt by displaying a messagebox or dialog at the wrong time.

If a plugin is awaiting user interaction and there are un-committed transactions pending, then other users will be blocked from reading or writing to the same tables or pages of the database.

The SaveEnding event of all business logic objects is raised when the business logic has created a SQL Transaction, issued SQL inserts, updates or deletes and not yet committed the transaction.

Awaiting user interaction, or any long running operation - such as I/O or external API’s should not be done in handlers of the SaveEnding event.

Plugin Development Guidelines

Name

Meaningful Description

Purpose of the plugin

System Settings

Custom Fields

Deployment Instructions

Author

Versioning

Exception Policy

Execution Order

Forms

Business Logic

Assembly References

Plugin References

Embedded References

Custom Fields

System Settings

Schedule

Code

FormPlugin class

SetupBeforeHandlers

Setup

BusinessLogicPlugin class

Common Mistakes

Blocking a SQL Transaction with a UI prompt