Integrations OfficeOnline - Huddle/huddle-apis GitHub Wiki

Office Online Integration

Huddle provides an integration with Office Online, which allows users to view and edit content stored in Huddle in the Office Online application.

If enabled by the account, the Office Online integration element will be returned with the response. In the links collection of this element, there will be one with the @rel value integration. This end point lets you know which specific actions you can perform in Office Online.

If the OfficeOnline integration element does not contain the integration link, then the reasons will be returned in the DisabledReasons collection, which will contain a list of (string) error codes explaining why Office Online is disabled.

Code	Reason
ACCOUNT_SETTING_DISABLED	-
WORKSPACE_SETTING_DISABLED (or DOC_LIB_SETTING_DISABLED)	Workspace setting disabled

Also, note that Office Online presently supports the following MimeTypes for 'Edit'

Extension	MIME Type	Integration
.docx	application/vnd.openxmlformats-officedocument.wordprocessingml.document	Office Online
.pptx	application/vnd.openxmlformats-officedocument.presentationml.presentation	Office Online
.xlsx	application/vnd.openxmlformats-officedocument.spreadsheetml.sheet	Office Online

A successful GET request has been made to the integration uri will return a set of links. The link with a @rel of view-session is the uri to initiate a view (read-only) Office Online session, and the link with a @rel of edit-session is the uri for initiating an Office Online editing session.

Example

Request

GET .../officeOnline/integration/123 HTTP/1.1
Accept: application/vnd.huddle.data+json

Response - Success

HTTP/1.1 200 OK
Content-Type: application/vnd.huddle.data+json

{
    "links": [
        {
            "rel": "view-session",
            "href": "..."
        },
        {
            "rel": "edit-session",
            "href": "..."
        },
        {
            "rel": "leave-session",
            "href": "..."
        }
    ],
    "cannotEditReasons": [],
    "cannotViewReasons": []
}

Error Codes - CannotEditReasons

These string values are returned to indicate the reason(s) that a user is unable to edit a document in Office Online.

Code	Reason
UNSUPPORTED_MIMETYPE	-
DOCUMENT_TOO_LARGE	The document is bigger than the maximum permitted size
CANNOT_LOCK	User cannot lock the document
EXCLUSIVELY_LOCKED	The document is already locked by another user

Error Codes - CannotViewReasons

These string values are returned to indicate the reason(s) that a user is unable to view a document in Office Online.

Code	Reason
UNSUPPORTED_MIMETYPE	-
READ_PERMISSION_DENIED	User does not have permissions to view/read the document

Editing a document in Office Online

If it is possible to edit the document in Office Online, the Integration endpoint will return a link with a @rel value of edit-session. POSTing to this endpoint will initiate/join the current user to an editing session, and return you the accessToken and editor-src elements needed to display the Office Online editor.

Note, editing will always be 'co-authoring' enabled.

Example

Request

POST .../officeOnline/integration/123/edit-session HTTP/1.1
Accept: application/vnd.huddle.data+json

{"hostUrl":"http://my.document.app/123"}

Response - Success

HTTP/1.1 201 Created
Content-Type: application/vnd.huddle.data+json
Location: .../officeOnline/integration/123/edit-session

{
    "links": [
        {
            "rel": "editor-src",
            "href": "..."
        },
        {
            "rel": "leave-session",
            "href": "..."
        }
    ],
    "accessToken": {
        "accessTokenId":"...",
        "documentId":123,
        "userId":456,
        "sessionTimeMinutes":60
    }
}

Viewing a document in Office Online

If it is possible to view a document in Office Online, the Integration endpoint will return a link with a @rel value of view-session. POSTing to this endpoint will initiate a viewing session for the user, and return you the accessToken and editor-src elements needed to display the Office Online viewer.

Example

Request

POST .../officeOnline/integration/123/view-session HTTP/1.1
Accept: application/vnd.huddle.data+json

{"hostUrl":"http://my.document.app/123"}

Response - Success

HTTP/1.1 201 Created
Content-Type: application/vnd.huddle.data+json
Location: .../officeOnline/integration/123/view-session

{
    "links": [
        {
            "rel": "editor-src",
            "href": "..."
        }
    ],
    "accessToken": {
        "accessTokenId":"...",
        "documentId":123,
        "userId":456,
        "sessionTimeMinutes":60
    }
}

Leaving a session

If the user is already part of an Office Online session, the Integration endpoint will return a link with a @rel value of leave-session. A DELETE to this uri will end the editing session.

Example

Request

DELETE .../officeOnline/integration/123/edit-session HTTP/1.1
Accept: application/vnd.huddle.data+json

Response - Success

HTTP/1.1 204 No Content
Content-Type: application/vnd.huddle.data+json