DataMigrator/Reporting Server > Listeners and Special Services > Listeners

Listeners

Topics:

Configuring Listeners
Other Listener Options

How to:

Configure a SOAP Listener
Return a JSON Answer Set Using the SOAP Listener

The listeners are:

HTTP
TCP
SOAP

These listen for activity on their respective ports.

Note: To include a SOAP listener, you need to configure one. For more information, see How to Configure a SOAP Listener

Configuring Listeners

How to:

Configure a Listener

Reference:

Listener Basic Parameters
Additional Listener Parameters

All listeners have the same type of basic parameters. They differ in the additional parameters that are available. All three types have Security parameters. HTTP also includes Sessions Control, Aliases and Miscellaneous Settings.

Procedure: How to Configure a Listener

From the menu bar, select Workspace.
Open the Special Services and Listeners folder in the navigation pane.
Right-click a listener and select Properties.

The Listener Configuration page opens.
In the Basic section, you can enter a value for the HOST parameter.
If you need to set additional parameters, expand the corresponding section and enter values in the parameter fields.
Click Save and Restart Server.

Reference: Listener Basic Parameters

The HTTP, TCP, and SOAP listeners have the same type of basic parameters.

NODE

Defines the logical name of a node block. The settings are:

For HTTP - LST_HTTP.

For TCP - LST_TCP.

For SOAP - LST_SOAP.

PORT

Defines the port number that a listener is listening on. The default value for the HTTP listener is 8117. The default value for the TCP listener is 8116.

HOST

Defines an IP address that a listener is listening on. If blank, the listener will listen on all IP addresses.

Reference: Additional Listener Parameters

The HTTP, TCP, and SOAP listeners have the following security parameter:

RESTRICT_TO_IP

Defines the name of a host or IP address(es) that will be accepted by the listener. The syntax is

hostname, xxx.xxx.xxx.xxx, yyy.yyy.yyy, ...

The address must be in base 256 standard dot notation. For platforms that support IPv6, IPv6 notation can be used if it is enabled (for example, 2001:1b1:719:1b1:203:baff:fe0a:fe23)

The internal default is *.*.*.*, which allows all IP addresses.

Note: You can use a wildcard to mask an entire section of the address, as in the following examples:

172.204.201.*
172.*.*.*
172.204.*.*
2001:1b1:719:1b1:203:baff:*:fe23

Partial masking is not supported, for example:

172.204.201.1*
172.204.201.*23

The HTTP listener has the following additional parameters:

Security

SECURITY

Defines the authentication protocol used by a secured listener. The valid values are:

IWA - for NTLM protocol.
KERBEROS - for Kerberos protocol.

LOGIN_FAILURE

Defines the type of message shown for a login error. The valid values are:

0 - Shows a general error message.

1 - Shows a precise error message.

The default value is 0.

LOGIN_HIDE_PROVIDERS

Defines whether available security providers or domains should be shown in the login screen. The valid values are:

0 - shows all available security providers or domains.
1 - hides all available security providers or domains.

CSRF_TOKEN

Defines whether a secret token should be used in all form submissions. This is used to prevent cross-site request forgery attacks. The valid values are:

0 - disable CSRF token.
1 - enable CSRF token.

SANITIZE_PARAMETERS

Defines whether the HTTP listener should sanitize all submitted form parameters. Valid values are zero (0) to disable sanitizing of form parameters, or 1 to enable sanitizing of form parameters. The default value is 1.

X_FRAME_OPTIONS

Defines whether a browser should be allowed to render the Web Console in a frame. Valid values are:

NONE. This is available for the HTTP Listener only. The Web Console can be displayed in a frame.
DENY. The Web Console cannot be displayed in a frame.
SAMEORIGIN. The Web Console can only be displayed in a frame on the same origin as the page itself. This is the default value.

Enable HTTPS

Enables HTTPS support, either for OpenSSL or Microsoft Windows SSL.

Both types have the following additional parameters:

SSL_CERTIFICATE

Defines the SSL certificate. The sample certificate name provided by Information Builders for testing purposes for Microsoft SSL is iwaycert.p12.

SSL_PASSPHRASE_E

If the private key of the certificate is encrypted, an encrypted passphrase must be provided to decrypt the private key.

Note: The sample certificate provided by Information Builders as described under the SSL_CERTIFICATE parameter above contains an encrypted key. The passphrase for this sample certificate is 1234567.

The following additional parameters are specific to OpenSSL:

SSL_PRIVATE_KEY: Defines the file that contains the private key for the listener. It must correspond to the public key embedded in the PEM certificate and must be in PEM format.
SSL_CA_CERTIFICATE: Defines the file containing the trusted CA certificate in PEM format. It is used to verify the client certificate. If the client fails to send the certificate or if verification fails, connections will be rejected. More than one CA certificate may be present in the file.

The following additional parameter is specific to Microsoft SSL:

SSL_FRIENDLY_NAME

Indicates a name used to identify the certificate in the PKCS#12 file, if the file contains more than one certificate.

SSL_AUTH_CLIENT

Defines whether client authentication should be enabled. Valid values are:

0 (zero). The Client is not asked for a certificate. There is no client authentication. This is the default value.
1. The server requests a certificate from the client. All received certificates are validated. If the client fails to send a certificate or verification fails, connections will be rejected.

Sessions Control

PERSISTENT_GLOBAL

Defines whether global FOCUS variables will be persistent within a browser session. The valid values are:

0 - Global variables are not persistent within a browser session.

1 - Global variables are persistent within a browser session.

The default value is 0.

PASS_EXPIRE_NOTIFICATION

Determines whether users receive a password expiration notification by defining the number of days before expiration at which a notification will occur. The default value is 0, meaning no notification.

MAX_WEBSESSION

Defines the maximum number of active sessions. The HTTP listener will reject connections to the Web Console if this number is reached. The default value is 0, meaning no limit.

TIMEOUT_WARNING

Defines how many minutes before session expiration a warning message will be displayed. The default value is zero (0), which means there is no timeout warning message.

LOG_LAST_REQUESTS

Defines the maximum number of last requests in a session that will be collected as statistics. The default value is 10.

Alias

IBI_HTML: Defines a URL alias for the primary file lookup directory. Lookup is performed first in the directory described by this alias. The default value is $EDAHOME/etc.
HTML_HOME: Defines a comma-delimited list of directories for file lookup. Directories are searched in the order in which they appear in this list.
SESSION_EXPIRATION: This parameter has been deprecated and has been combined with the foccache_maxage parameter, in order to make sure that no foccache files remain when the session has expired. For more information about the foccache_maxage parameter, see Application Settings.

Miscellaneous Settings

DEFAULT_HOST

Defines the preferred hostname or IP address for the listener when a listener has multiple IP addresses or hostnames.

PROXY_SERVER

Runs the HTTP Listener as a proxy server. The valid values are:

0 - Proxy server for the HTTP protocol is off.

1 - Proxy server for the HTTP protocol is on.

The default value is 0.

Procedure: How to Configure a SOAP Listener

A SOAP listener needs to be configured before it will appear in the Special Services and Listeners folder.

From the menu bar, select Workspace.
Right-click the Special Services and Listeners folder, and select New, then SOAP.

The Listener Configuration page opens.
Enter values in the PORT and HOST fields.
Optionally, enter a host or IP address that will be accepted by listener in the RESTRICT_TO_IP field.
Click Save and Restart Listener.

The SOAP listener is added to the Special Services and Listeners folder.

Procedure: How to Return a JSON Answer Set Using the SOAP Listener

Using the Simple Object Access Protocol (SOAP) Listener, you can run report requests or DataMigrator flows using RESTful Web Service calls. The answer set is returned in JSON format.

First, configure the SOAP Listener as described in How to Configure a SOAP Listener.
Place the procedure to run in an application directory in the APP PATH of the Reporting Server.
Assuming you created the WebFOCUS Retail tutorial in the ibisamp application, the following FOCEXEC can be created in ibisamp to demonstrate the JSON Answer Set feature. If you created the WebFOCUS Retail tutorial in another application name, substitute application names where applicable.
```
TABLE FILE WF_RETAIL_LITE
SUM
  COGS_US
BY BRAND
BY PRODUCT_CATEGORY
BY PRODUCT_SUBCATEG
IF PRODUCT_CATEGORY EQ '&CATEGORY'
END
```
Note that the request has an IF test that requires a value for the variable &CATEGORY. You will supply the parameter name and value as part of the URL.
In a browser window, enter a URL in the following form.
```
http://host:port/rest/app/proc?param=value ...
```
where:

host

Is the Reporting Server host name.

port

Is the SOAP Listener port number.

app

Is the application that contains the procedure. This application must be on the APP PATH of the Reporting Server.

proc

Is the procedure name and extension.

param

Is a parameter name.

value

Is the parameter value.

Example: Returning a JSON Answer Set

For example, to run the retail_ws.fex procedure with the parameter &CATEGORY=Accessories, in the ibisamp application, on the host localhost, enter the following URL and press Enter.

http://localhost:8050/rest/ibisamp/retail_ws.fex?CATEGORY=Accessories

The following answer set is returned in JSON format. In this answer set, after the message header information and report statistics, each row is listed in an array named rows. The array of all rows is enclosed in square brackets ([ ]). Each row is enclosed in curly braces ({ }) and separated from the other rows by a comma (,). The rows consist of fieldname:value pairs separated by commas. Alphanumeric values are enclosed in double quotation marks (").

{ "_ibi_Report" : {"Messages" : [ "0 NUMBER OF RECORDS IN TABLE=       10  LINES=     10"],
"rows" : [
 { "BRAND" : "Audio Technica" , "PRODUCT_CATEGORY" : "Accessories" , 
  "PRODUCT_SUBCATEG" : "Headphones" , "COGS_US" :             38000.00}, 
 { "BRAND" : "Denon" , "PRODUCT_CATEGORY" : "Accessories" ,
  "PRODUCT_SUBCATEG" : "Headphones" , "COGS_US" :             25970.00}, 
 { "BRAND" : "Grado" , "PRODUCT_CATEGORY" : "Accessories" ,
  "PRODUCT_SUBCATEG" : "Headphones" , "COGS_US" :             21930.00}, 
 { "BRAND" : "Logitech" , "PRODUCT_CATEGORY" : "Accessories" ,
  "PRODUCT_SUBCATEG" : "Universal Remote Controls" , "COGS_US" :             61432.00}, 
 { "BRAND" : "Niles Audio" , "PRODUCT_CATEGORY" : "Accessories" ,
  "PRODUCT_SUBCATEG" : "Universal Remote Controls" , "COGS_US" :             73547.00}, 
 { "BRAND" : "Pioneer" , "PRODUCT_CATEGORY" : "Accessories" ,
  "PRODUCT_SUBCATEG" : "Headphones" , "COGS_US" :             16720.00}, 
 { "BRAND" : "Samsung" , "PRODUCT_CATEGORY" : "Accessories" ,
  "PRODUCT_SUBCATEG" : "Charger" , "COGS_US" :              5405.00}, 
 { "BRAND" : "Sennheiser" , "PRODUCT_CATEGORY" : "Accessories" ,
  "PRODUCT_SUBCATEG" : "Headphones" , "COGS_US" :             78113.00}, 
 { "BRAND" : "Sony" , "PRODUCT_CATEGORY" : "Accessories" ,
  "PRODUCT_SUBCATEG" : "Charger" , "COGS_US" :              3168.00}, 
 { "BRAND" : "Sony" , "PRODUCT_CATEGORY" : "Accessories" ,
  "PRODUCT_SUBCATEG" : "Headphones" , "COGS_US" :             18592.00} 
         ] 
} 
}

Other Listener Options

How to:

Configure the Servlet
Refresh the WebFOCUS Jar Files

The Listener right-click menu also enables you to configure the servlet and refresh the WebFOCUS jar files.

Procedure: How to Configure the Servlet

From the menu bar, select Workspace.
Open the Special Services and Listeners folder in the navigation pane.
Right-click TCP/HTTP and select Configure Servlet.

The Configure Servlet page opens.
Enter the path to your Java Development Kit in the JDK_HOME field or click or click the selector button (...) and navigate to it.
Optionally, you can elect to register the JDK by selecting y from the Register JDK_HOME drop-down menu.
Enter the string that uniquely identifies the servlet and is a part of the URL allowing access to the servlet in the Context PATH field. The default value is ibi_apps.
Click Configure.

Procedure: How to Refresh the WebFOCUS Jar Files

From the menu bar, select Workspace.
Open the Special Services and Listeners folder in the navigation pane.
Right-click TCP/HTTP and select Refresh WF jar files.

The Copy server related java components into WF installation directory page opens.
Enter the path to the jar files in the IBI_Repository_Root_Directory field or click the selector button (...) and navigate to it.
Click Refresh WF jar files.

Note: After copying the files, the application server will need to be restarted.

	WebFOCUS

Feedback