Foresight REST API Configuration

To check the Foresight REST API configuration user can run the Get request with status=y parameter that is. 

GET http://localhost:8080/ForesightREST?status=Y

The user gets all the config parameters with values in response. The response is as follows:

Foresight REST API Version 1.2.0 build v02
Status at 2024-09-04 11:28:16 UTC
Started: 2024-08-23 06:18:12 UTC
Jobs Run since start: 0
Instream Thread Pool Count: 5 (Max: 128)
Translator Thread Pool Count: 9 (Max: 128)
Max Validation Errors Count: 100 (Max: 1720000)
Job ID Type: Timestamp (yymmddhhmmss_nnnnn)
Guideline ID Match Required on PUT: true
Logging Level: 1
Job Logging: false
Job Retention: Forever
Skipped Transaction sets for PublishReport: 837,835
FSRest.ini Directory: /usr/local/tomcat/TibcoFSRest/
Instream Library Status: Loaded
Instream Library Version: 9.2.0 [Build 012r(64 bit): 11/19/2021]
Instream Edition:   Standard
Code Table: not found.
Guideline Version: ValidatorVersion=9.2.0.0
Instream Base Path: /usr/share/tomcat/tibco/instream/fseng/
Instream Ini Path: /usr/share/tomcat/tibco/instream/fseng/bin/
Translator Library Status: Loaded
Translator Library Version: 4.1.0 Build 007 [Build 007r(64 bit): 10/19/2020]
Translator Base Path: /usr/share/tomcat/tibco/instream/fseng/
Translator Ini Path: /usr/share/tomcat/tibco/instream/fseng/bin/
Guidelines Path: /usr/local/tomcat/TibcoFSRest/guidelines/
Maps Path: /usr/local/tomcat/TibcoFSRest/maps/
DataFiles Path: /usr/local/tomcat/TibcoFSRest/datafiles/
ControlFiles Path: /usr/local/tomcat/TibcoFSRest/controlfiles/
Jobs Base Path: /var/cache/tomcat/temp/TibcoFSRestJobs/
External System Links:
Validation Callback POST: Address=(none) Format=Unknown Format 0
Translation Callback POST: Address=(none) Format=Unknown Format 0 Default Buffer=2048
Notification POST: Address=(none) Format=Unknown Format 0
Message POST: Address=(none) Format=Default
File Request Callback POST: Address=(none) Format=(none)
Current Working Directory: /usr/local/tomcat
Operating System: Linux
Properties:
  APIKeyExpireTime=604800 (Src:ini)
  DefaultResponseMediaType=application/json (Src:ini)
  DefaultThreadLocking=false (Src:default)
  FileReqCallbackFormat=TEXT (Src:default)
  FileRequestCaching=ALL (Src:ini)
  FileRequestCallbackAddr= (Src:default)
  FileRequestCallbackSecurity= (Src:default)
  GuidelineIDMatchRequired=Y (Src:ini)
  InstreamIniPath=/usr/share/tomcat/tibco/instream/fseng/bin/ (Src:env[FSINSTREAMINI])
  InstreamMainPath=/usr/share/tomcat/tibco/instream/fseng/ (Src:calc)
  InstreamThreadCount=5 (Src:ini)
  JobIdType=S (Src:ini)
  JobRetention=ALL (Src:ini)
  LogLevel=1 (Src:ini)
  MaxErrorsCount=100 (Src:ini)
  MessageFormat=AuditSafe (Src:ini)
  MessagePostAddr= (Src:default)
  MessagePostFormat=JSON (Src:ini)
  MessagePostSecurity= (Src:default)
  NotifyPostAddr= (Src:default)
  NotifyPostFormat=JSON (Src:ini)
  NotifyPostSecurity= (Src:default)
  OutputJobMessagesSection=Y (Src:ini)
  RestControlPath=/usr/local/tomcat/TibcoFSRest/controlfiles/ (Src:ini)
  RestDataPath=/usr/local/tomcat/TibcoFSRest/datafiles/ (Src:ini)
  RestGuidelinesPath=/usr/local/tomcat/TibcoFSRest/guidelines/ (Src:ini)
  RestJobsPath=/var/cache/tomcat/temp/TibcoFSRestJobs/ (Src:ini)
  RestMapsPath=/usr/local/tomcat/TibcoFSRest/maps/ (Src:ini)
  RestRetainJobsPath=/usr/local/tomcat/TibcoFSRest/retainjobs/ (Src:ini)
  SkipTS=837,835 (Src:ini)
  TIInboundPath=/var/cache/tomcat/temp/inbound (Src:ini)
  TIOutboundPath=/var/cache/tomcat/temp/outbound (Src:ini)
  TimestampPattern=yyyy-MM-dd'T'HH:mm:ss.SSSXXX (Src:ini)
  TransCallbackAddr= (Src:default)
  TransCallbackFormat=JSON (Src:ini)
  TransCallbackSecurity= (Src:default)
  TranslatorIniPath=/usr/share/tomcat/tibco/instream/fseng/bin/ (Src:env[FSTRANSLATORINI])
  TranslatorMainPath=/usr/share/tomcat/tibco/instream/fseng/ (Src:calc)
  TranslatorThreadCount=9 (Src:ini)
  ValCallbackAddr= (Src:default)
  ValCallbackFormat=JSON (Src:ini)
  ValCallbackSecurity= (Src:default)
  jdbc.driver=oracle.jdbc.driver.OracleDriver (Src:ini)
  jdbc.platform=oracle (Src:ini)
  jdbc.url=jdbc:oracle:thin:@<Database Host>:1521/<SID> (Src:ini)
  jdbc.username=<Database Username> (Src:ini)
  secureWithAPIKey=y (Src:ini)

The status response parameters are described below. Note that the response values of config properties can be changed using the corresponding environment variable name. Unless otherwise specified, the overriding environment variable name is the parameter keyword converted to all caps with the prefix FSREST_ added. For example, the InstreamThreadCount parameter setting is overridden by the contents of the FSREST_INSTREAMTHREADCOUNT environment variable.

Keyword

Response Description

InstreamThreadCount

The number of processing threads in the Instream thread pool. It controls the number of Instream jobs that can be processed simultaneously. Set higher values for heavy loads, but too high can bog down the machine. The maximum setting is 128.

Example: InstreamThreadCount=5

The default value is 3.

TranslatorThreadCount

The number of processing threads in the Translator thread pool. It controls the number of translation jobs that can be processed simultaneously. You can set higher values for heavy loads, but too high can bog down the machine. The maximum setting is 128.

Example: TranslatorThreadCount=9

The default value is 3.

TimestampPattern

Sets the pattern for date and time output in the resource GET information.

Note: AuditSafe requires the timestamp format 'nnnn-nn-nnTnn:nn:nn.nnn+/-zzz'

Example: TimestampPattern=yyyy-MM-dd HH:mm:ss.SSSZ

Default: yyyy-MM-dd'T'HH:mm:ss.SSSXXX

InstreamMainPath

Directory path to the top of the Instream installation.

Example: InstreamMainPath=c:/tibco/instream/9.0

Environment Variable Override: FSINSTREAMMAINDIR

InstreamIniPath

Directory where the main Instream dir.ini file is located.

Example: InstreamIniPath=c:/tibco/instream/9.0/bin

Environment Variable Override: FSINSTREAMINI

TranslatorMainPath

Directory to the top of the Translator installation.

Example: TranslatorMainPath=c:/tibco/translator/4.0

Environment Variable Override: FSTRANSLATORMAINDIR

TranslatorIniPath

Directory where the main Translator dir.ini file is located.

Example: TranslatorIniPath=c:/tibco/translator/4.0/bin

Environment Variable Override: FSTRANSLATORINI

JobIdType

Controls the type of Job ID required.

‘S’ uses the current date and time along with a counter to create a Job ID of the format Jyymmddhhmmss_nnnnn.

Example: J190507164911_00001

‘U’ uses a full UUID for the Job ID.

Example: Jbca8888d-b27a-4cb5-9aeb-b4a1655bd066

Using ‘U’ is preferred when running more than one instance of the REST API on a single machine as the chance of generating identical IDs is greatly reduced. This allows the sharing of folder structures between the instances.

Example: JobIdType=S

Default: S

RestControlPath

Directory where REST ‘controlfiles’ resources are to be stored. Read/Write permissions are required.

Environment Variable Override: FSREST_CONTROLDIR
RestDataPath

Directory where REST ‘datafiles’ resources are to be stored. Read/Write permissions are required.

Example: RestDataPath=C:\FSRest\datafiles

Environment Variable Override: FSREST_DATADIR

RestGuidelinesPath

Directory where REST ‘guidelines’ resources are to be stored. Read/Write permissions are required.

Environment Variable Override: FSREST_GUIDELINEDIR

RestJobsPath

Directory where REST ‘jobs’ resources are to be stored. Read/Write and Create Directory permissions are required.

Example: RestJobsPath=C:\FSRest\jobs

Environment Variable Override: FSREST_JOBSDIR

RestMapsPath

Directory where REST ‘maps’ resources are to be stored. Read/Write permissions are required.

Environment Variable Override: FSREST_MAPDIR

OutputJobMessagesSection

Include Messages section in Job SYNC responses and Notifications

GuidelineIDMatchRequired

Indicates if any uploaded guideline must have an internal ID that matches its external filename.

Default: y

ValCallbackAddr

The HTTP address of the server that processes the Instream Callback HTTP POST request.

Example: ValCallbackAddr=http://<host-name>:<port>/CallbackTesterREST/ValCB

ValCallbackFormat

Indicates the content format for POSTs to, and replies from, the Instream Callback process specified in ValCallbackAddr.

Valid Values

J or JSON = application/json T or TEXT = text/plain

Default: TEXT

ValCallbackSecurity

Specifies the type of security with any parameters in use between Foresight REST API and the server/application processing the Instream Callback POSTs. The general format of this parameter is:

Type: Info

Where type is the code for the type of security implemented, and

Info is the additional data required for that type of security.

Currently, the following types of security are supported:

  • BASIC: Basic security, where the information contains the user ID and password separated by a colon (:).

  • BASIC64: Basic security with encode user ID and password, where the information contains the Base 64 encoded user ID and password.

Examples:

  • ValCallbackSecurity=BASIC:admin3:myPassword

  • ValCallbackSecurity=BASIC64:YWRtaW23aXdheQ==

TransCallbackAddr

The HTTP address of the server that processes the Translator Callback HTTP POST request.

Example: TransCallbackAddr=http://<host-name>:<port>/LocalApp/HandleFSRest

TransCallbackFormat

Indicates the content format for POSTs to, and replies from, the Translator Callback process specified in TransCallbackAddr.

Valid Values

J or JSON = application/json T or TEXT = text/plain

Default: TEXT

TransCallbackSecurity

Specifies the type of security with any parameters in use between the Foresight REST API and the server/application processing the Translator Callback POSTs.

(See ValCallbackSecurity description for details.)

NotifyPostAddr

The HTTP address of the server that processes the Notification Callback HTTP POST request.

Example: NotifyPostAddr=http://<host-name>:<port>/myApp/CatchFSRestNotify

NotifyPostFormat

Indicates the content format for POSTs to, and replies from, the Notification Callback process specified in NotifyPostAddr.

Valid Values

J or JSON = application/json T or TEXT = text/plain

Default: TEXT

NotifyPostSecurity

Specifies the type of security with any parameters in use between REST API and the server/application processing the notification Callback POSTs. (See ValCallbackSecurity description for details.)

MessagePostAddr

The HTTP address of the server that processes the Message Callback HTTP POST request.

MessagePostAddr=http://<host-name>:<port>/myLogger/catchMessage

MessagePostFormat

Indicates the content format for POSTs to, and replies from, the Message Callback process specified in MessagePostAddr.

Valid Values

J or JSON = application/json T or TEXT = text/plain

Default: TEXT

MessagePostSecurity

Specifies the type of security with any parameters in use between Foresight REST API and the server/application processing the message Callback POSTs. (See ValCallbackSecurity description for details.)

MessageFormat

Controls the format of the external messages that are sent to the messaging POST address. There are two values for MessageFormat:

default value passes the message as the body of the message POST, and

AuditSafe formats the message for AuditSafe, including passing the various AuditSafe fields.

Note: If this parameter is not present, or has values other than the two defined values, then it takes the default value. These values are not case-sensitive.

FileRequestCallbackAddr

The HTTP address of the server that processes the Message Callback HTTP POST request.

Example:

FileRequestCallbackAddr=http://<host-name>:<port>/myLogger/catchMessage

FileReqCallbackFormat

Indicates the content format for POSTs to, and replies from, the File Request Callback process specified in FileRequestCallbackAddr.

Valid Values

J or JSON = application/json T or TEXT = text/plain

Default: TEXT

FileRequestCallbackSecurity

Specifies the type of security with any parameters in use between Foresight REST API and the server/application processing the File Request Callback POSTs. (See ValCallbackSecurity description for details.)

FileRequestCaching

Cache files are returned to Foresight REST API via the FileRequest Callback. Files are cached by writing them to their respective Foresight REST API resource directory. For example, Guidelines are cached in the Foresight REST API Guideline directory, Maps are cached in the Foresight REST API Maps directory.

The caching is controlled using the FileRequestCaching parameter, which can be set in the FSREST.ini file. This parameter can be 'All' or a string of letters identifying the types of files to be cached. Example: A FileRequestCaching parameter of 'GMC' caches guidelines, maps, and control files.

G = guidelines, M = maps, C = control files, D = data files.

The order and casing of the letter are not significant, that is, GMC, mcg, and cgM mean the same thing.

Specifying 'All' or 'GMCD' are the same in the FileRequestCaching parameter.

If the FileRequestCaching parameter is set to 'None', then no files received via the File Request Callback are cached. As with the other parameters, the FileRequestCaching parameter can be overridden with the contents of the environment variable FSREST_FILEREQUESTCACHING.

Note: The FileRequestCaching setting has no effect if the FileRequestCallback parameter is not used.

LogLevel

Controls the verbosity level of log events:

0 = Errors

1 = Warnings

2 = Recommendations

3 = Informational

5 = Debug

Default: 1

DefaultThreadLocking

Sets the default setting for the jobs.

JobRetention

Controls whether job files, including output files, are kept on the system after a SYNCO or ASYNCO job is completed and their output is returned or posted.

Values:

All: All jobs and their output are kept on the system (default)

NoSYNCO: All jobs run with mode SYNCO has their files deleted once the job POST has been returned to the submitter.

NoASYNCO: All jobs run with mode ASYNCO has their files deleted once the job results and files have been POSTed and acknowledged by the NotifyCallback receiver.

Note: Both NoSYNCO and NoASYNCO can be specified, separated by a comma.

Example: JobRetention=NoSYNCO
secureWithAPIKey Secures your application using an API key for authentication.
APIKeyExpireTime Expire time (in seconds) for API key.
jdbc.platform

MYSQL or Oracle

If you are using an Oracle database, add its connector lib path to the database.driver.path
jdbc.driver Database driver URL
jdbc.url Database driver URL
jdbc.username Database username
jdbc.databasename

Database name for MYSQL or Oracle database.

Note: Property is specific to the Mysql database.
RestRetainJobsPath

Directory where RetainJobs resources are to be stored. Read/Write permissions are required. The parameter can be update using updateEnv request.

Following is the default RetainJobs path:

RestRetainJobsPath=/usr/local/tomcat/TibcoFSRest/retainjobs
TIInboundPath Inbound path of the Foresight Transaction Insight. You can update this using updateEnv request.
TIOutboundPath Outbound path of the Foresight Transaction Insight. You can update this using updateEnv request.
skipTS It skips one or multiple transaction set types for the copy operation. The default value is none, and could be set with the transaction set names, separated by commas. You can update this using updateEnv request.

Other Environment Variables

FSTRANSLATORINI Contains path to the Translator Installation’s bin directory.
InstreamIniPath FSINSTREAMINI
InstreamMainPath FSINSTREAMMAINDIR
TranslatorIniPath FSTRANSLATORINI
TranslatorMainPath FSTRANSLATORMAINDIR

Changing Foresight REST API Config Parameters

You can now change certain parameters without restarting the Foresight REST API server. This is done via a PUT operation to the main REST API address with the ‘updateEnv=y’ parameter. The body of PUT contains the parameters to change. You can change the following parameters:

TimestampPattern TransCallbackFormat FileReqCallbackFormat
JobIdType NotifyCallbackAddr FileRequestCaching
GuidelineIDMatchRequired

NotifyPostFormat

LogLevel
ValCallbackAddr MessageCallbackAddr JobRetention

ValCallbackFormat

MessagePostFormat DefaultResponseMediaType
TransCallbackAddr FileReqCallbackAddr NotifyPostAddr
MessagePostAddr RestRetainJobsPath  

For example:

http:.../ForesightREST?updateEnv=y

Body

LogLevel=0

ValCallbackAddr=http://NA-DUB-DOCKER1:8080/BCStubREST/ValCB

NotifyPostAddr=http://NA-DUB-DOCKER1:8080/BCStubREST/Notify

MessagePostAddr=http://NA-DUB-DOCKER1:8080/BCStubREST/Message

Note: Tags are case-insensitive and blank lines are ignored. Invalid entries are noted in the PUT response and no changes are made.