Plug-in API for Online Connect

The Plug-in API exposes a number of different events that a plug-in can subscribe to in order to enhance the process in various ways.

The ReadSoft Online Connect Plug-in API (later referred to as the Plug-in API) allows partners to write plug-ins that execute in ReadSoft Online Connect, on premise at the site of the customer. The Plug-in API exposes a number of different events that a plug-in can subscribe to in order to enhance the process in various ways.

Plug-ins can be used in a number of scenarios, from simple tasks such as renaming files, to full integrations to new target systems.

Plug-in essentials

Plug-ins are created using theReadSoft Online Connect Plug-in SDK. A plug-in is a .NET 4.0 class library assembly (DLL) with references to the Plug-in API.

When a plug-in has been built, the main DLL must be signed using a code certificate. All files needed by the plug-in should then be compressed into a single ZIP file and uploaded to ReadSoft Online as a resource, using the ReadSoft Online Control Center.

Once uploaded, the plug-in can be selected as part of the target system configuration for a specific customer. When the customer runs through the configuration wizard of ReadSoft Online (on premise) they will be informed about the usage of the plug-in and have to accept this in order to continue.

Relationship to the ReadSoft Online API

The Plug-in API is a simplification of the ReadSoft Online API. In many cases, developing a plug-in is sufficient in order to meet integration needs. When using plug-ins, the infrastructure around it, such as the installation of ReadSoft Online Connect, Windows Service, automatic updates, authentication, scheduling etc, are handled for you.

If the Plug-in API does not meet your needs, you can create a more advanced integration using the ReadSoft Online API.

Tip The Plug-in API uses parts of the ReadSoft Online API, and knowledge about both APIs can be necessary.

Plug-in API

The Plug-in API consists of a few interfaces and classes that are contained in ReadSoft.Connect.Plug-in.dll, which is part of the plug-in SDK.

IPlugin

In order for a plug-in to be valid, the plug-in DLL must contain a class that implements the IPlugin interface and also exports that same type as demonstrated in the example scenarios below.

When a plug-in is loaded, the Initialize method is invoked and the plug-in can set things up as well as subscribe to different events. Each event comes with a specialized event handler.

Note Plug-ins are executed in ReadSoft Online Connect, which runs in the background as a Windows Service. Therefore, you cannot display any UI elements (such as message boxes) that might block the ReadSoft Online Connect process. Instead, messages must be written to log files or the Windows Event Log.

Plug-ins are executed in ReadSoft Online Connect, which runs in the background as a Windows Service. Therefore, you cannot display any UI elements (such as message boxes) that might block the ReadSoft Online Connect process. Instead, messages must be written to log files or the Windows Event Log.

public interface IPlugin

  {

    void Initialize(IApplication app);

    Guid Id { get; }

  }

IApplication

IApplication is the main application interface that plug-ins use to subscribe to events and get various information.

The GetProgramFolder method returns the path to the folder where the ReadSoft Online Connect configuration is located (default location: C:\ProgramData\ReadSoft Software Services AB\ReadSoftOnlineConnect).

 public interface IApplication

  {

    string GetProgramFolder();

    event EventHandler<DocumentDownloadStartEventArgs> DocumentDownloadStart;

    event EventHandler<ImageDownloadCompleteEventArgs> ImageDownloadComplete;

    event EventHandler<FileDownloadCompleteEventArgs> FileDownloadComplete;

    event EventHandler<DocumentDownloadCompleteEventArgs> DocumentDownloadComplete;

    event EventHandler<MasterDataRequestEventArgs> MasterDataRequest;

  }

Events

Plug-ins subscribe to events in order to execute code when an event occurs, such as when a file has been downloaded.

Some of the events require references to other DLLs besides ReadSoft.Connect.Plug-in.dll. The other DLLs can be found in the ReadSoft Online SDK.

Some event arguments provide a connection to the ReadSoft Online API (ServiceConnection property). This connection can be used to communicate further with the ReadSoft Online API in case more information is needed. Knowledge of the ReadSoft Online API and SDK is required for such tasks. The same events also provide information allowing the plug-in to know if the connection was made using customer or partner credentials (IsCustomerLevelConnection property).

Event flow chart


Event flow chart

DocumentDownloadStart event

This event occurs when a document has been processed in ReadSoft Online and is about to be downloaded by ReadSoft Online Connect. The event arguments contain brief information about the document (DocumentReference) as well as connection information. It also has a property (SkipXmlDownload) that allows the plug-in to control if the XML file for the document should be downloaded or not. This can be useful in situations where only the image is needed, or the document data is fetched by the plug-in code instead.

public class DocumentDownloadStartEventArgs : EventArgs

  {

    public bool SkipXmlDownload { get; set; }

    public DocumentReference DocumentReference { get; set; }

    public ClientConfiguration ServiceConnection { get; set; }

    public bool IsCustomerLevelConnection { get; set; }

  }

ImageDownloadComplete event

This event occurs when a document image has been downloaded and saved to a local file (in the folder selected in the Online Connect wizard configuration). It can, for example, be used to do image manipulation.

public class ImageDownloadCompleteEventArgs : EventArgs

  {

    public string ImageFilePath { get; set; }

  }

FileDownloadComplete event

This event occurs when the document XML and image have been downloaded and saved to local files. It can be used to manipulate the XML content and/or image, or to rename/move files.

Note This event is not triggered if SkipXmlDownload is set during the DocumentDownloadStart event.

public class FileDownloadCompleteEventArgs : EventArgs

  {

    public string XmlFilePath { get; set; }

    public string ImageFilePath { get; set; }

  }

DocumentDownloadComplete event

This event occurs when the document processing (downloading of files) is complete, from ReadSoft Online Connect’s point of view. You can use this event. for example, to integrate data with external systems. The argument class contains a Result property that can be used to give more details to ReadSoft Online about the document process result. For example, if the integration fails for any reason, the error message can be set in the Result, and the status can be set to Failed. Doing so would send the document back to ReadSoft Online, where an operator can review the message and take appropriate actions. In the Plug-in SDK, there is a sample that shows a full integration solution.

public class DocumentDownloadCompleteEventArgs : EventArgs

  {

    public string XmlFilePath { get; set; }

    public string ImageFilePath { get; set; }

    public DocumentReference DocumentReference { get; set; }

    public ClientConfiguration ServiceConnection { get; set; }

    public OutputResult Result { get; set; }

    public bool IsCustomerLevelConnection { get; set; }

  }

MasterDataRequest event

Most events are triggered by each document. However, this event is triggered even when ReadSoft Online Connect determines that it is time to provide master data from your external system to ReadSoft Online. By default, the event is triggered every 12 hours, and when the user presses Synchronize in ReadSoft Online Connect.

Use the connection data provided in the event arguments to connect to the ReadSoft Online API and upload the master data needed by your integration. ReadSoft Online API knowledge is required. See the Plug-in SDK sample for more details on how this can be used.

public class MasterDataRequestEventArgs : EventArgs

  {

    public ClientConfiguration ServiceConnection { get; set; }

    public bool IsCustomerLevelConnection { get; set; }

  }

Scenario: Hello World

This scenario demonstrates how to create a plug-in and subscribe to an event. It also shows how to create a custom debug log file for your plug-in.

  1. In Visual Studio (or similar), create a new project for a .NET 4.0 class library named MyTargetSystemPlug-in.
  2. Add a reference to ReadSoft.Connect.Plug-in.dll (part of the plug-in SDK).
  3. Rename Class1.cs file to MyPlugin.cs and add the following code:
    // Unique ID for your plugin, create a new one if copying this sample.
    }
  4. Compile and publish the plug-in as described in the Publishing section.
  5. Process a document in ReadSoft Online using a customer where the plug-in is activated.
  6. After the document is processed by ReadSoft Online Connect, the plug-in log file “C:\ProgramData\ReadSoft Software Services AB\ReadSoftOnlineConnect\myplug-in_log.txt” contains the greeting message from the code.

Rename files

In this scenario, we want to rename the XML and image files downloaded using the invoice number and supplier name from the document.

  1. Set up your project according to the Hello World scenario.
  2. In the event handler for FileDownloadComplete, get the invoice number and supplier name from the downloaded XML. If you use Online XML v2.0, you can achieve this using these XPath values:
    var supplierName = string.Format("{0}", xmlDoc.XPathSelectElement("/Batches/Batch/Documents/Document/Parties/Party[Type='supplier']/Name").Value);
  3. Rename the XML file and image file using the paths available in FileDownloadCompleteEventArgs.
    ...

Image manipulation

In this scenario, we want to manipulate the downloaded image. Assume you want to split a multi-TIF file into several files (one per page). Or maybe you want to convert the image to a format that is not supported by ReadSoft Online.

  1. Set up your project according to the Hello World scenario.
  2. In the event handler, ImageDownloadComplete, the “args” argument contains the path to the downloaded document image (PDF or multi-TIF, depending on the configuration you have done in ReadSoft Online). Process the image file as needed.

Full target system integration

In the Plug-in SDK, there is a sample that describes how a full integration to a new target system can be implemented. This sample uses several events to get data and image from the document, as well as uploading master data.

Publishing

The following steps are needed to publish and activate your plug-in to be used for a specific customer, or for testing.

  1. Compile your plug-in project.
  2. Using a code signing certificate, sign the plug-in DLL.

    If you do not have such a certificate, you can create a test certificate in Visual Studio: Create a new console app project, open project properties, go to the Signing tab, click Sign the ClickOnce manifest and then click Create Test Certificate (you can delete the console app project after this).

    You can use SignTool.exe from the Microsoft Windows Kit to perform the actual signing. Besides doing this manually, you can also set up a post-build event in Visual Studio for your plug-in project. Here is an example of how such a command line could look. You must include the quotation marks in the command.:

    "C:\Program Files (x86)\Windows Kits\8.1\bin\x64\signtool.exe" sign /f "$(ProjectDir)MyKey.pfx" /p "test" /d "Test Description" "$(TargetPath)"

    To validate that the plug-in DLL is signed, right click the DLL and choose properties. If the dialog that appears contains a Digital Signatures tab with a signature in the list, the DLL is signed correctly.

  3. Compress all plug-in files (DLLs) into a zip file. The name of the zip file is important, it will be used as name of the plug-in. Upload the zip file on the Resources page in ReadSoft Online Control Center, on partner level. (If your plug-in is not signed, you will get an error message)
  4. In ReadSoft Online Control Center, navigate to the customer you would like to activate the plug-in for. Go to Services and Target system. Select XML locally as target system (if it is not listed, you might need to activate this on partner level first). Press Configuration and select your newly uploaded plug-in on the plug-in dropdown list. Save the customer service configuration.
  5. In ReadSoft Online Connect (on premise, customer site), run through the configuration wizard. You will be prompted to allow usage of the new plug-in. (The customer will see the name of plug-in and the certificate information). Accept the usage and finish up the configuration wizard.

Plug-in configuration

Currently, there is no way for plug-ins to display a configuration UI in ReadSoft Online Connect or the ReadSoft Online Control Center. One way of providing configurable settings for your plug-in, is to serialize/de-serialize your configuration object to an XML file located in the same folder that ReadSoft Online Connect stores its configuration. In your plug-in code, you can retrieve this folder path from the app object via the Initialize method. See the Plug-in SDK sample for an example that demonstrates how to do this.

Debugging

You can debug your plug-in by attaching Visual Studio to the ReadSoft Online Connect Windows service process:

  • In debug mode, build your plug-in.
  • Publish the plug-in and run the ReadSoft Online Connect configuration wizard locally on your computer to make sure the latest version of the plug-in is downloaded by ReadSoft Online Connect.
  • In Visual Studio, select Debug/Attach to Process and attach to the ReadSoft.Connect.Host.exe process.
  • Make sure you have breakpoints set up in your code, and then process a document in ReadSoft Online.