iConnect ebXML Client System

User Manual

1

I. INSTALLATION SETUP GUIDE

TABLE OF CONTENTS

I.D Configuring the Display Style Sheet and Internet Browser Application 9 iConnect URL 11

12 I.G Uninstalling iConnect Client System

G. II. USING ICONNECT ebXML CLIENT SYSTEM

II.A Sending and Receiving Messages 13

II.C. Adding New Contacts and Specifying Contact

Display Style Sheets 17

II.E. Settings for Proxy Server Access 31

II.F. Sorting Messages 33

II. G. Java Heap Size Settings 33

2

I. INSTALLATION SETUP GUIDE

I.A. System Requirements

1. Pentium III 450Mhz or higher or equivalent CPU. At least 128 MB RAM.

2. Operating System: Any Operating System that supports Java Runtime Environment (JRE) 1.4.1 or higher.

Sample Operating Systems supported are:

¾ Windows 95, 98, ME

¾ Windows NT 4.0 service pack 5

¾ Windows 2000

¾ Windows XP

¾ Linux Intel kernel v2.2.12

¾ Solaris

3. Minimum screen area setting is 800 x 600 pixels. Recommended value is 1024 x 768 for better viewing of the interface.

I.B. Installing & Running the iConnect Client System

1. Install the Java Runtime Environment using the JRE installer included in the zip file or downloaded from http://java.sun.com/downloads.html. To check whether the JRE is installed in the system, run "java -version" on the command-line prompt. If JRE is properly installed, you should see the following output at the screen:

C:\>java -version

java version "1.4.1_01"

Java(TM) 2 Runtime Environment, Standard Edition (build 1.4.1

Java HotSpot(TM) Client VM (build 1.4.1_01-b01, mixed mode)

3

2. Extract the iConnect zip file to a specified directory location. This extraction will create the iConnect folder which contains the needed files to run the application. For example, extracting the zip file to

C:\ will create iConnect folder in that directory.

3. Run the iConnect Client App: a) Windows Explorer

Go to the iConnect folder and double-click

iConnectRun.bat

file.

b) Command Line

Go to the iConnect folder, type

iConnectRun.bat

and then press Enter.

c) To run iConnect on Linux, use this command inside the iConnect folder:

$ sh ./iConnectRun.sh

Note:

Make sure that the file's executable permission is set correctly. You can issue this command to make the script file executable to all users:

chmod 777 iConnectRun.sh

4

4. After launching the iConnect, the application will check if the JRE's security file is updated. iConnect will automatically update JRE's security settings that will be used during runtime. A message will be prompted that the security settings was updated. Just restart the application after it shutdowns.

I.C. Setting Up Your Company’s Identity (Generating Key Pairs)

Public and Private keys generated by your iConnect Client app will be used to identify your client PC when accessing the message service of the iConnect Server.

Please follow these steps to generate the key pairs:

1. Go to

Options > Security & Identity

at the menu options to launch the

Security & Identity

Configurations

window.

5

2. Below is the Security & Identity Configurations. Click the

Security and Identity tab

to view the

Security & Identity settings.

Global Location Number (GLN): a 13-digit number used to uniquely identify a location. a.)

Specify the Global Location Number or GLN of your company to set the Local Party ID to be used by the application.

Local Party ID: identification name that will be registered to the iConnect server. It consists of the URL prefix

http://www.panc.org.ph/party/GLNnumber

a.) By default, the prefix of the Local Party ID is http://www.panc.org.ph/party/ . Click the

Edit Prefix button if you want to replace the prefix specified.

Company Name: Specify the company name.

Location of Private Key (secret key): contains the secret key file that will be used to identify the client user to the iConnect server.

Location of Public Key certificate: contains the certificate file which is issued after authenticating the public key file.

Passphrase – private key password

6

3. Click the

Generate new Key Pair

button to launch the Generate New Key Pair dialog box. Fill-up the following fields:

Enter Passphrase - Password for the Public and Private Key and for login access in the iConnect client application.

Private Key Filename – Filename of the Private key to be generated. Note that the extension name

.sk

will be automatically added at the end of the filename you specify. The Private key file will be saved at the

PrivateKeys

folder inside the iConnect application folder.

Public Key Filename – Filename of the Public key to be generated. Note that the extension name

.pk

will be automatically added at the end of the filename you specify. The Public key file will be saved at the

PublicKeys

folder inside the iConnect application folder.

Use file naming scheme to distinguish different key pair versions

Ex. Public key = company01.pk, company02.pk

Secret key = company01.sk, company02.sk

4. Click the

Save

button to generate the key pairs. This will take some minutes to finish depending on the speed of your computer.

5. After the key pairs are generated, click the

Save

button at the

Security & Identity Configurations window

to set your identity. This action might require you to restart the iConnect application.

It is important that you keep the

Private Key

(key pair with the .sk extension name) file from getting deleted or used by unauthorized persons. We recommend that you backup this file and take note of its passphrase. You can store the file in an access-secured directory or in a diskette. Just click the Browse button at the Security & Identity settings to specify the location of the Private/Secret key if you want to use it from a diskette of another folder.

7

The

Public Key

(key pair with the .pk extension name) file must be submitted to the iConnect System

Administrator for authentication, otherwise the client app will not be able to access the iConnect server.

Send an email to

[email protected]

with the attached Public Key file and specify the following needed information in the email content:

CN (Common Name) = Local Party ID used in generating the Public and Private keys

OU (Organizational Unit) = Type of Organization Unit (ex. Food Manufacturing, Semi-

O (Organization)

Conductor Firm)

Name of Organization / Company

L (Locality)

ST (State)

C (Country)

=

=

=

=

City

State/Province

Two-Letter Country Code

Here’s an example Public Key application info assuming that the Local Party ID is http://www.panc.org.ph/party/1234567890999 (GLN is 1234567890999):

CN = http://www.panc.org.ph/party/1234567890999

OU = Food Manufacturing

O = My Company

L = Quezon City

ST = Metro Manila

C = PH

The iConnect System Administrator will notify you as soon as the Public Key is authenticated.

Note: There is no need to click the

Generate new Key Pair

button when your Public Key is already authenticated by the iConnect System Administrator. All you have to do is simply indicate the location of your private key and public key certificate, set its valid passphrase and then click the

SAVE

button.

8

6. When you restart the application again, you will be prompted to enter the

Passphrase

for your Private

Key file. Enter the valid passphrase to login.

I.D. Configuring the Display Style Sheets and Internet browser application

Display Style sheets are used to format the XML message for HTML view using the Internet Browser.

Follow these steps to set the preferred display style sheets for each document type.

1. Go to

Options > Document Display Configuration

to launch the Document Display Configuration window.

9

2. By clicking the Browse button, set the location of the Internet browser application that will be used for viewing the XML messages in HTML format (e.g. Internet Explorer or Netscape for Windows,

Konqueror or Mozilla for Linux).

3. Set the Display Style sheet file for a particular document type by double-clicking the table row to launch the Set File dialog window. The default values are already set for installed document types.

4. Click

SAVE

button.

10

I.E. Setting the iConnect Server URL

1. Go to

Options > URL of iConnect Server

to specify the URL location of iConnect ebXML server.

The default value is https://www.iconnect.com.ph

.

I.F. Schema File Configurations

1. Go to

Options > Schema Path Configuration

to launch the window for viewing/importing the schema files that will be used to define the document type messages in the iConnect system.

11

2. By default there will be Document Types already installed in the system. You can find the schema files for these document types by referring to the Location column.

3. To create new document type, click on the

Import New Schema

button to launch the dialog window for importing the new schema file.

To uninstall the application, simply delete the iConnect folder.

4. Fill up the following text fields and then click the Import button to create the new document type based on the schema file:

Document Type

– name of the message document.

ex. PO, PRICAT

Description

– description for the message document.

ex. PURCHASE ORDER, PRICE CATALOG

Location

– file location of the schema file; click the Browse button to set the schema file's

location

I.G. Uninstalling iConnect Client System

12

II. USING ICONNECT ebXML CLIENT SYSTEM

II.A. Sending and Receiving Messages

To test the iConnect ebXML Client System use the sample PO (purchase order) CSV files provided during installation found in iConnect/TestCsv/po directory.

Sending PO Messages

1. Before importing the sample CSV files, set first the BUYER and SELLER GLN columns in the CSV file.

SET_SELLER_GLN_HERE with the seller/receiver GLN.

2. Go to

File > Import

or simply click IMPORT button to launch the Import CSV file to XML message window. This will create PO XML messages in OUTBOX folder.

3. Browse for the CSV file then click OK. You should see this message window.

13

4. Check your OUTBOX folder. There should be 5 messages in it.

5. Click SEND button to send PO XML messages from OUTBOX folder to iConnect ebXML server. All messages successfully sent will be archived in the SENT folder.

Receiving Acknowledgement from iConnect ebXML Server

1. Go to

File > Export

or simply click receive button to retrieve Acknowledgement messages from server.

2. All Acknowledgement messages will be placed in the ACKNOWLEDGEMENT folder.

3. These messages serve as a confirmation that the PO XML messages are now routed in the recipient’s inbox at the server.

If you are able to receive the acknowledgement messages properly, your private key and public keys are properly set and your connection to the iConnect ebXML server is working.

Receiving PO XML Message

1. Click RECEIVE button to retrieve PO XML messages from the server. All PO XML messages will be placed in the INBOX folder.

2. Export the PO XML messages as either CSV or XML file by selecting a file and clicking the EXPORT button.

II.B. Mapping Configurations

Default mapping configurations for the pre-installed document types are already specified for your convenience. You can use these mapping configurations to import the sample CSV file inside the

TestCsv directory in the iConnect folder. Reference for the mapping configurations for this CSV file is also located in the TestCsv directory.

To set iConnect on how to import CSV files to XML message and export XML message to the preferred

CSV format, specify the appropriate mapping columns for each document type.

1. Go to

Options > Mapping Configurations

. There are 2 options for this item: a)

Import (CSV to XML message)

- for setting the Import mapping configurations.

b)

Export (XML message to CSV)

- for setting the Export mapping configurations.

.

14

2. In the mapping configuration window, choose the document type for specifying the column numbers for each element/attribute of the XML message.

a) For Import mapping configurations, specify the column number where the XML element/attribute is located in the CSV file. You can leave the column number blank for optional elements/attributes so that these data will not be included in generated XML message. Be careful in specifying the column values to avoid parsing errors during import of CSV files. Duplicate column value entries are not allowed, except for the Receiver's Party ID, which is the GLN location of the receiver of your XML message document.

15

b) For Export mapping configurations, specify the column number where the XML element/attribute from the XML message will be placed in the generated CSV file. Take note that empty field entries are not allowed and column values should be sequential.

c)

documentID

parameter should be set always to 1.

d) Click the

Save

button to save the settings.

16

II.C. Adding New Contacts and Specifying Contact Display Style Sheets

You can add contacts containing company information such as Name and Party ID. Contacts are useful to easily identify the sender or receiver of your messages in the message grid view. You can also specify specific display style sheets for each contact.

1. Add a contact list by: a) Right-clicking at the Contact List window pane. Choose

New Contact

to launch the edit window, or b) Go to

File > New > Contact...

at the menu option.

17

2. Fill-up the text fields and then click the

Save

button when finished.

Note:

Name

and

Party ID

are required values.

3. At the bottom of the Contact editing window, you will see a grid table where you can specify display style sheet for a particular contact. Double-click on the File Location’s row to launch the Set File dialog window. Choose the display style sheet file of the contact.

4. Click the Save button to save all settings.

18

II.E. Schedule Manager

The iConnect Schedule Manager lets users automate the 4 basic tasks of the client system: (1) Import

CSV files to generate the XML messages, (2) Send XML messages to the iConnect server, (3) Receive

XML messages from the iConnect server, and (4) Export XML messages to CSV or XML files. To automate any of the 4 basic tasks, users must specify schedule entries in the Scheduler Manager. During the automated run of the specified tasks, logs will be prompted on the log screen and saved also to a file.

Users can do other operations like viewing a message in HTML or XML while the Scheduler Service is running.

To set the Scheduler settings, go to

Options > Schedule Manager

to launch the Schedule Manager window.

Below is a brief description of the controls you will see in the Schedule Manager.

19

The following diagram shows the

Basic Schedule Controls

in the

Schedule Control View

that can be used for setting the schedule for each task.

20

The following diagrams describe the

Specific Controls

for Import/Export and Send/Receive. These controls can be found below the

Basic Schedule Controls

in the

Schedule Control View

.

21

22

How To Define Schedules in the Schedule Manager

There are 5 parameters that should be specified when defining a schedule in the Schedule Manager:

1.

Schedule Task Option – parameter for specifying if the task will be scheduled for automated run.

2.

Time – parameter for time entry values specified in the Set Time Per Time or Set Time By Range option.

3.

Day – parameter for containing which day of the week the task will be executed.

4.

Week Frequency – parameter for per week frequency, i.e. if the task will be executed every week, every 3 weeks, etc.

5.

Start Date – parameter for specifying the start date of task execution.

23

Here’s an example on how to set schedules using the

Basic Schedule Controls

:

Example 1:

Task for Scheduling = Import File to XML Message

Time = 9:00 AM, 12:15 PM & 5:59 PM

Day = Every Weekdays

Week Frequency = Every Week

Start On = Today (Jan 22, 2003)

24

If the current OS date/time is Jan 22, 2003 WED 4:30PM, the Scheduler Service will execute the task on the next latest schedule which is Jan 22, 2003 WED 5:59PM. The table below shows the 1-week schedule that will be generated after saving the settings on Jan 22, 2003 WED 4:30PM:

DATE

JAN 22, 2003 WED

JAN 23, 2003 THURS

JAN 24, 2003 FRI

TIME

5:59 PM

9:00 AM

12:15PM

5:59 PM

9:00 AM

12:15 PM

5:59 PM

JAN 27, 2003 MON

JAN 28, 2003 TUES

9:00 AM

12:15 PM

5:59 PM

9:00 AM

12:15 PM

5:59 PM

25

Example 2:

Task for Scheduling = Send XML Message to Server

Time = 9:30 AM to 11:00 PM / Every 3 Hours

Day = Every Tuesday, Thursday and Sunday

Week Frequency = Every 2 Weeks

Start On = Today (Feb 14, 2003)

26

If the current OS date/time is Jan 22, 2003 WED 4:30PM, the Scheduler Service will execute the task on the next latest schedule which is Feb 16, 2003 SUN 9:30AM (Feb 14, 2003 is not the next latest schedule because this date falls on Friday). The table below shows the 5-week schedule that will be generated after saving the settings on Jan 22, 2003 WED 4:30PM:

WEEK DATE

FEB 16, 2003 SUN

TIME

9:30 AM

12:30 PM

3:30 PM

1st FEB 18, 2003 TUES

FEB 20, 2003 THURS

6:30 PM

9:30 PM

9:30 AM

12:30 PM

3:30 PM

6:30 PM

9:30 PM

9:30 AM

12:30 PM

3:30 PM

6:30 PM

9:30 PM

2nd

3rd

4th

5th

No Schedule

MAR 2, 2003 SUN

MAR 4, 2003 TUES

MAR 6, 2003 THURS

No Schedule

MAR 16, 2003 SUN

MAR 18, 2003 TUES

MAR 20, 2003 THURS

(same time)

(same time)

(same time)

(same time)

(same time)

(same time)

Note: Week starts on Sunday

27

How To Use the Import/Export Directory Bin

To use the

Import

and

Export

task scheduler, users must set the Directory Bin folder location wherein the CSV/XML files will be placed for import or export. To set the Directory Bin location, set the

Location of File

parameter at the

Specific Control for Import/Export Tasks

(please refer to the Overview discussion).

The Directory Bin consists of subfolders inside the specified Directory Bin location. Let’s say that the user specified C:\For Import folder as the Import task’s directory bin and C:\Exported folder as the Export

Task’s directory bin. Assuming that we have 3 document types namely; PO, PRICAT and PRODAT, the following directory bin structure will be created after saving the scheduler settings:

28

The

Errors

and

Imported

folders are automatically generated by the Schedule Manager. The Schedule

Manager will create the

Document Type (PO, PRICAT and PRODAT) Folders

based on the imported schema file document type name. If a schema file for a new document/message type is imported in the

Schema Path Configuration, a new folder for this document type will be created in the Directory Bin for

Import Task (assuming that the Import Task is set for scheduling).

For example, if a new document type named RETURN was imported in the Schema Path Configuration and the Import task is set for scheduling, a RETURN document type folder will be created automatically in the C:\For Import directory bin. All RETURN CSV files must be placed in the RETURN document type folder for automatic import by the Scheduler Service.

For Export Task, the directory bin will consist only of document type subfolders. All messages that are exported will be placed in the appropriate document type folder. If a message was not successfully exported, the message status will not change to EXPORTED at the Message View window.

An appropriate log message will also be shown at the Service Log tab in the Schedule Manager and saved on log files located in the

logs

folder inside the iConnect application folder. Below is a sample view of the directory structure for Export Task:

29

Starting/Stopping the Scheduler Service

After saving all the settings for each tasks, click on the Start button to activate the Scheduler Service.

When the Scheduler Service is successfully started, the status message at the lower right corner of the main iConnect window will change from

Scheduler Service is OFF

to

Scheduler Service is ON.

30

Click on the Service Log tab to view the log Messages shown.

There are two types of log messages: (1) INFO and (2) ERROR. Here are some of the common logs that can be shown by INFO and ERROR log messages:

INFO LOGS

¾ Next Schedule

¾ Start Date/Time value of an executed task

¾ Location of successfully imported files

¾ Files that were exported

¾ Send and Receive duration

¾ Number of messages sent/received

ERROR LOGS

¾ Send/Receive errors

¾ Import/Export errors

The log messages also have daily archive files located at the

logs

folder located inside the iConnect folder.

To stop the Scheduler Service, click the Stop button at the Schedule Manager.

31

II.F. Settings for Proxy Server Access

iConnect can access the Internet through a proxy server for sending/receiving messages. Use

iConnectRunProxy.bat

in Windows or

iConnectRunProyx.sh

in Linux to launch iConnect configured for proxy server access.

To configure iConnect for proxy server access, edit

iConnectRunProxy.bat

or

iConnectRunProyx.sh

and specify the proxy server IP address and port number for the following parameters:

-Dhttps.proxyHost=SET_IP_ADDRESS_HERE (Proxy Server IP address)

-Dhttps.proxyPort=SET_PORT_VALUE_HERE (Proxy Server Port Value)

Here's an example of a valid parameter setting inside the batch file: java -DproxySet=true -Dhttps.proxyHost=192.168.0.111

-Dhttps.proxyPort=3128 -Djavax.net.debug=all .....(other parameters)

In order for iConnect client system to connect to the iConnect server, the proxy server must allow https connection and security policies (i.e., user authentication) should be configured properly to allow the client app to access the iConnect Server URL (see Part 1 Section E for the default iConnect Server URL value). If the client app is installed in a computer behind a firewall, make sure that the firewall allows https connection via port 443.

Notes on Proxy Server Setup

iConnect ebXML client system is a stand-alone Java application that is capable of sending and receiving ebXML messages to/from a secured web server. iConnect is dependent on the environment settings in the Java Virtual Machine or JVM, and by default the JVM is configured for a proxy server access. By using the iConnectRunProxy.bat batch program, the JVM will be configured for proxy server access. The

JVM only supports HTTPS proxy settings using the Host (IP Address) and Port parameters. Proxy server authentication can only be done with Java's http proxy settings, which include a username, password,

Host, and Port parameters. In the case of the iConnect client app, the web server is accessed through a https connection.

If your computer is behind a firewall, the proxy server must also handle HTTPS requests for you to visit a secure Web site on the Internet. However, there is one significant difference between a proxy server processing HTTP requests and HTTPS requests. For HTTP requests, the proxy server is able to parse the communication content and exercise a lot more discretion on policing the traffic, including dropping the connection at the appropriate time (a proxy server always assumes HTTP connections are nonpersistent).

On the other hand, the proxy server will not be able to decipher HTTPS connections because of encryption, so it has no choice but to relay the data intact and cannot drop the connection unless the client and or the server desires so. Another "secret" of HTTPS proxy connections is that the actual client/server communication need not to be encrypted or involve SSL, even though this type of connection is often called SSL Tunneling. Again, this is because the proxy server assumes the subsequent communication will not be readable.

iConnect uses SSL for sending and receiving confidential XML messages. SSL does not support proxies in the way that clear text HTTP does in terms of protocol design, since an SSL connection is end-to-end.

Only the original server on the remote end can do the necessary decryption and encryption for communication. Contrast this with Plain HTTP, which is easily handled by a server such as Squid or MS

Proxy Server, because it takes requests as a server and makes requests as a client. One possible approach to allow iConnect client app to connect to an HTTPS web server through a proxy server is to set

32

per-IP basis security policies. Network Administrators can do this by relaxing the security policies for accessing the iConnect web server at https://www.iconnect.com.ph

.

II. F. Sorting Messages

iConnect (v1.3.2.) offers a new feature wherein you can sort messages either in ascending or descending order according to column, by clicking at the table grid columns.

Table Grid Columns

II. G. Java Heap Size Settings

The Java heap size can be set depending on the size of RAM installed in your PC. This is done to enable the JVM run on the correct RAM settings and as a solution whenever your application encounters

Out of Memory error.

To set the Java heap size, edit the

iConnectRun.bat

using any text editor application. In the batch file, you will see the following command: java –cp . . . (other parameters)

For example, if the RAM installed is 128MB insert the following after the word “java”:

-Xms128m –Xmx128m

The batch file should contain the following after editing: java –Xms128m –Xmx128m –cp ... (other parameters) where "128" is the allocated heap size in megabytes.

Save the batch file and run iConnect. iConnect User Manual Revision 1.5

© 2003 Supply Chain Networks, Inc.

33