9 Implementing Apps

Apps provide an easy way to extend Oracle Communications Operations Monitor with analytical capabilities that are not present in the user interface. Apps can query information from Operations Monitor, process this information, and store results in an output table.

Structure of an App

A valid Operations Monitor extension app consists of a Python 2.7 module and of an app specification file, that declares the parameters of the app and the schema of the app's result table. The Python module file and the app specification file must be packed into a ZIP archive, containing no other files and no directories. Such a ZIP archive can be uploaded to Operations Monitor as described in "Apps".

Further requirements for the app module and the app specification file apply. The app module must contain a run function with the following signature:

run (facade, params)

Parameters:

facade

An instance of libpalladion.scripting.Facade which provides access to the Apps API.
params

A dict instance which represents the parameters supplied to the app.

This function is called by Operations Monitor when the app is executed from the web interface or via remote procedure calls.

The app specification file must be an XML file which complies with the Operations Monitor app-specification DTD cited below:

<!DOCTYPE script [
<!ELEMENT script (param-spec?,result-schema?)>
<!ATTLIST script xmlns CDATA #FIXED "http://iptego.de/palladion/script-spec">
<!ATTLIST script name CDATA #REQUIRED>
<!ATTLIST script description CDATA #IMPLIED>
<!ATTLIST script result-type (custom|calls) #REQUIRED>
  
<!ELEMENT param-spec (param+)>
  
<!ELEMENT param EMPTY>
<!ATTLIST param name CDATA #REQUIRED>
<!ATTLIST param label CDATA #REQUIRED>
<!ATTLIST param type (string|datetime|numeric) #REQUIRED>
<!ATTLIST param required CDATA #IMPLIED>
<!ATTLIST param default CDATA #IMPLIED>
  
<!ELEMENT result-schema (column+,primary-key?,unique-key*)>
  
<!ELEMENT column EMPTY>
<!ATTLIST column name CDATA #REQUIRED>
<!ATTLIST column type CDATA #REQUIRED>
<!ATTLIST column null (true|false) #IMPLIED>
<!ATTLIST column auto-increment (true|false) #IMPLIED>
<!ATTLIST column default CDATA #IMPLIED>
  
<!ELEMENT primary-key EMPTY>
<!ATTLIST primary-key columns NMTOKENS #REQUIRED>
  
<!ELEMENT unique-key EMPTY>
<!ATTLIST unique-key name CDATA #REQUIRED>
<!ATTLIST unique-key columns NMTOKENS #REQUIRED>
]>

The top-level script element is used to configure some important properties of an app. Its name attribute specifies a name for the app which is displayed in the Available Apps table. The description attribute can contain a longer description for the app. Most importantly, the result-type attribute specifies what kind of result table the app will have. It can be either custom, in which case you must specify the result table in the result-schema element, or calls, in which case the result table is fixed as a calls table.

The param-spec element is a container for parameter specifications declared by the param element. Parameter specifications are used by the web interface to generate the right kind of parameter entry dialog when an app is started. The name attribute of the param element specifies the name of the parameter, that is passed to the app. The label attribute specifies a label that is displayed in the parameter entry dialog. The type attribute specifies how the parameter entry is rendered in the parameter entry dialog. The required attribute decides whether the parameter must be entered or can be left blank. The default attribute specifies a default value, that is filled into the parameter entry.

The result-schema element is used to specify a schema for the result table of the app. This is required when the result-type attribute of the main script element is set to custom. The contents of the result-schema element are translated into an SQL CREATE TABLE statement. You can specify columns in the result table, as well as a primary key and multiple unique keys. The column element specifies a column. The name attribute gives the name of the column. The type attribute specifies the type of the column. It can contain any of the data type specifications valid in MySQL. For more information, see the Create Table Syntax in the MySQL 5.0 Reference Manual:

http://dev.mysql.com/doc/refman/5.0/en/create-table.html

The null attribute decides whether the column is nullable or not. The auto-increment attribute specifies whether the column can be filled via auto increment on insert. The default attribute gives a default value for the column. The primary-key element declares a primary key for the result table. Its columns attribute is a list of columns that make up the primary key. The unique-key element declares a unique key in the result table. Its name attribute gives the name for the unique key. Its columns attribute is a list of columns that make up the unique key.

Apps API

class libpalladion.scripting.Call (facade)

This class represents a call in Operations Monitor. For general information on how Operations Monitor handles calls, see"Calls".

Table 9-1 describes the fields for the Call class.

Table 9-1 Call Class Fields

Field	Type	Description
id	String	Indicates the ID of the call.
nlegs	Integer	Indicates the number of legs in the call consists of.
state_msg	String	Indicates the call state. The available call states are: Unauthorized Proceeding Ringing Established Finished Timed out Error Failed Closed by CleanBye Not found Moved Off-line Busy Cancelled
state_details	String	Indicates an additional description of the call state.
setup_start_ts	String, Integer	Indicates a timestamp specifying when the call was initiated.
setup_time	Integer	Indicates the time in milliseconds taken for the call to reach the Established state. Note: Only available if state_msg equals Established.
call_time	Integer	Indicates the duration of the call in milliseconds for which the call was in the Established state. Note: Only available if state_msg equals Finished.
code	Integer	Indicates the final response code of the INVITE transaction associated with the call.
src_user	String	Indicates the user creating the call. This is usually taken from the From header field of the first call leg.
src_ua	String	Indicates the user agent for the caller.
src_codecs	String	Indicates the comma separated list of codecs proposed in the SDP body by the UAC in the INVITE message. Example: On each re-INVITE from inside the dialog, this field is updated to the last proposed list of codecs. This is useful for detecting T.38 calls.
src_initial_codecs	String	Indicates the comma separated list of codecs proposed in the SDP body by the UAC in the first INVITE message. Note: This field is not updated at re-INVITES.
src_ip	String	Indicates the IP address of the caller.
dst_user	String	Indicates the user to which the call is addressed. This is usually taken from the To header field of the first call leg.
dst_ua	String	Indicates the user agent string for the callee.
dst_codecs	String	Indicates the comma separated list of codecs proposed in the SDP body by the UAS. On each re-INVITE from inside the dialog, this field is updated to the last proposed list of codecs.
dst_initial_codecs	String	Indicates a comma separated list of codecs proposed in the SDP body by the UAS, usually in the first INVITE message. This field is not updated at re-INVITES.
dst_ip	String	Indicates the IP address of the callee if the call was successful.
term_devs	String	Indicates a comma separated list of device IDs for devices that this call has an inbound leg to.
init_devs	String	Indicates a comma separated list of device IDs for devices that this call has an outbound leg from.
ingress_devs	String	Indicates a comma separated list of ingress devices for this call.
egress_devs	String	Indicates a comma separated list of egress devices for this call.
traversing_devs	String	Indicates a comma separated list of traversed devices for this call.
gateway_devs	String	Indicates a comma separated list of gateway devices for this call.
MOSlqe_avg	Float	Indicates the average MOSlqe value for all the relevant streams in the call.
MOSlqe_min	Float	Indicates the minimum MOSlqe value of all the stream chunks associated with the call.
end_ts	Integer	Indicates the timestamp of the message that closes the main leg of the call (usually the first BYE message).
reason_hdr	String	Indicates the content of the Reason field from the BYE, CANCEL, SIP request, or from a failure SIP reply.
pai	String	Indicates the content of the P-Asserted-ID header from the initial INVITE SIP request.
rpid	String	The content of the Remote-Party-ID or P-Preferred-Identity header from the initial INVITE SIP request.
megaco_mg_ip	String	Indicates the IP address of the MEGACO Gateway.
megaco_mgc_ip	String	Indicates the IP address of the MEGACO Gateway Controller.
megaco_termination_id	String	Indicates a MEGACO TerminationID defined for a PSTN line, a channel in a Trunk, or RTP stream. Format is a string. For example, line/1 or rtp/1 for RTP streams.
megaco_cmds	String	Indicates the commands placed by the MEGACO Gateway Controller to the MEGACO Gateway in a transaction. For example, Commands exist to add, modify, and subtract Terminations from the Context.
megaco_txids	String	Indicates a MEGACO Transaction is identified by a Transaction ID.
mgcp_mg_ip	String	Indicates the IP address of the MGCP Gateway.
mgcp_mgc_ip	String	Indicates the IP address of the MGCP Media Gateway Controller.
mgcp_capabilities	String	Defines the capabilities of the endpoints.
mgcp_connection_ids	String	Indicates the connection identifier that is encoded as a hexadecimal string, at most 32 characters in length.
mgcp_call_ids	String	Indicates the hexadecimal strings of maximum of 32 characters that identify uniquely a call.
opc	String	Originating Point Codes (OPC) contains the address of the originator for the ISUP call. This is always taken from the first ISUP leg seen by Operations Monitor.
dpc	String	Destination Point Codes (DPC) contains the address of the destination for the ISUP call. This is always taken from the first ISUP leg seen by Operations Monitor.
q850_code	Integer	Q.850 cause code for the ISUP call.
q850_state_msg	String	Q.850 State for the ISUP call.
q850_state_details	String	Q.850 Details for the ISUP call.
merged_into_call_id	Integer	If the call has been merged into another call, then this is the id of that call.
rtcp_streams	Integer	Indicates the number of RTCP streams belonging to the call.
rtcp_delay_max	Integer	Indicates the maximum round-trip delay time reported by RTCP.
rtcp_delay_avg	Integer	Indicates the average round-trip delay time reported by RTCP.
src_user_pref_tag	Integer	Indicates the number of the caller determined by the configurable number determination mechanism, if available.
dst_user_pref_tag	Integer	Indicates the number of the callee determined by the configurable number determination mechanism, if available.
setup_delay	Integer	Indicates the number of the callee determined by the configurable number determination mechanism, if available.
setup_delay	Integer	This field represents the time elapsed between the initial' INVITE' message and the first valid network response, like '180 Ringing', '183 Session in progress', '480 Temporarily Unavailable', etc. It fulfills Session Request Delay for RFC6076. If the call contains ISUP, Setup Delay is computed on the first SIP leg. This field has a precision of milliseconds. By default, this column is hidden.
setup_delay_type	Integer	Shows the type of Setup Delay computed. Available options are: Successful Session Request Delay Failed Session Request Delay By default, this column is hidden.
diversion	String	Diversion URI of first Diversion header in call.
diversion_type	String	Diversion type of first Diversion header in call. Possible values are: deflection (CD) do-not-disturb (DND) follow-me no-answer (CFNA) time-of-day (CFTOD) unavailable (CFUNV) unconditional (CFUNC) unknown: for unknown and all cases that could not be matched to any of the above user-busy (CFB) out-of-service
transfer	Integer	True, if this call has been transferred using the call transfer capabilities in SIP.
dtmf	Integer	Displays Yes if there is DTMF information available for this call. Unless the user has the correct rights this field will not be available.
media_types	String	Indicates the media types that were negotiated in the call. Multiple media types are separated by a comma (for example: audio, video).
getLegs ()		Query legs that belong to this call. Note that this method works only for calls that are in the permanent history (that is, finished for more than 15-20 seconds). Return type: QueryIterator over Leg instances.
getMessages (filter=[])		Query all SIP messages, that belong to this call. Note that this method works only for calls that are in the permanent history (that is, finished for more than 15-20 seconds). Return type: QueryIterator over Message instances.
getOneWayAudio (filter=[], keys={}, orderBy=[])		Query all voice quality information, that belong to this call. Return type: Integer Values: 0: No audio. 1: There is a media leg with audio only in one direction. 2: All media legs with two way audio.
getRawMessages (filter=[])		Query all raw signaling messages, that belong to this call. Note that this method works only for calls that are in the permanent history (that is, finished for more than 15-20 seconds). Parameters filter - A filter specification to be applied to the queried RawMessage instances. Return type: QueryIterator over RawMessage instances.
getVoiceQuality (filter=[], keys={}, orderBy=[])		Query all voice quality information, that belong to this call. Parameters filter - A filter specification to be applied to the queried VoiceQuality instances. keys - Keys that the queried VoiceQuality instances must match. orderBy - Ordering specification. Return type: QueryIterator over VoiceQuality instances.
getVoiceQualityChunks (filter=[], keys={}, orderBy=[])		Query all voice quality information, that belong to this call. Parameters filter - A filter specification to be applied to the queried Chunk instances. keys - Keys that the queried Chunk instances must match. orderBy - Ordering specification. Return type: QueryIterator over Chunk instances.

class libpalladion.scripting.Leg (facade)

The Leg class represents a leg found by Operations Monitor. A leg is the portion of a call that happens between two given devices. Table 9-2 describes the fields for the Leg class.

Table 9-2 Leg Class Fields

Field	Type	Description
id	Integer	Corresponds to the Call.id attribute of the associated call.
state	Integer	Indicates a numeric representation of the call state.
state_msg	String	Indicates a string describing the call state. Following options are available: Unauthorized Proceeding Finished Timed out Error Failed Closed by CleanBye Not found Moved Off-line Busy Canceled
state_details	String	Indicates an additional description of the call state.
setup_start_ts	Integer	Indicates the timestamp of the first message (in seconds) in this leg.
setup_time	Integer	The time in milliseconds that the leg took to reach the Established state. Note: Only available, if state_msg equals Established.
call_time	Integer	Indicates the time in milliseconds that the leg was in the Established state. Note: Only available, if state_msg equals Finished.
code	Integer	Indicates the final response code in this leg.
src_user	String	Indicates the identifier of the caller.
src_uri	String	Indicates the URI of the caller.
src_ip	String	Indicates the IP address of the caller.
src_mac	String	Indicates the hardware address of the caller.
src_port	Integer	Indicates the port the caller is listening on.
src_ua	String	Indicates the user agent string of the caller.
dst_user	String	Indicates the identifier of the callee.
dst_uri	String	Indicates the URI of the callee.
dst_ip	String	Indicates the IP address of the callee.
dst_mac	String	Indicates the hardware address of the callee.
dst_port	Integer	Indicates the port the callee is listening on.
dst_ua	String	Indicates the user agent string of the callee.
ruri	String	Indicates the request URI.
callid	String	Indicates the value of the Call-ID header.
from_tag	String	Indicates the value of tag parameter of the From header.
to_tag	String	Indicates the value of tag parameter of the To header.
transfer	List of Integer	Indicates the list of integer IDs of the calls that relate to this leg because of a call transfer
getMessages (filter=[])	-	Query all SIP messages, that belong to this leg. Parameters filter - A filter specification to be applied to the queried Message instances. Return type: QueryIterator over Message instances.
getRawMessages (filter=[])	-	Query all raw signaling messages, that belong to this leg. Parameters filter - A filter specification to be applied to the queried Message instances. Return type: QueryIterator over RawMessage instances.

class S6Transaction (facade)

The S6Transaction class represents a S6 transaction.

Table 9-3 describes the fields for the Counter class.

Table 9-3 S6Transaction Class Fields

Field	Type	Description
sessionid	Integer	Indicates an unique identifier for the S6 transaction.
timestamp_msecs	Integer	Indicates a timestamp specifying the time since when the session is running.
imsi	String	Indicates a string used to identify the user of the S6 transaction.
command_code	Integer	The command code of the S6 transaction. For example for the command UPDATE_LOCATION the code would be 316. All the possible codes are defined in 3GPPTS 29.272 at the interface commands for S6a/S6d and S13.
msisdn	CHAR (16)	Identifies the subscription to a mobile network.
result_code	Integer	The numerical value of the Result-Code of the Diameter S6 transaction. For example 2001 for DIAMETER_SUCCESS.
result	TINYINT	The high-level result of the overall Diameter S6 transaction. For example 0 for Successful, 1 for Failed, or 2 for Timed out.
error_diagnostic	Integer	Shows information about possible errors that can appear in S6 transaction configuration.
origin_realms	String	Contains the realm of the originator of the Diameter messages of this transaction.
destination_realms	String	Contains the realm the messages of a Diameter transaction should be routed to.
visited_plmn_id	String	The decoded visited PLMN ID found in the transaction with the 3 digit Mobile Country Code (MCC) and 2 or 3 digit Mobile Network Code (MNC) as defined in TS 123000 at section 12.1.
rat_type	Integer	A numeric code used to identify radio access technology that is serving the UE. Defined in TS 29212 at section 5.3.31.
initiator_devices	SET	Comma-separated list of numerical device IDs of the initiator devices for the transaction, that is, of devices from where the transaction is started.
terminator_devices	SET	Comma-separated list of numerical device IDs of the terminator devices for the transaction, that is, of devices from where the transaction is ended.
traversed_devices	SET	Comma-separated list of numerical device IDs of the terminator devices for the transaction.

class libpalladion.scripting.RegistrationEvent (facade)

This class represents registration events found by Operations Monitor. For a general description of registration events in Operations Monitor, see "Registrations".

Table 9-4 describes the fields for the Registration Event class.

Table 9-4 Registration Event Class Fields

Field	Type	Description
id	Integer	Indicates an unique ID for this registration event.
ts	Integer	Indicates the timestamp of the registration event.
realms	Integer	Indicates the realms bit mask for this registration event.
type	Integer	Indicates the type of the registration event.
type_msg	String	Displays an additional message associated with the type of registration event.
user	String	Indicates the identifier of the user that is associated with this registration event.
ip	String	Indicates the source IP address of this registration event.
dest_ip	String	Indicates the destination IP address of this registration event.
contacts	String	Indicates the content of the contact header of the REGISTER request.
code	Integer	Indicates the response code for this registration event.
dev_id	Integer	Indicates the unique identifier of the device that handled the registration event.
getMessages (filter=[])		Query all SIP messages, that belong to this registration event. Parameters filter - A filter specification to be applied to the queried Message instances. Return type: QueryIterator over Message instances.
getRawMessages (filter=[])	-	Query all raw SIP messages, that belong to this registration event. Parameters filter - A filter specification to be applied to the queried RawMessage instances. Return type: QueryIterator over RawMessage instances.

class libpalladion.scripting.Message(facade)

This class encapsulates a single SIP message. Table 9-5 describes the fields for the Message class.

Table 9-5 Message Class Fields

Field	Type	Description
ts	Integer	The timestamp, when the message was received by Operations Monitor.
request	Boolean	True if the message is a request, False otherwise.
proto	String	Protocol used.
src_ip	String	Source IP address.
src_mac	String	Source MAC address.
dst_ip	String	Destination IP address.
dst_mac	String	Destination MAC address.
method	String	The request method of this message. Only present, if this is a request message.
ruri	String	The request URI of this message. Only present, if this is a request message.
code	Integer	The response code of this message. Only present, if this is a response message.
reason	String	The response reason of this message. Only present, if this is a response message.
headers	List	A list of (fieldname, field body) tuples, representing the headers of this message.
body	String	Indicates the message body.
getBody ()	-	Returns the body of the message. Return type: str.
getHeaders ()	-	Returns a list of (fieldname, field body) tuples for all defined header fields. Field name and field body are both instances of str. Return type: list of tuples.
getHeadersByName (name)	-	Returns a list of header field bodies for header fields where the field name equals the given name. A field body is an instance of str. Parameters name - Name to match header fields against. Return type: list of str.
isRequest ()	-	Returns, whether this message is a request. Return type: bool.

class libpalladion.scripting.RawMessage(facade)

This class encapsulates a raw signaling message. Table 9-6 describes the fields for the Raw Message class.

Table 9-6 Raw Message Class Fields

Field	Type	Description
ts	Integer	The timestamp, when the message was received by Operations Monitor.
h	DICT	A dictionary representing the PCAP header.
frame	String	The raw data.

class libpalladion.scripting.VoiceQuality(facade)

This class represents voice quality measurements for a call found by Operations Monitor, or reported by one of the User Agents from the call. A call can have more Voice Quality instances associated, one for each RTP stream.

It cannot be invoked directly. It is used for the return objects of the method getVoiceQuality for Call objects.

Note:

Following are the requirements for Voice Quality App to support the data from an SBC probe:

The SBC must be running on an Enterprise version, ECZ7.3.0m1p1 and above.
Ensure the platform is 4600/6300.
Ensure that the setting on the SBC, interim-qos-update is enabled. If this setting is not available, upgrade the SBC to the latest version.

For all other platforms and releases, the Voice Quality app does not display the data received from SBC probes.

For more information on how Operations Monitor gathers voice quality data, see "Voice Quality".

Table 9-7 describes the fields for the Voice Quality class.

Table 9-7 Voice Quality Class Fields

Field	Type	Description
start_ts	Integer	The timestamp of the first measured RTP packet.
probe	String	IP address of the probe that received the data.
vlan	String	VLAN of the probe.
direction	String	The direction of the RTP stream that was measured. One of 'src2dst' or 'dst2src'.
dst_ip	String	The destination IP of the call.
dst_port: INTEGER	Integer	The destination port of the call.
src_ip: STRING	String	The source ip of the call.
src_port: INTEGER	Integer	The source port of the call.
start_ts	Integer	The timestamp of the call.
packets_received	Integer	The number of RTP packets received.
packets_lost_rate	Integer	Packet loss rate for the RTP stream.
forward	Boolean	True if forward.
source	String	Source Device Name.
moscqe_avg	Float	MOS average for voice quality.
jitter_total	Float	Sum of the jitter value for each packet, in milliseconds.
jitter_max	Float	Average jitter value for the RTP packets from the call.
latency	Integer	Latency as reported by the client's User Agent, when available.
r_factor	Float	R-factor value for voice quality.
rtcp	OBJECT	If present, this optional object contains the following fields: start_ts: DATETIME The timestamp of the first measured RTP packet. end_ts: DATETIME The timestamp of the last measured RTP packet. jitter_max: FLOAT Maximum jitter value for a single packet, in milliseconds. jitter_avg: FLOAT Average jitter value for the RTP packets from the call. packets_lost: INTEGER Packets lost for the RTP stream. source: STRING Source Device Name.

class libpalladion.scripting.Chunk(facade)

This class represents a single chunk of voice quality data.

It cannot be invoked directly. It is used for the return objects of the method getVoiceQualityChunks for Call objects.

For more information on how Operations Monitor gathers voice quality data, see "Voice Quality".

Table 9-8 describes the fields for the Chunk class.

Table 9-8 Chunk Class Fields

Field	Type	Description
start_ts	Integer	The timestamp of the first measured RTP packet.
end_ts	Integer	The timestamp of the last measured RTP packet.
received	Integer	The number of RTP packets received.
expected	Integer	The number of RTP packets expected.
codec	String	The codec used for this chunk.
pkt_delay_variation_us	Double	Variation on packet delay.
no_moscqe_reason	String	If there is no MOS data, its cause.

class libpalladion.scripting.Device(facade)

This class represents a platform device configured in Operations Monitor. For a general introduction on platform devices in Operations Monitor, see "Platform Devices".

Table 9-9 describes the fields for the Device class.

Table 9-9 Device Class Fields

Field	Type	Description
id	Integer	The unique numeric ID of the device.
type	String	The type of the device. One of 'SBC', 'PROXY','L2LB', 'GW', or 'TRUNK'.
name	String	The user visible name of the device.
description	String	A description for the device.
match_type	String	If the device is of type 'SBC', this value indicates how call matching is performed.
suffix	Integer	Some call matching types require a suffix parameter.
match_script	String	This attribute contains a script that specifies the call matching algorithm.
ipranges	String	The IP address ranges which are occupied by this device.
hw_addrs	String	The hardware addresses of this device.
up_since	Integer	A timestamp specifying the time since when the device is known to be running.
dtg	String	If the device is of type TRUNK and device identification via DTG/OTG URI parameters was configured, this attribute contains the value of the DTG request URI parameter to look for.
otg	String	If the device is of type TRUNK and device identification via DTG/OTG URI parameters was configured, this attribute contains the value of the OTG From URI parameter to look for.
getCreatedCalls (filter=[], keys={}, orderBy=[])	-	Query calls that are created by this device, that is, calls that have an outbound leg from this device and no inbound leg to this device. See Facade.query() for the meaning of the parameters. Parameters filter - A filter specification to be applied to the queried Call instances. keys - Keys that the queried Call instances must match. orderBy - An ordering specification. Return type: QueryIterator over Call instances.
getRegistrationEvents (filter=[], keys={}, orderBy=[])	-	Query registration events that are handled by this device. See Facade.query() for the meaning of the parameters. Parameters filter - A filter specification to be applied to the queried RegistrationEvent instances. keys - Keys that the queried RegistrationEvent instances must match. orderBy - An ordering specification. Return type: QueryIterator over RegistrationEvent instances.
getRelayedCalls (filter=[], keys={}, orderBy=[])	-	Query calls that are relayed by this device, that is calls that have an inbound leg to this device and an outbound leg from this device. See Facade.query() for the meaning of the parameters. Parameters filter - A filter specification to be applied to the queried Call instances. keys - Keys that the queried Call instances must match. orderBy - An ordering specification. Return type: QueryIterator over Call instances.
getTerminatedCalls (filter=[], keys={}, orderBy=[])	-	Query calls that are terminated by this device, that is, calls that have an inbound leg to this device and no outbound leg from this device. See Facade.query() for the meaning of the parameters. Parameters filter - A filter specification to be applied to the queried Call instances. keys - Keys that the queried Call instances must match. orderBy - An ordering specification. Return type: QueryIterator over Call instances.

class libpalladion.scripting.Counter(facade)

A Counter is an object in Operations Monitor that takes periodic measurements of a numeric property of the monitored platform. For a general introduction on counters, see "KPI/Metrics".

Table 9-10 describes the fields for the Counter class.

Table 9-10 Counter Class Fields

Field	Type	Description
id	Integer	A unique identifier for the counter.
name	String	The name of the counter.
maintype	Integer	The main type of the counter.
subtype	Integer	The sub type of the counter.
device	String	The device this counter belongs to. May be None.
p1	String	The first parameter for the counter.
p2	String	The second parameter for the counter.
p3	String	The third parameter for the counter.
sec	Integer	The last second measurement.
m_avg	Float	The last minute average of measurements.
h_avg	Float	The last hour average of measurements.
getHourValues (span, offset=0)	-	Query hour average values from the counter history. The returned query iterator yields a dict instance for each hour in the supplied time span. The yielded dict instances contain the keys avg, min, max and sum, with the obvious meanings. The time span is given by the parameters span and offset, where offset specifies the end point of the time span relative to the current time. Parameters span - The length of the queried time span in seconds. offset - The offset of the queried time span from the current time, specified in seconds. Return type: QueryIterator over dict instances.
getMinuteValues (span, offset=0)	-	Query minute average values from the counter history. The returned query iterator yields a dict instance for each minute in the supplied time span. The yielded dict instances contain the keys avg, min, max, and sum, with the obvious meanings. The time span is given by the parameters span and offset, where offset specifies the end point of the time span relative to the current time. Parameters span - The length of the queried time span in seconds. offset - The offset of the queried time span from the current time, specified in seconds. Return type: QueryIterator over dict instances.

class libpalladion.scripting.Alert(facade)

This class represents alerts raised by Operations Monitor. Table 9-11 describes the fields for the Alert class.

Table 9-11 Alert Class Fields

Field	Type	Description
ts	Integer	The time when this alert was raised.
type	String	The type of the alert raised.
subtype	String	The sub type of the alert raised.
new: BOOLEAN	Boolean	Whether this alert is new or read.
message	String	The message issued when raising the alert.
details	String	Some details about the raised alert.
prio	Integer	The priority of the alert.

class libpalladion.scripting.RegisteredUser(facade)

This class represents a registered user. Table 9-12 describes the fields for the Registered User class.

Table 9-12 Registered User Class Fields

Field	Type	Description
identifier	String	Username of the registered user.

class libpalladion.scripting.QueryIterator(facade,query_handle, cls=None)

Instances of this class can be used to iterate over query result sets. You cannot instantiate a QueryIterator directly, but various query methods in this API return QueryIterator instances.

Instances conform to the Python iterator protocol and can be used in 'for item in iterable:' constructs. You can also use the next() method directly to retrieve one result at a time. QueryIterator instances also provide a close() method, which frees resources tied by the query. Once close() has been called, iteration stops. close() is called automatically when all references to a QueryIterator instance are gone.

Table 9-13 describes the fields for the Query Iterator class.

Table 9-13 Query Iterator Class Fields

Field	Type	Description
close()	-	Free the resources tied up by the query.
next()	-	Return the next item in the query result set. Return type: Depends on the type of query.

Field

Type

Description

close()

Free the resources tied up by the query.

next()

Return the next item in the query result set.

Return type: Depends on the type of query.

Using the Apps API Examples

The following app searches the Operations Monitor database for calls which have a given Call-ID header and have been set up between two given points in time:

from libpalladion.scripting.Model import Call, Leg
  
def run(facade, args):
  
    # Get input parameters
    start_ts = args.get("start_ts")
    end_ts = args.get("end_ts")
    callid = args.get("callid")
  
    callid = callid.strip()
  
    for call in facade.getCalls(
          filter=[Call.setup_start_ts >= start_ts, Call.setup_start_ts <= end_ts]
        ):
        # search for the specific callid in all the call legs
        # the callid of each call leg might be different
        for leg in call.getLegs():
             if leg.callid == callid:
                 facade.addResult(
                    {"id": call.id},
                    on_duplicate_key='ignore'
                 )

This app has to be packaged with an app specification file, which should specify the type of the result table (calls in this case), and the names and types of the parameters callid, start_ts, and end_ts. The following specification file achieves this:

<?xml version="1.0" encoding="utf-8"?>
<script xmlns="http://iptego.de/palladion/script-spec"
   name="Call-Id Search"
   description="This script will find all the calls with a given Call-ID value"
   result-type="calls">
   <param-spec>
     <param name="start_ts" label="Started after" type="datetime" required="yes"/>
     <param name="end_ts" label="Started before" type="datetime" required="yes"/>
     <param name="callid" label="Call-Id" type="string" required="yes"/>
   </param-spec>
</script>

Note, that the parameters specified as datetime are passed as the standard Python datetime type. If the result-type of an app is specified as calls, it has a result table with one integer column, ID. When displaying the results table of such an app in the user interface, a join with the calls table is performed. In the example above, the call to facade.addResult has to be surrounded by try ... except because there can be multiple libpalladion.scripting.Leg objects, with the same ID attribute. This is because a call can have multiple legs. Adding the same ID twice to the calls result table results in a duplicate key error.

In the next example we look at an app that requires a custom result table. We will see how this custom result table can be specified in the app specification file. The app calculates a statistics of which user agents use which codecs how often. Again the source data for the app is restricted to calls that were set up between two given points in time.

from libpalladion.scripting.Model import Call
  
def run(facade, args):
    start_ts = args.get("start_ts")
    end_ts = args.get("end_ts")
  
    stats = {}
    filter = [Call.setup_start_ts > start_ts, Call.setup_start_ts <= end_ts]
    for call in facade.getCalls(filter=filter):
        ua = call.src_ua
        if ua is not None:
            codecs = call.src_codecs
            if (ua, codecs) not in stats:
                stats[(ua, codecs)] = 0
            stats[(ua, codecs)] += 1
  
    for ((ua, codecs), count) in stats.items():
         facade.addResult({'ua': ua, 'codecs': codecs, 'count': count})

The facade.addResult call on the last line makes the assumption that the result table has the columns ua, codecs, and count. So this schema has to be specified in the script specification file.

<?xml version="1.0" encoding="utf-8"?>
<script xmlns="http://iptego.de/palladion/script-spec"
    name="Statistics of which user agent uses which codecs"
    description="This app calculates a statistic of which user agents use which codecs"
    result-type="custom">
    <param-spec>
        <param name="start_ts" label="Start time" type="datetime" required="yes"/>
        <param name="end_ts" label="End time" type="datetime" required="yes"/>
    </param-spec>
    <result-schema>
        <column name="ua" type="VARCHAR(255)" null="false"/>
        <column name="codecs" type="VARCHAR(255)" null="false"/>
        <column name="count" type="INT(11)" null="false" default="1"/>
        <primary-key columns="ua codecs"/>
    </result-schema>
</script>

Caution:

When creating your own applications, or using third-party applications, test your scripts in a test environment to ensure they are safe before uploading them to your production environment. Applications approved by Oracle are safe to use in your environments. However, non-approved applications could cause security and performance issues. Oracle is not responsible for any loss, costs, or damages incurred from using your own applications, or third-party applications.

Remote App Procedure Calls

Remote app procedure calls provide programmatic access to the app functionality of Operations Monitor. It is possible to invoke apps installed on Operations Monitor and get their results via a simple HTTP GET interface. For more information, see "Apps" and "Implementing Apps".

Apps are possibly long running processes. Therefore invoking an app and retrieving the results of an app run have been split into two separate steps.

Invoking an App

Invoking an app is done by an HTTP GET request to the URL /scripts/run/app_name on the Operations Monitor host, where app_name is to be replaced by the identifier of an app. Note, that you can lookup the identifier of an app in the Id column of that app's entry in the Available Apps table. The parameters of the app have to be encoded as URL parameters into the GET request URL. For more information on the Apps table, see "Apps".

If invoking the app succeeds, an app run is created, and the GET request returns the numeric run ID for the app run in the response body. This run ID can later be used to retrieve the results of the app run.

There are two possible failure cases when invoking an app. First, the given app name could be invalid. In this case Operations Monitor responds with an HTTP '404 Not found' error code. Secondly, the parameters given in the request could be invalid when a required parameter is missing or a given parameter cannot be parsed. In this case Operations Monitor responds with an 'HTTP 400 Bad request' error code.

A note regarding parameter encoding is required here: Datetime values have to be encoded in a special way to make Operations Monitor recognize them. Operations Monitor expects datetime values to be in the format YYYY-mm-dd HH:MM:SS, where the 4-digit string YYYY gives the year, mm gives the month, dd gives the day, HH gives the hour, MM gives the minute, and SS gives the second.

Retrieving the Results of an App Run

Retrieving the results of an app run is done by an HTTP GET request to the URL /scripts/get/run_id on the Operations Monitor host, where run_id is a numeric run ID. Run IDs are returned when invoking an app. They can also be looked up in the Id column of the App runs table. For more information, see "Apps".

There are three possible outcomes of this request. First, if the run ID given is invalid an HTTP '404 Not found' error code is returned. Secondly, if the run ID is valid but the app run is not yet finished, an HTTP '202 Accepted' status code is returned. In this case the body of the response contains the string 202 Accepted. The third case is when the run ID is valid and the app run is finished already. In this case an HTTP '200 OK' status code is returned, and the body of the response contains the app run result table in CSV format.