Operational flows for Office for iOS and Office for Android

This section outlines the implementation requirements and operational flows for user scenarios outlined in the Browsing, opening, and saving files from Office for iOS and Office for Android section.

Terminology

User

Self-explanatory

Office Client

The Office for iOS and Android app, i.e. Excel/Word/PowerPoint

Office Identity Service

The Office Identity service is a service Office for iOS and Android uses for handling user identity information. In OAuth flows, the Office Identity Service behaves as the External User Agent

Bootstrapper URL

URL which the Storage Provider hosts to allow an Office Client app with a valid OAuth 2.0 access token to retrieve a WOPI access token

Token Endpoint URL

URL which the Storage Provider hosts and uses in order to generate access or refresh tokens

Services Manager

Office-owned service which stores a Service Catalog, listing all of the available services for an app or endpoint

Storage provider

Refers to a CSPP partner who has integrated their service into Office for iOS and Android

Note

  • Any time during these flows that Office for iOS and Android tries to hit the bootstrapper and have expired or invalid OAuth credentials, Office for iOS and Android will ask the user to log in again.

  • Any time during these flows that Office for iOS and Android has a missing, invalid, or expired WOPI access token, Office for iOS and Android will attempt to get a valid WOPI access token by calling GetNewAccessToken.

Add a Place

This describes the first time a user adds your storage provider using the Add a Place in Office for iOS and Android. To correctly authenticate users, we use the following operational flow in order to connect a user’s storage provider account with their Office for iOS and Android account.

Image representation of the authentication flow for adding a place.
  1. When the Office client boots, it calls the Services Manager for a list of available services. The Services Manager returns a Service Catalog, which is an alphabetically-sorted list of available providers and places which the user can connect to.

  2. When the user clicks Add a Place in the Office for iOS and Android backstage, they see your Storage Provider listed as an available place.

  3. When the users adds the Storage Provider, the Office client makes an unauthenticated Bootstrap call.

  4. The Bootstrap response includes the Authorization URI and token issue URI. Note that the Authorization URI must be provided as part of your Onboarding information so we can add it as a trusted domain.

  5. Office for iOS and Android loads the Authorization URI in a web view which prompts the user to sign in with the service provider. Once the user finishes the sign in process, the web view reaches a redirect URI which causes it to close. The redirect URI also provides an auth code to Office for iOS and Android.

  6. Office for iOS and Android sends the auth code and token issue URI to the Office Identity Service.

  7. The Office Identity Service sends the auth code and the client secret to the Token endpoint.

  8. The Token Endpoint issues an access token and a refresh token (if available) back to the Office Identity Service.

  9. The Office Identity Service makes an authenticated Bootstrap call using the access token to retrieve the user profile information.

  10. The Office Identity Service sends the access and refresh tokens and the user profile information to Office for iOS and Android.

  11. The user has now added the Storage Provider as a place. For the operational flow on browsing, opening, and saving files, see the next sections.

Browsing and opening files

Here is the operational flow for browsing and opening files.

  1. Get the Root Container URL: Office for iOS and Android calls GetRootContainer (bootstrapper) to obtain a Root Container URL.

  2. Get the contents of the container: Office for iOS and Android calls EnumerateChildren (containers) on the Root Container. The results are a set of containers and files in the root container. If the user wants to browse to another container within the current container, Office for iOS and Android calls CheckContainerInfo on the other container to check permissions, then calls EnumerateChildren (containers) on that second container. This step is repeated as the user browses the container hierarchy, until the user selects the file they want to open.

  3. Check file permissions: Once the user selects a file, Office for iOS and Android calls CheckFileInfo on that file to verify that the user has permissions to the file.

  4. Check file lock:

    • If the earlier CheckFileInfo call returned true for SupportsGetLock, Office for iOS and Android calls GetLock. If the GetLock response is a 409 Conflict or includes an X-WOPI-Lock header, the file is locked and Office for iOS and Android does not continue opening it.

    • If the earlier CheckFileInfo call returned true for SupportsGetLock, Office for iOS and Android sends a RefreshLock request with a known invalid lock ID. If the RefreshLock response is a 409 Conflict with a lock ID in the X-WOPI-Lock response header, the file is locked and Office for iOS and Android does not continue opening it.

  5. Take a lock on the file: Office for iOS and Android calls Lock on the file, passing a lock ID it wishes to use in the X-WOPI-Lock request header. If the Lock call returns a 200 OK, the file is locked. Office for iOS and Android will use the same lock ID when making future PutFile requests.

  6. Download the file: Office for iOS and Android makes a GetFile request on the file.

Saving and closing a file

  1. Save the file: If the user has made changes to the file, Office for iOS and Android will update the file’s contents by calling PutFile. The PutFile request will include the current WOPI lock ID previously used by Office for iOS and Android to lock the file.

  2. Unlock the file: Office for iOS and Android will make an Unlock request against to unlock the file. This Unlock request will include the current WOPI lock ID previously used by Office for iOS and Android to lock the file.