Modifying Policies

You can modify an existing policy using the Rights Management Java API or web service API. To make changes to an existing policy, you retrieve it, modify it, and then update the policy on the server. For example, assume that you retrieve an existing policy and extend its validity period. Before the change takes effect, you must update the policy.

You can modify a policy when business requirements change and the policy no longer reflects these requirements. Instead of creating a new policy, you can simply update an existing policy.

To modify policy attributes using a web service (for example, using Java proxy classes that were created with JAX-WS), you must ensure that the policy is registered with the Rights Management service. You can then reference the existing policy by using the PolicySpec.getPolicyXml method and modify the policy attributes by using the applicable methods. For example, you can modify the offline lease period by invoking the PolicySpec.setOfflineLeasePeriod method.

Note: For more information about the Rights Management service, see Services Reference for LiveCycle .

Summary of steps

To modify an existing policy, perform the following steps:

  1. Include project files.

  2. Create a Rights Management Client API object.

  3. Retrieve an existing policy.

  4. Change policies attributes.

  5. Update the policy.

Include project files

Include necessary files into your development project. If you are creating a client application using Java, then include the necessary JAR files. If you are using web services, then make sure that you include the proxy files.

Create a Rights Management Client API object

Before you can programmatically perform a Rights Managementservice operation, you must create a Rights Management service client object. If you are using the Java API, create a RightsManagementClient object. If you are using the Rights Management web service API, create a RightsManagementServiceService object.

Retrieve an existing policy

You must retrieve an existing policy in order to modify it. To retrieve a policy, specify the policy name and the policy set to which the policy belongs. If you specify a null value for the policy set name, the policy is retrieved from the My Policies policy set.

Set the policy’s attributes

To modify a policy, you modify the value of policy attributes. The only policy attribute that you cannot change is the name attribute. For example, to change the policy’s offline lease period, you can modify the value of the policy’s offline lease period attribute.

When modifying a policy’s offline lease period using a web service, the offlineLeasePeriod field on the PolicySpec interface is ignored. To update the offline lease period, modify the OfflineLeasePeriod element in the PDRL XML document. Then reference the updated PDRL XML document by using the PolicySpec interface’s policyXML data member.

Note: For information about other attributes that you can set, see the Policy interface description in the LiveCycle API Reference .

Update the policy

Before the changes that you make to a policy take affect, you must update the policy with the Rights Management service. Changes to policies that are protecting documents are updated the next time that the policy-protected document is synchronized with the Rights Management service.

Modify existing policies using the Java API

Modify an existing policy by using the Rights Management API (Java):

  1. Include project files.

    Include client JAR files, such as adobe-rightsmanagement-client.jar, in your Java project’s class path.

  2. Create a Rights Management Client API object.

    • Create a ServiceClientFactory object that contains connection properties.

    • Create a RightsManagementClient object by using its constructor and passing the ServiceClientFactory object.

  3. Retrieve an existing policy.

    • Create a PolicyManager object by invoking the RightsManagementClient object’s getPolicyManager method.

    • Create a Policy object that represents the policy to update by invoking the PolicyManager object’s getPolicy method and passing the following values”

      • A string value that represents the policy set name to which the policy belongs. You can specify null that results in the MyPolicies policy set being used.

      • A string value that represents the policy name.

  4. Set the policy’s attributes.

    Change the policy’s attributes to meet your business requirements. For example, to change the policy’s offline lease period, invoke the Policy object’s setOfflineLeasePeriod method.

  5. Update the policy.

    Update the policy by invoking PolicyManager object’s updatePolicy method. Pass the Policy object that represents the policy to update.

Code examples

For code examples using the Rights Management service, see the following Quick Starts in API Quick Starts (Code Examples) :

  • “Quick Start (EJB mode): Modifying a policy using the Java API”

  • “Quick Start (SOAP mode): Modifying a policy using the Java API”

Modify existing policies using the web service API

Modify an existing policy by using the Rights Management API (web service):

  1. Include project files.

    Create a Microsoft .NET project that uses MTOM. Ensure that you use the following WSDL definition: http://localhost:8080/soap/services/RightsManagementService?WSDL&lc_version=9.0.1 .

    Note: Replace localhost with the IP address of the server hosting LiveCycle.

  2. Create a Rights Management Client API object.

    • Create a RightsManagementServiceClient object by using its default constructor.

    • Create a RightsManagementServiceClient.Endpoint.Address object by using the System.ServiceModel.EndpointAddress constructor. Pass a string value that specifies the WSDL to the LiveCycle service (for example, http://localhost:8080/soap/services/RightsManagementService?WSDL .) You do not need to use the lc_version attribute. This attribute is used when you create a service reference.)

    • Create a System.ServiceModel.BasicHttpBinding object by getting the value of the RightsManagementServiceClient.Endpoint.Binding field. Cast the return value to BasicHttpBinding .

    • Set the System.ServiceModel.BasicHttpBinding object’s MessageEncoding field to WSMessageEncoding.Mtom . This value ensures that MTOM is used.

    • Enable basic HTTP authentication by performing the following tasks:

      • Assign the AEM forms user name to the field RightsManagementServiceClient.ClientCredentials.UserName.UserName .

      • Assign the corresponding password value to the field RightsManagementServiceClient.ClientCredentials.UserName.Password .

      • Assign the constant value HttpClientCredentialType.Basic to the field BasicHttpBindingSecurity.Transport.ClientCredentialType .

    • Assign the constant value BasicHttpSecurityMode.TransportCredentialOnly to the field BasicHttpBindingSecurity.Security.Mode .

  3. Retrieve an existing policy.

    Create a PolicySpec object that represents the policy to modify by invoking the RightsManagementServiceClient object’s getPolicy method and passing the following values:

    • A string value that specifies the policy set name to which the policy belongs. You can specify null that results in the MyPolicies policy set being used.

    • A string value that specifies the name of the policy.

  4. Set the policy’s attributes.

    Change the policy’s attributes to meet your business requirements.

  5. Update the policy.

    Update the policy by invoking the RightsManagementServiceClient object’s updatePolicyFromSDK method and passing the PolicySpec object that represents the policy to update.

Code examples

For code examples using the Rights Management service, see the following Quick Starts in API Quick Starts (Code Examples) :

  • “Quick Start (MTOM): Modifying a policy using the web service API”

  • “Quick Start (SwaRef): Modifying a policy using the web service API”

// Ethnio survey code removed