The Product Service Request (PSR) module integrates telephone number administration, product catalog, and customer management with an ordering engine. It captures and stores information required to reference and provision a service request. Other modules in Oracle Communications MetaSolv Solution rely upon the information in the PSR module to enable fulfillment of an order for a product or service for a specific customer. The service request itself initiates several other processes, such as service design and provisioning, telephone number assignment, directory services, LIDB/CNAM, and E911. The PSR module is an ordering engine that enables you to order and provision telephone and non-telephone products including dial tone services, centrex, ISDN-BRI, ISDN-PRI, private line circuits, ATM/frame services, travel cards, customer premise equipment, etc. Any product you define in the product catalog can be ordered through the PSR module.
The PSR Order Entry API provides access to necessary data and business rules underlying the order management functionality in the PSR module, which allows orders to be provisioned. The PSR Order Entry API enables users to enter order information in other systems, bypassing the data entry and data management functionality of the PSR module. The other system is responsible for order entry and validation of information that allows products to be provisioned. The other system is also responsible for the initiation of the mediation layer and/or API. The API inserts into the MetaSolv Solution database the customer account, service location and product service request information necessary for any telecom products or services that are provisioned. The functionality of the other MetaSolv Solution modules remains intact and references the service request information in the same way as is done for a service request that is entered through the PSR GUI.
The PSR Order Entry API provides IDL for PSR ordering, enabling, retrieval, creation, updating, and deletion of PSR orders. The structure of the PSR API architecture is based on the following assumptions:
Your application is responsible for following MetaSolv Solution business rules. These business rules include:
All static values are defined in the IDL files as ENUM types. MetaSolv Solution does not provide valid values for user-defined values.
Any customer can be exported from the database. The status is not checked when exporting customers.
Customers can be exported based on the customer ID.
If an error is encountered at any point, the individual operation fails but the process can continue.
Import of an updated customer can be performed only on a customer that currently exists in the database.
The third-party application is responsible for managing all database transactions, including commit and rollback processing.
Figure 10-1 shows the relationship of the interfaces in the PSR Order Entry API.
Table 10-1 lists the operations in the WDIManager interface of the WDIPSR.IDL file and their accompanying description or notification operations.
Table 10-1 PSR Order Entry API WDIManager Interface Operations
Operation | Description |
---|---|
startPSRSession |
Obtains the object reference of the PSRSession |
destroyPSRSession |
Terminates the PSRSession |
startPSRSession2 |
Obtains the object reference of the PSRSession2 |
destroyPSRSession2 |
Terminates the PSRSession2 |
startPSRProductCatalogSession |
Obtains the object reference of the PSRProductCatalogSession |
destroyPSRProductCatalogSession |
Terminates the PSRProductCatalogSession |
startPSRProvisioningSession |
Obtains the object reference of the PSRProvisioningSession |
destroyPSRProvisioningSession |
Terminates the PSRProvisioningSession |
startInfrastructureSession |
Obtains the object reference of the InfrastructureSession |
destroyInfrastructureSession |
Terminates the InfrastructureSession |
startTransaction |
commit rollback |
destroyTransaction |
Terminates the Transaction |
startSignal |
eventOccurred eventTerminated eventInProgress eventCompleted eventErrored |
destroySignal |
Terminates the Signal |
startInSignal |
eventInProgress eventCompleted eventErrored |
destroyInSignal |
Terminates the Insignal |
Table 10-2 lists the operations in the PSRSession of the WDIPSR.IDL file and their accompanying notification operations.
Table 10-2 PSRSession Interface Operations
Operation | WDINotification |
---|---|
assignCFA_v2 |
assignCFASucceeded_v2 assignCFAFailed_v2 |
exportAccountProvisioningData_v2 |
accountProvisioningDataExportSucceeded_v2 accountProvisioningDataExportFailed |
exportAccountServerDataPSR_v2 |
accountServerDataPSRExportSucceeded_v2 accountServerDataPSRExportFailed |
exportAllServiceLocations_v2 - Deprecated. Use the corresponding Infrastructure API operation instead. |
PSRExportFailed |
exportCFAInfo_v2 |
exportCFAInfoSucceeded_v2 exportCFAInfoFailed_v2 |
exportCLLILocation_v2 - Deprecated. Use the corresponding Infrastructure API operation instead. |
exportCLLILocationSucceeded_v2 exportCLLILocationFailed |
exportCPNIConsents_v2 |
PSRexportCPNIConsentsSucceeded_v2 PSRexportCPNIConsentsFailed |
exportCreditCardAuthorizationData_v2 |
creditCardAuthorizationDataExportSucceeded_v2 creditCardAuthorizationDataExportFailed |
exportCustomerAccount_v2 |
PSRCustomerExportSucceeded_v2 PSRExportFailed |
exportCustomerAccount_v3 |
PSRCustomerExportSucceeded_v3 PSRExportFailed |
exportCustomerAccounts_v2 |
PSRCustomerExportSucceeded PSRExportFailed |
exportCustomerAccounts_v3 |
PSRCustomerExportSucceeded PSRExportFailed |
exportCustomerOrders_v2 - Deprecated. |
PSRExportCustomerOrdersSucceeded_v2 |
exportCustomerOrders_v3 |
PSRExportCustomerOrdersSucceeded_v3 |
exportCustServiceLocations_v2 |
PSRExportFailed |
exportDomainNameRegistrationData_v2 |
domainNameRegistrationDataExportSucceeded_v2 domainNameRegistrationDataExportFailed |
exportEMailProvisioningData_v2 |
emailProvisioningDataExportSucceeded_v2 emailProvisioningDataExportFailed |
exportEMailServerDataPSR_v2 |
emailServerDataPSRExportSucceeded_v2 emailServerDataPSRExportFailed_v2 |
exportFTPServerDataPSR_v2 |
FTPServerDataPSRExportSucceeded FTPServerDataPSRExportFailed_v2 |
exportNGNPSR |
exportNGNPSRSucceeded exportNGNPSRNoDataFound exportNGNPSRFailed |
exportNGNServItem |
exportNGNServItemSucceeded exportNGNServItemFailed |
exportOrder_v2 - Deprecated. |
PSRExportOrderSucceeded_v2 |
exportOrder_v3 |
PSRExportOrderSucceeded_v3 |
exportOrderValues_v2 |
PSROrderValuesExportSucceeded_v2 |
exportProvisioningData_v2 |
provisioningDataExportSucceeded_v2 provisioningDataExportFailed |
exportPSR_v2 - Deprecated. |
exportPSRSucceeded_v2 exportPSRFailed |
exportPSR_v3 |
exportPSRSucceeded_v3 exportPSRNoDataFound_v3 exportPSRFailed_v3 |
exportServiceLocations_v2 - Deprecated. Use the corresponding Infrastructure API operation instead. |
PSRSvcLocationExportSucceeded_v2 PSRExportFailed |
exportServItem_v2 - Deprecated. |
PSRServItemSucceeded_v2 PSRExportFailed |
exportServItem_v3 |
PSRServItemSucceeded_v3 PSRExportFailed |
exportWebHostingProvisioningData_v2 |
webHostingProvisioningDataExportSucceeded_v2 webHostingProvisioningDataExportFailed |
exportWebHostingServerDataPSR_v2 |
webHostingServerDataPSRExportSucceeded webHostingServerDataPSRExportFailed_v2 |
getOrderStatus_v2 |
getOrderStatusSucceeded_v2 getOrderStatusFailed_v2 |
importCPNIConsent_v2 |
PSRImportCPNIconsentSucceeded PSRImportCPNIconsentFailed |
importNewCustomerAccount_v2 |
PSRImportSucceeded PSRImportFailed |
ImportNewCustomerAccount_v3 |
PSRImportSucceeded PSRImportFailed |
importNewServiceLocation_v2 - Deprecated. Use the corresponding Infrastructure API operation instead. |
PSRImportSucceeded PSRImportFailed |
importNGNPSR |
importPSROrderSucceeded importPSROrderFailed |
importPSR_v3 |
importPSROrderSucceeded_v3 importPSROrderFailed_v3 |
importPSROrder_v2 - Deprecated. |
importPSROrderSucceeded importPSROrderFailed |
importUpdatedCustomerAccount_v2 |
PSRImportSucceeded PSRImportFailed |
ImportUpdatedCustomerAccount_v3 |
PSRImportSucceeded PSRImportFailed |
importUpdatedServiceLocation_v2 - Deprecated. Use the corresponding Infrastructure API operation instead. |
PSRImportSucceeded PSRImportFailed |
processBillingTelephoneNumber_v2 |
processBillingTelephoneNumberSucceeded_v2 processBillingTelephoneNumberFailed |
searchMsag_v2 |
searchMsagSucceeded_v2 searchMsagFailed |
surveyUpdate_v2 |
surveyUpdateImpactSucceeded_v2 surveyUpdateImpactFailed |
unassignCFA_v2 |
unassignCFASucceeded_v2 unassignCFAFailed_v2 |
updateDomainProvisioning_v2 |
updateDomainProvisioningSucceeded_v2 updateDomainProvisioningFailed |
validateCustomerAccount_v2 |
validateCustomerAccountSucceeded_v2 validateCustomerAccountFailed |
validateCustomerAccount_v3 |
validateCustomerAccountSucceeded_v3 validateCustomerAccountFailed |
verifySvcLoc_v2 - Deprecated. Use the corresponding Infrastructure API operation instead. |
verifySvcLocSucceeded verifySvcLocFailed |
This section describes the operations defined in the WDIPSR.IDL file.
importNGNPSR
Enables import of orders with template-based service items (those with item types of System, Element, Connector, or Equipment) and nontemplate-based service items.
exportNGNPSR
Enables export of orders with template-based and nontemplate-based service items. This export includes header information, such as customer identification information.
exportNGNServItem
Enables export of template-based and nontemplate-based service items. This export includes service items only; no header information is exported. Using this operation, you can export all service items for a customer.
MetaSolv Solution defines several preferences that are specific to the PSR API. These preferences are located in the Preferences window, in the API/PSR Order Entry API Preferences directory.
This system level preference is a check box that can be deselected (N) or selected (Y):
N: The PSR API switch validation is performed for a TN Assignment.
Y: The PSR API switch validation is not performed for a TN Assignment.
This system level preference is a check box that can be deselected (N) or selected (Y):
N: The software does not bypass any PSR API import structure validation.
Y: Selected PSR API validation is not as strict. This functionality currently exists only for values and label validations. When a structure fails validation, it is not processed by the APIs and the incorrect information is not entered into the MetaSolv Solution database. However, the PSR is still saved in the system. The PSR is subject to validation at the time of completion.
Note: You must be using the PSR Order Entry API for this preference to affect MetaSolv's software.
This system level preference is a check box that can be deselected (N) or selected (Y):
N: You must populate the default values and an activity code for delete.
Y: The importNGNPSR and importPSR_v3 methods overwrite the default values before making the API call when the PSROrderItemValue2 structure is populated.
You do not have to populate the value structure with the default value and an activity code for delete. You can populate it with the preferred value and an activity code of New.
Note: You must be using the PSR Order Entry API for this preference to affect MetaSolv's software.
This system level preference is a check box that can be deselected (N) or selected (Y):
N: When an item is copied during the import of a PSR order, the item, as well as all child items, are copied.
Y: When an item is copied during the import of a PSR order, only the item itself is copied.
This system level preference is a check box that can be deselected (N) or selected (Y):
N: You can create a WTN while you are creating a service request.
Y: You can assign the working telephone number (WTN) from the telephone number inventory to a service request, but you cannot create a WTN during service request entry.
Table 10-3 lists the operations in the PSRProductCatalogSession of the WDIPSR.IDL file and their accompanying notification operations.
Table 10-3 PSRProductCatalogSession Interface Operations
Operation | WDIProductCatalogNotification |
---|---|
exportProductCatalog_v2 - Deprecated |
exportProductCatalogSucceeded_v2 exportProductCatalogFailed |
exportProductCatalog_v3 |
exportProductCatalogSucceeded_v3 exportProductCatalogFailed |
exportProductGroups |
PSRExportProductGroupsSucceeded PSRExportProductGroupsFailed |
exportProductCatalogWith Templates |
PSRExportProductCatalogWithTemplatesSucceeded exportProductCatalogFailed |
This section describes the operations defined in the WDIPSR.IDL file.
exportProductCatalogWithTemplates
Enables export of product catalog information for template-based products (those with an item type of System, Element, Connector, or Equipment).
Table 10-4 lists the operations in the PSRProvisioningSession of the WDIPSR.IDL file and their accompanying notification operations.
Table 10-4 PSRProvisioningSession Interface Operations
Operation | WDIProvisioningNotification |
---|---|
executeFinishOrder |
executeFinishOrderSucceeded executeFinishOrderFailed |
executeCLSCktIDAssignment |
executeCKTIDAssignmentSucceeded executeCKTIDAssignmentFailed |
exportCktItems |
exportCktItemsSucceeded exportCktItemsFailed |
exportLSOClli |
exportCktLSOClliSucceeded exportCktLSOClliFailed |
The section that follows contains a sample process flow for unsolicited messages. Use the sample flow as a template when you develop your own process flows.
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.
The overall process flow for importing a customer is as follows:
The third-party application binds to the MetaSolv Solution Application Server to get a WDIRoot object reference.
The third-party application invokes the startPSRSession operation of the WDIManager interface to get a PSRSession 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 startTransaction operation of the WDIRoot interface to get a WDITransaction object reference.
The third-party application instantiates a WDINotification object.
The third-party application invokes the importNewCustomer operation on the PSRSession interface, providing WDITransaction, WDINotification, and PSRCustomerAccount objects.
The MetaSolv Solution Application Server processes the invoked PSRSession operation and invokes the appropriate callback operation on the input WDINotification. In this example, the operations are PSRCustomerExportSucceeded or PSRExportFailed for exporting, and PSRImportSucceeded or PSRImportFailed for imports.
If the PSRImportSucceeded operation is invoked, the third-party application invokes the commit operation of the WDITransaction interface. If the PSRExportFailed operation is invoked, a WDIError sequence describing the error is returned to the third-party application. The third-party application then performs the appropriate error handling routine. In the case of an import failing, the third-party application should rollback the transaction.
The third-party application invokes the destroyPSRSession operation of the WDIManager interface.
The third-party application invokes the destroyTransaction operation on the WDIManager interface.
The third-party application invokes the disconnect operation of the WDIRoot interface.
When the import of a new object succeeds, the document number is populated with the ID of the new record. For PSRCustomerAccount imports, it is custAcctID. For PSRServiceOrder imports, it is documentNumber. For PSRSvcLocation imports, it is endUserLocationID, endUserLocationType is whatever was provided during the import.
The documentNumber field will never pass back a value other than 0 on any of the failed notification operations. The success notification operations will return a value of 0, except in the following situations:
An existing PSR API operation has passed any unique integer value that would allow the client to uniquely identify the success notification operation. This is usually an API operation method using a specific customer account ID or order (document) number to export/import data.
A new (not versioned _v2 or _v3) operation is added to the PSR API which can correctly implement the field for the client to send the documentNumber to the server.
To indicate that a date should be considered null, send "0" for the day, "0" for the month, and "0" for the year. If you supply a year that is fewer than four digits, 1900 is added to the value to determine the year. If four digits are provided, it is assumed that this is the exact year.
Table 10-5 provides information on how the dates that you specify are interpreted.
The failure of one item in an export of multiple items does not cause the failure of the entire export. Instead, the items that succeed are returned, as well as a sequence of error messages describing the failed operations. When the client requests an operation that can result in multiple items being returned, both the exportSucceeded and exportFailed operations can be called. The exportSucceeded operation is always called, even if all items failed export, in which case the returned sequence is empty. Although the exportFailed operation is generally called first, it cannot be guaranteed in multi-threaded environments.
The export of items such as Telephone Number Inventory Export result in a large amount of data, which can be difficult to manage. Therefore, this operation was broken into a series of exports. Groups of 100 telephone numbers at a time, minus failed retrievals, are sent to the notification object with the PSRTelNbrBatchSucceeded operation. After all such operations have finished, the notification object is sent with the PSRTelNbrExportComplete operation.
The PSR API provides a means to export data based on specific search criteria. You can perform the search using the specifications identified in the SearchableField enumerated type in the WDIPSR.IDL file. Additionally, there are specific operations available to specify the criteria, such as EQUAL, LIKE, and so on. These are defined in the SearchOperation enumerated type.
Finally, the SearchCriteria struct contains one SearchableField reference, one SearchOperation reference, and a string value to search for. Note that all fields that can be searched are not necessarily strings; in the cases of numeric values, a string representation of the value is expected. In the case of enumerated values, a string representation of the numeric value of the enumerated type is expected. It is possible to provide multiple SearchCriteria for an operation, which means that the resulting values must meet all of the specified criteria (an AND operation).
This section provides information on MetaSolv Solution product specification and product catalog.
MetaSolv Solution has the following product levels:
Item Types
Product Specifications
Product Catalog
Think of item types as the MetaSolv Solution rules. These are items and relationships that MetaSolv Solution has predefined for products and services. Examples include line products, which can have attributes such as lines, system options, and features. These attributes allow the MetaSolv Solution code to determine what kind of service a product is and ensure certain data is collected and specific processing occurs. For example, circuits are built (in the background) for dial tone lines so they can be designed later.
Product specifications are engineering rules defined by technical staff in conjunction with product management. These specifications are supported by engineers and network designers for specific implementations. Using the item type examples above (line products, with attributes of lines, system options, and features), a customer could create a product specification for dial tone (POTS) service as a line product with lines that have a system option of Hunt Groups. Each line may have several features such as call waiting, call forwarding, caller identification, three way conferencing, and so on. These specifications are building blocks that have pre-defined relationships designed so that a product catalog can be built using these building blocks. People creating the product catalog need not be worried about the provisioning/designing aspects of a product.
The product catalog is the marketing rules defined by product management. The product catalog addresses three primary marketing issues: 1) Product availability (by location or by business/market segment), 2) Pricing and 3) Packaging. Again, continuing our earlier example, a residential dial tone product, a basic business dial tone product and an enhanced business dial tone product could all be built from the product specification example. Each product may have different pricing, market segments, etc. Multiple product catalogs can be built from one product specification.
An item is the generic name for products and options. Setting up products and options is a two-step process. First, the product specifications and the rules for relationships between product specifications must be defined. The next step is creating the product catalog and designing how the items will be sold. The product catalogs must follow the rules set up in the first step. When setting up product catalogs, the marketing item is the level one item. Usually products are the level one items in the product catalog. The highest level in the hierarchy of items is defined as a level one item.
Figure 10-2 describes the basic process flow for setting up product specifications.
Note:
All references to standard item in this flow refer to product specifications. References to item types refer to MetaSolv Solution-defined item types.Figure 10-1 shows the standard item setup data model.
Figure 10-3 Standard Item Setup Data Model
Note:
All entities with standard_item in the name hold the product specification information. Entities with item_type in the name store MetaSolv Solution-defined items.The item type and item relationship type entities are preloaded with MetaSolv Solution. These two entities define the common characteristics that are handled in the application. An item type and its characteristics are pre-defined. Characteristics might include an item category (such as product, option, line, trunk, etc.), whether the item type must have a premise, and the item type's processing path. (The processing path defines the processing that must take place for an item type.)
Table 10-6 describes the item types's processing path.
Table 10-6 Item Type Processing Path
Processing Path | Acronym | Description |
---|---|---|
Local Telephone Line Service |
LTLS |
The item will have a premise and will have lines. |
Local Telephone Trunk Service |
LTTS |
The item will have a premise and trunks. |
Non-Premise Service |
NPS |
Indicates the item will not have a service location and the billing address will be used for the service location. |
Non Switched Services |
NSS |
Product catalogs that fall in this path will require circuit assignments and two locations. |
For instance, a type of item might be ”line product,” which would be characterized as a product. Another type might be ”line”, which would be characterized as a physical item (meaning a circuit will be created for design purposes) with a premise. The relationship between these two item types would be defined in the item type relationship table with line product being the superior item and line being the subordinate item.
When users define the product specifications, they delineate the actual items that can be sold. For instance, a product specification of basic business line might be set up with a type of line product. Some rules of use are defined here. For example, if you want a disconnect reason to be entered when this item is disconnected, you could set that here. Line types are another product specification that can be set up with a basic business line. The rules that can be defined for this item include the disconnect reason must be entered, and when the item is ordered the question ”how many do you want?” must be asked.
Table 10-7 lists the characteristics that you must define if you use the Arbor/BP billing system or flow through provisioning with PSR.
Table | Column | Description |
---|---|---|
standard Item |
Arbor EMF Ind (called Service Instance on the window) |
Indicates that the item translates to a service instance in the billing system. These columns may be used for any billing interface, not just the Kenan Arbor billing system. |
standard Item |
Arbor Usage Guiding Key (called Guiding Key on the window) |
If the Arbor EMF Ind is set on, a usage guiding key is necessary. These columns may be used for any billing interface, not just the Kenan Arbor billing system. |
standard Item |
Flow Through Provisioning Nm |
The command recognized by the FTP Gateway for a PSR item. If this column has a value, it can be used in the flow-through provisioning process. |
standard Item |
Switch Provisioning Ind |
Indicates that the product specification will be used for switch provisioning. In an installation where the FTP Gateway is used this indicator directs the item to be used in the flow through provisioning process. If the FTP Gateway is not used, this indicator directs the item to be part of a report to be used to perform the switch provisioning. |
standard Item |
Circuit Design Ind |
Indicates that the product specification will be used in the circuit design process. |
Note:
The standard item table is referring to product specificationsNext the standard item relationship must be defined. If basic business is set up as the highest item in the hierarchy (a product), it would be defined in this table with basic business having no superior item. Basic business line would be set up as a subordinate to basic business. Valid values may also be specified during the product specification setup process. If you have an item that requires one or more values to be collected, a name (label) is setup for each value collected and a list or range of valid values defined. A default value may also be defined. An example illustrating this feature might be an item called Start Type. A product specification of Start Type would have a label of ”Type” and a value list of ”ground” or ”loop.”
Figure 10-4 describes the basic process flow for setting up product catalogs (things to sell). All references to specifications in this flow refer to product catalogs. References to items refer to product specifications.
Figure 10-1 shows the item specification data model.
Figure 10-5 Item Specification Data Model
Note:
Entities with specification in the name store the product catalog information.When creating a product catalog for a product, choose the product you want to set up from a list of standard items. The relationship (product specifications) of these items must have no superior items, for example, basic business. Once you have chosen the level one item, the next level of items may be selected from a list of standard items whose relationship has basic business as the superior item. In our example, basic business lines may be selected. This process sets up the product catalog relationship. For level one items there is other information that needs to be collected such as type of service, offering type (wholesale, resell, and retail), taxing information, and tariff information. A product catalog name may be entered. Other information may be specified about any item including information describing the availability of the item (by Network Area), the from and to effective dates, and whether or not it is required or standard. Pricing information may also be entered at this time (see the pricing area of this document for specifics).
Defining a package is the same as defining a product. Currently, MetaSolv Solution allows packages to be set up within a product for example packages of features for a line. MetaSolv Solution does not currently support packages across products (for example, packaging lines and trunk groups together).