Sub-Collection Licensing

Performance tests show that the NXT 4 Online Server performs best with a few large content collections rather than many smaller content collections. However, for publishers who distribute their collections both online and offline, having many smaller content collections simplifies the creation of subscriptions.

Since the Library Manager sets subscription information only at the content collection level, it appears that you must make a choice between online performance (fewer collections) or flexibility (more collections) in your subscription management.

However, you can create subscriptions at the sub-collection level. Thus, you can create larger (and fewer) content collections to support your library's online performance needs while still serving your offline market with more granular subscriptions.

To enable sub-collection license management, you must

• Set unique IDs for the nodes you want to license in your content collections
• Create a library referencing your content collections
• Create an initial subscription in the Library Manager which includes the content collections containing your desired subscription content
• Export the subscription definition file from the Library Manager
• Modify the subscription definition file in a text editor
• Import the subscription definition back into the Library Manager
• Create licenses based on the subscription

Setting Unique IDs in Content Collections

The license management system relies on IDs to identify which content is included in each subscription. Since you can only create subscriptions on a content collection level in Library Manager, the license management system uses content collection IDs by default. Similarly, to set up sub-collection license management, you must specify the IDs for folder or document nodes you wish to control inside the collection.

You can specify and set IDs for a subscription on a document level. However, Rocket does not recommend document-level subscriptions, because as the ID list grows, performance may suffer. Therefore, typically, you will want to set and specify IDs on the folder level.

To set an explicit and unique ID, you must either use the File System Content Bridge in Library Manager or ccBuild and the makefile. Rocket does not support sub-collection subscription and licensing for collections you create from ODBC and Lotus Notes content bridges.

Using the File System Bridge

Within the property and value to create unique ID values for each folder or document node in your content collection. You use the id property and the path value to create IDs and ensure their uniqueness. The path value ensures ID uniqueness because it includes the full path to the folder or document as well as the name and extension for documents.

All IDs within a content collection have a 127 character limit. So, if you have a deep structure or long folder and document names, you may need to consider using ccBuild instead of the File System Content Bridge.

If you choose to use the File System Content Bridge and set the id property to path, you must configure the Content Rules accordingly for each document type in the collection.

1. In the Library Manager, open the Content Rules property dialog for a collection builder using the File System Content Bridge. (Figure 1)
2. Select the dir Both rule and open the Property Values dialog for this rule. (Figure 1)
3. Add the id property to the Members list.
4. Set the following values in the Properties pane (Figure 1):
   1. Property Source: Path.
   2. Property Source Value: Path.
5. Set up the rest of the file system bridge as you normally would and build the collection.

Figure 1. Library Manager

To set and specify IDs for specific documents, you must repeat this process each document type in the Content Rules Members list.

Once you build your content collection, you may now reference the full file system path to folders and documents as the ID. Please note that the full path includes the drive letter. For example, the ID could be c:\projects\shakespeare\tragedies to the "Tragedies" folder.

Using ccBuild

Using ccBuild is the recommended way to set unique IDs for folders inside your content collection. ccBuild uses the attributes and settings in a makefile to specify all the documents and attributes for a content collection. Inside the makefile, you can set unique IDs. (If you don't set an explicit ID, then ccBuild generates one automatically; unfortunately, you have no way of knowing what that ID is.)

The makefile.dtd that governs the structure of your content collection makefile allows each document element to have an id attribute. So, to set IDs for folders or documents within your makefile, you must add the id attribute and value to each respective document element. As you look at the makefile, keep in mind that "folders" are simply documents whose element encompasses other documents. For example:

<document id="XYZPublishing/Shakespeare" 
	 name="Shakes" 
	 title="Shakespeare's Works">
	<document id="XYZPublishing/Shakespeare/Tragedies" 
		 name="Tragedies" 
		 title="Tragedies">
		<document name="Hamlet" 
			 title="Hamlet, Prince of Denmark" 
			 location="&prj-root;\Shakes\Trag\Hamlet.xml" 
			 content-type="text/xml"/>
	</document>
</document>
						

In this example, the first two "documents" are folders. The third document is an actual document. Note that the folders have ID attributes and values but not the document.

The path metaphor used in the example IDs is recommended, but not required. The format of the ID is up to you. Your only limitations to these ID values are:

• They must not contain quotes
• They must be unique
• They must not exceed 127 characters in length

Exporting Subscription Definitions

After you have set or created the IDs for your folder or document nodes, you can now configure your base or initial subscriptions to leverage these IDs and create a sub-collection subscription. When you create a subscription in Library Manager, Library Manager creates a subscription definition. This definition holds all the information about the subscription, including the content collections to which the subscription gives access. To enable sub-collection license management, you must manually modify the subscription definition file (.pubsd extension). You create a subscription definition file by "exporting" a subscription.

To export a subscription definition to a file so you can edit it:

1. In the Library Manager, choose the Subscriptions tab.
2. Select the subscription you wish to modify to support sub-collection license management.
3. Choose Subscriptions..Export License from the Subscriptions menu.
4. Save the subscription definition file. Make note of where you saved the file.

That is it! You now have a subscription definition file (.pubsd) to manually configure for sub-collection license management.

Modifying Subscription Definitions

The NXT subscription definition file is an XML file with the extension .pubsd. You may edit it in any text or XML editor.

The subscription definition file has three general sections:

• Subscription stores the ID, expiration options, and concurrent user options for the subscription. Do not modify this section.
• Collections-with-passwords lists the IDs of the collections in the subscription. Do not modify this section. You should refer to this section to identify the right collections to modify in the <grant> section.
• Grant lists the access permissions the subscription grants for each content collection. You will modify the information in the <grant> elements. You can grant permissions on the following domains (refer to the access control documentation for the more information on the domains):
  • Content-Domain
  • Query-Domain
  • Metadata-Domain
  • Excerpts-Domain
  • Excerpts-Domain
  • Navigate-Domain
  • Element-Domain

To enable sub-collection license management, you need to:

• Identify the document IDs for each folder in the content collection you wish to give access to.
• Enter that ID in the <grant> section of the subscription definition file, using the format

  <id>Enter the complete ID here</id>

  For example:

  <id>XYZPublishing/Shakespeare/Tragedies</id>
  <id>Some-Really-Ugly-ID</id>
  <id>c:\myfiles\yourfiles\theirfiles</id>
  

Refer to the following sample file for a sample subscription definition file that has been modified and includes sub-collection IDs.

<?xml version='1.0'?>
<!-- General Subscription Information -->
<subscription id="4c6646e9-de27-4d7b-9c31-a89a1201dd5f"
	      title="30 Day Trial" 
		  version="1" 
		  reference-id="e56ee4ad-58e3-4b2f-9819-8ed1dfe4f757" 
		  expiration-period="0" 
		  relative-license-expiration-date="EndCurrentMonth" 
		  concurrent-user-limit="1">
<!-- Collections with Passwords -->	
		<collections-with-passwords><id>ShakesTragedies</id>	
	</collections-with-passwords>
<!-- Grant Permissions - this is where you set the 
	sub-collection domains -->	
	<grant permission="Content-Domain">		
		<id>Shakespeare/Tragedies</id>		
		<id>Shakespeare/Comedies</id>		
		<id>c:\project files\shakespeare\histories</id>	
	</grant>	
	<grant permission="Query-Domain">		
		<id>Shakespeare/Tragedies</id>					
		<id>Shakespeare/Comedies</id>		
		<id>c:\project files\shakespeare\histories</id>	
	</grant>	
	<grant permission="Metadata-Domain">		
		<id>Shakespeare/Tragedies</id>		
		<id>Shakespeare/Comedies</id>		
		<id>c:\project files\shakespeare\histories</id>	
	</grant>	
	<grant permission="Excerpts-Domain">		
		<id>Shakespeare/Tragedies</id>		
		<id>Shakespeare/Comedies</id>		
		<id>c:\project files\shakespeare\histories</id>	
	</grant>	
	<grant permission="Navigate-Domain">		
		<id>Shakespeare/Tragedies</id>		
		<id>Shakespeare/Comedies</id>		
		<id>c:\project files\shakespeare\histories</id>	
	</grant>	
	<grant permission="Element-Domain">		
		<id>Shakespeare/Tragedies</id>		
		<id>Shakespeare/Comedies</id>		
		<id>c:\project files\shakespeare\histories</id>	
	</grant>
</subscription>

Importing Subscription Definitions

Once you have modified and saved your subscription definitions, you must import them into the Library Manager so you can then use them to create licenses.

To import a modified subscription definition:

1. In the Library Manager Subscription tab, and delete the subscription you modified from the Subscriptions list (choose Subscriptions..Delete from the Subscriptions menu). (You must delete the existing subscription before re-importing it, as the subscriptions both have the same IDs.)
2. Choose Subscriptions..Import License from the Subscriptions menu.
3. Locate the modified subscription definition file and click Open.

The Library Manager validates the format of the subscription definition prior to importing it. If there are problems, the Library Manager will not import the file.

Testing Your Changes

To test your changes, you need to:

1. Create a license from the imported subscription.
2. Install the library on the NXT Offline Publisher client or Intranet Publisher Server
3. Apply the license.
4. View the content in NXT. Verify that the correct information is available and that other, non-subscription content is not.

Copyright © 2006-2023, Rocket Software, Inc. All rights reserved.