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

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.


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.

The Id property must return a GUID, unique to your plug-in. Remember to create new GUIDs if you copy any of the sample code.

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 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;



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.

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 change the the following code:
    using System;
    using System.ComponentModel.Composition;
    using System.IO;
    using ReadSoft.Connect.Plugin;
    namespace MyTargetSystemPlugin
    public class MyPlugin : IPlugin
    private string _logFilePath;
    public Guid Id
    // Unique ID for your plugin, create a new one if copying this sample.
    get { return Guid.Parse("EB67638B-308F-4627-A927-0D9743DC99AC"); }
    public void Initialize(IApplication app)
    _logFilePath = Path.Combine(app.GetProgramFolder(),"myplugin_log.txt");
    app.FileDownloadComplete += AppOnFileDownloadComplete;
    private void AppOnFileDownloadComplete(object sender, FileDownloadCompleteEventArgs args)
    LogDebug("Hello world! I just downloaded this guy: " + args.XmlFilePath);
    private void LogDebug(string message)
    message = string.Format("{0} – {1}\n", DateTime.Now, message);
    File.WriteAllText(_logFilePath, message);
  4. Compile and publish the plug-in as described in the Publishing section below.
  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.

Scenario: 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 downloadedXml = File.ReadAllText(args.XmlFilePath, Encoding.UTF8);
    var xmlDoc = XDocument.Parse(File.ReadAllText());
    var invoiceNumber = string.Format("{0}", xmlDoc.XPathSelectElement("/Batches/Batch/Documents/Document/HeaderFields/HeaderField[Type='invoicenumber']/Text").Value);
    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.
    var newFileName = Path.Combine(Path.GetDirectory(args.XmlFilePath), string.Format("{0}_{1}", supplierName, invoiceNumber)) + ".xml";
    File.Copy(args.XmlFilePath, newFileName)

Scenario: 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.

Scenario: 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.


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 Windows Forms App project, open project properties, go to the Signing tab, click Sign the ClickOnce manifest and then click Create Test Certificate. After you copy the resulting PFX file to your plugin project folder, you can delete the Windows form app project.

    You can use SignTool.exe from the Microsoft Windows Kit to perform the actual signing. 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 "MyKeyPassword" /d "Test Description" "$(TargetPath)\MyTargetSystemPlugin.dll"

    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 used as name of the plug-in.
  4. Upload the ZIP file to the Resources view in ReadSoft OnlineAdmin Center on the partner level.

    If your plug-in is not signed, you will get an error message

  5. In ReadSoft Online Admin Center, navigate to the customer you would like to activate the plug-in for and choose XML locally as the target system.
  6. Specify your newly uploaded plug-in in the Online Connect plug-in setting and save your changes.
  7. In ReadSoft Online Connect run the configuration wizard. When prompted to allow usage of the new plug-in accept the usage and finalize 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 Admin 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.


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.