Share via

RightsTemplate object

  • Article

The RightsTemplate object can be used to manage a rights policy template. Templates identify rights and conditions that can be applied to AD RMS protected content, and they identify the users who can access the content. Different templates typically contain a different mix of rights or a different set of conditions. The following template elements can be defined by using the AD RMS Scripting API:

  • A collection of template names and descriptions with a different name-description pair for each locale ID (LCID) entered.
  • Users and groups that can be granted content licenses.
  • The rights granted to each user or user group.
  • The content expiration policy.
  • A set of extended policies.
  • A collection of application-specific name-value pairs.
  • The revocation policy for the template.
  • A revocation list.
  • A revocation list refresh interval.
  • A revocation list public key file.

Individual RightsTemplate objects can be retrieved from the RightsTemplateCollection object that is initialized from the existing templates on the server when the ConfigurationManager object is initialized. You can create a new template by using the CreateObject() function or the Copy method on the RightsTemplateCollection object.

Members

The RightsTemplate object has these types of members:

Properties

The RightsTemplate object has these properties.

Property Description
ApplicationSpecificDataItems
 Retrieves an ApplicationSpecificDataItemCollection object that contains application specific name-value pairs.
Author
 Retrieves the name of the individual who created or last updated the template.
CreatedTime
 Retrieves the date and time at which the template was created.
ExpirationCondition
 Retrieves an ExpirationCondition object that identifies expiration policy for the content associated with the template.
ExtendedCondition
 Retrieves an ExtendedCondition object that identifies additional policies that can be contained in the rights policy template.
Id
 Retrieves a GUID for the template.
IsPublished
 Retrieves a Boolean value that specifies whether the template can be exported.
RevocationCondition
 Retrieves a RevocationCondition object that contains revocation information for the template.
RightsRequestUrl
 Specifies and retrieves a URL that identifies the location used to respond to client rights requests.
Summaries
 Retrieves a TemplateSummaryCollection object that contains descriptive information, in one or more languages, for the template.
UpdatedTime
 Retrieves the date and time at which the template was last updated.
UserRightsItems
 Retrieves a UserRightsItemCollection object that contains a collection of user IDs and associated rights.

Examples

DIM config_manager
DIM admin_role

' *******************************************************************
' Create and initialize a ConfigurationManager object.

SUB InitObject()

  CALL WScript.Echo( "Create ConfigurationManager object...")
  SET config_manager = CreateObject _
    ("Microsoft.RightsManagementServices.Admin.ConfigurationManager")      
  CheckError()
    
  CALL WScript.Echo( "Initialize...")
  admin_role=config_manager.Initialize(false,"localhost",80,"","","")
  CheckError()

END SUB

' *******************************************************************
' Create a template and add it to the template collection. 

SUB CreateRightsTemplate()

  DIM template_manager
  DIM templateColl
  DIM templateObj
  DIM summary
  DIM rights
  DIM appData
  DIM itemIndex

  ' Retrieve the RightsTemplatePolicy object.
  SET template_manager = config_manager.RightsTemplatePolicy
  CheckError()
    
  ' Retrieve the template publishing path.
  CALL WScript.Echo("RightsTemplatePolicy.PublishingFilePath: " _
                    & template_manager.PublishingFilePath)

  ' Clear the template collection.
  template_manager.RightsTemplateCollection.Clear()
  CheckError()

  ' Create a template object and specify the request URL.
  SET templateObj = CreateObject( _
      "Microsoft.RightsManagementServices.Admin.RightsTemplate")
  templateObj.RightsRequestUrl = "http://rms_test/"
  CheckError()

  ' Create a template summary object.
  CALL WScript.Echo("Create a template summary.")
  SET summary = CreateObject( _
      "Microsoft.RightsManagementServices.Admin.TemplateSummary")
  summary.LanguageId = 1033
  summary.Name = "Scripting test template"
  summary.Description = "Scripting test template Desc"
  templateObj.Summaries.Add( summary )
  CheckError()
    
  ' Add rights to the template object.
  CALL WScript.Echo("Create template rights...")
  SET rights = CreateObject( _
      "Microsoft.RightsManagementServices.Admin.UserRightsItem")
  rights.UserId = "someone@example.com"
  rights.WellKnownRights = _
           config_manager.Constants.TemplateRightExtract + _
           config_manager.Constants.TemplateRightPrint + _
           config_manager.Constants.TemplateRightForward
  rights.CustomRights.Add("CUSTOMRIGHTA")
  rights.CustomRights.Add("CUSTOMRIGHTB")
  Err.Clear()
  templateObj.UserRightsItems.Add( rights )
  CheckError()

  ' Add an expiration condition.
  CALL WScript.Echo("Create template ExpirationCondition.")
  templateObj.ExpirationCondition.ExpirationData.ExpirationType = 2
  templateObj.ExpirationCondition.ExpirationData.Value = Now
  templateObj.ExpirationCondition.RenewalDays = 120
  CheckError()

  ' Add an extended condition.
  CALL WScript.Echo("Create template ExtendedCondition.")
  templateObj.ExtendedCondition.EnableViewInTrustedBrowser = true
  templateObj.ExtendedCondition.EnableOnetimeLicense = true
  CheckError()

  ' Identify an excluded application.
  CALL WScript.Echo("Create template ApplicationSpecificDataItems.")
  SET appData = CreateObject( _
      "Microsoft.RightsManagementServices.Admin.ApplicationSpecificDataItem")
  appData.Name = "NOTE PAD"
  appData.Value = "Notepad.exe"
  templateObj.ApplicationSpecificDataItems.Add( appData )
  CheckError()

  ' Add revocation information.
  CALL WScript.Echo("Create template RevocationCondition.")
  templateObj.RevocationCondition.Url = "https://test"
  templateObj.RevocationCondition.RefreshPerDays = 30
  templateObj.RevocationCondition.PublicKeyFile = "PublicKey.dat"
  CheckError()
  
  ' Retrieve the RightsTemplateCollection object.
  CALL WScript.Echo("Create template Collection.")
  SET templateColl = template_manager.RightsTemplateCollection
  CheckError()

  ' Add the new template to the collection.
  CALL WScript.Echo("Add template to template collection...")
  itemIndex = templateColl.Add( templateObj )
  CheckError()

  ' Verify that the template was added. Because the collection
  ' was earlier cleared, it should contain only one template. 
  IF template_manager.RightsTemplateCollection.Count <> 1 THEN
      CALL RaiseError(-401, "Fail to add RightsTemplate.")
  END IF

  ' Update the templates on the server with the template that
  ' you just added to the collection.
  SET firstObj = template_manager.RightsTemplateCollection.Item(0)
  CheckError()
  template_manager.RightsTemplateCollection.Update( firstObj )
  CheckError()

END SUB

' *******************************************************************
' Error checking function.

FUNCTION CheckError()
  CheckError = Err.number
  IF Err.number <> 0 THEN
    CALL WScript.Echo( vbTab & "*****Error Number: " _
                       & Err.number _
                       & " Desc:" _
                       & Err.Description _
                       & "*****")
    WScript.StdErr.Write(Err.Description)
    WScript.Quit( Err.number )
  END IF
END FUNCTION

' *******************************************************************
' Generate a runtime error.

SUB RaiseError(errId, desc)
  CALL Err.Raise( errId, "", desc )
  CheckError()
END SUB

Requirements
Minimum supported client
 None supported
Minimum supported server
 Windows Server 2008
Assembly
Microsoft.RightsManagementServices.Admin.dll

See also

Active Directory Rights Management Services Scripting API Reference

ConfigurationManager

RightsTemplateCollection