14 Documenting ASAP Cartridges

This chapter describes how to use Oracle Communications Design Studio to document Oracle Communications ASAP cartridges.

About Design Studio Cartridge Documentation

Design Studio provides a cartridge guide generation feature that simplifies the documentation process. The feature becomes available whenever you create a network cartridge project. Design Studio provides a template for the guide, and generates most of the cartridge documentation with information added to entities modeled in the project and the information entered in various editors during development process. An HTML version of the cartridge documentation can be found in the doc/guide folder.

The following list describes the components required to ensure that the cartridge contains all necessary information:

Make sure all description fields for various entities, default values for parameters, and data restrictions are completed.

The Document Command Overview tab in Action Processor editor should describe the MML command string that ASAP sends to the network element (NE). Whenever possible (for example, with the TCP/IP NE interfaces) document the logic of the conditional building of the MML command as pseudo-code, explaining the conventions/syntax used. For example:

Router# configure terminal 
if(INTERFACE_TYPE="optical"){ 
Router(config)# controller SONET {SLOT}/[MODULE]/{PORT} 
Router(config-controller)# au-4 {AU4_NUMBER} tug-3 {TUG3_Number} 
}else ………

When this is not possible (for example, in the case of CORBA or Web service NE interfaces), document the API calls and parameters and if the case provide the request XML (Web services). For example:

This is a sample of SOAP Activate service request:
<?xml version='1.0' encoding='UTF-8'?> <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"> <SOAP-ENV:Body> <ns1:submitSync xmlns:ns1="urn:ProvisioningRequestServer" SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"> <request xmlns:ns2="java:provision.services.web.rpc.ejb" xsi:type="ns2:ProvisionRequest">
<body xmlns:ns3="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="ns3:Array" ns3:arrayType="ns2:ProvisionReqEntity[1]"> <
xmlns:ns5="http://schemas.xmlsoap.org/soap/encoding/" </header>
</request> ……………….
………………………………….etc
</SOAP-ENV: Envelope>

Document the output parameters, returned by the cartridge, under Action Processor Output tab. Provide the label and the value format for returned data as Service Action or INFO parameters. Such parameters are retrieved by the upstream system or can be used in the service model for conditional executions of the next mapped atomic actions. Make sure that returned labels are unique and easy to be identified. It is a good practice to use as prefix the atomic action name. For example:
```
Return as Service Action parameter:
A_NT-DMS100_SN06_ADD_LINE_RETURNCODE=<user defined exit type>
Return as info parameter:
A_NT-DMS100_SN06_ADD_LINE_RETURNINFO=<NE error code>:<NE error description>
```

Enter information under Development Notes tab. Describe the business logic, triggered by the atomic action execution, as implemented in the Java action processor class. For example:

Business Logic Flow:
- Get atomic action parameters from the work order
- Build the User object and set the content (parameters)
- Check if the system is in loopback or not
- If loopback, print the log the API call and parameters
- If not loopback send request to the NE by calling addSubscriber
- Set atomic action exit type by using user defined exit types
- Return out parameters (Service Action and INFO)