Third-Party Integration Mechanism

Files, Users, and Permissions

Files: Files are stored in the business system, and each file must have a file ID. The naming rules for IDs are determined by the business system, requiring that the same file has the same ID, and different files have different IDs (except for file systems that support multiple versions). When the business system calls online editing/preview, it needs to provide the file ID. Filez Document Platform will call back to the business system based on the file ID to obtain the corresponding file.

Users: Filez Document Platform does not need to synchronize the organization and users of the business system. During online editing and online preview, the caller (business system) needs to provide current user information. This user information will be recorded in the document platform and reflected in the files, such as: revision records, comments, and collaboration records.

Permissions: Only the business system knows whether a user can edit/preview a file online at a certain moment. This information does not need to be synchronized to the document platform. Every time the document platform provides online editing/preview services, it will ask the business system whether the current user has permission.

Integration Methods

Files, users, and permission information are all in the business system. Therefore, every time the business system requests online editing/preview, Filez Document Platform needs to obtain file, user, and permission information from the business system. Depending on how this information is obtained, there are different integration methods.

Standard Integration Method

The following explains the integration principle using the API call process after Filez Document Platform is integrated with a third-party system.

1. When users need to use document editing/preview services in the frontend page of a third-party service, they request the zOffice editing page according to the following URL pattern.

http(s)://${zOffice_domain}/docs/app/${app_id}/${docId}/${action}/content

Where zOffice_domain is the domain name of the zOffice server, which can be the same as the domain name of the third-party service. app_id is the ID of the third-party business system calling zOffice, determined by the third-party business system, with related information configured in the zOffice system. docId is the ID of the document to be operated. For a document, its ID must be unique in the third-party system. For editing, the value of action is edit, and for preview, the value is view.

2. The zOffice server receives the document editing or preview request. First, it needs to verify this request. zOffice will send a profiles request (to get current user information) to the third-party service with the token passed from the third-party service. If a correct response is received, the verification passes, and the current user information is obtained.

3. After verification passes, the zOffice server sends a request to the third-party service to get document metadata. The response JSON contains information such as file name, size, etc., as well as permission information for the current user regarding this file. Based on the response, it determines whether the user can edit/preview this file.

4. If the user has permission to access this file, the zOffice server requests the third-party service to download this file.

5. After obtaining the file, zOffice will process the file and return the processed content to the frontend. At this point, users can edit/preview the document.

Basic Callback APIs

zOffice calls back the business system's APIs using agreed-upon paths. The related API agreements are as follows:

Name	Method	API	Description
Get File Content	GET	/{context}/{docId}/content	Get the document content specified by docId, where docId is the document ID in the third-party service. Returns a downloadable file.
Get File Metadata	GET	/{context}/{docId}/meta	Get the document metadata specified by docId, where docId is the document ID in the third-party service. Returns in JSON format.
Store File Content	POST	/{context}/{docId}/content	Upload the document specified by docId, where docId is the document ID in the third-party service. Returns the latest meta information of this document in JSON format.
Current User Information	GET	/{context}/profiles	Returns detailed information of the current user

Where {context} is the domain name and path prefix of the callback API provided by the business system. For example: if context is set to

http://my.integration.com/zoffice/files (Note: this URL does not have a trailing '/'). The get content API sent by zOffice (docId = 12168237), i.e., the file download callback API implemented by the business system is: GET http://my.integration.com/zoffice/files/12168237/content

Frontend Integration Method

1. Filez Document Platform and the business system need to agree on a secret to calculate the HMAC of the request URL

2. When the business system frontend needs to call online editing/preview services, it requests the business system's server. The business system's server generates the online editing/preview URL based on the secret. The URL format is as follows:

http(s)://${zOffice_domain}/docs/app/driver-callback?repoId=${repoId}&docId=${docId}&action=edit&userinfo=${userInfo}&meta=${meta}&downloadUrl=${downloadUrl}&uploadUrl=${uploadUrl}&params=${params}&ts=${ts}&HMAC=${hmac}

3. After the Filez Document Platform server receives the request, it first verifies whether the request is correct based on the HMAC value to ensure that related parameters are not tampered with.

4. Verify whether the request has expired based on ts (timestamp) to ensure that online editing/preview requests are not arbitrarily propagated. By default, an online editing/preview request URL address is valid for 10 seconds. The business system and Filez Document Platform need to have synchronized time.

5. After obtaining related information from the userinfo and meta parameters, download the file from the location specified by downloadUrl.

Frontend SDK Integration Method

Applicable Version

Filez Document Platform supports Frontend SDK integration from v8.1 onwards

1. Filez Document Platform and the business system need to agree on a secret to calculate the token for request parameters
2. When the business system frontend needs to call online editing/preview services, it requests the business system's server. The business system's server generates initialization configuration based on the document to be opened and the user, and uses the secret to generate the token
3. The business system frontend uses the initialization configuration and token to call the Filez Document Platform's JSSDK API to access the online editing/preview services
4. The Document Platform JSSDK will create an iframe, then access the Document Platform's online editing/preview services, passing the initialization configuration and token
5. After the Filez Document Platform server receives the request, it performs necessary validations, such as whether the token is valid, whether the token has expired, whether the callback address is correct, etc.
6. Filez Document Platform obtains related information from parameters such as userinfo and meta, and downloads the file from the location specified by downloadUrl.
7. The Document Platform returns the page containing the document content to the iframe. At this point, users can edit/preview the document.

Integration Method Selection

1. If you only need to integrate the Document Platform's online preview capability, it is recommended that customers use the frontend integration method. The reason is that this integration method is relatively simple and fast, and can utilize the business system's existing file download interface.

2. For business systems that prefer developing server-side APIs, the standard integration method can be adopted. This method requires the business system to return important information through server-side callbacks, such as: userinfo, meta, etc.

3. The online editing/preview request URL in the frontend integration method contains a timestamp. The Filez Document Platform service ensures the timeliness of the request address based on the timestamp to prevent the request address from being propagated. To ensure the validity of the timestamp, the business system can only generate the timestamp on the server side. At the same time, the time on the business system server and the Document Platform server must be strictly synchronized (error less than 1 second).

4. With the frontend JSSDK integration method, important information is not passed in the request URL. This prevents the request address from being propagated. And the main integration capabilities are implemented through the JSSDK. However, it requires that the online editing or preview page must be embedded as an iframe in the business system's page.