Tips on Documents Cloud URL Parameters: Part II

In the first post on this topic we covered some of the ways you can use and understand the Oracle Documents Cloud URL structure. Since that post, an update to DOCS has added some great new features, especially for embedding a folder of file. More granular control over the user interface is possible through URL parameters. In addition, the REST API has public link abilities now which enriches the possibilities of client side apps interacting with DOCS. The structure of the public link URLs is straightforward, and we will show how to use a public link to do a direct download of a file (rather than open the DOCS web interface).

 

Public Links

The DOCS public links REST API is available now. One of the first questions fielded on this API asked, “Where is the public link in the JSON response?”  Notice that upon creation of a public link that the response doesn’t have the full URL in the response.

{
    "assignedUsers": "@everybody",
    "createdTime": "2015-06-10T16:01:44Z",
    "errorCode": "0",
    "expirationTime": "2016-01-01T00:00:01Z",
    "id": "FBE1117A270E747BB1D95024T0000000000100000001",
    "lastModifiedTime": "2015-06-10T16:01:44Z",
    "linkID": "LF906748A021ACD714CABC82T0000000000100000001",
    "linkName": "MyLinkOne",
    "ownedBy": {
        "displayName": "User AA",
        "id": "U0EAA20910FAF3052ACB79E4T00000000001",
        "type": "user"
    },
    "role": "contributor",
    "type": "publiclink"
}

But this “missing” URL actually reduces the size of the response and allows the calling client to react and use the data in an appropriate manner for the context. For example, the public link response can be used in different ways. Typically, the public link will be used to open up the DOCS web interface. So what is the URL format for the web public link? Here are the formats for folder, file, and file direct download.

Public link to a folder

Creating a public link to a folder has been around since the inception of DOCS, so this is likely the most familiar public link. The host name of DOCS is already known (since you’ve successfully made a REST call to DOCS to create the public link) and thus putting together the URL only requires two pieces of the JSON response: linkID, and id. Note that id can represent a folder or a file, but it’s easy to tell them apart because a folder id starts with ‘F’ and a file id starts with a ‘D’ (as in document).

The format for all public links only requires these two parts of the JSON response.
https://mydocshost/documents/link/{linkID}/folder/{id}

Example: /documents/link/LFA634B6996F78EB758C14E915BE5DEA38AC513C7430/folder/F0AF7C0FFA4D23F7509C524715BE5DEA38AC513C7430

Public link to a file

A public link to a file is almost identical to the folder, except that the word “folder” is changed to “fileview”. This will open the file in the DOCS file viewer.
https://mydocshost/documents/link/{linkID}/fileview/{id}

Example: /documents/link/LD3DB1208053E644D517B25315BE5DEA38AC513C7430/fileview/D59AD1F507B1B167ABF5D59315BE5DEA38AC513C7430

 

Public link to a file – direct download

Another question that has come up from customers is, “How can I automatically prompt the user to download a file instead of view the file?” This requires just a small tweak of the URL, changing “fileview” to “file”. The URL below will prompt the user to open or save the file. This can be useful when the recipient of the public link URL doesn’t need to see the DOCS interface at all, but rather is expected to download and open the file using the native application, such as a Word file, or a zip file which isn’t viewable. Often delivering a direct download link matches the usage better than the file viewer.

https://<host>/mydocshost/link/{linkID}/file/{id}

Example: /documents/link/LD3DB1208053E644D517B25315BE5DEA38AC513C7430/file/D59AD1F507B1B167ABF5D59315BE5DEA38AC513C7430

 

Emebedded URL parameters

 

Two powerful parameters have been added to DOCS that allow what is displayed in the interface. The parameters are cfg, for folder browsing configuration, and vcf, for the file viewer configuration. These parameters contain many toggle switches for showing and hiding options for the user. Note that these are parameters used in embedded mode, meaning for public links, file picker, or AppLink integrations. See this link for reminders on how to embed the DOCS interface. Here’s a super short primer on embedding a DOCS folder. The word ’embed’ just needs to be added to the URL.

Not embedded: https://mydocshost/documents/home/nameasc
Embedded: https://mydocshost/documents/embed/home/nameasc

And surely you recall from the first post on this topic that “nameasc” means “sort by name, ascending”.

 

Browse Configuration: cfg

The cfg parameter can take multiple values in a comma-separated list. For example, if you want to hide the upload and the breakout button for a public link set with a contributor rights, you can set cfg=nup,hbr.

So for example, if I have a public link that is set to contributor rights but need to deliver it to a user who we want to be able to delete files but not upload them, we would add cfg=nup. If we also want to disable the breakout icon, the hbr value can also be added.

/documents/embed/link/{LinkID}/folder/{id}/cfg=hbr,nup

The full list of values and the usage are shown in the table below.

 

Value Description
sfo Show Folders Only
sdo Show Documents Only. Allow selection of documents (files) only. When in this mode, the folders are shown only for the purposes of navigating into a folder so that you can find a file.
ssl Allow single selection only. (No, it’s not Secure Sockets Layer!)
evw Embed file viewer. When not specified, the file view will appear in a top-level window.
hbr Hide the Breakout button
hhd Hide the Header
hdc Hide the Open Oracle Documents Cloud button
hnw Hide the New Button
nca No Context Actions. When present, no context actions will appear in the toolbar or menu when an item is selected.
nvw No View Action. If present, documents cannot be opened in the viewer.
nop No Open Action. If present, folders cannot be opened.
nup No upload. If present, there will be no upload capability. The upload buttons and links are hidden.
nmv No Move Action
ncp No Copy Action
nsh No Share. If present, the share button is hidden.
npr No Properties
ndl No Delete Action
ndw No Download Action. Removes the ability to download in all areas of the product including the Viewer even if the Viewer Configuration (vcf) option ndl has not been set.

 

Viewer Configuration: vcf

Like the cfg parameter, the vcf parameters can take multiple values. The vcf parameter can hide or show functionality on the DOCS viewer. Various controls may need to be hidden depending on the user context of where the embedded interface is presented.

An example of using a public link to a file is below. The vcf parameter has ndl set to disallow downloads of the file, and hbc to hide the breadcrumbs.

/documents/embed/link/{LinkID}/fileview/{id}/vcf=ndl,hbc

The full list of values and the usage are shown in the table below.

Value Description
hfp Hide fit-to-page control.
hfw Hide fit-to-width control.
hzc Hide zoom controls. This includes the zoom out, zoom in, and zoom slider controls.
hzs Hide the zoom slider. IF hzc is specified, this setting is redundant.
nup No upload button will be shown.
ndl No download button will be shown.
htn Hide the thumbnails of each page in the file.
hfv Hide the favorite indicator button.
hnm Hide the name of the file.
hbc Hide the breadcrumbs.
sfp Start in fit-to-page mode. This is the default setting. Only one of sfp, sfw, or sos should be specified.
sfw Start in fit-to-width mode. Only one of sfp, sfw, or sos should be specified.
sos Start in original size mode. Only one of sfp, sfw, or sos should be specified.
stc Start with the thumbnail pane collapsed.
vhc Video controls should be hidden.
vap Video should auto play when the page loads
vlp Video should loop when it finishes playing.
vmt Video should be muted.

 

 

These URL configuration parameters enable more integration capabilities of how public links or AppLinks are used. The context of the embedded URL usage can be controlled with more focus on the user experience. The addition of the public link REST API and the URL parameters allow Oracle customers to incorporate DOCS into more places with a refined interface.

 

Comments

  1. Clive Winger says:

    I’m trying to use Applink to view files in embed mode. I am able to display files in an iframe. When the file is displayed in the iframe basically the only option the user has is download, as I have given the role of downloader. I want them to also have some other options like being able to collaborate. I tried a role of contributor but I get an error saying invalid sharing role. I assumed that role would give me more options and then I could use the configuration values to hide the options I didn’t want them to have access to. How do I display the file in an embed view and get more options in the view similar to doing embed mode directly to the fileid?

    • Clive Winger says:

      Update on this. I can create the applink using role of contributor. My issue was having Contributor (upper case C). My overall issue still seems to be there though. I do I display the file and get more options?

  2. Clive Winger says:

    I was trying to do an AppLink to a file, and I can’t get it to work?
    I have tried various ways, but what I was thinking should work is one of the following. But the page never loads the document.

    https://mydocshost/documents/link/app/{ApplinkID}/fileview/{id}?dAppLinkAccessToken={AccessToken}
    or
    https://mydocshost/documents/link/app/{ApplinkID}/fileview/{id}/FileName.pdf?dAppLinkAccessToken={AccessToken}

    I use the following to do a download and that works correctly:
    https://mydocshost/documents/link/app/{ApplinkID}/file/{id}/FileName.pdf?dAppLinkAccessToken={AccessToken}

    I also tried doing similar things above with embed with no success. Any help will be appreciated.

  3. Jonathan Hult says:

    A refresh for new parameters (such as lyt=compact) would be great.

  4. Hi Peter,

    Thanks for this and the previous post. Good overview of the possibilities and trics to use it.
    The direct public download is very usefull if you send a public link to a non oracle documents user who will maybe try to open the link on his mobile. The current browserbased GUI is not responsive and gives a bad user experience when used on a mobile phone. I was looking for a solution and this direct download is perfect. My question is where I can find possible other options for the formatting of the URL?

    Further i have an own blog dedicated on Oracle Documents in Dutch. Do you mind if a make an entry with a link to this post and do some translation?

    Ise

    • There is an app for mobile use of DOCS for android and iOS. Try using those for the mobile user experience instead of the browser.

      Yes, please feel free to link and translate!

      What other URL tips are you seeking? Any specific areas or usages?

Add Your Comment