How to Control Document File Visibility in the Default Theme

A how-to guide for using licenses to control the visibility of documentation files in the Community Manager developer portal.

Table of Contents

• Overview
• Step 1 - Download ZIP file with samples
• Step 2 - Update sample files with correct values
• Step 3 - Upload documentation files
• Step 4 - Create and upload a metadata.xml file
• Step 5 - Test it out

Overview

This article describes how to use licenses to control the visibility of documentation files in the default theme. This is typically used in conjunction with content visibility controls to provide a comprehensive solution. This article provides a simple set of instructions to get you started.

For a comprehensive guide to the documentation visibility controls, refer to API Documentation Tagging.

A common scenario is that you have a set of documents for an API with an overview doc, and one document for each API operation. The documentation for some of the API operations should only be visible to users with an Admin license, while the rest should be visible to all users. All of the docs also contain a content element (for example, a footer) with links to each of the other docs. This article describes how you can use the metadata.xml file to control which files a user will be allowed to see (which also controls what will show up in the default theme API documentation table of contents). You will need to use these instructions along with content visibility controls to hide links to these protected files and other sensitive content from within the documents.

This article assumes that you have completed the steps in the simple license setup article.

Step 1 - Download ZIP file with samples

For this example, download the sample_docs.zip file with sample API documentation files, to a location where you can work on the files.

Step 2 - Update sample files with correct values

You'll have to update certain values in the sample files so that they'll work in a current example. Update one or more of the following:

1. The API Version ID for your API. In the code for each operation, update this line (see example below):

    <soa:showforscope scopeNames="ScopeName" apiVersionId="Your-API-Version-ID">

2. Optional: the scope name, if you are using a different scope name, not the one used in the example. The example uses a scope name of Admin. If needed, update the same line as above, in all files.
3. Optional: the license name, if you are using a different license name, not the one used in the example. The example uses license names of Admin and User.

   To update the license name, open the metadata.xml file and update this line:

   <license name="Your-Licence-Name"/>

Updating the code for the operation: example

The example below assigns the Admin scope to the Add, Update, and Delete operations in the specified API version. In this scenario you'd need to, at minimum, update the apiVersionId value to your own API Version ID.

<soa:showforscope scopeNames="Admin" apiVersionId="56305d25-dd23-4c84-8ba6-bd2080e99bec.acmepaymentscorp">
  <div class="soa-ui-cm-dynamic-docs">
    <li><a href="addPet.htm">Add Pet</a></li>
    <li><a href="updatePet.htm">Update Pet</a></li>
    <li><a href="deletePet.htm">Delete Pet</a></li>
  </div>
</soa:showforscope>

Step 3 - Upload documentation files

In our example we have an API with 5 operations, 2 of which are scoped for end users and 3 are scoped to admins. There are separate documents for each of the 5 operations, plus an overview document.

1. Click the Documents left nav for your API.
2. Access the File Manager by clicking on the tool that appears to the left under the page title.

   

3. Either upload the zip archive, or upload the files individually (there are different buttons for each option).
4. Use the actions tools to set display names for each document, and check the Show in TOC box so that the documents will appear in the table of contents.

Step 4 - Create (or update if needed) and upload the metadata.xml file

The sample ZIP file includes a metadata.xml file to specify access rules for the uploaded documents. The following example provides simple controls for the sample documents. If you're using a different API, create a file that's correct for your API.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<metadataconfig xmlns="http://soa.com/xsd/metadataconfig/1.0">
	<!-- When API use Licenses then by default all files are restricted.
		Hence all unrestricted entries should be added to metadata.xml and assignd a public license.
	-->
	<metadata>
		<target>documents/overview.htm</target>
		<licenses>
			<license name="User"/>
		</licenses>
	</metadata>
	<metadata>
		<target>documents/findPetById.htm</target>
		<licenses>
			<license name="User"/>
		</licenses>
	</metadata>
	<metadata>
		<target>documents/findPetByTag.htm</target>
		<licenses>
			<license name="User"/>
		</licenses>
	<metadata>
		<target>documents/addPet.htm</target>
		<licenses>
			<license name="Admin"/>
		</licenses>
	</metadata>
	<metadata>
		<target>documents/updatePet.htm</target>
		<licenses>
			<license name="Admin"/>
		</licenses>
	</metadata>
	<metadata>
		<target>documents/deletePet.htm</target>
		<licenses>
			<license name="Admin"/>
		</licenses>
	</metadata>
</metadataconfig>

In this example, each entry defines a target by file name, and specifies the list of licenses that will grant access to this document. So, for example, to access the updatePet.htm file, a user must be in a group that has the Admin license assigned.

There are a lot of different ways of specifying targets and rules. For a comprehensive description, please see the Community Manager Document Tagging Guide.

Once you have updated the metadata.xml file if needed, upload it to the API's documentation folder using the File Manager as described above.

Step 5 - Test it out

Now you should have appropriate controls in place to be able to view some of the documents as an anonymous user, and you should need to be logged in as a user who is a member of your Admin group to see the other docs.

• Log out of the system.
• Find your API and click Documents.
• Verify that you see only the unrestricted documents in the table of contents.
• If you are using the sample docs, you should see a block of links to other docs at the bottom, try and click on one of the docs that are available only to users with the Admin license (for example, addPet.htm) - verify that you get an unauthorized error.

Note: the default set of documents include internal element tags that will likely hide the protected file links from you. You can always remove the tags described in How to Control Document Content Visibility, to ensure that your access controls are working correctly.

With anonymous access working, you can now verify that a user in your Admin group has appropriate access:

1. Log in as a user who is a member of the Admin group.
2. Note: this user should not be a Site Admin or Business Admin, because these roles override any license restrictions.
3. Find your API and click Documents.
4. Verify that you see all the documents in the table of contents.
5. Verify that you can view any of these documents both from table of contents links and the links in the files themselves (assuming you are using the sample docs).