| Oracle® Communications ASAP Cartridge Development Guide Release 7.2 E22486-01 |
|
 Previous |
 Next |
| Oracle® Communications ASAP Cartridge Development Guide Release 7.2 E22486-01 |
|
Previous |
Next |
This chapter describes how to create Java and State Table implementations for network element (NE) connections and atomic action scripts that implement MML commands for Oracle Communications ASAP.
The following sections provide information about the Java action processor:
Parameters are returned individually as a name value pair using the following API calls:
returnCSDLParam
returnRollbackParam
returnInfoParam
returnGlobalParam
Parameters can also be returned in a properties list which can contain multiple name value pairs using the following API calls:
returnCompoundCSDLParam
returnCompoundRollbackParam
returnCompoundInfoParam
returnCompoundGlobalParam
This API is available the Java JProcessor class described in the ASAP Java Online Reference.
For Java methods that perform querying, depending on the value of the atomic action parameter RET_PARM_TYPE responses must be passed back to the SARM as either service action parameters, work order parameters, information parameters or some combination of these as follows:
C - service action parameters
W - work order parameters
I - information parameters
IC - information parameters and service action parameters
IW - information parameters and WO parameters
If a default value is not provided for the RET_PARM_TYPE parameter or if it is left out of the atomic action parameter list then no parameters is returned from the query. The parameter names for service action and work order parameters must not conflict with the parameter names that come in on the work order therefore parameters of type "C" and "W" must be prefixed with the token "OLD_". Information parameters do not require this prefix.
Query responses should be parsed where possible rather than passing raw responses upstream including responses that are organized into columns. In general the format for the labels would be feature tag_column header = value. For example a query for feature information that results in the following response:
NAME PROV ACT NPI C-NUMBER CFU ...CALL FWD Y A I 6742727
Should return the following:
CFU_PROV = Y CFU_ACT = A CFU_NPI = I CFU_C-NUMBER = 6742727
If a column does not have a value then no parameter needs to be defined for that item.
Data extracted from a switch printout (for example, a query) must be passed back to the SARM as NE history for retrieval by clients such as OCA. For TCP/IP telnet the startResponseLog and returnResponse Java methods perform this automatically. For non-TCP/IP telnet protocols such as CORBA, the log method must be explicitly invoked to capture the name value pairs.
If an error occurs on the NE, an error text variable and an error code variable (if an error code is present) must be created and passed to the SARM as service action parameters. The value passed back for the exit text should be a meaningful alphabetic string created from the NE response. These variables are often used in customer defined atomic action spawning logic. The naming convention for the error text label and value is:
technology_action_entity_EXIT_TEXT = generic error
For example,
AUC_ADD_SUBS_EXIT_TEXT = SUBSCRIBER_ALREADY_EXISTS
The naming convention for the error code label and value is:
technology_action_entity_EXIT_CODE = <error code>
For example,
AUC_ADD_SUBS_EXIT_CODE = 00016
For all atomic actions that execute successfully on the NE, the error text and error code passed back to the SARM should be set to the value "SUCCEED" and "–1" respectively. For example:
AUC_ADD_SUBS_EXIT_TEXT = SUCCEED AUC_ADD_SUBS_EXIT_CODE = -1
If it is not possible to determine the context for which the error occurred (for example for some NEs an error code and/or error text is not provided or cannot be interpreted) than the exit text and exit code should be set as appropriately as possible to reflect the error even if they may not be as visually meaningful.
AUC_ADD_SUBS_EXIT_TEXT = UNDEFINED
AUC_ADD_SUBS_EXIT_CODE = exception number
If an error code is not provided by the NE leave it without a value.
The presence of the generic error text will ensure that the cartridge implementation methods are compatible with a common service model. The presence of the technology token in the naming convention prevents collisions from occurring when similar atomic actions are being executed on multiple NEs from a single service action (for example a service action to create a new subscriber may mean that the subscriber needs to be created on the FNR, AUC and HLR).
In common service modeling scenarios the error text code needs to follow the format described above; however, currently the team is using the actual user-defined exit type label (stored in the config file) as the label for the service action parameter. This includes the vendor, technology and software load which means that spawning logic implemented by customers would need to be implemented as follows:
A_DO_SOMETHING ( if ERIC-AUC_3-1_ADD_SUBS_EXIT_TEXT = SUBSCRIBER_ALREADY_EXISTS ||
if NOK-AUC_3-1_ADD_SUBS_EXIT_TEXT = SUBSCRIBER ALREADY EXIST ||
if NT-AUC_7-2_ADD_SUBS_EXIT_TEXT = SUBSCRIBER ALREADY EXIST )
The future guideline will likely be to provide both a vendor specific code and a generic code. There could be hundreds or thousands of codes coming back from a vendor and it may be difficult to map them uniquely across multiple vendors. The generic code is the cartridge interpretation and the vendor code gives the service modeler access to the precise code if desired.
When a hard failure is detected by the cartridge (this means a call will need to be made to return the core exit type), prior to exiting from the cartridge code the following two information parameters must be created:
USER_EXIT_TYPE = <the user defined exit type tag> USER_EXIT_DESC = <the user defined exit type description - human readable description of the error>
The description should be retrieved from tbl_user_err along with the base and core exit types. If the description is not available the actual error message from the switch should be provided.
An enhancement has been opened on the user-defined exit type mechanism to ensure that this is handled automatically by the core in the future. The core will automatically generate these labels, populate them with the user type and description and pass them back to the SARM as information parameters.
When a hard failure is detected on a rollback atomic action (this means a call will need to be made to return the core exit type), prior to exiting from the cartridge code the following two information parameters must be created:
ROLLBACK_USER_EXIT_TYPE = <the user defined exit type tag> ROLLBACK_USER_EXIT_DESC = <the user defined exit type description - human readable description of the error>
If the method is set to soft fail when a certain error is received the error code value should still be set to the generic error (because additional atomic actions may need to be spawned based on the error that has occurred).
The following sections describes return parameter types and usage.
|
Note: Any return parameter cannot exceed 255 characters. If it does, the return parameter value will be empty, and the information will not be returned.To avoid this situation, split large return values into multiple return messages when you implement your Java or State Table code. |
Global parameters provide contextual information that different service actions can use. These global parameters are valid for the entire work order scope. Local parameters have precedence over Global parameters if the local parameters are defined.
Global and local work order parameters can be defined when you create a work order Activation Test Case, or an NE Template using Design Studio for ASAP. For more information, see Oracle Communication Design Studio for ASAP.
Parameters defined in a service action overrides global parameters and there is no limit to the number of parameters you can associate with a service action.
Service action parameters are returned to give context between different atomic actions, and are valid in the service action scope. Returned service action parameters overwrites the previous parameter of the same type. Any subsequent atomic actions associated to the service action use the returned value.
Atomic action parameters are not returned explicitly; however, service action parameters are returned which may be implicitly be re-mapped to subsequent future forward atomic actions.
SRP can only retrieve these parameters. Used usually for upstream information purposes. Error code and diagnostic information can be set in this type of return parameter. These parameters are not used parameter data for subsequent service model interactions at the service action or atomic action level.
Information parameters are returned for the upstream system only for future retrieval. These parameters are not available to any future forward or rollback atomic actions within the current or other service actions.
Rollback parameters may be returned as indexed scalar or compound parameters. However, each separate instance must be returned as a name-value pair with the name corresponding to the correct index. For example, name=BASE[1] = AAA, BASE[2] = BBB. For a compound each element within the structure and its instance number must be explicitly returned.
The following section will outline some of the current best practice guidelines used in the field to address particular use cases implemented in existing cartridges.
The convention is to return service action parameters with the prefix ?OLD_?, which will then be the service action service parameters used for any rollback atomic actions.
There may be uses where it is desired to simply return the service action parameter with the same name as in the forward scenario if this simplifies the service model from having to re-map the service action to atomic action parameter in different context's.
Any parameter whether it is service action or ROLLBACK can be used in a Rollback atomic action; however CDSL parameters are persisted in the service action scope.
Generally error parameters are returned as Information parameters to the SRQ to be retrieved later by an upstream system. This error information can be returned as a series of one or more information parameters, or it can be custom encoded into a single value to be associated with one parameter name. For example, Name = ERRORINFO, Value = ?ERRORCODE | ERRORDESCRIPTION | MODULE?. This custom encoding needs to agree with the upstream system which will decode the single value.
If an error value is required as part of the evaluation expression in the service model for subsequent service logic, then the error value should be passed back to SARM as service action parameters and named appropriately in the parameter name.
Note that there are no specific Error parameters, it depends its uses.
For stream-based protocols supported by core ASAP (for example TCP/IP Telnet) the Java startResponseLog and returnResponse methods should be called whether the virtual screen is being employed by the cartridge or not. This results in switch responses being stored in tbl_srq_log where they can be retrieved by upstream systems or viewed through OCA and hence explicit calls to the Java log method can be avoided.
Response logging can be activated/deactivated by setting the NE_CMD_LOG_ON option (which can be configured on a per NEP basis) in ASAP.cfg.
For stream-based protocols supported by core ASAP (for example TCP/IP Telnet), whenever confidential data must be sent to an NE the data should be prevented from being written into tbl_srq_log. There are two sets of methods that can be used as wrappers around the ?send? method calls to control core ASAP behavior in this manner:
The disableCommandLog and enableCommandLog method calls result in no data being written into tbl_srq_log and should therefore only be employed if absolutely necessary (this impairs the ability to debug).
The maskCommandLog and unMaskCommandLog result in asterisks being written to tbl_srq_log instead of the raw characters and is the preferred approach when secure data is being managed.
RULE: for non-stream based protocols such as CORBA it is not possible to use the core ASAP response logging functionality and therefore explicit calls to the log method (JProcessor class) must be made within the cartridge to capture NE history into tbl_srq_log. Ensure that for such protocols explicit calls are made to the log method to record the API call that is being made as well as the return code and/or return text received back from the NE if they are available. For performance reasons at this time do not place calls to log each parameter used in the API call (because these are available through OCA by querying on the work order and also through the diagnostics). In the case where XML documents are being constructed within the cartridge and transmitted using non-stream based protocols the entire XML document should be recorded using a call to the log method.
Where possible, user-defined exit types will be provided in the cartridge.
In the absence of a user-defined exit type configuration (for example the customer has removed those provided by the cartridge) the cartridge default should be to fail responses that lie outside the normal success detection criteria.
The mapping between a message received from the switch and its corresponding user-defined exit type (user_type) should be kept within a cartridge specific configuration file with the following naming convention:
<vendor>_<technology>_<swld>_UserExitTypes.xml
The mapping between the user-defined exit type and its corresponding base exit type (base_type) is contained in tbl_user_err.
Improvements to the user-defined exit type lookup mechanism in ASAP core are pending.
The following data columns in tbl_user_err must be populated:
NE_VENDOR
TECH_TYPE
SFTWR_LOAD
USER_TYPE
BASE_TYPE
DESCRIPTION
SEARCH_PATTERN
The naming convention of user_type, <vendor>_<technology>_<swld>_<error tag>, is no longer required. user_type is for <error_tag> only.
tbl_user_err currently has a 20 character limit and therefore some truncation of the user_type may be required for it to be successfully loaded into the table. An issue is opened on core to increase the size of this table.
The data contained in tbl_user_err must be loaded into a RAM cache upon startup of the NEP.
When regular expressions (regex) are used to perform pattern searches on responses from NE, the following situations should be considered when defining a search pattern (to avoid exception and stack overflow). If the NE response is greater than 1400 characters, then suggest to use the search pattern as follow:
((?s).)*<search string>((?s).)*
Use the fail exit type when the NE indicates that an order cannot be processed due to incorrect parameter values.
In the case where numerous (for example hundreds) of responses/error codes are described in the NE specification, a subset of the most commonly occurring responses will be supported.
Apply the following guidelines when assigning exit types to error messages:
Hard Fail—used for non-recoverable errors that cause the immediate failure of a work order. For example, when an invalid provisioning parameter has been used.
Soft Fail—may be used when for minor errors that should not stop the provisioning of the order for example assigning a feature that has already been added to the subscriber line.
Retry—used when an activation request fails due to reasons other than data errors. For example, if the NE is temporarily unavailable or too busy to handle the provisioning request.
Fail—used when the NE indicates that an order cannot be processed due to incorrect parameter values
User defined exit types are most often configured without associated atomic action commands (see tbl_user_err), however on occasion when the same Java method is associated with two different atomic action commands it may be necessary to trigger different exit types. This is most often done as project configuration work and is not typically part of the cartridge.
The following is the naming convention for user-defined exit type:
<Severity Level>_<Error Label>
The following is the mapping between severity level and base type
Table 13-1 Severity Level Mapping to Base Type
| Severity Level | Base Type |
|---|---|
|
SUCCEED (S) |
SUCCEED |
|
CRITICAL (C) |
FAIL |
|
WARNING (W) |
SOFT_FAIL |
|
RETRY (R) |
RETRY_DIS |
The following are the common labels used in user-defined exit types:
Table 13-2 Common User-Defined Exit Type Labels
| User Exit Type | Base Type | Search Pattern | Description |
|---|---|---|---|
|
S_SUCCEED |
SUCCEED |
TBD |
Succeed |
|
C_FAIL |
FAIL |
TBD |
Fail |
|
C_INVALID-DATA-TYPE |
FAIL |
TBD |
Data is specified in wrong data type |
|
C_DATA-OUT-OF-RANGE |
FAIL |
TBD |
Data value is out of range |
|
C_INVALID-DATA-LNGTH |
FAIL |
TBD |
The length of the given data exceeds the limit |
|
C_CMD-SYNTAX-ERR |
FAIL |
TBD |
Command syntax error |
|
C_MISSING-PARAM |
FAIL |
TBD |
Missing parameter in command (MML) |
|
C_MISSING-DATA |
FAIL |
TBD |
Expected data is missing |
|
C_SRV-NOT-IMPLMNT |
FAIL |
TBD |
Service is not yet implemented |
|
C_FEAT-NOT-IMPLMNT |
FAIL |
TBD |
Feature is not yet implemented |
|
C_UNKNOWN-ERR |
FAIL |
TBD |
Unknown response from the NE |
|
C_MATCH-NOT-FND |
FAIL |
TBD |
No matching exit type is found |
|
S_DATA-NOT-FND |
SUCCEED |
TBD |
No data/object is found in query. |
|
C_DATA-NOT-FND |
FAIL |
TBD |
No data/object is found in query. |
|
W_DATA-NOT-FND |
SOFT_FAIL |
TBD |
No data/object is found in query. |
|
S_DATA-EXISTS |
SUCCEED |
TBD |
Data/object is already existed. |
|
C_DATA-EXISTS |
FAIL |
TBD |
Data/object is already existed. |
|
W_DATA-EXISTS |
SOFT_FAIL |
TBD |
Data/object is already existed. |
|
S_WARNING |
SUCCEED |
TBD |
Warning Message |
|
W_WARNING |
SOFT_FAIL |
TBD |
Warning Message |
|
C_TIMEOUT |
FAIL |
TBD |
Time out |
|
R_BUSY |
RETRY_DIS |
TBD |
Network is busy |
|
R_CONNECTION-LOST Foot 1 |
RETRY_DIS |
((?s).)*Connection to the NE lost((?s).)* |
Connection to the NE is lost |
|
R_BROKEN-PIPE Footref 1 |
RETRY_DIS |
((?s).)*Broken pipe((?s).)* |
Broken Pipe. Connection to the NE is lost |
|
C_PROVCART-EXCEPTION Footref 1 |
FAIL |
((?s).)*ProvCartridgeException((?s).)* |
Provisioning Cartridge Exception |
|
CL_EXCEPTION Footref 1 |
FAIL |
((?s).)*Exception((?s).)* |
General Exception |
Footnote 1 You must define this user exit type in your cartridge
|
 Copyright © 2012, Oracle and/or its affiliates. All rights reserved. Legal Notices |
|