Frontend Integration Active Parameter Mode
Integration Diagram
- Filez Document Platform and the business system need to agree on a secret to calculate the HMAC of the request URL
- 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}¶ms=${params}&ts=${ts}&HMAC=${hmac}
See Request Parameters for all request parameters.
- 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.
- 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. - After obtaining related information from the
userinfoandmetaparameters, download the file from the location specified bydownloadUrl.
Active Parameter Mode
Request Address:
GET http(s)://${zOffice-server-IP}:${zOffice-server-port}/docs/app/driver-callback
Request Parameter Definitions:
| Parameter Name | Required | Description |
|---|---|---|
| repoId | Yes | Unique identifier ID of the third-party service in zOffice, defined by the third-party service itself, and needs to be set in the management console at the same time. |
| docId | Yes | Unique ID of the document in the third-party system |
| action | No | Identifies the behavior of opening the document, value can be edit or view, default is view |
| userinfo | Yes | Identifies the user information performing the operation, a base64-encoded JSON string. base64(JSON.stringify(userinfoObj)). Must be encoded with encodeURIComponent before concatenating to the URL |
| meta | Yes | Identifies the metadata of the current document, a base64-encoded JSON string. base64(JSON.stringify(metaObj)). Must be encoded with encodeURIComponent before concatenating to the URL |
| downloadUrl | Yes | Address for downloading the file stream, the file can be downloaded through this URL. The corresponding URL address cannot use encodeURIComponent encoding, please do not include request parameters, request parameters that need to be passed should be passed through params. The host of downloadUrl must be consistent with the interface address prefix configured for this application in the management console. host includes hostname and port. If the host in downloadUrl does not include a port, the related configuration should not include a port either, even if it's the default port |
| uploadUrl | No | File upload address. Can be ignored when previewing documents, needs to be passed when editing documents. The corresponding URL address cannot use encodeURIComponent encoding, please do not include request parameters, request parameters that need to be passed should be passed through params. |
| params | No | Information that needs to be passed back, format key=value;key2=value2. If the third-party system has permission verification when requesting downloadUrl and uploadUrl, please be sure to pass related identity information in params, otherwise the request will fail. See params description below for details |
| ts | Yes | Timestamp when the URL was generated, precision in milliseconds |
| HMAC | Yes | Salted hash value of the request URL, used to verify whether the request address has been tampered with |
Example
http://luoshuhost:8001/docs/app/driver-callback?
repoId=thirdpart-rest&
docId=demo-docx-123&
action=edit&
userinfo=eyJpZCI6ImxpY2h1biIsImRpc3BsYXlfbmFtZSI6Iueri%2BaYpSIsImVtYWlsIjoibGljaHVuQGxlbm92b2Nsb3VkLmNvbSJ9Cg%3D%3D&
meta=eyJjcmVhdGVkX2J5Ijp7ImlkIjoibGljaHVuIiwibmFtZSI6ImxpY2h1biIsImVtYWlsIjoibGljaHVuQGxlbm92b2Nsb3VkLmNvbSJ9fQ%3D%3D&
downloadUrl=http://thirdparty-file-server/context/content&
params=3rd-party-token=xxx;id=demo-docx-123;x-webhook-header=xxx&
ts=1685673093648&
HMAC=8b48d4833bd2e22203eb890c91a6fe08df6056bf3bda126ab31e5a9d9c04aad5
uploadUrl Notes
The Document Platform server uses HTTP POST to upload files through formData. Content type is multipart/form-data.
| Parameter | Required | Location | Description | Type |
|---|---|---|---|---|
| Content-Type | Yes | Header | Fixed as multipart/form-data | string |
| file | Yes | Body(form data) | The file itself, contains two attributes: filename (fixed as content, please ignore. Currently, file names will not be modified through this API), contentType (the file's mimeType, e.g., 'application/octet-stream') | multipartfile |
After successful upload, the latest file modification time needs to be returned.
For example:
{
"modified_at": "2020-03-25T02:57:38.000Z" // Required, this time should be the latest save time of this file in the business system, and this save is brought about by this API.
}
userinfo Description
Properties
| Field Name | Required | Description |
|---|---|---|
| id | Yes | User ID |
| display_name | Yes | User nickname |
| Yes | User email, can be the same as id | |
| photo_url | No | User avatar |
JSON Representation
{
"id": "301", // User ID
"display_name": "docstest02", // User nickname
"email": "docstest02@lenovocloud.com", // User email
"photo_url": "https://avatar.thirdparty.com/testOrg/people/301.png", // User avatar
}
meta Description
meta supports passing in the following information, other information will be filtered. The following information can be selected to transmit only part of the information.
Properties
| Field Name | Required | Type | Example Value | Description |
|---|---|---|---|---|
| id | Yes | String | 577 | Unique file ID, must be consistent with docId in the request URL |
| name | Yes | String | preview-center.docx | File name including extension |
| modified_at | Yes | String | 2023-08-17T13:57:38.000Z | Modification time, format needs to be consistent with the example on the left. See detailed description below |
| created_by.id | Yes | String | 301 | Document creator ID |
| created_by.name | Yes | String | docstest02 | Document creator name |
| permissions.write | Yes | Boolean | true | Whether has edit permission |
| permissions.read | Yes | Boolean | true | Whether has read permission |
| permissions.download | No | Boolean | true | Whether the file can be downloaded. If the file cannot be downloaded, the file content cannot be copied to places other than the current file. Default value is false |
| permissions.print | No | Boolean | true | Whether the file can be printed. Default value is false |
| role | No | String | commenter | This value can be "contributor", "commenter", "auditor". Default value is none |
| waterMark.line1 | No | String | Filez zOffice docstest02 | Watermark first line, default is empty |
| waterMark.line2 | No | String | last modified user | Watermark second line, default is empty |
| waterMark.line3 | No | String | product info | Watermark third line, default is empty |
| waterMark.line4 | No | String | more info | Watermark fourth line, default is empty |
| waterMark.withData | No | Boolean | true | Whether watermark includes date, default true |
| waterMark.fontcolor | No | String | #cecece | Watermark color, default gray |
| waterMark.transparent | No | Number | 70 | Transparency. The smaller the value, the more obvious the transparent effect, default 70, type is number |
| waterMark.rotation | No | Number | 315 | Rotation angle, range 0-360, e.g., left tilt=315, right tilt=45, horizontal=0, type is number |
| waterMark.fontsize | No | String | 16 | Watermark font size, default 16 |
| waterMark.font | No | String | SimHei | Watermark font, default SimHei |
| waterMark.spacing | No | Number | 50 | Line spacing, default 50, type is number |
| owner.id | No | String | 301 | Document owner ID |
| owner.name | No | String | docstest02 | Document owner name |
| extension.previewWithTrackChange | No | Boolean | false | true means revisions are automatically displayed during preview. false or not providing this field means revisions are not displayed during preview. Only for text documents |
| extension.trackChangeForceOn | No | Boolean | false | true means revisions are automatically turned on during editing and cannot be turned off. false or not providing this field means revisions are not forced on during editing. Only for text documents. |
JSON Representation
{
"id": "577",
"name": "preview-center.docx",
"modified_at": "2023-08-17T13:57:38.000Z",
"created_by": {
"id": "301",
"name": "docstest02"
},
"permissions": {
"write": true, // Controls whether the document can be edited
"read": true, // Controls whether the document can be previewed
},
"role": "commenter", // Optional, indicates the current user's role in the zoffice editor for the current document (only for text documents). This value can be "contributor", "commenter", "auditor".
"extension": {
"previewWithTrackChange": false, // true means revisions are automatically displayed during preview. false or not providing this field means revisions are not displayed during preview. Only for text documents.
"trackChangeForceOn": false, // true means revisions are automatically turned on during editing and cannot be turned off. false or not providing this field means revisions are not forced on during editing. Only for text documents.
},
"waterMark": { // Document watermark related
"line1": "李明liming@lenovo.com", // For example, file last updater information
"line2": "张三hangshan@lenovo.com", // For example: file editor/previewer information
"line3": "", // For example: other custom text
"line4": "", // For example: other custom text
"withDate": true, // Whether to include date after each line of text
"fontcolor": "#fD4147", // RGB value,
"transparent": 30, // 0-100, transparency. The smaller the value, the more obvious the transparent effect.
"rotation": 315, // Rotation angle 0-360, left tilt=315, right tilt=45, horizontal=0
"fontsize": "72",
"font": "SimHei"
}
}
modified_at Implementation Must Pay Attention Please refer to: Cache Notes
params
Information passed in params will be passed back in header, cookie, and queryParams when calling third-party interfaces.
For example, when params=x-param-1=aaa;x-param-2=bbb, and the third-party interface is /v2/context/docId/content, the actual request received by the third party is as follows:
Request Address: /v2/context/docId/content?x-param-1=aaa&x-param-2=bbb
Request Headers:
x-param-1: aaa
x-param-2: bbb
Cookie: x-param-1=aaa;x-param-2=bbb
Note: Parameters that need to be passed back in the header must start with x- (can be modified through special configuration headerPrefix default value)