Skip Ribbon Commands
Skip to main content
ContactsLaw provides an API for third-party plug-ins, to allow third-party developers to extend and augment the software for the purposes of:
  • Providing additional import/export formats
  • Providing support for additional document, template and report formats
  • Integration with proprietary telephone systems
  • Integration with third-party software

API documentation

The latest version of the ContactsLaw API documentation can be downloaded from the following address:
http://download.overtech.com.au/public/contactslaw/plugin-api/plugin-api.zip

Development

Third-party developers can author plug-ins for ContactsLaw by downloading the latest version of the ContactsLaw Primary Interop Assembly (ContactsLaw.Integration.dll) and referencing the assembly in their own class libraries. Plug-ins must be written for the Common Language Runtime 2.0 or 4.0 (preferred), but may contain or reference unmanaged code.
You can access a range of existing functionality using the CLApplication singleton class. Functionality is added or extended by implementing one of the integration interfaces (or extending one of the included base classes) in the prescribed manner.
 
All plug-ins must provide an implementation of the IPluginDescriptor interface (or extend BasePluginDescriptor) - ContactsLaw will attempt to locate an implementation of this interface when it loads the plug-in, and will use this to get the name and description of the plug-in.
 
​Important: ContactsLaw loads all plug-in code into a separate application domain (AppDomain), therefore any classes that are instantiated by ContactsLaw or which cross the domain boundary must derive from MarshalByRefObject.
 
The CLApplication class provides access to:
  • Activities - for launching activities and opening records.
  • Charts - for creating, rendering and printing charts.
  • Documents - for generating documents from templates.
  • Search - for interacting with the ContactsLaw search and loading existing records based on their primary key value.
  • Tasks - for creating tasks and appointments programmatically.
  • UserPrompts - for displaying prompts to the user in a GUI-agnostic manner.
The following are examples of interfaces that can be implemented:
  • IAccountBalanceProvider - for providing opening balances on accounts from other systems.
  • IContactImporter (BaseContactImporter) - for adding a file format or import source for contacts.
  • IContactExporter - for adding a file format for exporting contacts.
  • IDocumentProvider (IDocumentPreviewer, IDocumentActions, IFaxDocument, IPageCounter, IConvertToPDF) - for adding support for a new document format.
  • IEmailMessage (BaseEmailMessage) - for adding support for e-mail registration from third-party software.
  • IEmailMessageProvider - for direct integration with third-party software to 'send' e-mails to ContactsLaw.
  • IMainMenuItem - for adding entry-points to third-party features on the ContactsLaw ribbon.
  • IPaymentExporter - for exporting electronic payment details to internet banking portals and transaction processing systems.
  • IPhoneController - for adding support for additional types of telephone systems.
  • IPrintedReport - for adding additional printable reports.
  • IReportGenerator - for adding support for report generation in additional formats.
  • ISharePointOperations - for adding support for different versions/variants of Microsoft SharePoint.
  • ITaskExporter - for exporting ContactsLaw tasks to third-party applications.
  • ITemplateEditor - for exposing in-place editor functionality for templates.
  • ITemplateProvider - for adding support for a new document template format.
Other important interfaces include:
  • IContact - models a contact and all related data. You do not implement this interface; rather, objects of this type will be passed to your code by ContactsLaw.
  • IFile - models a file and all related data. Again, you do not implement this interface yourself.

Deployment

Plug-ins are loaded into ContactsLaw on application startup if they are placed in the program's plug-in directory (user-configurable). Third-party plug-ins can utilise ContactsLaw's plug-in manager to simplify the process of installing, uninstalling and updating plug-ins.
 
To use this mechanism, third-party developers must publish their plug-ins on the web. The web deployment will consist of a package containing the plug-in files (typically a ZIP archive) and an XML manifest file which is read by ContactsLaw. Refer to the documentation for more information about how to deploy plug-ins using this system.

Handling configuration in plug-ins

There are two supported approaches to handling configuration of plug-ins. For per-user configuration, you can implement the IPluginConfiguration interface; this allows your plug-in to display its own configuration UI and save the configuration to a local file - you can use any representation, however the standard .NET settings mechanism is preferred. Users configure the plug-in via the application settings screen.
 
For practice or company-wide configuration, implement the ISettingsProvider (BaseSettingsProvider) interface. This allows you to declare additional global application settings which will be stored in ContactsLaw's database (and therefore applied to all members). Callback methods to get, set, commit and revert settings are passed to your class when ContactsLaw starts. The simplest approach to implementing the interface is to return instances of GlobalSetting, the primary implementation of IGlobalSetting.

Using plug-ins to create new activities in ContactsLaw

You can define new types of activities in ContactsLaw; you implement several interfaces that comprise the definition, then provide your own GUI for the activity itself.
If your activity operates upon its own types of records, you must implement the storage of these records and implement both the IRecordType and IRecordIdentifier interfaces to enable ContactsLaw to interact with them.
 
You define the activity itself by implementing the IActivityType interface; this determines the semantics of your activity, the type of record it operates upon and how ContactsLaw should treat it. Given an active instance of the activity, it must be able to start the GUI for the activity.
 
Your activity type implementation will be assigned an object of type IActivityInstance. This object describes the record being operated upon, the workflow action (e.g. request, authorise, process) to perform, directives passed to the activity and a reference to any task that may exist for the item. It allows you to determine which directives will be passed back to ContactsLaw and lets you finish or cancel the activity.

Exception handling

You must take care to properly handle exceptions in plug-in code. Many operations defined in plug-in interfaces return a boolean value to indicate success or failure; you may display your own error messages before returning 'false' from such an operation.
 
Built-in exception handling will apply to operations in plug-in code which are called by ContactsLaw. You can take advantage of ContactsLaw's error handling mechanisms by throwing exceptions of the type UserFriendlyException. These exceptions wrap an underlying exception, but provide a user-friendly caption and descriptive message. When debugging, the full exception detail is available.

Extensibility

In addition to the application services and integration interfaces included in the ContactsLaw API, plug-ins can also communicate with each other to build on existing functionality. This is done by requesting an extensibility object using CLApplication.Extensibility - supplying the globally unique identifier (GUID) that corresponds to the desired service object. Plug-ins can expose their own extensibility objects by implementing the IExtensibilityProvider interface. Methods and properties on extensibility objects are intended to be invoked using the dynamic programming features available in C# 4.0 and above.

Additionally, ContactsLaw provides some extensibility services of its own:

  • {C786CB76-670D-4197-AF0E-04D154FD2CDC} - Exposes functionality to apply the ContactsLaw GUI theme to plug-in forms.
  • {FD300E85-9D52-4C86-BCD2-B39D82DF4497} - Exposes factory methods for creating various types of ContactsLaw records directly.
  • {4889D6B1-094B-4D04-89AB-BCC3A74F3CEB} - Allows plug-ins to build on ContactsLaw's existing PDF and vCard support.