SharePoint 2016: How to knowledgeably administer Adobe PDF integration

Article
1/17/2024

Introduction

Adobe integration from a SharePoint perspective can present several different experiences to the user, depending on how it is configured, including:

Whether the PDF document title link, when clicked, displays the PDF document in the PDF browser client, in an Office Online Server web view, in the installed Adobe Acrobat thick client or some combination of these.
What document options are presented and enabled on the popup that appears when the user clicks on the vertical ellipse next to a PDF document
What SharePoint-related menu options are available in the Adobe thick client if it appears after clicking on a document link in SharePoint
Whether the Adobe thick client presents an error when it appears.

There are several SharePoint settings that govern these experiences, and some of these experiences are dependent on more than one setting. This posting presents the key SharePoint settings governing these user experiences, the values you can set them to, and how these values affect the user Adobe Integration experience. It consolidates notes with regard to implementing Adobe PDF integration on a SharePoint Server 2016 on-prem enterprise farm. The discussion presented here is valid for an on-prem SharePoint Server 2016 Enterprise farm. The next section presents the key SharePoint configuration items or settings that you must administer, where they are located or accessed and the values that you can set them to. The spreadsheet-based matrix that is used in conjunction with this posting is available here.

The References section below lists articles and postings for additional reading on this topic.

Key Configuration Settings

Knowledgeably administering Adobe integration so that it presents the user experiences you want to deliver depends on several key configuration settings, including the:

Open Documents in Client Applications by Default site collection feature
SPWOPIBinding -Application "WordPDF" -Action "View" Office Online Server binding for WordPDF application
<Mapping Key ="pdf" Value="icpdf" OpenControl="" PDF control mapping configuration in DOCICON.XML
Default open behavior for browser-enabled documents setting in Document library > LIBRARY tab > Library Settings > Advanced settings
Browser File Handling setting in the web application General Settings
"application\pdf" in the web application's trusted MIME type list

Let's take a look at where each of these settings is found and how it is administered.

The Open Documents in Client Applications by Default site collection feature is found by navigating to:

[site collection] > Settings > Site Settings > Site Collection Administration > Site collection features

and either activating or de-activating the feature. The effect of activating or de-activating this feature is immediate and does not pose any adverse impacts or cleanup needs like those for example associated with activating and deactivating the Publishing feature.

The SPWOPIBinding -Application "WordPDF" -Action "View" binding is either created or removed. Though one command is used to create it, two WOPI bindings for both external and internal WOPI zones or in fact created. To create the binding, launch an elevated SharePoint Management Shell and run this command:

New-SPWOPIBinding -ServerName "[Your-OOS-Domain-Name]" -Application "WordPdf" -Action "View"

To remove this binding, run this commandlet in the elevated shell

Get-SPWOPIBinding –Application "WordPDF" -Action "View" | Remove-SPWOPIBinding -Confirm:$false

The effect of creating or removing this binding is immediate and does not require an IISRESET to have it go into affect.

The <Mapping Key = "pdf" Value = "icpdf" OpenControl = "" control mapping in the DOCICON.XML file will have two values for its OpenControl parameter. This will be set to an empty value "" or to the Adobe Acrobat control "AdobeAcrobat.OpenDocuments". This file exists on every farm web server hosting a web application, such as the web front ends. There is one file per server, and it is located by default here:

C:\Program Files\Common Files\microsoft shared\Web Server Extensions\16\TEMPLATE\XML

After editing this file, you must reset the IIS server before the new setting goes into affect.

The Default open behavior for browser-enabled documents setting is found here:

[document library] > DOCUMENTS tab on the ribbon > Library Settings > Advanced Settings > Default open behavior for browser-enabled documents.

Changing this setting impacts the user experience immediately.

The Browser File Handling setting is found in Central Administration through this path:

CA > Application Management > Web Applications > Manage web applications > [select the web application] > General Settings > General Settings > Browser File Handling

By default, this is set to Strict for new web applications. Setting this to Strict prevents the execution of untrusted file types. When this is set to Strict, you'll need to make sure that the PDF MIME type has been added to the list of Trusted MIME types, or otherwise your users will be prompted to download PDFs when they click on the PDF document titles. This setting is presumed to be set to Strict in this discussion.

The PDF MIME type must be added to the Trusted MIME Types list of each web application that you want to add Adobe integration to. It does not appear to be added to a web application's trusted MIME type list by default in SharePoint, according to the postings I have read to date and from experience. Use these commands to add it:

$webApplication = Get-SPWebApplication("[WebAppUrl]")
$webApplication.AllowedInlineDownloadedMimeTypes.Add("application/pdf")
$webApplication.Update()

The PDF MIME type is presumed to have been added for the purposes of this discussion.

These are the six key SharePoint settings that you must configure in order to knowledgeably administer the Adobe Integration experience for your SharePoint users. The next section reviews the various Adobe Integration outcomes to the user experience and presents some general observations. It also reviews the settings for two specific user experiences.

User Experiences

The four difference configuration items presented in the previous section enable (4^2 =) 16 different Adobe Integration outcomes, or experiences, for the SharePoint user. These 16 different experiences have been fully mapped and detailed and can be found here: SharePoint - Adobe Integration Settings Matrix. This is a CSV file that presents the 16 different configuration scenarios and their outcomes. Mapping out these scenarios and presenting all of there outcomes makes it easier to identify the dependencies that various outcomes may have on one or more configuration items. Through review of these outcomes, several general observations can be made:

The activation status of the Open Documents in Client Applications by Default site collection feature has no impact on any outcome.
When enabled, the Full Screen button on the PDF document's popup dialog (the one that appears when you click on the vertical ellipse next to the document title) always opens the PDF document in a new browser tab in Word Online.
When the OPEN link is displayed on the document's popup dialog, clicking it always opens the PDF document in the current browser tab in the PDF client.
The document popup will always be presented regardless of a change to any of the four settings discussed in this posting.

These experiences are consistent no matter how the settings are configured. It's important to know these because you will need to educate your users on this. Your users will likely be expecting PDF documents to always open in the PDF thin or thick client - Adobe Acrobat Reader and Adobe Acrobat - no matter what they click on to open the document. It's also important from the perspective of knowing what you can and can't control. Now let's look at a two specific outcomes that focus on what happens when the user clicks on the document title, since this is the primary method users use to open documents in a SharePoint document library.

User Experience 1: Document opens in current browser tab, in the PDF thin client

This is a common outcome, consistent with what users expect to occur when they browse the Internet or their corporate SharePoint. It does not employ Adobe Integration per se, meaning, integrating with SharePoint Check in/out, but delivers the basic Adobe Acrobat Reader experience and delivers it through the browser. To deliver this experience to your users, set the following configuration items:

The Open Documents in Client Applications site collection feature can be activated or not activated.
Remove the SPWOPIBinding –Application "WordPDF" -Action "View" binding
Remove the OpenControl parameter from the PDF key mapping so that it looks like "<Mapping Key="pdf" Value="icpdf.png" />"
The document library's default open behavior can be set to Open in browser or Open in the client application.

By removing the WOPI "View" action and removing the mapping to the Adobe control, you deliver a pure and consistent PDF browser thin client experience. Whether the user clicks on the document title itself or on the OPEN link on the document popup, the result is the same: the document opens in the current browser tab, in the PDF thin client. The Full Screen button on the document popup is not enabled.

User Experience 2: Document opens in current browser tab, in the PDF thin client, PDF thick client opens in integrated mode

This outcome is a variation on the previous one, but in addition it also presents the Adobe thick client opening in integrated mode. This outcome is useful for delivering a convenient PDF forms updating experience to your users. With just two clicks, the PDF document is checked out and opened in the thick client. The user can then edit the form in the thick client as necessary. Then with just four clicks, the user can save the modified PDF form back to the document library and check it in, optionally adding version comments - all through the PDF thick client interface. No need to interact with SharePoint directly to do this. To deliver this experience to your users, set the following configuration items:

The Open Documents in Client Applications site collection feature can be activated or not activated.
Remove the SPWOPIBinding –Application "WordPDF" -Action "View" binding
Add the OpenControl to the PDF key mapping like so: "<Mapping Key="pdf" Value="icpdf.png" OpenControl="AdobeAcrobat.OpenDocuments"/>"
Set the Library Settings - Advanced - Default open behavior to: Open in the client application.

These settings for User Experience 2 deliver the full Adobe Integration experience to your users. Don't forget to set the default open behavior to Open in the client application, or otherwise the thick client will still appear but not in integrated mode; and an Adobe error prompt will also appear. The Full Screen button on the document popup is not enabled.

Summary

There are four key configuration settings associated with knowledgeably administering the user's Adobe integration experience. These four settings result in 16 different potential outcomes for the user experience. Two of these outcomes are the ones most commonly used. The first one delivers a pure Adobe thin client experience; there is no integration between this thin client and SharePoint; and the document is opened in the PDF browser thin client in view-only mode. The second one delivers the full Adobe integration experience; the document is still opened in the PDF browser thin client in view-only mode, but in addition, the Adobe thick client is also launched and providing options to check out/in the document and save the document using UI elements within the Adobe thick client application. Reviewing all 16 potential outcomes that are possible from the four different SharePoint configuration settings helps to more quickly identify and understand how a particular setting affects the user experience. Note that the Open Documents in Client Application site collection feature activation has no impact on the Adobe user experience. This posting should be used in conjunction with the spreadsheet-based Adobe Integration Matrix available here that shows all 16 different combinations of the four settings and their outcomes on the user experience.

References

Notes

Changes made to the DOCICON.XML file of an IIS instance globally impact all web applications hosted by that instance.
Changes made to the DOCICON.XML file must be performed on each of a farm's web front end servers to ensure consistent and repeatable user experience.
To set the web application general setting Browser File Handling, go: CA > Application Management > Web Applications > Manage web applications > [select a web application] > General Settings > General Settings > Browser File Handling
To view a web application's trusted MIME types, execute the following in an elevated SharePoint management shell:
```
$webApplication = Get-SPWebApplication("[WebAppUrl]")
$webApplication.AllowedInlineDownloadedMimeTypes
```

To add a new trusted MIME type to the web application, execute the following in an elevated SharePoint management shell:

$webApplication = Get-SPWebApplication("[WebAppUrl]")
$webApplication.AllowedInlineDownloadedMimeTypes.Add("application/pdf")
$webApplication.Update()

Share via