| 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 service actions for Oracle Communications ASAP.
A Common Service Description Layer (CSDL) or service action command is an ASAP command that is associated with a particular work order. The service action command is associated with one or more operations on one or more network elements (NEs).
Service action command names are comprised of the string C_ (for Service Action) as well as attributes including the cartridge identification elements (tokens), actions, and services that have been selected for the cartridge. The tokens are separated by underscores, and compound tokens (if required) include a dash as a separator. If the software load token includes a "." it is replaced by a dash. All characters in the name must be in uppercase. The naming convention is as follows:
C_vendor-technology_softwareload_action_entity
Where
C_: This prefix indicates a service action.
vender: see "Selecting the Vendor Token"
technology: see "Selecting the Technology Token"
softwareload: see "Selecting the Software Load Token"
action: see "Selecting the Action Tokens"
entity: see "Selecting Entity Tokens"
|
Note: If service packages are used, the service token should include the service package in its name. For example a service action belonging to the BGP service package would be named as follows:C_CSCO-IOS_12-2-X_ADD_BGP-MAX-PREFIX |
Identify and model meaningful services as service action commands. The first step is to create a one-to-one mapping between each service action and atomic action command. For example, an atomic action that adds three-way calling to a subscriber line should have an associated service action that allows for this feature to be activated individually by an upstream system:
Table 8-1 Service-Action-to-Atomic-Action Mapping (One-to-One)
| Service Action | Atomic Action |
|---|---|
|
|
|
Where possible, also model other meaningful services. For example an atomic action to nail up a relay point on a Nortel Passport NE should also be modeled into a more meaningful service. The service action configuration should therefore include an individual service action that allows the relay point to be nailed up as well as a service action that implements a more meaningful service such as the activation of permanent virtual circuit (which makes use of the atomic action to nail up a relay point among other atomic actions that are used to construct the PVC):
Table 8-2 Meaningful Service-Action-to-Atomic-Action Mapping
| Service Action | Atomic Action | Meaningful Service |
|---|---|---|
|
|
|
No |
|
|
|
Yes |
Service cartridge service actions do not have to follow this naming convention.
Design Studio for ASAP automatically enforces this naming convention when you create a service action with the Service Action Wizard.
To create a service action using Design Studio, use the following procedure:
Select Studio, then New, then Activation, and then Service Action.
From the Service Action Wizard, do the following:
In the Action field, enter an action name that corresponds to an NE command.
In the Entity field, enter an entity name that corresponds to an NE service name or service package you want to configure.
Click Finish.
The Service Action editor appears.
Service action level refers to the relative ordering of the service action within the work order. The SARM must have the service action level in case it receives service actions from a service request processor (SRP) or a Java SRP that is not in the work order in which it must be provisioned. Using the service action level, the SARM can re-order the service actions on an ASAP work order.
Assign service action levels based on the logical sequence in which the service action commands would need to occur if they were contained within a single work order. For example, on some NEs where a change line command is not available, a work order may contain service actions to
Query the line for line attribute information.
Delete the line.
Recreate the line with new attributes.
Re-assign the old attributes
Assigning the levels as shown in the following list ensures that service actions are executed in the correct order if they were for some reason out of sequence on the original order:
Query 100
Delete 120
Add 140
Modify/change 160
To configure a service action sequence using Design Studio:
From the Service Action editor, click the Properties tab.
In the Level field, enter a service action sequence level.
You can optionally configure a service action to trigger a return event to the SRP or JSRP when it receives a defined event.
Service Action Completion Event – The event that is triggered if this service action completes successfully. These events can either be system events or custom events. For information about system events and configuring system events see the ASAP System Administrator's Guide.
Service Action Failure Event – The event that is triggered if this service action fails. These events can either be system events or custom events. For information about system events and configuring system events, see the ASAP System Administrator's Guide.
Each service action command must be defined in a static user-configured translation table that specifies the particular characteristics of the service action command. tbl_csdl_config is a user-created static table that contains all service actions. Each work order submitted to can have one or more associated service actions.
To configure a service action fail or complete event using Design Studio:
From the Service Action editor, in the Properties tab, select a service action completion event from the Service Action Completion Event list.
From the Service Action Failure Event list, select a service action failure event.
After you have defined service action commands, atomic action commands, and atomic action parameters, you can establish mapping relationships between the service action commands and atomic action commands. You must define which atomic action commands are transmitted to the NEP for a given service action command.
A service action command can have one or more atomic action commands. Multiple atomic action commands must be performed in the correct sequence, otherwise the service action can fail. This sequence is identified when creating the mapping relationship. In the example below, the atomic action command CREATE_LINE must be performed before any options are added to that line.
Table 8-3 Service-Action-to-Atomic-Action Mappings
| Service Action | Atomic Action | Parameters | Description |
|---|---|---|---|
|
CREATE_RES_LINE |
CLEAR_INTERCEPT |
MCLI="NEWYORK", NPA="516", NNX="555", LINE="1212" |
Clear the intercept for the directory number before adding line. |
|
CREATE_RES_LINE |
CREATE_LINE |
MCLI="NEWYORK", LEN="2111112", NPA="516", NNX="555", LINE="1212", PARTY="I", PIC="333" |
Create the line in the NE. |
|
CREATE_RES_LINE |
SET_OPTION_ON |
MCLI="NEWYORK", LEN="2111112", NPA="516", NNX="555", LINE="1212", OPT="TTR" |
Add the Touch Tone feature to the line. |
|
ADD_FEATURE |
SET_OPTION_ON |
MCLI="NEWYORK", LEN="2111112", NPA="516", NNX="555", OPT="CAW" |
Add the Call Waiting feature to the line. |
|
Note: Any changes or additions you make to mapping relationships only take effect after the SARM server is restarted. |
The goal of NE interface optimization is to limit the number of independent NE commands (either MML or API calls) that ASAP sends to an NE. Collect related service activation requests and combine them into a single service activation request that ASAP sends to the NE. This avoids performance overhead associated with checking multiple NE responses and provides a higher degree of throughput to the NE.
In the non-optimized (standard) approach, a number of independent atomic actions are combined together to create a service action as shown in the following example:
C_NOKIA-HLR_M11_ADD_FEATURES
A_NOKIA-HLR_M11_ADD_CW
A_NOKIA-HLR_M11_ADD_3WC
A_NOKIA_HLR_M11_ADD_CF
…others feature atomic actions…
In this example, a service, C_NOKIA-HLR_M11_ADD_FEATURES, spawns multiple atomic actions that activate features on a subscriber line. Because each Java method has one feature-related NE command embedded in it, each atomic action that executes sends one NE command to the NE and each atomic action is responsible for checking the response from the NE to verify its success. Though this approach enables tight feature-specific parameter checking in the SARM, the error checking required after ASAP sends each command creates a significant amount of overhead. This approach is suitable when ASAP provisions a small volume of work orders and performance is not a major factor; however, when ASAP provisions a large volume of work orders, this approach may impair the performance of ASAP.
When NE interface optimization is used, a Java method is created that combines the multiple feature requests into one or more NE commands. Some NEs have a length limit to the command string and therefore some splitting of commands may be necessary. The Java method is used to examine the feature flags on the work order and then construct a larger NE command. A generic atomic action command maps to the main Java method and all of the possible atomic action parameters for adding the supported features to the subscriber line are associated with the following atomic action:
C_NOKIA-HLR_M11_ADD_FEATURES
A_NOKIA-HLR_M11_ADD_FEATURES
When a Java method sends more than one command to an NE, it must be transaction-oriented. For example, if a Java method sends multiple commands to an NE and the third command fails, it is necessary to roll back the previous two commands before failing the atomic action
An optimized design requires that all of the atomic action parameters provided to the Java method be configured as optional in the SARM. This reduces the error-checking ability of the SARM and results in a higher degree of fallout at the NE level. Additional coding, maintenance, and testing effort is also required within each Java method. The benefits of this design includes reducing the number of independent commands that are sent to the NE and reducing the number of atomic action commands and responses that ASAP must manage. For more information about atomic action to Java method and MML command ratio, see "About Atomic Action to Java Method Provisioning Command Ratio".
In addition to providing a standard set of atomic action commands that map to the individual NE commands on an NE, it may be possible to implement atomic actions that support NE interface optimization if coupling of commands is supported by the NE. This is most common in the voice networks where numerous features (such as creating a subscriber and adding a number of features) are needed to provide different levels of service to a customer. If the NE does support this functionality, it must be supported in the cartridge in addition to the standard service modeling approach.
To add atomic actions to a service action using Design Studio:
From the Service Action editor, click the Atomic Actions tab, and then click Add.
The Atomic Action Selection dialog box appears.
In the Matching items list, select an atomic action.
Click OK.
The atomic action you selected is added to the atomic action list in the Atomic Actions tab.
|
Note: Atomic actions are executed in the order in which they are added to a service action from the top of the list to the bottom. You can change the position of atomic actions in Atomic Actions tab using the up and down arrows. |
When given a particular service action command and its parameters, the SARM refers to a static user-populated translation table to generate one or more atomic action commands for this service action with certain conditions. tbl_csdl_asdl is a static table that is used by the SARM and contains these mappings between service action commands and atomic action commands. For each atomic action associated with a service action, the SARM verifies whether the atomic action should be spawned for the specified service action. The final determination of whether the atomic action is spawned depends on the atomic action parameter translation process specified in the tbl_asdl_parm database table.
ASAP's translation logic makes it possible to determine whether or not to spawn an atomic action based on a range of values, or based on equal, not equal, greater than or less than conditions. It is also possible to combine conditions using an AND or OR operator. This logic permits detailed computations required to execute an atomic action on the NE, to be performed in the service-action-to-atomic-action translation step, rather than in the atomic action to NE translation step, and streamlines bandwidth usage during NEP to NE communications. The expanded set of possibilities for service-action-to-atomic-action translation allows for a greater flexibility in the translation and mapping process and a more efficient processing effort.
The generation of each atomic action command can also depend on the results of previous atomic actions that return parameters to the SARM upon successful completion.
This arrangement provides a mechanism for flexible translation, allowing the SARM to use one of the following methods to perform service-action-to-atomic-action translation.
Unconditional translation: The SARM always generates the atomic action command for this service action. ASAP supports the following unconditional translation option:
Always – The SARM always generates the atomic action command for this service action.
Conditional translation: The SARM uses conditional logic to decide whether to generate the atomic action command. If the label and/or values associated with the conditional translation are not configured in the database, the atomic action fails. ASAP supports the following conditional translation options:
Always with Include Expression option: The user can define a logical expression using a number of criteria for a service action parameter. The range of options available allows an atomic action to be generated if the service action parameter value is within a set range of values or if the service action parameter is greater than, or less than, or equal to, a specified value. More than one condition can be combined in the expression, using an AND or OR operator. For more information about creating logical expressions, see "Components of Service-Action-to-Atomic-Action Translation Expressions" and "Defining Service Action-Atomic Action Translation Expressions".
Defined – The SARM only generates a particular atomic action command if the stated service action parameter is defined on the service action.
Not Defined – The SARM only generates a particular atomic action command if the stated service action parameter is not defined on the service action.
Equals – The SARM only generates a particular atomic action command if the stated service action parameter is defined on the service action and has a particular parameter value.
|
Note: Always use optional parameters to spawn atomic action commands using the Equals, Defined, and Not Defined conditional translation options. Using a mandatory parameter creates error messages if the mandatory parameter is not used. |
To configure atomic action spawning conditions using Design Studio:
From the Service Action editor, in the Atomic Actions tab, select one of the following options:
Always
Defined
Not Defined
Equals
(Optional) Select Include Expression. This option is only available with the Always condition.
(Optional) Enter a logical expression in the Include Expression text box. This option is only available with the Always condition.
(Optional) Enter an atomic action parameter label in the Parameter Label field. This option is available for the Defined, Not Defined, and Equals conditions.
(Optional) Enter an atomic action parameter label value in the Parameter Value field. This option is only available for the Equals condition.
The eval_exp column (also called Include Expression field in Design Studio) in tbl_csdl_asdl SARM table contains an algebraic expression (as a string) that combines all the parameters to be checked. If the value of the eval_exp in the tbl_csdl_asdl is not NULL, the string is parsed and the expression is evaluated to TRUE or FALSE. If the expression cannot be evaluated (for example, incorrect semantics or non-existent parameter), the translation fails.
The expression for the service-action-to-atomic-action translation contains <parameter operator [value]> groups. To specify the order operations, you must use brackets in the algebraic expression. A string with a length of 255 can accommodate a number of conditions. The average is 20 groups of <parameter operator [value]> groups. Each parameter or value should not exceed 30 bytes in length.
The parameters that may be included in the expression and to be checked are:
Service action parameters and work order parameters
Technology and software load
Table 8-4 shows the predefined parameters available to use with each translation expression.
Table 8-4 Predefined Parameters
| Parameters | Description |
|---|---|
|
HOST_NE |
Remote NE. |
|
TECH |
Technology or NE type. This parameter is read from memory and loaded when SARM starts. |
|
SFTWR |
Software that runs on the NE. This parameter is read from memory and loaded when SARM starts. |
The parameters in the algebraic expression must match one of the parameter names that come from SARM, such as service action or work order parameters. You can define all other parameters and you can check any number of parameters in the algebraic expression (limit of 255 bytes.)
Table 8-5 shows the operators you can use in the service-action-to-atomic action translation expression.
Table 8-5 Service-Action-to-Atomic-Action Translation Expression Operators
| Operators | Description |
|---|---|
|
Boolean: AND, OR and NOT |
These Boolean operators are applied against Boolean values returned by operations performed on parameters. For example: NUM3 < 9999 AND NUM2 <333 The expression to enter in tbl_csdl_asdl is (NUM3 < 9999) AND (NUM2 <333) |
|
Operators to be used against parameters |
Parameter value not required: ISDEF, NOTDEF. For example: NOTDEF VAR7 AND NUM2 > 333 The expression in tbl_csdl_asdl is (NOTDEF VAR7) AND (NUM2 > 333) |
|
Parameter value is required |
Integer operators: >, <, >=, =<, =, != String operators: LIKE, !LIKE For example: (VAR7=72) AND (CENTER !LIKE “YORK”) |
The operators >, <, >=, =<, != and = are used only for integer values. The values provided for these operators in the expression must be convertible to an integer or the translation will fail. These operators trigger the conversion when the expression is parsed.
For string values, you use the operators LIKE and !LIKE (that is, not LIKE) and the values require quotation marks, for example, CENTER !LIKE “YORK”. These operators accept the wildcards % and ?. For example: (TECH LIKE “D?S”) AND (SFTWR !LIKE “BCS%”)
A value is not required for the ISDEF and NOTDEF operators. The groups evaluate to TRUE or FALSE and they can be aggregated together using the operands AND and OR.
All other parameters to be included in the expression can have any name, as long as they match a service action or work order parameter label. If a parameter label is not defined on the incoming work order, translation will fail.
The use of brackets in the service-action-to-atomic-action translation expression to specify the order of the operations simplifies the following aspects of the service-action-to-atomic-action translation process:
Precedence of the operators is already determined
Increased performance when evaluating each atomic action for service action translation
Coding, maintenance, and enhancements of service actions and atomic actions
To avoid errors, you must use spaces between Literal operators and labels and Literal operators and values.
The format is:
(DIS LIKE "B747")
|
Note: Literal operators are: LIKE, !LIKE, ISDEF, NOTDEF. The operators AND and OR always have their operands in brackets, therefore no blank space is mandatory on either side. |
A space between other operators and the operands is recommended but not mandatory.
(AAA < 72) AND (NOTDEF BBB)
To specify the order of the operations, each operator and its operands must be enclosed in a set of brackets:
((A < 8) OR ((NOTDEF B) AND ((C != 3) OR (NOT(D = 9)))))
Table 8-6 shows the possible values in the eval_exp column of tbl_csdl_asdl.
Table 8-6 eval_exp column values
| Value | Description |
|---|---|
|
NULL |
Used when you do not require the enhanced service-action-to-atomic- action translation. You can leave the eval_exp column of tbl_csdl_asdl empty. This expression translates to TRUE, which means the translation relies completely on the cond_flag column. As a result, existing functionality is not affected and an AND is placed between the new and the existing functionality. These conditions are identified in columns cond_flag and eval_exp. An atomic action is valid only if both conditions are satisfied. |
|
Valid algebraic expression |
If you require the enhanced service-action-to-atomic-action translation, you must use a valid algebraic expression that evaluates to TRUE or FALSE in the eval_exp column of the tbl_csdl_asdl table. The evaluation of an expression fails if it finds any syntax error in the expression, or if it cannot get a value for a parameter when the value is required. |
|
TRUE |
The string that is evaluated by the C code to the boolean value TRUE. This is similar to A (always) for existing functionality. |
If the evaluation of the expression fails, a SYS_ERR diagnostic message is logged in the diagnostic file, and the atomic action is not included on the service action.
The expression evaluates to TRUE or FALSE, which would result in spawn or don't spawn the atomic action, respectively. You must ensure that the translation expression is correct. When the SARM starts or the configuration changes are dynamically re-loaded, the syntax of the translation expressions is checked.
Ensure that there is no conflict between the conditions set by the different entities, if you use the following:
Conditional service-action-to-atomic-action spawning logic
Standard service-action-to-atomic-action spawning logic
Atomic action to program or Java method mapping logic
You must also consider that the SARM service-action -to-atomic-action spawning logic creates an AND condition between these entities.
As part of the service action configuration, you must identify whether the service action rolls back in the event of failure. When the SARM begins provisioning a work order, it scans each service action on the order to determine if rollback has been configured. If rollback has been configured for one or more service actions, the SARM flags the work order as requiring rollback in the event of failure.
Table 8-7 shows the service action level rollback qualifications.
Table 8-7 Service Action-Level Rollback Qualifications
| Qualification | Description |
|---|---|
|
Atomic actions must also be configured for rollback separately |
Atomic actions associated with the service actions are not affected by the rollback configuration for service actions. |
|
Override default behavior using order property |
The service action Level Rollback Configuration defines the default behavior for a service action. This setting is ignored if the work order Rollback Property specifies no rollback in the event of a work order failure. |
|
Service action rollback configuration is a prerequisite for work order rollback |
If the WO Rollback Property is turned on and no service actions are configured to require rollback, the work order will not roll back in the event of a failure. |
|
The end state of rolled back service actions is unknown |
During rollback processing, a list of all completed atomic actions is obtained. Regardless of whether an atomic action completes or fails, rollback of previous atomic actions continues. Consequently, the end state of the service action is unknown and must be tested. |
The rollback_req configuration variable is located in tbl_csdl_config in the SARM database. If it is set to Y, rollback occurs. If it is set to N, no rollback occurs.
If a service action that requires rollback fails, the dynamic work order structure in the SARM memory is flagged and the entire work order is rolled back.
|
Note: If employing the delayed_failure property (see "About Delayed Failure Properties"), rollback must be turned off. rollback_req must be set to N, and ignore rollback must be set to Y. |
To enable CSDL rollback functionality using Design Studio:
From the Service Action editor, click the Properties tab, select Rollback.
The wo_rback configuration variable located in tbl_wo_def in the SRP database defines whether the work order rolls back in the event of failure.
|
Note: tbl_wo_def and this variable are only applicable when using the SRP emulator. |
If set to Y, rollback for a work order occurs if the work order times out or fails.
If set to N, no rollback for the work order occurs.
If not specified, the SARM uses D, the default value. In this case, rollback depends on the service action parameter rollback_req in tbl_csdl_config. If rollback_req is set for service action, then the work order rolls back when it times out or fails.
You can configure atomic actions so that when a rollback situation occurs, rollback will only be partially performed, stopping at the atomic action configured to be the point of no return. By configuring the Rollback Point (pointOfNoReturn in the XML) value in an atomic action, you can cause the following actions:
No point of no return functionality - Rollback is performed normally.
State: An atomic action can be configured as the rollback point (also called a point of no return) for partial rollback. If rollback occurs, and execution has continued beyond this point, execution is rolled back to this atomic action but no further.
Stop: An atomic action can be configured as the rollback point for a rollback. After execution has continued past this atomic action, no rollback can occur.
An example scenario with atomic action1, atomic action2, atomic action3 and atomic action4, with atomic action2 configured for point of no return for partial rollback (for example, with a PNR=1), would work as follows. atomic action1, atomic action2 and atomic action3 execute correctly. A work order timeout occurs on atomic action4. atomic action3 is rolled back but because atomic action2 is considered to be the point of no return for partial rollback, neither atomic action2 nor atomic action1 is rolled back.
In the same scenario, if atomic action2 is configured for point of no return with no rollback (for example, PNR=2), then no rollback occurs at all.
To configure a point of no return using Design Studio:
From the Service Action editor, click the atomic actions tab, and then click the empty Rollback Point field for an atomic action.
A list appears.
Select one of the following options:
Leave the field blank to maintain full rollback functionality.
State
Stop
|
 Copyright © 2012, Oracle and/or its affiliates. All rights reserved. Legal Notices |
|