14.1 API Agent

On This Page:

What does the API Agent do?
System Parameters
Logfiles

Related Pages:

What does the API Agent do?

Basically, the API Agent (spapiagent) is the routing process for ServiceOptimizer API clients. It connects API clients to the correct FRU process and collates results back from multiple FRUs.

Example syntax: MUST only be run by spsysmon

Parameter	Options	Description
-d	<database>	Mandatory database connection string (supplied by spsysmon)
[-c <num>]	The default number to use is: four.	Number of database connections to use. Should be set to: sp409.listener_count(component=apiagent port_type=C-API) + sp409.listener_count(component=apiagent port_type=SOAP) + sp083 value for jeopa_nwt + number of expected concurrent SP_DispatchInitEx commands (value between 1 and sp083 value for disa_nwt) + 2,
-i <componentId>	This is supplied by the System Monitor	Component identifier for this component.
[-m <monitorId>]	This is supplied by the System Monitor.	Component identifier for System Monitor. This parameter is optional: if it is not present then it is assumed that there is no System Monitor controlling this process.
[-S secsToSleep]		This is for ServicePower internal use only, and tells the API Agent to pause for the specified number of seconds during the process initialisation.
[-n <retryLimit>]	Default value is set to 3 if a value is not specified.	Number of times the API Agent process will attempt to reconnect to the database before signalling it has failed
[-r <retryDelay>]	Default value is set to 3 if a value is not specified.	Time interval between database reconnection attempts. Care must be taken not to set the time interval too high as blocking threads will cause issues.
[-h]		Display usage message.

System Parameters

The following Database sp083_system_parameters apply specifically to the configuration of the API Agent and control how it manages the various aspects of its behaviour:

Communicating with the FRU processes

Parameter Description

apia_spuserid When the API Agent logs on to the FRU processes it needs to supply a username and password. A special user name should be set up in sp085_users (see 14.1 Access Control) for this purpose and this user name must then be added into the sp083_system_parameters table entry apia_spuserid. Failure to set this up will mean the APIAgent will be unable to communicate with the FRUs.

apia_cfru Number of connections made by API Agent to each FRU Process. This must be set to the number of API clients, up to a maximum of database sp409_component_ports.<listener_count>(GR). If you have a very large setting here you will use a lot of socket connections (especially if you have a lot of FRUs). Set too low and the requests will be queued in the API agent. This setting depends to some extent on the degree of geographical overlap - if every request goes to all FRUs at once then it needs to be larger than if each request goes only to one FRU.

Note that all these parameters are installed in the database but no default value is supplied for apia_spuserid. A valid value must be supplied for this parameter to run ServiceOptimizer - the system will not start up without one.

Note, also, that an associated password is also required, to allow authentication as described in 14.1 Access Control. There are no specific requirements as to the format of this password.

Managing the dispatch processes

Parameter	Description
disa_nwt	Specifies how many Dispatch Agent Worker Threads should be used. You will need help from a consultant to set this up. It is critical to the running of the system and incorrect settings can result in performance degradation, system instability or hitting operating system limits.
disp_inactivity_timeout	Specifies the maximum time (in seconds) allowed between dispatch client requests, before the API Agent disconnects the dispatch client. See also notes below this table. Lowering this value will increase the chances that the API Agent will erroneously consider the dispatch client to be inactive (for instance because of processing and network delays). Therefore the value for this timeout would normally be at least ten seconds (in order to allow for processing and network delays) and often the value would correspond to a duration of several minutes. It is also the case that, if set less than or equal to the client's SOAP timeout, then this can cause the API Agent to think the system has crashed and hence it restarts itself. Set disp_inactivity_timeout > client SOAP timeout. If you have a firewall (or similar) between your dispatch clients and the API Agent that closes network connections after a period of inactivity, then the 'disp_inactivity_timeout' parameter can be used to prevent this. In this case, you need to ensure that the value of the 'disp_inactivity_timeout' parameter is less than the firewall timeout period.
disp_request_timeout	Specifies the maximum time that the API Agent will wait for dispatched jobs (per dispatch client) before returning with return code SP_OK_DISPATCH_REQUEST_TIMEOUT. See also notes below this table. Lowering this value will increase the network traffic and also the processing load on the dispatch client and API Agent. Therefore the value for this timeout would normally be at least ten seconds and often the value would correspond to a duration of several minutes. If you want to the API Agent to detect dispatch clients that are not reachable (for instance because of network problems or because the dispatch client has crashed), then set both the 'disp_inactivity_timeout' and 'disp_request_timeout' parameters' to non-NULL values. In this case the values of these two parameters must both be less than the time in which you want to detect unreachable dispatch clients.

Managing the Jeopardy Reports

Parameter	Description
jeopa_nwt	Specifies how many Jeopardy Agent Worker Threads should be used. You will need help from a consultant to set this up. It is critical to the running of the system and incorrect settings can result in performance degradation, system instability or hitting operating system limits.

Logfiles

The API Agent l;ogfiles are very important for use when diagnosing faults and for helping to answer questions about why the system has behaved as it has. As such, it is wise to set these up such that they can hold a complete day's worth of tracing within a single file. 14.1 Application Logfiles gives more details.