A Configuring Services Using XML

This chapter describes how to configure Oracle Communications ASAP services using XML schemas and deploy these services using the Service Activation Deployment Tool (SADT).

This service configuration method supersedes the use of stored procedures to configure services.

Note:

Schema validation for XML data processed by the Service Activation Configuration Tool (SACT) and the SADT is turned off by default. If you turn on schema validation and use these tools to deploy ASAP configuration data and service models, and you upgrade ASAP to version 7.2 or later, errors may be reported where previously none were reported.

Configuration Restrictions and Limitations

You can add, update, or delete an entity within the provisioning translation configuration. Before doing so, however, Oracle recommends that you review the structure of the existing configuration to ensure that real-time translation is carried out accurately and successfully.

Specifically, consider the following when you configure provisioning translation:

Constraint conditions, such as switch technology and software load (the software version of the specific switch).
Prerequisite information, such as translation mappings from service actions to atomic actions, that cannot be defined unless the atomic action command is already defined.

You can add configurations at run time without restarting the SARM or network element processor. For more information, see "Loading ASAP Services Dynamically".

Configuring ASAP Services

This section describes the steps for configuring ASAP services.

The configuration of ASAP services using XML consists of the following steps:

Planning
Configuring Atomic Actions
Adding Supporting Data
Configuring Service Actions
Mapping Atomic Actions to Service Actions
Mapping User Exit Types to Base Exit Types
Creating Activation-Model.xml
Configuring Network Element Throughput Using XML

Planning

Based on the services and network elements to be supported, determine the NE-specific commands used for identified service (API calls, MML commands).

Create the service model components and scripts to support the service requirements. Specifically:

Create a State Table or Java method for each NE-specific API call or MML command.
Identify an atomic action for each script (State Table or Java method).
Identify the atomic action parameters and values for atomic action command.
Identify the mapping between each atomic action and State Table.
Identify service action commands required for each supported service.
Identify service-action-to-atomic-action mappings.
Plan enhanced service-action-atomic-action translation.

Configuring Atomic Actions

A typical atomic action XML definition appears as follows:

<?xml version="1.0" encoding="UTF-8"?>
<serviceModel xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:sam="http://www.metasolv.com/ServiceActivation/2003/ServiceModel" xmlns="http://www.metasolv.com/ServiceActivation/2003/ServiceModel" xmlns:fo="http://www.w3.org/1999/XSL/Format">
<description>Nortel NT-DMS10 atomic action Services</description>

<atomicService name="A_NT-DMS10_503-10_ADD_POTS-LINE" xsi:type="AtomicServiceType">

<description>Adds a POTS line.</description>
<timeout>20</timeout>
<retryCount>3</retryCount>
<retryInterval>6</retryInterval>
<rollbackService enable="true">

<rollbackService>A_NT-DMS10_503-10_ADD_POTS-LINE-RB</rollbackService>

</rollbackService>
<sendParameterCount>false</sendParameterCount>
<parameter name="MCLI" xsi:type="SimpleParameterType">

<description>Host NE identifier.</description>
<required>true</required>
<default/>
<parameterValueMap>NE_ID_NT-DMS10</parameterValueMap>

</parameter>
<parameter name="NPA" xsi:type="SimpleParameterType">

<description>3 digit area code.</description>
<required>false</required>
<default/>
<parameterValueMap>NPA</parameterValueMap>

</parameter>
<parameter name="NXX" xsi:type="SimpleParameterType">

<description>First 3 digits of the line number.</description>
<required>true</required>
<default/>
<parameterValueMap>NXX</parameterValueMap>

</parameter>
<parameter name="LINE" xsi:type="SimpleParameterType">

<description>4 digit line extension.</description>
<required>true</required>
<default/>
<parameterValueMap>LINE</parameterValueMap>

</parameter>
<parameter name="LEN" xsi:type="SimpleParameterType">

<description>Line equipment number.</description>
<required>true</required>
<default/>
<parameterValueMap>LEN</parameterValueMap>

</parameter>
<parameter name="LOC" xsi:type="SimpleParameterType">

<description>Equipment location.</description>
<required>false</required>
<default/>
<parameterValueMap>LOC</parameterValueMap>

</parameter>
<parameter name="LCC" xsi:type="SimpleParameterType">

<description>The line or agent class code. 1FR, 1MR, 2FR, 8FR, 10FR, 1MB, 2MR, 4MR.</description>
<required>true</required>
<default/>
<parameterValueMap>LCC</parameterValueMap>

</parameter>
<parameter name="RINGCODE" xsi:type="SimpleParameterType">

<description>The ringing code input for two-party or multiparty services.</description>
<required>false</required>
<default/>
<parameterValueMap>RINGCODE</parameterValueMap>

</parameter>
<parameter name="ZONE" xsi:type="SimpleParameterType">

<description>The OUTWATS zone identification number.</description>
<required>false</required>
<default/>
<parameterValueMap>ZONE</parameterValueMap>

</parameter>
<parameter name="LTG" xsi:type="SimpleParameterType">

<description>Line treatment group.</description>
<required>false</required>
<default/>
<parameterValueMap>LTG</parameterValueMap>

</parameter>
<parameter name="OPT" xsi:type="CompoundParameterType">

<description>Options associated with a service to be established or deleted. A maximum of 20 options can be specified in any single command.</description>
<required>false</required>
<default/>
<parameterValueMap>OPT</parameterValueMap>

</parameter>
<parameter name="IS_OPTIMIZED" xsi:type="SimpleParameterType">

<description>A flag to indicate MML optimization of the command. The values are false and true.</description>
<required>false</required>
<default>true</default>
<parameterValueMap>IS_OPTIMIZED</parameterValueMap>

</parameter>
<parameter name="ACT_CFB" xsi:type="SimpleParameterType">

<description>Conditional flag to activate the CFB feature.</description>
<required>false</required>
<default/>
<parameterValueMap>ACT_CFB</parameterValueMap>

</parameter>
<parameter name="ACT_CFD" xsi:type="SimpleParameterType">

<description>Conditional flag to activate the CFD feature.</description>
<required>false</required>
<default/>
<parameterValueMap>ACT_CFD</parameterValueMap>

</parameter>
<parameter name="ACT_CFDA" xsi:type="SimpleParameterType">

<description>Conditional flag to activate the CFD feature.</description>
<required>false</required>
<default/>
<parameterValueMap>ACT_CFDA</parameterValueMap>

</parameter>
<parameter name="CUSTOM" xsi:type="CompoundParameterType">

<description>Customer-specific parameter.</description>
<required>false</required>
<default/>
<parameterValueMap>CUSTOM</parameterValueMap>

</parameter>

</atomicService>
<atomicService name="A_NT-DMS10_503-10_DEL_POTS-LINE" xsi:type="AtomicServiceType">

<description>Deletes a POTS line.</description>
<sendParameterCount>false</sendParameterCount>
<parameter name="MCLI" xsi:type="SimpleParameterType">

<description>Host NE identifier.</description>
<required>true</required>
<default/>
<parameterValueMap>NE_ID_NT-DMS10</parameterValueMap>

</parameter>
<parameter name="NPA" xsi:type="SimpleParameterType">

<description>3 digit area code.</description>
<required>false</required>
<default/>
<parameterValueMap>NPA</parameterValueMap>

</parameter>

<parameter name="NXX" xsi:type="SimpleParameterType">

<description>First 3 digits of the line number.</description>
<required>true</required>
<default/>
<parameterValueMap>NXX</parameterValueMap>

</parameter>
<parameter name="LINE" xsi:type="SimpleParameterType">

<description>4 digit line extension.</description>
<required>true</required>
<default/>
<parameterValueMap>LINE</parameterValueMap>

</parameter>
<parameter name="CUSTOM" xsi:type="CompoundParameterType">

<description>Customer-specific parameter.</description>
<required>false</required>
<default/>
<parameterValueMap>CUSTOM</parameterValueMap>

</parameter>

</atomicService>

Adding Supporting Data

For atomic actions that map to the JInterpreter device type, the supporting data will consist of Java classes. Java classes are placed in the ..\java\lib directory within a .jar file. The deviceMap section of the atomic action definition appears as follows:

<atomicDeviceMap name="A_NT-DMS10_503-10_ADD_POTS-LINE">

<deviceMap>

<description>(user_msg_only)</description>
<type>NT-DMS10</type>
<version>503-10</version>
<implementation>com.metasolv.cartridge.oss.nt_dms10_503_10.
  DMS10PotsLineProv.addNewLine</implementation>
<interpreter>JINTERPRETER_PROGRAM</interpreter>

</deviceMap>

</atomicDeviceMap>
<atomicDeviceMap name="A_NT-DMS10_503-10_DEL_POTS-LINE">

<deviceMap>

<description>(user_msg_only)</description>
<type>NT-DMS10</type>
<version>503-10</version>
<implementation>com.metasolv.cartridge.oss.nt_dms10_503_10.
  DMS10PotsLineProv.delPotsLine</implementation>
<interpreter>JINTERPRETER_PROGRAM</interpreter>

</deviceMap>

</atomicDeviceMap>

For atomic actions that map C/C++ device types, the supporting data will be State Tables. State Tables are placed in the ..sarm\ne_progs\ directory within an *.npg file. The atomicdeviceMap section of the atomic action definition appears as follows:

<atomicDeviceMap name="A-ADD_OPTION">

<deviceMap>

<description>Adds an option to the POTS line.</description>
<vendor>Nortel</vendor>
<type>DMS</type>
<version>BCS36<</version>
<implementation>ADD_DMS_POT_OPT</implementation>
<interpreter>STATE_TABLE</interpreter>

</deviceMap>

</atomicDeviceMap>

Configuring Service Actions

A service action command (referred to as a CommonServiceType in the XML schema) 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 NEs.

Each service action command within the SARM has a configuration record that you can set up. This record contains the following attributes:

A service action definition appears as follows:

<commonService name="C_NT-DMS10_503-10_ADD_POTS-LINE">

<description>Adds a POTS line.</description>
<rollbackOnFailure>false</rollbackOnFailure>
<priority>30</priority>
<failEvent>

<customEvent/>

</failEvent>

<completeEvent>

<customEvent/>

</completeEvent>

Mapping Atomic Actions to Service Actions

Following the service action configuration parameters, add one or more atomic actions within <serviceMap> element. Atomic-action-to-service-action mappings consist of the <atomicService> identifier and one or more optional conditions.

atomicService – The atomic action identified in the atomicService name.
pointOfNoReturn – The 'point of no return' value for partial rollbacks. Values are:
- 0 (default) – This atomic action is not the 'point of no return' for rollback purposes
- 1 – This atomic action is the 'point of no return' for partial rollback. If rollback occurs, and execution has continued beyond this point, roll back to this atomic action but no further.
- 2 – 'point of no return' for no rollback. After past this atomic action, no rollback can occur.
For more information, see "About Configuring a Rollback Point (Point of No Return)"
description – You can optionally provide a description of the atomic action.
condition – Can be one of four types "A" (AlwaysConditionType),"D" (DefinedConditionType),"N" (NotDefinedConditionType) and "E" (EqualConditionType).
- If the condition is A, the SARM always generates the network action for this service action. For example:
```
...
<condition xsi:type="AlwaysConditionType">
<expression>true</expression>
</condition>
```

<condition xsi:type="AlwaysConditionType"/>

If the condition is D, the SARM only generates a particular atomic action command if the stated service action parameter is defined on the current service action. For example:

...
<condition xsi:type="DefinedConditionType">
<expression/>
<parameterLabel>CCC</parameterLabel>
</condition>

If the condition is N, the SARM only generates a particular atomic action command if the stated service action parameter is not defined on the current service action. For example:

...
<condition xsi:type="NotDefinedConditionType">
<expression/>
<parameterLabel>DDD</parameterLabel>
</condition>

If the condition is E, the SARM only generates a particular atomic action command if the stated service action parameter is defined on the current service action and has a particular parameter value. For example:
```
...
<condition xsi:type="EqualConditionType">
<expression>ABC LIKE "BCS%"</expression>
<parameterLabel>AAA</parameterLabel>
<parameterValue>12345</parameterValue>
</condition>
...
```

A complete service action definition, with the atomic action mappings highlighted in bold, appears as follows:

<commonService name="C_NT-DMS10_503-10_ADD_POTS-LINE">

<description>Adds a POTS line.</description>
<rollbackOnFailure>false</rollbackOnFailure>
<priority>30</priority>
<failEvent>

<customEvent/>

</failEvent>
<completeEvent>

<customEvent/>

</completeEvent>
<serviceMap>

<atomicService>A_NT-DMS10_503-10_ADD_POTS-LINE</atomicService>

</serviceMap>
<serviceMap>

<atomicService>A_NT-DMS10_503-10_ACT_CFB-OPT</atomicService>
<pointOfNoReturn>1</pointOfNoReturn>
<condition xsi:type="AlwaysConditionType">
<expression>(ACT_CFB LIKE "Y%")</expression>
</condition>

</serviceMap>
<serviceMap>

<atomicService>A_NT-DMS10_503-10_ACT_CFD-OPT</atomicService>
<condition xsi:type="AlwaysConditionType">
<expression>(ACT_CFD LIKE "Y%")</expression>
</condition>

</serviceMap>
<serviceMap>

<atomicService>A_NT-DMS10_503-10_ACT_CFDA-OPT</atomicService>
<condition xsi:type="AlwaysConditionType">
<expression>(ACT_CFDA LIKE "Y%")</expression>
</condition>

</serviceMap>

</commonService>

Mapping User Exit Types to Base Exit Types

The ServiceModel.xsd XML schema file contains the following definitions:

<xsd:simpleType name="RegexPattern">

<xsd:annotation>

<xsd:documentation>Simple data type for representing regular

expression search pattern</xsd:documentation>

</xsd:annotation>
<xsd:restriction base="xsd:string">

<xsd:maxLength value="255"/>
<xsd:minLength value="1"/>

</xsd:restriction>

</xsd:simpleType>

<xsd:simpleType name="BaseType">

<xsd:annotation>

<xsd:documentation>Simple data type for representing base

atomic action exit types</xsd:documentation>

</xsd:annotation>
<xsd:restriction base="xsd:string">^{Foot 1}

<xsd:enumeration value="SUCCEED"/>
<xsd:enumeration value="FAIL"/>
<xsd:enumeration value="RETRY"/>
<xsd:enumeration value="RETRY_DIS"/>
<xsd:enumeration value="MAINTENANCE"/>
<xsd:enumeration value="SOFT_FAIL"/>
<xsd:enumeration value="DELAYED_FAIL"/>
<xsd:enumeration value="STOP"/>

</xsd:restriction>

</xsd:simpleType>

<xsd:simpleType name="UserType">

<xsd:annotation>

<xsd:documentation>Simple data type for representing user

defined atomic action exit types</xsd:documentation>

</xsd:annotation>
<xsd:restriction base="xsd:string">

<xsd:minLength value="1"/>
<xsd:maxLength value="20"/>

</xsd:restriction>

</xsd:simpleType>

<xsd:complexType name="NEDescriptor">

<xsd:annotation>

<xsd:documentation>

Identifier used for representing network element software load 
and technology software load. Put in place so that
this information is represented as one logical unit of data.

</xsd:documentation>

</xsd:annotation>
<xsd:sequence>

<xsd:element name="softwareLoad" type="sam:SoftwareLoadType"

minOccurs="0"/>

<xsd:element name="technology" type="sam:TechnologyType"/>
<xsd:element name="neVendor" type="sam:VendorType"/>

</xsd:sequence>

</xsd:complexType>

<xsd:complexType name="UserDefinedExitType">

<xsd:annotation>

<xsd:documentation>

A logical representation of a user defined exit type to base type
mapping.

</xsd:documentation>

</xsd:annotation>
<xsd:sequence>

<xsd:element name="CSDL" type="sam:CommandType" minOccurs="0"/>
<xsd:element name="ASDL" type="sam:CommandType" minOccurs="0"/>
<xsd:element name="neDescriptor" type="sam:NEDescriptor"

minOccurs="0"/>

<xsd:element name="searchPattern" type="sam:RegexPattern" ^{Foot 2}

minOccurs="0"/>

<xsd:element name="userType" type="sam:UserType"/>
<xsd:element name="baseType" type="sam:BaseType"/>
<xsd:element name="description" type="sam:DescriptionType"

minOccurs="0"/>

</xsd:sequence>

</xsd:complexType>

A sample instance document is illustrated below:

<serviceModel xmlns=http://www.metasolv.com/ServiceActivation/2003/ServiceModel

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xsi:schemaLocation="http://www.metasolv.com/ServiceActivation/2003/
ServiceModel
X:\...\Program\ASAP\4.7.1\920_Analysis+Design\Schema\ServiceModel.xsd">
…
…

</commonService>

<userDefinedExitType>

<CSDL>C-ADD_POTS_LINE</CSDL>
<ASDL>A-ADD_POTS_LINE</ASDL>
<neDescriptor>

<softwareLoad>DYNAMIC_SL</softwareLoad>
<technology>DYNAMIC_VENDOR-DYNAMIC_TECH</technology>

</neDescriptor>
<searchPattern>SUCCESS.</searchPattern>^{Foot 3}
<userType>U_SUCCEED</userType>^{Foot 4}
<baseType>SUCCEED</baseType>^{Foot 5}
<description>The Atomic Action provisioning was successful</description>

</userDefinedExitType>
<userDefinedExitType>

<searchPattern>90.</searchPattern>
<userType>U_FAIL</userType>
<baseType>FAIL</baseType>
<description>The Atomic Action failed - fail the current order

and stop processing.</description>

</userDefinedExitType>
<userDefinedExitType>

<searchPattern>101-110[201-215]</searchPattern>^{Foot 6}
<userType>U_SOFT_FAIL</userType>
<baseType>SOFT_FAIL</baseType>
<description>The Atomic Action has encountered a soft failure. Processing will

continue.</description>

</userDefinedExitType>
<userDefinedExitType>

<searchPattern>801-850</searchPattern>^{Foot 7}
<userType>U_MINOR_ERROR</userType>
<baseType>SOFT_FAIL</baseType>

<description>The Atomic Action has encountered a soft failure. Processing will

continue.</description>

</userDefinedExitType>
<userDefinedExitType>

<searchPattern>251-275&&[^261-265]</searchPattern>^{Foot 8}
<userType>U_DELAYED_FAIL</userType>
<baseType>DELAYED_FAIL</baseType>
<description>The Atomic Action has failed during provisioning.</description>

</userDefinedExitType>
<userDefinedExitType>

<CSDL>C-DEL_POTS_LINE</CSDL>
<ASDL>A-DEL_POTS_LINE</ASDL>
<neDescriptor>

<softwareLoad>BCS36</softwareLoad>
<technology>NORTEL_DMS</technology>
<neVendor>Nortel</neVendor>

</neDescriptor>
<searchPattern>*.</searchPattern>
<userType>U_MAINTAIN</userType>
<baseType>MAINTENANCE</baseType>
<description>The Atomic Action will Wait until the NE comes out of

Maintenance Mode</description>

</userDefinedExitType>

</serviceModel>

The previous code sample shows some typical search pattern examples.

Creating Activation-Model.xml

The deployment descriptor must be named activation-model.xml and must reside in the top level of the META-INF directory of the service activation archive (SAR) file. The deployment descriptor must be a valid XML document according to the schema for an activation model deployment descriptor XML document.

When you define an activation model, Oracle recommends that you define your own unique namespace and corresponding namespace prefix for your names. For example:

<activationModel targetNamespace="Nortel,UEIMAS,5.2,ADSL/ATM,DSL 2.0.7"
xmlns="http://www.metasolv.com/2003/ServiceActivation/ActivationModel" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:imas="Nortel,UEIMAS,5.2,ADSL/ATM,DSL 2.0.7"
xmlns:foo="foo,bar"
xsi:schemaLocation="http://www.metasolv.com/2003/ServiceActivation/ActivationModel
D:\ccm_databases\ASAP~smith_windows\ASAP\jmx\xsd\SA_Archive.xsd">
     <vendor>String</vendor>
     <version/>
     <name>String</name>
     <components>
          <component>
               <serviceModel>my_service_model.xml</serviceModel>
          </component>
     </components>
</activationModel>

In this example, any new IDs (commonServices, atomicServices, etc.) defined in the activation model are scoped by the target namespace. Any references to IDs in other activation models must be prefixed by the appropriate namespace (for example, foo:name). Any references to IDs in the current activation model must also be prefixed because the default namespace (xmlns=) refers to the activation model schema namespace. The semantics for the XML schema are the same.

Any service models defined in this SAR must also define the IMAS namespace because any common services, atomic services, and so forth, defined in the service model are scoped by the target namespace. Any references to IDs in other cartridges must be prefixed by the appropriate namespace.

Configuring Network Element Throughput Using XML

NE instance throughput (expressed as the number of milliseconds per transaction on an NE) can be configured using XML through the SACT or using asap_utils. (See asap_utils option 18. Set NE instance throughput in the ASAP Server Configuration Guide for more information).

For general information on NE throughput configuration, see the ASAP Server Configuration Guide.

The Activation Configuration XML schema supports configuration of NE instance throughput through the ElementType and DynamicRoutingTemplateType schema definitions, illustrated below:

Figure A-1 ElementType Schema

Figure A-2 DynamicRoutingTemplateType Schema

Footnote Legend

Footnote 1: The base types supported by this service model
Footnote 2: The mapping between base and user types, with an optional search pattern and description.
Footnote 3: Pattern searches accommodate situations in which responses from the device contain small variants that represent the same meaning. The user type contains an associated search pattern that is applied at runtime. Using regular expressions, you can default a series of responses. For example a regular expression "90." can specify a pattern where any response with the character "90" followed by any character will translate to base type of FAIL. If the regular expression is defined as "90*", then any response with the character "90" followed by any number of characters will translate to base type of FAIL
Footnote 4: The user type that the search pattern maps to.
Footnote 5: The base type that maps to the user type.
Footnote 6: 101 to 110 and 201 to 215 will translate to a base type of SOFT_FAIL
Footnote 7: 801-850 will translate to a base type of SOFT_FAIL. Note that the user type differs from the previous range.
Footnote 8: 251 to 275 but not 261 to 265 will translate to a base type of DELAYED_FAILURE.