Office Online Integration Documentation, Release 2016.01.27
1.18.1 Indicating that a user is a business user
The first requirement in order to support document editing for business users is to indicate that the user is a business
user. Doing this requires the following:
1. Set theBUSINESS_USER placeholder value on the Office Online action URL. This parameter must always be
on the action URL for business users.
2. Include theLicenseCheckForEditIsEnabledproperty in theCheckFileInforesponse. This property must always
be set to true for business users.
3. Include theHostEditUrlin theCheckFileInforesponse. This property must be included in theCheckFileInfo
response for business users. TheHostEditUrlis used to redirect the user back to the host edit page after the
subscriptioncheck is completed.
4. (Optional) You may also optionally include theDownloadUrlin theCheckFileInforesponse. If provided, the
DownloadUrlisusedtoprovideadirectdownloadlinktothefileiftheuser’ssubscriptioncheckfails.
Important: For security purposes, both of these URLs must be served from domains that are on theRedirect
domain allow list. IfeitheroftheURLsisnotontheredirectdomainallowlist,theflowabortsandtheuseris
directed to Office.com.
Important: If any of the properties above are not set properly, or ifthe URL values provided are not on theRedirect
domain allow list,thenthelicensecheckflowwillfail.Iftheflowfails,userswillberedirectedtoOffice.com.
1.18.2 Validating edit capabilities
When Office Online is loaded for business users, it will check that the user is signed in with an Office 365 business
account. If the user is not signed in,they’ll be prompted to sign in.
Once signed in, Office Online will verify that the user has a valid Office 365 subscription. After this is verified,Office
Online will redirect the userback to theHostEditUrland the user canedit documents.
1.18.3 Tracking users’ subscription status
In the flow described above,theuser mustalways be signedin witha validOffice 365business accountin order to edit
documents. This is not an ideal experience since it might require the user to sign in many times.
To provide a better experience for users with Office 365 subscriptions, hosts can implement thePutUserInfo WOPI
operation. Office Online will use this operation to pass back user information, including subscription status, to the
host. The host can,in turn,pass the UserInfo string back to Office Online on subsequentCheckFileInforesponses for
that user. Office Online will use the data in the UserInfo string to determine whether a subscription check is needed,
andinmostcases will not requirethe user to sign in. Notethathosts musttreat the UserInfostring as an opaquestring.
Important: Hosts must treat the UserInfo string as an opaque string.
This approach helps ensure that users are required to sign in to validate their Office 365 subscription as infrequently
as possible.
1.18. Supporting document editing for business users
57
Pdf email link - insert, remove PDF links in C#.net, ASP.NET, MVC, Ajax, WinForms, WPF
Free C# example code is offered for users to edit PDF document hyperlink (url), like inserting and deleting
adding hyperlinks to pdf files; adding an email link to a pdf
Pdf email link - VB.NET PDF url edit library: insert, remove PDF links in vb.net, ASP.NET, MVC, Ajax, WinForms, WPF
Help to Insert a Hyperlink to Specified PDF Document Page
add hyperlink to pdf in; adding a link to a pdf in preview
Office Online Integration Documentation, Release 2016.01.27
1.18.4 Testing the business user flow
Attention: Sorry, this documentation hasn’t been written yet. You can track the status ofissue#118 through our
public GitHub issue tracker.
1.19 Editing binary document formats
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 theTestenvironmentonly.
Office Online does not support editing files in binary formats such as doc, ppt, and xls, directly. However, Office
Online can convert documents in those formats to modernformats like docx, pptx,andxlsx, sothatusers can then
edit them in Office Online.
Important: Conversion is almost always a lossless process, and there are typically very few, if any, user-visible
changes to the layout and formatting of the document during conversion. However, this is not always the case, and
hosts should be aware that users may wish to revert back to the previous binary version of the document after it has
been converted.
The conversion capability is exposed in WOPI discovery as theconvert action. In order to support editing binary
file formats, hosts must support thePutRelativeFile WOPI operation. The conversion process is started by simply
invoking theconvert action on the binary file. The high level process is as follows:
1. The host invokes theconvert action on a binary file.
2. Office Online will retrieve the file fromthe host and convert it.
3. Office Online will sendthe converteddocument back tothe host by issuing aPutRelativeFilerequest against the
original file ID.
4. Hosts can use the X-WOPI-FileConversionheader onthePutRelativeFilerequestto determine that the request
is being made in the context of a file conversion. Hosts can thus treat these requests differently than other
PutRelativeFile requests.
5. Afterthe document is successfullyconverted, Office Online will redirect the userto theHostEditUrlreturned in
the PutRelativeFile response.
1.19.1 Enabling ‘convert and edit’ from within the Office Online viewer
In the basic conversion flow described above, a user will invoke theconvert action using some UI on the host.
However, hosts may wish to open a document first in the Office Online viewerand use Office Online’s in-application
Edit button to convert and edit the document, as is done with documents in editable formats.
Hosts can support this in the same way that view -> edit transitions are typically supported. Hosts must do the
following when opening binary documents using theview action:
1. Set theUserCanWriteproperty to true.
2. Set theUserCanNotWriteRelativeproperty to false (or simply omit it).
3. Set theHostEditUrlproperty to a host URL that will invoke theconvert action when loaded.
58
Chapter 1. How to read this documentation
RasterEdge.com General FAQs for Products
copy and email the secure download link to the assistance, please contact us via email (support@rasteredge & profession imaging controls, PDF document, image to
convert doc to pdf with hyperlinks; add hyperlink to pdf in preview
RasterEdge Product Licensing Discount
s). After confirming the informations provided, we will send you an email that contains price(s) at a discount and the online order link for new licensing.
add hyperlinks to pdf online; clickable pdf links
Office Online Integration Documentation, Release 2016.01.27
Following these steps will ensure that the in-application Edit button is displayed. When clicked, this button will
navigate the user to the HostEditUrl provided for the binary file, which will in turn begin the conversion process and
eventually redirect the user to the HostEditUrl forthe newly converted document.
Hosts may optionally handle the in-application Edit button themselves by setting theEditModePostMessageproperty
to true and handling theUI_Edit PostMessage.
1.19.2 Customizing the conversion process
In the basic conversion process,Office Online will create a new file each time a user attempts to edit a file in a binary
file format. For example,considerthis scenario:
1. A user opens a binary file named File.doc in the Office Online viewer.
2. The user clicks the Edit button in the Office Online viewer.
3. The conversion process is started,andOffice Online callsPutRelativeFileonthehost, creatinga newlyconverted
file, File.docx.
4. The user edits the newly converted document, then ends the editing session.
5. Later,the userreturns and opens the original binary file,File.doc, in the Office Online viewer.
Atthis point, the user maybe confusedas towhy the changes made earlierare not in the document. Ifthe userattempts
toedit the file again,Office Online willagain convert it and createa second converted file,forexample File1.docx.
This can be very confusing for users depending on how the userexperience within the host UI is designed. Thus,it is
importantto considerhow to manage userconfusionaround converteddocuments. There are threebasiccustomization
options that hosts can employ to help manage this.
First, the host can choose to display some UI to the user prior to beginning the conversion process. Because hosts
ultimately control when theconvert action is invoked, a host could choose to display a notification message when
auser attempts to edit a binary document, informing them that the document will be converted. This can also apply
to the in-application Edit button by setting theEditModePostMessageproperty to true and handling theUI_Edit
PostMessage.
Second,thehostcan choosetohandle converteddocuments ina unique way,by handling thePutRelativeFileoperation
differently whencalled fromtheconversion flow. The X-WOPI-FileConversionheadertells hosts when the operation
is being called fromthe conversion flow, so the host can choose how best to handle those requests.
Finally, the host can control where the user is navigated after conversion is complete. Office Online navigates to the
HostEditUrlthatisreturnedinthePutRelativeFileresponse,whichthehostcontrols.Thus,hostscancustomizewhere
the userlands after the conversionis finished. This allows hosts to opt not tosend the userdirectlyto the Office Online
editor, but to any URL they wish. For example, a host may redirect the user to an interstitial page that informs them
their document has been converted.
The following are some examples illustrating how these options can be used by hosts to change the user experience
around file conversion. Note that these examples are not meant to be exhaustive,and that hosts may opt to customize
the conversion process and flow in ways not described here.
Example 1
In the following example, the host helps the user understand the conversionprocess by naming the convertedfile such
that it is clearthat it was converted froma binary file.
1. A user selects a binary file in the host UI and chooses to edit it using Office Online.
2. The conversion process is started, and Office Online callsPutRelativeFilewith the converted document content.
1.19. Editing binary document formats
59
RasterEdge Product Renewal and Update
4. Order email. Our support team will send you the purchase link. HTML5 Viewer for .NET; XDoc.Windows Viewer for .NET; XDoc.Converter for .NET; XDoc.PDF for .NET;
adding hyperlinks to pdf documents; pdf hyperlinks
VB.NET Create PDF from PowerPoint Library to convert pptx, ppt to
Link: Edit URL. Bookmark: Edit Bookmark. Metadata: Edit, Delete Metadata. Form Process. Create PDF file from PowerPoint free online without email.
add links to pdf in preview; pdf hyperlink
Office Online Integration Documentation, Release 2016.01.27
3. The host creates a new file as part of the PutRelativeFile request and appends (Editable) to the name of the
file.
4. The user is navigated to a page that allows them to edit the newly converted file in Office Online.
Example 2
In the following example,the host wishes to hide the conversion process from the user to provide the most frictionless
experience possible.
1. A user selects a binary file in the host UI and chooses to edit it using Office Online.
2. The conversion process is started, and Office Online callsPutRelativeFilewith the converted document content.
3. Rather than create a new file, the host chooses to add the converted file as a new version to the existing binary
file.
4. The user is navigated to a page that allows them to edit the newly converted file in Office Online.
5. The user can restore the binary version ofthe file by using the ‘version history’ features within the host.
Note: This approach may not be feasible for all hosts, depending on how file metadata and versions are handled
within their system. However,it does offerthe following benefits:
• The user only ever sees a single document both before and after the document is converted.
• Since there is always only a single document, the user always finds the ‘right’ document. That is, if the user
editedthefile -whichis likely since theyinvoked theconversion process byattempting to edita binary document
-then when they open the file a second time, their previous edits will be there, just as they expect.
Example 3
In the following example,the hosthas deemedit important to informusers explicitly about the conversion process and
its possible side effects.
1. A user selects a binary file in the host UI and chooses to edit it using Office Online.
2. The host displays a notification message with the following text:
In order to edit File.doc, it must be converted to a modern file format. If the document doesn’t look
the same after it’s converted, don’t worry- you canalways getback to the original file if you need to.
The user can cancel the conversion operation or choose to continue with it.
3. Ifthe userchooses to continue, the host navigates them to a page that invokes theconvert action on the file.
4. The conversion process is started, and Office Online callsPutRelativeFilewith the converted document content.
5. The host returns a special URL in theHostEditUrlproperty in the PutRelativeFile response. Office Online
navigates the userto that URL once the conversion is complete.
6. The user lands on the URL specified by the host, and sees the following message:
Your file, File.doc, has been converted to a new file, File.docx. The new file is in a modern file
format, and the file extension has changed. If you don’t need the original file any more, you can
delete it.
The message includes a button that the user can use to delete the original file immediately if they wish.
7. Once the user clicks OK, they’re navigated to a page that invokes theedit action on the converted file.
60
Chapter 1. How to read this documentation
VB.NET Create PDF from Word Library to convert docx, doc to PDF in
Link: Edit URL. Bookmark: Edit Bookmark. Metadata: Edit, Delete Metadata. Form Process. Free online Word to PDF converter without email.
pdf link open in new window; adding links to pdf
VB.NET Create PDF from Excel Library to convert xlsx, xls to PDF
Link: Edit URL. Bookmark: Edit Bookmark. Metadata: Edit, Delete Metadata. Form Process. Convert Excel to PDF document free online without email.
add hyperlink in pdf; add hyperlink pdf
Office Online Integration Documentation, Release 2016.01.27
Figure 1.14: Example conversionnotification message
Figure 1.15: Example conversion completed message
1.19. Editing binary document formats
61
VB.NET PDF Convert to Word SDK: Convert PDF to Word library in vb.
Create editable Word file online without email. Supports transfer from password protected PDF. VB.NET class source code for .NET framework.
pdf edit hyperlink; change link in pdf file
C# PDF Convert to Word SDK: Convert PDF to Word library in C#.net
and .docx. Create editable Word file online without email. Password protected PDF file can be printed to Word for mail merge. C# source
check links in pdf; pdf link to email
Office Online Integration Documentation, Release 2016.01.27
Variant 3.1: Display post-conversion message in the Office Online UI
In steps 5and 6, rather than navigating the usertoan interstitial page,the host may choose toappend some parameters
to the standard HostEditUrl. Then, when that HostEditUrl is navigated to, the host page can use the parameters that
were added to the URL to determine that the dialog described in step 6 should be displayed. The host candisplay that
notification above the Office Online editor frame. This is similar to what hosts do when handling theUI_Sharing
PostMessage.
Tip: Hosts must ensure that they properly use theBlur_Focus andGrab_Focus messages when drawing UI
over the Office Online frame.
1.20 Verifying that requests originate from Office Online by using
proof keys
When processing WOPI requests from Office Online, you might want to verify that these requests are coming from
Office Online. To do this,youuse proof keys.
Office Online signs every WOPI request witha private key. The corresponding public key is available in the proof-key
element in the WOPI discovery XML.The signature is sent with every request in the X-WOPI-Proof and X-WOPI-
ProofOldHTTP headers.
The signature is assembled from information that is available to the WOPI host when it processes the incoming WOPI
request. To verify that a request came fromOffice Online,you must:
• Create the expected value of the proof headers.
• Use the public key provided in WOPI discovery to decrypt the proof provided in the X-WOPI-Proof header.
• Compare the expected proof to the decrypted proof. Iftheymatch, the request originated fromOffice Online.
• Ensure that the X-WOPI-TimeStamp header is no more than 20 minutes old.
Note: Requests to theFileUrlwill not be signed. 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.
Tip: TheOfficeOnlineGitHubrepositorycontains aset ofunitteststhathosts canadapt toverifyproof keyvalidation
implementations. SeeProofkeyunittestsfor more information.
1.20.1 Constructing the expected proof
To constructthe expected proof, you mustassemble a byte array consisting of the access token, the URL ofthe request
(in uppercase),and the value of the X-WOPI-TimeStamp HTTP header from the request. Each ofthese values must
be converted toa byte array. In addition,you must include the length, in bytes, ofeach ofthese values.
To convert the access token and request URL values, which are strings, to byte arrays, you must ensure the original
strings are in UTF-8 first, then convert the UTF-8 strings to byte arrays. Convert the X-WOPI-TimeStamp header to
along and then into a byte array. Do not treat it as a string.
Then, assemble the data as follows:
• 4 bytes that represent the length,in bytes, of the access_token on the request.
62
Chapter 1. How to read this documentation
C# Create PDF from Excel Library to convert xlsx, xls to PDF in C#
Export PDF from Excel with cell border or no border. Free online Excel to PDF converter without email. Quick integrate online C# source code into .NET class.
add a link to a pdf in acrobat; add links to pdf file
C# Create PDF from PowerPoint Library to convert pptx, ppt to PDF
application. Free online PowerPoint to PDF converter without email. C# source code is provided for .NET WinForms class. Evaluation
add hyperlink to pdf; add url to pdf
Office Online Integration Documentation, Release 2016.01.27
• The access_token.
• 4 bytes that represent the length, in bytes, of the full URL of the WOPI request, including any query string
parameters.
• The WOPIrequest URL in all uppercase. All query string parameters on the request URL should be included.
• 4 bytes that represent the length,in bytes, of the X-WOPI-TimeStamp value.
• The X-WOPI-TimeStamp value.
The following C# code snippet illustrates the construction ofan expected proof.
Code sample 1.10: Sample code fromProofKeyHelper.cs
62
public bool Validate(ProofKeyValidationInput testCase)
63
{
64
// Encode values from headers into byte[]
65
var accessTokenBytes = = Encoding.UTF8.GetBytes(testCase.AccessToken);
66
var hostUrlBytes = = Encoding.UTF8.GetBytes(testCase.Url.ToUpperInvariant());
67
var timeStampBytes = EncodeNumber(testCase.Timestamp);
68
69
// prepare a list that will be used to combine all those arrays together
70
List<byte> expectedProof = new List<byte>(
71
+ accessTokenBytes.Length +
72
+ hostUrlBytes.Length h +
73
+ timeStampBytes.Length);
74
75
expectedProof.AddRange(EncodeNumber(accessTokenBytes.Length));
76
expectedProof.AddRange(accessTokenBytes);
77
expectedProof.AddRange(EncodeNumber(hostUrlBytes.Length));
78
expectedProof.AddRange(hostUrlBytes);
79
expectedProof.AddRange(EncodeNumber(timeStampBytes.Length));
80
expectedProof.AddRange(timeStampBytes);
81
82
// create another byte[] from that list
83
byte[] expectedProofArray = = expectedProof.ToArray();
84
85
// validate it against current and old keys in proper combinations
86
bool validationResult =
87
TryVerification(expectedProofArray, testCase.Proof, _currentKey) ||
88
TryVerification(expectedProofArray, testCase.OldProof, _currentKey) ||
89
TryVerification(expectedProofArray, testCase.Proof, _oldKey);
90
91
// TODO:
92
// in real code you should also check that TimeStamp header is no more than 20 minutes old
93
// but because we're using predefined test cases to validate that the method works
94
// we can't do it here.
95
return validationResult;
96
}
1.20.2 Retrieving the public key
Office Online provides two different public keys as part ofthe WOPI discovery XML: the current key and the old key.
Two keys are necessary because the discovery data is meant to be cached by the host, and Office Online periodically
rotates the keys it uses to sign requests. When the keys are rotated, the current key becomes the old key, and a new
currentkeyis generated. This helps tominimizetheriskthata host does not haveupdatedkey information fromWOPI
discovery when Office Online rotates keys.
1.20. Verifying that requests originate from Office Online by using proof keys
63
Office Online Integration Documentation, Release 2016.01.27
Both keys are represented in the discovery XML in two different formats. One format is for WOPI hosts that use the
.NET framework. The otherformat can be imported in a variety of different programming languages and platforms.
Using .NET to retrieve the public key
If your application is built on the .NET framework, you should use the contents of the value and oldvalue attributes
of the proof-key element in the WOPI discovery XML. These two attributes contain the Base64-encoded public keys
that are exported by using theRSACryptoServiceProvider.ExportCspBlobmethod ofthe .NET Framework.
To import this key in your application,you must decode it from Base64 then import it by using theRSACryptoServi-
ceProvider.ImportCspBlobmethod.
Using the RSA modulus and exponent to retrieve the public key
For hosts that don’t use the .NET framework, Office Online provides the RSA modulus and exponent directly. The
modulus and exponentofthe current keyare foundin the modulus andexponentattributes ofthe proof-key element in
the WOPI discovery XML. The modulus and exponent of the old key are found in the oldmodulus and oldexponent
attributes. All fourof these values are Base64-encoded.
The steps to import these values differbased onthe language, platform, and cryptography APIthat you are using.
The following example shows how to import the public key by using the modulus and exponent in a Python program
using the PyCrypto library.
1
from base64 import b64decode
2
from Crypto.PublicKey import RSA
3
from Crypto.Util import asn1
4
5
def generate_key(modulus_b64, exp_b64):
6
mod int(b64decode(modulus_b64).encode('hex'), 16)
7
exp int(b64decode(exp_b64).encode('hex'), 16)
8
seq = asn1.DerSequence()
9
seq.append(mod)
10
seq.append(exp)
11
der = seq.encode()
12
return RSA.importKey(der)
13
14
# proof_key_attributes is from the discovery XML
15
key = generate_key(proof_key_attributes['modulus'], proof_key_attributes['exponent'])
1.20.3 Verifying the proof keys
Afteryouimport the key, you can use a verificationmethod provided by your cryptography library to verify incoming
requests were signed by Office Online. Because Office Online rotates the current and oldproof keys periodically, you
have to check three combinations of proof key values:
• The X-WOPI-Proof value using the current public key
• The X-WOPI-ProofOld value usingthe current public key
• The X-WOPI-Proof value using the old public key
If anyone ofthe values is valid, the request was signed by Office Online.
The following example shows how toverify one of these combinations in .NET.
64
Chapter 1. How to read this documentation
Office Online Integration Documentation, Release 2016.01.27
1
private static bool TryVerification(byte[] expectedProof, byte[] signedProof, byte[] publicKeyToTry, int keySize)
2
{
3
using (RSACryptoServiceProvider rsaAlg = new RSACryptoServiceProvider(keySize))
4
{
5
try
6
{
7
rsaAlg.ImportCspBlob(publicKeyToTry);
8
bool result = = rsaAlg.VerifyData(expectedProof, "SHA256", signedProof);
9
return result;
10
}
11
catch(Exception e)
12
{
13
return false;
14
}
15
}
16
}
The following example shows how toverify one of these combinations in Python using the PyCrypto library.
1
from base64 import b64decode
2
from Crypto.Hash import SHA256
3
from Crypto.Signature import PKCS1_v1_5
4
5
def try_verification(expected_proof, signed_proof, , public_key):
6
verifier = PKCS1_v1_5.new(public_key)
7
= SHA256.new(expected_proof)
8
return verifier.verify(h, signed_proof)
1.20.4 Troubleshooting proof key implementations
If you are having difficulty with your proof key verification implementation, here are some common issues that you
should investigate:
• Verify you’re converting the URL to uppercase.
• Verify you’re including any query string parameters on the URL when transforming it for the purposes of
building the expected proof value.
• Verify you’re using the same encoding for any special characters that may be in the URL.
• Verify you’re using an HTTPS URL if your WOPI endpoints are HTTPS. This is especially important if you
have SSL termination inyour network prior to yourWOPIrequesthandlers. In this case,theURL Office Online
will use tosign the requests will be HTTPS, butthe URL yourWOPIhandlers ultimatelyreceive will be HTTP.
If you simply use the incoming request URL your expected proof will not match the signature provided by
Office Online.
In addition, use theProofkeyunitteststo verify your implementation with sample data.
1.21 Considerations for security and privacy
1.21.1 Office Online and customer data
There are two classes of customer data that flow through Office Online servers: user metadata and customer content
(documents, presentations,workbooks, and notebooks).
1.21. Considerations for security and privacy
65
Office Online Integration Documentation, Release 2016.01.27
User metadata
User metadata consists of URLs,email addresses, user IDs, etc. This data lives in memory and travels back and forth
betweenOffice Online and the WOPI host through HTTPS. Office Online goes to great lengths to scrub all personally
identifying information (PII) fromits logs. This is regularly audited to ensure Office Online is compliant with several
different privacy standards (such as FedRamp in the USA).
Customer content
In the case of customer content, Office Online retrieves it from the host in orderto renderit for viewing orediting. In
the image below you can see how WOPI is used to fetch content from the host and send content changes to the host
(ContosoDrive in this case).
Figure 1.16: WOPI protocol workflow
With the exception of caching (discussed below), it is reasonable to say that customer content only lives on Office
Online servers during a usersession. That is, a usercan reasonably expect that when they end an editing session, their
content will no longer live anywhere on Office Online servers once it has been saved to the host. The key exception
here is the Office Online viewing cache.
The Office Online viewing cache
In order to optimize view performance for PowerPoint Online and Word Online, Office Online stores rendered docu-
ments in a local disk cache. This way, if more than one person wants to view a document, Office Online only has to
fetch it and render it once. It is important tonote that a complete removal of the cache would significantly degrade the
customer experience formany users and dramatically increase the cost ofrunning Office Online.
Documents in the cache are indexed using aSHA256hash that is generated based on the contents of the file (or some
other unique attribute of the file). No user information is used to index the file. On every request for a file, if the
66
Chapter 1. How to read this documentation
Documents you may be interested
Documents you may be interested