Please note the following points before setting mail adapters.

• Set a valid address for the destination of a mail adapter.
• If you set an invalid address for a mail adapter, all emails sent to that address are bounced by the mail server function.
• If you use a file forwarded from an FTP client or FTP server as an attachment, linkage with the FTP inbound adapter, FTP reception, and FTP adapter is required in addition to linkage with the mail adapter. For details about the function for linking with FTP, see Chapter 8. Functionality to Transfer Files by Integrating with FTP (FTP Integration) in the manual Service Platform Overview.

The following shows the types and forms of the message formats used by mail adapters.

(a) Message format type

Mail adapters use either of the following two message formats:

• Request message format
• Response message format

For the request message format, set the mail server information or user input information (such as the email body, address, and subject). For the response message format, the message ID of the sent mail is set.

A mail adapter uses the XML schema provided by the service platform as the message format. The XML schemata used for request messages and response messages are adpmail_smtp_request.xsd and adpmail_smtp_response.xsd, respectively.

(b) Message format

The following describes the request message format and response message format used by mail adapters.

The files are stored in installation-directory-of-the-service-platform\CSC\schema\mail.

adpmail_smtp_request.xsd (request message format file)

The format of the request message passed to the mail adapter when the mail adapter is called from a business process is shown below. The name space name is http://www.hitachi.co.jp/soft/xml/cosminexus/csc/adapter/mail/send_request.

Table 3-66 Request message format

Tag name					Number of occurrences	Description
<request>					Once	--
	<smtp-host-name>				0 or once	A tag that indicates the IP address or host name of the mail server to connect with. When the tag and the value exist: Connection is performed by using the specified character string. When the tag exists but the value does not exist: A system exception is returned. When the tag does not exist: The value in the mail adapter runtime environment property file becomes valid.
	<request-id>				0 or once	A tag that indicates the request ID created at the reception. When the tag and the value exist: The value is used as the request ID. When the tag does not exist, or when the tag exists but the value does not exist: If a work folder is used, a system exception is returned. If the common folder is used, this tag is ignored.
	<smtp-port>				0 or once	A tag that indicates the port number of the mail server to connect with. When the tag and the value exist: Specify a port number in the range from 1 to 65535. If you specify a value outside this range, a system exception is returned. When the tag exists but the value does not exist: The default value 25 is specified. When the tag does not exist: The value in the mail adapter runtime environment property file becomes valid. If this tag is also not specified in the mail adapter runtime environment property file, the default value 25 is specified.
	<mail-user>				0 or once	A tag that indicates the login user name of the mail server to connect with. When the tag and the value exist: Characters specified in the range from 0x20 to 0x7E are valid. If you specify characters outside this range, a system exception is returned. When the tag exists but the value does not exist: A system exception is returned. When the tag does not exist: The value in the mail adapter runtime environment property file becomes valid.
	<mail-addr-to>#1				0 or once	A tag that indicates the email address of the user the email is sent to. If you specify multiple email addresses, use a comma (,) as the delimiter for the email addresses. When the tag and the value exist: The value is used as the address for the TO field. The address is not validated. When the tag exists but the value does not exist: A system exception is returned. When the tag does not exist: The value in the mail adapter runtime environment property file becomes valid.
	<mail-addr-from>				0 or once	A tag that indicates the email address of the user who sends the email. You can specify only one email address. When the tag and the value exist: The value is used as the address for the FROM field. The address is not validated. When the tag exists but the value does not exist: A system exception is returned. When the tag does not exist: The value in the mail adapter runtime environment property file becomes valid.
	<mail-addr-cc>#1				0 or once	A tag that indicates the email address of the user who is set for the CC field. If you specify multiple email addresses, use a comma (,) as the delimiter for the email addresses. When the tag and the value exist: The value is used as the address for the CC field. The address is not validated. When the tag exists but the value does not exist: A system exception is returned. When the tag does not exist: The value in the mail adapter runtime environment property file becomes valid.
	<mail-addr-bcc>#1				0 or once	A tag that indicates the email address of the user who is set for the BCC field. If you specify multiple email addresses, use a comma (,) as the delimiter for the email addresses. When the tag and the value exist: The value is used as the address for the BCC field. The address is not validated. When the tag exists but the value does not exist: A system exception is returned. When the tag does not exist: The value in the mail adapter runtime environment property file becomes valid.
	<mail-subject-text>				0 or once	A tag that indicates the subject of the email. When the tag and the value exist: The value is used as the subject of the email. Note, however, that if the number of characters for the subject exceeds the size specified in the mail adapter runtime environment property file, the exceeded characters will be discarded. When the tag exists but the value does not exist: The email is sent without a subject. When the tag does not exist: The value in the mail adapter runtime environment property file becomes valid. If this tag is also not specified in the mail adapter runtime environment property file, the email is sent without a subject.
	<mail-body>#2				0 or once	A tag that indicates the body of the email. Specify the email body by using <message> and <file>. When the tag and the value exist: The value is used as the body of the email.#3 When the tag exists but the value does not exist: A system exception is returned. When the tag does not exist: The value in the mail adapter runtime environment property file becomes valid. If this tag is also not specified in the mail adapter runtime environment property file, the email is sent without a body.
		<message>			0 or once	A tag that indicates the character string used as the email body. Before you use a character such as < or >, sanitize the character string. When the tag and the value exist: The value is used as the body of the email. When the tag exists but the value does not exist, or there is no <file> specification: The email is sent without a body. When the tag does not exist: The value in the mail adapter runtime environment property file becomes valid.
		<file>			0 or once	A tag that indicates the path to the file whose contents are used as the email body and the character set. Specify the file path and the character set by <folder-name>, <mail-body-file-name>, and <file-charset>. When the tag and the value exist: The value is used as the email body. If you use the contents of the file as the email body, you do not have to sanitize the character string. When the tag exists but the value does not exist: A system exception is returned. When the tag does not exist: The value in the mail adapter runtime environment property file becomes valid.
			<folder-name>		Once	A tag that indicates the folder in which the file is to be stored. When common="true" is specified as the attribute of the tag: Use a common folder as the folder to which the file is to be stored, and specify the common folder definition name for this tag. If the common folder cannot be acquired from the specified common folder definition name, a system exception is returned. When common="false" is specified as the attribute of the tag: Use a work folder as the folder to which the file is to be stored. When the common attribute does not exist, the value of the common attribute is neither true nor false, or there is no tag: A system exception is returned.
			<mail-body-file-name>		Once	A tag that indicates the file name to be acquired. Specify the file directly under the work folder or common folder. You can use a delimiter, such as a slash (/) or back slash (\) only for the beginning of the file name. If you use a slash (/) at the beginning of the file name, the slash (/) is ignored. Specify a file that is not a symbolic link. You cannot specify multiple file names. When the tag exists and the value conforms to the above restriction: The value is used as the file name. When the tag exists and the value violates the above restriction: A system exception is returned. When the tag does not exist, or when the tag exists but the value does not exist: A system exception is returned.
			<file-charset>		0 or once	Specify the character set of the file containing the email body text. When the tag and the value exist: The value is used as the character set. When the tag exists but the value does not exist: A system exception is returned. When the tag does not exist: The value in the mail adapter runtime environment property file becomes valid. If this tag is also not specified in the mail adapter runtime environment property file, UTF-8 is used as the character set.
	<attachment-file>				0 or once	A tag that indicates the email attachment. Specify the attachment by using <item>. You can specify multiple attachments. When the tag and the value exist: The value is used as the email attachment. When the tag exists but the value does not exist: A system exception is returned. When the tag does not exist: The value in the mail adapter runtime environment property file becomes valid.
			<item>		Once or more	A tag that indicates the details of the email attachment. Specify the details of the attachment by using <attach-folder> and <attach-file-name>. When the tag and the value exist: The value is used as the email attachment. When the tag does not exist, or when the tag exists but the value does not exist: A system exception is returned.
				<attach-folder>	Once	A tag that indicates the folder in which the attachment is stored. When common="true" is specified for the attribute of the tag: Use a common folder as the folder to which the file is to be stored, and specify the common folder definition name for this tag. If the common folder cannot be acquired from the specified common folder definition name, a system exception is returned. When common="false" is specified for the attribute of the tag: Use a work folder as the folder to which the file is to be stored. When the common attribute does not exists, the value of the common attribute is neither true nor false, or there is no tag: A system exception is returned.
				<attach-file-name>	Once	A tag that indicates the name of the attachment. Specify the file directly under the work folder or common folder. You can use a delimiter, such as a slash (/) or back slash (\), only for the beginning of the file name. If you use a slash (/) at the beginning of the file name, the slash (/) is ignored. Specify a file that is not a symbolic link. You cannot specify multiple file names. When the tag exists and the value conforms to the above restriction: The value is used as the file name. When the tag exists and the value violates the above restriction: A system exception is returned. When the tag does not exist, or when the tag exists but the value does not exist: A system exception is returned.
	<mail-format>				0 or once	A tag that indicates the email format. Specify one of the following: text/plain: Creates the email body in plain text. text/html: Creates the email body in html format. text/xml: Creates the email body in xml format.#4 When the tag exists and the value is text/plain, text/html, or text/xml: The value is used as the email format. When the tag exists and the value is not text/plain, text/html, or text/xml: A system exception is returned. When the tag exists but the value does not exist: The value depends on the JavaMail settings. When the tag does not exist: The value in the mail adapter runtime environment property file becomes valid. If this tag is also not specified in the mail adapter runtime environment property file, the email body is created by using text/plain.
	<mail-encoding>				0 or once	A tag that indicates the encoding of the email. When the tag and the value exist: The value is used as the encoding of the email. When the tag exists but the value does not exist: The value depends on the JavaMail settings. When the tag does not exist: The value in the mail adapter runtime environment property file becomes valid. If this tag is also not specified in the mail adapter runtime environment property file, ISO-2022-JP is used.
	<mail-auth>				0 or once	A tag that indicates the SMTP authentication format. Specify either of the following: PLAIN: Authentication is not performed. LOGIN: The user name and password are used for authentication when the user logs in. When the tag exists and the value is PLAIN or LOGIN: The value is used as the SMTP authentication format. When the tag exists and the value is not PLAIN or LOGIN: A system exception is returned. When the tag exists but the value does not exist: The value depends on the JavaMail settings. When the tag does not exist: The value in the mail adapter runtime environment property file becomes valid. If this tag is also not specified in the mail adapter runtime environment property file, the email is sent in PLAIN format.
	<mail-option>				0 or more	A tag that indicates the user-defined email header. Specify the header name and value by combining <option-key> and <option-value>. When the tag and the value exist: The value is used as the user-defined email header. When the tag exists but the value does not exist: A system exception is returned. When the tag does not exist: The value in the mail adapter runtime environment property file becomes valid. If this tag is also not specified in the mail adapter runtime environment property file, the email is sent without a user-defined email header.
		<option-key>			Once	Specify the key name of the user-defined email header. When the tag and the value exist: The value is used as the key name of the email header. When the tag does not exist, or when the tag exists but the value does not exist: A system exception is returned.
		<option-value>			Once	Specify the value of the user-defined email header. When the tag and the value exist: The value is used as the value of the mail header. When the tag does not exist, or when the tag exists but the value does not exist: A system exception is returned.

Legend:

--: There is no relevant item.

#1

If no address is specified for <mail-addr-to>, <mail-addr-cc>, and <mail-addr-bcc>, and this tag is not specified in the mail adapter runtime environment property file, a system exception is returned.

#2

The settings of <mail-body> in a request message and the settings of the mailadp.mail.body-text key and mailadp.mail.body-filepath key in the mail adapter runtime environment property file are not linked. For example, say that in <mail-body> of a request message, you specify only <message> and do not specify <file>. In this case, even if you specify a file for the mailadp.mail.body-filepath key, <file> will not be set for the body.

#3

When you specify both <message> and <file>, the character string specified for <message> is set for the email body first. Then, the contents of the file specified for <file> are set for the email body.

#4

When you specify text/xml, the email body is displayed in plain text format in the mail adapter.

adpmail_smtp_response.xsd (response message format file)

The format of the response message that the mail adapter returns to the caller business process is shown below. The name space name is http://www.hitachi.co.jp/soft/xml/cosminexus/csc/adapter/mail/send_response.

Table 3-67 Response message format

Tag name		Number of occurrences	Description
<response>		Once	--
	<message-id>	Once	A tag that indicates the message ID of the sent email message. When an email is sent, the internally created MimeMessage is sent to the mail server. The ID of this MimeMessage will be the message ID.

Legend:

--: There is no relevant item.

The following are the types of definition files to be created:

• Mail adapter command definition file
  This file is used to set the output destination of the command message log and the output level.
  
• Mail adapter account definition file
  This file is used to manage the user name and password that are required when connecting from the mail adapter to the mail server.
  
• Email header definition file
  This file is used to write user-defined email header options, such as the importance of an email and whether to respond to a request.
  
• Mail adapter runtime environment property file
  This file is used to define configuration information of the mail adapter.
  

The following describes how to create individual definition files.

(a) Creating the mail adapter command definition file

1. Copy the template file (installation-directory-of-the-service-platform\CSC\config\mail\templates\adpmailcommand.properties), and store it in the following directory:
   installation-directory-of-the-service-platform\CSC\config\mail
   
2. Edit and save the definitions.

For details about the definitions that can be edited in the mail adapter command definition file, see Mail adapter command definition file in the manual Service Platform Reference Guide.

(b) Creating the mail adapter account definition file

1. Execute the csmmailaddusr command to create a mail adapter account definition file.
   Specify the path to the created mail adapter account definition file in the mailadp.account.file.path key in the mail adapter runtime environment property file. For details about the csmmailaddusr command, see csmmailaddusr (Registering and updating the mail adapter user information) in the manual Service Platform Reference Guide.
   

(c) Creating the email header definition file

1. Copy the template file (installation-directory-of-the-service-platform\CSC\config\mail\templates\mail-header.properties), and store it in any directory.
2. Rename the copied template file to any name.
3. Edit and save the definitions.

For details about the definitions that can be edited in the email header definition file, see Mail header definition file in the manual Service Platform Reference Guide.

(d) Creating the mail adapter runtime environment property file

1. Copy the template file (installation-directory-of-the-service-platform\CSC\config\mail\templates\adpmail.properties), and store it in the following directory:
   installation-directory-of-the-service-platform\CSC\config\mail
   
2. Rename the copied template file to service-ID^#.properties.
3. Edit and save the definitions.

For details about the definitions that can be edited in the mail adapter runtime environment property file, see Mail adapter runtime environment property file in the manual Service Platform Reference Guide.

#

service-ID is a character string specified in the Service Adapter Settings window when a new mail adapter is added.

The contents of the mail adapter runtime environment property file are applied to the execution environment when the mail adapter starts operating. Therefore, if you change the contents of the mail adapter runtime environment property file, you need to temporarily stop the mail adapter.

To define a mail adapter:

1. Open the Service Adapter Settings window.
   For details about how to open the Service Adapter Settings window, see 3.3.1(4) Displaying the service adapter settings screen.
   
2. In the Service Adapter Settings (standard) window, set the definition information.
   For details about the items that need to be set in the Service Adapter Settings (standard) window, see 3.3.15(10) For mail adapters and 1.2.2 Service Adapter Definition Window in the manual Service Platform Reference Guide.
   
3. Click the Service-adapter definition (details) tab.
   The Service Adapter Settings (details) window appears.
   
4. In the Service Adapter Settings (details) window, set the definition information.
   For details about the items that need to be set in the Service Adapter Settings (details) window, see 3.3.15(10) For mail adapters.
   

The figure below shows the directory structure after the service platform is installed. Note that only the directories for storing the definitions and message schema of a mail adapter are shown in this figure.

Figure 3-23 Directory structure of a mail adapter

For details about directory structures other than the above, see 2.1.2 Installing Service Platform in the manual Service Platform Setup and Operation Guide.

Below are examples of setting a mail adapter and business process. In these examples, the message passed to the standard reception is set to the email body, and the email is sent to the destination set in the mail adapter runtime environment property file.

(a) Example of setting a mail adapter

Below are examples of setting a mail adapter in the development environment and the mail adapter runtime environment property file.

Setting a mail adapter in the development environment

Set the individual items in the Service Adapter Settings window in the development environment as shown below. For details about the storage location of the email format and definition file, and how to operate in the development environment, see 3.2.12 Adding a new mail adapter.

Figure 3-24 Example of configuring the Service Adapter Settings (standard) window

Table 3-68 Settings in the Service Adapter Settings (standard) window

Legend:

--: The item is not set, or there is no relevant item.

Figure 3-25 Example of setting the Service Adapter Settings (details) window

Table 3-69 Setting items in the Service Adapter Settings (details) window

Legend:

--: The item is not set.

Creating the mail adapter runtime environment property file

Create the mail adapter runtime environment property file that corresponds to the mail adapter defined in the development environment. In the example below, the file name mailadp.properties is used.

For details about how to create the mail adapter runtime environment property file, see 3.3.12(3) Creating the mail adapter definition file.

An example of creating the mail adapter runtime environment property file is shown below. Italics indicate modified parts.

# All Rights Reserved. Copyright (C) 2011, Hitachi, Ltd.
 
mailadp.smtp.host.name = mail-server
#mailadp.smtp.port = 25
#mailadp.user = 
mailadp.addr.from = sampleuser2@XXXXXX.com
mailadp.addr.to = sampleuser@XXXXXX.com
#mailadp.addr.cc = 
#mailadp.addr.bcc = 
#mailadp.addr.count.max = 768
#mailadp.mail.body.size = 1024000
#mailadp.attach.path.1 =
#mailadp.attach.file.size = 5242880
#mailadp.max.attach.count.per.mail = 10
#mailadp.mail.format = text/plain
#mailadp.mail.body-text = 
#mailadp.mail.body-filepath = 
#mailadp.mail.body-filecharset = UTF-8
#mailadp.subject.size = 80
#mailadp.subject.text = 
mailadp.smtp.encoding = ISO-2022-JP
#mailadp.smtp.auth = PLAIN
#mailadp.user.header.path = 
#mailadp.account.file.path = 
#mailadp.methodtrace.level = 3
#mailadp.methodtrace.filepath = 
#mailadp.methodtrace.filenum = 
#mailadp.methodtrace.filesize = 2097152
#mailadp.messagelog.level = 10
#mailadp.smtp.timeout = 180
#mailadp.smtp.connectiontimeout = 180
#mailadp.read-lock.retry.count = 0
#mailadp.read-lock.retry.interval = 1

The created mail adapter runtime environment property file is stored in the installation-directory-of-the-service-platform\CSC\config\mail folder.

(b) Example of setting a business process

Below are examples of setting a business process in the development environment and data transformation definition.

For details about the window used in the development environment, see Chapter 1. Windows (Development Environment) in the manual Service Platform Reference Guide. For details about how to operate in the development environment, see Chapter 5. Defining Business Processes and Chapter 6. Defining Data Transformation in the manual Service Platform Basic Development Guide.

Setting the Define Business Process window

In the Define Business Process window in the development environment, define an activity as follows.

Figure 3-26 Example of setting a business process

Setting variables

Create variables for service component messages and standard messages, that are necessary for passing messages within a business process. Note that this setting example does not use a correlation set.

• Creating variables for service component messages
  In the List Of Variables And Correlation Sets dialog box of the Define Business Process window, add the following variables.
  

  Table 3-70 Variables for service component message

  Variable name	Description
  mail_input	A variable for request messages of the mail adapter
  mail_output	A variable for response messages of the mail adapter

  Always set the type XML. Set each variable as follows in the Take In Message Format dialog box.
  

  Table 3-71 Setting values in the Take In Message Format dialog box

  Item name	Variable name
  	mail_input	mail_output
  Service/Reception	Service name	Service name
  Service name/Reception name	mailadp	mailadp
  Operation name	SEND	SEND
  Message type	Request message (Body)	Response message (Body)
  Message format	mail_input	mail_output

• Creating variables for standard messages
  Create the message formats for request messages and response messages for standard messages, by using the following names and content:
  
  • input.xsd
    

    <?xml version="1.0" encoding="UTF-8" ?> <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"> <xsd:element name="SampleSOAPinput"> <xsd:complexType> <xsd:sequence> <xsd:element name="MAIL_BODY" type="xsd:string"/> </xsd:sequence> </xsd:complexType> </xsd:element> </xsd:schema>

  • output.xsd
    

    <?xml version="1.0" encoding="UTF-8" ?> <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"> <xsd:element name="SampleSOAPoutput"> <xsd:complexType> <xsd:sequence> <xsd:element name="MESSAGE_ID" type="xsd:string"/> </xsd:sequence> </xsd:complexType> </xsd:element> </xsd:schema>

  Then, in the List Of Variables And Correlation Sets dialog box of the Define Business Process window, add the following variables.
  

  Table 3-72 Variables for standard messages

  Variable name	Description
  input	Variable for request messages for standard reception
  output	Variable for response messages for standard reception

  Always set the type XML.
  Then, in the List Of Variables And Correlation Sets dialog box, click the ... button, and then specify the created message format as follows for each variable.
  

  Table 3-73 Message format to be specified

  Variable name	Message format to be specified
  input	input.xsd
  output	output.xsd

Setting the data transformation definition

In the data transformation activity (CreateMailAdapterRequestMessage), you can perform mapping for creating a request message of the mail adapter from a request message of the standard reception. In the same way, in the data transformation activity (CreateResponseMessage), you can perform mapping for creating a response message of the standard adapter from a response message of the mail adapter.

First, right-click the data transformation activity (CreateMailAdapterRequestMessage) in the Define Business Process window, and then select Launch &mapping definition.

Map the MAIL_BODY element in the request message of the standard reception to the message element, which is the child element of the mail-body element in the request message of the mail adapter.

Figure 3-27 Mapping for the request message

In the same way, right-click the data transformation activity (CreateResponseMessage) in the Define Business Process window, and then select Launch &mapping definition.

Map the message-id element in the response message of the mail adapter to the MESSAGE_ID element in the response message of the standard reception.

Figure 3-28 Mapping for the response message

Setting the invoke service activity

In the Define Business Process window, double-click the invoke service activity (InvokeMailAdapter), and then make the following settings in the displayed Invoke Service Activity dialog box.

Figure 3-29 Setting values for the invoke service activity

The following table describes the settings.

Table 3-74 Settings of the invoke service activity

Legend:

--: The item is not set.

This completes the mail adapter and business process settings.

To execute the business process in this example setting, you need to specify a request message for the standard reception from the service requester, and then send the message. For details about how to create a service requester, see 8.2 Service Requester That Sends Requests to a Standard Synchronous Reception (Web Services) (SOAP communication infrastructure) in the manual the Service Platform Basic Development Guide.

After the above operation, perform validation and packaging of the component, perform deployment definition in the test environment, and then check the operation. For details, see Chapter 7. Packaging HCSC Components and Defining Deployment in the manual Service Platform Basic Development Guide.