Creating Search Rules

You can create search rules that result in the Output service examining input data and using different form designs based on the data content to generate output. For example, if the text mortgage is located within the input data, then the Output service can use a form design named Mortgage.xdp. Likewise, if the text automobile is located in the input data, then the Output service can use a form design that is saved as AutomobileLoan.xdp. Although the Output service can generate different output types, this section assumes that the Output service generates a PDF file. The following diagram shows the Output service generating a PDF file by processing an XML data file and using one of many form designs.

View full size graphic

In addition, the Output service is able to generate document packages, where multiple records are provided in the data set and each record is matched to a form design and a single document is generated made up of multiple form designs.

View full size graphic
Note: For more information about the Output service, see Services Reference for LiveCycle.

Summary of steps

To instruct the Output service to use search rules while generating a document, perform the following steps:

  1. Include project files.

  2. Create an Output Client object.

  3. Reference an XML data source.

  4. Define search rules.

  5. Set PDF run-time options.

  6. Set rendering run-time options.

  7. Generate a PDF document.

  8. Retrieve the results of the operation.

Include project files

Include necessary files in 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.

The following JAR files must be added to your project’s classpath:

  • adobe-livecycle-client.jar

  • adobe-usermanager-client.jar

  • adobe-output-client.jar

  • adobe-utilities.jar (Required if LiveCycle is deployed on JBoss)

  • jbossall-client.jar (Required if LiveCycle is deployed on JBoss)

if LiveCycle is deployed on a supported J2EE application server that is not JBoss, then you will need to replace adobe-utilities.jar and jbossall-client.jar with JAR files that are specific to the J2EE application server on which LiveCycle is deployed.

Create an Output Client object

Before you can programmatically perform an Output service operation, you must create an Output service client object.

Reference an XML data source

An XML element must exist for every form field that you want to populate with data. The XML element name must match the field name. An XML element is ignored if it does not correspond to a form field or if the XML element name does not match the field name. It is not necessary to match the order in which the XML elements are displayed, as long as all XML elements are specified.

Define search rules

To define search rules, you define one or more text patterns that the Output services searches for in the input data. For each text pattern that you define, you specify a corresponding form design that is used if the text pattern is located. If a text pattern is located, then the Output service uses the corresponding form design to generate the output. An example of a text pattern is mortgage.

Note: If text patterns are not located, then the default form is used. Make sure that all form designs that you use are located in the content root.

Set PDF run-time options

Set the following PDF run-time options in order for the Output service to successfully create a PDF document based on multiple form designs:

  • File URI: Specifies the name and location of the PDF file that the Output service generates.

  • Rules: Specifies rules that you defined.

  • LookAHead: Specifies the number of bytes to use from the beginning of the input data file to scan for the defined text patterns. The default is 500 bytes.

Set rendering run-time options

You can set rendering run-time options while creating PDF files. Although these options are not required (unlike PDF run-time options), you can perform tasks such as improving the performance of the Output service. For example, you can cache the form design that the Output service uses in order to improve performance.

Generate a PDF document

After you reference a valid XML data source and set run-time options, you can invoke the Output service resulting in it generating a PDF document. If the Output service locates a specified text pattern in the input data, then it uses the corresponding form design. If a text pattern is not used, then the Output service uses the default form design.

Retrieve the results of the operation

After the Output service performs an operation, it returns XML data that specifies whether the operation was successful.

See also

Including LiveCycle Java library files

Setting connection properties

Output Service API Quick Starts

Create search rules using the Java API

Create search rules by using the Output API (Java):

  1. Include project files.

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

  2. Create an Output Client object.

    • Create a ServiceClientFactory object that contains connection properties.

    • Create an OutputClient object by using its constructor and passing the ServiceClientFactory object.

  3. Reference an XML data source.

    • Create a java.io.FileInputStream object that represents the XML data source that is used to populate the PDF document by using its constructor and passing a string value that specifies the location of the XML file.

    • Create a com.adobe.idp.Document object by using its constructor and passing the java.io.FileInputStream object.

  4. Define search rules.

    • Create a Rule object by using its constructor.

    • Define a text pattern by invoking the Rule object’s setPattern method and passing a string value that specifies a text pattern.

    • Define the corresponding form design by invoking the Rule object’s setForm method . Pass a string value that specifies the name of the form design.

    Note: For each text pattern that you want to define, repeat the previous three sub-steps.

    • Create a java.util.List object by using an java.util.ArrayList constructor.

    • For each Rule object that you created, invoke the java.util.List object’s add method and pass the Rule object.

  5. Set PDF run-time options.

    • Create a PDFOutputOptionsSpec object by using its constructor.

    • Specify the name and location of the PDF file that the Output service generates by invoking the PDFOutputOptionsSpec object’s setFileURI method. Pass a string value that specifies the location of the PDF file. The File URI option is relative to the J2EE application server hosting LiveCycle, not the client computer.

    • Set the rules that you defined by invoking the PDFOutputOptionsSpec object’s setRules method. Pass the java.util.List object that contains the Rule objects.

    • Set the number of bytes to scan for the defined text patterns by invoking the PDFOutputOptionsSpec object’s setLookAhead method. Pass an integer value that represents the numbers of bytes.

  6. Set rendering run-time options.

    • Create a RenderOptionsSpec object by using its constructor.

    • Cache the form design in order to improve the performance of the Output service by invoking the RenderOptionsSpec object’s setCacheEnabled and passing true.

  7. Generate a PDF document.

    Generate a PDF document that is based on multiple form designs by invoking the OutputClient object’s generatePDFOutput method and passing the following values:

    • A TransformationFormat enumeration value. To generate a PDF document, specify TransformationFormat.PDF.

    • A string value that specifies the name of the default form design. That is, the form design that is used if a text pattern is not located.

    • A string value that specifies the content root where the form designs are located.

    • A PDFOutputOptionsSpec object that contains PDF run-time options.

    • A RenderOptionsSpec object that contains rendering run-time options.

    • The com.adobe.idp.Document object that contains the form data that is searched by the Output service for the defined text patterns.

    The generatePDFOutput method returns an OutputResult object that contains the results of the operation.

  8. Retrieve the results of the operation.

    • Create a com.adobe.idp.Document object that represents the status of the generatePDFOutput method by invoking the OutputResult object’s getStatusDoc method.

    • Create a java.io.File object that will contain the results of the operation. Ensure that the file extension is .xml.

    • Invoke the com.adobe.idp.Document object’s copyToFile method to copy the contents of the com.adobe.idp.Document object to the file (ensure that you use the com.adobe.idp.Document object that was returned by the getStatusDoc method).

See also

Summary of steps

Quick Start (EJB mode): Creating search rules using the Java API

Quick Start (SOAP mode): Creating search rules using the Java API

Including LiveCycle Java library files

Setting connection properties

Create search rules using the web service API

Create search rules by using the Output 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/OutputService?WSDL&lc_version=9.0.1.

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

  2. Create an Output Client object.

    • Create an OutputServiceClient object by using its default constructor.

    • Create an OutputServiceClient.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/OutputService?blob=mtom.) You do not need to use the lc_version attribute. This attribute is used when you create a service reference. However, specify ?blob=mtom to use MTOM.

    • Create a System.ServiceModel.BasicHttpBinding object by getting the value of the OutputServiceClient.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 LiveCycle user name to the field OutputServiceClient.ClientCredentials.UserName.UserName.

      • Assign the corresponding password value to the field OutputServiceClient.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. Reference an XML data source.

    • Create a BLOB object by using its constructor. The BLOB object is used to store data that will be merged with 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 PDF document to encrypt 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.

  4. Define search rules.

    • Create a Rule object by using its constructor.

    • Define a text pattern by assigning a string value that specifies a text pattern to the Rule object’s pattern data member.

    • Define the corresponding form design by assigning a string value that specifies the form design to the Rule object’s form data member.

    Note: For each text pattern that you want to define, repeat the previous three sub-steps.

    • Create a MyArrayOf_xsd_anyType object that stores the rules.

    • Assign each Rule object to an element of the MyArrayOf_xsd_anyType array. Invoke the MyArrayOf_xsd_anyType object’s Add method for each Rule object.

  5. Set PDF run-time options

    • Create a PDFOutputOptionsSpec object by using its constructor.

    • Set the file URI option by assigning a string value that specifies the location of the PDF file that the Output service generates to the PDFOutputOptionsSpec object’s fileURI data member. The File URI option is relative to the J2EE application server hosting LiveCycle, not the client computer.

    • Set the copies option by assigning an integer value that specifies the number of copies that the Output service generates to the PDFOutputOptionsSpec object’s copies data member.

    • Set the rules that you defined by assigning the MyArrayOf_xsd_anyType object that stores the rules to the PDFOutputOptionsSpec object’s rules data member.

    • Set the number of bytes to scan for the defined text patterns by assigning an integer value that represents the numbers of bytes to scan to the PDFOutputOptionsSpec object’s lookAhead data method.

  6. Set rendering run-time options

    • Create a RenderOptionsSpec object by using its constructor.

    • Cache the form design in order to improve the performance of the Output service by assigning the value true to the RenderOptionsSpec object’s cacheEnabled data member.

    Note: You cannot set the version of the PDF document by using the RenderOptionsSpec object’s pdfVersion member if the input document is an Acrobat form. The output PDF document retains the PDF version of the Acrobat form. Likewise, you cannot set the tagged PDF option by using the RenderOptionsSpec object’s taggedPDF method if the input document is an Acrobat form.
    Note: You cannot set the linearized PDF option by using the RenderOptionsSpec object’s linearizedPDF member if the input PDF document is certified or digitally signed. For information, see Digitally Signing PDF Documents.

  7. Generate a PDF document

    Create a PDF document by invoking the OutputServiceService object’s generatePDFOutput method and passing the following values:

    • A TransformationFormat enumeration value. To generate a PDF document, specify TransformationFormat.PDF.

    • A string value that specifies the name of the form design.

    • A string value that specifies the content root where the form design is located.

    • A PDFOutputOptionsSpec object that contains PDF run-time options.

    • A RenderOptionsSpec object that contains rendering run-time options.

    • The BLOB object that contains the XML data source that contains data to merge with the form design.

    • A BLOB object that is populated by the generatePDFOutput method. The generatePDFOutput method populates this object with generated metadata that describes the document. (This parameter value is required only for web service invocation).

    • A BLOB object that is populated by the generatePDFOutput method. The generatePDFOutput method populates this object with result data. (This parameter value is required only for web service invocation).

    • An OutputResult object that contains the results of the operation. (This parameter value is required only for web service invocation).

    Important: When generating a PDF document by invoking the generatePDFOutput method, be aware that you cannot merge data with an XFA PDF form that is signed, certified, or contains usage rights. For information about usage rights, see Applying Usage Rights to PDF Documents.

  8. Retrieve the results of the operation

    • Create a System.IO.FileStream object by invoking its constructor and passing a string value that represents an XML file location that contains result data. Ensure that the file extension is XML.

    • Create a byte array that stores the data content of the BLOB object that was populated with result data by the OutputServiceService object’s generatePDFOutput method (the eighth parameter). 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 the XML file by invoking the System.IO.BinaryWriter object’s Write method and passing the byte array.

See also

Summary of steps

Quick Start (MTOM): Creating search rules using the web service API

Quick Start (SwaRef): Creating search rules using the web service API

Invoking LiveCycle using MTOM

Invoking LiveCycle using SwaRef

// Ethnio survey code removed