12
Integrating Portal-to-Go

This document discusses the features that enable you to integrate Portal-to-Go with other systems. It provides information on the listening agents and servers Portal-to-Go uses to enable email and Short Message Service (SMS) support. Topics include:

• Asynchronous Notifications

• Notification Engine

• SMS Listener

• Probe Runtime Monitor and Management

• RMI Server

• FTP Server

Asynchronous Notifications

Asychronous notifications are scheduled requests that Portal-to-Go delivers to end users. The end user configures notifications from the Personalization Portal. The Portal-to-Go system manages asynchronous notifications using the Oracle8i Advanced Queuing package. Portal-to-Go uses asychronous notifications to perform requests and notifications.

Request Queue

Portal-to-Go processes requests as follows:

1. A job is created or updated with a start date and a specified interval. An agent is connected to the job. The agent specifies the address and device type to which the result is sent.

2. If the start date is greater than the current date, the job is placed in the job scheduler.

3. When the scheduler executes the job, the Job object is activated and invoked. The result is placed in the notification queue. The Job object calculates the new execution date and saves it to the database. Once saved, the new execution date is added to the job scheduler with the new execution time.

4. If the job fails, it is not added to the job scheduler, and can only be activated by updating the start date again.

Notification Queue

Portal-to-Go processes notifications as follows:

1. The notification queue receives a message, such as an SMS or email message.

2. The notification queue immediately dispatches the message to the notification listener.

Component Requirements

Asynchronous messaging requires the following:

• The repository must be stored in Oracle8i.

• The database JOB option must be installed in Oracle8i and activated. See the init.ora file configuration in the Oracle8i documentation.

• The database AQ option must be installed in Oracle8i and activated. See the init.ora file configuration in your Oracle8i documentation.

Notification Engine

The notification engine implements the interface oracle.panama.util.NotificationListener, and is registered in the system properties key locator.notification.dispatcher.class.

The current implementation of the notification engine is the class:

oracle.panama.util.NotificationDispatcherImpl

This class dispatches messages to SMS or email agents using the following helper classes:

• oracle.panama.util.sms.SmsSender

• oracle.panama.util.mail.MailSender

You can customize all notification engine properties in the Notification.properties file, which you can find in the oracle/panama/core/admin directory. This property file contains the following parameters:

Key	Type	Modifiable?	Description
sms.account.id	AccountId	Y	The large account number of this system.
sms.server.name	HostName	Y	The SMS TCP server host name.
sms.server.port	Integer	Y	The SMS TCP server listening port.
dispatcher.logicaldevice. email.name	String	Y	The name of the email logical device in the repository.
dispatcher.logicaldevice. sms.name	String	Y	The name of the SMS logical device in the repository.
mail.server.name	HostName	Y	The SMTP server host name. This is mandatory.
mail.from	String	Y	The "from" address in mail headers. This is mandatory.
mail.organization	String	Y	The organization name in mail headers. This is optional.
mail.domain	DomainName	Y	The network domain name to send to the SMTP service when connecting. This is only needed if the SMTP server requires a HELO greeting.
mail.subject	String	Y	The default subject of mail messages.

Component Requirements

The current notification implementation requires the following components:

• An SMS-C TCP server available on the network.

• An SMTP service available on the network.

Limitations

The current notification engine has the following limitations.

• It can only construct SMS, Universal Computer Protocol, UCP messages of operation 01.

• The current character encoding is based on ISO-8859-1 for both SMS and email messages.

SMS Listener

The SMS Listener processes SMS requests and returns results as SMS messages. It processes requests by performing the following:

1. Authenticates the user by finding an agent with the actual address (phone number).

2. Selects the agent by searching the order of logical devices specified in the Notification.properties file. These include SMS and TTML devices. The message appears as a single line with the relative path of the service name. The path is relative to the users home/root folder.

3. Invokes the service.

4. Sends the result back to the caller by placing the message in the notification queue.

The SMS Listener uses notification functionality and shares properties configured in the Notification.properties file in the oracle/panama/core/admin directory.

This properties file has the following parameters:

Key	Type	Modifiable?	Description
sms.listener.port	Integer	Y	The TCP port on which the daemon listens.
sms.listener.logicaldevice. search.list	StringList	Y	The logical device search order, with highest priority first. The name must be the same as in the repository.

The implementation is managed by the daemon:

oracle.panama.util.sms.SmsServer

Component Requirements

The SMS listener contains the following component requirements:

• The notification components, both the queue and the engine, must be up and running.

• The caller must have a valid agent which specifies a telephone number, and a device that matches a device in the property file.

Probe Runtime Monitor and Management

The probe is a daemon that displays runtime information about:

• Log files

• Active objects

• Active sessions

• Active threads

The probe performs simple runtime management including:

• Shutting down an active object instance

• Refreshing persistent attributes on an active object

• Setting the global debug flag to on or off

• Reloading properties for device recognition when adding a new device to a running system.

By default, the Portal-to-Go installation process installs and initiates the probe runtime monitor with the listening port 8090. To access the probe, from a browser enter the following URL:

http://host_name:8090

You can configure the probe component by editing the www-server.properties file in the oracle/panama/core/probe directory.

The www-server.properties file has the following parameters:

Key	Type	Modifiable?	Description
port	Integer	Y	The TCP listening port.
root	Path	Y	The root directory for log files.
timeout	Milliseconds	Y	Timeout for a request TCP socket.
workers	Integer	Y	The number of working request threads to start up.
log	String	Y	True if the activity should be logged, otherwise false.

The following daemon manages the implementation:

oracle.panama.core.probe.WebServer

RMI Server

You can manage objects in the Portal-to-Go repository from a remote client using the RMI (Remote Method Invocation) server. The RMI server is a daemon that enables you to access and manipulate Portal-to-Go objects using an RMI interface. Currently, Portal-to-Go automatically generates the RMI component from the interface definitions using introspection of the compiled Java interfaces. See oracle.panama.core.util.GenerateRMI for more information.

An RMI session is stateless and each update call is always completed with a commit or rollback. For this reason, you can manage all persistent objects from a remote client. Management actions take immediate effect when the RMI server works at the object level of the system. To connect to an RMI daemon, you must provide a valid administrator user name and password.

You can configure the RMI component by editing the Rmi.properties file in the oracle/panama/core/admin directory.

The Rmi.properties file has the following parameters:

Key	Type	Modifiable?	Description
rmi.server.port	Integer	Y	The TCP port on which the daemon listens.
rmi.server.name	String	Y	The name of the RMI server.

The implementation is managed by the daemon:

oracle.panama.core.rmi.server.ServerImpl

FTP Server

The FTP server is a daemon that publishes the repository as an FTP file system. The repository folder is represented as an FTP directory, and repository objects are represented as FTP files. The FTP server makes it possible to upload and download users, services, and other repository objects as XML documents.

FTP support allows you to:

• Authenticate users (only administrators can use this utility).

• List directories and files.

• Download XML-enabled persistent objects.

• Upload XML-enabled persistent objects.

• Create subdirectories (service tree folders only).

• Delete directories (service tree folders only).

• Delete any object.

• Rename directories and files.

Note: When uploading new objects, you do not need to assign values to the unique name or objectid_ attributes. The upload feature uses "update or create" logic. If either the unique name or objectid_ attribute is set to the same value as an existing object, then the existing object is updated. The unique name of a service is the url attribute. For all other objects, the unique name is the name attribute.

The FTP component can be configured by editing the Ftp.properties file in the oracle/panama/core/admin directory.

The Ftp.properties file has the following parameter:

Key	Type	Customizable	Description
ftp.server.port	Integer	Y	The TCP listening port