Skip to content

Commit

Permalink
Clean up project
Browse files Browse the repository at this point in the history
  • Loading branch information
cetra3 committed Oct 20, 2015
1 parent fc1c0cb commit 87f503f
Show file tree
Hide file tree
Showing 3 changed files with 73 additions and 116 deletions.
156 changes: 57 additions & 99 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,114 +1,72 @@
# Alfresco Onlyoffice integration

This Share plugin enables users to edit HTML documents within Onlyoffice lite from Alfresco Share. This will create a new **Edit in Onlyoffice** action within the document library for HTML documents. This allows multiple users to collaborate in real time and to save back those changes to Alfresco.
This Share plugin enables users to edit Office documents within Onlyoffice from Alfresco Share. This will create a new **Edit in Onlyoffice** action within the document library for Office documents. This allows multiple users to collaborate in real time and to save back those changes to Alfresco.

Tested with Enterprise 4.2.\*, 5.0.\* and Community 4.2.\*, 5.0.\*

![image](onlyoffice-alfresco.gif)
Tested with Enterprise 5.0.\*

## Compiling

You will need:

* Java 7 SDK or above

* Maven or Gradle

### Maven

* Run `mvn package` from the `share` directory

### Gradle
* Gradle

* You will need Parashift's alfresco amp plugin from here: https://bitbucket.org/parashift/alfresco-amp-plugin
* Parashift's alfresco amp plugin from here: https://bitbucket.org/parashift/alfresco-amp-plugin

* Run `gradle amp` from the `share` directory
* Run `gradle amp` from the `share` and `repo` directories

## Installation

* Deploy the amp using Alfresco MMT or copy the onlyoffice jar to the WEB-INF/lib/ directory of share

* Update your `share-config-custom.xml` to include two new endpoints, `onlyoffice` and `onlyoffice-api`. `onlyoffice` is for end users and `onlyoffice-api` is only for Share to update content from Alfresco and setup pads.

* Update your `share-config-custom.xml` to disable CSRF actions for the onlyoffice endpoint, see **CSRF Instructions** below

* Restart Alfresco Share

### Example share-config-custom.xml

This example uses the following:

* 127.0.0.1 as the host
* 9001 as the port
* an API Key of `CHANGEME`.

To find the API key, check for the file `APIKEY.txt` on your onlyoffice instance.

#### Example Endpoints

```
<config evaluator="string-compare" condition="Remote">
<remote>
<endpoint>
<id>onlyoffice</id>
<name>Onlyoffice - unauthenticated access</name>
<description>Onlyoffice access</description>
<connector-id>http</connector-id>
<endpoint-url>http://127.0.0.1:9001</endpoint-url>
<identity>none</identity>
</endpoint>
<endpoint>
<id>onlyoffice-api</id>
<name>Onlyoffice - API access</name>
<description>Onlyoffice access</description>
<connector-id>onlyoffice</connector-id>
<endpoint-url>http://127.0.0.1:9001/api/1/</endpoint-url>
<identity>declared</identity>
<username>apikey</username>
<password>CHANGEME</password>
<unsecure>true</unsecure>
</endpoint>
</remote>
</config>
```

## CSRF Instructions

Because CSRF is enabled for all POST requests, we need to override the default CSRF policy to switch it off for POST requests to the onlyoffice proxy.

As discussed in this [blog](http://blogs.alfresco.com/wp/ewinlof/2013/03/11/introducing-the-new-csrf-filter-in-alfresco-share/), there are two options. Both involve overriding configuration in your `share-config-custom.xml` file.

You can switch off the CSRF Policy completely by using this statement (not recommended in production):

```
<config evaluator="string-compare" condition="CSRFPolicy" replace="true">
<filter/>
</config>
```


Or you can copy the CSRFPolicy configuration from [this file](https://svn.alfresco.com/repos/alfresco-open-mirror/alfresco/COMMUNITYTAGS/V5.0.d/root/projects/slingshot/config/alfresco/share-security-config.xml) and then add the example in the onlyoffice-alfresco readme. So you would end up with a config section like this in your share-config-custom.xml:

```
<config evaluator="string-compare" condition="CSRFPolicy" replace="true">
<filter>
<rule>
<request>
<method>POST</method>
<path>/proxy/onlyoffice/.*</path>
</request>
</rule>
<-- OTHER RULE STATEMENTS FROM share-security-config.xml -->
</filter>
</config>
```

What this accomplishes is that you have the default CSRFPolicy, so you are secure, but you enable POST requests to pass through unfiltered to onlyoffice. You must include the onlyoffice filter rule first, as `share-security-config.xml` is loaded before `share-config-custom.xml`


## Todo

* Increase security of Onlyoffice. Right now you will still need the Node's UUID to discover the pad, but we can do better.
* Handle error cases alot better (wrong API Key, etc..)
* Provide some documentation on setting up onlyoffice correctly
* Support text documents
### OnlyOffice

You will need an instance of onlyoffice that is resolvable and
connectable both from alfresco and any end clients. Onlyoffice must
also be able to POST to alfresco directly.

The easiest way to start an instance of onlyoffice is to use Docker: https://github.com/ONLYOFFICE/Docker-DocumentServer

### Alfresco

* Deploy the amp to both the repo and share end using alfresco-mmt or
other methods

* Add the `onlyoffice.url` property to alfresco-global.properties:
* e.g: `onlyoffice.url=http://onlyoffice.mycompany.com/`


## How it works

The Onlyoffice integration follows the API documented here
https://api.onlyoffice.com/editors/basic:

* User navigates to a document within Alfresco Share and selects the
`Edit in Onlyoffice` action
* Alfresco Share makes a request to the repo end (URL of the form: `/parashift/onlyoffice/prepare?nodeRef={nodeRef}`)
* Alfresco Repo end prepares a JSON object for Share with the following
properties:
* **docUrl**: the URL that onlyoffice uses to download the document
(includes the `alf_ticket` of the current user)
* **callbackUrl**: the URL that onlyoffice needs to POST a callback to
when finished editing
* **onlyofficeUrl**: the URL that the client needs to talk to onlyoffice
(given by the onlyoffice.url property)
* **key**: the UUID+Modified Timestamp to instruct onlyoffice whether to download the document again or not
* **docTitle**: the Title (name) of the document
* Alfresco Share takes this object and constructs a page from a
freemarker template, filling in all of those values so that the client
browser can load up the editor
* The client browser makes a request for the javascript library from
onlyoffice and sends onlyoffice the docEditor configuration with the
properties as above
* Onlyoffice then downloads the document from alfresco and the user begins editing
* Onlyoffice sends a POST request to the callback URL to inform Alfresco
that a user is editing the document
* Alfresco locks the document, but still allows other users with write access
the ability to collaborate in real time with onlyoffice by leaving the Action present
* When all users and client browsers are finished, they close the
editing window
* After 10 seconds of inactivity, onlyoffice sends a POST to the
callback URL letting Alfresco know that the clients have finished.
* Alfresco downloads the new version of the document, replacing the old
one
12 changes: 4 additions & 8 deletions repo/build.gradle
View file
Original file line number Diff line number Diff line change
Expand Up @@ -24,10 +24,9 @@ ext {
alfresco = [:]
alfresco.version = "5.0.1"

baseName = "onlyoffice-alfresco-repo"
}

project.description = "Onlyoffice Integration"
project.description = "Onlyoffice Integration for Alfresco"
version = "git describe --tags".execute().text.trim()


Expand Down Expand Up @@ -67,18 +66,15 @@ dependencies {
}

jar {
baseName = project.baseName
baseName = project.name
version = project.version
}

amp {
id = "com.parashift." + project.baseName
baseName = project.baseName
alias = "onlyoffice"
id = "com.parashift." + project.name
version = project.version
title = "Onlyoffice"
title = "Onlyoffice Alfresco Integration Repo"
description = project.description

}


Expand Down
21 changes: 12 additions & 9 deletions share/build.gradle
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,9 @@ allprojects {
targetCompatibility = 1.7
}

project.description = "Onlyoffice Integration for Alfresco Share"
version = "git describe --tags".execute().text.trim()


repositories {
mavenCentral()
Expand All @@ -27,16 +30,16 @@ dependencies {
compile 'org.springframework.extensions.surf:spring-webscripts:1.2.0'
}

jar {
baseName = project.name
version = project.version
}

amp {
// id is mandatory when you want to pack a AMP
id = "com.parashift.onlyoffice-alfresco"

// the following is options but highly recommended you fill yourself
// as the plugin just infer the values from project.version
// and project.name
alias = "onlyoffice-alfresco"
version = "1.0.0"
title = "Onlyoffice Alfresco Integration"
description = "This Module integrates Alfresco Share with Onlyoffice"
id = "com.parashift" + project.name
version = project.version
title = "Onlyoffice Alfresco Integration Share"
description = project.description
}

0 comments on commit 87f503f

Please sign in to comment.