Skip to content

Set up Office Round Trip Experience

Microsoft Office Round Trip Experience is a feature included in Domino REST API that simplifies editing of a supported Microsoft Office file attached to a Domino document. The feature enables you to access, edit, and save the changes to the attached file using the applicable Microsoft Office application without having to download and re-attach the file to the Domino document.

About this task

The procedure guides you on how to setup and use the Microsoft Office Round Trip Experience feature included in Domino REST API.

Prerequisite

  • Make sure your computer has Microsoft Office installed or can access Office 365.
  • You must run your Domino REST API in HTTPs.

Procedures

  1. Add a Microsoft Office file as an attachment to a Domino document.

    Tip

    You can use the POST /attachments/{unid} endpoint in the OpenAPI UI to add the file as attachment.

  2. Create a link to access the attached file. You can do this by either:

    • Manually creating the link to access the attached file using the following format.

      <scheme name>:<command name>|u|<DRAPI HTTPs hostname>/api/webdav-v1/attachment/<dataSource>/<document UNID>/<filename>
      Property Description
      scheme name Scheme name of Microsoft Office application

      When Microsoft Office is installed, each scheme name is registered with the operating system to be handled by the Office product of the same name. Below is a list of scheme names:

      ms-word
      ms-powerpoint
      ms-excel
      ms-visio
      ms-access
      command name Describes the action that the application should perform.

      ofv - to view the file attachment
      ofe - to edit the file attachment
      DRAPI HTTPs hostname Domino REST API HTTPS hostname
      dataSource Domino database where your current document is uploaded or attached.
      document UNID Universal ID of the Domino document.
      filename Filename of the Microsoft Office file attached to the Domino document.

      Example link:
      ms-word:ofv|u|whitepalace.keepproject.io:8880/api/webdav-v1/attachment/attachmentdb/2D88CDF9549379C700258A9F002797CA/sample.docx

      Info

      The link format is based on the Office URI Schemes.

    OR

    • Using the GET /attachmentnames/{unid} endpoint to retrieve URLs to access the attached files.

      Important

      Make sure to set the value of the includeProtocolUrl query parameter to true to include the attachment URLs in the query response.

      The query response shows the filenames of the attachments and the URLs of the attachments with supported file extensions. There are two URLs for each attachment, one for viewing as indicated by the ofv command name and one for editing as indicated by the ofe command name included in the URLs. Attachments with unsupported file extensions will have no URLs.

      The query response example below shows the attachment file named document.docx has two URLs, as the file extension .docx is supported. However, no URLs are available for the attachment file named sample.png as the file extension .png isn't yet supported.

      {
"Files": [
    {
    "filename": "document.docx",
    "urls": [
        "ms-word:ofv|u|http://localhost:8880/api/webdav-v1/attachment/dataSource/documentUNID/document.docx",
        "ms-word:ofe|u|http://localhost:8880/api/webdav-v1/attachment/dataSource/documentUNID/document.docx"
            ]
    },
    {
    "filename": "sample.png",
    "urls": []
    }
        ]
}

To access and edit the MS Office file attachment

  1. Open the created link to the MS Office file attachment in a web browser.

  2. In the Open MS Office application dialog, click Open.

    The following image shows an example of the Open Microsoft Word dialog when trying to open a Microsoft Word attachment.

    Open MS Office application

  3. In the login dialog, enter your Domino REST API login credentials and click Login.

    Login dialog

    Info

    The authentication is based on the Office Forms Based Authentication (OFBA) protocol. This is necessary since browsers and office applications don't currently support cookie and header sharing.

    Note

    You might see a different login dialogue with less functionality for OFBA when doing this on Windows. This is because some Microsoft applications in Windows still use Internet Explorer, and a lot of the functionalities we use in the original login dialogue is unsupported in it.

    The MS Office file attachment is now opened in the applicable MS Office application. In the following image, you see an opened MS Word document as an example.

    Example of opened Microsoft Word attachment

  4. Edit the attachment.

    Note

    Editing is only possible if the specified command name in the created link is ofe.

    As an example, the content of the opened MS Word document is changed from Nothing to see here to Hello Sprint playback 114!!.

  5. Save your changes, and close the MS Office application. You have now edited the attachment without downloading it and reattaching it again to the Domino document.

To verify your updates to the MS Office file attachment

  1. Open the created link to the MS Office file attachment that you have edited in a web browser.
  2. In the Open MS Office application dialog, click Open.

  3. In the login dialog, enter your Domino REST API login credentials and click Login. The MS Office file attachment is now opened in applicable MS Office application and you can verify the updates that you have made.

    As an example, the following image shows that the content of the edited Microsoft Word attachment has been updated.

    Example of edited content

Additional information

For more information on MS Office file extensions recognized by Office Forms Based Authentication, see Extensions used to open Microsoft Office in OFBA.