Skip Headers

Oracle Application Server InterConnect Adapter for SMTP Installation and User's Guide
10g (9.0.4)

Part Number B10414-01
Go To Documentation Library
Home
Go To Product List
Solution Area
Go To Table Of Contents
Contents
Go To Index
Index

Go to previous page Go to next page

2
Installation and Configuration

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

This chapter contains these topics:

Installing SMTP Adapter

This section contains these topics:

Preinstallation Tasks

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

Consult the following guides before proceeding with SMTP adapter installation:

Installation Tasks

To install the SMTP adapter:

  1. On the Available Product Components page of the OracleAS InterConnect installation, select SMTP adapter, then select Next.

    Consider the following scenarios:

  2. If installing OracleAS InterConnect for the first time on this machine, complete the following steps to enter the hub database information:

    1. On the Welcome page, select Next. The Database Configuration page displays. Enter information in the following fields:

      • Host Name--The host name of the machine where the hub database is installed.

      • Port Number--The TNS listener port for the hub database.

      • Database SID--The SID for the hub database.

    2. Click Next. The Database User Configuration page displays. Enter information in the following fields:

      • User Name--The hub database user name. Make sure the OracleAS InterConnect Hub is installed. If the Hub is not installed, complete the installation and note the user name and password.

      • Password--The password for the hub database user.

  3. Click Next. The Adapter Configuration page displays. Enter the application to be defined or already defined in iStudio in the Application Name field. White spaces or blank spaces are not permitted. The default value is mySMTPApp.

  4. Click Next. The Oracle Application Server InterConnect for SMTP Adapter usage page displays.

  5. 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

    6

    Configure for sending messages ONLY

    6

    Configure for receiving messages ONLY

    8

  6. Enter the following information in the OracleAS InterConnect SMTP Adapter Configuration - Configure sending endpoint information screen:

    • Email Address--The e-mail address of the outgoing SMTP server to which Oracle Application Server InterConnect sends messages. Enter the e-mail address as follows:

      username@hostname
      
      
    • Outgoing Mail Server--The hostname of the outgoing SMTP server to which Oracle Application Server InterConnect sends messages

  7. Click Next.

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

    If You Selected... Then Go to Step...

    Configure for both sending and receiving messages

    8

    Configure for sending messages ONLY

    10

  8. Enter the following information in the OracleAS InterConnect SMTP Adapter Configuration - Configure receiving endpoint information screen:

  9. Click Next.

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

    When finished, the Summary screen appears.

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

    Platform Directory

    Windows

    ORACLE_HOME\oai\9.0.4\adapters\Application

    UNIX

    ORACLE_HOME/oai/9.0.4/adapters/Application

    You have defined the value of Application in Step 3.

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

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.d3ls

    • ota.type

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:

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 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
Platform Directory

UNIX

ORACLE_HOME/oai/9.0.4/adapters/Application

Windows

ORACLE_HOME\oai\9.0.4\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)

Contains one error code per 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 files.

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.

Hub.ini Parameters

The SMTP adapter connects to the hub database using parameters from the hub.ini file located in the hub directory. Table 2-5 lists the parameter name, description, the possible and default values, and example for each parameter

Table 2-5 Hub.ini Parameters
Parameter Description Example

hub_username

The name of the hub database schema (or username). The possible value is a valid hub database username. There is no default value.

hub_username=myhub

hub_password

The password for the hub database user. The possible value is a the valid password for the hub database user. There is no default value.

hub_password=manager

hub_host

The name of the machine hosting the hub database. The possible value is a the valid machine name. There is no default value.

hub_host=mpjoshipc

hub_instance

The valid SID of the hub database. The possible value is a valid SID. There is no default value.

hub_instance=orcl

hub_port

The TNS listener port number for the HUB database instance. The possible value is a TNS listener port number. There is no default value.

hub_port=1521

repository_name

The valid name of the repository this adapter talks to. The possible value is a valid repository name. The default value is InterConnectRepository.

repository_name=InterConnectRepository

RAC-specific Hub.ini Parameters

When a hub is installed on a Real Application Cluster (RAC) database, parameters listed in Table 2-6 represent information on additional nodes used for connection and configuration. These parameters are added on top of the default parameters which represent the primary node. In Table 2-6, x represent the node number, which varies between 2 and the number of nodes. For example, if the RAC setup contains 4 nodes, x can take a value between 2 and 4.

Table 2-6 RAC-specific Hub.ini Parameters
Parameter Description Example

hub_num_nodes

Number of nodes in RAC cluster.

hub_num_nodes=4

hub_hostx

This parameter represents the host where the RAC database is installed.

hub_host2=dsunram13

hub_instancex

This parameter represents the instance on the respective node.

hub_instance2=orcl2

hub_portx

This parameter represents the port where the node has its instance available.

hub_port2=1521

Adapter.ini Parameters

This section contains these topics:

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-7 lists the parameter name, a description for each parameter, the possible and default values, and an example.

Table 2-7 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 OracleAS InterConnect-specific DTD for all messages sent to the hub, as other OracleAS 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 OracleAS InterConnect DTD. Only set this parameter to true if an OracleAS 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 there are a lot of tables 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 OracleAS 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 OracleAS 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 milliseconds. 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 OracleAS InterConnect message. Possible values are any integer greater than or equal to 60000 milliseconds. The default value is 60000.

agent_persistence_retry_interval=60000

agent_pipeline_to_hub

Specifies how to turn on or off the pipeline for messages from the Bridge towards the hub. If you set the pipeline to false, the file persistence is not used in that direction.

agent_pipeline_to_hub=false

agent_pipeline_from_hub

Specifies how to turn on or off the pipeline for messages from the hub towards the Bridge. If you set the pipeline to false, the file persistence is not used in that direction.

agent_pipeline_from_hub=false

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\ora904\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\
ora904\oai\904\lib\
oai.jar;%JREHOME%\lib\rt.jar;D:\oracle\ora904\jdbc\classes12.zip

service_class

Specifies the entry class for the Windows 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

corba_port_number

The CORBA port number on which the adapter CORBA service listens. Generally, this port is allocated dynamically. However, it can be configured to enable access across firewall.

corba_port_number=14000

encoding

Character encoding for published messages. The adapter uses this parameter to generate encoding information in encoding tag of transformed OracleAS InterConnect message. OracleAS InterConnect represents messages internally as an XML document. The default encoding of the XML document is UTF-8. However, this encoding can be configured using this parameter, which is typically used when the OracleAS InterConnect message consists of characters not supported by UTF-8 and when the XMLParser is unable to handle them.

encoding=JA16SJIS

nls_date_format

Format for date fields expressed as string. The default date format is EEE MMM dd HH:mm:ss zzz yyyy. For the meaning of this string, see the list of reserved characters in Table 2-8.

Date format pattern dd/MMM/yyyy can represent 01/01/2003.

nls_date_format=dd-MMM-yy

Multiple date formats can be specified as num_nls_formats=2

nls_date_format1=dd-MMM-yy

nls_date_format2=dd/MMM/yy

nls_country

This parameter is a valid ISO Country Code. These upper-case and two-letter codes are defined by ISO-3166. You can find a full list of these codes at a Web site, such as, http://www.chemie.fu-berlin.de/diverse/doc/ISO_3166.html

The default Country code is US.

Note: This parameter specifies date format. It is applicable for the date format only.

US

nls_language

This parameter is a valid ISO Language Code. These lower-case and two-letter codes are defined by ISO-639. You can find a full list of these codes at a Web site, such as, http://www.ics.uci.edu/pub/ietf/http/related/iso639.txt

The default language code is en.

Note: This parameter specifies date format. It is applicable for the date format only.

nls_language=en

Table 2-8 shows the reserved characters used to specify the value of the nls_date_format parameter. Using these characters, you can construct a pattern to define date formats.

Table 2-8 Reserved Characters for the Value of the nls_date_format Parameter
Letter Description Example

G

Era designator

AD

y

Year

1996; 96

M

Month in year

July; Jul; 07

w

Week in year

27

W

Week in month

2

D

Day in year

189

d

Day in month

10

F

Day of week in month

Number 2

E

Day in week

Tuesday; Tue

a

A.M./P.M. marker

P.M.

H

Hour in day (0-23)

0

k

Hour in day (1-24)

24

K

Hour in A.M/P.M. (0-11)

0

h

Hour in A.M./P.M. (1-12)

12

m

Minute in hour

30

s

Second in minute

55

S

Millisecond

978

G

Era designator

AD

SMTP Adapter-Specific Parameters

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

Table 2-9 SMTP Adapter-Specific Parameters
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.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.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

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

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:joe.one@test.com

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

smtp.sender.subject_rule

Specifies the rule for generating subject. Used by the SMTP sender. The default value is: %APP%%PART%_%TIME%

smtp.sender.subject_rule=Message_from_%APP%_%EVENT%_%TIME%

smtp.sender.customizer_class

Specifies the class name for customization. Used by the SMTP sender. The default value is: oracle.oai.agent.adapter.technology.SMTPDefaultSenderCustomizer

smtp.sender.customizer_class=MySMTPSenderCustomizer

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 be retrieved in each polling session. Possible values are any integers greater than 0. The default value is 30.

smtp.receiver.max_msgs_retrieved=10

smtp.receiver.customizer_class

Specifies the class name for customization. Used by the SMTP receiver. The default value is: oracle.oai.aget.adapter.technology.DefaultReceiverCustomizer

smtp.receiver.customizer_class=MySMTPSenderCustomizer


Go to previous page Go to next page
Oracle
Copyright © 2002, 2003 Oracle Corporation.

All Rights Reserved.
Go To Documentation Library
Home
Go To Product List
Solution Area
Go To Table Of Contents
Contents
Go To Index
Index