16.5 NBI Fault and Provisioning Services (Target NSA)
16.5.3 Command Execute Macro
The macro file must already exist on the NBI Server. To execute the macro from the NBI Test Client run command Execute Macro to execute a macro on the NBI Server:
Step 1 Select command Execute Macro.
Step 2 Type the macro file name in the Macro File entry field.
Step 3 Type the macro arguments in the Arguments entry field.
Step 4 Optional: modify the timeout in the Timeout entry field if wanted.
Step 5 Click the Send button.
Appendix: JavaAPI Examples
This appendix chapter contains the following JavaAPI code examples:
• Opening Communication (Socket)
• Open Session
• Manage Input Parameters of Get Commands
• Using JavaAPI to Get Bulk Data
• Using JavaAPI to Receive Notifications
• Using JavaAPI to Execute Macros
Example: Opening Communication (Socket)
//--- //
// Create an object of class TolService and call its method openCommunication //
// Two parameters are given to method openCommunication // 1. hostname or IP-address of the Northbound Interface // 2. port in the Northbound Interface
// 2462 is the default port for the Inventory and Performance services // 2461 is the default port for the Fault and Provisioning services //
//---
TolService service = new TolService();
try {
service.openCommunication(“172.19.45.16”,”2462”);
}
catch (IOException e){
System.out.println(“opening communication port failed”);
}
Example: Open Session
//--- //
// Create an object of class OpenResultSet and call method openCommunication // of the TolService object created before
//
// Three parameters are given to method openCommunication // 1. user name of an NBI operator
// 2. password of an NBI operator // 3. an object of class OpenResultSet //
//--- OpenResultSet openresultSet = new OpenResultSet ();
try {
service.openSession(“nbif”,”nbif”);
}
catch (IOException e) { ...
}
catch (TolCommunicationException e) { ...
}
//--- //
// Get the handleId using method getHandleId of the OpenResultSet object //
//--- class long handleId = openresultSet.getHandleId();
Example: Manage Input Parameters of Get Commands
//---
// Example: the entity id for entity “interface”
int entityId = NbifAttributeInfo.NIMA_CI_IFACE;
//
// 3A. Attributes must be selected for when getting data for Inventory or // Performance Entities
// - The attribute ids can be taken directly from the NbifAttributeInfo // class using their id or name variables
//
//---
int entityId = NbifAttributeInfo.NIMA_CI_NODE;
ArrayList selectedAttributes = new ArrayList();
int attrId = NbifAttributeInfo.NIMA_AI_NODE_NID;
selectedAttributes.add(new Integer(attrId));
String attrName = NbifAttributeInfo.NIMA_AN_NODE_NHWTYPE;
selectedAttributes.add(new String(attrName));
String attrName = “info1”;
selectedAttributes.add(new String (attrName));
//--- //
// 3B. For a Fault entity ALL attributes must be selected in the // predefined order. The attributes are selected with method // ArrayList getAttrIdArrayList(int entityId)
//
// NOTE: it is also possible to use command getActiveAlarmData(), // which does not require giving the selected attributes at all //
//---
// Example: the entity id for entity “network element fault”
int entityId = NbifAttributeInfo.NSA_CI_NEFLT;
NbifAttributeService nas = new NbifAttributeService();
ArrayList faultAttributeIds;
try {
faultAttributeIds = nas.getAttrIdArrayList(entityId);
}
catch (TolAttributeException e) { throw e;
}
//--- //
// 3C. Key Attributes and Key Values for GetOneData Command
//
//---
// Example of giving keys for GetOne command attributes for // entity iface, which has two key attributes
int entityId = NbifAttributeInfo.NIMA_CI_IFACE;
...
ArrayList keyAttributes = new ArrayList();
ArrayList keyAttrValues = new ArrayList();
int attrIdNid = NbifAttributeInfo.NIMA_AI_IFACE_NID;
int nid = 501;
int attrIdIfnr = NbifAttributeInfo.NIMA_AI_IFACE_IFNR;
int ifnr = 100872;
// Example of creating filters for GetFilteredAll command to get // those interfaces, whose node ID is in the wanted interval // (1000 <= nid < 2000) and whose ifcat value is 2157.
int entityId = NbifAttributeInfo.NIMA_CI_IFACE;
…
ArrayList<Integer> filterAttrIdList = new ArrayList()<Integer>;
ArrayList<Object> filterAttrValueList = new ArrayList<Object>();
ArrayList<Integer> filterTypeCodes = new ArrayList()<Integer>;
String filterStr = “ifcat=2157;nid>=1000;nid<2000”
// Call method parseFilters to parse the filters from a string // and insert the filter IDs, filter types and filter values to // ArrayLists.
try {
parseFilters(filterStr, entityId, filterAttrIdList,
filterAttrIdList, filterAttrValueList, filterTypeCodes) }
catch (TolAttributeException e) {
// parsing String failed – give error info to your application }
// Method parseFilters has filled the attribute ids, filter // types and attribute values to corresponding ArrayLists, which // you can give to method GetAllData.
//
// Note that if you give an optional NbifAttributeValueService- // parameter to method parseFilters, you will be able to give the // values also by their descriptions in the filterStr – String
Example: Using JavaAPI to Get Bulk Data
//--- //
// Use JavaAPI to get data from 8000 NBI //
// The following example shows how to use JavaAPI to get data from 8000 NBI.
// First the OSS Client must create a valid session to the NBI Server. Start // with creating a new objects of JavaAPI classes TolService, TolResultSet // and TolOpenResultSet:
//---
TolService srv = new TolService();
TolResultSet result = new TolResultSet();
OpenResultSet openResult = new OpenResultSet();
// Next, the OSS Client opens the communication channel to the 8000 NBI service // giving the IP address and port number where the 8000 NBI service is running.
// Note that when Inventory data is required, open the communication port 2462:
srv.openCommunication(“172.19.35.104”, 2462);
// When the connection to the 8000 NBI service is established, it is time to // open a client session to 8000 NBI by providing the session’s username (for // example “nbif”) and password (for example “nbif1234”).
srv.openSession(“nbif”, “nbif1234”, openResult);
// At this point the OSS Client has established a valid session to the 8000 NBI // service and it can start sending get requests to 8000 NBI. The handleId of // the OSS Client session is found from the openResult data set.
// Let us assume the OSS Client wants to send a getAllData request to extract // Node object data (Node ID and Node Name).
// Before calling the getAllData method the OSS Client must build the ArrayList // that contains the IDs of the Node attributes that should be in the response // data:
ArrayList selected = new ArrayList();
selected.add(new Integer(NbifAttributeInfo.NIMA_AI_NODE_NID));
selected.add(new Integer(NbifAttributeInfo.NIMA_AI_NODE_NNM));
// Now, the OSS Client is ready to send the getAllData command to 8000 NBI.
try {
srv.getAllData (openResult.getHandleId(), NbifAttributeInfo.NIMA_CI_NODE,
}
catch (IOException e){
// System.out.println ("IOException occurs in GetAllData\n");
}
catch (TolCommunicationException e) { if (e.getSubErrorCode() > 0)
System.out.println("TolCommunicationException occurs in GetAllData\n"
+ “Error code = “ + e.getErrorCode() + “\n”
System.out.println ("TolCommunicationException occurs in GetAllData\n”
+ “Error code = “ + e.getErrorCode() + “\n”
+ “Error message = “ + e.getMessage() + “\n”
+ “No further info available\n”);
} }
// TolCommunicationException might occur if, for example, the selected attribute // IDs are incorrect. The error message looks like the following:
TolCommunicationException occurs in GetAllData Error code = 2
Error message = System error message Sub-Error Code = 1
Sub-Error Description = Parameter error
// TolCommunicationException is also thrown if the query is executed as normal // but there is no data. In that case the error message looks like the
// following:
TolCommunicationException occurs in GetAllData Error code = 0
Error message = GetAll OK but there was no matching data No further info available
// If no Exception occurred, it is time to read result data and you can do this // by using the getNext() iterator. The OSS Client should scan all records until // getNext() returns false. The OSS Client must know what attributes it is // expecting in the response records (Node ID and Node Name). To fetch the // attribute values from the result data set, the OSS Client can use either the // getValueAsString() method for both attributes or use the specific
// getValueXX() methods according to the attributes’ native data types. In this // example we use the native data type method.
//
// Note that the OSS Client can fetch the attributes in a different order from // the one in which the attributes were added to the selected array.
while (result.getNext() == true) {
String nodeName = result.getValueString(NbifAttributeInfo.NIMA_AI_NODE_NNM);
int nodeId = result.getValueInt(NbifAttributeInfo.NIMA_AI_NODE_NID);
System.out.println("Node Id = " + nodeId + " Node name = " + nodeName);
}
Example: Using JavaAPI to Receive Notifications
//--- //
// To receive inventory notifications from 8000 NBI the OSS Client must first // define an own class that implements TolEventObserver
//---class OSSClientObserver implements TolEventObserver {
/* OSS Client code ...*/
}
// If the OSS Client has not yet opened a session to 8000 NBI, this should be // done in the same way as explained in the previous example.
// In the OSS client code, e.g. the constructor of the “OSSClientObserver class, // call the addChangeListener method of the TolService object
srv.addChangeListener(this);
// The next step is to subscribe to the entities from which the OSS Client wants // to receive notifications.
// In this example the OSS Client is only subscribing to the Node entity.
ArrayList subscribeList = new ArrayList();
subscribeList.add(new Integer(NbifAttributeInfo.NIMA_CI_NODE));
srv.subscribeNotification(openResult.getHandleId(), subscribeList);
// The remaining task is to define the implementation of the TolEventObserver // methods in the OSS client class “OSSClientObserver”, which has registered as // an observer to JavaAPI by calling the addChangeListener method.
// JavaAPI will be calling those methods when it has a notification to send.
public void addNotification(TolAddEvent addEvent) {
/* OSS Client code */
}
public void updateNotification(TolUpdateEvent updateEvent) {
/* OSS Client code */
}
public void delNotification(TolDelEvent delEvent) {
/* OSS Client code */
}
public void alarmNotification(TolAlarmEvent alarmEvent) {
/* OSS Client code */
}
public void systemNotification(TolSystemEvent systemEvent) {
/* OSS Client code */
}
// At this stage, the OSS Client is ready to start receiving notifications from // JavaAPI. Whenever there is a change in the 8000 System, JavaAPI will call the // appropriate TolEventObserver method implemented at the OSS Client side.
// To continue our example, let us see how a create notification
// would be processed. When a new Node object is created at the 8000 System, // JavaAPI calls the addNotification method with a TolAddEvent object as // parameter.
// Below is an example on how the addNotification method can be implemented by // the OSS Client:
public void addNotification(TolAddEvent addEvent) {
System.out.println("OSSClientObserver:: New add event, EntityId "
+ addEvent.getEntityId());
ArrayList attrList = addEvent.getAttrIdList();
TolResultSet result = addEvent.getAttrValueSet();
try
catch (TolAttributeException {
System.out.println("TolAttributeException " + e.getMessage());
} }
// Similarly, here are examples on how the delNotification and // updateNotification methods can be implemented:
public void delNotification(TolDelEvent delEvent) {
System.out.println("CustomerApi:: New delete event, EntityId"
try
catch (TolAttributeException e) {
System.out.println("TolAttributeException " + e.getMessage());
} }
public void updateNotification(TolUpdateEvent updateEvent) {
System.out.println("CustomerApi:: New update event, EntityId "
+ updateEvent.getEntityId());
ArrayList keyAttrList = updateEvent.getKeyAttrIdList();
ArrayList changeAttrList = updateEvent.getChangeAttrIdList();
TolResultSet resultKey = updateEvent.getKeyAttrValueSet();
TolResultSet resultChange = updateEvent.getChangeAttrValueSet();
try
String changeAttrVal = resultChange.getValueAsString(changeAttrId);
System.out.println("ChangeAttrId " + changeAttrId + "ChangeAttrValue " + changeAttrVal);
} } }
catch (TolAttributeException e) {
System.out.println("TolAttributeException " + e.getMessage());
} }
// And here is an example on how the alarmNotification method could be // implemented:
public void alarmNotification(TolAlarmEvent alarmEvent) {
System.out.println("CustomerApi:: New alarm event \n"
+ alarmEvent.getString());
TolResultSet result = alarmEvent.getAttrValueSet();
ArrayList attrIdList = result.getAttrIdList();
try
} }
Example: Using JavaAPI to Execute Macros
//--- //
// The following example shows how to use JavaAPI to handle the faults or // provision the 8000 network by executing macros through NBI.
//
// Note that the macro file must already exist on the NBI Server.
// First the OSS Client must create a valid session to the NBI Server.
// with creating a new objects of JavaAPI classes TolService, TolResultSet // and TolOpenResultSet:
//---
TolService srv = new TolService();
TolResultSet result = new TolResultSet()
OpenResultSet openResult = new OpenResultSet();
// Next, the OSS Client opens the communication channel to the 8000 NBI service // giving the IP address and port number where the 8000 NBI service is running.
// Note that when fault data or provisioning is required, open the communication // port 2461:
srv.openCommunication("172.19.35.104", 2461);
// When the connection to the 8000 NBI service is established, it is time to // open a client session to 8000 NBI by providing the session’s username (for // example “nbif”) and password (for example“nbif1234”).
srv.openSession("nbif", "nbif1234", openResult);
// At this point the OSS Client has established a valid session to the 8000 NBI // service and it can start sending get requests to 8000 NBI. The handleId of // the OSS Client session is found from the openResult data set.
// Let us assume the OSS Client wants to execute a macro to acknowledge faults.
// The macro name in the example is “UMSFltAck.mac” and it requires an input // parameter with a name ID “FaultID”. In the following example the timeout // parameter is not given which means that the default timeout is used:
int handleId = openResult.getHandleId();
String macroFileStr = “UMSFltAck”;
String macroArguments = “FaultID=165“;
try{
srv.executeMacro(handleId, macroFileStr, macroArguments);
System.out.println ("Macro executed!\n");
}
catch (IOException e) {
System.out.println ("IOException occurs in Executemacro\n");
}
catch (TolCommunicationException e) {
System.out.println ("TolCommunicationException occurs in Executemacro\n"
+ "Error code = " + e.getErrorCode() + "\n"
// TolCommunicationException occurs e.g. if the macro arguments are not given or // if there are macro specific error messages. The error output looks like the // following:
TolCommunicationException occurs in Executemacro Error code = 2
Error message = System error message Sub-Error Code = 102200
Sub-Error Description = Error at line 27: variable ’FaultID’ not supplied in argument
Exception thrown from file: adaexecm.cpp function: AdaExecMacro