|
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.
Note: You cannot add an Email endpoint by using web
services.
Summary of stepsTo add an Email endpoint to a service, perform the following
tasks:
Include project files.
Create an EndpointRegistryClient object.
Set Email endpoint attributes.
Specify configuration values.
Define input parameter values.
Define an output parameter value.
Create the Email endpoint.
Enable the endpoint.
Include project filesInclude 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 objectBefore you can programmatically
add an Email endpoint, you must create an EndpointRegistryClient object.
Set Email endpoint attributesTo 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 valuesYou 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 valuesWhen 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 valueWhen 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 endpointAfter you set the Email endpoint attributes
and configuration values, and define input and output parameter
values, you must create the Email endpoint.
Enable the endpointAfter 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 APIAdd an Email endpoint by using the Java API:
Include project files.
Include client JAR files,
such as adobe-livecycle-client.jar, in your Java project’s class
path.
Create an EndpointRegistry Client object.
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.
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.
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.
Note: 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.
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.
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.
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 fileThe 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";
}
|
|
|
