9 The PSR Ancillary API
The PSR Ancillary API provides a bi-directional interface for LIDB/CNAM information and E911 data in National Emergency Numbering Association (NENA) format for transfer to the area E911 provider. All fields needed for NENA 2.1 compliancy are provided by this API.
Implementation Concepts
The PSR Ancillary API only supports batch-mode interaction. Two types of operations are provided for this purpose: extract and respond. The extract operation performs a data export and the respond operation performs data import. The only minor variation is the appearance of operations of the form extract{Function}Empty in the WDINotification interface. Such notification callback operations are invoked by PSRAncillaryServer to indicate the absence of candidate extract records for that day.
Essential Terminology
Table 9-1 lists the terms that identify information and concepts that are required to understand the PSR Ancillary API.
Table 9-1 PSR Ancillary API Essential Terminology
| Term | Definition |
|---|---|
|
CNAM |
A telephone service used to display the name and telephone number of the caller. |
|
E911 |
A telephone service used to provide emergency (911) operators with the caller's telephone number and location. |
|
LIDB |
A telephone service used to verify a telephone number for toll service and third-party billing, such as for validation of calling card numbers. |
PSR Ancillary API Interfaces
Figure 9-1 illustrates the relationship of the interfaces in the PSR Ancillary API.
E911Session Interface Operations
Table 9-2 lists the operations available in the E911Session of the PSRANCILLARY.IDL file.
CNAMSession Interface Operations
Table 9-3 lists the operations available in the CNAMSession of the PSRANCILLARY.IDL file.
LIDBSession Interface Operations
Table 9-4 lists the operations available in the LIDBSession of the PSRANCILLARY.IDL file.
Implementation Concepts
All interfaces and operations for the PSR Ancillary API are defined in WDIPSRANCILLARY.IDL. Some interfaces and operations are implemented in the PSR Ancillary API server, PSRAncillaryServer, and the others must be implemented in your application.
The PSR Ancillary API supports only batch-mode interaction. Two types of operations are provided for this purpose: extract and respond. The extract performs a data export and the respond operation performs data import. The only minor variation is the appearance of operations of the form extract{Function}Empty in the WDINotification interface. Such notification callback operations are invoked by PSRAncillaryServer to indicate that there were no candidate extract records for that day.
The PSR Ancillary API and Smart Tasks
The PSRAncillary server E911 functionality does not use the Gateway Event Model. An E911 Smart Task is used to create the row data and determine function codes. The PSRAncillary server is now responsible for extracting the row data with the PSRAncillary extract method and matching the extract data row to the response records returned in the respond method call. The WDISignal interface is no longer used. E911 Gateway Events still show up in the GUI and need to be removed from the provisioning plans by whoever is responsible for modifying provisioning plans.
Note:
Do not use Gateway Events for E911.Field by Field Matching Between Extract Row and Response Record
The telephone number data in the database, which was sent out in the E911ExtRecord, is matched to the data sent back for every calling telephone number (CTN) (911RespRecord.ctn) in the respond method call. Every field sent back in the E911RespRecord must exactly match the row data in the MetaSolv Solution database for any record marked Complete (E911RespRecord.sti = ’C'.) If a match does not occur the E911 response code is changed to error and any mismatched fields are displayed in the GUI.
Since this is a database matching system, the PSRAncillary server considers any data field changes an error, but a succeeded notification is sent back to the gateway vendor so the errors can be seen, corrected, and resent using the MetaSolv Solution GUI. Since the CTN is the key field triggering matching, if any CTN cannot be matched to a record in Sending status for an extractSeq, a failed notification is sent back to the gateway vendor with error messages for all CTN fields not matched to a Sending telephone number in the database.
The gateway vendor is responsible for removing the offending calling telephone numbers and calling another respond method. It is impossible for the PSRAncillary server to determine if the database information is correct without matching a telephone number in Sending status to a valid CTN. It is the gateway vendor's responsibility to contact the appropriate party (either the customer or the third-party provider) to correct any discrepancies between a CTN and the telephone numbers in the MetaSolv Solution database.
Rules of Operation
-
Each extract and respond operation has an extractID parameter. This extractID is generated by the third-party application and is transferred back to your application as a parameter on the succeeded, failed and empty notifications for the extract and respond. The extractID provides the third-party application with a mechanism to match a notification with the corresponding extract or respond request.
-
When an extract operation is invoked by your application, MetaSolv Solution generates and returns a unique sequence number in the notify callback. This sequence number is passed in the extractSeq parameter. When your application sends the response for the extract, the extractSeq in the response structure must be the same as the extractSeq sent in the corresponding extract structure. The extractSeq provides the APIs with a mechanism to match an extract with a response. The third-party application is responsible for managing database transaction processing. This means the third-party application establishes the MetaSolv Solution database connection through the WDITransaction interface of the API and controls commit and rollback processing.
Each extract and respond structure has an extractSeq parameter. The extractSeq is generated by MetaSolv Solution and sent to the third-party application through the extract operation. When the third-party application sends the respond for the extractSeq in the E911 Update respond structure, it must be the same as the extractSeq sent in the corresponding extract.
The extractSeq provides a mechanism to match an extract with a response.
-
There is an extractID parameter for each extract and respond operation. This extractID is generated by the third-party application and is transferred back to your application as a parameter on the successful, failed, and empty notifications for the extract and respond. The extractID provides the third-party application with a mechanism to match a notification with the corresponding extract or respond request.
-
When an extract operation is invoked by your application, MetaSolv Solution generates and returns a unique sequence number in the notify callback. This sequence number is passed in the extractSeq parameter. When your application sends the response for the extract, the extractSeq in the response structure must be the same as the extractSeq sent in the corresponding extract structure. The extractSeq provides the APIs with a mechanism to match an extract with a response.
The PSR Ancillary API defines the interfaces between MetaSolv Solution and a third-party gateway. This API facilitates the sharing of E911, CNAM, and LIDB information between MetaSolv Solution and the appropriate database provider.
The third-party application is responsible for managing database transaction processing. This means the third-party application establishes the MetaSolv Solution database connection through the WDITransaction interface of the API and controls commit and rollback processing.
There is an extractID parameter for each extract and respond operation. This extractID is generated by the third-party application, then transferred back to the third-party application as a parameter on the succeeded, failed, and empty notifications for the extract and respond. The extractID provides the third-party vendor with a mechanism to match a notification with the corresponding extract or respond request.
There is an extractSeq parameter within each extract and respond structure (extractE911, respondE911, extractCNAM, respondCNAM, extractLIDB, and respondLIDB). The extractSeq is generated by MetaSolv Solution and sent to the third-party application through the extract operation. When the third-party application sends the respond for the extractSeq, in the respond structure, it must be the same as the extractSeq sent in the corresponding extract. The extractSeq provides a mechanism to match an extract with a response.
Extract Sequence Matching
The E911Extract.extractSeq sent in the succeeded notification must be returned in the E911Response.extractSeq in the respond method call. The extractSeq field allows database rows in a Sending status to be matched to records in the E911RespRecords array (see Field by Field Matching Between Extract Row and Response Record.) The E911 Update extactSeq field allows multiple respond methods to be processed simultaneously (if the extractSeq are different.) The respond method can be made any time after the extract method is called, and can contain a partial set of records. The response does not have to contain every record extracted previously if those records contain the correct extractSeq. This allows the PSRAncillary server to match records using unordered extract and respond method calls.
Extract method calls and/or respond method calls can be done daily, in any amount, in any order. There are restrictions enforced by the PSRAncillary server as to how the method calls are processed. If an extract method call has not finished processing before another extract method call is received, the second (and subsequent) extract method calls wait until the first has finished processing before being allowed to do further processing. If a respond method call for an extractSeq is not finished processing before another respond method call using the same extractSeq is received, the second (and subsequent) respond method calls with the same extractSeq wait until the first has finished processing before being allowed to do any further processing.
Note:
The previous restriction of a twenty-four hour turn around time using one extract method call followed by one respond method call containing every record extracted is no longer required.Extract and Respond Scenario
Rules for extract and response scenarios are summarized in the following list:
-
Extractseq matching on extract and respond is strictly enforced.
-
Extract and respond does not need a 24-hour turn around.
-
Respond does not have to follow extract (which means multiple extracts can be done before a respond is sent back.
-
Respond does not have to contain all the records extracted for the extractSeq on the extract.
-
Respond cannot contain telephone numbers (matched by CTN) that were not sent in the extract or were previously processed by another respond with the same extractSeq (no unmatched, if a telephone number is sent in the response that cannot be matched to a telephone number in sending status, the respond method fails until the CTN is removed).
-
Extract cannot have telephone numbers differing only by suffix (the CTN would be the same which makes matching the CTN on the respond impossible), the CTNs are errored but the extract still occurs with the offending telephone numbers removed.
-
All fields are strictly matched in the respond, if any field sent in the extract has changed, the record is errored but the respond is still considered a success.
Note:
Previously, customers set the exd field, which is stamped on the extract record. This field should not be modified. The only supported function codes are C or E Matching for STI (status indicator or response code).
Error Logging Changes
PSRAncillary server E911 errors are now logged to the E911.log file. If the error is related to a data issue and can be corrected in the GUI, the error also appears in the PSRAncillary Maintenance window. Errors displaying in the GUI include NENA errors returned in the response, data integrity errors that can be corrected in the GUI, or in the determination of the ordering of extract records. Errors written only to the E911.log file are fatal server errors needing immediate attention. These errors cannot be fixed using the GUI alone.
Any server error appearing in the PSRAncillary Maintenance window also appears in the E911.log file, but not all errors written to the E911.log file appear in the PSRAncillary Maintenance window. Both the E911.log file and the PSRAncillary Maintenance window must be used to monitor errors logged by the server.
The PSRAncillary E911 error logging includes the following:
-
Logging the PSRAncillary server errors to the E911.log file in the path set up in the gateway.ini file. Any previous log files used by the PSRAncillary server (
MetaSolv Solution.log/appserver.log, WDI.log, EventServer.log, and PSR Ancillary.log) no longer contain any E911 related error logging (although CNAM and LIDB information is still logged to these log files.) -
Errors written to both the E911.log file and the MetaSolv Solution database E911 error table (writing to the error table allows the errors to be seen in the PSRAncillary Maintenance window.) Scenarios where this is most likely to occur include but are not limited to:
-
Duplication of telephone numbers differing only by suffix on the extract database table with an extract indicator set to Y.
-
Respond record returning with an E in the sti field, indicating a NENA error. The NENA error returned is written to the E911 error table with a prepended ’NENA Error:' stamp on the error message.
-
Respond record returning with a C in the sti field and the record does not pass field matching criteria. An error is written for each field that does not match up with a prepended MSLV Error: stamp on the error message.
-
Updating an extract database row while the E911 record is in ’Sending' status.
-
-
All E911 error rows are cleared when the gateway provider calls the extract method on the PSRAncillary server. If the PSRAncillary server is not used as part of the E911 solution, the E911 rows are never deleted from the database.
If the System Queue is used to complete the task, errors can be written to the WM_TskSv.log file and to the SERVER_LOG database table. An error written to the SERVER_LOG table is displayed in the GUI. The PSRAncillary server logging occurs independent of System Queue logging. Therefore, errors occurring in the PSRAncillary server are logged by the PSRAncillary server and they can also be logged by the System Queue. As a general rule, if an error occurs on the PSRAncillary server, it is logged normally by the PSRAncillary server and then picked up by the System Queue and logged on the SERVER_LOG table so it can be displayed in the GUI. If the error is not written to the E911.log, then the error most likely occurred due to functional issues on the System Queue, and is logged in the WM_TskSv.log file and possibly the SERVER_LOG table (if the error is of a nature that needs to be displayed by the GUI.)
Process Flow
This section contains a sample process flow for an unsolicited message. Use the sample flow as a template for developing your own process flows.
Unsolicited Messages
When the message is initiated by the third party (unsolicited), MetaSolv Solution plays the role of the server, and the third-party application plays the role of the client. Unsolicited messages are processed asynchronously, meaning a callback mechanism is used to report back the results of an operation invoked by the third-party application.
Table 9-5 lists the interfaces and operations that MetaSolv Solution implements using IDL files provided with the PSR Ancillary API.
Table 9-5 PSR Ancillary API Operations
| Interface | Operations |
|---|---|
|
WDIRoot |
connect disconnect |
|
WDIManager |
startE911Session startCNAMSession startLIDBSession destroyE911Session destroyCNAMSession destroyLIDBSesion startTransaction destroyTransaction startSignal destroySignal |
|
E911Session |
extract respond |
|
CNAMSession |
extract respond |
|
LIDBSession |
extract respond |
Table 9-6 lists the interfaces and operations that your application can implement.
Table 9-6 PSR Ancillary API Notification Operations
| Interface | Operations |
|---|---|
|
WDINotification |
extractE911Succeeded extractE911Failed extractE911Empty respondE911Succeeded respondE911Failed extractCNAMSucceeded extractCNAMFailed extractCNAMEmpty respondCNAMSucceeded respondCNAMFailed extractLIDBSucceeded extractLIDBFailed extractLIDBEmpty respondLIDBSucceeded respondLIDBFailed |
Sample Unsolicited Message Process Flow
-
The third-party application binds to the PSR Ancillary server to get a WDIRoot object reference.
-
The third-party application invokes the connect operation of the WDIRoot interface, which yields a WDIManager object reference.
-
The third-party application invokes the startE911Session, startCNAMSession or startLIDBSession operation of the WDIManager interface to get an E911Session, CNAMSession, or LIDBSession object reference, respectively.
-
The third-party application instantiates a WDINotification object.
-
The third-party application invokes the startTransaction operation of the WDIManager interface, which yields a WDITransaction object reference. This object reference passes as a parameter on subsequent operations and is used by the third-party application upon completion of processing to initiate the commit or rollback operation.
-
The third-party application invokes the appropriate operation on the session object reference returned in step 3 (that is, extract or respond). The WDINotification and WDITransaction object references are passed as parameters.
-
The PSR Ancillary server processes the invoked operation of the session object and invokes the appropriate failed, succeeded, or empty operation of the input WDINotification upon completion. The empty notification is used only for the extract operations.
-
If the failed operation was invoked in step 7, the third-party application initiates the rollback operation of the WDITransaction interface.
-
If the succeeded or empty operations were invoked in step 7, the third-party application initiates the commit operation of the WDITransaction interface.
-
The third-party application invokes the appropriate destroy session operation of the WDIManager interface (destroyE911Session, destroyCNAMSession or destroyLIDBSession).
-
The third-party application invokes the destroyTransaction operation of the WDITransaction interface.
-
The third-party application invokes the disconnect operation of the WDIRoot interface.
Auto Respond Preference
The auto respond functionality is now available to those who want to receive responses from a third-party provider in a format other than the electronic respond method provided by the PSRAncillary server. If a customer receives an error from a third-party provider, in the form of a fax, email, letter, or other method, the PSRAncillary Maintenance window is used to adjust the record and resend it to the gateway vendor. The respond method cannot be used by the gateway vendor to respond to records after the extract method is called, this causes a failed notification to be sent to the gateway vendor. The third-party provider must be informed to send ALL NENA errors directly to the customer.
When this preference is turned on, all records sent to the gateway vendor are immediately marked as Complete as if a successful electronic response was received. The auto respond preference is not a mix and match preference. The preference is either turned on and no electronic responses are received using the respond method call, or the preference is turned off and all records need to receive an electronic response using the E911 Update PSRAncillary server respond method. The server must be restarted after the new lines below are added to the gateway.ini file. This registers the new preference with the PSRAncillary server. Add the following lines to the gateway.ini exactly as they appear below to turn the preference on:
[PSRAncillary] AutoRespond=true
Glossary of Terms and Abbreviations
-
ALI: Automatic Location Identification; automatic display at the PSAP of the caller's telephone number, the address/location of the telephone, and supplementary emergency services information.
-
ALI database: The set of ALI records residing on a computer system.
-
E911: Used to refer to emergency 9-1-1.
-
E911 information: Any data that is captured by MetaSolv Solution and sent to the E911 Service Provider by the gateway vendor. This data is any information in MetaSolv Solution that needs to be formatted into a NENA specific transfer protocol in order to be put into an ALI database.
-
E911 record: Collectively refers to any data passed from MetaSolv Solution through the gateway vendor to the E911 service provider. The data can be in the form of a database row, a JAVA object or a NENA specified transfer format The data representation may be different but the E911 information remains consistent unless a valid modification by a system occurs.
-
E911 Service Provider: System responsible for storing and maintaining E911 records on an ALI database and makes the information available to the PSAPs. The gateway vendor forwards the E911 records to the E911 service provider, any reference to the E911 service provider should be considered a System as defined by the UML specification.
-
E911 Smart Task: The task on a provisioning plan giving the user control of the information that is sent to the E911 service provider.
-
Gateway Vendor: The system using the PSRAncillary server to obtain E911 information. The gateway vendor is responsible for taking the E911 information and formatting it into the appropriate NENA transfer protocol and passing the E911 information to the appropriate E911 service provider. Any reference should be considered an actor to MetaSolv Solution as defined by UML specifications. In this case, the actor is also a system.
-
MetaSolv Solution E911 Administrator: The person responsible for working E911 related issues in MetaSolv Solution. This person has domain knowledge about NENA, emergency 9-1-1 processing, use of MetaSolv Solution to work E911 related issues and tasks. Any reference should be considered an actor to MetaSolv Solution as defined by UML specifications. The MetaSolv Solution E911 administrator can be considered a more specialized role than that of the MetaSolv Solution user.
-
MetaSolv Solution Database: Used to persist information for MetaSolv Solution.
-
MetaSolv Solution User: The person using MetaSolv Solution to do order entry or location/customer maintenance. This person is not expected to know specific E911 related information other than the very basics needed in an order entry capacity.
-
NENA: National Emergency Number Association; organization responsible for standardizing emergency 9-1-1 procedures.
-
PSAP: Public Safety Answering Point; a facility equipped and staffed to receive 9-1-1 calls.
-
PSRAncillary server: The MetaSolv Solution API server handling the E911 processing methods of the WDIPSRAncillary IDL interface. This term is used when referring to the server portion of MetaSolv Solution.