Adding Email Endpoints

You can programmatically add an Email endpoint to a service by using the LiveCycle Java API. By adding an Email endpoint, you enable users to send an email message with one or more file attachments to a specified email account. Then the configure service operation is invoked and manipulates the files. After the service performs the specified operation, it sends an email message to the sender with the modified files as file attachments.

For the purposes of programmatically adding an Email endpoint to a service, consider the following short-lived process named MyApplication\EncryptDocument. For information about short-lived processes, see Understanding LiveCycle Processes.

This process accepts an unsecured PDF document as an input value and then passes the unsecured PDF document to the Encryption service’s EncryptPDFUsingPassword operation. This process encrypts the PDF document with a password and returns the password-encrypted PDF document as the output value. The name of the input value (the unsecured PDF document) is InDoc and the data type is com.adobe.idp.Document. The name of the output value (the password-encrypted PDF document) is SecuredDoc and the data type is com.adobe.idp.Document.

Remarque : You cannot add an Email endpoint by using web services.

Summary of steps

To add an Email endpoint to a service, perform the following tasks:

  1. Include project files.

  2. Create an EndpointRegistryClient object.

  3. Set Email endpoint attributes.

  4. Specify configuration values.

  5. Define input parameter values.

  6. Define an output parameter value.

  7. Create the Email endpoint.

  8. Enable the endpoint.

Include project files

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

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

  • adobe-livecycle-client.jar

  • adobe-usermanager-client.jar

  • adobe-utilities.jar (required if LiveCycle is deployed on JBoss Application Server)

  • jbossall-client.jar (required if LiveCycle is deployed on JBoss Application Server)

For information about the location of these JAR files, see Including LiveCycle Java library files.

Create an EndpointRegistry Client object

Before you can programmatically add an Email endpoint, you must create an EndpointRegistryClient object.

Set Email endpoint attributes

To create an Email endpoint for a service, specify the following values:

  • Connector identifier value: Specifies the type of endpoint that is created. To create an Email endpoint, specify Email.

  • Description: Specifies a description for the endpoint.

  • Name: Specifies the name of the endpoint.

  • Service identifier value: Specifies the service to which the endpoint belongs. For example, to add an Email endpoint to the process that is introduced in this section (a process becomes a service when activated using Workbench), specify EncryptDocument.

  • Operation name: Specifies the name of the operation that is invoked by using the endpoint. Typically, when creating an Email endpoint for a service that originated from a process created in Workbench, the name of the operation is invoke.

Specify configuration values

You must specify configuration values for an Email endpoint when programmatically adding an Email endpoint to a service. These configuration values are specified by an administrator if an Email endpoint is added using Administration Console.

Important : The email account that is monitored is a special account that is used for the Email endpoint only. This account is not a regular user's email account. A regular user’s email account must not be configured as the account that the Email Provider uses because the Email Provider deletes email messages from the inbox after it is finished with the messages.

The following configuration values are set when programmatically adding an Email endpoint to a service:

  • cronExpression: A cron expression if the email must be scheduled by using a cron expression.

  • repeatCount: Number of times the email endpoint scans the folder or directory. A value of -1 indicates indefinite scanning. The default value is -1.

  • repeatInterval: The scanning rate in seconds that the receiver uses for checking for incoming mail. The default value is 10.

  • startDelay: The time to wait to scan after the scheduler starts. The default time is 0.

  • batchSize: The number of email messages the receiver processes per scan for optimum performance. A value of -1 indicates all emails. The default value is 2.

  • userName: The user name used when invoking a target service from email. The default value is SuperAdmin.

  • domainName: A mandatory configuration value. The default value is DefaultDom.

  • domainPattern: Specifies the domain patterns of incoming email that the provider accepts. For example, if adobe.com is used, only email from adobe.com is processed, email from other domains is ignored.

  • filePattern: Specifies the incoming file attachment patterns that the provider accepts. This includes files that have specific file name extensions (*.dat, *.xml), files that have specific names (data), and files that have composite expressions in the name and extension (*.[dD][aA][Tt]). The default value is *.

  • recipientSuccessfulJob: An email address to which messages are sent to indicate successful jobs. By default, a successful job message is always sent to the sender. If you type sender, email results are sent to the sender. Up to 100 recipients are supported. Specify additional recipients with email addresses, each one separated by a comma. To turn off this option, leave this value blank. In some cases, you may want to trigger a process and do not want an email notification of the result. The default value is sender.

  • recipientFailedJob: An email address to which messages are sent to indicate failed jobs. By default, a failed job message is always sent to the sender. If you type sender, email results are sent to the sender. Up to 100 recipients are supported. Specify additional recipients with email addresses, each one separated by a comma. To turn off this option, leave this value blank. The default value is sender.

  • inboxHost: The inbox host name or IP address for the email provider to scan.

  • inboxPort: The port that the email server uses. The default value for POP3 is 110 and the default value for IMAP is 143. If SSL is enabled, the default value for POP3 is 995 and the default value for IMAP is 993.

  • inboxProtocol: The email protocol for the email endpoint to use to scan the inbox. The options are IMAP or POP3. The inbox host mail server must support these protocols.

  • inboxTimeOut: Time-out in seconds for the email provider to wait for inbox responses. The default value is 60.

  • inboxUser: The user name required to log in to the email account. Depending on the email server and configuration, this may only be the user name portion of the email or it may be the full email address.

  • inboxPassword: The password for the inbox user.

  • inboxSSLEnabled: Set this value to force the email provider to use SSL when sending notification messages of results or errors. Ensure the IMAP or POP3 host supports SSL.

  • smtpHost: The host name of the mail server that the email provider sends results and error messages to.

  • smtpPort: The default value for the SMTP port is 25.

  • smtpUser: The user account for the email provider to use when it sends out email notifications of results and errors.

  • smtpPassword: The password for the SMTP account. Some mail servers do not require an SMTP password.

  • charSet: The character set used by the email provider. The default value is UTF-8.

  • smtpSSLEnabled: Set this value to force the email provider to use SSL when sending notification messages of results or errors. Ensure that the SMTP Host supports SSL.

  • failedJobFolder: Specifies a directory in which to store results when the SMTP mail server is not operational.

  • asynchronous: When set to synchronous, all input documents are processed and a single response is returned. When set to asynchronous, a response is sent for each input document that is processed. For example, an Email endpoint is created for the process introduced in this topic, and an email message is sent to the endpoint's inbox that contains multiple unsecured PDF documents. When all PDF documents are encrypted with a password, and if the endpoint is configured as synchronous, a single response email message is sent with all secured PDF documents attached. If the endpoint is configured as asynchronous, a separate response email message is sent for each secured PDF document. Each email message contains a single PDF document as an attachment. The default value is asynchronous.

Define input parameter values

When creating an Email endpoint, you must define input parameter values. That is, you must describe the input values that are passed to the operation that is invoked by the Email endpoint. For example, consider the process introduced in this topic. It has one input value named InDoc and its data type is com.adobe.idp.Document. When creating an Email endpoint for this process (after a process is activated, it becomes a service), you must define the input parameter value.

To define input parameter values required for an Email endpoint, specify the following values:

Input parameter name: The name of the input parameter. The name of an input value is specified in Workbench for a process. If the input value belongs to a service operation (a LiveCycle service that is not a process created in Workbench), the input name is specified in the component.xml file. For example, the name of the input parameter for the process introduced in this section is InDoc.

Mapping type: Used to configure the input values required to invoke the service operation. Two types of mapping types are as follows:

  • Literal: The Email endpoint uses the value entered in the field as it is displayed. All basic Java types are supported. For example, if an API uses input such as String, long, int, and Boolean, the string is converted to the proper type and the service is invoked.

  • Variable: The value entered is a file pattern that the Email endpoint uses to pick the input. For example, if you select Variable for the mapping type and the input document must be a PDF file, you can specify *.pdf as the mapping value.

Mapping value: Specifies the value of the mapping type. For example, if you select a Variable mapping type, you can specify *.pdf as the file pattern.

Data type: Specifies the data type of the input values. For example, the data type of the input value of the process introduced in this section is com.adobe.idp.Document.

Define an output parameter value

When creating an Email endpoint, you must define an output parameter value. That is, you must describe the output value that is returned by the service that is invoked by the Email endpoint. For example, consider the process introduced in this topic. It has an output value named SecuredDoc and its data type is com.adobe.idp.Document. When creating an Email endpoint for this process (after a process is activated, it becomes a service), you must define the output parameter value.

To define an output parameter value required for an Email endpoint, specify the following values:

Output parameter name: The name of the output parameter. The name of a process output value is specified in Workbench. If the output value belongs to a service operation (a service that is not a process created in Workbench), the output name is specified in the component.xml file. For example, the name of the output parameter for the process introduced in this section is SecuredDoc.

Mapping type: Used to configure the output of the service and operation. The following options are available:

  • If the service returns a single object (a single document), the pattern is %F.pdf and the source destination is sourcefilename.pdf. For example, the process introduced in this section returns a single document. As a result, the mapping type can be defined as %F.pdf (%F means use the given file name). The pattern %E specifies the extension of the input document.

  • If the service returns a list, the pattern is Result\%F\, and the source destination is Result\sourcefilename\source1 (output 1) and Result\sourcefilename\source2 (output 2).

  • If the service returns a map, the pattern is Result\%F\, and the source destination is Result\sourcefilename\file1 and Result\sourcefilename\file2. If the map has more than one object, the pattern is Result\%F.pdf and the source destination is Result\sourcefilename1.pdf (output 1), Result\sourcefilenam2.pdf (output 2), and so on.

Data type: Specifies the data type of the return value. For example, the data type of the return value of the process introduced in this section is com.adobe.idp.Document.

Create the Email endpoint

After you set the Email endpoint attributes and configuration values, and define input and output parameter values, you must create the Email endpoint.

Enable the endpoint

After you create an Email endpoint, you must enable it. When the endpoint is enabled, it can be used to invoke the service. After you enable the endpoint, you can view it within Administration Console.

Add an Email endpoint using the Java API

Add an Email endpoint by using the Java API:

  1. Include project files.

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

  2. Create an EndpointRegistry Client object.

    • Create a ServiceClientFactory object that contains connection properties.

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

  3. Set Email endpoint attributes.

    • Create a CreateEndpointInfo object by using its constructor.

    • Specify the connector identifier value by invoking the CreateEndpointInfo object’s setConnectorId method and passing the string value Email.

    • Specify the description of the endpoint by invoking the CreateEndpointInfo object’s setDescription method and passing a string value that describes the endpoint.

    • Specify the name of the endpoint by invoking the CreateEndpointInfo object’s setName method and passing a string value that specifies the name.

    • Specify the service to which the endpoint belongs by invoking the CreateEndpointInfo object’s setServiceId method and passing a string value that specifies the service name.

    • Specify the operation that is invoked by invoking the CreateEndpointInfo object’s setOperationName method and passing a string value that specifies the operation name. Typically, when creating an Email endpoint for a service that originated from a process created in Workbench, the name of the operation is invoke.

  4. Specify configuration values.

    For each configuration value to set for the Email endpoint, you must invoke the CreateEndpointInfo object’s setConfigParameterAsText method. For example, to set the smtpHost configuration value, invoke the CreateEndpointInfo object’s setConfigParameterAsText method and pass the following values:

    • A string value that specifies the name of the configuration value. When setting the smtpHost configuration value, specify smtpHost.

    • A string value that specifies the value of the configuration value. When setting the smtpHost configuration value, specify a string value that specifies the name of the SMTP server.

    Remarque : To see all the configuration values set for the EncryptDocument service introduced in this section, see the Java code example located at QuickStart: Adding an Email endpoint using the Java API.
  5. Define input parameter values.

    Define an input parameter value by invoking the CreateEndpointInfo object’s setInputParameterMapping method and pass the following values:

    • A string value that specifies the name of the input parameter. For example, the name of the input parameter for the EncryptDocument service is InDoc.

    • A string value that specifies the data type of the input parameter. For example, the data type of the InDoc input parameter is com.adobe.idp.Document.

    • A string value that specifies the mapping type. For example, you can specify variable.

    • A string value that specifies the mapping type value. For example, you can specify *.pdf as the file pattern.

    Remarque : Invoke the setInputParameterMapping method for each input parameter value to define. Because the EncryptDocument process has only one input parameter, you need to invoke this method once.
  6. Define an output parameter value.

    Define an output parameter value by invoking the CreateEndpointInfo object’s setOutputParameterMapping method and passing the following values:

    • A string value that specifies the name of the output parameter. For example, the name of the output parameter for the EncryptDocument service is SecuredDoc.

    • A string value that specifies the data type of the output parameter. For example, the data type of the SecuredDoc output parameter is com.adobe.idp.Document.

    • A string value that specifies the mapping type. For example, you can specify %F.pdf.

  7. Create the Email endpoint.

    Create the endpoint by invoking the EndpointRegistryClient object’s createEndpoint method and passing the CreateEndpointInfo object. This method returns an Endpoint object that represents the Email endpoint.

  8. Enable the endpoint.

    Enable the endpoint by invoking the EndpointRegistryClient object’s enable method and passing the Endpoint object that was returned by the createEndpoint method.

Email configuration values constant file

The QuickStart: Adding an Email endpoint using the Java API uses a constant file that must be part of your Java project in order to compile the quick start. This constant file represents configuration values that must be set when adding an email endpoint. The following Java code represents the constant file. For information about these configuration values, see Specify configuration values.

/** 
    * This class contains constants that can be used when setting email endpoint  
    * configuration values 
    */ 
public class EmailEndpointConfigConstants { 
     
    public static final String PROPERTY_EMAILPROVIDER_CRON_EXPRESSION = "cronExpression"; 
    public static final String PROPERTY_EMAILPROVIDER_REPREAT_COUNT = "repeatCount"; 
    public static final String PROPERTY_EMAILPROVIDER_REPREAT_INTERVAL = "repeatInterval"; 
    public static final String PROPERTY_EMAILPROVIDER_START_DELAY = "startDelay"; 
    public static final String PROPERTY_EMAILPROVIDER_BATCH_SIZE = "batchSize"; 
    public static final String PROPERTY_EMAILPROVIDER_USERNAME = "userName"; 
    public static final String PROPERTY_EMAILPROVIDER_DOMAINNAME = "domainName"; 
    public static final String PROPERTY_EMAILPROVIDER_DOMAINPATTERN = "domainPattern"; 
    public static final String PROPERTY_EMAILPROVIDER_FILEPATTERN = "filePattern"; 
    public static final String PROPERTY_EMAILPROVIDER_RECIPIENT_SUCCESSFUL_JOB = "recipientSuccessfulJob"; 
    public static final String PROPERTY_EMAILPROVIDER_RECIPIENT_FAILED_JOB = "recipientFailedJob"; 
    public static final String PROPERTY_EMAILPROVIDER_INBOX_HOST = "inboxHost"; 
    public static final String PROPERTY_EMAILPROVIDER_INBOX_PORT = "inboxPort"; 
    public static final String PROPERTY_EMAILPROVIDER_PROTOCOL = "inboxProtocol"; 
    public static final String PROPERTY_EMAILPROVIDER_INBOX_TIMEOUT = "inboxTimeOut"; 
    public static final String PROPERTY_EMAILPROVIDER_INBOX_USER = "inboxUser"; 
    public static final String PROPERTY_EMAILPROVIDER_INBOX_PASSWORD = "inboxPassword"; 
    public static final String PROPERTY_EMAILPROVIDER_INBOX_SSL = "inboxSSLEnabled"; 
    public static final String PROPERTY_EMAILPROVIDER_SMTP_HOST = "smtpHost"; 
    public static final String PROPERTY_EMAILPROVIDER_SMTP_PORT = "smtpPort"; 
    public static final String PROPERTY_EMAILPROVIDER_SMTP_USER = "smtpUser"; 
    public static final String PROPERTY_EMAILPROVIDER_SMTP_PASSWORD = "smtpPassword"; 
    public static final String PROPERTY_EMAILPROVIDER_CHARSET = "charSet"; 
    public static final String PROPERTY_EMAILPROVIDER_SMTP_SSL = "smtpSSLEnabled"; 
    public static final String PROPERTY_EMAILPROVIDER_FAILED_FOLDER = "failedJobFolder"; 
    public static final String PROPERTY_EMAILPROVIDER_ASYNCHRONOUS = "asynchronous"; 
}