Open topic with navigation

Kourier Integrator Online Help

Kourier Data Source Name (DSN) Guide

Kourier uses DSNs (Data Source Names) to transfer messages between U2 and other applications such as a corporate intranet or a CRM application. A source DSN defines where an application places messages to be retrieved by Kourier and imported into U2. A target DSN defines where Kourier sends messages from U2 to be processed by another application.

When you define a Kourier DSN, you specify a class that determines how the messages are transferred. Likewise, the DSN has an address that tells Kourier where to deliver messages or from where to retrieve them. When defining a DSN that accesses messages on secured servers, you must also specify the required credentials.

Kourier uses these DSNs while processing services. Each service defines a source and a target DSN, each of which can optionally have an append address. When services run, Kourier retrieves messages from the source DSN, modified by its append address. Messages from the source DSN are placed in a queue for that DSN so that Kourier can more easily access them. The service process all the messages generating result messages. Kourier sends these messages to the target DSN after modifying it with its append address. For a more complete explanation of how Kourier processes services, refer to the Kourier Services Guide.

When Kourier retrieves messages from a source DSN, they are typically deleted from the source location. There are some classes such as HTTPGET where this is not the case.

Because of the nature in which Kourier moves and deletes messages, it is possible to corrupt your database if you incorrectly configure a DSN. Always make sure to use the safest DSN class possible for your application, and make sure to take extra precautions when specifying the address.

Class

A DSN class defines the fundamental type of each message and how the message is transferred. Some DSN classes can only be used as a source DSN. Other classes can only be used as a target DSN. The remaining classes can be used both as source and target DSNs.

The class also defines the method that is used to transfer the messages. Some classes transfer data using standard UniBASIC statements, while others use networking protocols such as FTP and HTTP. The class also defines the message type of the data. For example, messages transferred using UniBASIC statements will transfer items in U2 files, while FTP transfers OS-level files.

The class will also specify where the messages can exist. In order to access files in an RDBMS file, you must use a DATA class DSN, and when accessing data from an FTP server, you must use an FTP class DSN. Regardless of the class, the location must be accessible from the U2 server.

To access messages on servers other than the U2 server, there must be network access to the server.

The HTTPGET and HTTPPOST classes are optional and purchased separately, and may not be available on your system.

Address

The address that you specify for a DSN defines the exact location of target or source messages. The syntax for addresses is the same as the URLs that are used to define internet addresses; the protocol part should be omitted and have the following format:

://server/path?query

Kourier suppresses the display of the protocol field because it is encapsulated in the class and is thus redundant. A complete URL can be obtained by appending the address field to the end of the class field.

The way Kourier interprets addresses depends on the DSN class and whether it is a source DSN or target DSN. For example, the server part is ignored in a DATA-class DSN, but required in an FTP-class DSN. Likewise, a search query may be specified for a source DSN but not a target DSN. Although the parts of an address vary between classes, the purpose of each part is generally the same. The server defines the name or IP address of the server that has the messages. It can be on the corporate WAN or the Internet, provided the U2 server has access to it. If omitted, the server field is assumed to be "localhost," the U2 server on which Kourier is running. The path part specifies the path on the server that contains the messages. The query part is typically used when accessing Web servers, or when specifying search criteria for source DSNs.

If the user enters an address with incorrect or ambiguous syntax, Kourier re-formats the address. It is common to accidentally omit the server part when specifying an address for a local resource such as a database file or directory. This can yield unexpected results. Always make sure that you don't inadvertently specify an incorrect server part of an address.

Addresses can contain substitution tags that can specify dynamic values when the message is transferred. Use these tags when the address cannot be fully specified at design time. It is good practice to use the {%SEQUENCE} substitution tag when sending messages to a target DSN to ensure unique message IDs so newer messages do not overwrite older ones.

When exchanging messages with another application, you may have multiple services accessing messages in a common location where only the message ID differs. You can often simplify data entry by defining DSNs with a partial address and define append addresses in each service that references them. Refer to Append Addresses for more information on this technique. 

DATA Class

DATA-class DSNs can be used either as a source or target. The path defines the RDBMS file and optional record ID. When being used as a source DSN, an optional search can be specified. Kourier accesses messages as items in an RDBMS file through a file pointer in the VOC.

Used in conjunction with directory-type file pointers, you can access virtually any file on the local server. This is done by creating VOC entries that are pointers to directories on the system. This results in each OS-level file in the directory to behave as an item in an RDBMS file. This an especially good practice when your messages are contained in directories in a database account. For more information about creating directory-type file pointers, refer to the manual that came with your RDBMS.

The syntax for different usage is shown below.

When specifying conditions, the equal sign (=) is part of the standard URL syntax and cannot be used in the condition itself. Use EQ instead.

Examples 

This is an example of a source DATA class DSN that looks for any message placed in the XML file:

:///XML

This is an example of a target DATA-class DSN that sends an EDI 850 purchase order document to the RDBMS file EDI_FROM_ACME for processing. Each item in the file has the EDI document type 850, the date and time the message was received, and a sequence counter to ensure that newer items don't overwrite unprocessed older items (e.g. 850.03-01-2001.11:02:51.380):

:///EDI_FROM_ACME/850.{@DATE}.{@TIME}.{%SEQUENCE}

This is an example of a source DATA-class DSN that selects only part messages beginning with "PART" from the file FR_PLANT01 file, which may contain other types of messages:

:///FR_PLANT01?select=EQ "PART]" 

FILE Class

FILE-class DSNs can be used either as a source or target. To access message files in the specified directory, Kourier uses OS-level file movement commands, such as MOVE on Windows and mv on UNIX. As a result, messages can be located on the local U2 server or a remote server subject to network and security restrictions.

You can use any path that defines the full pathname as accessed from the U2 server. In the case of a UNIX system using NFS, the remote directory must be mounted to a local directory. In the case of Windows, any UNC-style share address or mapped network drive can be used.

The user account under which Kourier runs must have full read/write/delete permissions for the specified directory.

All of the path up to the last directory delimiter is assumed to be the directory that contains the message. The last part of the path is the filename and becomes the message ID. For source DSNs, you can use file system wildcards appropriate for the OS.

When using wildcards, use those wildcard patterns that are specific to your operating system.

If you don't know the name of the file when defining a DSN or append address, you can only select files in a directory by using wildcards. Otherwise, Kourier will assume incorrectly that the last part of the directory name is a file and will generate an error. 

The syntax for different usage is shown below.

It is possible to corrupt your database if you incorrectly configure a FILE-class DSN. In many cases, it is possible to use a DATA-class DSN which adds an additional level of protection against inadvertent data loss. If you must use the FILE-class, make sure to take extra precautions when configuring the Address.

Examples

This is an example of a source DSN on a UNIX-based system that selects only part messages where the filename begins with "PART" from the directory /dbms/temp, which may contain other types of messages.

:///dbms/temp/PART*

FTP Class

FTP-class DSNs can be used either as a source or target. The server specifies the name or IP address of the FTP server. All of the path up to the last directory delimiter is assumed to be the directory that contains the message. The last part of the path is the filename and becomes the message ID.

If you don't know the name of the file when defining a DSN or append address, you can only select files in a directory by using a search query. Otherwise, Kourier will assume incorrectly that the last part of the directory name is a file and will generate an error. 

You typically have to specify credentials when creating an FTP-class DSN. This user must have the proper access to the specified directory on the FTP server, otherwise Kourier will generate errors in the event log. If creating a source DSN, the user must have read and delete access. If creating a target DSN, the user must have read, write, and delete access.

If you get errors when using an FTP-class DSN, use any FTP client (i.e. Microsoft Internet Explorer or WS_FTP) to test the connection. Connect to the server and log in using the credentials specified in the DSN. Change to the directory specified in the path, and make sure that you can create and/or delete files as required. It may be necessary to run the FTP console application from the U2 server to ensure that the server has the proper network access. 

The syntax for different usage is shown below:

Examples

This is an example of a target FTP-class DSN that sends sales information to a reports directory on the corporate sales server. The name of the server is "sales." Each message is written with the name "SALES" followed by the date and the extension ".txt". This directory will only contain the last message sent to this DSN on any given day.

://sales/reports/SALES.{@DATE}.txt

This is an example of a source DSN that selects EDI advance ship notice (856) messages that are made available on a trading partner FTP site, ftp.acme.com. All accessible EDI documents including the ship notices are placed in a customer-specific folder cust1013, and the ship notices have prefix "E856".

://ftp.acme.com/cust1013?select=EQ "E856]"

HTTPGET Class 

HTTPGET-class DSNs can be used only as a source. The entire address is the Web page address to get.

The syntax for usage is shown below:

Example 

This is an example of a source DSN that retrieves the current exchange rates from a public web page. This data is then parsed to update the local currency exchange rates file in U2.

://moneycentral.msn.com/investor/market/rates.asp

HTTPPOST Class

HTTPPOST-class DSNs can be used either as a source or target. The entire address is the Web page address to POST to. When used as a source DSN, the message is the web page generated from the web server as a result of the POST. When used as a target DSN, the message is the data that is posted to the address, and the response from the server is discarded.

This is sometimes done to execute a process on a web server.

The syntax for usage is shown below:

Example 

This is an example of a target DSN that runs an active server page that updates information on a corporate intranet Web site.

://intranet/updateinfo.asp 

SMTP Class

SMTP Class DSN's can only be used as a target. This DSN is used when Kourier sends e-mails generated in U2 to the intended recipients.

The syntax for the only usage is shown below:

You sometimes have to specify the username part of the credentials when creating an SMTP-class DSN. This user must have the proper access to send e-mails, otherwise Kourier will generate errors in the event log.

If you get errors when using an SMTP-class DSN, use any telnet client to test the connection. Connect to port 25 of the server and log in using the credentials specified in the DSN. It may be necessary to run the telnet console application from the U2 server to ensure that the server has the proper network access.

Examples

This is an example of a target DSN that sends e-mails using an internal SMTP server named mail:

://mail

This is an example of a target DSN that sends e-mails via a remote corporate SMTP server:

://mail.acme.com

SOCKET Class

SOCKET-class DSNs can be used as a target DSN. Kourier implements the socket interface in blocking mode where Kourier sends a message and then waits for a response from the integrating application and then reads that response from the socket. Once the response is received, the outbound message and the response is passed to an application subroutine for further application processing (i.e. logging responses to a file, writing an event to the Kourier event log).

The syntax for usage is shown below:

The supported query arguments are:

Example

This is an example of a socket DSN that connects to server 75.55.58.163 on port 6005 with an application subroutine named KMK.Z96 and a socket timeout value of 20000 milliseconds.

://75.77.58.163:6005?APPSUB=KMK.Z96&TIMEOUT=20000

SYSTEM Class 

SYSTEM-class DSNs do not have a source or target. Messages in this class remain internal to Kourier queues.

The Kourier SYSTEM DSN reserves a queue for the internal Kourier SYSTEM queue that is used when processing services.

To create a messaging application that leverages message queuing, you can create a SYSTEM-class DSN. The only way to access a SYSTEM-class DSN is by using the Kourier messaging API.

SYSTEM-class DSNs have no address.

Credentials

Credentials consist of the username and password that are required when accessing secure servers. When you define a DSN that accesses a secure server, you must specify these credentials so Kourier can access the server.

The following classes support credentials:

• FTP
• KS_EXPORT
• SMTP (username only)

Append Addresses

When integrating with complex applications, you frequently have many services that access messages in the similar locations. For example, different services may retrieve all their messages from the same FTP server but in different directories. Or, they may even retrieve them from the same directory but with different filenames. In situations like these where most of the DSN information is identical and only the directories or filenames change between services, you can use append addresses to minimize maintenance.

To use an append addresses in a service, first define a DSN that has the root information that is common between the different services; then reference the DSN as usual in each of the services, and place the additional unique information in the append address for the DSN. Append addresses can be specified for both source DSNs and target DSNs as required.

The different parts of an append address are appended to the parts of the DSN address independently. If a part exists in either the DSN address or the append address but not both, then the result address contains only that part. When the part exists in both the DSN address and the append address, then the parts are appended to each other. The path of the append address is added to the path of the DSN address using a directory delimiter (/). The query part of the append address is added to the query part of the DSN address using the query delimiter (&). The exception to this is when both the DSN and append address specify a server part. In this case, the server part from the append address is used.

Related Topics: 

Kourier Services

Kourier Messaging Guide