|
| |
| IS B2B: ECXpert 3.6.3 Support for Custom Java Communications Agents | |
ECXpert Support for Custom Java Communications Agents
Sun™ Open Net Environment (Sun ONE) Integration Server, B2B Edition (ECXpert) includes support for custom Java™ Communications Agents. This document explains how to create Java Communications Agents with ECXpert to exchange messages. ECXpert provides two sample plug-in Java SMTP Communications Agents you can modify to meet your messaging needs. These sample Java Communications Agents are not production-ready Communications Agents. They are provided to you as a reference for writing your own custom Java Communications Agents.
This document contains the following sections:
ECXpert and Its Communications AgentsTrading partner applications send data files via ECXpert using their native messaging protocols, for example, FTP, HTTP, JMS, ebXML, SMTP, or AS2. ECXpert itself does not interpret all the different protocols. It uses inbound and outbound Communications Agent components as interpreters as illustrated in Figure 1.
On the inbound side, the appropriate Communications Agent accepts the message, extracts the data within it, and submits the data to ECXpert for processing. After processing the submitted data, ECXpert passes the data and messaging parameters to the outbound Communications Agent. The outbound Communications Agent constructs a message in the protocol appropriate for the receiving application using the messaging parameters, and then transmits the message according to the rules of that particular protocol.
Figure 1 ECXpert’s Messaging System
About Custom Java Communications AgentsAs with all of the ECXpert Communications Agents, the Java Communications Agent feature provides two agents: an outbound, or send, Communications Agent and an inbound, or receive, Communications Agent. The rest of this section describes these Communications Agents.
Use the send Communications Agent to send outbound messages to your partners. A receive Communications Agent acts as a listener for a messaging server or client you specify.
The alternative to using Java Communications Agents is writing custom Communications Services. Communications Services run separate scripts for each send and receive process. Writing and deploying Communications Services require that a separate process be created each time a script is run.
In instances where large amounts of data are exchanged, multiple JVM processes can create serious performance issues. The benefit to using Java Communications Agents is that each send and receive Communications Agent allows ECXpert to run a dedicated JVM process for loading Java classes.
Java Send Communications Agents
When you create a Java send Communications Agent, you must create or modify trading information in ECXpert for the trading partnership that will use this Communications Agent. You can then start the Communications Agent with the ECXpert Administration interface.
When you start a Java send Communications Agent, you start a dedicated process that runs in the background. When a processed document is ready for sending, the ECXpert gateway process sends a request packet to this process. The entire request packet is passed to the instance of the Communications Agent, which then creates a new thread.
Java Receive Communications Agents
When you create a Java receive Communications Agent, you must create or modify trading information in ECXpert for the trading partnership that will use this Communications Agent. You then start the Communications Agent with the ECXpert Administration interface.
When you start the receive Communications Agent from the ECXpert Administration interface, you start a dedicated process. This process runs in the background, polling for received messages (or some other task your implementation of the receive Communications Agent is designed to execute), until you shut down the Communications Agent from the Administration interface.
Since it is possible that threads might still be processing when you shut down the Communications Agent, it is up to you to implement the shutdown() method in the receive Communications Agent in such a way that all currently executing threads shutdown gracefully.
Custom Java Communications Agent Example
The ECXpert installation includes a plug-in example of Java send and receive Communications Agents. You can find the plug-in example in the following location:
ECXPERT_HOME/NS-apps/ECXpert/javacomm/example
ECXPERT_HOME is the location where you installed ECXpert
To run the plug-in example, you must configure the example based on your ECXpert environment, and then start the Communications Agents. For more information, see the following:
Creating Java Communications AgentsRead these sections first for high-level overviews of the steps required to create and start Java Communications Agents:
After reading the overviews, read the following sections:
Creating Java Send Communications Agents
To Create a Java send Communications Agent
- Implement the following interfaces for the send Communications Agent using the Java framework provided with ECXpert:
- B2BOutboundCommAgentFactory
- B2BOutboundCommAgent
For more information, see Implementing the Custom Java Framework.
- Configure a Java send Communications Agent and define its parameters in the ECXpert configuration file (ecx.ini).
- Add a section in the ecx.ini file for the send Communications Agent and define the send parameter types for the agent.
You later define these parameters in the Outgoing Protocol screen for a Partnership that will use this Communications Agent.
- Set the value of the comm_agent_factory_class parameter of your send Communications Agent in the ecx.ini file.
This value is the fully qualified name of the class that implements the B2BOutboundCommAgentFactory interface in Step 1 above.
For an example of a send Communications Agent, open the ecx.ini file and search for the section named [user-defined-3]. You can modify the send parameter types in this plug-in example for your own Communications Agent.
For more information, see Configuring Custom Java Communications Agents.
- From the ECXpert Support interface, specify Partnership, Service, and Membership information for the send Communications Agent.
For more information on how to specify this information for a send Communications Agent, see Setting Up and Running the Send Example, or refer to the ECXpert Administrator’s Guide.
- From the ECXpert Administration interface, start the send Communications Agent.
For more information, see Starting and Stopping Java Communications Agents.
Creating Java Receive Communications Agents
To Create a Java receive Communications Agent
- Implement the following interfaces for the receive Communications Agent using the Java framework provided with ECXpert:
- B2BInboundCommAgentFactory.
- B2BInboundCommAgent.
For more information, see Implementing the Custom Java Framework.
- Configure a Java receive Communications Agent and define its parameters in the ECXpert configuration file (ecx.ini).
- Add a section in the ecx.ini for the receive Communications Agent and define the agent’s receive parameters.
- Set the value of the comm_agent_factory_class parameter of your receive Communications Agent in the ecx.ini file.
This value is the fully qualified name of the class that implements the B2BInboundCommAgentFactory interface in of Step 1 above.
For an example of a receive Communications Agent, open the ecx.ini file and search for the section named [commjava-receive]. You can modify the receive parameters in this plug-in example for your own Communications Agent.
For more information, see Configuring Custom Java Communications Agents.
- From the ECXpert Support interface, specify Partnership, Service, and Membership information for the receive Communications Agent.
For more information on how to specify this information for a receive Communications Agent, see Setting Up and Running the Send Example, or refer to the ECXpert Administrator’s Guide.
- Start the receive Communications Agent from the ECXpert Administration interface.
For more information, see Starting and Stopping Java Communications Agents.
Implementing the Custom Java FrameworkSend Communications Agents
To create a send Communications Agent, you must implement the following interfaces using the provided Java framework:
You create the B2BOutboundCommAgentFactory factory, which initializes your implementation of the B2BOutboundCommAgent.
Locate the documentation for the Java framework, which describes these interfaces, here:
ECXPERT_HOME/NS-apps/ECXpert/javacomm/docs.ECXPERT_HOME is the location of your ECXpert installation.
Note
The custom Java framework for send Communications Agents supports immediate/scheduled delivery similar to custom Communications Services.
Example Send Implementation
In the case of the example send Communications Agent included with ECXpert, the B2BoutboundCommAgentFactoryImpl class initializes and returns a B2BoutboundMailCommAgent interface in the implementation of the createOutboundCommAgent() method.
Code Example 1 shows the B2BOutboundMailCommAgent class. This class has send and readRequestData as its methods.
Locate the Java Communications Agent example plug-in code here:
ECXPERT_HOME/NS-apps/ECXpert/javacomm/example.Locate the documentation for the example plug-in code here:
ECXPERT_HOME/NS-apps/ECXpert/javacomm/example/docs.Receive Communications Agents
To create a receive Communications Agent, you must implement the following interfaces using the provided Java Framework:
You create a B2BInboundCommAgentFactory factory, which initializes your implementation of the B2BInboundCommAgent.
Locate the documentation for the Java framework, which describes these interfaces, here:
ECXPERT_HOME/NS-apps/ECXpert/javacomm/docs.ECXPERT_HOME is the location of your ECXpert installation.
Note
The custom Java framework for receive Communications Agents does not support scheduled receive.
Required Methods for B2BInboundCommAgent
The B2BInboundCommAgent interface contains two methods you must call within the implementation of the interface:
Table 1 B2BInboundCommAgent Methods
Method
Description
startUp()
The CommAgentManager calls this method on the inbound Communications Agent to bootstrap the agent.
shutDown(B2BStartupContext aCtx)
The CommAgentManager calls this method on the inbound Communications Agent to shut down the agent. ECXpert’s Native C++ Server calls this method when you shut down the agent from the ECXpert Administration interface.
The receive Communication Agent should exit all active threads gracefully on shutdown. If you find that all threads are not completing, increase the setting of the java_thread_wait_interval parameter for the receive Communications Agent in the ecx.ini file.
Example Receive Implementation
In the case of the example receive Communications Agent included with ECXpert, the B2BInboundCommAgentFactoryImpl class initializes and returns a B2BInboundMailCommAgent interface in the implementation of the createInboundCommAgent() method.
The messageHandler.java file shipped with the example Java Communications Agent shows how the example handles a document received by ECXpert.
Code Example 2 shows two methods from the messageHandler class:
Method
Description
isPartnershipValid
This method checks the validity of a partnership by checking the message’s parameters against ECXpert’s defined partnerships.
If the sender, receiver, and the subject (which is the received document type) of a message match a defined partnership, information is sent to the ECXpert logger file.
writeMessageToFile
This method writes the attached file to the tmp working directory specified in the ecx.ini file for the receive Communications Agent.
Code Example 2 Checking Partnership and Writing to a File
/**
* Check is the partnership is valid
* @param aLoginObj - is the login object
* @param aSender - Sending member whose EL matches the From Address
* @param aReceiver - Receiving member whose ER matches the From Address
* @param aFileType - is the subject of the email should match a filetype
* @return true is a Partnership exists between aSender, aReceiver with
* doctype = aFileType
*/
private boolean isPartnershipValid(JEcxLogin aLoginObj,
String aSender,
String aReceiver,String aFileType){
try{
JEcxPartnership
partnership = new JEcxPartnership();
partnership.setLogin(aLoginObj);
partnership.clear();
partnership.setSenderName(aSender);
partnership.list();
while(partnership.more() > 0) {
if ( partnership.getReceiverName().equals(aReceiver) &&
partnership.getDocType().equals(aFileType) ){
myContext.getLogger().logInformation(" Partnership is
valid... ");return true;
}
partnership.next();
}
} catch (Exception aEx){
try {
myContext.getLogger().logError(
"Error in validating partnership " + aEx.getMessage());
} catch (LoggerException aExp) {
aExp.printStackTrace();
}
return false;
}
return false;
}
/**
* Write message contents to a file and return the file name
*/
public String writeMessageToFile(Message aMailMessage){
try{
Object content = aMailMessage.getContent();
if(content instanceof Multipart) {
myContext.getLogger().logError("Multipart messages not supported .");
return null;
}else{
String filename = myTempDir + java.io.File.separator
+ (new java.util.Date()).toString() + ".txt";FileWriter fw = new FileWriter( filename);
fw.write((String)content);
fw.close();
return filename;
}
} catch (Exception aEx){
aEx.printStackTrace();
return null;
}
}
Locate the Java Communications Agent example plug-in code here:
ECXPERT_HOME/NS-apps/ECXpert/javacomm/example.Locate the documentation for the example plug-in code here:
ECXPERT_HOME/NS-apps/ECXpert/javacomm/example/docs.
Configuring Custom Java Communications AgentsThis section describes the configuration parameters you must set in the ECXpert configuration file (ecx.ini) for Java Communications Agents. You can locate ECXpert‘s ecx.ini file here:
ECXPERT_HOME/NS-apps/ECXpert/config/ecx.iniECXPERT_HOME is the location of your ECXpert installation.
There are three sub-sets of parameters used for Java Communications Agents:
Provide descriptions for configuration parameters common to all Java send and receive Communications Agents.
Provide descriptions for configuration parameters specific to Java send Communications Agents.
Provide descriptions for configuration parameters specific to Java receive Communications Agents.
Send and receive Communications Agents require a combination of parameters common to both Communications Agents, and specific to each Communications Agent.
It might be helpful for you to print a listing of your ecx.ini file for a reference while reading this section.
Common Agent Parameters
Table 2 lists the send and receive configuration parameters that are common to both Communications Agents.
Many of the parameters defined are similar to parameters defined for SNMP Communications Agents. This table lists the actual parameter name specified in the ecx.ini file.
The Change Required column defines whether or not it is necessary for you to change the current value to create your own Java Communications Agent. A value of “maybe” implies that your specific implementation might require a change.
Note
Table 3 and Table 4 describe the parameters specific to send and receive Communications Agents, respectively.
Table 2 Common Java Communications Agents Parameters
Parameter
Description and Value
Change Required?
server_type
The server_type parameter for the Communications Agent.
This must be a unique numeric value for each Communication Agent.
yes
snmp_trap_flag
Trap information for SNMP service?
Restrictions—valid values: yes, no
Default: no
no
snmp_trap_level
SNMP event level to trap.
Restrictions—valid values:
- 0 = all messages
- 10 = information, warning, and error mesages
- 20 = warning and error messages
- 30 = error messages only
Default: 0no
section_type
Type of section for the Communications Agent.
Restrictions—Must be server; do not change.
no
protocol_id
Protocol identifier.
Default: 3
no
port_location
Location to pick up the port.
Default: mmap
no
max_listeners
Maximum number of listener threads that are allowed. Base on concurrent processing needs, if multiple submission units are to be processed in parallel.
Restrictions—Total number of threads you specify must be supported by your hardware.
Default: 1
no
listener_level
Listener level. Number of listener threads to launch on startup.
Default: 1; do not change.
no
listener_type
Listener type.
Restrictions—valid values:
- thread = runs as a thread
- process = runs as a processDefault: thread
no
runnable_flag
Can executable be run?
Restrictions—valid values:
- yes = executable will be run as needed
- no = executable will not be run (for example, in a test situation)Default: yes
no
thread_mode
Thread operational mode
Restrictions—valid values:
- threaded = run threaded
- serialized = run serializedDefault: threaded (only the Admin. server should be serialized; in all other sections where section_type=server, it is strongly recommended that you leave this setting as threaded)
no
listener_time_out
Listener timeout, in seconds.
Default: 10
no
admin_time_out
Admin server timeout period, in seconds.
Default: 10
no
start_mode
Server start mode.
Restrictions—valid values: commandline, background
Default: background
no
Machine Dependent Information
host_name
IP address of host machine where instances of executable are run.
Restrictions—Must be a valid IP address in your domain.
Default: set during installation.
For each send Communications Agent you define, use the host_name value set in any of the other Communications Agent Machine dependent information sections in your ecx.ini file.
no
File and directory information
exec_path
For a Java send Communications Agent:
the path to the b2bjavasendmain executable:
ECXPERT_HOME/NS-apps/ECXpert/bin/
b2bjavasendmainFor a Java receive Communications Agent:
the path to the b2bjavareceivemain executable:
ECXPERT_HOME/NS-apps/ECXpert/bin/
b2bjavareceivemainyes
Multi-threading parameters
max_thread_flag
Limit the number of threads running in system?
Restrictions—valid values: yes, no
Default: yes
no
worker_max_threads
Number of worker threads to run in parallel.
Default: 4
no
master_max_threads
Number of master threads to run in parallel.
Default: 4
no
master_max_threads_
queued_flagQueue master threads above master_max_threads?
Restrictions—valid values: yes, no
Default: yes
no
master_max_threads_queued
Maximum number of master threads to queue.
Default: 500
no
master_max_threads_stacked
Maximum number of master threads to place on stack.
Default: 500
no
Port Information
admin_port
Administrative port number.
Restrictions: Ports used by ECXpert must not be used by other applications.
Default: 50519; set during installation.
Change if you used a different port number at installation.
no
admin_port_type
Administrative port type.
Restrictions—valid values:
- dynamic = Administrative Server assigns
- manual = always use value in admin_portDefault: dynamic
no
listener_port
Listener port number.
Restrictions: Ports used by ECXpert must not be used by other applications.
Default: 50504; set during installation.
Change if you used a different port number at installation.
no
listener_port_type
Listener port type. Only set when adding your own network_id.
Restrictions—valid values:
- dynamic = Administrative Server assigns
- manual = always use value in admin_portDefault: dynamic
no
Configurable Options
restart_flag
Restart this executable automatically if it experiences an abnormal exit?
Restrictions—valid values:
- yes = automatically restart when ECXpert is restarted - (you are confident manual intervention is not required)
- no = do not restart when ECXpert is restarted- (you expect that manual intervention might be required)Default: no
no
autostart_flag
Start communications servers automatically when ECXpert is started?
Restrictions—valid values:
-yes
-noDefault: yes
no
Debug Output Configuration
debug_flag
Turn on low level tracing information?
Restrictions—valid values:
-yes
-noDefault: no
maybe
redirect_stdout
redirect_stderrWhen set to yes, the output directed to stdout and stderr is redirected to the files specified in the stdout_path and stderr_path parameters.
Restrictions—valid values:
-yes
-noDefault: yes
maybe
stdout_path
Fully specified path for log file to receive standard output from low level trace.
Send: ECXPERT_HOME/NS-apps/
ECXpert/data/log/ECXpert.log.
commjava-send.datReceive: ECXPERT_HOME/NS-apps/
ECXpert/data/log/ECXpert.log.
commjava-receive.datno
stderr_path
Fully specified path for log file to receive standard output from low level trace.
Send: ECXPERT_HOME/NS-apps/
ECXpert/data/log/ECXpert.log.
commjava-send.datReceive: ECXPERT_HOME/NS-apps/
ECXpert/data/log/ECXpert.log.
commjava-receive.datno
log_dir
Full path to directory for log files.
Default: ECXPERT_HOME/NS-apps/
ECXpert/data/logno
log_prefix
File prefix used for name generation.
Default: ECXpert.log.admin.dat
no
log_flag
Should entry appear in the logging API?
Restrictions—valid values:
-yes
-noDefault: yes
no
Send Agent Parameters
In addition to parameters common to both send and receive Communications Agents, there are parameters that are specific to send Communications Agents. Table 3 shows ecx.ini parameters specific to Java send Communications Agents.
The Change Required column defines whether it is necessary to change the current value to create your own Java send Communications Agent. A value of “maybe” implies that your specific implementation might require a change.
Table 3 Java send Communications Agent Specific Parameters
Parameter
Description and Value
Change Required?
section name
The name associated with the internal_name parameter within ECXpert. This parameter should appear at the beginning of each Communications Agent section.
Use the form [user-defined-x].
For more information, see internal_name in this table.
yes
type
Type of executable.
Restrictions: must be daemon, do not change.
no
operation
Restrictions: must be send, do not change.
no
is_comm_agent
Restrictions: must be yes, do not change.
no
pre_enveloped_edi
Allow retrieval of EDI documents with existing envelopes?
Restrictions—valid values:
- true = yes, pre-enveloped
- false = no, not pre-envelopedDefault: true
maybe
bundle_all
Package all data together as one file (one body part)?
Note: Do not set this parameter to yes with EDI data. Sending multiple interchanges in one E-mail violates EDI standards; ECXpert will not send EDI data if bundle_all is set to true.
Restrictions—valid values:
- yes
- noDefault: no
maybe
use4digit_year
Use all four digits for year, for year 2000 compliance?
Restrictions—valid values:
- yes = use all four digits, year 2000 compliant
- no = use only last two digits, not year 2000 compliantDefault: yes
Note: Only applicable in versions of X12 standard that support an 8-digit GS04 value (specifically, version 3072 and version 4010 and later versions).
no
multi_part
Enable sending of multiple body parts (attachments) using MIME?
Restrictions—valid values:
- yes
- noDefault: yes
maybe
num_jvm_properties
Number of JVM properties specified. There should be an equal amount of JVM properties specified in the jvm_propertyn parameter as the value set for this parameter.
Default: 2
yes
jvm_propertyn
This parameter must have 1...n JVM properties specified where n = num_jvm_properties above.
For example, if n = 2, you must specify jvm_property1 and jvm_property2
Note: Always retain the two jvm_properties already set in the Communication Agent.
jvm_property1 = -Djava.library.path = ...
jmv_property2 = -Djava.class.path = ...The java.class.path system property must always contain the following paths:
ECXPERT_HOME/NS-apps/ECXpert/javacomm/lib/javacomm.jar
ECXPERT_HOME/NS-apps/ECXpert/javacomm/lib/b2bcomm.jar
ECXPERT_HOME/NS-apps/ECXpert/javacomm/lib/ecxsdkjni.jar
ECXPERT_HOME/NS-apps/ECXpert/javacomm/lib/ecxcpplogger.jar
If you plan to clone a send Communications Agent in the ecx.ini file of another machine’s ECXpert installation, you must update the jvm_property class and library paths to point to the correct paths for that instance of ECXpert.
yes
ignore_unrecognized_
jvm_propertyIgnore a non-standard JVM system property?
Restrictions—valid values:
- yes
- noDefault: yes
maybe
comm_agent_factory_
classFully qualified classname of the class that implements the B2BOutboundCommAgentFactory interface.
yes
parameter_name_m
Specify m protocol parameters that you can configure from the Outgoing Protocol parameters tab of the Partnership tab in the ECXpert Support interface.
Match each parameter_name_m with a parameter_type_m to define the type of widget associated with the parameter.
yes
parameter_type_m
Specify the type of UI widget for parameter_name_m by specifying a matching parameter_type_m.
Valid values:
textbox – displays a textbox.
password – displays a textbox with all text characters appearing as asterisks “*”.
dropdown – displays a dropdown box. When defining parameter_type_m as a dropdown, the parameter_name_m should be of the form: DropDownLabel ? Item1 ? Item2 ? Item3 ? Item4 ? ...
Note: If parameter_type_m is not specified for a parameter_name_m, the parameter type defaults to textbox.
Optional
(See note)internal_name
The name used internally within ECXpert.
USER DEFINED x
where x = 1...n
Note: You must use the form USER DEFINED x for the internal_name.
Use the form user-defined-x for the corresponding section_name that begins the send Communication Agent section.
yes
visible_name
The name displayed externally by ECXpert.
In the case of the example plug-in Java Communications Agent installed with ECXpert, the visible_name is CustomJava SMTPSend.
yes
The ecx.ini file installed with ECXpert contains a plug-in example of a Java send Communications Agent. Code Example 3 shows the section specific to an ECXpert send Communications Agent. To view the section, open the ecx.ini file in a text editor and search for B2B Java Send Section.
Code Example 3 Java send Communications Agent Parameters in ecx.ini File
#
# This is the name of the ecx.ini section for the send agent.
# It appears at the top of the section. The agent name must follow
# the convention user-defined-x and match the internal_name parameter.
# defined later in the agent’s section.
#
[user-defined-3]
#
# Common receive agent parameters skipped here. See ecx.ini file for
# skipped parameters.
#
#
# File and directory information
#
exec_path = /export/iisb2b/ecx363_migrate/NS-apps/ECXpert/bin/b2bjavasendmain
#
# Common receive agent parameters skipped here. See ecx.ini file for
# skipped parameters.
#
#
# Outbound Comm Agent Specific Properties
#
type=daemon
opertaion = send
is_comm_agent = yes
pre_enveloped_edi = True
bundle_all = yes
use4digit_year = yes
multi_part = yes
#
# JVM Specific Properties
#
# num_jvm_properties specified how many jvm properties are specified here.
# You can specify 1..num_jvm_properties.i.e. jvm_property[1..n] where
# n = num_jvm_properties
#
# ignore_unrecognized_jvm_property specifies whether a unrecognized
# jvm_property is to be ignored {yes/no}
#
num_jvm_properties = 2
jvm_property1 =
-Djava.library.path=/export/iisb2b/ecx363_migrate/NS-apps/ECXpert/lib:/export/
iisb2b/ecx363_migrate/NS-apps/ECXpert/bin/Solaris_JRE_142/lib/sparc
jvm_property2 =
-Djava.class.path=/export/iisb2b/ecx363_migrate/NS-apps/ECXpert/javacomm/lib/b
2bcomm.jar:/export/iisb2b/ecx363_migrate/NS-apps/ECXpert/javacomm/lib/javacomm
.jar:/export/iisb2b/ecx363_migrate/NS-apps/ECXpert/ecxsdk/jni/ecxsdkjni.jar:/e
xport/iisb2b/ecx363_migrate/NS-apps/ECXpert/ecxsdk/jni/ecxcpplogger.jar:/expor
t/iisb2b/ecx363_migrate/NS-apps/ECXpert/javacomm/lib/activation.jar:/export/ii
sb2b/ecx363_migrate/NS-apps/ECXpert/javacomm/lib/mail.jar:/export/iisb2b/ecx36
3_migrate/NS-apps/ECXpert/javacomm/lib/smtp.jar
ignore_unrecognized_jvm_property = yes
#
# CommAgentFactoryClass Instance
#
comm_agent_factory_class =
com.sun.iis.b2b.bdg.example.B2BOutboundCommAgentFactoryImpl
#
# Custom Communication Agent UI specific properties
#
parameter_name_1 = SMTP Mail Host
parameter_type_1 = textbox
parameter_name_2 = SMTP Mail Host Port
parameter_name_3 = Sender
parameter_name_4 = Sender Email
parameter_name_5 = Receiver
parameter_name_6 = Receiver Email
parameter_name_7 = User Id
parameter_name_8 = User Password
parameter_type_8 = password
parameter_name_9 = Unused Parameter ? item1 ? item2
parameter_type_9 = dropdown
internal_name = USER DEFINED 3
visible_name = CustomJava SMTPSend
#
# Debug output configuration.
#
debug_flag = no
redirect_stdout = yes
redirect_stderr = yes
stderr_path =
/export/iisb2b/ecx363_migrate/NS-apps/ECXpert/data/log/ECXpert.log.commjava-
send.dat
stdout_path =
/export/iisb2b/ecx363_migrate/NS-apps/ECXpert/data/log/ECXpert.log.commjava-
send.dat
log_flag = yes
log_prefix = ECXpert.log.commjava-send.dat
log_dir = /export/iisb2b/ecx363_migrate/NS-apps/ECXpert/data/log
When you select CustomJava SMTPSend as the Outgoing Protocol from the Partnership tab, the B2B Java Send Section of the ecx.ini file results in the Protocol screen pictured in Figure 2.
The parameter types and names specified in the ecx.ini file appear in the Parameters section of the Protocols screen.
Figure 2 Protocol Tab for CustomJava SMTPSend Defined in ecx.ini File
Receive Agent Parameters
In addition to parameters common to all Java send and receive Communications Agents, there are parameters you must set in the ecx.ini file that are specific to receive Communications Agents. Table 4 shows ecx.ini parameters you must set for your Java receive Communications Agents.
The Change Required column defines whether it is necessary to change the current value to create your own Java receive Communications Agent. A value of “maybe” implies that your specific implementation might require a change.
Table 4 Java receive Communications Agent Specific Parameters
Parameter
Description and Value
Change Required?
section name
The name associated with the receive Communications Agent. This name appears at the beginning of each Communications Agent section.
Unlike the Java send Communications Agent, there is no restriction on the section name for the Java receive Communications Agent. You do not have to use the form user-defined-x.
yes
num_jvm_properties
Number of JVM properties specified. There should be an equal amount of JVM properties specified in the jvm_propertyn parameter as the value set for this parameter.
Default: 2
yes
jvm_propertyn
This parameter must have 1...n JVM properties specified where n = num_jvm_properties above.
For example, if n = 2, you must specify jvm_property1 and jvm_property2
Note: Always retain the two jvm_properties already set in the Communication Agent.
jvm_property1 = -Djava.library.path = ...
jmv_property2 = -Djava.class.path = ...The java.class.path system property must always contain the following paths:
ECXPERT_HOME/NS-apps/ECXpert/javacomm/lib/javacomm.jar
ECXPERT_HOME/NS-apps/ECXpert/javacomm/lib/b2bcomm.jar
ECXPERT_HOME/NS-apps/ECXpert/javacomm/lib/ecxsdkjni.jar
ECXPERT_HOME/NS-apps/ECXpert/javacomm/lib/ecxcpplogger.jar
If you plan to clone a receive Communications Agent in the ecx.ini file of another machine’s ECXpert installation, you must update the jvm_property class and library paths to point to the correct paths for that instance of ECXpert.
yes
ignore_unrecognized_
jvm_propertyIgnore a non-standard JVM system property?
Restrictions—valid values:
- yes
- noDefault: yes
maybe
comm_agent_factory_class
Fully qualified classname of the class implementing the B2BInboundCommAgentFactory interface.
yes
java_thread_wait_interval
Time interval in milliseconds that ECXpert waits for any threads created by the B2BInboundCommAgent to die.
If shutdown of your receive Communications Agent takes more time, increase this value from the default value of 20000 ms.
maybe
Inbound Communications Agent Specific properties
In the plug-in example provided with ECXpert, the B2B Custom receive agent section contains the following SMTP parameters:
- mail_host
- mail_host_port
- mail_protocol
- mail_userid
- mail_userpwd
- work_dir
Parameters that are specific to the implementation of the inbound receive Communications Agent.
You must set these messaging server parameters, which are specific to your environment, in the ecx.ini file.
To encrypt the mail_userpwd password, use the bdgsetpasswd Password Utility, discussed on (more...) .
For implementation details on reading these parameters from the ecx.ini file, refer to the readConfigData()method in the B2BInboundMailCommAgent.java file for the example SMTP receive Communications Agent in the following location: ECXPERT_HOME/NS-apps/ECXpert/javacomm/example.
ECXpert’s ecx.ini file contains a plug-in example of a Java receive Communications Agent. Code Example 4 shows the section specific to an ECXpert receive Communications Agent. To view the section, open the ecx.ini file in a text editor and search for B2B Java Receive Section.
To configure the Communications Agent to receive messages, you must enter values for your messaging server in the Sample Inbound Comm. Agent Specific properties subsection of the B2B Java Receive Section in the ecx.ini file.
Code Example 4 Java receive Communications Agent Parameters in ecx.ini File
###############################################
# #
# B2B Java Receive Section #
# #
###############################################
#
# This is the name of the ecx.ini section for the receive agent.
# It appears at the top of the section. The agent name does not
# have to follow the user-defined-x convention used in B2B send agents.
#
[commjava-receive]
#
# Common receive agent parameters skipped here. See ecx.ini file for
# skipped parameters.
#
#
# File and directory information
#
exec_path = /kes1/ecx_3_6_3/NS-apps/ECXpert/bin/b2bjavareceivemain
#
# Common receive agent parameters skipped here. See ecx.ini file for
# skipped parameters.
#
#
# JVM Specific Properties
#
# num_jvm_properties specified how many jvm properties are specified here.
# You can specify 1..num_jvm_properties.i.e. jvm_property[1..n] where
# n = num_jvm_properties
#
# ignore_unrecognized_jvm_property specifies whether a unrecognized
# jvm_property is to be ignored {yes/no}
#
num_jvm_properties = 2
jvm_property1 =
-Djava.library.path=/export/iisb2b/ecx363_migrate/NS-apps/ECXpert/lib:/export/
iisb2b/ecx363_migrate/NS-apps/ECXpert/bin/Solaris_JRE_142/lib/sparc
jvm_property2 =
-Djava.class.path=/export/iisb2b/ecx363_migrate/NS-apps/ECXpert/javacomm/lib/
b2bcomm.jar:/export/iisb2b/ecx363_migrate/NS-apps/ECXpert/javacomm/lib/
javacomm.jar:/export/iisb2b/ecx363_migrate/NS-apps/ECXpert/ecxsdk/jni/
ecxsdkjni.jar:/export/iisb2b/ecx363_migrate/NS-apps/ECXpert/ecxsdk/jni/
ecxcpplogger.jar:/export/iisb2b/ecx363_migrate/NS-apps/ECXpert/javacomm/lib/
activation.jar:/export/iisb2b/ecx363_migrate/NS-apps/ECXpert/javacomm/lib/
mail.jar:/export/iisb2b/ecx363_migrate/NS-apps/ECXpert/javacomm/lib/smtp.jar:/
export/iisb2b/ecx363_migrate/NS-apps/ECXpert/javacomm/lib/pop3.jar
ignore_unrecognized_jvm_property = yes
#
# CommAgent Factory Implementation class
#
comm_agent_factory_class =
com.sun.iis.b2b.bdg.example.B2BInboundCommAgentFactoryImpl
#
# This is the time interval in ms for which the communication agent manager
# waits for the Java thread to die.
#
#
java_thread_wait_interval = 20000
#
# Sample Inbound Comm. Agent Specific properties
#
mail_host = <mail server>
mail_host_port= <port on which the POP3/IMAP daemon is listening on mail_host>
mail_protocol = <mail protocol pop3/imap>
mail_userid = <mail user id>
mail_userpwd = <mail user encrypted password>
work_dir = <temporary work directory>
#
# Debug output configuration.
#
debug_flag = no
redirect_stderr = yes
redirect_stdout = yes
stderr_path =
/export/iisb2b/ecx363_migrate/NS-apps/ECXpert/data/log/ECXpert.log.commjava-re
ceive.dat
stdout_path =
/export/iisb2b/ecx363_migrate/NS-apps/ECXpert/data/log/ECXpert.log.commjava-re
ceive.dat
log_flag = yes
log_prefix = ECXpert.log.commjava-receive.dat
log_dir = /export/iisb2b/ecx363_migrate/NS-apps/ECXpert/data/log
Starting and Stopping Java Communications AgentsUse the ECXpert Administration interface to start and stop the Java Communications Agents as you would any other Communications Agents for ECXpert protocols. For more information on staring and stopping Communications Agents, refer to the ECXpert Administrator’s Guide.
Figure 3 shows the ECXpert Administration interface with the Custom Java SMTP (send) and Custom Java SMTP (receive) Communications Agents turned off.
Figure 3 Administration Interface Showing Java Communications Agents
Setting Up and Running the Send ExampleThis section describes how to set up and run the plug-in example for the Java send Communications Agent. For this example, you should set up an ECXpert user named test on your Messaging Server, with a password test. This user will send a message using the Java send Communications Agent installed with ECXpert.
To Create a Messaging Server User
To Modify Partnership Information to Include Messaging Server and User Information for Sending a Message
- From the Partnership tab, select Change.
- Select Search.
A list of all current partnerships appears, as shown in Figure 4.
- Select the following default Partnership and click Retrieve.
Figure 4 Partnership Results List
- From the Protocol tab, select CustomJava SMTPSend from the outgoing protocol drop-down list.
The parameters defined in the Java send Communications Agent section of the ecx.ini file appear in the Protocols screen.
- Enter values into the fields for the Partnership’s outbound Protocol as shown in Figure 5, and click Change.
These fields represent the Java send Communications Agent properties for the parameters you defined in the B2B Java Send Section of the ecx.ini file.
Figure 5 Partnership Protocols Tab
Table 5 Outgoing Protocol Parameters
Field
Value and Description
SMTP Mail Host
The messaging server host name.
SMTP Mail Host Port
The messaging server host port.
If no port is specified, the default port is used.
Sender
The message sender’s name.
Use test for this example.
Sender Email
The message sender’s E-mail address.
This must be a valid E-mail address.
Use test@yourmessagingsever.com where yourmessagingserver.com is the host name for the account you have created for user test on your messaging server.
Receiver
The messages receiver’s name.
Use test for this example.
Receiver Email
The message receiver’s E-mail address.
This must be a valid E-mail address.
Use test@yourmessagingsever.com where yourmessagingserver.com is the host name for the account you have created for user test on your messaging server.
User Id
The User Id for logging in to the Messaging Server.
Use test for this example.
User Password
The User Password for logging in to the Messaging Server.
Use test for this example.
To Start the send Communications Agent
To Send a Message Using ECXpert’s Document Submission Form
- Copy the Input_810.txt file from ECXPERT_HOME/NS-apps/ECXpert/maps to your /tmp directory on Solaris or C:\tmp directory on Windows.
- Use the Document Submission Form to submit the 810.txt file as shown in Figure 6.
Figure 6 Document Submission Form
Table 6 Document Submission Form Information
Field
Value and Description
Sending Member
The member ID for the sending member you defined in the associated partnership.
Use PartnerA for this example.
Password
The sending member’s Password.
Receiving Member
The member ID of the receiving member you defined in the associated partnership.
Use ECX for this example.
File Name
The name of the file to submit to ECXpert (the submission unit).
On Solaris: /tmp/Input_810.txt
On Windows: C:\tmp\Input_810.txt
File Type
The Document Type for the file as defined in the Service List.
Use EDI for this example.
If the document submission is successful, a message appears, as shown in Code Example 5. Make a note of the tracking ID in the success window. In this case, the tracking number is 235.
Code Example 5 Document Submission Successful Message
Submitting...
Sender: PartnerA
Password: **********
Receiver: ECX
ECX Ini File: /export/home/ecxadmin/ECX363_INT/NS-apps/ECXpert/config/ecx.ini
Submit File Name: /tmp/Input_810.txt
Submit File Type: EDI
Submission is successful, and the tracking ID is: 235
Done
To Check Your Mail Client to Make Sure Message Was Successfully Sent
- Log in to the mail client as test/test as shown in Figure 7 to verify that the message sent in by the Submission Form was received by user test.
Figure 7 Mail Client Login Screen
- Retrieve E-mail messages using you mail client.
The message should appear in the Inbox as shown in Figure 8.
Figure 8 Mail Client Interface Showing Received Messages in Inbox
To Check ECXpert’s Event Log to Make Sure Message Was Successfully Sent
- From the Support Interface, select Tracking.
- Select the Event Log Tab.
- To view Send error events, specify a specific tracking ID.
If the message was sent successfully, it should appear in the event log as shown in Figure 9.
Figure 9 ECXpert Event Log With Send Events Shown
Setting Up and Running the Receive ExampleThis section describes how to set up and run the plug-in example for the Java receive Communications Agent. For this example, you use the same ECXpert user named test on your Messaging Server, with a password test.
This user will receive a message using the Java receive Communications Agent installed with ECXpert.
Note
You must complete the send example section before you begin the receive example. See Setting Up and Running the Send Example.
To Modify the B2B Java Receive Section of the ecx.ini File
- Edit the messaging server information for the receive Communications Agent in the ecx.ini file and save the file.
To find this section, open the ecx.ini file in a text editor and search for [commjava-receive]. The inbound specific parameters are shown in Code Example 6.
Code Example 6 Messaging Server B2B Java Receive Section of ecx.ini File
#
# Sample Inbound Comm. Agent Specific properties
#
mail_host = <mail server>
mail_host_port= <port on which the POP3/IMAP daemon is listening on mail_host>
mail_protocol = <mail protocol pop3/imap>
mail_userid = <mail user id>
mail_userpwd = <mail user encrypted password>
work_dir = <temporary work directory>
Table 7 shows the list of receive Communications Agent messaging server parameters and their descriptions for this example.
Table 7 Receive Communications Agent Messaging Server Information
Parameter
Description
mail_host
The messaging server’s host name.
Use the messaging server host name where you created the test/test account in Step 1 for this example.
mail_host_port
The SMTP host port.
If the port is not specified, the default port is used.
mail_protocol
The mail protocol for your messaging server instance.
pop3/imap
mail_userid
The User account for receiving messages.
Use test for this example.
mail_password
The encrypted password for mail_userid.
Use the password test for this example.
To encrypt the mail_userpwd parameter, use the password utility (on one line):
bdgsetpassword -i path/ecx.ini -s commjava-receive -param mail_userpwd -v test
For more information about bdgsetpasswd, see Password Utility, on (more...) .
work_dir
Temporary working directory.
Use /tmp for this example.
To Modify/Create Members Using the Membership Tab
The Custom Java SMTP (receive) Communications Agent validates received mail as follows:
A Partnership should exist between the Sender/Receiver with the determined document type. In this case, the Sender is PartnerA and the Receiver is a new member Test1.
- Set the EL of Sending member PartnerA.
- From the Membership tab, click Change.
- Select PartnerA from the drop-down list and click Retrieve.
- Select the Trading Addresses tab.
The trading addresses tab appears.
- Select Local E-Mail from the Address Type drop-down list, enter the E-mail address for your test user, and click Add.
The new EL for PartnerA appears in the Existing Trading Address table as shown in Figure 10.
- Click the Change button located at the bottom of the Trading Addresses window.
Figure 10 Sending Member’s (PartnerA) Local E-mail (EL) Address
- Add a new Receiving member test1.
- From the Membership tab, click Add.
- Enter Test1 in the Member ID field on the Membership Information tab.
- Enter Test1 in the Full Name field on the Contact Information tab.
- Click the Trading Addresses tab.
- Select Remote E-Mail from the Address Type drop-down list, enter the E-mail address for your test user, and click Add.
The new ER for Test1 appears in the Existing Trading Address table as shown in Figure 11.
- Click the Add button located at the bottom of the Trading Addresses window.
Figure 11 Receiving Member’s (Test1) Remote E-mail (ER) Address
To Create a Partnership to Use the Custom Java SMTP (receive) Communications Agent
- Click Add from the Partnership tab.
- Select PartnerA from the Sending Member drop-down list.
- Select Test1 from the Receiving Member drop-down list.
- Specify EDI for the document type.
Figure 12 shows the Partnership Information window.
Figure 12 Partnership Information for receive Communications Agent
- From the Protocol tab, select FTP from the Outgoing Protocol drop-down list.
- Fill in the fields for your FTP server as shown in Figure 13 and click Add.
For more information on specifying FTP Protocol information, refer to the Chapter “Setting up Trading Partnerships,” available from the ECXpert Administrator’s Guide.
Figure 13 Partnership Protocol for receive Communications Agent
To Create a Service List to Process Retrieved Documents
- From the Services tab, click Add.
- Select the following services and click the Add button in the middle of the window:
- Specify the Service List Details as shown in Figure 14 and click the Add button at the bottom of the Services window.
Figure 14 Service List Details for receive Communications Agent
Service List Details Field
Description and Value
Service List Name
The name of the service list. This can be any unique name.
Use testJavaRecv for this example.
Service List Data Type
The File type for the service list is EDI.
The document will be submitted with Filetype = Subject = EDI
Sending Member
PartnerA
Receiving Member
Test1
To Start the Custom Java SMTP (receive) Communications Agent
To Check Your Mail Client for Received Messages
The receive Communications Agent should have received a message from the Document Submission you performed in Step 2.
- Login to your mail client as test/test as shown in Figure 15 to verify that the message was received by user test.
Figure 15 Mail Client Login Screen
- Check for messages using your mail client.
The received message should not appear in your Inbox. The example receive Communications Agent deletes messages upon successful retrieval of the document. Figure 16 shows an Inbox with no messages.
Figure 16 Mail Client Interface Showing Empty Inbox
To Check the Tracking Logs for Received Messages.
If the message does not appear in your mail client, check ECXpert’s Tracing logs for the javaRecv document.
- From the Support Interface, select Tracking.
- From the Enter Search Constraints tab, select the following member IDs from the Sender/Receiver drop-down lists, and click Search:
- Select the file from the Results List whose timestamp most closely matches the time you sent the document, and click Retrieve.
The EDI document appears as shown in Code Example 7.
Code Example 7 EDI Document Retrieved From File Level Results Tab
FILE,/export/home/ecxadmin/ECX363_INT/NS-apps/ECXpert/data/work/tmp
0, IPS PAPER PRODUCTS,ABC CORPORATION, EARL OFFICE PRODUCTS
1,F,18,2.86
1,F,180,.84
1,F,36,.84
1,F,612,.84
1,F,36,.84
0,IPS PAPER PRODUCTS, ABC CORPORATION, L&L PUBLISHERS
1,F,2,95.04
1,F,36,4.32
1,F,18,4.32
1,F,18,3.24
1,F,36,3.24
1,F,18,3.24
1,F,36,3.24
End of File
- From the File Level Results tab, click Events.
Look through the events list to determine whether the FTP transfer was successful. Note the timestamp for the “FTP (APPLICATION) succeeded” event message.
- Navigate to the ftp server’s outbound directory, which in this case is tmp.
- Verify the document transferred properly by listing all *javaRecv* documents in the tmp directory, as shown in Code Example 8.
Code Example 8 javaRecv Documents Received to tmp Directory
> hostname
nala
> ls -lrt /tmp/*javaRecv*
-rw-r--r-- 1 ftpuser staff 268 Sep 18 10:53 /tmp/javaRecv.A37
-rw-r--r-- 1 ftpuser staff 268 Sep 18 10:53 /tmp/javaRecv.A38
-rw-r--r-- 1 ftpuser staff 268 Sep 19 02:00 /tmp/javaRecv.A41
-rw-r--r-- 1 ftpuser staff 268 Sep 19 02:00 /tmp/javaRecv.A42
-rw-r--r-- 1 ftpuser staff 268 Sep 19 16:19 /tmp/javaRecv.A49
-rw-r--r-- 1 ftpuser staff 268 Sep 19 16:19 /tmp/javaRecv.A50
-rw-r--r-- 1 ftpuser staff 268 Sep 19 17:32 /tmp/javaRecv.A52
-rw-r--r-- 1 ftpuser staff 268 Sep 19 18:41 /tmp/javaRecv.A54
-rw-r--r-- 1 ftpuser staff 268 Sep 19 18:48 /tmp/javaRecv.A56
-rw-r--r-- 1 ftpuser staff 268 Sep 29 23:51 /tmp/javaRecv.A59
>
Password UtilityECXpert provides the bdgsetpassword utility to encrypt passwords specified in the ECXpert configuration file (ecx.ini). This utility is necessary to configure passwords such as mail_userpwd in commjava-receive.
The bdgsetpassword utility can be found at the following location:
ECX_HOME/NS-apps/ECXpert/bin
ECX_HOME is the directory in which you installed ECXpert.
Environment Variables
Before you run the utility, modify your environment as follows:
On Solaris and Windows platforms, set an environment variable, BDGHOME, to point to:
ECX_HOME/NS-apps/ECXpert
On Solaris platforms, modify LD_LIBRARY_PATH to include:
ECX_HOME/NS-apps/ECXpert/lib
On Windows platforms, modify PATH to include:
ECX_HOME\NS-apps\ECXpert\lib
ECX_HOME is the directory in which you installed ECXpert.
Usage
When you run the bdgsetpasswd utility, you must specify which password you are generating, as indicated below:
bdgsetpasswd -i path/ecx.ini -s <section_name> -param <parameter_name> -v value
path: ECX_INSTALL_DIR/NS-apps/ECXpert/config
password: the password you want to encrypt for the configuration fileThe utility automatically updates the ecx.ini file. After running this utility, you must restart the Java receive Communications Agent for the changes to take effect.
TroubleshootingYou can use the ECXpert Event Log to troubleshoot errors encountered when sending or receiving messages.
To View the ECXpert Event Log
For more information on viewing the ECXpert Event Log, refer to the Chapter “Tracking the Documents that ECXpert Processes,” available from the ECXpert Administrator’s Guide.
Table 8 lists Java Communications Agent error event numbers, the message displayed, and possible causes and remedies.
Table 8 Java Communications Agent Error Events
Error
Description
20010
Could not find class %s.
< where %s is replaced by a classname that the Java Communications Agent engine cannot find >
Possible Causes: The particular class was not found by the Java Communications Agent engine.
Remedies: Verify that javacomm.jar is specified in java.class.path jvm_property in ecx.ini.
20011
The class %s is an invalid B2B Communications Agent Factory instance.
Possible Causes: The classname specified for the comm_agent_factory_class parameter in the ecx.ini file must implement the B2BInboundCommAgentFactory or the B2BOutboundCommAgentFactory interface. The class mentioned in the error does not implement either interface.
Remedies: Verify that the class mentioned in the error implements the B2BInboundCommAgentFactory or B2BOutboundCommAgentFactory interface.
20012
Error: Could not find method %s in class %s.
Possible Causes: The method specified in the error could not be found in the class. Either the method is not defined in the class or the class was not found.
Remedies: Verify that javacomm.jar is specified in java.class.path jvm_property in ecx.ini.
20014
An Exception was thrown by the Java Communications Agent.
Possible Causes: Some unknown exception has been thrown.
Remedies: Check the log files for more details.
