Integrating ONLYOFFICE Document Editors With the Groupware Platform Written on С#

ONLYOFFICE is an open-source office suite that comprises editors for text documents, spreadsheets, and presentations. The suite allows extending the functionality of third-party web apps with document editing components, thus being used within their interface. In the previous articles, we showed you how such integration is done (see the examples for Node.js, or Python).

In this article, we will show you one of the most actual integration cases, namely the integration of ONLYOFFICE document editors with its own collaboration platform.

ONLYOFFICE Collaboration Platform

ONLYOFFICE collaboration platform (Community Server) is a free, open-source collaborative system written on C# and distributed under GNU GPL v3.0. It includes document and project management, CRM, email aggregator, calendar, user database, blogs, forums, polls, wiki, and instant messenger.

The ONLYOFFICE collaboration platform is a part of complete self-hosted solutions that allow you to deploy a full-featured private web-office on your own server. It is distributed as a free Community Edition, or Enterprise Edition, with more system administration options and enhanced security tools for bigger teams.

Integration Checklist

This is the list of the most important permissions needed for a smooth integration of ONLYOFFICE document editors with the collaboration platform:

1. Adding custom code

2. Anonymous access for downloading and saving files. It means that our editors only communicate with the collaboration platform on the server side without involving any user authorization data from the client side (browser cookies)

3. Adding interface buttons

4. Integration with modules of the collaboration platform (DMS, CRM, Projects, Mail)

5. Opening a new page where we can execute the script to add an editor

6. Ability to specify Document Server connection settings

Let’s see how we implemented the integration according to this checklist:

1. Adding Code

Since ONLYOFFICE editors are the central element of all ONLYOFFICE solutions, embedding editing functionality in our collaboration system was initially an integral part of the development.

Additionally, ONLYOFFICE allows adding custom modules (e.g. your own CRM system) to Community Server, as well as creating API for the added modules. Sample projects are available on GitHub.

2. Anonymous Access

We implemented a callback handler that handles requests from ONLYOFFICE Document Server to the collaboration platform, namely to the DMS. This direct interaction between them doesn’t require any user authentication data like browser cookies. Instead, it is based on JWT technology that uses request signature validation.

Document Server adds JWT to the request using the so-called ‘secret’ from its configuration file. The DMS in its turn checks if the JWT secret coincides with the secret from its own config. The callback handler will only perform the requested action if the signature was validated successfully.

That’s how a request with JWT validation is processed:

public class FileHandler : IHttpAsyncHandler
{
    public override void OnProcessRequest(HttpContext context)
    {
        using (var receiveStream = context.Request.InputStream)
        using (var readStream = new StreamReader(receiveStream))
        {
            //request body
            var body = readStream.ReadToEnd();

            //request data
            var data = JToken.Parse(body);
            var callbackData = data.ToObject<CallbackData>();

            //request token
            var jwtString = JsonWebToken.Decode(callbackData.Token, Config.JwtSecret);
            var jwtData = JObject.Parse(jwtString);
            if (jwtData == null)
            {
                throw new ArgumentException("Document Service request token is incorrect");
            }

            //request data from JWT
            callbackData = jwtData.ToObject<CallbackData>();
            result = ProcessData(callbackData);
            context.Response.Write(result ?? "{\"error\":0}");
        }
    }
    ...
}

The response should be:

{”error”:0}

Depending on the status of the request, a certain action is performed:

public string ProcessData(CallbackData callbackData)
{
    switch (callbackData.Status)
    {
        case NotFound:
        case Closed:
            FileTracker.Remove(callbackData.key);
            break;

        case Editing:
            ProcessEdit(callbackData);
            break;

        case MustSave:
        case Corrupted:
            return ProcessSave(callbackData);
    }
    return null;
}

3. Adding Buttons

Two most important actions are surely opening for viewing and editing (buttons “Preview” and “Edit” correspondingly). Other action buttons we implemented in the interface allow users to:

• move
• copy
• download, including the ability to select the desired format
• rename
• delete
• see the document’s version history
• set access rights to the file, including sharing settings, the ability to generate a link for portal users, to block/unblock the doc, and to send it by email. The last-mentioned option is implemented through the integration with the Mail module (see below). 

4. Integration With Modules

Along with the buttons, there are additional actions that require interaction between Document Server and other services or modules. For instance, we convert files at various stages of document management via the conversion service, e.g. when users upload, open, or download the document. It is important to note, however, that DOCX, XLSX and PPTX files are processed directly since Office Open XML is our core format, while all other file formats are converted to OOXML. It's done to speed up the file processing and increase the interoperability.

Work with documents is performed not only within the document management system (what we described in detail in the previous article), but also within CRM, Projects, and Mail.

In the CRM module, users are able to:

• attach documents to CRM opportunities and cases,
• create new docs, sheets, and presentations right in CRM (also applies to opportunities and cases),
• open and edit attached documents, or download them.

Users can import contacts to their CRM in bulk from a CSV file as well as export the customer database as a CSV file:

In the Projects module, we implemented a separate folder with documents, spreadsheets, and presentations (Project Documents).

It is possible to attach documents to project tasks and discussions, including the ability to create new files directly in the Project module. Managing attached documents, users are able to edit, download, or delete them.

In the Mail module, we implemented the integration this way that along with attaching docs, spreadsheets, and presentations from the local drive to messages, users are able to attach files stored in the Documents module. If the file size exceeds the allowed limit, users are suggested to send the attachment as a link to the needed document.

In this case, the link to the file is inserted into the message body. Before sending the message, users are asked to set up access rights for all the files attached as links. When a recipient then follows the link from the message, the document is opened in the online viewer or editor depending on the specified access rights.

When ONLYOFFICE users receive a message with an attached document, they are able to :

• download the attachment
• view the file in the browser
• open the doc, spreadsheet, or presentation for editing (in this case it will be automatically converted to .docx/.xlsx/.pptx if the format differs from OOXML and saved to the Documents)
• save the file to the Documents module selecting the needed folder

Mail settings allow users to select any folder in the Documents module where all the attachments from email messages will be automatically saved:

Additionally, in the CRM and Projects module, we generate reports via Document Builder, ONLYOFFICE document generation tool that allows you to build a document without the need to actually run the document processing editor. It also allows the developers to automate document building using templates, or inserting the data from their database into the document.

5. Opening the Page With Editors

When a new page with the editors is opened, the initialization config is generated. Among the main parameters sent for the editor are those defining the type of the file, the interface language (editorConfig.lang = "en-US"), and the list of permissions for each user, i.e. we check if the user has the appropriate access rights to open and edit the doc, and apply other actions (leave comments, download, rename the file, etc.):

var config = {
   "document":{
      "fileType":"docx",
      "info":{
         "author":"Me",
         "created":"3\/29\/2019 10:06 PM",
         "folder":"My Documents",
         "sharingSettings":[
            {
               "permissions":"Full Access",
               "user":"Me"
            }
         ]
      },
      "key":"kouNPg1",
      "permissions":{
         "changeHistory":true,
         "comment":true,
         "download":true,
         "edit":true,
         "fillForms":true,
         "print":true,
         "rename":true,
         "review":true
      },
      "title":"ONLYOFFICE Sample Document.docx",
      "url":"https:\/\/demo.onlyoffice.com\/demo.docx"
   },
   "documentType":"text",
   "editorConfig":{
      "callbackUrl":"https:\/\/demo.onlyoffice.com\/filehandler.ashx",
      "lang":"en-US",
      "mode":"edit",
      "user":{
         "id":"9acf7169b737",
         "name":"John Smith"
      }
   },
   "type":"desktop"
}

6. Connection Settings

Depending on the solution, users are able or not to specify Document Server connection settings.

In ONLYOFFICE Cloud Service that we host ourselves, connection settings are hidden from users and set by us in the configuration on the server.

Users of ONLYOFFICE server solutions are able to specify the address of the server with ONLYOFFICE editors installed. Such settings are available for portal administrators and can be found in the Integration section of the Settings page:

Generally, ONLYOFFICE Document and Community Server are installed on the same machine. In this case, your network configuration might not allow the requests between them using public addresses. Therefore, two other fields (as seen on the screenshot above) are needed to specify the ONLYOFFICE Document Server address for internal requests from the Community Server and vice versa.

When an administrator saves the settings, the interaction between the portal and the editors is checked to ensure the correct connection.

Read more about how the integration of ONLYOFFICE document editors with other services works in the API documentation.

If you would like to try ONLYOFFICE document editors in combo with the collaboration platform and check its integration, you can start a free trial deploying ONLYOFFICE on your private server.