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.

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.

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.

All content listed on this page is the property of Oracle Corp. Redistribution not allowed without written permission