CheckFileInfo

Required for: Online iOS
GET /wopi/files/(file_id)

The CheckFileInfo operation is one of the most important WOPI operations. This operation must be implemented for all WOPI actions. CheckFileInfo returns information about a file, a user’s permissions on that file, and general information about the capabilities that the WOPI host has on the file. In addition, some CheckFileInfo properties can influence the appearance and behavior of WOPI clients.

Office Online Tip

Some properties require special arrangements with Microsoft in order to be used with Office Online. These properties are marked Special permission required for use in Office Online. If you wish to use these properties, you must contact Microsoft and request that the appropriate settings be adjusted to allow you to use these properties. Otherwise these properties will be ignored.

Parameters:
  • file_id (string) – A string that specifies a file ID of a file managed by host. This string must be URL safe.
Query Parameters:
 
  • access_token (string) – An access token that the host will use to determine whether the request is authorized.
Request Headers:
 
  • X-WOPI-SessionContext – The value of the Session context parameter, if provided on the initial WOPI action URL using the sc parameter.
Status Codes:

See also

Standard WOPI request and response headers
In addition to the request/response headers listed here, this operation may also use the Standard WOPI request and response headers.

Response

The response to a CheckFileInfo call is JSON (as specified in RFC 4627) containing a number of properties, most of which are optional.

All optional values default to the following values based on their type:

Type Default value
Boolean false
String The empty string
Integer/Long Varies; see individual properties for details
Array Empty array

Important

No properties should be set to null. If you do not wish to set a property, simply omit it from the response and WOPI clients will use the default value.

Required response properties

The following properties must be present in all CheckFileInfo responses:

BaseFileName
The string name of the file, including extension, without a path. Used for display in user interface (UI), and determining the extension of the file.
OwnerId

A string that uniquely identifies the owner of the file.

Important

This ID is subject to uniqueness and consistency requirements. See Requirements for user identity properties for more information.

Size
The size of the file in bytes, expressed as a long, a 64-bit signed integer.
UserId

A string value uniquely identifying the user currently accessing the file.

Important

This ID is subject to uniqueness and consistency requirements. See Requirements for user identity properties for more information.

Version

The current version of the file based on the server’s file version schema, as a string. This value must change when the file changes, and version values must never repeat for a given file.

Important

This value must be a string, even if numbers are used to represent versions.

Requirements for user identity properties

Hosts use the OwnerId and UserId properties to provide user ID data to WOPI clients. User identity properties are intended for telemetry purposes, and thus should not be shown in any WOPI client UI. These properties must meet the following requirements:

  • Unique to a single user.
  • Consistent over time. For example, if a particular user uses a WOPI client to view a document on Monday, then returns and views another document on Tuesday, the value of the user identity properties should match.

Important

Hosts should avoid the following characters in user identity properties in order to support the widest range of WOPI clients:

<>"#{}^[]`\/

WOPI host capabilities properties

The WOPI host capabilities properties indicate to the WOPI client what WOPI capabilities that the host supports for a file. All of these properties are optional and thus default to false; hosts should set them to true if their WOPI implementation meets the requirements for a particular property.

Important

If a WOPI server sets any capabilities properties to true, WOPI clients will assume that all of the operations represented by that capability property are supported. Thus, a WOPI host must implement all operations represented by that capability property if they set the property to true.

SupportedShareUrlTypes

An array of strings containing the Share URL types supported by the host.

These types can be passed in the X-WOPI-UrlType request header to signify which Share URL type to return for the GetShareUrl (files) operation.

Possible Values:

ReadOnly
This type of Share URL allows users to view the file using the URL, but does not give them permission to edit the file.
ReadWrite
This type of Share URL allows users to both view and edit the file using the URL.
SupportsCobalt

A Boolean value that indicates that the host supports the following WOPI operations:

SupportsContainers

A Boolean value that indicates that the host supports the following WOPI operations:

Tip

SupportsContainers is a superset of SupportsDeleteFile. However, WOPI hosts should explicitly return true for both properties if SupportsContainers is true.

SupportsDeleteFile
A Boolean value that indicates that the host supports the DeleteFile operation.
SupportsEcosystem

A Boolean value that indicates that the host supports the following WOPI operations:

SupportsExtendedLockLength

A Boolean value that indicates that the host supports lock IDs up to 1024 ASCII characters long. If not provided, WOPI clients will assume that lock IDs are limited to 256 ASCII characters.

Important

While the 256 ASCII character lock length is currently sufficient, longer lock IDs will likely be required to support future scenarios, so we recommend hosts support extended lock lengths as soon as possible. See lock ID lengths for more information.

SupportsFolders

A Boolean value that indicates that the host supports the following WOPI operations:

SupportsGetFileWopiSrc
A Boolean value that indicates that the host supports the 🚧 GetFileWopiSrc (ecosystem) operation.
SupportsGetLock
A Boolean value that indicates that the host supports the GetLock operation.
SupportsLocks

A Boolean value that indicates that the host supports the following WOPI operations:

SupportsRename
A Boolean value that indicates that the host supports the RenameFile operation.
SupportsUpdate

A Boolean value that indicates that the host supports the following WOPI operations:

SupportsUserInfo

A Boolean value that indicates that the host supports the PutUserInfo operation.

New in version 2015.08.03.

User metadata properties

The following properties are used to provide additional information about users.

IsAnonymousUser

A Boolean value indicating whether the user is authenticated with the host or not. Hosts should always set this to true for unauthenticated users, so that clients are aware that the user is anonymous.

When setting this to true, hosts can choose to omit the UserId property, but must still set the OwnerId property.

New in version 2017.02.15.

IsEduUser

A Boolean value indicating whether the user is an education user or not.

New in version 2016.01.27.

LicenseCheckForEditIsEnabled

A Boolean value indicating whether the user is a business user or not.

UserFriendlyName
A string that is the name of the user, suitable for displaying in UI.
UserInfo

A string value containing information about the user. This string can be passed from a WOPI client to the host by means of a PutUserInfo operation. If the host has a UserInfo string for the user, they must include it in this property. See the PutUserInfo documentation for more details.

New in version 2015.08.03.

User permissions properties

A WOPI client must always assume that users have limited permissions to documents. If a host does not set the appropriate user permissions properties, users will not be able to perform operations such as editing documents using a WOPI client.

Ultimately, the host has final control over whether WOPI operations attempted by the client should succeed or fail based on the access token provided in the WOPI request. Thus, these properties do not act as an authorization mechanism. Rather, these properties help WOPI clients tailor tailor their UI and behavior to the specific permissions a user has. For example, a WOPI client can hide file renaming UI if the UserCanRename property is false.

However, a WOPI client expects that even if that UI were somehow made available to a user without appropriate permissions, the WOPI RenameFile request would fail since the host would determine the action was not permissible based on the access token passed in the request.

Note that there is no property that indicates the user has permission to read/view a file. This is because WOPI requires the host to respond to any WOPI request, including CheckFileInfo, with a 404 Not Found if the access token is invalid or expired.

ReadOnly
A Boolean value that indicates that, for this user, the file cannot be changed.
RestrictedWebViewOnly
A Boolean value that indicates that the WOPI client should restrict what actions the user can perform on the file. The behavior of this property is dependent on the WOPI client.
UserCanAttend
A Boolean value that indicates that the user has permission to view a broadcast of this file.
UserCanNotWriteRelative
A Boolean value that indicates the user does not have sufficient permission to create new files on the WOPI server. Setting this to true tells the WOPI client that calls to PutRelativeFile will fail for this user on the current file.
UserCanPresent
A Boolean value that indicates that the user has permission to broadcast this file to a set of users who have permission to broadcast or view a broadcast of the current file.
UserCanRename
A Boolean value that indicates the user has permission to rename the current file.
UserCanWrite
A Boolean value that indicates that the user has permission to alter the file. Setting this to true tells the WOPI client that it can call PutFile on behalf of the user.

File URL properties

Hosts can return a number of URLs for the file that WOPI clients may navigate to in various scenarios.

Office Online Tip

These properties can be used to customize the user experience of the Office Online applications. See Customizing Office Online using CheckFileInfo properties for more information about how each property is used in Office Online.

CloseUrl
A URI to a web page that the WOPI client should navigate to when the application closes, or in the event of an unrecoverable error.
DownloadUrl

A user-accessible URI to the file intended to allow the user to download a copy of the file.

Important

This URI should directly download the file. In other words, WOPI clients expect that when directing users to this URL, the file will be immediately downloaded. This URL should not direct the user to some separate UI to download the file.

Important

This URI should always provide the most recent version of the file.

FileSharingUrl
A URI to a location that allows the user to share the file.
FileUrl

A URI to the file location that the WOPI client uses to get the file. If this is provided, the WOPI client may use this URI to get the file instead of a GetFile request. A host might set this property if it is easier or provides better performance to serve files from a different domain than the one handling standard WOPI requests. WOPI clients must not add or remove parameters from the URL; no other parameters, including the access token, should be appended to the FileUrl before it is used.

Important

The FileUrl is meant as a performance enhancement. The GetFile operation must still be supported for the file even when the FileUrl property is provided.

Note

Requests to the FileUrl can not be signed using proof keys. The FileUrl is used exactly as provided by the host, so it does not necessarily include the access token, which is required to construct the expected proof.

FileVersionUrl

A URI to a location that allows the user to view the version history for the file.

New in version 2017.02.15.

HostEditUrl
A URI to a host page that loads the edit WOPI action.
HostEmbeddedViewUrl
A URI to a web page that provides access to a viewing experience for the file that can be embedded in another HTML page. This is typically a URI to a host page that loads the embedview WOPI action.
HostViewUrl
A URI to a host page that loads the view WOPI action. This URL is used by Office Online to navigate between view and edit mode.
SignoutUrl

A URI that will sign the current user out of the host’s authentication system.

See also

SignInUrl

PostMessage properties for web-based WOPI clients

CheckFileInfo supports a number of properties that can be used by web-based WOPI clients such as Office Online to customize the user interface and experience when using those clients. See PostMessage properties for more information on these properties and how to use them.

Other miscellaneous properties

AllowAdditionalMicrosoftServices

A Boolean value that indicates a WOPI client may connect to Microsoft services to provide end-user functionality.

New in version 2016.06.27.

Office Online Tip

In Office Online, setting this property to true enables the following features:

Bing spelling and proofing
Office Online will use the Bing Spell Check API to provide better spelling and proofing suggestions for supported languages.
Smart Lookup
Office Online will use Bing to power the Smart Lookup feature, which provides quick access to definitions, Wiki articles, and top related searches from the web.

Additional features might be added in the future.

AllowErrorReportPrompt

A Boolean value that indicates that if the session ends in an error, it is permitted to prompt the user for permission to collect a detailed report about their specific error. The information gathered could include the user’s file, and other session specific state.

New in version 2017.06.01.

Tip

This value should be set to false if no additional collection should be done on errors, or if the user has opted out of telemetry collection.

AllowExternalMarketplace
A Boolean value that indicates a WOPI client may allow connections to external services referenced in the file (for example, a marketplace of embeddable JavaScript apps).
CloseButtonClosesWindow
A Boolean value that indicates the WOPI client should close the window or tab when the user activates any Close UI in the WOPI client.
DisablePrint
A Boolean value that indicates the WOPI client should disable all print functionality.
DisableTranslation
A Boolean value that indicates the WOPI client should disable all machine translation functionality.
FileExtension

A string value representing the file extension for the file. This value must begin with a .. If provided, WOPI clients will use this value as the file extension. Otherwise the extension will be parsed from the BaseFileName.

Tip

While this property is not required, hosts should set it rather than relying on the BaseFileName parsing.

FileNameMaxLength

An integer value that indicates the maximum length for file names that the WOPI host supports, excluding the file extension. The default value is 250. Note that WOPI clients will use this default value if the property is omitted or if it is explicitly set to 0.

Office Online Tip

This property is optional; however, hosts wishing to enable file renaming within Office Online should verify that the default value is appropriate and set it accordingly if not. See the RenameFile operation for more details.

LastModifiedTime
A string that represents the last time that the file was modified. This time must always be a must be a UTC time, and must be formatted in ISO 8601 round-trip format. For example, "2009-06-15T13:45:30.0000000Z".
SHA256

A 256 bit SHA-2-encoded [FIPS 180-2] hash of the file contents, as a Base64-encoded string. Used for caching purposes in WOPI clients.

Office Online Tip

See 🔧 Optimizing document viewing for high volume for more details on how this property is used in Office Online.

UniqueContentId

Special permission required for use in Office Online

In special cases, a host may choose to not provide a SHA256, but still have some mechanism for identifying that two different files contain the same content in the same manner as the SHA256 is used.

This string value can be provided rather than a SHA256 value if and only if the host can guarantee that two different files with the same content will have the same UniqueContentId value.

Office Online Tip

See 🔧 Optimizing document viewing for high volume for more details on how this property is used in Office Online.

Unused and future properties

The following properties are defined as valid CheckFileInfo response properties. However, they are not used, either because they are pending deprecation or they are designated for future features of WOPI clients and WOPI servers.

ClientUrl
A user-accessible URI directly to the file intended for opening the file through a client. Can be a DAV URL (RFC 5323), but may be any URL that can be handled by a client that can open a file of the given type.
DisableBrowserCachingOfUserContent
A Boolean value that indicates that the WOPI client should disable caching of file contents in the browser cache. Note that this has important performance implications for web browser-based WOPI clients.
EditAndReplyUrl
🔧 Not yet documented.
HostAuthenticationId

A string value uniquely identifying the user currently accessing the file.

Warning

This property should not be used. Hosts should use the UserId property instead.

HostEmbeddedEditUrl
A URI to a web page that provides access to an editing experience for the file that can be embedded in another HTML page. For example, a page that provides an HTML snippet that can be inserted into the HTML of a blog.
HostNotes
A string that is used by the host to pass arbitrary information to the WOPI client. The client must ignore this string if it does not recognize its contents. A host must not require that a client understand the contents of this string to operate.
HostRestUrl
A URI that is the base URI for REST operations for the file.
IrmPolicyDescription
A string that the WOPI client should display to the user indicating the IRM policy for the file. This value should be combined with IrmPolicyTitle.
IrmPolicyTitle
A string that the WOPI client should display to the user indicating the IRM policy for the file. This value should be combined with IrmPolicyDescription.
PresenceProvider
A string that identifies the provider of information that a WOPI client may use to discover information about the user’s online status (for example, whether a user is available via instant messenger).
PresenceUserId
A string that identifies the user in the context of the PresenceProvider.
ProtectInClient
A Boolean value that indicates that the WOPI client should take measures to prevent copying and printing of the file. This is intended to help enforce IRM.
SignInUrl

A URI that will allow the user to sign in using the host’s authentication system. This property can be used when supporting anonymous users. If this property is not provided, no sign in UI will be shown in Office Online.

See also

SignoutUrl

SupportsFileCreation
A Boolean value that indicates that the host supports creating new files using the WOPI client.
A Boolean value that indicates that the host supports scenarios where users can operate on files in limited ways via restricted URLs.
SupportsSecureStore
A Boolean value that indicates that the host supports calls to a secure data store utilizing credentials stored in the file.
TenantId

A string value uniquely identifying the user’s ‘tenant,’ or group/organization to which they belong.

Caution

The presence of this property does not remove the uniqueness and consistency requirements listed above. User properties are expected to be unique per user and consistent over time regardless of the presence of a TenantId.

TimeZone
A string that is used to pass time zone information to a WOPI client. The format of this value is determined by the host.
UserPrincipalName
A string value uniquely identifying the user currently accessing the file.
WebEditingDisabled

A Boolean value that indicates that the WOPI client must not allow the user to edit the file.

Note

This does not mean that the user doesn’t have rights to edit the file. Hosts should use the UserCanWrite property for that purpose.

Workflow properties

Pre-release Feature

This documentation is for an upcoming feature and may undergo dramatic changes prior to final release. Pre-release features are available in the Test environment only.

WorkflowType

Pre-release property - not yet used by any WOPI client

An array of strings containing the workflow types available for the document. Possible values are:

  • Assign
  • Submit

This property must always be specified if WorkflowUrl or WorkflowPostMessage are provided. If this property is not supplied, then both WorkflowUrl and WorkflowPostMessage must be ignored by the WOPI client.

Conversely, if the WorkflowType property is provided but neither WorkflowUrl nor WorkflowPostMessage are provided, then the WorkflowType value must be ignored by the WOPI client.

Important

While this property is an array of strings, note that specific values of WorkflowType may be mutually exclusive depending on the WOPI client. WOPI clients must use the following guidelines when handling values in the WorkflowType array:

  • If no supported values are provided, the WOPI client must behave as though the WorkflowType property was not provided.
  • If multiple values are provided and the WOPI client does not support multiple values, the client may use the first supported value provided in the array or behave as though the WorkflowType property was not provided.
WorkflowUrl

Pre-release property - not yet used by any WOPI client

A URI to a location that allows the user to participate in a workflow for the file.

Important

This value will be ignored if WorkflowType is not provided.

Deprecated properties

The following properties are deprecated and should no longer be used by WOPI clients or servers.

BreadcrumbDocUrl

Deprecated since version 2014.06.01.

EditingCannotSave

Deprecated since version 2014.06.01.

HostName

Deprecated since version 2016.01.12.

PrivacyUrl

Deprecated since version 2015.06.01.

SupportsCoauth

Deprecated since version 2016.01.27.

TermsOfUseUrl

Deprecated since version 2015.06.01.