2
Installation and Configuration

This chapter describes Simple Mail Transfer Protocol (SMTP) adapter installation and configuration.

This chapter contains these topics:

• Installing SMTP Adapter

• SMTP Adapter Configuration Parameters

Installing SMTP Adapter

This section contains these topics:

• Preinstallation Tasks

• Installation Tasks

• Postinstallation Tasks

Preinstallation Tasks

The SMTP adapter must be installed in one of the following Oracle homes:

• An existing Oracle9i Application Server home

• An existing Oracle9iAS Infrastructure database home

• An existing Oracle9iAS InterConnect home

• A new Oracle home (Oracle Universal Installer creates this Oracle home for you)

Consult the Oracle9i Application Server Installation Guide before proceeding with SMTP adapter installation. This guide includes the following information:

• CD-ROM mounting

• Oracle Universal Installer startup

• Oracle9iAS InterConnect software, hardware, and system requirements

• Oracle9iAS InterConnect installation

  Note: Oracle9iAS InterConnect is installable through the Oracle9iAS InterConnect Hub installation type. You must install the Oracle9iAS InterConnect Hub before proceeding with SMTP adapter installation.

Installation Tasks

To install the SMTP adapter:

1. Click Next on the Welcome screen.

   The File Locations screen appears.

2. Enter the following information in the Destination fields:
   • Name--The Oracle home name

   • Path--The full path to the Oracle home in which to install the SMTP adapter

     Note: Do not change the path specified in the Source field. This is the location on the CD-ROM from which to install the SMTP adapter.

3. Click Next.

   The Installation Types screen appears.

4. Select Oracle9iAS InterConnect Adapters and click Next.

   The Available Product Components screen appears.

5. Select Oracle9iAS InterConnect SMTP Adapter and click Next.

6. If the SMTP adapter is not being installed on the same computer as Oracle9iAS InterConnect and another adapter is not installed in the current Oracle home, the Oracle9iAS InterConnect Hub Database screen appears. Enter the following information about the Oracle9iAS InterConnect Hub to use:
   • Host Name--The hostname of the computer on which Oracle9iAS InterConnect is installed

   • Port Number--The port number of the computer

   • Database SID--The system identifier (SID) of the Oracle9iAS InterConnect Oracle9iAS Metadata Repository

   • Password--The password for the Oracle9iAS Metadata Repository schema

   The Oracle9iAS Metadata Repository stores metadata used by Oracle9iAS InterConnect to coordinate communication between components.

7. Click Next.

   The Oracle9iAS InterConnect SMTP Adapter Configuration screen appears.

8. Enter the name of the application associated with the SMTP adapter. White spaces or blanks are not allowed. This is the same application name created or to be created in iStudio.

9. Click Next.

   The Oracle9iAS InterConnect SMTP Adapter usage screen appears.

10. Select one of the following options and go to the step specified to enable the sending and receiving of messages, the sending of messages only, or the receiving of messages only from an external data source, such as an SMTP server. You can change the values for these selections later by editing parameter settings in the adapter.ini file.

    If You Select...	Then Click Next and Go to Step...
    Configure for both sending and receiving messages	11
    Configure for sending messages ONLY	11
    Configure for receiving messages ONLY	13

11. Enter the following information in the Oracle9iAS InterConnect SMTP Adapter Configuration - Configure sending endpoint information screen:
    • Email Address--The e-mail address of the outgoing SMTP server to which Oracle9iAS InterConnect sends messages. Enter the e-mail address as follows:

      username@hostname
      

    • Outgoing Mail Server--The hostname of the outgoing SMTP server to which Oracle9iAS InterConnect sends messages

12. Click Next.

    The installation screen that appears next is based on the selection you made in Step 10:

    If You Selected...	Then Go to Step...
    Configure for both sending and receiving messages	13
    Configure for sending messages ONLY	15

13. Enter the following information in the Oracle9iAS InterConnect SMTP Adapter Configuration - Configure receiving endpoint information screen:
    • Username--The username account of the IMAP server from which the Oracle9iAS InterConnect receives messages

    • Password--The password for the username account

    • Incoming Mail Server--The hostname of the IMAP server from which Oracle9iAS InterConnect receives messages. This information is required for polling the username account and sending information back to Oracle9iAS InterConnect.

      Caution: For testing purposes, do not specify a personal e-mail account as the receiving endpoint. During runtime, the SMTP adapter connects to the IMAP server and removes messages in the folder specified by the receiving endpoint. Oracle Corporation recommends that you create a dedicated e-mail account for testing and deploying this adapter.

14. Click Next.

15. Complete any other fields for other components selected for installation, such as other adapters.

    When finished, the Summary screen appears.

16. Select Install to install the SMTP adapter. The adapter is installed in the following directory:

    Platform	Directory
    Windows	%ORACLE_HOME%\oai\9.0.2\adapters\Application
    UNIX	$ORACLE_HOME/oai/9.0.2/adapters/Application

    Application is the value you specified in Step 8.

Postinstallation Tasks

SMTP adapter installation creates an adapter.ini file that consists of configuration parameters read by the SMTP adapter at startup. These configuration parameter settings are appropriate for most SMTP application environments. You can customize some adapter.ini file parameter settings for the SMTP application after installation. See the following sections:

• Customizing the Payload Datatype

• Customizing the Sending Endpoints

• Customizing the Receiving Endpoints

  See Also: Table 2-1 for the location of the adapter.ini file Table 2-6 for adapter.ini file parameter setting information specific to the SMTP adapter

Customizing the Payload Datatype

Payload data is the data sent between applications. If you want to change the payload datatype from the default of XML to the data definition description language (D3L), edit the following parameters in the adapter.ini file.

To customize the payload datatype:

1. Set the ota.type parameter to the payload type D3L. For example:

   ota.type=D3L
   

2. Copy the D3L XML files associated with the SMTP application to the directory in which the adapter.ini file is located.

3. Set the ota.d3ls parameter to specify the D3L files associated with the SMTP application. For example:

   ota.d3ls=person1.xml,person2.xml
   

   See Also: The following parameter descriptions for additional information: ota.type ota.d3ls

Customizing the Sending Endpoints

If you want to customize the behavior of the sending endpoints (destinations) for messages, edit the following parameters in the adapter.ini file. These parameters are not automatically set to default values during installation.

To customize the sending endpoint:

1. Set the smtp.sender.content_type parameter to the message content type to use. For example:

   smtp.sender.content_type=plain/text
   

2. Set the smtp.sender.character_set parameter to the message character set to use. For example:

   smtp.sender.character_set=iso-2022-jp
   

   See Also: The following parameter descriptions for additional information: smtp.sender.content_type smtp.sender.character_set

Customizing the Receiving Endpoints

If you want to customize the behavior of the receiving IMAP endpoints for messages, edit the following parameters in the adapter.ini file.

To customize the receiving endpoint:

1. Set the smtp.receiver.exception_folder to the folder name in which to place files that have not been processed successfully. For example:

   smtp.receiver.exception_folder=error_messages
   

   This parameter is not automatically set to a default value during installation. The IMAP administrator must create this folder. Leave this setting blank if you do not want to save these files.

2. Set the smtp.receiver.polling_interval parameter to the time interval in milliseconds during which to poll the IMAP server for messages. This parameter automatically defaults to a value of 10000 during installation. For example:

   smtp.receiver.polling_interval=20000
   

3. Set the smtp.receiver.max_msgs_retrieved parameter to the maximum number of messages to retrieve in a polling session. This parameter automatically defaults to a value of 10 during installation. For example:

   smtp.receiver.max_msgs_retrieved=30
   

   See Also: The following parameter descriptions for additional information: smtp.receiver.exception_folder smtp.receiver.polling_interval smtp.receiver.max_msgs_retrieved

SMTP Adapter Configuration Parameters

Table 2-2, Table 2-3, and Table 2-4 describe SMTP executable files, configuration files, and directories. These files and directories are accessible from the directory shown in Table 2-1.

Table 2-1 SMTP Adapter Directory

On...	Go to...
UNIX	$ORACLE_HOME/oai/9.0.2/adapters/Application
Windows	%ORACLE_HOME%\oai\9.0.2\adapters\Application

Table 2-2 SMTP Executable Files

File	Description
start.bat (Windows) start (UNIX)	Takes no parameters; starts the adapter
stop.bat (Windows) stop (UNIX)	Takes no parameters; stops the adapter
ignoreerrors.bat (Windows) ignoreerrors (UNIX)	If an argument is specified, then the given error code is ignored: ignoreerrors errorCodeToBeIgnored If no argument is specified, then all error codes specified in the ErrorCodes.ini file are ignored: ignoreerrors

See Also: "SMTP Adapter Error Codes" for a list of error codes

Table 2-3 SMTP Configuration Files

File	Description
ErrorCodes.ini (Windows and UNIX)	Should contain one error code for each line
adapter.ini (Windows and UNIX)	Consists of all the initialization parameters that the adapter reads at startup

See Also: Appendix A, "adapter.ini Example File"

Table 2-4 SMTP Directories

Directory	Description
persistence	The messages are persisted (made available) in this directory. Do not edit this directory or its contents.
logs	The logging of adapter activity is done in subdirectories of the logs directory. Subdirectory names take the following form: timestamp_in_milliseconds Each time the adapter is run, a new subdirectory is created in which logging is done in an oailog.txt file.

adapter.ini Initialization Parameter File

This section contains these topics:

• Agent Connection Parameters

• SMTP Adapter-Specific Parameters

Agent Connection Parameters

The agent component of the SMTP adapter reads the adapter.ini file at runtime to access SMTP adapter parameter configuration information. Table 2-5 lists the parameter name, a description for each parameter, the possible and default values, and an example.

Table 2-5 Agent Connection Parameters

Parameter	Description	Example
application	Specifies the name of the application to which this adapter connects. This must match with the name specified in iStudio during creation of metadata. Use any alphanumeric string. There is no default value.	application=smtpapp
partition	Specifies the partition this adapter handles as defined in iStudio. Any alphanumeric string is a possible value. There is no default value.	partition=germany
instance_number	Specifies the instance number to which this adapter corresponds. Specify a value only if you want to have multiple adapter instances for the given application with the given partition. Possible values are any integer greater than or equal to 1. There is no default value.	instance_number=1
agent_log_level	Specifies the amount of logging necessary. Possible values are: 0=errors only 1=status and errors 2=trace, status, and errors The default value is 1.	agent_log_level=2
agent_subscriber_name	Specifies the subscriber name used when this adapter registers its subscription. The possible value is a valid Oracle Advanced Queue subscriber name. There is no default value.	agent_subscriber_name=smtpapp
agent_message_selector	Specifies conditions for message selection when registering its subscription with the hub. The possible value is a valid Oracle Advanced Queue message selector string. There is no default value.	agent_message_selector=recipient_list like '%,aqapp,%'
agent_reply_subscriber_name	Specifies the subscriber name used when multiple adapter instances for the given application with the given partition are used. This parameter is optional if only one instance is running. The possible value is the application name (parameter:application) concatenated with the instance number (parameter:instance_number). There is no default value.	If application=smtpapp and instance_number=2, then agent_reply_subscriber_name=smtpapp2
agent_reply_message_selector	Used only if multiple adapter instances exist for the given application with the given partition. The possible value is a string built using the concatenated application name (parameter:application) with the instance number (parameter:instance_number). There is no default value.	If application=smtpapp and instance_number=2, then agent_reply_message_selector=recipient_list like '%,smtpapp2,%'
agent_tracking_enabled	Specifies if message tracking is enabled. Set this parameter to false to turn off all tracking of messages. Set this parameter to true to track messages with tracking fields set in iStudio. Possible values are true or false. The default value is true.	agent_tracking_enabled=true
agent_throughput_measurement_enabled	Specifies if throughput measurement is enabled. Set this parameter to true to turn on all throughput measurements. Possible values are true or false. The default value is true.	agent_throughput_measurement_enabled=true
agent_use_custom_hub_dtd	Specifies whether to use a custom document type definition (DTD) for the common view message when handing it to the hub (the repository in which metadata is stored). By default, adapters use an Oracle9iAS InterConnect-specific DTD for all messages sent to the hub, as other Oracle9iAS InterConnect adapters retrieve the messages from the hub and know how to interpret them. Set this parameter to true if for every message, the DTD imported for the message of the common view is used instead of the Oracle9iAS InterConnect DTD. Only set this parameter to true if an Oracle9iAS InterConnect adapter is not receiving the messages from the hub. Possible values are true or false. There is no default value.	agent_use_custom_hub_dtd=false
agent_metadata_caching	Specifies the metadata caching algorithm. Possible values are: startup--Cache everything at startup. This may take a while if a lot of metadata is in the repository. demand--Cache metadata as it is used. none--No caching. This slows down performance. The default value is demand.	agent_metadata_caching=demand
agent_dvm_table_caching	Specifies the domain value mapping (DVM) table caching algorithm. Possible values are: startup--Cache all DVM tables at startup. This may take a while if many tables are in the repository. demand--Cache tables as they are used. none--No caching. This slows down performance. The default value is demand.	agent_dvm_table_caching=demand
agent_lookup_table_caching	Specifies the lookup table caching algorithm. Possible values are: startup--Cache all lookup tables at startup. This may take a while if many tables are in the repository. demand--Cache tables as they are used. none--No caching. This slows down performance. The default value is demand.	agent_lookup_table_caching=demand
agent_delete_file_cache_at_startup	With any of the agent caching methods enabled, metadata from the repository is cached locally on the file system. Set this parameter to true to delete all cached metadata on startup. Possible values are true or false. The default value is false. Note: After changing metadata or DVM tables for this adapter in iStudio, you must delete the cache to guarantee access to the new metadata or table information.	agent_delete_file_cache_at_startup=false
agent_max_ao_cache_size	Specifies the maximum number of application objects' metadata to cache. Possible values are any integer greater than or equal to 1. The default value is 200.	agent_max_ao_cache_size=200
agent_max_co_cache_size	Specifies the maximum number of common objects' metadata to cache. Possible values are any integer greater than or equal to 1. The default value is 100.	agent_max_co_cache_size=100
agent_max_message_metadata_cache_size	Specifies the maximum number of messages' metadata (publish/subscribe and invoke/implement) to cache. Possible values are any integer greater than or equal to 1. The default value is 200.	agent_max_message_metadata_cache_size=200
agent_max_dvm_table_cache_size	Specifies the maximum number of DVM tables to cache. Possible values are any integer greater than or equal to 1. The default value is 200.	agent_max_dvm_table_cache_size=200
agent_max_lookup_table_cache_size	Specifies the maximum number of lookup tables to cache. Possible values are any integer greater than or equal to 1. The default value is 200.	agent_max_lookup_table_cache_size=200
agent_max_queue_size	Specifies the maximum size to which internal Oracle9iAS InterConnect message queues can grow. Possible values are any integer greater than or equal to 1. The default value is 1000.	agent_max_queue_size=1000
agent_persistence_queue_size	Specifies the maximum size to which internal Oracle9iAS InterConnect persistence queues can grow. Possible values are any integer greater than or equal to 1. The default value is 1000.	agent_persistence_queue_size=1000
agent_persistence_cleanup_interval	Specifies how often to run the persistence cleaner thread (in milliseconds). Possible values are any integer greater than or equal to 30000. The default value is 60000.	agent_persistence_cleanup_interval=60000
agent_persistence_retry_interval	Specifies how often the persistence thread retries when it fails to send an Oracle9iAS InterConnect message. Possible values are any integer greater than or equal to 60000. The default value is 60000.	agent_persistence_retry_interval=60000
service_path	Windows only. Specifies the value to which to set the environment variable PATH. The PATH variable is set to the specified value before forking the Java VM. Typically, list all directories here that contain all necessary DLLs. Possible values are the valid PATH environment variable setting. There is no default value.	service_path=%JREHOME%\bin;D:\oracle\ora902\bin
service_classpath	Specifies the class path used by the adapter Java VM. If a custom adapter is developed and, as a result, the adapter is to pick up any additional jars, add the jars to the existing set of jars being picked up. Possible values are the valid class path. There is no default value.	service_classpath=D:\oracle\ ora902\oai\902\lib\ oai.jar;%JREHOME%\lib\rt.jar;D:\oracle\ora902\jdbc\classes12.zip
service_class	Specifies the entry class for the Windows NT service. A possible value is oracle/oai/agent/service/AgentService. There is no default value.	service_class=oracle/oai/agent/service/AgentService
service_max_java_stack_size	Windows only. Specifies the maximum size to which the Java VM's stack can grow. Possible values are the valid Java VM maximum native stack size. The default value is the default for the Java VM.	service_max_java_stack_size=409600
service_max_native_stack_size	Windows only. Specifies the maximum size to which the Java VM's native stack can grow. Possible values are the valid Java VM maximum native stack size. The default value is the default for the Java VM.	service_max_native_stack_size=131072
service_min_heap_size	Windows only. Specifies the minimum heap size for the adapter Java VM. Possible values are the valid Java VM heap sizes. The default value is the default Java VM heap size.	service_min_heap_size=536870912
service_max_heap_size	Windows only. Specifies the maximum heap size for the adapter Java VM. Possible values are any valid Java VM heap sizes. The default value is 536870912.	service_max_heap_size=536870912
service_num_vm_args	Windows only. Specifies the number of service_vm_argnumber parameters specified. Possible values are the number of service_vm_argnumber parameters. There is no default value.	service_num_vm_args=1
service_vm_argnumber	Windows only. Specifies any additional arguments to the Java VM. For example, to get line numbers in any of the stack traces, set service_vm_arg1=java.compiler=NONE. If a list of arguments to specify exists, use multiple parameters as shown in the example by incrementing the last digit starting with 1. Be sure to set service_num_vm_args correctly. Possible values are any valid Java VM arguments. There is no default value.	service_vm_arg1=java.compiler=NONE service_vm_arg2=oai.adapter=database

SMTP Adapter-Specific Parameters

Table 2-6 lists the parameters specific to the SMTP adapter.

Table 2-6 SMTP Adapter-Specific Values

Parameter	Description	Example
bridge_class	Specifies the entry class for the SMTP adapter. A value must be specified and cannot be modified later. There is no default value. A possible value is oracle.oai.agent.adapter.technology.TechBridge.	bridge_class=oracle.oai.agent. adapter.technology. TechBridge
ota.send.endpoint	Specifies the sending endpoint URL for the SMTP adapter. There is no default value. The URL is of the form: mailto:username@hostname	ota.send.endpoint=mailto:[e-mail]
smtp.sender.smtp_host	Specifies the SMTP host to use in sending messages.	smtp.sender.smtp_host=smtp1.foo.com
smtp.sender.content_type	Specifies the content type of e-mail messages (RFC 822 header field).	smtp.sender.content_type=plain/text
smtp.sender.character_set	Specifies the character encoding for the message.	smtp.sender.character_set=iso-2022-jp
ota.receive.endpoint	Specifies the receiving endpoint URL for the SMTP adapter. There is no default value. The URL is of the form: imap://username@imapHostName	ota.receive.endpoint=imap://joe@server10
ota.type	Specifies the message type the SMTP adapter handles for both incoming and outgoing messages. The options are XML or D3L. The default value is XML.	ota.type=XML
smtp.receiver.password	User password for the IMAP server. The possible value is a valid password. There is no default value. This password can also be encrypted by running the encrypt tool and renaming this parameter to encrypted_smtp.receiver.password. See Also: "How do I make the adapter.ini file password parameter secure?" for instructions on encrypting the user password	smtp.receiver.password= smtpuser
smtp.receiver.protocol	Specifies the e-mail protocol to use. For this release, the only possible value is imap. There is no default value.	smtp.receiver.protocol= imap
smtp.receiver.exception_folder	Specifies a mail folder in which to put e-mails that cannot be processed successfully. This mail folder must be created by the IMAP server administrator. Possible values are a valid mail folder name. There is no default value.	smtp.receiver.exception_folder=error
smtp.receiver.polling_interval	Specifies the time interval during which to poll the IMAP server (in milliseconds). Possible values are any integers greater than 0. The default value is 60000 (60 seconds).	smtp.receiver.polling_interval=10000
smtp.receiver.max_msgs_retrieved	Specifies the maximum number of messages to retrieve in each polling session. Possible values are any integers greater than 0. The default value is 30.	smtp.receiver.max_msgs_retrieved=10
ota.d3ls	Specifies the list of data definition description language (D3L) XML files used by this bridge. Each business event handled by the bridge must have its own D3L XML file. Whenever a new D3L XML file is imported in iStudio for use by an application using the SMTP adapter, the parameter must be updated and the SMTP adapter restarted. There is no default value.	ota.d3ls=person.xml, person1.xml