...

public void FormatCell(JiwaFinancials.Jiwa.JiwaApplication.IJiwaBusinessLogic BusinessLogicHost, JiwaFinancials.Jiwa.JiwaApplication.Controls.JiwaGrid GridObject, JiwaFinancials.Jiwa.JiwaApplication.IJiwaForm FormObject, int Col, int Row, JiwaFinancials.Jiwa.JiwaApplication.IJiwaCustomFieldValuesIJiwaLineCustomFieldValues HostObjectHostItem, JiwaFinancials.Jiwa.JiwaApplication.CustomFields.CustomField CustomField, JiwaFinancials.Jiwa.JiwaApplication.CustomFields.CustomFieldValue CustomFieldValue)
{
  // FormatCell handler for a combo custom field
  if (CustomField.PluginCustomField.Name == "MyCustomFieldName") 
  {
		var typeCell = new FarPoint.Win.Spread.CellType.ComboBoxCellType();			
		typeCell.Items = new string[] { "Option 1", "Option 2", "Option 3"};
		typeCell.ItemData = new string[] { "1", "2", "3"};
		typeCell.EditorValue = FarPoint.Win.Spread.CellType.EditorValue.ItemData;                  
		GridObject.ActiveSheet.Cells[Row, GridObject.ActiveSheet.GetColumnFromTag(null, CustomField.PluginCustomField.GridColumnName).Index].CellType = typeCell;
  }
}

...

Identical in nature to the ReadData method of the CustomFieldPlugin class.

ButtonClicked

Identical in nature to the ButtonClicked method of the CustomFieldPlugin class.

SystemSettingPlugin class

ScheduledExecutionPlugin class

This class has only relevance when the Jiwa Plugin Scheduler Service is configured and running.

It contains three methods:

Execute

This is executed for each schedule defined against the plugin, as they fall due. The template code has a lock semaphore in place to prevent pre-empting any already running execution.

...

...

This is used most typically to map an ID from a custom field contents to a display value - such as an InventoryID to a Part No and / or Description, for example:

public void ReadData(JiwaFinancials.Jiwa.JiwaApplication.IJiwaBusinessLogic BusinessLogicHost, JiwaFinancials.Jiwa.JiwaApplication.PluginControls.PluginJiwaGrid PluginGridObject, JiwaFinancials.Jiwa.JiwaApplication.Schedule.Schedule Schedule)
    {
        lock (IJiwaForm FormObject, int Row, JiwaFinancials.Jiwa.JiwaApplication.IJiwaLineCustomFieldValues HostItem, JiwaFinancials.Jiwa.JiwaApplication.CustomFields.CustomField CustomField, JiwaFinancials.Jiwa.JiwaApplication.ManagerCustomFields.CriticalSectionFlagCustomFieldValue CustomFieldValue)
{
  // ReadData handler for a {lookup custom field for an inventory item
  if (CustomField.PluginCustomField.Name   // place processing code in here
        }
    }

OnServiceStart

This method is invoked when the service is starting.

It is often used to add handlers for the Windows File System to detect when a file appears in a folder (File Watcher) - note that no schedule is needed for such handlers.

OnServiceStopping

...

== "MyCustomFieldName") 
  {
		if (CustomFieldValue.Contents.Trim().Length > 0) 
		{
			JiwaFinancials.Jiwa.JiwaApplication.Entities.Inventory.Inventory inventoryItem = CustomField.Manager.EntityFactory.CreateEntity<JiwaFinancials.Jiwa.JiwaApplication.Entities.Inventory.Inventory>();
			try
			{
				inventoryItem.ReadRecord(CustomFieldValue.Contents);
				CustomFieldValue.DisplayContents = String.Format("{0} - {1}", inventoryItem.PartNo, inventoryItem.Description);
			}
			catch(JiwaFinancials.Jiwa.JiwaApplication.Exceptions.RecordNotFoundException notFoundEx)
			{
				CustomFieldValue.DisplayContents = "";
			}
		}
		else
		{
			CustomFieldValue.DisplayContents = "";
		}
  }
}

ButtonClicked

Identical in nature to the ButtonClicked method of the CustomFieldPlugin class, typically used to react to a button click of the lookup button to the right of the custom field contents for Lookup type custom fields - usually to display a search window - for example:

public void ButtonClicked(JiwaFinancials.Jiwa.JiwaApplication.IJiwaBusinessLogic BusinessLogicHost, JiwaFinancials.Jiwa.JiwaApplication.Controls.JiwaGrid GridObject, JiwaFinancials.Jiwa.JiwaApplication.IJiwaForm FormObject, int Col, int Row, JiwaFinancials.Jiwa.JiwaApplication.IJiwaLineCustomFieldValues HostItem, JiwaFinancials.Jiwa.JiwaApplication.CustomFields.CustomField CustomField, JiwaFinancials.Jiwa.JiwaApplication.CustomFields.CustomFieldValue CustomFieldValue)
{
  // ButtonClicked handler for a lookup custom field for an inventory item
  if (CustomField.PluginCustomField.Name == "MyCustomFieldName") 
  {
		JiwaFinancials.Jiwa.JiwaApplication.Entities.Inventory.Inventory inventoryItem = CustomField.Manager.EntityFactory.CreateEntity<JiwaFinancials.Jiwa.JiwaApplication.Entities.Inventory.Inventory>();
		inventoryItem.Search(FormObject.Form, "", "");
		CustomFieldValue.Contents = inventoryItem.RecID;
		CustomFieldValue.DisplayContents = String.Format("{0} - {1}", inventoryItem.PartNo, inventoryItem.Description);
  }
}

SystemSettingPlugin class

Similar to the custom field classes, this class has methods used for the display and interaction with system settings.

ScheduledExecutionPlugin class

This class has only relevance when the Jiwa Plugin Scheduler Service is configured and running.

It contains three methods:

Execute

This is executed for each schedule defined against the plugin, as they fall due. The template code has a lock semaphore in place to prevent pre-empting any already running execution.

public void Execute(JiwaFinancials.Jiwa.JiwaApplication.Plugin.Plugin Plugin, JiwaFinancials.Jiwa.JiwaApplication.Schedule.Schedule Schedule)
    {
        lock (JiwaFinancials.Jiwa.JiwaApplication.Manager.CriticalSectionFlag)
        {
            // place processing code in here
        }
    }

OnServiceStart

This method is invoked when the service is starting.

It is often used to add handlers for the Windows File System to detect when a file appears in a folder (File Watcher) - note that no schedule is needed for such handlers.

OnServiceStopping

This method is invoked when the service is stopping.

Understanding Business Logic Behaviours

When writing plugins to interact with business logic objects, particularly handling events raised by these objects, it is important to understand the behaviours and sequence of events.

The Save

When the Save() method of a business logic object is invoked, the following occurs in order:

1. If no SQL Transaction is already started, one is started

2. The SaveStart event is raised. It is safe to perform long running actions and UI interactions

3. SQL commands are issued to INSERT, UPDATE and DELETE

4. The SaveEnding event is raised. It is unsafe to perform long running actions and UI interactions

5. The SQL transaction, if started by this business logic object is committed

6. The SaveEnd event is raised. It is safe to perform long running actions and UI interactions

If any exception is thrown during the save (even by a plugin) then if the business logic object had started a transaction, then it will RollBack that transaction and all SQL commands issued since the transaction started will be undone.

Plugins that wish to use the same SQL transaction to update data to ensure consistency should do this in either the SaveStart or SaveEnding events. If using the SaveEnding event then ensure no user interaction is made.

The Read

When the Read(string RecID) of a business logic object is invoked, the following occurs in order:

1. The ReadStart event is raised

2. The Clear() method is invoked to clear contents of properties, private members and collections - this will in turn raise the ClearStart and then ClearEnd events.

3. The data is read

4. The ReadEnd event is raised

JiwaCollections

All collections or lists in Jiwa are of type JiwaCollection. Each item in the collection inherit from the JiwaCollectionItem class.

Sales order lines, purchase order lines, debtor delivery addresses, Bill input items are all JiwaCollections.

There are several events of JiwaCollections which can be subscribed to, via the public property of the business logic object.

Note that the JiwaCollection events are not raised during the normal read of a business logic object.

Adding

The Adding event is raised when an item is being added to the collection. A CancelEventArgs argument allows this add to be cancelled.

Added

The Added event is raised when an item is added to the JiwaCollection. The item argument is the item which was added.

The code below shows a handler for a sales order lines, displaying a message box of the PartNo property of the sales order line when added to the collection.

public class FormPlugin : System.MarshalByRefObject, JiwaFinancials.Jiwa.JiwaApplication.IJiwaFormPlugin
{
	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)
    {
    }
	
    public void Setup(JiwaFinancials.Jiwa.JiwaApplication.IJiwaForm JiwaForm, JiwaFinancials.Jiwa.JiwaApplication.Plugin.Plugin Plugin)
    {
		JiwaFinancials.Jiwa.JiwaSalesUI.SalesOrder.SalesOrderEntryForm salesOrderForm = (JiwaFinancials.Jiwa.JiwaSalesUI.SalesOrder.SalesOrderEntryForm)JiwaForm;
		salesOrderForm.SalesOrder.SalesOrderLines.Added += delegate(JiwaFinancials.Jiwa.JiwaSales.SalesOrder.SalesOrderLine salesOrderLine)
			{
				System.Windows.Forms.MessageBox.Show(String.Format("Added '{0}'", salesOrderLine.PartNo));
			};
    }
}

Changed

The Changed even is raised when a property if the item changes. The PropertyChangedEventArgs argument has a PropertyName property which contains the name of the property which changed.

Removing

The Removing event is raised when an item is being removed from the JiwaCollection.

Removed

The Removed event is raised when an item is removed from the JiwaCollection.

Common Mistakes

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

...

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 eventto 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.

DRY (Don’t Repeat Yourself)

If there is code that is going to be needed by multiple plugins don’t repeat the code in multiple places, instead create a plugin and create a public class within this plugin to hold the code and then add a plugin reference to each of the plugins that need to access this code and call this new class. By doing this you don’t have to maintain multiple copies of the same code.