9 Configuring Base Exit and User Exit Types

This chapter describes how to define an Oracle Communications ASAP user-defined exit types (UDETs) and map them to ASAP base exit types.

About User Errors and Thresholds

Network element errors can be associated with exit types. An exit type reflects the status of an atomic action at any point during the processing of that atomic action. Atomic action exit types that are associated with atomic action completion and failure scenarios are termed base exit types. The Service Activation Request Manager (SARM) database contains several tables that reference base exit types (in other words, contain a base_types column). You can define custom user-defined exit types (also known as user errors) that you can then map to ASAP events. User-defined errors are stored in the Service Request Manager (SARM) tbl_user_err table.

After you have defined user errors, you can define user error thresholds to elicit user-defined responses or events should the failure threshold for an atomic action command be exceeded. For example, if a host network element (NE) returns a given error notification from a specific atomic action command a given number of times (the defined threshold), the appropriate user-defined event is issued. User defined error thresholds are stored in tbl_err_threshold.

About Base Exit Types

In provisioning, when a user exit type is returned from a State Table or JNEP Java code, the corresponding base type is found. For State Tables, the Network Element Processor finds the base type. For the JNEP Java code, JNEP finds the base type and sends this base type to the NEP.

There are seven base types defined in SARM database tbl_user_err. If you try to define more base types in tbl_user_err, at startup and load time, the NEP server detects it as an error and terminates the server.

These base exit types include the following:

SUCCEED – The atomic action executed successfully. The NEP successfully completes the atomic action command and the SARM provisions the next atomic action on the work order. The completed atomic action command and its associated parameters are saved by the SARM to facilitate rollback, if necessary.

FAIL – Hard error; the atomic action failed, which results in the failure of the work order. The NEP State Table or the JInterpreter method sends this response if the provisioning activity has failed and work order provisioning must stop. The SARM then fails the entire work order and notifies the SRP of the work order failure event. If rollback is configured on the work order, the SARM rolls back any previously completed atomic actions.

Note:

FAIL is predefined in the Java code like other base types. You may define other user exit types based on it.

To use this exit type from Java code, the Java method should call the setASDLExitType method. Oracle recommends adding error text to the failure to clarify diagnostic messages. For example:

setASDLExitType("FAIL", "User error text for FAIL");

RETRY – The atomic action will be retried later. The NEP State Table or the JInterpreter method sends this response when it is determined that the atomic action must be retried. While the atomic action is waiting to be retried, the connection to the NE can be used to provision other atomic actions destined to that NE. This is in contrast to the Maintenance Mode condition in which no other atomic actions are transmitted to the NE. If the atomic action command does not complete after the final retry, the SARM fails it. The atomic action command and associated parameters are logged only once by the SARM after the final try. When the retry threshold is reached, a system event indicates that the atomic action command (and consequently the work order) has failed. Using the Control subsystem, you can map this system event to generate the appropriate alarm.

The number and frequency of retry attempts is governed by work order properties, and in the event that these properties are not defined on the work order, by ASAP.cfg configuration parameters.

For more information about RETRY behavior, see "Behaviors of RETRY and RETRY_DIS".
RETRY_DIS – This is a base type which is similar to RETRY. This base type means the atomic action did not complete and needs to be retried. You can base new user exit types on RETRY_DIS. (DIS refers to disconnect rather than disable).

When RETRY_DIS is returned from a State Table or Java provisioning class, the related port is disconnected. The atomic action will fail but will be retried by NEP server. The NEP server will indicate this to the SARM server. Just before the NEP server retries the atomic action, it has to establish a new connection because it was disconnected. The NEP will establish a connection again and will retry the same atomic action. This will continue as long as RETRY_DIS is returned from the State Table or Java provisioning class.

If the parameter IO_ASDL_RETRY (which has a default value of 0) is defined as 1 in the ASAP.cfg file, the atomic action with RETRY_DIS exit code will be only retried as many times as is indicated by NUM_TIMES_RETRY. In this case, RETRY_DIS functions similar to RETRY with the difference of the additional disconnect and reconnect after each atomic action retry.

The NUM_TIMES_RETRY parameter represents the number of times the SARM sends an atomic action to the NEP to be processed after the NEP returns it with a 'Fail but Retry' status. A work order is failed when the number of retries equals the value specified for NUM_TIMES_RETRY. The RETRY_DIS base exit type can occur if a device is found to be in an abnormal state and must be manually reset.

For more information about RETRY_DIS behavior, see "Behaviors of RETRY and RETRY_DIS".
MAINTENANCE – The atomic action command failed because the NE is currently unavailable to receive provisioning requests. The State Table or the JInterpreter method sends this atomic action response after being notified that the NE is currently unable to accept provisioning updates. The NEP automatically logs off and disconnects from the NE. On receiving this atomic action response, the SARM moves the atomic action from the In Progress atomic action queue to the Pending queue, and then marks the status of the NE as Maintenance. The SARM waits for the NEP to transmit an NE Available notification after it has successfully re-established its primary connection to the NE. The atomic action command and its associated parameters are not logged by the SARM because the atomic action itself did not actually fail.
SOFT_FAIL – The atomic action has encountered an error has occurred that is not serious enough to halt the successful provisioning of the order. For example, this event can occur when the State Table or JInterpreter method logic detects that a user is attempting to add a feature to a line that already has that option. The SARM receives the relevant atomic action response and manages it in the same manner as an atomic action completion, with one exception. The SARM sets the Exceptions flag on the work order Completion notification returned to the SRP to indicate that some of the provisioning activity that was requested by the originating system was not performed. The failed atomic action command and its associated parameters are saved by the SARM.
DELAYED_FAIL – The atomic action had failed during provisioning. The SARM skips any subsequent atomic action in the service action, continues provisioning at the next service action, and then fails the order. The failed atomic action command and its associated parameters are saved by the SARM. Rollback and delayed failure are incompatible because the intent of this base type is to continue provisioning subsequent Service Actions, while rollback would reverse successfully provisioned Service Actions. It it therefore recommended that you set the service action rollback parameter to N and the ignore_rollback parameter to Y. Delayed failure should only be used when there are no dependencies on subsequent Service Actions. If dependencies exist, the subsequent provisioning actions will fail.
STOP – The atomic action has stopped processing. The NEP State Table or the JInterpreter method sends this response when it detects that the work order has been set in a stopped state. While the work order is in a stopped state, the Work Order Manager in the SARM only accepts requests to resume or cancel this work order. You can submit such requests through an Order Control Application (OCA) or Service Request Processor (SRP) API call by resubmitting the stopped work order.

Behaviors of RETRY and RETRY_DIS

When IO_ASDL_RETRY is a set to 0 (the default value)

The atomic action will fail but will be retried again (same behavior for both RETRY and RETRY_DIS)
The related port used will be kept intact for RETRY but disconnected for RETRY_DIS
The port will be connected again (only for RETRY_DIS).

For RETRY, retry happens according to the NUM_TIMES_RETRY and RETRY_TIME_INTERVAL parameters, but not for RETRY_DIS.

For RETRY_DIS, steps a), b) and c) will be repeated as long as the State Table or Java provisioning class for that atomic action returns with RETRY_DIS.

When IO_ASDL_RETRY is set to 1

Atomic action will fail but will be retried again (same behavior for RETRY and RETRY_DIS)
The related port used will be kept intact for RETRY but disconnected for RETRY_DIS.
The port will be connected again (only for RETRY_DIS).

For both RETRY and RETRY_DIS, retry happens according to the NUM_TIMES_RETRY and RETRY_TIME_INTERVAL parameters

Steps a), b) and c) will be repeated NUM _TIMES_RETRY times only.

How to use RETRY_DIS:

State tables

RETRY_DIS is usable for the State Table action function ASDL_EXIT. For example:

2000 ASDL_EXIT 'RETRY_DIS:Retry and disconnect - %error'

JNEP

RETRY_DIS is predefined in the Java code like other base types. You may define other user exit types based on it.

To use this exit type from Java code, the Java method should call the setASDLExitType method. For example:

setASDLExitType("RETRY_DIS", "User error text for RETRY_DIS");

About User Exit Types

User exit types allow cartridge developers and systems administrators to map atomic action exit codes to one of the predefined base exit types. Base exit types determine the product behavior. Cartridges map return codes and status values from an NE to a user-defined exit type.

Regular expressions (regex) are used to perform pattern searches on responses from NEs. The pattern used is stored in tbl_user_err in the SARM database. The user exit type contains a regex pattern that is applied at runtime.

Regular expressions enable users to associate a series of responses to a specific base type. For example, a regular expression 6 can identify a pattern where any response with the character 6 followed by any number of characters will translate to base type of FAIL. Regular expressions can also allow very specific searches within a response from an NE.

Regular expressions are typically compiled before being executed. Compilation produces a binary version of the expression and ensures that the syntax of the regular expression is correct. This compilation occurs using SACT and SADT when user exit types are deployed into ASAP as part of a cartridge. If the syntax is incorrect during compilation, SADT displays an error message and the deployment of the user exit type fails.

The supported regular expression version is consistent with Java 1.4.x regular expressions.

Using Regular Expression Search Patterns

The following provides additional regular expression search examples:

^.*\b(one|two|three)\b.*$ = matches a complete line of text that contains one, two or three
^(?=.*?\bone\b)(?=.*?\btwo\b)(?=.*?\bthree\b).*$ matches a complete line of text that contains all of the words one, two and three
"[^"\r\n]*" matches a single-line string that does not allow the quote character to appear inside the string.
\b\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}\b matches any IP address.

For more information on search patterns, refer to

http://download.oracle.com/javase/1.4.2/docs/api/java/util/regex/Pattern.html

Using Search Patterns Against Long Switch Responses

There is a known issue with the Java.util.regex package from Java. Any match pattern with alteration on a string that is greater than 1400 bytes causes an exception and a stack overflow. This situation is not uncommon, particularly when implementing services and you want to match the appearance of a word in a switch response. The following describes how to work around this issue.

In the following example, a command is sent to an NE and a multiline reply is received in which you want to match a keyword:

You may attempt to match the word COMPLETED in the reply as follows:

if (Pattern.matches("(.|\r|\n)*COMPLETED(.|\r|\n)*", replyString) ){

System.out.println("Matches \”COMPLETED\”");

} else {

System.out.println("No Match");

The problem will be encountered if the length of the replyString length exceeds 1400 bytes.

In the above sample, the “.” signifies any character except a line terminator, that is, any of the following set of characters:

\n (line feed, the UNIX line terminator)
\r (carriage return)
\u0085 (next line)
\u2028 (line separator)
\u2029 (paragraph separator)
the sequence \r\n

Typically, to match . and \r and \n (or any combination of these), you would use (.|\r\n)* and this causes the problem.

However, Java Regexp enables you to match any characters including line terminator by means of an embedded flag expression. ((s).)* enables the flag to let "." match any character as well as line terminator. The problem is avoided by changing the search pattern to "((?s).)*COMPLD((?s).)*".

About User Exit Types for Unknown Errors

You must identify as many error codes or error messages from the NE as possible, and create user exit types for these errors. However; it is often difficult or impossible to map every possible error message. For these unknown error messages, create a catch-all user exit type, such as NO_MATCH_FOUND with a base exit type of FAIL.

The API call setTypeByMatch returns the error label (user-defined exit type field, as defined in Design Studio) for each match, but in case that no match is found (there is no modeled entry for this response pattern) it returns NULL. The code should associate all unknown errors with this type. setTypeByMatch can be overridden to handle this case. For example:

……………………………
logger.logDebug("NE REPLY: " + reply);
String exitValue = exitType.setTypeByMatch(reply);
logger.logDebug("Match returned for pattern <<" + reply + ">> is: "+ exitValue);
//If no match can be found among the defined exit types
if (exitValue == null) {
               exitValue = "NO_MATCH_FOUND";
               exitType.setTypeByMatch(exitValue);
}…………………..

About User Exit Types for Success Cases

Always identify the success case. This success case is the response pattern that means that the request successfully completed on the NE. Add it to the user-defined exit type mapping entries. This avoids failing the atomic action if no mapping is found for this case.

Mapping User Exit Types to Base Exit Types Based on Context

In some cases may require different atomic action exit types based on the context (like service) when the same response is received from the NE. For example, the same atomic action may be linked with various service actions (services) and should have a different exit status based on the service it is part of. The error code received is the same, but the outcome (fail, retry, warning) depends in this case on the incoming service action. For example, it is possible that the business requirements allow certain actions to be performed when creating an account but bar them when modifying the same account. In any of such cases, UDET granularity can be defined at service action or atomic action level. The UDET editor allows specifying the service action or atomic action for which the defined pattern and exit type will apply.

Creating New User Exit Types

Use the User Exit Type Wizard to create a user-defined exit type.

To create a new user-defined exit type:

Select Studio, then select Show Design Perspective.
Select Studio, select New, select Activation, then select User Defined Exit Type.
Select the project for this element and enter a name for the entity.
(Optional) Select a location for the entity.

By default, Design Studio saves the entity to your default workspace location. You can enter a folder name in the Folder field or select a location different from the system-provided default. To select a different location:
1. Click the Folder field Browse button.
2. Navigate to the directory in which to save the entity.
3. Click OK.
Click Finish to create the user-defined exit type.

Configuring User Exit Types

You can configure user-defined exit types using the User Defined Exit Type editor.

To configure a user exit type:

In the Cartridge view, double-click a User-Defined Exit Type entity to open the User Defined Exit Type editor.
In the User Defined Exit Types area, click Add.

This enables the fields in the User Defined Exit Types Detail area of the editor and populates those fields with default values.
In the Pattern field, enter a value.

For example, enter SUCCESS, DENIED, RESOURCE BUSY, and so on.
Select the corresponding base exit type.
Enter the User Defined Exit Type for this pattern.

For example, you might enter AA1_SUCCESS.
Select File, then Save.

Note:

Use the Service Action and Atomic Action fields when creating Service Cartridges.

Examples: User Exit Types

Consider the following user exit type examples:

Example: Unstable Network Element Connections
Example: Configuration of Context Sensitive Exit Types
Example: Exit Type Rationalization

Example: Unstable Network Element Connections

Problem: On an Ericsson network element during activation (after a successful connection and login to the network element) the login to the network element is randomly terminated. As an atomic action may be in progress against the network element at the time the connection was dropped it must be placed back in the queue for later activation and the connection must be re-established.

Solution: Configure a user exit type with the RETRY_DIS base type that triggers when the login prompt is detected during normal activation. This allows for the atomic action to retry at a later time after instructing ASAP to disable the current connection. If there is only one connection to the network element then ASAP eventually re-enables the connection and re-login.

Example: Configuration of Context Sensitive Exit Types

Problem: The customer has a network in which each HLR (referred to as a primary HLR) has a backup HLR (referred to as a secondary HLR). Services must be activated on both HLRs but if activations fail on primary HLRs the work order must be failed; if activations fail on secondary HLRs they must be soft failed.

Solution: Create different atomic actions that map to the same implementation. Configure two user-defined exit types that include the atomic action names in the configuration. Configure the base type for the primary atomic action with FAIL. Configure the base type for the secondary atomic action with SOFT_FAIL. The service model for this configuration is shown in the following diagram:

The user-defined exit type configuration is shown as follows:

In this example, whenever the response from the network element contains the strings SUB and EXISTS and the atomic action is A_HLR_ADD_SUB-PRIMARY, then a failure is triggered. Whenever the response from the network element contains the strings SUB and EXISTS and the atomic action is A_HLR_ADD_SUB-SECONDARY then a soft failure is triggered.

Example: Exit Type Rationalization

Problem: There are too many exit type entries with similar attributes present in the configuration, resulting in potentially high maintenance costs.

Solution: Where possible, collapse multiple exit type rows. For example, collapsing rows that have identical attributes other than the software load may be possible when the network element responses remain the same across software loads. A prime example of when exit type rationalization should occur is when multiple delivered cartridges are employed in the solution for the same network element. Because the user exit types in delivered cartridges always contain the vendor, technology, and software load attributes to ensure uniqueness, exit type rationalization is generally possible.