Doc Tagging General Information:

What types of content can I use documentation tagging for?

Documentation tagging allows you to control who will see your content.

Here are two examples of types of content you can use documentation tagging for on the platform:

Site documentation. The documentation might include instructions for different user groups, such as app developers and API admins. If you don't want your app developers to see the API Admin documentation, you can apply file-based tagging. For an example, see How do I use file-based tagging to filter by user role?

API documentation. You can use doc tagging to limit parts of your API documentation for users with visibility of a specific license, scope, or even operation; you can also tag documentation to be visible to specific types of users, logged-in users, or anonymous users.

Documentation must be tagged for the appropriate licenses. If not tagged, documentation is not visible, even if the API is public. If appropriately tagged, documentation associated with public scopes is visible to all users, including anonymous users. Documentation associated with private scopes is only visible to users who have visibility to the private scopes.

Registered Users

No

Documentation is visible to all users who are logged in.

Registered Users

Yes

Documentation must be tagged for the appropriate licenses. If appropriately tagged, documentation associated with public scopes is visible to all users who are logged in. Documentation associated with private scopes is only visible to users who have visibility to the private scopes.

Private

No

Documents are visible only to API Admins, Business Admins, and users who are members of a group that has visibility of the API (API Context Group or invited independent group).

Private

Yes

API documentation mapped to a private license or scope is available only to users who have visibility of the applicable license or a license that includes the applicable scope. Visibility is based on group membership. Note that the API documentation must be tagged according to the tagging rules as explained in How do I control visibility of API documentation files? below. If an API uses licenses, whatever the visibility setting is for the API, documentation tagging must be used.

How do I control visibility of API documentation files?

If an API uses licenses, visibility of API documentation files is restricted to users who are authorized, based on their access to licenses, scopes, or operations and the way that the documentation is tagged. The platform offers a series of visibility filters that you can use to control the display of applicable API documentation files, or portions of content within individual files, to authorized users. If the API uses licenses, API documentation tagging must be used.

When API documentation is tagged appropriately, the platform displays documentation to users who are authorized, based on membership of one or more groups that have visibility of the API. Other users do not see the documentation.

Tagging your API documentation, in combination with the licenses feature, gives you a lot of flexibility regarding portions of your API that you show or hide to different audiences. From the API owner's perspective the basic process is essentially:

You determine how you want to package your API to offer it to different audiences. For example, you can:

Offer the entire API with different quality of service agreements and/or legal agreements.

Subdivide the API by using the scope mapping feature to map individual operations to specific scopes. The Business Admin must define the licenses, and the scopes that are part of them, so you'll need to coordinate with the Business Admin to make sure your scope mapping strategy results in the correct license offerings to your app developer audience.

You apply scopes to your operations and licenses to your API.

You apply tags to your API documentation as covered in the topics below.

Note: If your API uses licenses at all, you must tag your API documentation with the applicable tags so that the documentation is visible to the applicable users. Even if the API is public and the licenses are public, if you don't tag the documentation it will not be visible. At minimum, set up a metadata.xml file with one or more entries that make all your files visible to all users.

Multi-Level Privacy

In some cases, you might also apply privacy at various levels. Privacy settings allow you to restrict visibility of certain areas of your API. You can make the entire API private so that it is visible only to invited users; but you can also define licenses or scopes to be private. For example, you might have a group of new operations that need to be tested, and you want to make these available to a beta partner without exposing them to your main customer base. You can do this by defining a private scope, assigning it to a private license, and inviting your beta partner to have visibility to the private license.

Where do I apply API visibility settings?

You can limit visibility—that is, which users can see your API—by applying privacy settings at these levels:

API

You can mark the entire API as private. If the API is private, a user must be a member of an invited group or an API Context Group, or be an API Admin, in order to see the API. If an API is private but all the scopes are public, invited users can see all scopes and operations; if the scopes are private, no matter what the visibility setting is for the API, only users who are specifically invited will see the licenses that include private scopes.

License

No matter what the visibility setting is for the API, a license can be public or private. A public license is visible to those who have visibility of the API; if a license is private, specific permission is required.

Scope

No matter what the visibility setting is for the API, a scope can be public or private. A public scope is visible to all who have visibility of the API; if a scope is private, a user must be invited to have visibility of a license that includes the scope.

The table below summarizes these privacy levels.

If an API is...

And a license is...

And a scope is...

API visibility/doc visibility (if tagged) is...

Public

Public

Public

Visible to all.

Public

Public

Private

Visible to all, except private scopes by invitation only.

Public

Private

Public

Visible to all, except private licenses by invitation only.

Public

Private

Private

Visible to all, except private licenses by invitation only.

Private

Public

Public

Visible only to users who are members of an API Context Group or invited group.

What are the different ways I can tag API documentation?

There are two main ways that you can tag documentation. When you understand both, you'll be able to design a strategy that best matches your unique scenario and is most efficient for you and appropriate for your audience. You can use them in combination; the two approaches work together to give you fine control over the visibility of your API documentation.

They are:

File-based tagging

Content-based tagging

File-based tagging

File-based tagging is the recommended approach for most content. An additional file in the documents folder, metadata.xml, controls which files are accessible to which users. This file-based authorization allows you to specify which of your documentation files, or groups of files, are visible to which users based on the API version and the licenses, scopes, or operations that the user is authorized to view, or based on the user's role. For tagging of API documentation, you must set up the applicable API Version ID in the metadata.xml file to ensure that your documentation visibility settings will work.

Content-based tagging

Content-based tagging allows you to tag specific pieces of content within a file, to control who can see that piece of content. This more granular approach gives you fine control over the visibility of your content. What a viewing user sees is personalized/customized based on the user's access rights and permissions. To use this feature, you'll need to add some lines of code in the <head> tag of your file, as explained below.

This approach can get complex, so it's best to keep it to a minimum; for example, you could use content-based tagging in your main index file and file-based tagging for the rest of your files.

How does documentation tagging work?

At runtime, the platform checks the settings on the files and/or content and verifies against the access rights of the viewing user. Where there is a match, content is displayed. Any content that doesn't match the viewer's rights is not displayed to the user.

Note: A full set of linked files and setup instructions is also available, as a ZIP file that you can customize, upload, and test. To get a copy of the doc tagging ZIP file, contact Technical Support.

What is file-based doc tagging and how does it work?

File-based tagging is the recommended approach for most content. An additional file in the documents folder, metadata.xml, controls which files are accessible to which users.

In your documents directory, set up the metadata.xml file with permission settings for your API documentation files, using special tags. You can set permissions:

For individual files

For specific file types

For folders that should have restricted visibility

The settings in the metadata.xml file determine not only visibility but also authorization. If file restrictions are set up in the metadata.xml file, a user cannot access those files even if the user has the URL for the file.

What is content-based doc tagging and how does it work?

With content-based tagging, you apply special tags to specific pieces of content within a file. At runtime, visibility rules are applied to each section of content according to the tags you set up.

We recommend that you use this approach judiciously. Permissions vary by user, and documentation projects often include links between files, so a simple tagging approach is most efficient. Refer to the examples below for some ideas.

What is the recommended approach to API documentation tagging?

File-based tagging is simplest; content-based tagging can get complex, so it's best to keep it to a minimum.

The approach we recommend is to use content-based tagging in your main index file and file-based tagging for the rest of your files. This is an efficient combination that allows you to take advantage of the features of both approaches while keeping things simple and easy to maintain.

There are two key reasons to keep the design of the documentation simple:

If there are many paragraphs tagged for specific user subsets (whether by license, scope, or operation) it can get complicated to track which content is seen by which users. Particularly, you must make sure that both source and destination for any links are viewable by the same users. Otherwise, you might run into one of these issues:

Users can see a link but do not have permission to follow the link.

Users do not see a link to a piece of content that they do actually have permission to see, and therefore cannot access content that is relevant to them.

Tagging by paragraph requires more processing, since the platform must check permissions at many levels. A streamlined approach is more efficient on the processing side.

Tagging the index page

We recommend that you tag the index page with the following:

Private API: Use the InvitedUser tag to make the index page available to all users who are invited to your API.

Public API: Define at least one public scope, and then tag the index page for that scope in the metadata.xml file, so that it will be available to all users.

Note: If there are any overlapping conditions, the user must meet all the conditions for the content to be displayed to that user.

Tagging by user group

Another approach is to separate out most of your content for different user groups by file. For example, you could have one file for each license you offer; or you could have one file for each operation.

The overview page would then lead in to the various types of content. In this file, you could use the more granular level of tagging by paragraphs, so that each user sees only the links to additional files that are viewable for that user. Other links would not be seen.

Any additional content that would need to be shared by different groups would also have to be tagged at the more granular level.

My API uses licenses, but I just want my documentation to be visible to everyone. What's the easiest way to set that up?

If your API uses licenses, and you have content that you want to display to all users, tag your content as visible for a specific public license, scope, or operation. If your API is public and a license is public, content tagged for that license will be visible to all users, even anonymous users (users who have not logged in). If you do not tag the content, it is not displayed to users at all.

To implement this, you'll need to have a public license and apply it to all your operations.

Example #1: Public API using licenses, public license assigned to all operations, target documentation available to all authorized users

The example below defines a rule that all .html files in the documents folder for this API version are only visible to invited users. Note that if you have other types of files, you'll need to list those also, in an additional <target> node, as shown in Example #3.

The example below defines a rule that makes multiple documentation files for the API visible to invited users. In this example, the API documentation includes several file types. Each is listed separately in an additional <target> node.

Doc Tagging By File

How do I use the metadata.xml file for file-based tagging?

You can control the visibility of API documentation and downloadable files by creating a metadata.xml file that includes one or more regular expressions and uploading it to the /documents folder for the API (API > Documentation > File Explorer). The regular expressions specify which files can be seen, via tagging, for one or more of the following:

Note: If your API uses licenses, you must include the metadata.xml file with appropriate tagging. If you don't specify a metadata.xml file with permissions to your content, or if you include a metadata.xml file but don't add the information about your files, your users will not see your documentation, other than the properties file and any legal agreements. This includes a custom CSS file or any other assets associated with your documentation. This is always true when the API uses licenses, even if the API is public.

Sample metadata.xml file #1

The example below shows a simple metadata.xml file with one API version, 0157f427-0b07-4ae6-9ade-26f4ef3bcc71.acmepaymentscorp; one operation, addPayment; one scope, fullscope-public; and one license, Gold. There is one file within each tag.

In this scenario, users will only see the link to a specific file if they have permission to the applicable API version, scope, operation, or license. Users who do not have the applicable visibility permissions will not see the links (and would not be able to access the files even if they had the URLs).

Note: In setting up your metadata.xml file, make sure you get the names of referenced objects, such as license, scope, or file names, exactly right. Make sure the case matches.

What does an entry in the metadata.xml file look like?

Optional: an <APIVersionID> tag that limits the rule to a specific version of the API. If an API version is not specified, <metadata> tags apply to all versions of the API.

Required: a <target> node that states which files are affected by the rule. There can be multiple <target> nodes but there must be at least one.

Required: A node that specifies the visibility rules that are applied to the file. This can be one of several types of nodes; for example, limiting visibility by role, license, scope, or operation. Operations are as specified for the API; scopes and licenses are as specified by the Business Admin. There can be more than one, but they must be of the same type.

The sample file below has a single entry.

In the sample <metadata> node below, visibility is limited by role. Only users with the role of InvitedUser will see the index.html file specified in the <target> node.

How do I use file-based tagging to define the API version a file applies to?

If you have a file that includes content for a specific API version, you can apply the <APIVersionID> tag.

This tag is the primary way that the developer portal controls which API documents apply to which version. In Default Theme/Hermosa Theme, when a user chooses to view documentation for a specific API version, the platform uses the API version tag to filter visibility so that the user only sees documentation that's applicable to the specified API version.

How do I use file-based tagging to filter by license?

The <licenses> filter in the metadata.xml file allows you to specify one or more target documents and one or more license names. Users must have visibility of all specified licenses in order to have visibility of the specified documents.

How do I use file-based tagging to filter by scope?

The <scopes> filter in the metadata.xml file allows you to specify one or more target documents and one or more scope names. Users must have visibility of all specified scopes (via licenses that they have visibility of) in order to have visibility of the specified documents. In the developer portal, the API Admin maps scopes to API operations using the information set up in the Manage Licensing page, accessed via the API's Details page.

How do I use file-based tagging to filter by operation?

The <operations> filter in the metadata.xml file allows you to specify one or more target documents and one or more operation names. Users must have visibility of all specified operations (via licenses that they have visibility of, that include scopes the operations are mapped to) in order to have visibility of the specified document. The API Admin maps scopes to API operations using the information set up in the Manage Licensing page, accessed via the API's Details page.

How do I use file-based tagging to assign the same filter to more than one file type?

Within a specific <metadata> tag, you can specify multiple <target> nodes. The rules specified in the <metadata> tag are applied to all files specified in one or more <target> nodes.

In the example below, users must have visibility of all specified operations (via licenses that they have visibility of, that include scopes the operations are mapped to) in order to have visibility of either of the specified documents.

How do I use file-based tagging to filter by user role?

You can restrict visibility of a specific piece of content by specifying the entire documentation file in the metadata.xml file so that it can only be seen by users with a specific login status. The valid roles are:

InvitedUser: for a Private API, a user who has been invited to have visibility of the API and has accepted (generally via an invitation to a group that has visibility of the API)

Admin: the administrator of the referenced object. Can be the admin for an app, app version, API, API version, or group.

SiteAdmin: the administrator of the tenant that owns the resource.

SystemAdmin: used only for access root workflow.

BusinessAdmin. For objects that do not belong to a business, the tenant's business scope will be applied

In the example below, all invited users for this version of this private API will see the index.html page.

Multiple roles: visibility for either role

When using file-based tagging to restrict visibility by user role, you can also tag content for multiple roles. If the viewing user has one of the specified roles, the content is visible. An example is shown below.

How do I use file-based tagging to limit visibility of a specific file?

You can filter visibility of a specific file by specifying the filename in the <target> node. For example, you might want to define a filtering rule that applies to a specific PDF file, sample.pdf, so that it's visible only to users with a certain license. To do this you would specify the filename in the <target> node and the license in the <license> node, as shown below.

How do I use file-based tagging to filter by API version?

In addition to applying filters to all API documentation, you can further filter documentation for a specific version of the API by using the <api:APIVersionID> filter.

You configure this filter by extracting the API Version ID plus tenant name (for example, 0157f427-0b07-4ae6-9ade-26f4ef3bcc71.acmepaymentscorp) from the API documentation URL. It's the ID that's after /versions/ in the path. In the example below, it's the second ID in the path.

Doc Tagging By Content

When should I use doc tagging by content?

Setting up the metadata.xml file covers the broad strokes of your documentation tagging, defining which files are accessible to which audiences.

It's best to organize the bulk of your content using file-based tagging, so that entire files are visible or hidden based on a user's visibility settings. However, there will be at least one or two instances where you'll need to designate content within one file as being visible only to users with access to the applicable licenses, scopes, or operations. This is where doc tagging by content comes in.

For example, let's say you have two new operations in beta testing and want to make those available only to your beta testing partners. You:

Define the beta scope and license.

Assign the beta scope to your new operations.

Write the documentation for those operations.

Set up the metadata.xml file so that the beta documentation is available only to those with the beta license.

Set up your main index file with a link to the file for the new operations, tagged for the new scope or license.

The lead-in to your API documentation content will need to accommodate all possible users, with some way to branch off to private content that's accessible only to a restricted audience, as in the above example.

The content-based tagging approach lets you tag specific content within an individual file, so that individual portions of the file are visible only to specific audiences.

A common, and recommended, approach is to customize the main index page, creating a separate section for each user group (based on visibility rights). Sections of content tagged for users with specific visibility rights are invisible to unauthorized users. Each user only sees content that he/she is authorized to view, and from there can click through to other files containing authorized content.

The platform displays content by checking the permissions of the viewing user for licenses, scopes, and operations and comparing the viewer's permissions with the licenses, scopes, and operations specified in the tagged content.

Where the tags match the user's permission, the content is displayed. If a tag specifies a license, scope, or operation to which the viewer does not have access, the content is not displayed.

I want to use content-based tagging. How do I set up my file?

You can use the content-based tagging feature to show or hide sections of a specific document based on the visibility access rights of the viewing user. To use this feature you'll need to do these things:

Note: In the tags, make sure that the scope, license, or operation name is exactly the same as it is in the user interface, including case. Case differences might not be an issue, but it's best to be exact.

In the file paths, you can use whatever value you want to use in the /{resource.version}/ part of the path. For example, you could use the platform version (recommended) or your API version or API doc version.

The importance of this value is in controlling the version of the dynamic_docs.js file that is served to your users. This file is cached by the browser, for efficiency. However, if there is a new version with increased capabilities, and you use those new capabilities in a new version of your documentation, when your users are viewing the file you'll want the browser to use the new version of the dynamic_docs.js file, not an earlier, cached version.

In this scenario, all you need to do is update the value of the {resource.version} variable in the file path. Changing the value ensures that when a user accesses your documentation, the browser will reference the latest version of the file.

If you see in the release notes for a new version that there are updates to the dynamic documentation capabilities, it's best to update the value of your {resource.version} variable to make sure you and your users get the full functionality of the new features.

How do I use content-based tagging to restrict visibility by license?

To restrict visibility of certain pieces of content within a documentation file, so that the content can only be seen by users with visibility of a specific license, specify the license names in the soa:showforlicense tag.

To specify multiple licenses, separate them with commas.

If the tagged content is a link to another file, remember to also specify in the metadata.xml file that the destination file is accessible to users with visibility of the same license. If you don't, users will see the link and be able to click the link but will not have permission to view the target file.

In the documentation tag, use a <div> tag with the soa-ui-cm-dynamic-docs tag assigned to it. Refer to the examples below.

The platform automatically checks access rights, and makes the content accessible to users who have visibility of the applicable license.

Note: If you want to restrict documentation visibility by license, you must assign scopes to licenses and also assign scopes to the API.

Example 1: one license

In the example below, when an app developer has visibility of the Gold license, based on the license's privacy settings and the developer's visibility access, the developer can view the link to a separate file containing information about this license.

Example 2: tagging by license, private API, public license

In the example below, the API is private but the license (LicenseName_Public) is public. All users who have been invited to the API will see the content below. Users who have not been invited will not see the API at all, and will not be able to access the content.

Example 3: tagging by license, private API, private license

In the example below, the API is private and the license (LicenseName_Private) is also private. To see this content, users must be invited to the API but also must be invited to this specific license. Even members of groups that are invited to the API will not see the content unless specifically invited to see this license.

Remember to also specify in the metadata.xml file that the destination file is accessible to users with visibility of the same license. If you don't, users will see the link and be able to click the link but will not have permission to view the target file.

How do I use content-based tagging to restrict visibility by scope?

To restrict visibility of certain pieces of content within a documentation file, so that the content can only be seen by users with visibility of a specific scope, specify the scope names in the showforscope tag.

To specify multiple scopes, separate them with commas.

If the tagged content is a link to another file, remember to also specify in the metadata.xml file that the destination file is accessible to users with visibility of the same scope. If you don't, users will see the link and be able to click the link but will not have permission to view the target file.

The platform automatically checks access rights, and makes the content visible to users who have visibility of licenses that include the applicable scope.

Note: If you want to restrict documentation visibility by scopes, you must assign scopes to the API. To assign scopes to your API, in API > Details > from the drop-down on the right, Manage Licensing. See What is scope mapping and how do I set it up? For the most security, be sure to assign at least one scope to each operation. If an operation doesn't have a scope assigned, no specific license is needed to access that operation.

In the documentation tag, use a <div> tag with the soa-ui-cm-dynamic-docs tag assigned to it. Refer to the examples below.

Example 1: one scope

In the example below, when an app developer has visibility of the specified scope, ScopeName, the developer can view the link to the file containing information about the scope.

How do I use content-based tagging to restrict visibility by operation?

To restrict visibility of certain pieces of content within a documentation file, so that the content can only be seen by users with visibility of a specific operation, specify the operation name in the showforoperation tag.

To specify multiple operations, separate them with commas.

If the tagged content is a link to another file, remember to also specify in the metadata.xml file that the destination file is accessible to users with visibility of the same operation. If you don't, users will see the link and be able to click the link but will not have permission to view the target file.

In the documentation tag, use a <div> tag with the soa-ui-cm-dynamic-docs tag assigned to it. Refer to the examples below.

The platform automatically checks access rights, and makes the content accessible to users who have visibility of licenses that include scopes with the applicable operations.

Note: To restrict documentation visibility by operation, scopes must also be assigned to the API. To assign scopes to your API, in API > Details> Manage Licensing, check the Enable Licensing for API box, and then select either API-Wide Mapping or Operation-Specific Mapping. Assign scopes to operations and save. For the most security, be sure to assign at least one scope to each operation. If an operation doesn't have a scope assigned, no specific license is needed to access that operation.

Then, in the API documentation HTML file, configure the tags as follows, adding one or more operation names separated by commas.

How do I use content-based tagging to restrict visibility by role?

The examples below illustrate several scenarios you can use to tag documentation to be visible to users with a specific role or multiple roles.

Note: When tagging by role, if the tag references multiple roles, by default a user with just one of the roles can see the content. However, you can use the AND operator to specify that the user must have all specified roles in order to see the content, as illustrated in the examples below.

Valid role values for the roleNames parameter are:

SiteAdmin

BusinessAdmin

Admin (a user who is both API Admin and Business Admin)

ApiAdmin

You can also tag for multiple roles.

Example 1: Site Admin

In the example below, the specified file is visible only to users with the role of Site Admin.

Example 3: Admin (user must be either API Admin or Business Admin)

In the example below, the specified file is visible only to users with the Admin role. This role includes both API Admin and Business Admin. Therefore, the file is visible to users with the role of either API Admin or Business Admin.

Example 4: Site Admin or Business Admin: user must have either role

In the example below, the specified file is visible only to users with the role of either Site Admin or Business Admin. This is the same result as the example above, but is accomplished by specifying multiple roles. This approach could also be used for specifying a different combination of roles; for example, API Admin or Business Admin.

Note: When tagging by role, if multiple roles are specified, by default the content is available to users who have one of the referenced roles.

Example 7: Multiple pieces of tagged content within a file

The example below shows five pieces of content. Each type of admin (API, Business, Site) will see the one piece of content that's tagged for that role. If content is tagged for either of two roles (OR), and the user has one of the roles, the user will see it. If content is tagged for users who have both roles (AND), only users with both roles will see it.

<soa:showforrole roleNames="ApiAdmin">
<div class="soa-ui-cm-dynamic-docs">
<h3>API Admin</h3>
<p>Important information for the API Admin.</p>
</div>
</soa:showforrole>
<soa:showforrole roleNames="BusinessAdmin">
<div class="soa-ui-cm-dynamic-docs">
<h3>Business Admin</h3>
<p>Important information for the Business Admin.</p>
</div>
</soa:showforrole>
<soa:showforrole roleNames="SiteAdmin">
<div class="soa-ui-cm-dynamic-docs">
<h3>Site Admin</h3>
<p>Important information for the Site Admin.</p>
</div>
</soa:showforrole>
<soa:showforrole roleNames="SiteAdmin, BusinessAdmin" condition="and">
<div class="soa-ui-cm-dynamic-docs">
<h3>Business Admin AND Site Admin</h3>
<p>Important information for any user who is Business Admin and also a Site Admin.</p>
</div>
</soa:showforrole>
<soa:showforrole roleNames="SiteAdmin, BusinessAdmin">
<div class="soa-ui-cm-dynamic-docs">
<h3>Site Admin OR Business Admin</h3>
<p>Important information for all users who are either Business Admin or Site Admin.</p>
</div>
</soa:showforrole>

Example: Multiple scopes

When I'm doing content-based tagging, what operators can I use in my tags?

In most cases, with content tags, if you provide multiple values (separated by commas) the default behavior is or. This means that if the viewing user has visibility of one of the specified resources, the user can see the content. The exception to this is the soa:showforscope tag. For specifics, refer to the table below.

Tag

Default operator

Supports the "and" operator?

soa:showforlicense

Or

No

soa:showforscope

And

Yes, plus it is the default. The user must have visibility access to all the specified scopes in order to see the content.

Streamlining Content-Based Doc Tagging:

How can I simplify content-based doc tagging updates using the replacements.js file?

If you have a lot of tags on your documentation set, and something changes, you might have many updates to make. For example:

You might have a new license, or change a license name. Perhaps you have a new version of your Gold license, and you call it UltraGold, but you want users of the new license to see the new content.

Alternatively, you might have some customization in place that might affect how you tag your documentation. For example:

You might have a custom role. Perhaps you set up a custom role, SeniorAdmin, that encompasses both Site Admin and Business Admin roles.

The platform's documentation tagging feature includes a facility that you can use to help automate updates to your documentation. It's a JavaScript file, replacements.js, which you can customize to your implementation by performing the following steps:

In your doc tagging, instead of using the actual license, scope, operation, or role names, use placeholder variables.

In the replacements.js file, specify the values the platform will use for the placeholder variables.

In your documentation files, load replacements.js by means of a <script> tag in the <head> tag, before loading the dynamic_docs.js file.

Note: the processing of this file includes up to two levels of replacement. So, for example, you can map one variable to two or more variables. On the first pass, the single variable is replaced by the two variables; on the second pass, each of the two variables is replaced by the actual values. If two passes are not needed, the platform only does one (or none, if no variables are used).

Below is an example of a replacements.js file, which you can use to build your own. It includes:

At the top, a namespace declaration,

On each line, name-value pairs:

Name: a variable name which you can use in your doc tag, preceded by the namespace value. The replacements.js file looks for this value in your files, and replaces it with the second value.

Value: the value that's substituted. It can be the actual name of a scope, license, operation, or role, or it can be another variable which the platform will replace with actual values on a second pass through the documentation.

In each line of the above, the first value is the name of a license, scope, operation, or role, that you might use in your doc tagging. The second value is a placeholder variable that you use in the documentation to designate that license, scope, operation, or role.

Tip: It's best to create a namespace for the variables, as shown in the default example above, and then use it in all the names for your variables. For example, in the variable {ACMEPC.myscopename}, ACMEPC is the namespace, which would have to be defined at the top of the file as in the MYAPP example above (window.MYAPP = ). Using a namespace will ensure there's no naming collision between any variable names that might already be in use elsewhere in the platform.

Below are some examples of how you can use this file to automate your doc tagging updates.

Example 1: One change instead of many

Let's say you have many instances in your documentation files where there is content tagged for the GoldLicense. By setting up the below entry in your replacements.js file, if the license name changes, all you need to do is change the entry on the left in the file. You don't need to update any of the tags in your documentation files.

window.ACMEPC = {
"goldLicense" : "Gold",
...
}

In this example, the tag in your documentation file would look like the below:

With this approach, if you want to add a third license to the definition, you can change one line in the replacements.js file and your change is effected throughout the documentation set. Otherwise, you'd have to find every instance where documentation is tagged for two licenses and add the third. It's more work, and more possibility for error.

Example 3: One variable for multiple values: roles

Let's say you want to create a role for internal users. Site Admin and Business Admins are internal users; but the definition of this term might change, either to add API Admins or to remove Site Admins.

You can define a variable that encompasses these multiple roles, as follows:

How do I implement the replacements.js file?

If you're using a replacements.js file to automate maintenance of your doc tags, you'll need to load it with a <script> tag in the <head> tag of your HTML files, making sure you load it before the dynamic_docs.js file.

Below is an example of what the <head> tag of one of your documentation files might look like.

By default, if an API has multiple versions, the latest version is the default version.

In Default Theme/Hermosa Theme, the user chooses the API, chooses the version, and then views the documentation. The platform applies the user's API version selection, filtering out the documentation by version. If the user doesn't choose a different version, the user sees the latest version, since it is the default.

In Simple Dev theme, this is not the case. There is no way for the platform to determine which API version the user is interested in. Therefore, to implement version-specific documentation in Simple Dev theme, you can use the API Version attribute in your content-based doc tags.

There are some content-based doc tags for which API version isn't relevant; for example, showforanonymoususer and showforloggedinuser. However, it is relevant for the following tags:

showforlicense

showforscope

showforoperation

showforrole

By tagging sections of your content with the apiVersionId attribute, you identify which sections of text should be shown for which API version.

The example below shows a tag that includes the apiVersionId attribute.

Testing and Finalizing:

How do I test my API documentation tagging?

Correctly applied, documentation tagging will ensure that each piece of your API documentation content is available for its specific target audience, as defined by you, and for nobody else. No matter how private you want your documentation to be, or how broadly available you want to make it, you can accomplish your goals by correctly tagging your content for valid licenses, scopes, operations, and roles, and testing thoroughly.

It's very important to make sure the visibility is working as expected.

Basic testing steps (before upload)

After you've finished tagging, test your documentation by performing the following checks:

Verify that the following are properly configured in all applicable HTML files:

<html> tag

<head> tag

<div> tags

{resource.version} variable

Visibility tags

Verify that the metadata.xml file is complete and that all of the following are correct:

Paths

Filenames

Referenced resource names (such as scopes and licenses)

If applicable, make sure that the API version is correctly specified. When you go to your API in the platform, the API version is in the URL path, after /versions/ in the path. It is in the format {uniqueid}.{tenant}. For example, 0157f427-0b07-4ae6-9ade-26f4ef3bcc71.acmepaymentscorp.

Verify that links to tagged sections are also tagged.

Verify that the scope and operation names you specified in the visibility tags are valid. In the developer portal, scopes are mapped to operations on the Manage Licensing > Edit API Scope page.

Verify that the license names you specified in the visibility tags are available to your app developer audience via the API Access Wizard. To do this you can create a new app and submit an API Access Request by selecting Access at the top right of the API > Overview page.

Role-based testing (after upload)

When you upload the API documentation, all the documentation should be visible to you since you are the API Admin and have full access rights. If there are any tagging errors, you might not know it unless you test.

Once your API documentation is in place, it's best to test from the perspective of several users with different roles, or with visibility of different licenses, scopes, or operations, according to the tags you've used.

You'll want to make sure of two things, both very important:

That the API documentation is being displayed correctly to users who have the appropriate visibility rights.

That the API documentation is not being displayed to users who do not have the appropriate visibility rights.

Make absolutely sure that your documentation index page will be accessible. Even if most of your API is by invitation only, there should ideally be some general information that's available to as many users as possible. A broadly available index page is an opportunity to tell people about your API.

We recommend that you create several test user accounts and request API access using various scenarios that will illustrate visibility and restricted visibility of API documentation in the API > Documentation section.

Sample testing scenario: overview

Let's say for example you have a public API and create a scenario using these three licenses:

A Bronze license for limited view-only access (public)

A Gold license for full access to your published API (public)

A Beta license for access to your newest operations for beta testing (private)

Because the API is public, any user can request API access and choose between the Bronze and Gold licenses. Only invited users will see the Beta license. Your documentation must be appropriately tagged so that all users will see the documentation for the Bronze and Gold licenses and only Beta license holders will see the documentation for the part of your API you're releasing to those customers.

Sample testing scenario: test steps

In this sample testing scenario, below are some test steps you could follow.

To test that the API documentation is tagged correctly:

Set up a test user.

Request API Access to the Live implementation with the Bronze license.

View the documentation. You should be able to see the portions of your documentation that are tagged for Gold and Bronze licenses/scopes but not the content tagged for the Beta license/scope.

Now, as the API Admin, invite your test user to have visibility of the Beta license.

As the user, change your API access request to a request for the Beta license.

View the documentation. You should now be able to view the content for all three licenses.

How do I control the documentation Table of Contents?

If you've selected a set of files to display in the documentation Table of Contents in the left navigation bar, in the API > Documentation section of the platform, the content is displayed dynamically based on the filters specified for all API documentation or for a specified API version.

For more information about working with the API documentation Table of Contents, refer to these topics in the Content Guidelines documentation: