Protecting Documents with Policies protecting-documents-with-policies

Revoking Access to Documents

Apply a policy to a PDF document using the Java API apply-a-policy-to-a-pdf-document-using-the-java-api

Apply a policy to a PDF document by using the Document Security API (Java):

Include project files.

Include client JAR files, such as adobe-rightsmanagement-client.jar, in your Java project’s class path.
Create a Document Security Client API object.
- Create a ServiceClientFactory object that contains connection properties.
- Create a RightsManagementClient object by using its constructor and passing the ServiceClientFactory object.
Retrieve a PDF document.
- Create a java.io.FileInputStream object that represents the PDF document by using its constructor. Pass a string value that specifies the location of the PDF document.
- Create a com.adobe.idp.Document object by using its constructor and passing the java.io.FileInputStream object.
Apply an existing policy to the PDF document.
- Create a DocumentManager object by invoking the RightsManagementClient object’s getDocumentManager method.
- Apply a policy to the PDF document by invoking the DocumentManager object’s protectDocument method and passing the following values:
  - The com.adobe.idp.Document object that contains the PDF document to which the policy is applied.
  - A string value that specifies the name of the document.
  - A string value that specifies the name of the policy set to which the policy belongs. You can specify a null value that results in the MyPolicies policy set being used.
  - A string value that specifies the policy name.
  - A string value that represents the name of the user manager domain of the user who is the publisher of the document. This parameter value is optional and can be null (if this parameter is null, then the next parameter value must be null).
  - A string value that represents the name of the canonical name of the user manager user who is the publisher of the document. This parameter value is optional and can be null (if this parameter is null, then the previous parameter value must be null).
  - A com.adobe.livecycle.rightsmanagement.Locale that represents the locale that is used for selecting the MS Office template. This parameter value is optional and not used for PDF documents. To secure a PDF document, specify null.
  The protectDocument method returns a RMSecureDocumentResult object that contains the policy-protected PDF document.
Save the PDF document.
- Invoke the RMSecureDocumentResult object’s getProtectedDoc method to get the policy-protected PDF document. This method returns a com.adobe.idp.Document object.
- Create a java.io.File object and ensure that the file extension is PDF.
- Invoke the com.adobe.idp.Document object’s copyToFile method to copy the contents of the Document object to the file (ensure that you use the Document object that was returned by the getProtectedDoc method).

Code examples

For code examples using the Document Security service, see the following Quick Starts:

“Quick Start (EJB mode): Applying a policy to a PDF document using the Java API”
“Quick Start (SOAP mode): Applying a policy to a PDF document using the Java API”

See also

Apply a policy to a PDF document using the web service API apply-a-policy-to-a-pdf-document-using-the-web-service-api

Apply a policy to a PDF document by using the Document Security API (web service):

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 note
NOTE
Replace `localhost` with the IP address of the server hosting AEM Forms.

Create a Document Security 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 Forms 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.
Retrieve a PDF document.
- Create a BLOB object by using its constructor. The BLOB object is used to store a PDF document to which a policy is applied.
- Create a System.IO.FileStream object by invoking its constructor and passing a string value that represents the file location of the PDF document and the mode in which to open the file.
- Create a byte array that stores the content of the System.IO.FileStream object. Determine the byte array size by getting the System.IO.FileStream object’s Length property.
- Populate the byte array with stream data by invoking the System.IO.FileStream object’s Read method. Pass the byte array, the starting position, and the stream length to read.
- Populate the BLOB object by assigning its MTOM field with the contents of the byte array.
Apply an existing policy to the PDF document.

Apply a policy to the PDF document by invoking the RightsManagementServiceClient object’s protectDocument method and passing the following values:
- The BLOB object that contains the PDF document to which the policy is applied.
- A string value that specifies the name of the document.
- A string value that specifies the name of the policy set to which the policy belongs. You can specify a null value that results in the MyPolicies policy set being used.
- A string value that specifies the policy name.
- A string value that represents the name of the user manager domain of the user who is the publisher of the document. This parameter value is optional and can be null (if this parameter is null, then the next parameter value must be null).
- A string value that represents the name of the canonical name of the user manager user who is the publisher of the document. This parameter value is optional and can be null (if this parameter is null, then the previous parameter value must be null).
- A RMLocale value that specifies the locale value (for example, RMLocale.en).
- A string output parameter that is used to store the policy identifier value.
- A string output parameter that is used to store the policy-protected identifier value.
- A string output parameter that is used to store the mime type (for example, application/pdf).
The protectDocument method returns a BLOB object that contains the policy-protected PDF document.
Save the PDF document.
- Create a System.IO.FileStream object by invoking its constructor and passing a string value that represents the file location of the policy-protected PDF document.
- Create a byte array that stores the data content of the BLOB object that was returned by the protectDocument method. Populate the byte array by getting the value of the BLOB object’s MTOM data member.
- Create a System.IO.BinaryWriter object by invoking its constructor and passing the System.IO.FileStream object.
- Write the contents of the byte array to a PDF file by invoking the System.IO.BinaryWriter object’s Write method and passing the byte array.

Code examples

For code examples using the Document Security service, see the following Quick Starts:

“Quick Start (MTOM): Applying a policy to a PDF document using the web service API”
“Quick Start (SwaRef): Applying a policy to a PDF document using the web service API ”

Removing Policies from PDF Documents removing-policies-from-pdf-documents

You can remove a policy from a policy-protected document in order to remove security from the document. That is, if you no longer want the document to be protected by a policy. If you want to update a policy-protected document with a newer policy, then instead of removing the policy and adding the updated policy, it is more efficient to switch the policy.

NOTE

For more information about the Document Security service, see Services Reference for AEM Forms.

Summary of steps summary_of_steps-4

To remove a policy from a policy-protected PDF document, perform the following steps:

Include project files
Create a Document Security Client API object.
Retrieve a policy-protected PDF document.
Remove the policy from the PDF document.
Save the unsecured PDF document.

Include project files

Create a Document Security Client API object

Before you can programmatically perform a Document Security service operation, create a Document Security service client object.

Retrieve a policy-protected PDF document

You can retrieve a policy-protected PDF document in order to remove a policy. If you attempt to remove a policy from a PDF document that is not protected by a policy, you will cause an exception.

Remove the policy from the PDF document

You can remove a policy from a policy-protected PDF document provided that an administrator is specified in the connection settings. If not, then the policy used to secure a document must contain the SWITCH_POLICY permission in order to remove a policy from a PDF document. Also, the user specified in the AEM Forms connection settings must also have that permission. Otherwise, an exception is thrown.

Save the unsecured PDF document

After the Document Security service removes a policy from a PDF document, you can save the unsecured PDF document as a PDF file.

See also

Remove a policy from a PDF document using the Java API remove-a-policy-from-a-pdf-document-using-the-java-api

Remove a policy from a policy-protected PDF document by using the Document Security API (Java):

Include project files.

Include client JAR files, such as adobe-rightsmanagement-client.jar, in your Java project’s class path.
Create a Document Security Client API object.
- Create a ServiceClientFactory object that contains connection properties.
- Create a DocumentSecurityClient object by using its constructor and passing the ServiceClientFactory object.
Retrieve a policy-protected PDF document.
- Create a java.io.FileInputStream object that represents the policy-protected PDF document by using its constructor and passing a string value that specifies the location of the PDF document.
- Create a com.adobe.idp.Document object by using its constructor and passing the java.io.FileInputStream object.
Remove the policy from the PDF document.
- Create a DocumentManager object by invoking the DocumentSecurityClient object’s getDocumentManager method.
- Remove a policy from the PDF document by invoking the DocumentManager object’s removeSecurity method and passing the com.adobe.idp.Document object that contains the policy-protected PDF document. This method returns a com.adobe.idp.Document object that contains an unsecured PDF document.
Save the unsecured PDF document.
- Create a java.io.File object and ensure that the file extension is PDF.
- Invoke the Document object’s copyToFile method to copy the contents of the Document object to the file (ensure that you use the Document object that was returned by the removeSecurity method).

Code examples

For code examples using the Document Security service, see the following Quick Starts:

“Quick Start (SOAP mode): Removing a policy from a PDF document using the Java API”

Remove a policy using the web service API remove-a-policy-using-the-web-service-api

Remove a policy from a policy-protected PDF document using the Document Security API (web service):

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 note
NOTE
Replace `localhost` with the IP address of the server hosting AEM Forms.

Create a Document Security Client API object.
- Create a DocumentSecurityServiceClient object by using its default constructor.
- Create a DocumentSecurityServiceClient.Endpoint.Address object by using the System.ServiceModel.EndpointAddress constructor. Pass a string value that specifies the WSDL to the AEM Forms 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 DocumentSecurityServiceClient.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 DocumentSecurityServiceClient.ClientCredentials.UserName.UserName.
  - Assign the corresponding password value to the field DocumentSecurityServiceClient.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.
Retrieve a policy-protected PDF document.
- Create a BLOB object by using its constructor. The BLOB object is used to store the policy-protected PDF document from which the policy is removed.
- Create a System.IO.FileStream object by invoking its constructor and passing a string value that represents the file location of the PDF document and the mode in which to open the file.
- Create a byte array that stores the content of the System.IO.FileStream object. You can determine the size of the byte array by getting the System.IO.FileStream object’s Length property.
- Populate the byte array with stream data by invoking the System.IO.FileStream object’s Read method and passing the byte array, the starting position, and the stream length to read.
- Populate the BLOB object by assigning its MTOM field with the contents of the byte array.
Remove the policy from the PDF document.

Remove the policy from the PDF document by invoking the DocumentSecurityServiceClient object’s removePolicySecurity method and passing the BLOB object that contains the policy-protected PDF document. This method returns a BLOB object that contains an unsecured PDF document.
Save the unsecured PDF document.
- Create a System.IO.FileStream object by invoking its constructor and passing a string value that represents the file location of the unsecured PDF document.
- Create a byte array that stores the data content of the BLOB object that was returned by the removePolicySecurity method. Populate the byte array by getting the value of the BLOB object’s MTOM field.
- Create a System.IO.BinaryWriter object by invoking its constructor and passing the System.IO.FileStream object.

Code examples

For code examples using the Document Security service, see the following Quick Starts:

“Quick Start (MTOM): Removing a policy from a PDF document using the web service API ”
“Quick Start (SwaRef): Removing a policy from a PDF document using the web service API”

See also

Revoking Access to Documents revoking-access-to-documents

You can revoke access to a policy-protected PDF document resulting in all copies of the document being inaccessible to users. When a user attempts to open a revoked PDF document, they are redirected to a specified URL where a revised document can be viewed. The URL to where the user is redirected must be programmatically specified. When you revoke access to a document, the change takes effect the next time the user synchronizes with the Document Security service by opening the policy-protected document online.

The ability to revoke access to a document provides additional security. For example, assume a newer version of a document is available and you no longer want anyone viewing the outdated version. In this situation, access to the older document can be revoked, and nobody can view the document unless access is reinstated.

NOTE

For more information about the Document Security service, see Services Reference for AEM Forms.

Summary of steps summary_of_steps-5

To revoke a policy-protected document, perform the following steps:

Include project files.
Create a Document Security Client API object.
Retrieve a policy-protected PDF document.
Revoke the policy-protected document.

Include project files

Create a Document Security Client API object

Before you can programmatically perform a Document Security service operation, you must create a Document Security service client object.

Retrieve a policy-protected PDF document

You must retrieve a policy-protected PDF document in order to revoke it. You cannot revoke a document that has already been revoked or is not a policy-protected document.

If you know the license identifier value of the policy-protected document, then it is not necessary to retrieve the policy-protected PDF document. However, in most cases, you will need to retrieve the PDF document in order to obtain the license identifier value.

Revoke the policy-protected document

To revoke a policy-protected document, specify the license identifier of the policy-protected document. In addition, you can specify the URL of a document that the user can view when they attempt to open the revoked document. That is, assume that an outdated document is revoked. When a user attempts to open the revoked document, they will see an updated document instead of the revoked document.

NOTE

If you attempt to revoke a document that is already revoked, an exception is thrown.

See also

Reinstating Access to Revoked Documents

Revoke access to documents using the Java API revoke-access-to-documents-using-the-java-api

Revoke access to a policy-protected PDF document by using the Document Security API (Java):

Include project files

Include client JAR files, such as adobe-rightsmanagement-client.jar, in your Java project’s class path.
Create a Document Security Client API object
- Create a ServiceClientFactory object that contains connection properties.
- Create a DocumentSecurityClient object by using its constructor and passing the ServiceClientFactory object.
Retrieve a policy-protected PDF document
- Create a java.io.FileInputStream object that represent the policy-protected PDF document by using its constructor and passing a string value that specifies the location of the PDF document.
- Create a com.adobe.idp.Document object by using its constructor and passing the java.io.FileInputStream object.
Revoke the policy-protected document
- Create a DocumentManager object by invoking the DocumentSecurityClient object’s getDocumentManager method.
- Retrieve the license identifier value of the policy-protected document by invoking the DocumentManager object’s getLicenseId method. Pass the com.adobe.idp.Document object that represents the policy-protected document. This method returns a string value that represents the license identifier value.
- Create a LicenseManager object by invoking the DocumentSecurityClient object’s getLicenseManager method.
- Revoke the policy-protected document by invoking the LicenseManager object’s revokeLicense method and passing the following values:
  - A string value that specifies the license identifier value of the policy-protected document (specify the return value of the DocumentManager object’s getLicenseId method).
  - A static data member of the License interface that specifies the reason to revoke the document. For example, you can specify License.DOCUMENT_REVISED.
  - A java.net.URL value that specifies the location to where a revised document is located. If you do not want to redirect a user to another URL, then you can pass null.

Code examples

For code examples using the Document Security service, see the following Quick Starts:

“Quick Start (SOAP mode): Revoking a document using the Java API”

Revoke access to documents using the web service API revoke-access-to-documents-using-the-web-service-api

Revoke access to a policy-protected PDF document by using the Document Security API (web service):

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 note
NOTE
Replace `localhost` with the IP address of the server hosting AEM Forms.

Create a Document Security Client API object
- Create a DocumentSecurityServiceClient object by using its default constructor.
- Create a DocumentSecurityServiceClient.Endpoint.Address object by using the System.ServiceModel.EndpointAddress constructor. Pass a string value that specifies the WSDL to the AEM Forms 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 DocumentSecurityServiceClient.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 DocumentSecurityServiceClient.ClientCredentials.UserName.UserName.
  - Assign the corresponding password value to the field DocumentSecurityServiceClient.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.
Retrieve a policy-protected PDF document
- Create a BLOB object by using its constructor. The BLOB object is used to store a policy-protected PDF document that is revoked.
- Create a System.IO.FileStream object by invoking its constructor and passing a string value that represents the file location of the policy-protected PDF document to revoke and the mode in which to open the file.
- Create a byte array that stores the content of the System.IO.FileStream object. You can determine the size of the byte array by getting the System.IO.FileStream object’s Length property.
- Populate the byte array with stream data by invoking the System.IO.FileStream object’s Read method and passing the byte array, the starting position, and the stream length to read.
- Populate the BLOB object by assigning its MTOM field with the contents of the byte array.
Revoke the policy-protected document
- Retrieve the license identifier value of the policy-protected document by invoking the DocumentSecurityServiceClient object’s getLicenseID method and passing the BLOB object that represents the policy-protected document. This method returns a string value that represents the license identifier.
- Revoke the policy-protected document by invoking the DocumentSecurityServiceClient object’s revokeLicense method and passing the following values:
  - A string value that specifies the license identifier value of the policy-protected document (specify the return value of the DocumentSecurityServiceService object’s getLicenseId method).
  - A static data member of the Reason enum that specifies the reason to revoke the document. For example, you can specify Reason.DOCUMENT_REVISED.
  - A string value that specifies the URL location to where a revised document is located. If you do not want to redirect a user to another URL, then you can pass null.

Code examples

For code examples using the Document Security service, see the following Quick Starts:

“Quick Start (MTOM): Revoking a document using the web service API”
“Quick Start (SwaRef): Revoking a document using the web service API”

See also

Removing Policies from Word Documents

Reinstating Access to Revoked Documents reinstating-access-to-revoked-documents

You can reinstate access to a revoked PDF document, resulting in all copies of the revoked document being accessible to users. When a user opens a reinstated document that was revoked, the user is able to view the document.

NOTE

For more information about the Document Security service, see Services Reference for AEM Forms.

Summary of steps summary_of_steps-6

To reinstate access to a revoked PDF document, perform the following steps:

Include project files.
Create a Document Security Client API object.
Retrieve the license identifier of the revoked PDF document.
Reinstate access to the revoked PDF document.

Include project files

Create a Document Security Client API object

Before you can programmatically perform a Document Security service operation, you must create a Document Security service client object. If you are using the Java API, create a DocumentSecurityClient object. If you are using the Document Security web service API, create a DocumentSecurityServiceService object.

Retrieve the license identifier of the revoked PDF document

You must retrieve the license identifier of the revoked PDF document in order to reinstate a revoked PDF document. After you obtain the license identifier value, you can reinstate a revoked document. If you attempt to reinstate a document that is not revoked, you will cause an exception.

Reinstate access to the revoked PDF document

To reinstate access to a revoked PDF document, you must specify the license identifier of the revoked document. If you attempt to reinstate access to a PDF document that is not revoked, you will cause an exception.

See also

Revoking Access to Documents

Reinstate access to revoked documents using the Java API reinstate-access-to-revoked-documents-using-the-java-api

Reinstate access to a revoked document by using the Document Security API (Java):

Include project files.

Include client JAR files, such as adobe-rightsmanagement-client.jar, in your Java project’s class path.
Create a Document Security Client API object.
- Create a ServiceClientFactory object that contains connection properties.
- Create a DocumentSecurityClient object by using its constructor and passing the ServiceClientFactory object.
Retrieve the license identifier of the revoked PDF document.
- Create a java.io.FileInputStream object that represents the revoked PDF document by using its constructor and passing a string value that specifies the location of the PDF document.
- Create a com.adobe.idp.Document object by using its constructor and passing the java.io.FileInputStream object.
- Create a DocumentManager object by invoking the DocumentSecurityClient object’s getDocumentManager method.
- Retrieve the license identifier value of the revoked document by invoking the DocumentManager object’s getLicenseId method and passing the com.adobe.idp.Document object that represents the revoked document. This method returns a string value that represents the license identifier.
Reinstate access to the revoked PDF document.
- Create a LicenseManager object by invoking the DocumentSecurityClient object’s getLicenseManager method.
- Reinstate access to the revoked PDF document by invoking the LicenseManager object’s unrevokeLicense method and passing the license identifier value of the revoked document.

Code examples

For code examples using the Document Security service, see the following Quick Starts:

“Quick Start (SOAP mode): Reinstating access to a revoked document using the web service API”

Reinstate access to revoked documents using the web service API reinstate-access-to-revoked-documents-using-the-web-service-api

Reinstate access to a revoked document using the Document Security API (web service):

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 note
NOTE
Replace `localhost` with the IP address of the server hosting AEM Forms.

Create a Document Security Client API object.
- Create a DocumentSecurityServiceClient object by using its default constructor.
- Create a DocumentSecurityServiceClient.Endpoint.Address object by using the System.ServiceModel.EndpointAddress constructor. Pass a string value that specifies the WSDL to the AEM Forms 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 DocumentSecurityServiceClient.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 DocumentSecurityServiceClient.ClientCredentials.UserName.UserName.
  - Assign the corresponding password value to the field DocumentSecurityServiceClient.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.
Retrieve the license identifier of the revoked PDF document.
- Create a BLOB object by using its constructor. The BLOB object is used to store a revoked PDF document to which access is reinstated.
- Create a System.IO.FileStream object by invoking its constructor and passing a string value that represents the file location of the revoked PDF document and the mode in which to open the file.
- Create a byte array that stores the content of the System.IO.FileStream object. You can determine the size of the byte array by getting the System.IO.FileStream object’s Length property.
- Populate the byte array with stream data by invoking the System.IO.FileStream object’s Read method and passing the byte array, the starting position, and the stream length to read.
- Populate the BLOB object by assigning its MTOM field with the contents of the byte array.
Reinstate access to the revoked PDF document.
- Retrieve the license identifier value of the revoked document by invoking the DocumentSecurityServiceClient object’s getLicenseID method and passing the BLOB object that represents the revoked document. This method returns a string value that represents the license identifier.
- Reinstate access to the revoked PDF document by invoking the DocumentSecurityServiceClient object’s unrevokeLicense method and passing a string value that specifies the license identifier value of the revoked PDF document (pass the return value of the DocumentSecurityServiceClient object’s getLicenseId method).

Code examples

For code examples using the Document Security service, see the following Quick Starts:

“Quick Start (MTOM): Reinstating access to a revoked document using the web service API”
“Quick Start (SwaRef): Reinstating access to a revoked document using the web service API”

See also

Inspecting Policy Protected PDF Documents inspecting-policy-protected-pdf-documents

You can use the Document Security Service API (Java and web service) to inspect policy-protected PDF documents. Inspecting policy-protected PDF documents returns information about the policy-protected PDF document. You can, for example, determine the policy that was used to secure the document and the date when the document was secured.

You cannot perform this task if your version of LiveCycle is 8.x or an earlier version. Support for inspecting policy-protected documents is added in AEM Forms. If you attempt to inspect a policy-protected document using LiveCycle 8.x (or earlier), an exception is thrown.

NOTE

For more information about the Document Security service, see Services Reference for AEM Forms.

Summary of steps summary_of_steps-7

To inspect a policy-protected PDF document, perform the following steps:

Include project files.
Create a Document Security Client API object.
Retrieve a policy-protected document to inspect.
Obtain information about the policy-protected document.

Include project files

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

Create a Document Security Client API object

Before you can programmatically perform a Document Security service operation, create a Document Security service client object. If you are using the Java API, create a RightsManagementClient object. If you are using the Document Security web service API, create a RightsManagementServiceService object.

Retrieve a policy-protected document to inspect

To inspect a policy-protected document, retrieve it. If you attempt to inspect a document that is not secured with a policy or is revoked, an exception is thrown.

Inspect the document

After you retrieve a polciy-protected document, you can inspect it.

Obtain information about the policy-protected document

After you inspect a policy-protected PDF document, you can obtain information about it. For example, you can determine the policy that is used to secure the document.

If you secure a document with a policy that belongs to My Policies and then call RMInspectResult.getPolicysetName or RMInspectResult.getPolicysetId, null is returned.

If the document is secured using a policy that is contained in a policy set (other than My Policies) then RMInspectResult.getPolicysetName and RMInspectResult.getPolicysetId return valid strings.

See also

Inspect Policy Protected PDF Documents using the Java API inspect-policy-protected-pdf-documents-using-the-java-api

Inspect a policy-protected PDF document by using the Document Security Service API (Java):

Include project files.

Include client JAR files, such as the adobe-rightsmanagement-client.jar, in your Java project’s class path. For information about the location of these files, see Including AEM Forms Java library files.
Create a Document Security Client API object.
- Create a ServiceClientFactory object that contains connection properties. (See Setting connection properties.)
- Create a RightsManagementClient object by using its constructor and passing the ServiceClientFactory object.
Retrieve a policy-protected document to inspect.
- Create a java.io.FileInputStream object that represents the policy-protected PDF document by using its constructor. Pass a string value that specifies the location of the PDF document.
- Create a com.adobe.idp.Document object by using its constructor and passing the java.io.FileInputStream object.
Inspect the document.
- Create a DocumentManager object by invoking the RightsManagementClient object’s getDocumentManager method.
- Inspect the policy-protected document by invoking the LicenseManager object’s inspectDocument method. Pass the com.adobe.idp.Document object that contains the policy-protected PDF document. This method returns a RMInspectResult object that contains information about the policy-protected document.
Obtain information about the policy-protected document.

To obtain information about the policy-protected document, invoke the appropriate method that belongs RMInspectResult object. For example, to retrieve the policy name, invoke the RMInspectResult object’s getPolicyName method.

Code examples

For code examples using the Document Security service, see the following Quick Starts:

“Quick Start (SOAP mode): Inspecting policy protected PDF documents using the Java API”

Inspect Policy Protected PDF Documents using the web service API inspect-policy-protected-pdf-documents-using-the-web-service-api

Inspect a policy-protected PDF document by using the Document Security Service API (web service):

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 note
NOTE
Replace `localhost` with the IP address of the server hosting AEM Forms.

Create a Document Security 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 AEM Forms 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.
Retrieve a policy-protected document to inspect.
- Create a BLOB object by using its constructor. The BLOB object is used to store a PDF document to inspect.
- Create a System.IO.FileStream object by invoking its constructor. Pass a string value that represents the file location of the PDF document and the mode to open the file in.
- Create a byte array that stores the content of the System.IO.FileStream object. You can determine the size of the byte array by getting the System.IO.FileStream object’s Length property.
- Populate the byte array with stream data by invoking the System.IO.FileStream object’s Read method. Pass the byte array, starting position, and stream length to read.
- Populate the BLOB object by assigning its MTOM field with the contents of the byte array.
Inspect the document.

Inspect the policy-protected document by invoking the RightsManagementServiceClient object’s inspectDocument method. Pass the BLOB object that contains the policy-protected PDF document. This method returns a RMInspectResult object that contains information about the policy-protected document.
Obtain information about the policy-protected document.

To obtain information about the policy-protected document, get the value of the appropriate field that belongs to the RMInspectResult object. For example, to retrieve the policy name, get the value of the RMInspectResult object’s policyName field.

Code examples

For code examples using the Document Security service, see the following Quick Starts:

“Quick Start (MTOM): Inspecting policy protected PDF documents using the web service API”
“Quick Start (SwaRef): Inspecting policy protected PDF documents using the web service API”

See also

Creating Watermarks creating-watermarks

Watermarks help ensure the security of a document by uniquely identifying the document and controlling copyright infringement. For example, you can create and place a watermark that states Confidential on all pages of a document. After a watermark is created, you can include it as part of a policy. That is, you can set the policy’s watermark attribute with the newly created watermark. After a policy that contains a watermark is applied to a document, the watermark appears in the policy-protected document.

NOTE

Only users with Document Security administrative privileges can create watermarks. That is, you must specify such a user when defining connection settings required to create a Document Security service client object.

NOTE

For more information about the Document Security service, see Services Reference for AEM Forms.

Summary of steps summary_of_steps-8

To create a watermark, perform the following steps:

Include project files.
Create a Document Security Client API object.
Set the watermarks attributes.
Register the watermark with the Document Security service.

Include project files

Create a Document Security Client API object

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

Set the watermarks attributes

To create a new watermark, you must set watermark attributes. The name attribute must always be defined. In addition to the name attribute, you must set at least one of the following attributes:

Custom Text
DateIncluded
UserIdIncluded
UserNameIncluded

The following table lists key and value pairs that are required when creating a watermark using web services.

Key Name

Description

Value

WaterBackCmd:IS_USERNAME_ENABLED

Specifies if the user name of the user opening the document is part of the watermark.

True or False

WaterBackCmd:IS_USERID_ENABLED

Specifies if the identification of the user opening the document is part of the watermark.

True or False

WaterBackCmd:IS_CURRENTDATE_ENABLED

Specifies if the current date is part of the watermark.

True or False

WaterBackCmd:IS_CUSTOMTEXT_ENABLED

If this value is true, then the value of the custom text must be specified using WaterBackCmd:SRCTEXT.

True or False

WaterBackCmd:OPACITY

Specifies the opacity of the watermark. The default value is 0.5 if it is not specified.

A value between 0.0 and 1.0.

WaterBackCmd:ROTATION

Specifies the rotation of the watermark. The default value is 0 degrees.

A value between 0 and 359.

WaterBackCmd:SCALE

If this value is specified, then WaterBackCmd:IS_SIZE_ENABLED must be present and the value must be true. If this attribute is not specified, the default behavior is fit to page.

A value greater than 0.0 and less than or equal to 1.0.

WaterBackCmd:HORIZ_ALIGN

Specifies the watermark’s horizontal alignment. The default value is center.

left, center, or right

WaterBackCmd:VERT_ALIGN

Specifies the watermark’s vertical alignment. The default value is center.

top, center, or bottom

WaterBackCmd:IS_USE_BACKGROUND

Specifies if the watermark is a background. The default value is false.

True or False

WaterBackCmd:IS_SIZE_ENABLED

True if a custom scale is specified. If this value is true, SCALE must also be specified. If this value is false, then the default is fit to page.

True or False

WaterBackCmd:SRCTEXT

Specifies the custom text for a watermark. If this value is present, then WaterBackCmd:IS_CUSTOMTEXT_ENABLED must also be present and set to true.

True or False

All watermarks must have one of the following attributes defined:

WaterBackCmd:IS_USERNAME_ENABLED
WaterBackCmd:IS_USERID_ENABLED
WaterBackCmd:IS_CURRENTDATE_ENABLED
WaterBackCmd:IS_CUSTOMTEXT_ENABLED

All other attributes are optional.

Register the watermark

A new watermark must be registered with the Document Security service before it can be used. After you register a watermark, you can use it within policies.

See also

Create watermarks using the Java API create-watermarks-using-the-java-api

Create a watermark by using the Document Security API (Java):

Include project files.

Include client JAR files, such as the adobe-rightsmanagement-client.jar, in your Java project’s class path.
Create a Document Security Client API object.
- Create a ServiceClientFactory object that contains connection properties.
- Create a RightsManagementClient object by using its constructor and passing the ServiceClientFactory object.
Set the watermark attributes
- Create a Watermark object by invoking the InfomodelObjectFactory object’s static createWatermark method. This method returns a Watermark object.
- Set the watermark’s name attribute by invoking the Watermark object’s setName method and passing a string value that specifies the policy name.
- Set the watermark’s background attribute by invoking the Watermark object’s setBackground method and passing true. By setting this attribute, the watermark appears in the background of the document.
- Set the watermark’s custom text attribute by invoking the Watermark object’s setCustomText method and passing a string value that represents the watermark’s text.
- Set the watermark’s opacity attribute by invoking the Watermark object’s setOpacity method and passing an integer value that specifies the opacity level. A value of 100 indicates the watermark is completely opaque and a value of 0 indicates the watermark is completely transparent.
Register the watermark.
- Create a WatermarkManager object by invoking the RightsManagementClient object’s getWatermarkManager method. This method returns a WatermarkManager object.
- Register the watermark by invoking the WatermarkManager object’s registerWatermark method and passing the Watermark object that represents the watermark to register. This method returns a string value that represents the watermark’s identification value.

Code examples

For code examples using the Document Security service, see the following Quick Starts:

“Quick Start (SOAP mode): Creating a watermark using the Java API”

Create watermarks using the web service API create-watermarks-using-the-web-service-api

Create a watermark by using the Document Security API (web service):

Create a Document Security Client API object.

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 note
NOTE
Replace `localhost` with the IP address of the server hosting AEM Forms.

Create a Document Security 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 AEM Forms 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.
Set the watermark attributes.
- Create a WatermarkSpec object by invoking the WatermarkSpec constructor.
- Set the watermark’s name by assigning a string value to the WatermarkSpec object’s name data member.
- Set the watermark’s id attribute by assigning a string value to the WatermarkSpec object’s id data member.
- For each watermark property to set, create a separate MyMapOf_xsd_string_To_xsd_anyType_Item object.
- Set the key value by assigning a value to the MyMapOf_xsd_string_To_xsd_anyType_Item object’s key data member (for example, WaterBackCmd:OPACITY).
- Set the value by assigning a value to the MyMapOf_xsd_string_To_xsd_anyType_Item object’s value data member (for example, .25).
- Create a MyArrayOf_xsd_anyType object. For each MyMapOf_xsd_string_To_xsd_anyType_Item object, invoke the MyArrayOf_xsd_anyType object’s Add method. Pass the MyMapOf_xsd_string_To_xsd_anyType_Item object.
- Assign the MyArrayOf_xsd_anyType object to the WatermarkSpec object’s values data member.
Register the watermark.

Register the watermark by invoking the RightsManagementServiceClient object’s registerWatermark method and passing the WatermarkSpec object that represents the watermark to register.

Code examples

For code examples using the Document Security service, see the following Quick Starts:

“Quick Start (MTOM): Creating a watermark using the web service API”
“Quick Start (SwaRef): Creating a watermark using the web service API”

See also

Modifying Watermarks modifying-watermarks

You can modify an existing watermark using the Document Security Java API or web service API. To make changes to an existing watermark, you retrieve it, modify its attributes, and then update it on the server. For example, assume that you retrieve an watermark and modify its opacity attribute. Before the change takes effect, you must update the watermark.

When you modify a watermark, the change impacts future documents that have the watermark applied to them. That is, existing PDF documents that contain the watermark are not affected.

NOTE

Only users with Document Security administrative privileges can modify watermarks. That is, you must specify such a user when defining connection settings required to create a Document Security service client object.

NOTE

For more information about the Document Security service, see Services Reference for AEM Forms.

Summary of steps summary_of_steps-9

To modify a watermark, perform the following steps:

Include project files.
Create a Document Security Client API object.
Retrieve the watermark to modify.
Set the watermarks attributes.
Update the watermark.

Include project files

Create a Document Security Client API object

Before you can programmatically perform a Document Security service operation, you must create a Document Security service client object. If you are using the Java API, create a DocumentSecurityClient object. If you are using the Document Security web service API, create a DocumentSecurityServiceService object.

Retrieve the watermark to modify

To modify a watermark, you must retrieve an existing watermark. You can retrieve a watermark by specifying its name or by specifying its identifier value.

Set the watermarks attributes

To modify an existing watermark, change the value of one or more watermark attributes. When programmatically updating a watermark using a web service, you must set all of the attributes that were originally set, even if the value does not change. For example, assume the following watermark attributes are set: WaterBackCmd:IS_USERID_ENABLED, WaterBackCmd:IS_CUSTOMTEXT_ENABLED, WaterBackCmd:OPACITY, and WaterBackCmd:SRCTEXT. Although the only attribute that you want to modify is WaterBackCmd:OPACITY, you must set the other values are well.

NOTE

When using the Java API to modify a watermark, you do not need to specify all attributes. Set the watermark attribute that you want to modify.

NOTE

For information about the watermark attribute names, see Creating Watermarks.

Update the watermark

After you modify a watermark’s attributes, you must update the watermark.

See also

Creating Watermarks

Modify watermarks using the Java API modify-watermarks-using-the-java-api

Modify a watermark by using the Document Security API (Java):

Include project files.

Include client JAR files, such as the adobe-rightsmanagement-client.jar, in your Java project’s class path.
Create a Document Security Client API object.
- Create a ServiceClientFactory object that contains connection properties.
- Create a DocumentSecurityClient object by using its constructor and passing the ServiceClientFactory object.
Retrieve the watermark to modify.

Create a WatermarkManager object by invoking the DocumentSecurityClient object’s getWatermarkManager method and pass a string value that specifies the watermark name. This method returns a Watermark object that represents the watermark to modify.

Set the watermark attributes.

Set the watermark’s opacity attribute by invoking the Watermark object’s setOpacity method and passing an integer value that specifies the opacity level. A value of 100 indicates the watermark is completely opaque and a value of 0 indicates the watermark is completely transparent.

note note
NOTE
This example modifies only the opacity attribute.

Update the watermark.
- Update the watermark by invoking the WatermarkManager object’s updateWatermark method and pass the Watermark object whose attribute was modified.

Code examples

For code examples using the Document Security service, see the Quick Start(SOAP mode): Modifying a watermark using the Java API section.

Modify watermarks using the web service API modify-watermarks-using-the-web-service-api

Modify a watermark by using the Document Security API (web service):

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 note
NOTE
Replace `localhost` with the IP address of the server hosting AEM Forms.

Create a Document Security Client API object.
- Create a DocumentSecurityServiceClient 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 AEM Forms service (for example, http://localhost:8080/soap/services/DocumentSecurityService?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 DocumentSecurityServiceClient.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 DocumentSecurityServiceClient.ClientCredentials.UserName.UserName.
  - Assign the corresponding password value to the field DocumentSecurityServiceClient.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.
Retrieve the watermark to modify.

Retrieve the watermark to modify by invoking the DocumentSecurityServiceClient object’s getWatermarkByName method. Pass a string value that specifies the watermark name. This method returns a WatermarkSpec object that represents the watermark to modify.
Set the watermark attributes.
- For each watermark property to update, create a separate MyMapOf_xsd_string_To_xsd_anyType_Item object.
- Set the key value by assigning a value to the MyMapOf_xsd_string_To_xsd_anyType_Item object’s key data member (for example, WaterBackCmd:OPACITY).
- Set the value by assigning a value to the MyMapOf_xsd_string_To_xsd_anyType_Item object’s value data member (for example, .50).
- Create a MyArrayOf_xsd_anyType object. For each MyMapOf_xsd_string_To_xsd_anyType_Item object, invoke the MyArrayOf_xsd_anyType object’s Add method. Pass the MyMapOf_xsd_string_To_xsd_anyType_Item object.
- Assign the MyArrayOf_xsd_anyType object to the WatermarkSpec object’s values data member.
Update the watermark.

Update the watermark by invoking the DocumentSecurityServiceClient object’s updateWatermark method and passing the WatermarkSpec object that represents the watermark to modify.

Code examples

For code examples using the Document Security service, see the following Quick Start:

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

Searching for Events searching-for-events

The Rights Management service tracks specific actions as they occur, such as applying a policy to a document, opening a policy-protected document, and revoking access to documents. Event auditing must be enabled for the Rights Management service or events are not tracked.

Events fall into one of the following categories:

Administrator events are actions related to an administrator, such as creating a new administrator account.
Document events are actions related to a document, such as closing a policy-protected document.
Policy events are actions related to a policy, such as creating a new policy.
Service events are actions related to the Rights Management service, such as synchronizing with the user directory.

You can search for specify specific events by using the Rights Management Java API or web service API. By searching for events, you can perform tasks, such as creating a log file of certain events.

NOTE

For more information about the Rights Management service, see Services Reference for AEM Forms.

Summary of steps summary_of_steps-10

To search for a Rights Management event, perform the following steps:

Include project files.
Create a Rights Management Client API object.
Specify the event for which to search.
Search for the event.

Include project files

Create a Rights Management Client API object

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

Specify the events to search for

You must specify the event to search for. For example, you can search for the policy create event, which occurs when a new policy is created.

Search for the event

After you specify the event to search for, you can use either the Rights Management Java API or the Rights Management web service API to search for the event.

See also

Search for events using the Java API search-for-events-using-the-java-api

Search for events by using the Rights Management API (Java):

Include project files

Include client JAR files, such as adobe-rightsmanagement-client.jar, in your Java project’s class path.
Create a Rights Management Client API object

Create a DocumentSecurityClient object by using its constructor and passing a ServiceClientFactory object that contains connection properties.

Specify the events to search for

Create an EventManager object by invoking the DocumentSecurityClient object’s getEventManager method. This method returns an EventManager object.
Create an EventSearchFilter object by invoking its constructor.
Specify the event for which to search by invoking the EventSearchFilter object’s setEventCode method and passing a static data member that belongs to the EventManager class that represents the event for which to search. For example, to search for the policy create event, pass EventManager.POLICY_CREATE_EVENT.

note note
NOTE
You can define additional search criteria by invoking `EventSearchFilter` object methods. For example, invoke the `setUserName` method to specify a user associated with the event.

Search for the event

Search for the event by invoking the EventManager object’s searchForEvents method and passing the EventSearchFilter object that defines the event search criteria. This method returns an array of Event objects.

Code examples

For code examples using the Rights Management service, see the following Quick Starts:

“Quick Start (SOAP): Searching for events using the Java API”

Search for events using the web service API search-for-events-using-the-web-service-api

Search for events by using the Rights Management API (web service):

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 note
NOTE
Replace `localhost` with the IP address of the server hosting AEM Forms.

Create a Rights Management Client API object
- Create a DocumentSecurityServiceClient object by using its default constructor.
- Create a DocumentSecurityServiceClient.Endpoint.Address object by using the System.ServiceModel.EndpointAddress constructor. Pass a string value that specifies the WSDL to the AEM Forms 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 DocumentSecurityServiceClient.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 DocumentSecurityServiceClient.ClientCredentials.UserName.UserName.
  - Assign the corresponding password value to the field DocumentSecurityServiceClient.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.

Specify the events to search for

Create an EventSpec object by using its constructor.
Specify the start of the time period during which the event occurred by setting the EventSpec object’s firstTime.date data member with DataTime instance that represents the start of the date range when the event occurred.
Assign the value true to the EventSpec object’s firstTime.dateSpecified data member.
Specify the end of the time period during which the event occurred by setting the EventSpec object’s lastTime.date data member with DataTime instance that represents the end of the date range when the event occurred.
Assign the value true to the EventSpec object’s lastTime.dateSpecified data member.
Set the event to search for by assigning a string value to the EventSpec object’s eventCode data member. The following table lists the numeric values that you can assign to this property:

table 0-row-2 1-row-2 2-row-2 3-row-2 4-row-2 5-row-2 6-row-2 7-row-2 8-row-2 9-row-2 10-row-2 11-row-2 12-row-2 13-row-2 14-row-2 15-row-2 16-row-2 17-row-2 18-row-2 19-row-2 20-row-2 21-row-2 22-row-2 23-row-2 24-row-2 25-row-2 26-row-2 27-row-2 28-row-2 29-row-2 30-row-2 31-row-2 32-row-2 33-row-2 34-row-2 35-row-2 36-row-2 37-row-2 38-row-2 39-row-2 40-row-2 41-row-2 42-row-2 43-row-2 44-row-2 45-row-2 46-row-2 47-row-2
Event type	Value
`ALL_EVENTS`	999
`USER_CHANGE_PASSWORD_EVENT`	1000
`USER_REGISTER_EVENT`	1001
`USER_PREREGISTER_EVENT`	1002
`USER_ACTIVATE_EVENT`	1003
`USER_DEACTIVATE_EVENT`	1004
`USER_AUTHENTICATE_EVENT`	1005
`USER_AUTHENTICATE_DENY_EVENT`	1006
`USER_ACCOUNT_LOCK_EVENT`	1007
`USER_DELETE_EVENT`	1008
`USER_UPDATE_PROFILE_EVENT`	1009
`DOCUMENT_VIEW_EVENT`	2000
`DOCUMENT_PRINT_LOW_EVENT`	2001
`DOCUMENT_PRINT_HIGH_EVENT`	2002
`DOCUMENT_SIGN_EVENT`	2003
`DOCUMENT_ADD_ANNOTATION_EVENT`	2004
`DOCUMENT_FORM_FILL_EVENT`	2005
`DOCUMENT_CLOSE_EVENT`	2006
`DOCUMENT_MODIFY_EVENT`	2007
`DOCUMENT_CHANGE_SECURITY_HANDLER_EVENT`	2008
`DOCUMENT_SWITCH_POLICY_EVENT`	2009
`DOCUMENT_REVOKE_EVENT`	2010
`$1`	2011
`DOCUMENT_SECURE_EVENT`	2012
`DOCUMENT_UNKNOWN_CLIENT_EVENT`	2013
`DOCUMENT_CHANGE_REVOKE_URL_EVENT`	2014
`POLICY_CHANGE_EVENT`	3000
`POLICY_ENABLE_EVENT`	3001
`POLICY_DISABLE_EVENT`	3002
`POLICY_CREATE_EVENT`	3003
`POLICY_DELETE_EVENT`	3004
`POLICY_CHANGE_OWNER_EVENT`	3005
`SERVER_CLIENT_SYNC_EVENT`	4000
`SERVER_SYNC_DIR_INFO_EVENT`	4001
`SERVER_SYNC_DIR_COMPLETE_EVENT`	4002
`SERVER_VERSION_MISMATCH_EVENT`	4003
`SERVER_CONFIG_CHANGE_EVENT`	4004
`SERVER_ENABLE_OFFLINE_ACCESS_EVENT`	4005
`ADMIN_ADD_EVENT`	5000
`ADMIN_DELETE_EVENT`	5001
`ADMIN_EDIT_EVENT`	5002
`ADMIN_ACTIVATE_EVENT`	5003
`ADMIN_DEACTIVATE_EVENT`	5004
`ERROR_DIRECTORY_SERVICE_EVENT`	6000
`CREATED_POLICYSET_EVENT`	7000
`DELETED_POLICYSET_EVENT`	7001
`MODIFIED_POLICYSET_EVENT`	7002

Search for the event

Search for the event by invoking the DocumentSecurityServiceClient object’s searchForEvents method and passing the EventSpec object that represents the event for which to search and the maximum number of results. This method returns a MyArrayOf_xsd_anyType collection where each element is an AuditSpec instance. Using an AuditSpec instance, you can obtain information about the event such as the time that it occurred. The AuditSpec instance contains a timestamp data member that specifies this information.

Code examples

For code examples using the Rights Management service, see the following Quick Starts:

“Quick Start (MTOM): Searching for events using the web service API”
“Quick Start (SwaRef): Searching for events using the web service API”

See also

Applying Policies to Word Documents applying-policies-to-word-documents

In addition to PDF documents, the Rights Mangement service supports additional document formats such as a Microsoft Word document (DOC file) and other Micosoft office file formats. For example, you can apply a policy to a Word document in order to secure it. By applying a policy to a Word document, you restrict access to the document. You cannot apply a policy to a document if the document is already secured with a policy.

You can monitor the use of a policy-protected Word document after you distribute it. That is, you can see how the document is being used and who is using it. For example, you can find out when somebody has opened the document.

NOTE

For more information about the Document Security service, see Services Reference for AEM Forms.

Summary of steps summary_of_steps-11

To apply a policy to a Word document, perform the following steps:

Include project files.
Create a Document Security Client API object.
Retrieve a Word document to which a policy is applied.
Apply an existing policy to the Word document.
Save the policy-protected Word document.

Include project files

Create a Document Security Client APIobject

Before you can programmatically perform a Document Security service operation, you must create a Document Security service client object.

Retrieve a Word document

You must retrieve a Word document in order to apply a policy. After you apply a policy to the Word document, users are restricted when using the document. For example, if the policy does not enable the document to be opened while offline, then users must be online to open the document.

Apply an existing policy to the Word document

To apply a policy to a Word document, you must reference an existing policy and specify which policy set the policy belongs to. The user who is setting the connection properties must have access to the specified policy. If not, an exception occurs.

Save the Word document

After the Document Security service applies a policy to a Word document, you can save the policy-protected Word document as a DOC file.

See also

Revoking Access to Documents

Apply a policy to a Word document using the Java API apply-a-policy-to-a-word-document-using-the-java-api

Apply a policy to a Word document by using the Document Security API (Java):

Include project files.

Include client JAR files, such as adobe-rightsmanagement-client.jar, in your Java project’s class path.
Create a Document Security Client API object.
- Create a ServiceClientFactory object that contains connection properties.
- Create a DocumentSecurityClient object by using its constructor and passing the ServiceClientFactory object.
Retrieve a Word document.
- Create a java.io.FileInputStream object that represents the Word document by using its constructor and passing a string value that specifies the location of the Word document.
- Create a com.adobe.idp.Document object by using its constructor and passing the java.io.FileInputStream object.
Apply an existing policy to the Word document.
- Create a DocumentManager object by invoking the DocumentSecurityClient object’s getDocumentManager method.
- Apply a policy to the Word document by invoking the DocumentManager object’s protectDocument method and passing the following values:
  - The com.adobe.idp.Document object that contains the Word document to which the policy is applied.
  - A string value that specifies the name of the document.
  - A string value that specifies the name of the policy set to which the policy belongs. You can specify a null value that results in the MyPolicies policy set being used.
  - A string value that specifies the policy name.
  - A string value that represents the name of the user manager domain of the user who is the publisher of the document. This parameter value is optional and can be null (if this parameter is null, then the next parameter value must be null).
  - A string value that represents the name of the canonical name of the user manager user who is the publisher of the document. This parameter value is optional and can be null (if this parameter is null, then the previous parameter value must be null).
  - A com.adobe.livecycle.rightsmanagement.Locale that represents the locale that is used for selecting the MS Office template. This parameter value is optional and you can specify null.
  The protectDocument method returns a RMSecureDocumentResult object that contains the policy-protected Word document.
Save the Word document.
- Invoke the RMSecureDocumentResult object’s getProtectedDoc method to get the policy-protected Word document. This method returns a com.adobe.idp.Document object.
- Create a java.io.File object and ensure that the file extension is DOC.
- Invoke the com.adobe.idp.Document object’s copyToFile method to copy the contents of the Document object to the file (ensure that you use the Document object that was returned by the getProtectedDoc method).

Code examples

For code examples using the Document Security service, see the following Quick Start:

“Quick Start (SOAP mode): Applying a policy to a Word document using the Java API”

Apply a policy to a Word document using the web service API apply-a-policy-to-a-word-document-using-the-web-service-api

Apply a policy to a Word document by using the Document Security API (web service):

Include project files.

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

note note
NOTE
Replace `localhost` with the IP address of the server hosting AEM Forms.

Create a Document Security Client API object.
- Create a DocumentSecurityServiceClient object by using its default constructor.
- Create a DocumentSecurityServiceClient.Endpoint.Address object by using the System.ServiceModel.EndpointAddress constructor. Pass a string value that specifies the WSDL to the AEM Forms service (for example, http://localhost:8080/soap/services/DocumentSecurityService?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 DocumentSecurityServiceClient.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 DocumentSecurityServiceClient.ClientCredentials.UserName.UserName.
  - Assign the corresponding password value to the field DocumentSecurityServiceClient.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.
Retrieve a Word document.
- Create a BLOB object by using its constructor. The BLOB object is used to store a Word document to which a policy is applied.
- Create a System.IO.FileStream object by invoking its constructor and passing a string value that represents the file location of the Word document and the mode in which to open the file.
- Create a byte array that stores the content of the System.IO.FileStream object. Determine the byte array size by getting the System.IO.FileStream object’s Length property.
- Populate the byte array with stream data by invoking the System.IO.FileStream object’s Read method. Pass the byte array, the starting position, and the stream length to read.
- Populate the BLOB object by assigning its MTOM field with the contents of the byte array.
Apply an existing policy to the Word document.

Apply a policy to the Word document by invoking the DocumentSecurityServiceClient object’s protectDocument method and passing the following values:
- The BLOB object that contains the Word document to which the policy is applied.
- A string value that specifies the name of the document.
- A string value that specifies the name of the policy set to which the policy belongs. You can specify a null value that results in the MyPolicies policy set being used.
- A string value that specifies the policy name.
- A string value that represents the name of the user manager domain of the user who is the publisher of the document. This parameter value is optional and can be null (if this parameter is null, then the next parameter value must be null).
- A string value that represents the name of the canonical name of the user manager user who is the publisher of the document. This parameter value is optional and can be null (if this parameter is null, then the previous parameter value must be null).
- A RMLocale value that specifies the locale value (for example, RMLocale.en).
- A string output parameter that is used to store the policy identifier value.
- A string output parameter that is used to store the policy-protected identifier value.
- A string output parameter that is used to store the mime type (for example, application/doc).
The protectDocument method returns a BLOB object that contains the policy-protected Word document.
Save the Word document.
- Create a System.IO.FileStream object by invoking its constructor and passing a string value that represents the file location of the policy-protected Word document.
- Create a byte array that stores the data content of the BLOB object that was returned by the protectDocument method. Populate the byte array by getting the value of the BLOB object’s MTOM data member.
- Create a System.IO.BinaryWriter object by invoking its constructor and passing the System.IO.FileStream object.
- Write the contents of the byte array to a Word file by invoking the System.IO.BinaryWriter object’s Write method and passing the byte array.

Code examples

For code examples using the Document Security service, see the following Quick Start:

“Quick Start (MTOM): Applying a policy to a Word document using the web service API ”

Removing Policies from Word Documents removing-policies-from-word-documents

You can remove a policy from a policy-protected Word document in order to remove security from the document. That is, if you no longer want the document to be protected by a policy. If you want to update a policy-protected Word document with a newer policy, then instead of removing the policy and adding the updated policy, it is more efficient to switch the policy.

NOTE

For more information about the Document Security service, see Services Reference for AEM Forms.

Summary of steps summary_of_steps-12

To remove a policy from a policy-protected Word document, perform the following steps:

Include project files
Create a Document Security Client API object.
Retrieve a policy-protected Word document.
Remove the policy from the Word document.
Save the unsecured Word document.s

Include project files

Create a Document Security Client API object

Before you can programmatically perform a Document Security service operation, create a Document Security service client object.

Retrieve a policy-protected Word document

You must retrieve a policy-protected Word document in order to remove a policy. If you attempt to remove a policy from a Word document that is not protected by a policy, you will cause an exception.

Remove the policy from the Word document

You can remove a policy from a policy-protected Word document provided that an administrator is specified in the connection settings. If not, then the policy used to secure a document must contain the SWITCH_POLICY permission in order to remove a policy from a Word document. Also, the user specified in the AEM Forms connection settings must also have that permission. Otherwise, an exception is thrown.

Save the unsecured Word document

After the Document Security service removes a policy from a Word document, you can save the unsecured Word document as a DOC file.

See also

Applying Policies to Word Documents

Remove a policy from a Word document using the Java API remove-a-policy-from-a-word-document-using-the-java-api

Remove a policy from a policy-protected Word document by using the Document Security API (Java):

Include project files

Include client JAR files, such as adobe-rightsmanagement-client.jar, in your Java project’s class path.
Create a Document Security Client API object
- Create a ServiceClientFactory object that contains connection properties.
- Create a RightsManagementClient object by using its constructor and passing the ServiceClientFactory object.
Retrieve a policy-protected Word document
- Create a java.io.FileInputStream object that represents the policy-protected Word document by using its constructor and passing a string value that specifies the location of the Word document.
- Create a com.adobe.idp.Document object by using its constructor and passing the java.io.FileInputStream object.
Remove the policy from the Word document
- Create a DocumentManager object by invoking the RightsManagementClient object’s getDocumentManager method.
- Remove a policy from the Word document by invoking the DocumentManager object’s removeSecurity method and passing the com.adobe.idp.Document object that contains the policy-protected Word document. This method returns a com.adobe.idp.Document object that contains an unsecured Word document.
Save the unsecured Word document
- Create a java.io.File object and ensure that the file extension is DOC.
- Invoke the Document object’s copyToFile method to copy the contents of the Document object to the file (ensure that you use the Document object that was returned by the removeSecurity method).

Code examples

For code examples using the Document Security service, see the following Quick Start:

“Quick Start (SOAP mode): Removing a policy from a Word document using the Java API ”

Remove a policy from a Word document using the web service API remove-a-policy-from-a-word-document-using-the-web-service-api

Remove a policy from a policy-protected Word document by using the Document Security API (web service):

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 note
NOTE
Replace `localhost` with the IP address of the server hosting AEM Forms.

Create a Document Security 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 AEM Forms 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.
Retrieve a policy-protected Word document
- Create a BLOB object by using its constructor. The BLOB object is used to store the policy-protected Word document from which the policy is removed.
- Create a System.IO.FileStream object by invoking its constructor and passing a string value that represents the file location of the Word document and the mode in which to open the file.
- Create a byte array that stores the content of the System.IO.FileStream object. You can determine the size of the byte array by getting the System.IO.FileStream object’s Length property.
- Populate the byte array with stream data by invoking the System.IO.FileStream object’s Read method and passing the byte array, the starting position, and the stream length to read.
- Populate the BLOB object by assigning its MTOM field with the contents of the byte array.
Remove the policy from the Word document

Remove the policy from the Word document by invoking the RightsManagementServiceClient object’s removePolicySecurity method and passing the BLOB object that contains the policy-protected Word document. This method returns a BLOB object that contains an unsecured Word document.
Save the unsecured Word document
- Create a System.IO.FileStream object by invoking its constructor and passing a string value that represents the file location of the unsecured Word document.
- Create a byte array that stores the data content of the BLOB object that was returned by the removePolicySecurity method. Populate the byte array by getting the value of the BLOB object’s MTOM field.
- Create a System.IO.BinaryWriter object by invoking its constructor and passing the System.IO.FileStream object.

Code examples

For code examples using the Document Security service, see the following Quick Start:

“Quick Start (MTOM): Removing a policy from a Word document using the web service API”

See also