13 The Trouble Management API

The Trouble Management API exposes Trouble Management subsystem functions and information that an external (third-party) application can use to:

Create, update, and change the state of trouble tickets in the Trouble Management subsystem
Query for trouble tickets using criteria similar to the Trouble Management subsystem's Ticket Search window
Query to retrieve the service item identifier for a ticket to facilitate triggering of automatic testing through gateway events
Query to retrieve various service items, customer information, and other information such as could be used to populate dropdown lists in a client application

The Trouble Management API is designed to support development of applications that integrate existing network management systems and the Trouble Management subsystem. For example, when a piece of network equipment signals an alarm, your application could use the Trouble Management API to create a trouble ticket in the Trouble Management subsystem. Periodically, or on an as-needed basis, your application could query the Trouble Management API to determine whether a trouble ticket has cleared. Until the initial trouble ticket has cleared, your application can ignore additional alarms from the faulty equipment.

The CORBA servername used by the Trouble Management API is TMSSERVER.

Functionality

Major functions for which you can use the Trouble Management API include:

Creating new trouble tickets
Clearing, closing, and canceling existing trouble tickets
Creating log entries for a given trouble ticket
Updating attributes on an existing ticket
Querying for information about a trouble ticket
Querying for tickets

Once a trouble ticket is created via the Trouble Management API, that ticket can be processed in the Trouble Management subsystem as if it was created using the Trouble Management subsystem. For example, Trouble Management subsystem users can refer an API-generated ticket to multiple organizations, just as if the ticket was entered using the Trouble Management subsystem.

TroubleSession Interface

Note:

The Trouble Management API and the Trouble Management subsystem are separately licensed components of the Oracle Communications MetaSolv Solution product line. The Trouble Management API requires you have the Trouble Management subsystem installed. To acquire licenses to use these products, contact your Oracle representative.

WDIManager

Table 13-1 lists the operations available in the WDIManager interface of the WDITROUBLE.IDL file.

Table 13-1 Trouble Management API WDIManager Interface Operations

Operation	Description
startTroubleSession	Obtains the object reference for the TroubleSession
destroyTroubleSession	Terminates the TroubleSession
startTransaction	commit rollback
destroyTransaction	Terminates the Transaction
startSignal2	eventCompleted eventErrored eventInProgress eventOccurred eventTerminated
destroySignal2	Terminates the Signal2

The Trouble Management API uses the fundamental concepts of the signal handling pattern implemented by the other APIs. However, the Trouble Management API requires a different set of attribute values to uniquely identify an instance of an event within a trouble ticket. Using this variation of the signaling mechanism enables the Trouble Management API to support multiple concurrent events for a given trouble ticket.

See "Common Architecture" for more information about WDIManager.

TroubleSession Interface Operations

Table 13-2 lists the operations available in the TroubleSession interface of the WDITROUBLE.IDL file.

Table 13-2 Trouble Management API TroubleSession Interface Operations

Operation	WDINotification Operations
getPartyByPartyName	getPartyByPartyNameSucceeded getPartyByPartyNameFailed
getCauseCodes	getCauseCodesSucceeded getCauseCodesFailed
getTroubleFoundCodes	getTroubleFoundCodesSucceeded getTroubleFoundCodesFailed
getClearedCodes	getClearedCodesSucceeded getClearedCodesFailed
getServiceItemTypeCodes	getServiceItemTypeCodesSucceeded getServiceItemTypeCodesFailed
getTroubleTypeCodes2	getTroubleTypeCodes2Succeeded getTroubleTypeCodes2Failed
getInitiatingModeCodes2	getInitiatingModeCodes2Succeeded getInitiatingModeCodes2Failed
getTicketStatusCodes2	getTicketStatusCodes2Succeeded getTicketStatusCodes2Failed
getParties2	getParties2Succeeded getParties2Failed
getTicketTypeCodes2	getTicketTypeCodes2Succeeded getTicketTypeCodes2Failed
createLogEntry	createLogEntrySucceeded createLogEntryFailed
getTicketServiceItem	getTicketServiceItemSucceeded getTicketServiceItemFailed
updateTicket--Deprecated. Replaced by updateTicket_v2	updateTicketSucceeded--Deprecated. Replaced by updateTicketSucceeded_v2 operationFailed
updateTicket_v2	updateTicketSucceeded_v2 operationFailed
getTicketForUpdate-- Deprecated. Replaced by getTicketForUpdate_v2.	getTicketForUpdateSucceeded--Deprecated. Replace by getTicketForUpdateSucceeded_v2. operationFailed
getTicketForUpdate_v2	getTicketForUpdateSucceeded_v2 operationFailed
getMsgTrnkGrpServItem	getMsgTrnkGrpServItemNoDataFound getMsgTrnkGrpServItemSucceeded operationFailed
getEUSpecialTrnkGrpServItem	getEUSpecialTrnkGrpServItemNoDataFound getEUSpecialTrnkGrpServItemSucceeded operationFailed
getDSLServItem--Deprecated. This functionality is supported by the getQueryCircuits_v2 operation method in the DLR API.	getDSLServItemNoDataFound--Deprecated. getDSLServItemSucceeded--Deprecated. operationFailed
getInternetCircuitServItem--Deprecated. This functionality is supported by the getQueryCircuits_v2 operation in the DLR API.	getInternetCircuitServItemNoDataFound--Deprecated. getInternetCircuitServItemSucceeded--Deprecated. operationFailed
getInternetDialupServItem	getInternetDialupServItemNoDataFound getInternetDialupServItemSucceeded operationFailed
getTelephoneNumberServItem	getTelephoneNumberServItemNoDataFound getTelephoneNumberServItemSucceeded operationFailed
getCustomers	getCustomersNoDataFound getCustomersSucceeded operationFailed
getTicketForClearClose	getTicketForClearCloseSucceeded operationFailed
clearTicket	clearTicketSucceeded operationFailed
closeTicket	closeTicketSucceeded operationFailed
cancelTicket	cancelTicketSucceeded operationFailed
getTickets_v2	getTicketsNoDataFound_v2 getTicketsSucceeded_v2 operationFailed
getTicketReport_v2	getTicketReportSucceeded_v2 operationFailed
getParties_v3	getPartiesSucceeded_v3 getPartiesFailed
getCustomerAddresses	getCustomerAddressesSucceeded operationFailed
getAssignedToParties	getAssignedToPartiesSucceeded operationFailed
getEscalationMethods	getEscalationMethodsSucceeded operationFailed
createTicket_v2--Deprecated. Replaced by createTicket_v3	createTicketSucceeded_v2--Deprecated. Replaced by createTicketSucceeded_v3. operationFailed
createTicket_v3	createTicketSucceeded_v3 operationFailed
getNetworkElementServItem	getNetworkElementServItemNoDataFound getNetworkElementServItemSucceeded operationFailed
getNetworkSystemServItem	getNetworkSystemServItemNoDataFound getNetworkSystemServItemSucceeded operationFailed

TroubleSession Operation Descriptions

The following list contains a description of the operations available in the TroubleSession interface:

getPartyByPartyName

Given a Party Name and a Party Role as arguments, the getPartyByPartyName operation retrieves information for an active party. This operation may be used to get the party IDs for the Customer role (partyRole = ''CUST'), Responsible Org (partyRole = 'RESP_ORG'), and Administrative Org (partyRole = 'ADMIN_ORG') to pass as arguments in the createTicket_v3 operation. It returns successfully only if the party and its associated party role are still active.

If the party is an individual, the Party Name must be formatted as Last Name, First Name. The party name is stored in upper case in the MetaSolv Solution database, so the API converts the value passed to upper case before performing the search.

If the operation is called to get the Party ID for a customer (partyRole = 'CUST'), it is possible that multiple customers may exist in the database with the same Party Name.

Note:
MetaSolv Solution does not allow multiple Responsible Organizations or Administrative Organizations to have the same name.

If multiple party records are found for a given customer name, this operation returns an error. If this occurs, it is recommended that the customerPartyID not be passed when the createTicket_v3 operation is called. If a service item is included, the Trouble Management API automatically identifies the customer associated with the service item. The customer name can also be included in the logNotes attribute.
getCauseCodes

The getCauseCodes operation retrieves a list of cause codes defined in the MetaSolv Solution Infrastructure subsystem. This operation could be used to populate a drop-down list in a user interface.

You can use the activeOnly Boolean parameter to specify whether or not the list should contain only those codes that are currently listed in the database as active codes. Only active codes should be included in drop-downs used on interfaces where the code is updated for a ticket. Both active and inactive codes are retrieved for drop-downs on query interfaces like the Ticket Query.

The currentCauseCode parameter is used to return a given inactive code along with all the active values when the activeOnly parameter is true. This parameter is optional. It allows you to populate a dropdown field on a ticket that includes all the active codes along with the ticket's current value, even if that code was inactivated after it was set on the ticket. Since both active and inactive codes are returned when the activeOnly parameter is false, the currentCauseCode parameter is ignored if the activeOnly parameter is false.
getTroubleFoundCodes

The getTroubleFoundCodes operation retrieves a list of trouble found codes defined in the Trouble Management subsystem for a given cause code. This operation could be used to populate a drop-down list in a user interface.

You can use the activeOnly Boolean parameter to specify whether or not the list should contain only those codes that are currently listed in the database as active codes. Only active codes should be included in drop-downs used on interfaces where the code is updated for a ticket. Both active and inactive codes should be retrieved for drop-downs on query interfaces like the Ticket Query.

The currentTroubleFoundID parameter is used to return a given inactive code along with all the active values when the activeOnly parameter is true. This parameter is optional. It allows you to populate a dropdown field on a ticket that includes all the active codes along with the ticket's current value, even if that code was inactivated after it was set on the ticket. If passed, the currentTroubleFoundID must be passed as a numeric value. Since both active and inactive codes are returned when the activeOnly parameter is false, the currentTroubleFoundID parameter is ignored if the activeOnly parameter is false.

The causeCode parameter limits the trouble found codes that are returned to only those that are related to this cause code. If activeOnly is passed as true, the cause code is required and must be a valid active or inactive cause code in the Trouble Management subsystem.
getClearedCodes

The getClearedCodes operation retrieves a list of cleared codes and could be used to populate a drop-down list in a user interface.

You can use the activeOnly Boolean parameter to specify whether or not the list should contain only those codes that are currently listed in the database as active codes. Only active codes should be included in drop-downs used on interfaces where the code is updated for a ticket. Both active and inactive codes should be retrieved for drop-downs on query interfaces like the Ticket Query.

The currentClearedCode parameter is used to return a given inactive code along with all the active values when the activeOnly parameter is true. This parameter is optional. It allows you to populate a dropdown field on a ticket that includes all the active codes along with the ticket's current value, even if that code was inactivated after it was set on the ticket. Since both active and inactive codes are returned when the activeOnly parameter is false, the currentClearedCode parameter is ignored if the activeOnly parameter is false.
getServiceItemTypeCodes

The getServiceItemTypeCodes operation retrieves a list of service item type codes supported by the Trouble Management subsystem. This operation could be used to populate a drop-down list in a user interface. The set returned will depend on the migration. See Table 13-6, "Service Item Type and Service Item Identifier" for more information.
getTroubleTypeCodes2

The getTroubleTypeCodes2 operation retrieves a list of trouble type codes defined in the Trouble Management subsystem. This operation could be used to populate a drop-down list in a user interface.

You can use the activeOnly Boolean parameter to specify whether or not the list should contain only those codes that are currently listed in the database as active codes. Only active codes should be included in drop-downs used on interfaces where the code is updated for a ticket. Both active and inactive codes should be retrieved for drop-downs on query interfaces like the Ticket Query.

The currentTroubleTypeID parameter is used to return a given inactive code along with all the active values when the activeOnly parameter is true. This parameter is optional. It allows you to populate a dropdown field on a ticket that includes all the active codes along with the ticket's current value, even if that code was inactivated after it was set on the ticket. If passed, the currentTroubleTypeID must be passed as a numeric value. Since both active and inactive codes are returned when the activeOnly parameter is false, the currentTroubleTypeID parameter is ignored if the activeOnly parameter is false.
getInitiatingModeCodes2

The getInitiatingModeCodes2 operation retrieves a list of initiating mode codes defined in the Trouble Management subsystem. This operation could be used to populate a drop-down list in a user interface.

You can use the activeOnly Boolean parameter to specify whether or not the list should contain only those codes that are currently listed in the database as active codes. Only active codes should be included in drop-downs used on interfaces where the code is updated for a ticket. Both active and inactive codes should be retrieved for drop-downs on query interfaces like the Ticket Query.

The currentInitiatingModeID parameter is used to return a given inactive code along with all the active values when the activeOnly parameter is true. This parameter is optional. It allows you to populate a dropdown field on a ticket that includes all the active codes along with the ticket's current value, even if that code was inactivated after it was set on the ticket. If passed, the currentInitiatingModeID must be passed as a numeric value. Since both active and inactive codes are returned when the activeOnly parameter is false, the currentInitiatingModeID parameter is ignored if the activeOnly parameter is false.
getTicketTypeCodes2

The getTicketTypeCodes2 operation retrieves a list of ticket type codes defined in the Trouble Management subsystem. This operation could be used to populate a drop-down list in a user interface.

You can use the activeOnly Boolean parameter to specify whether or not the list should contain only those codes that are currently listed in the database as active codes. Only active codes should be included in drop-downs used on interfaces where the code is updated for a ticket. Both active and inactive codes should be retrieved for drop-downs on query interfaces like the Ticket Query.

The currentTicketTypeCode parameter is used to return a given inactive code along with all the active values when the activeOnly parameter is true. This parameter is optional. It allows you to populate a dropdown field on a ticket that includes all the active codes along with the ticket's current value, even if that code was inactivated after it was set on the ticket. Since both active and inactive codes are returned when the activeOnly parameter is false, the currentTicketTypeCode parameter is ignored if the activeOnly parameter is false.
getTicketStatusCodes2

The getTicketStatusCodes2 operation retrieves a list of Ticket Status Codes defined in the MetaSolv Solution Infrastructure subsystem. This operation could be used to populate a drop-down list in a user interface.

You can use the activeOnly Boolean parameter to specify whether or not the list should contain only those codes that are currently listed in the database as active codes. Only active codes should be included in drop-downs used on interfaces where the code is updated for a ticket. Both active and inactive codes should be retrieved for drop-downs on query interfaces like the Ticket Query.

The currentTicketStatusID parameter is used to return a given inactive code along with all the active values when the activeOnly parameter is true. This parameter is optional. It allows you to populate a dropdown field on a ticket that includes all the active codes along with the ticket's current value, even if that code was inactivated after it was set on the ticket. If passed, the currentTicketStatusID must be passed as a numeric value. Since both active and inactive codes are returned when the activeOnly parameter is false, the currentTicketStatusID parameter is ignored if the activeOnly parameter is false.

The ticketStateCode parameter is used to return only ticket status codes that are related to the given ticket state code. If activeOnly is passed as true, this parameter is required and must be a valid ticket state code in MetaSolv Solution. If activeOnly is passed as false, the ticketStateCode value is ignored. Valid ticket state codes include openActive, deferred, extreferred, cleared, closed, and canceled.
createLogEntry

The createLogEntry operation creates a log entry for a ticket. It is passed a sequence of log note strings (of no more than 2000 characters each) and creates a single log entry for the ticket. At least one log note string that does not equal spaces is required.

Either the ticketID or documentNumber values are required as input key values. If the documentNumber is not valid, and no valid ticketID is passed, the Trouble Management API returns an exception via the createLogEntryFailed operation.
getTicketServiceItem

The getTicketServiceItem operation returns the ticket ID, current state code, current status ID, for a given ticket document number along with the service item type code, service item ID, and service item description if there is a service item assigned to the ticket. This query is intended to be called in response to a gateway event that is triggered when a user initiates a test of the service item on the ticket.
updateTicket

Deprecated. Replaced by updateTicket_v2.
updateTicket_v2

This operation updates attributes for an existing trouble ticket. This new version of the operation contains support for the new service item types of Network Element, Network System, and Circuit/Connection that were introduced in M/5.1. See "The updateTicket_v2 Operation" for more information.
getTicketForUpdate

Deprecated. Replaced by getTicketForUpdate_v2.
getTicketForUpdate_v2

This operation gets information for a ticket so that an update can be requested. It returns a structure of updateable ticket fields that may be modified and passed to the updateTicket_v2 operation. It also returns the date and time of the report, which must be passed to the updateTicket_v2 operation in order to verify that the ticket has not changed since the information was retrieved.
getMsgTrnkGrpServItem

This operation returns a list of message trunk groups. The information returned includes a circuit ID, which is the identifier passed for a message trunk group service item in the createTicket_v3 and updateTicket_v2 operations.
getEUSpecialTrnkGrpServItem

This operation returns a list of end-user special trunk groups. The information returned includes a two-six-code, which is the identifier passed for an end-user special trunk group service item in the createTicket_v3 and updateTicket_v2 operations.
getDSLServItem

Deprecated. Replaced by getQueryCircuits_v2 in the DLR API.
getInternetCircuitServItem

Deprecated. Replaced by getQueryCircuits_v2 in the DLR API.
getInternetDialupServItem

This operation returns a list of Internet dial-ups. The information returned includes a user ID, which is the identifier passed for an Internet dial-up service item in the createTicket_v3 and updateTicket_v2 operations.
getTelephoneNumberServItem

This operation returns a list of telephone numbers. The information returned includes an unformatted telephone number and a telephone number inventory id either of which can be passed as the identifier for a telephone number service item in the createTicket_v3 and updateTicket_v2 operations.
getCustomers

This operation gets a list of customers matching the criteria given by the caller. The information returned includes a party id and party address sequence which can be passed for the customer and customer address in the createTicket_v3 and updateTicket_v2 operations.
getTicketForClearClose

This operation retrieves clear/close information for a ticket so that a clearTicket or closeTicket operation can be requested.
clearTicket

This operation clears an existing trouble ticket. See "The clearTicket Operation" for more information.
closeTicket

This operation closes an existing trouble ticket. See "Details Concerning Use of the closeTicket Operation" for more information.
cancelTicket

This operation cancels an existing trouble ticket. See "Details Concerning Use of the cancelTicket Operation" for more information.
getTickets_v2

This operation allows you to search for a trouble ticket or a collection of tickets based on a set of criteria, similar to the Ticket Search window in MetaSolv Solution. See "Details Concerning Use of the getTickets_v2 Operation" for more information.
getTicketReport_v2

This operation returns a ticket report. You must pass the operation either a valid document number or ticket ID. If a document number is passed, ticket ID is ignored.
getParties_v3

The getParties_v3 operation retrieves a list of parties that have a given role type. This operation could be used to populate a drop-down list in a user interface.

You can use the activeOnly Boolean parameter to specify whether or not the list should contain only those codes that are currently listed in the database as active codes. Only active codes should be included in drop-downs used on interfaces where the party is updated for a ticket. Both active and inactive parties should be retrieved for drop-downs on query interfaces like the Ticket Query.

The currentPartyID parameter is used to return a given inactive party along with all the active parties when the activeOnly parameter is true. This parameter is optional. It allows you to populate a dropdown field on a ticket that includes all the active parties along with the ticket's current value, even if that party was inactivated after it was set on the ticket. If passed, the currentPartyID must be passed as a numeric value. Since both active and inactive parties are returned when the activeOnly parameter is false, the currentPartyID parameter is ignored if the activeOnly parameter is false.

The partyRole parameter is used to return only parties that have been assigned that role type. This parameter is always required.

The enumerated type definition used for the partyRole parameter includes an option for CUST (Customer). However, the CUST value is not supported by the GetParties_v3 query, and results in an error if passed.
getCustomerAddresses

The getCustomerAddresses operation retrieves a list of active addresses for a given customer. This operation may be used to populate a drop-down list of addresses for a customer on a ticket. A customer address sequence number is returned with each address. The sequence number is passed along with the customer party ID to the createTicket_v3 or updateTicket_v2 operations to set the customer address on a ticket.

The customerPartyID parameter is the party ID that identifies the customer whose addresses are to be retrieved. This is a required parameter. The customerAddressSeq parameter is used return a given address along with all the active addresses. This parameter is optional. It allows you to populate a dropdown field on a ticket that includes all the active customer addresses along with the current address set on the ticket, even if that address was inactivated after it was set on the ticket. If passed, the customerAddressSeq must be passed as a numeric value.
getAssignedToParties

The getAssignedToParties operation retrieves a list of active employees that are associated with either a responsible organization or an administrative organization. This operation may be used to populate a drop-down list of Responsible Organization Assigned To parties or Administrative Organization Assigned To parties on a ticket.

The orgPartyID parameter is the party ID that identifies the responsible organization or administrative organization whose employees are to be retrieved. This is a required parameter. The assignedToPartyID parameter is used return a specific Assigned To party along with all the active employees. This parameter is optional. It allows you to populate a dropdown field on a ticket that includes all the active employees along with the current Assigned To party on the ticket, even if that party was inactivated after it was set on the ticket.
getEscalationMethods

The getEscalationMethods operation retrieves a list of escalation methods defined in the Trouble Management subsystem. This operation could be used to populate a drop-down list in a user interface.

You can use the activeOnly Boolean parameter to specify whether or not the operation should retrieve only active escalation methods. Only active values should be included in drop-downs used on interfaces where the field is updated for a ticket. Both active and inactive values should be retrieved for drop-downs on query interfaces like the Ticket Query.

The escalationMethodID parameter is used to return a given inactive escalation method along with all the active values when the activeOnly parameter is true. This parameter is optional. It allows you to populate a dropdown field on a ticket that includes all the active escalation methods along with the ticket's current value, even if that value was inactivated after it was set on the ticket. If passed, the escalationMethodID must be passed as a numeric value. Since both active and inactive escalation methods are returned when the activeOnly parameter is false, the escalationMethodID parameter is ignored if the activeOnly parameter is false.
createTicket_v2

Deprecated. Replaced by createTicket_v3.
createTicket_v3

This is the operation that creates a ticket. The createTicket_v3 operation contains support for the new service item types of Network Element, Network System, and Circuit/Connection that were introduced in M/5.1. See "The createTicket_v3 Operation" for more information.
getNetworkElementServItem

This operation returns a list of network elements. The information returned includes a a service item ID and name, which are the identifiers passed for a network element service item in the createTicket_v3 and updateTicket_v2 operations.
getNetworkSystemServItem

This operation returns a list of network systems. The information includes a service item ID and name, which are the identifiers passed for a network system service item in the createTicket_v3 and updateTicket_v2 operations.

Trouble Management API IDL Files

The IDL files that describe the operations and data structures that comprise the Trouble Management API are:

WDITROUBLE.IDL
WDITROUBLETYPES.IDL
WDITROUBLETYPES2.IDL
WDITROUBLETYPES_v3.IDL
WDITROUBLETYPES_v4.IDL
WDI.IDL
WDIUTIL.IDL

Process Flows

This section contains a sample process flow for a solicited message. Use the sample flow as a template for developing your own process flows.

Refer to the next section for the process flow used when the Trouble Management API is the client.

Solicited Messages

A solicited message is a message initiated by MetaSolv Solution. In this case, the Trouble Management API plays the role of the client, and your application plays the role of the server.

Table 13-3 lists the interfaces and operations that your application implements using the IDL file provided with the Trouble API.

Table 13-3 Trouble Management API Solicited Message Operations

Interface	For Implementing These Operations
WDIRoot	connect disconnect
WDIManager	startTransaction destroyTransaction
WDITransaction	N/A
WDISignal	eventOccurred eventTerminated
WDIInSignal	N/A

Sample: Solicited Message Process Flow

When the Trouble Management API is the client, the overall process flows as follows:

The Trouble Management API requests a WDIRoot object reference from your application. The request is routed through the ORB.
Your application instantiates a WDIRoot and returns a WDIRoot object
The Trouble Management API invokes the connect operation of the WDIRoot interface, which yields a WDIManager object reference.
The Trouble Management API invokes the startSignal2 operation of the WDIManager interface to get a WDISignal2 object reference.
The Trouble Management API invokes the eventOccurred operation of the WDISignal2 interface, passing a WDIEvent2 structure to notify your application that an event registered to them has occurred within MetaSolv Solution.
The Trouble Management API invokes the destroySignal2 operation of the WDIManager interface.
The Trouble Management API invokes the disconnect operation of the WDIRoot interface.
Once your application completes processing, possibly involving additional unsolicited messages to the APIs, your application connects to the MetaSolv Solution Application Server and follows the same process described above for the API client with the exception that the eventCompleted/Errored operations are invoked passing the original WDIEvent2 structure.

If your application encounters an error, it throws a WDIExcp as defined by the IDL. The Trouble Management API handles CORBA system exceptions and WDIExcp exceptions.

Unsolicited Messages

An unsolicited message is a message initiated by your application. In this case, the Trouble Management API plays the role of the server and your application plays the role of the client with the exception of the callback processing.

Table 13-4 lists the interfaces and operations that the Trouble Management API implements.

Table 13-4 Trouble Management API Unsolicited Message Operations

Interface

Implemented Operations

WDIRoot

connect

disconnect

WDIManager

startTransaction

destroyTransaction

WDITransaction

commit

rollback

Sample Flows for Business Tasks

This section provides a few sample flows for business tasks.

Process Flow for Updating a Trouble Ticket

This process flow demonstrates how your client application and the Trouble Management API server must interact to update a trouble ticket.

Figure 13-1 illustrates the process flow for updating a trouble ticket.

Figure 13-1 Process Flow for Updating a Trouble Ticket

Description of "Figure 13-1 Process Flow for Updating a Trouble Ticket"

The process flow for updating a trouble ticket is as follows:

The client calls the getTicketForUpdate operation to retrieve trouble ticket information.
The server calls the getTicketForUpdateSucceeded operation to return a TicketInfoForUpdate structure, which includes one structure of attributes that are updateable and another structure of attributes that are read-only. The structure also includes the date and time of the export.
The client makes modifications to the updateable data and calls the updateTicket operation, passing it the modified UpdateableTicketInfo structure. In addition to the WDITransaction and WDINotification objects, the updateTicket operation is passed the following parameters:
- The TicketImportInfo structure. This structure includes the ticket's document number and ticket ID.
  
  Note:
  You must pass either document number or ticket ID. If document number is passed, ticket ID is ignored. If you pass neither, an exception is returned.
- The UpdateableTicketInfo structure with any modifications.
- A ServiceItemSeq sequence, which is populated only if the service item is changed. Only one ServiceItem structure can be passed. If more than one structure is passed, an exception is returned.
- A LogNoteInfoSeq sequence, which is included if the update includes log notes.
- A duplicateTicketAllowed Boolean that indicates whether a change to the service item is allowed if another open ticket is found for the same service item. Both the ticket found and the ticket being updated have a ticket type that identifies repeat and chronic trouble (as defined for the ticket type in the MetaSolv Solution Infrastructure). If it is set to false, an exception is returned if another open ticket exists. The client can initially set it to false, and if an exception is returned, present a message to the user asking if they wish to create the ticket anyway (similar to the functionality in MetaSolv Solution). If so, the UpdateTicket operation can be called again with duplicateTicketAllowed set to true.
- The export date and time that was returned from the export. The Trouble Management API server uses this date and time to throw an exception if the ticket was updated by some other process since the ticket information was first exported.
The Trouble Management API server processes the update and indicates success or failure by calling either the updateTicketSucceeded operation or the operationFailed operation on WDINotification object.
Upon the successful update of the ticket, the client application should refresh its user interface by again retrieving the ticket attributes using the getTicketForUpdate operation. This action resets the export date and time.

Process Flow for Clearing a Trouble Ticket

This process flow demonstrates how your client application and the Trouble Management API server must interact to clear a trouble ticket. Clearing a ticket is done when the trouble has been resolved, and you are waiting for the customer to verify that the service has been restored so the ticket may be closed.

The client calls the getTicketForClearClose operation to retrieve trouble ticket information.
The server calls the getTicketForClearCloseSucceeded operation to return a clearCloseTicketExportInfo structure, which includes a structure of attributes that are updateable, the ticket's document number, and the ticket's unique Trouble Management subsystem ID.
The client populates the ClearCloseTicketImportInfo structure, then calls the clearTicket operation. In addition to the WDITransaction and WDINotification objects, the clearTicket operation is passed the following parameters:
- The ClearCloseTicketImportInfo structure. This structure includes the ticket's document number and ticket ID.
  
  Note:
  You must pass either document number or ticket ID. If document number is passed, ticket ID is ignored. If you pass neither, an exception is returned.
- The export date and time that was returned from the export. The Trouble Management API server uses this date and time to throw an exception if the ticket was updated by some other process since the ticket information was first exported.
- An arbitrary reference number supplied by your client application that identifies the transaction. If the clearTicket operation is successful, the Trouble Management API returns this reference number via the clearTicketSucceeded notification.
The Trouble Management API server processes the operation and indicates success or failure by calling either the clearTicketSucceeded operation or the clearTicketFailed operation on WDINotification object.

Process Flow for Closing a Trouble Ticket

This process flow demonstrates how your client application and the Trouble Management API server must interact to close a trouble ticket. Closing a ticket occurs when the trouble is resolved and the customer verifies the service is restored.

The client calls the getTicketForClearClose operation to retrieve trouble ticket information.
The server calls the getTicketForClearCloseSucceeded operation to return a clearCloseTicketExportInfo structure, which includes a structure of updateable attributes, the ticket's document number, and the ticket's unique Trouble Management subsystem ID.
If the ticket is a parent (that is, ParentChildInd = Y), the client should prompt the user to determine whether the child tickets should be closed with the parent. If so, the processChildTickets field on the ClearCloseTicketImportInfo structure should be passed as TRUE.
The client populates the ClearCloseTicketImportInfo structure then calls the closeTicket operation. In addition to the WDITransaction and WDINotification objects, the closeTicket operation is passed the following parameters:
- The ClearCloseTicketImportInfo structure. This structure includes the ticket's document number and ticket ID.
  
  Note:
  You must pass either document number or ticket ID. If document number is passed, ticket ID is ignored. If you pass neither, an exception is returned.
- The export date and time that was returned from the export. The Trouble Management API server uses this date and time to throw an exception if the ticket has been updated by some other process since the ticket information was exported.
- An arbitrary reference number supplied by your client application that identifies the transaction. If the closeTicket operation is successful, the Trouble Management API returns this reference number via the closeTicketSucceeded notification.
The Trouble Management API server processes the operation and indicates success or failure by calling either the closeTicketSucceeded operation or the closeTicketFailed operation on WDINotification object.

Process Flow for Canceling a Trouble Ticket

This process flow demonstrates how your client application and the Trouble Management API server must interact to cancel a trouble ticket. The cancelTicket operation changes the ticket's state to Canceled.
Your client application populates the CancelTicketImportInfo structure then calls the cancelTicket operation.

Note:
You must pass either document number or ticket ID. If document number is passed, ticket ID is ignored. If you pass neither, an exception is returned.
The server processes the cancellation of the ticket. If the cancellation fails, the server calls the operationFailed operation on the WDINotification object. If the operation is successful, the server calls the cancelTicketSucceeded operation. In this case the server also creates a log entry with an audit note for each attribute changed when canceling the ticket, similar to the notes generated by the Trouble Management subsystem.

Note:
If the cancellation is successful, and the ticket is a parent ticket (that is, the ticket's ParentChildInd = Y), then the associated child tickets are also automatically canceled along with the parent ticket. Because of the potential impact of inadvertently canceling many child tickets, you may wish to have your client application display a warning that all child tickets will also be canceled and request that your user confirm the action.

Using the Service Item Test Button Functionality

The service item test button functionality of the Trouble Management subsystem requires that your external application follow a particular sequence of events once it receives a signal that indicates that the Test SI button has been clicked within the Trouble Management subsystem. In order to use the service item test button functionality:

Your external application must receive the gateway event signal that indicates that the Test SI button has been clicked. The gateway event signal contains the trouble ticket's document number.
Your application must use the getTicketServiceItem operation to retrieve the service item ID on the trouble ticket.

Note:
Your application may be able to make use of other API operations that can return the TID, AID, or other identifier that uniquely identifies the service item.
Once the test is completed, your application should update the status of the gateway event to Completed. You can also have your application use the createLogEntry operation to write a trouble ticket log entry that describes the results of the test.

Implementation Concepts

See the following for more information on the Trouble Management API:

Interaction Life Cycle

The external application sends a message to the Trouble Management API via the CORBA implementation. The message consists of the operation requested, the data required by the operation's parameters, and a WDINotification object.
The Trouble Management API executes the requested operation.
Based on the result of the operation, the Trouble Management API determines the appropriate response to return to the external application then:
- If the operation was successful, the Trouble Management API invokes the corresponding succeeded operation on the WDINotification object. The parameters passed with the invocation include any data that is appropriate for the response.
- If the operation was successful but the database contains no records that match the criteria you specified, and the notification operations for that query include a NoData operation, the Trouble Management API invokes the NoData operation on the WDINotification object.
- If the operation was unsuccessful, the Trouble Management API invokes the corresponding failed operation on the WDINotification object. The parameters that the Trouble Management API passes when invoking the operation include appropriate error messages.

Session User ID Can Be Used to Verify Workforce Employee

When your client application calls the connect operation on the WDIManager object, the ConnectReq structure must contain a valid User ID or the connect operation fails. For the Trouble Management API, that User ID must be the workforce User ID for a valid workforce employee. Workforce employees are set up through the MetaSolv Solution Workforce Employee window. This is a different process than setting up an employee with a MetaSolv Solution User ID, and an employee's MetaSolv Solution User ID can be different from their workforce User ID.

Note:

The WDIManager object is a common object used by all the MetaSolv Solution APIs, and the ConnectReq structure was designed to support MetaSolv Solution User IDs and passwords. Unlike MetaSolv Solution User IDs, the Trouble Management subsystem's workforce User IDs do not have a password. Therefore, when populating the ConnectReq structure for use with the Trouble Management API, you can populate the Password field with an empty string,

For certain Trouble Management operations where an audit trail is desirable, the Trouble Management API uses this session User ID instead of the global User ID that is specified in the MetaSolv Solution Application Server's GATEWAY.INI file. The session User ID identifies the workforce user who made the changes to the ticket.

The Trouble Management API operations that require the session User ID are:

cancelTicket
clearTicket
closeTicket
createLogEntry
createTicket_v3
updateTicket_v2

When your client application successfully calls one of these TroubleSession interface operations, the API stores the session User ID (workforce User ID) in the audit notes. The User ID identifies the user who made the changes to the ticket. This mechanism permits you to build client applications that implicitly verify that the requesting user is authorized to perform the critical trouble management actions shown in the list above. If you prefer not to use this verification approach, you should pass a session User ID that is known to be set up in the Trouble Management subsystem as a workforce employee.

Date Field Types

Date fields of type UTCDate are in Coordinated Universal Time (UTC) which can be considered equivalent to GMT. Date fields of type MSVDate are in database server time.

The createTicket_v3 Operation

This section provides information about the createTicket_v3 operation.

Import Ticket Attributes

The createTicket_v3 and updateTicket_v3 operations share the structure UpdateableTicketInfo. Upon successful completion of the createTicket_v3 operation, the ticket ID and the document number are returned with the notification createTicketSucceeded_v3.

The createTicket_v3 operation also accepts an unlimited sequence of log notes. Each note can be up to 2,000 characters long. The Trouble Management subsystem displays these log notes as API Additional Info log notes. This replaces the AdditionalTroubleInfo sequence in the previous release.

The createTicket_v3 operation contains support for the new service item types of Network Element, Network System, and Circuit/Connection that were introduced in M/5.1.

Required Fields in createTicket_v3 Request

The following fields within the UpdateableTicketInfo structure must be populated when any create ticket is requested:

Trouble Detection Date (troubleDetectionDate)
Ticket Type Code (ticketTypeCode)
Initiating Mode ID (initiatingModeID)
Ticket Status ID (ticketStatusID)
Priority Level ID (priorityLevelID)
Responsible Org Party ID (responsibleOrgPartyID)
Administrative Org Party ID (administrativeOrgPartyID)
Intrusive Testing Authorized Indicator (intrusiveTestingAuthInd)
Billing Type Code (billTypeCd)

Business Rules in Processing createticket_v3 Request

The following items list business rules used in validating and processing the createTicket_v3 request:

All code and ID fields must exist and be active.
The Trouble Detection Date must be on or before the ticket open date.
The Ticket Status ID must be valid for the ”openActive” ticket state.
Priority Level values are 0, 1, 2, and 3.
Severity Level values are 0, 1, 2, and 3.
Reported By and Ticket Contact Access Numbers are now taken as a string, instead of in the previous release's TelephoneNumber structure.
Reported By and Ticket Contact Access Numbers can only contain numeric characters if the MetaSolv Solution Enable NPA/NXX Contact Telephone Number Formatting preference is ”Yes.” If this preference is ”Yes” and the access number is not numeric, the access number is not stored with the contact. Instead, a log note is added to provide the telephone number information.
The Reported By and Ticket Contact Access Numbers are only stored when a contact name is given. If the contact name is not given, a log note indicates that the contact access number could not be stored. The log not includes the imported access number.
The Customer Address Sequence can only be specified when the Customer Party ID is specified.
Responsible Org Assigned To Accepted Indicator must be populated with Y or N if the Responsible Org Assigned To Party ID is populated.
Administrative Org Assigned To Accepted Indicator must be populated with Y or N if the Administrative Org Assigned To Party ID
Office Network Location must be a valid location.
Billing Type Code valid values are ”bill” and ”nonBill.”
The Next Customer Status Date cannot be prior to the current date (time is not considered).
The Service Item Sequence (ServiceItemSeq) within the TicketImportInfo structure can either contain 0 or 1 instances of the ServiceItem structure.
The Log Note Information Sequence (LogNoteInfoSeq) can contain any number of entries. The log note text can only contain a maximum of 2000 character each.
These fields, if populated, are required to be numeric:
- Responsible Org ID (responsibleOrgPartyID)
- Responsible Org Assigned To ID (respOrgAssignedToPartyID)
- Administrative Org Party ID (administrativeOrgPartyID)
- Administrative Org Assigned To Party ID (adminOrgAssignedToPartyID)
- Customer Party ID (customerPartyID)
- Escalation Method ID (escalationMethodID)
- Initiating Mode ID (initiatingModeID)
- Ticket Status ID (ticketStatusID)
- Trouble Found ID (troubleFoundID)
- Trouble Type ID (troubleTypeID)
- Customer Status Minutes (customerStatusMinutes)
- ETTR (ettrSeconds)
- Priority Level (priorityLevelID)
- SeverityLevel (severityLevelID)

See "Trouble Management Operational Differences" for more information.

Notifications Upon Ticket Creation

When the createTicket_v3 operation is used to change the Responsible Org, Administrative Org, Resp Org Assigned To, or Admin Org Assigned To change, all appropriate notifications are generated, just as if the change had been made from within the MetaSolv Solution Trouble Management subsystem.

Escalation Levels for createTicket_v3 Request

The createTicket_v3 operation does not support input for escalation levels for the Responsible Org and Administrative Org. It also does not support the input of other escalation organizations on a ticket.

If the input Responsible Org and/or Administrative Org have an escalation profile defined for the input Escalation Method (defined in the organization's escalation profile in Infrastructure), the initial escalation level for the organization is defaulted on the new ticket by the API. If the input Escalation Method has a default escalation organization defined in Infrastructure, that escalation organization and its initial escalation level is defaulted on the new ticket by the API.

Ticket Linkage

Creating a parent-child relationship with another ticket through the Trouble Management API is not supported in M/5.2.

Creating Duplicate Tickets

The duplicateTicketAllowed Boolean field in the TicketImportInfo structure determines whether the API allows setting the service item on a ticket if an open ticket already exists on the that service item, and both tickets have a ticket type that identifies repeat and chronic trouble.

Customer Must Be Passed as a Party ID

In the Trouble Management subsystem, users optionally enter the customer name directly instead of selecting the customer from the Customer Search window. If the customer is not found, the Trouble Management subsystem displays an error when the ticket is saved. The createTicket_v3 operation requires that the customer be passed in the form of a party ID if a customer is being specified. A client may still allow the user to enter the customer name directly and determine the ID by calling the getPartyByPartyName operation. That operation returns a party ID which can then be passed to the createTicket_v3 operation.

Customer is Defaulted Based On the Service Item

If the service item is changed, and there is no customer on the ticket, the API defaults the customer to the customer associated in the MetaSolv Solution database with the service item. If the defaulted customer has only one billing address, the address is also defaulted.

Non-inventoried Service Items Are Not Created

A non-inventoried service item is not created if the service item on a ticket cannot be found in inventory. If the service item cannot be found, the new service item type is set on the ticket, but the service item description is set to null. A log note is created stating that the service item could not be found. The log note includes the service item identifier information passed in the ServiceItem structure.

Certain Codes Are Passed as ID Values

Changes to the following codes on a ticket are passed in the form of their numeric ID values, not the code directly. Trouble Management API queries that return the numeric ID and the code are available for each. This allows you to populate dropdown fields on the client application.

Escalation Method ID
Initiating Mode ID
Ticket Status ID
Trouble Found ID
Trouble Type ID

Ticket Dates and Times Are Imported in GMT

The Trouble Management API assumes that all dates imported via the createTicket_v3 operation are in GMT. It is the responsibility of the client application to convert any imported dates from local time to GMT.

Telcordia Preference and Trouble Management API

MetaSolv Solution uses its Telcordia preference to determine if circuit identifier fields should be formatted according to Telcordia specifications (for example, having the proper number of spaces between virgules). The setting of the Telcordia preference has no effect when you use the Trouble Management API to specify a circuit for the createTicket_v2, createTicket_v3, updateTicket, or updateTicket_v2 operations, and the service item type is one of the types shown in Table 13-5. In such a case, the Trouble Management API searches the database for the value in the corresponding field as a formatted circuit. If the API does not find that value as a formatted circuit, the API searches again for that value as an unformatted circuit using the input provided in the operation's parameters.

Table 13-5 lists the service item types and the field names.

Table 13-5 Field Formatting

Service item type	Field name
Circuit/Connection	CircuitConnectionID
Internet Circuit	InternetCircuitIdent
Internet DSL	DSLCircuitIdent
Message Trunk Group	MsgTrunkGroupIdent

Setting or Changing the Affected Service Item On a Trouble Ticket

The service item on a ticket may be set or changed via the createTicket_v3 or updateTicket_v2 operations by passing a single ServiceItem structure in the ServiceItemSeq sequence. If no change is to be made to the service item, no structure should be sent. Only one structure may be passed in the sequence.

If the API finds the service item in the MetaSolv Solution inventory, the service item type and appropriate service item description are set on the ticket. If the service item cannot be found, the API processes the ticket creation or update without an error, but sets only the service item type on the ticket and writes a log note indicating that the service item could not be found. The log note includes the service item information passed for the service item type. The API does not create non-inventoried service items.

Passing the Service Item Type and Service Item Identifier

The ServiceItem structure includes a service item type attribute and a set of service item identifier attributes. The service item type is an enumerated attribute that categorizes the service items supported by the Trouble Management System. The API uses the service item type to determine which service item identifier to use in attempting to find the service item. Only the appropriate service item identifier is used, and all other information passed is ignored. Table 13-6 lists the service item type values and their corresponding service item identifiers from the ServiceItem structure. One exception to this is the serviceItemID field. It can be used to specify any one of the following service item types.

Table 13-6 Service Item Type and Service Item Identifier

Service item type	Enumerated value	Service item identifier
Equipment	EQUIPMENT	See "Identifying an Equipment Service Item Type" for more information.
Circuit/Connection	CIRCUIT	See "Identifying a Circuit/Connection Service Item Type" for more information.
Message Trunk Group	MSG_TRNKGRP	msgTrunkGroupIdent - This is the circuit ID of the message trunk group.
End User Special Trunk Group	EUS_TRNKGRP	eusTrunkGroupIdent - This is the two six code of the end user special trunk group
Telephone Number	TELNBR	See "Identifying a Telephone Number Service Item Type" for more information.
Internet Dial-Up	INTRNTDLP	InternetDialupIdent - This is the user ID of the internet dial up service
Internet Circuit	INTRNTCKT	InternetCircuitIdent - This is the circuit ID of the internet circuit. After migration to the new M/5.1 graphical format, this service item type moves to the Circuit/Connection service item type.
Internet DSL	BWCKT	DSLCircuitIdent - This is the circuit ID of the Digital Subscriber Line bandwidth circuit. After migration to the new M/5.1 graphical format, this service item type moves to the Circuit/Connection service item type.

Identifying a Circuit/Connection Service Item Type

When a Trouble Management subsystem user creates a trouble ticket on a service item that has a service item type of CIRCUIT, it allows you to identify the faulty circuit by using the circuit ID. The Trouble Management API also allows you to use the circuit ID to identify the faulty circuit.You can use the serviceItemId field to specify a circuit or a connection, in addition to the fields in the CircuitConnectionInfo structure, which was previously called CircuitInfo.The circuit ID can be retrieved from the getQueryCircuits_v2 operation in the DLR API.

In addition, the Trouble Management API allows you to identify the faulty circuit by using port information that is associated with the circuit's port address. The port address information includes:

Target Identifier (TID): The TID identifies a group of equipment associated as part of a system or network element. In MetaSolv Solution, the TID information is maintained on the Node tab of the Network Element Properties window.
Access Identifier (AID): The AID identifies the port address on a piece of equipment within the network element identified by the TID. In MetaSolv Solution, the AID information is stored as the concatenated node address for the port address to which the circuit is assigned.

Using port address information allows you to create a trouble ticket on a circuit when an alarm is triggered on a port address monitored by a fault management product.

Note:

Using port address information for Circuit/Connection service items enables you to use the Outage report to identify all customers affected by the outage and contact the customers proactively to advise them of the trouble. You can generate the Outage report from the Active Ticket Queue window in the Trouble Management subsystem.

Identifying an Equipment Service Item Type

When you use the Trouble Management API to create a trouble ticket on a service item that has a service item type of EQUIPMENT, the Trouble Management API allows you to use one of four methods to identify the faulty equipment:

Equipment ID: The equipment ID for an installed piece of equipment. The equipment ID is retrieved from the queryEquipInstall_v2 operation in WDIEquipment.
Equipment Name: The equipment name for an installed piece of equipment. The equipment name is maintained in the Name field on the Equipment tab of the Equipment window.
Serial Number: The serial number for an installed piece of equipment. The serial number is maintained in the Serial Number field on the Equipment tab of the Equipment window.
Serial Number and COMMON LANGUAGE Equipment Identifier (CLEI) Code: If serial numbers are not unique among the vendors of your installed equipment, you can pass the serial number and CLEI code for the faulty equipment. Uniqueness of CLEI codes is enforced by Telcordia Technologies (formerly Bellcore). However, the CLEI code alone does not sufficiently identify a single piece of equipment. The CLEI code is maintained in the CLEI code field on the Equipment Spec tab of the Equipment Spec window.

WARNING:

The Trouble Management API can use these methods to identify a specific piece of equipment only if you maintain a unique equipment name or unique serial number values for each installed piece of equipment. The Name and Serial Number fields on the Equipment Maintenance window and the CLEI code field on the Equipment Spec tab of the Equipment Spec window are not required fields. Also, MetaSolv Solution does not enforce any validation on the Name and Serial Number fields to ensure that they are unique.

Neither the Trouble Management subsystem nor the Trouble Management API support creating a trouble ticket on equipment that has a service item type of EQUIPMENT at the port address level. The lowest level at which you can create a trouble ticket for Equipment service items is the card on which the port address resides. If you need to create trouble tickets for Equipment service items at a lower level than the card, a work-around method is to create the ticket with a service item type of CIRCUIT instead of EQUIPMENT and pass the TID and AID associated with the port address.

Identifying an Network Element Service Item Type

You can specify a Network Element service item type by specifying the service item type as Element in the servItemType field. You can then specify the specific element by either populating the networkElementName field with the network element name, or you can use the serviceItemId field. The serviceItemId field is preferred, because the networkElementName field can refer to more than one element. Both fields are returned by the getNetworkElementServItem query operation.

Identifying a Network System Service Item Type

You can specify a Network System service item type by specifying the service item type as System in the servItemType field. You can then specify the specific system by either populating the networkSystemShortName field with the unique network system short name, or you can use the serviceItemId field. Both fields are returned by the getNetworkSystemServItem query operation.

Identifying a Telephone Number Service Item Type

When you use the Trouble Management API to create a trouble ticket on a service item that has a service item type of Telephone Number, the Trouble Management API allows you to use one of two methods to identify the appropriate number:

UnformattedTelephoneNumber: The telephone number in a single string format, without containing any formatting characters (that is, it should be all numeric characters) for a telephone number.
TelephoneNbrInvId: The number inventory ID for telephone number. The number inventory ID is retrieved from the operation within the Trouble API.

Clearing the service item from a ticket

A service item may be cleared from an existing ticket by passing a ServiceItem structure with the service item type set to ”none”. No service item identifiers need to be populated in that case. The API clears both the service item type and the service item description from the ticket.

The updateTicket_v2 Operation

This section provides information about the updateTicket_v2 operation.

Updateable Ticket Attributes

When executed successfully, the getTicketForUpdate_v2 operation returns a TicketInfoForUpdate structure which contains an UpdateableTicketInfo structure and a ReadOnlyTicketInfo structure. The trouble ticket attributes you can change through the updateTicket_v2 operation are contained in the UpdateableTicketInfo structure. For each ticket attribute that is changed, a log entry is created with an audit note.

The updateTicket_v2 operation also accepts an unlimited sequence of log notes. Each note can be up to 2,000 characters long. The Trouble Management subsystem displays log notes along with any audit notes that are generated by the Trouble Management API.

Note:

In the Trouble Management subsystem, when the Responsible Org, Resp Org Assigned To, Administrative Org, or Admin Org Assigned To are changed on a ticket, a log note is required. The Trouble Management API does not require a log note when these fields are changed via the updateTicket_v2 operation. If necessary, this may be enforced by the client.

ExportDateTime Field is Used to Check Concurrency

The export date and time (aExportDateTime) returned by the getTicketForUpdate_v2 succeeded notification (getTicketForUpdateSucceeded)is in the database server's time zone. You passed this information back unchanged in the updateTicket _v2 operation and the API uses it to verify that the ticket has not been updated since the read operation in the getTicketForUpdate_v2. If the ticket has been updated after the getTicketForUpdate_v2 read, then an exception is returned.

Required Fields in updateTicket Request

The following fields within the updateableTicketInfo structure must be populated when any update is requested:

Trouble Detection Date (troubleDetectionDate)
Ticket Type Code (ticketTypeCode)
Initiating Mode Id (initiatingModeID)
Ticket Status Id (ticketStatusID)
Priority Level Id (priorityLevelID)
Responsible Org Party Id (responsibleOrgPartyID)
Administrative Org Party Id (administrativeOrgPartyID)
Intrusive Testing Authorized Indicator (intrusiveTestingAuthInd)
Billing Type Code (billTypeCd)

Business Rules in Processing updateTicket_v2 Request

The following items list business rules used in validating and processing the updateTicket_v2 request:

Closed tickets may not be edited.
All code and id fields must exist and be active.
The Trouble Detection Date must be on or before the ticket open date.
The Ticket Status Id must be valid for the current ticket state.
Priority Level values are 0, 1, 2, and 3.
Severity Level values are 0, 1, 2, and 3.
Contact Access Numbers can only contain numeric characters if the ”Enable NPA/NXX Contact Telephone Number Formatting” preference is Yes. Also, this can only be stored when a contact name is given.
The Customer Address Sequence can only be specified when the Customer Party Id is specified.
Responsible Org Assigned To Accepted Indicator must be populated with Y or N if the Responsible Org Assigned To Party Id is populated.
Administrative Org Assigned To Accepted Indicator must be populated with Y or N if the Administrative Org Assigned To Party Id
Office Network Location must be a valid location.
Billing Type Code valid values are ”bill” and ”nonBill.”
Cause Code field is required if the ticket is in a ”cleared” state.
Trouble Found Id field is required if the ticket is in a ”cleared” state.
If Trouble Found Id field is populated then the Cause Code must be populated.
The Trouble Found id field must be associated to the Cause Code.
Cleared Code is required if the ticket is in a ”cleared” state.
The Defer Until Date may be changed only if the ticket is in a Deferred state, and this date cannot be prior to the current date (time is not considered).
The Next Customer Status Date cannot be prior to the current date (time is not considered).
The Service Item Sequence (ServiceItemSeq) within the TicketImportInfo structure can either contain 0 or 1 instances of the ServiceItem structure. If the Service Item Sequence is not given, then it is assumed that it has not changed.
The Log Note Information Sequence (LogNoteInfoSeq) can contain any number of entries. The log note text can only contain a maximum of 2000 character each.
These fields, if populated, are required to be numeric:
- Responsible Org Id (responsibleOrgPartyID)
- Responsible Org Assigned To Id (respOrgAssignedToPartyID)
- Administrative Org Party Id (administrativeOrgPartyID)
- Administrative Org Assigned To Party Id (adminOrgAssignedToPartyID)
- Customer Party Id (customerPartyID)
- Escalation Method Id (escalationMethodID)
- Initiating Mode Id (initiatingModeID)
- Ticket Status Id (ticketStatusID)
- Trouble Found Id (troubleFoundID)
- Trouble Type Id (troubleTypeID)
- Customer Status Minutes (customerStatusMinutes)
- ETTR (ettrSeconds)
- Priority Level (priorityLevelID)
- SeverityLevel (severityLevelID)

See "Trouble Management Operational Differences" for more information.

Notifications Upon Ticket Update

When the updateTicket_v2 operation is used to change the Responsible Org, Administrative Org, Resp Org Assigned To, or Admin Org Assigned To change, all appropriate notifications are generated, just as if the change had been made from within the MetaSolv Solution Trouble Management subsystem.

Ticket Linkage and Ticket Update

If the updated ticket is linked in a common cause relationship as a parent ticket, the updateTicket_v2 operation synchronizes the child ticket(s) with the parent ticket. The Trouble Management API does not include functionality to link or unlink tickets. It only keeps the parent and child tickets synchronized when the parent ticket changes.

Attributes on a child ticket cannot be explicitly altered by an updateTicket_v2 request on the child ticket itself. These updates must be made to the parent ticket. These child ticket attributes are automatically updated when the corresponding attribute changes on the parent ticket:

Ticket Status
Responsible Organization
Administrative Organization
Office Network Location
Priority Level
Severity Level
ETTR
Trouble Description
Trouble Detection Date
Admin Org Assigned To
Responsible Org Assigned To
Administrative Org Assigned To Acceptance Indicator
Responsible Org Assigned To Acceptance Indicator
Defer Until Date
Cause Code
Trouble Found
Cleared Code

These child ticket DMOQ attributes are updated only when closing ticket:

TTR (Total Time to Repair)
Total Customer Time
Total Duration
ETTR Provided Within 30 Mins of Ticket Open
Service Restored Within 30 Minutes of ETTR
Number Statuses Over 30 Minutes After Previous Status
Number of Statuses Given
Circuit In Service Date/Time
Circuit In Service Within 30 Days of Ticket Open
Circuit In Service Within 60 Days of Ticket Open

Updating Duplicate Tickets

The duplicateTicketAllowed Boolean field in the TicketImportInfo structure determines whether the API allows a change to the service item on a ticket if an open ticket already exists on the new service item, and both tickets have a ticket type that identifies repeat and chronic trouble.

About Customer Information and Updating Tickets

This section provides information about customer information and updating tickets.

Customer Must Be Passed as a Party ID

In the Trouble Management subsystem, users can optionally enter the Customer Name directly instead of selecting the customer from the Customer Search window. If the customer is not found, the Trouble Management subsystem displays an error when the ticket is saved. The updateTicket_v2 operation requires that the customer be passed in the form of a party ID if a customer is being specified. A client may still allow the user to enter the customer name directly and determine the ID by calling the getPartyByPartyName operation. That operation returns a party ID which can then be passed to the updateTicket_v2 operation.

Customer is Defaulted Based On the Service Item

If the service item is changed, and there is no customer on the ticket, the API defaults the customer to the customer associated in the MetaSolv Solution database with the service item. The customer billing address is also defaulted. The API writes a log note indicating that the customer was defaulted by the API.

Non-inventoried Service Items Are Not Created

A non-inventoried service item is not created if the service item on a ticket cannot be found in the MetaSolv Solution inventory. If the service item cannot be found, the new service item type is set on the ticket, but the service item description is set to null. A log note is created stating that the service item could not be found. The log note includes the service item identifier information passed in the ServiceItem structure.

Certain Codes are Passed as ID Values

Escalation Method ID
Initiating Mode ID
Ticket Status ID
Trouble Found ID
Trouble Type ID

Ticket Dates and Times Are Exported and Imported in GMT

All dates exported by the getTicketForUpdate_v2 operation are exported in GMT. All dates imported in the updateTicket_v2 operation are assumed to be in GMT. It is the responsibility of the client to convert the exported dates to local time and the imported dates to GMT.

The export date and time returned by the getTicketForUpdate_v2 and getTicketReport operations are in the database server's time zone. The export date and time is passed back unchanged in the updateTicket operation and compared to the ticket's last modified date, which is stored in the database server's time zone.

Audit Note Date/Time Display

In the Trouble Management subsystem, the display of the date/time is determined by the setting on the client workstation and therefore varies depending on the user's individual settings. For the Trouble Management API, the standard format of mm/dd/yyyy hh:mm:ss am/pm (GMT) is used when giving details about date/time fields that have been updated, and these times are in GMT.

Telcordia Preference and Trouble Management API

MetaSolv Solution uses its Telcordia preference to determine if circuit identifier fields should be formatted according to Telcordia specifications (for example, having the proper number of spaces between virgules). The setting of the Telcordia preference has no effect when you use the Trouble Management API to specify a circuit for the createTicket_v2, createTicket_v3, updateTicket, or updateTicket_v2 operations, and the service item type is one of the types shown in Table 13-7. In such a case, the Trouble Management API searches the database for the value in the corresponding field as a formatted circuit. If the API does not find that value as a formatted circuit, the API searches again for that value as an unformatted circuit using the input provided in the operation's parameters.

Table 13-7 lists the service item types and the field names.

Table 13-7 Field Formatting

Service item type	Field name
Circuit/Connection	CircuitConnectionID
Internet Circuit	InternetCircuitIdent
Internet DSL	DSLCircuitIdent
Message Trunk Group	MsgTrunkGroupIdent

The clearTicket Operation

The clearTicket operation clears the designated ticket. That is, it changes the state of the ticket to 'Cleared'. This operation cannot be called on a ticket that is already in a cleared, closed or canceled ticket state. In addition, it cannot be called on a ticket that is an externally referred ticket state. You must first close (that is, verify) all the open external referrals through MetaSolv Solution.

A valid document number or ticket ID is required when a ticket is cleared. If both are passed, the ticket ID is ignored.

The following attributes are also required. These attributes may have already been set through the ticket update process prior to being cleared:

Cause Code
Trouble Found ID
Cleared Code
Ticket Status ID

Cleared Comment is an optional field.

The Trouble Found ID is the numeric ID associated with the trouble found code, and must be passed as a valid numeric value. The numeric ID values are returned with the trouble found codes in the getTroubleFoundCodes operation. The Trouble Found ID must be associated with the Cause Code as defined in the MetaSolv Solution infrastructure.

Likewise, the Ticket Status ID is the numeric ID associated with the ticket status code, and must be passed as a valid numeric value. The numeric ID values are returned with the ticket status codes in the getTicketStatusCodes2 operation. The Ticket Status ID must be associated with the Canceled ticket state as defined in the MetaSolv Solution infrastructure.

The above information is passed to the clearTicket operation in the UpdateableClearCloseInfo structure. Since this structure is also used by the closeTicket operation, it contains attributes for closing a ticket, including close contact first and last name, close contact access number, and close comment. These fields are ignored by the clearTicket operation. If you wish to clear and close a ticket at the same time, you can call the closeTicket operation.

You can also pass the clearTicket operation a sequence of log notes. These notes are displayed in the Clear Ticket event log entry along with the audit notes that are generated for each attribute that is changed. The log notes are not meant to replace the Cleared Comment.

Ticket Linkage and Clear Ticket

If the ticket being cleared is linked in a common cause relationship as a parent ticket, and the processChildTickets attribute is set to TRUE, the clearTicket operation automatically clears any child tickets that have not been cleared. You can determine whether the ticket is a parent or child by the ParentChildInd attribute returned by the getTicketForClearClose operation. The attribute is P if it is a parent, C if it is a child, and blank if it is not linked. If the ticket is a parent, the user should be prompt to ask if they wish to clear all child tickets with the parent.

All of the input information is applied to the child tickets that are cleared with the parent. The Cause Code, Trouble Found ID, and Cleared Code is applied to all child tickets that have not been closed or canceled, regardless of whether they are cleared with the parent.

If the ticket is a child ticket, the Cause Code, Trouble Found ID, and Cleared Code cannot be changed if they are already populated on the parent ticket.

Details Concerning Use of the closeTicket Operation

The closeTicket operation closes the designated ticket. That is, it changes the state of the ticket to 'Closed'. This operation cannot be called on a ticket that is already in a cleared, closed or canceled ticket state. In addition, it cannot be called on a ticket that is an externally referred ticket state. You must first close (i.e., verify) all the open external referrals through MetaSolv Solution.

A valid document number or ticket ID is required when a ticket is cleared. If both are passed, the ticket ID is ignored.

The following attributes are required, with the exception of Cleared Comment. These attributes may have already been set through the ticket update process prior to being cleared or when the ticket was cleared:

Ticket Status ID
Cause Code
Trouble Found ID
Cleared Code
Cleared Comment

With the exception of Close Contact Access Number, the following attributes are required when the state is changed to 'closed':

Close Contact Last Name
Close Contact First Name
Close Contact Access Number
Closed Comment

The API accepts a blank close contact first name or blank close contact last name, as long as one is provided.

If Close Contact Access Number is provided, it must be accompanied by the close contact first and/or last name. The close contact access number should be a telephone number, and can only contain numeric characters if the Enable NPA/NXX Contact Telephone Number Formatting preference is set to Y in MetaSolv Solution. This preference determines whether or not edit masks are used for contact phone numbers in MetaSolv Solution. If a telephone number is stored with formatting, it does not appear correctly when displayed in a field with an edit mask. If this preference is set to Y and the access number is not numeric, an error is returned.

You can also pass the closeTicket operation a sequence of log notes. These notes are displayed in the Close Ticket event log entry along with the audit notes that are generated for each attribute that is changed. The log notes are not meant to replace the Closed Comment.

Ticket Linkage and Close Ticket

If the ticket being closed is linked in a common cause relationship as a parent ticket, and the processChildTickets attribute is set to TRUE, the closeTicket operation automatically closes any child tickets that have not been closed or canceled. You can determine whether the ticket is a parent or child by the ParentChildInd attribute returned by the getTicketForClearClose operation. The attribute is P if it is a parent, C if it is a child, and blank if it is not linked. If the ticket is a parent, the user is prompted to confirm when closing all child tickets in the parent ticket.

All of the input information is applied to the child tickets that are closed with the parent. The Cause Code, Trouble Found ID, and Cleared Code is applied to all child tickets that have not been closed or canceled, regardless of whether they are closed with the parent.

If the ticket is a child ticket, the Cause Code, Trouble Found ID, and Cleared Code cannot be changed if they are already populated on the parent ticket.

Closing an Open/Active Trouble Ticket

As designed, the normal status life cycle of a trouble ticket proceeds from Open/Active at ticket creation, to Cleared when the trouble has been resolved but the customer has not yet verified that the service is restored, to Closed when the customer has verified that the service is working again.

Note:

As designed, the optional states Externally Referred and Deferred are temporary diversions from that normal status life cycle. The optional Canceled state indicates a permanent closure of the ticket.

You can call the closeTicket operation on an Open/Active ticket, and the Trouble Management API can successfully clear and close the ticket at the same time. In this case, you must populate both the required fields for clearing a ticket and the required fields for closing the ticket. From the standpoint of both the Trouble Management subsystem and the Trouble Management API, there is no difference between calling closeTicket on an Open/Active ticket and calling clearTicket and closeTicket separately on the ticket.

Notifications for Cleared and Closed Tickets

When a ticket is cleared or closed via the Trouble Management API, the API sends a cleared or closed ticket notification to all escalation levels to which that ticket had been escalated, just as if the ticket had been cleared or closed in the Trouble Management subsystem. For tickets that were in the Cleared state when closed, the notification process is not called, because the notification process would have already been called when the ticket was cleared.

Details Concerning Use of the cancelTicket Operation

The cancelTicket operation cancels the designated ticket. That is, it changes the state of the ticket to 'Canceled'. This operation cannot be called on a ticket that is already closed or canceled.

A valid document number or ticket ID is required. If both are passed, the ticket ID is ignored.

With the exception of Close Contact Access Number, the following attributes are required when a ticket is canceled:

Closed Comment
Close Contact First Name
Close Contact Last Name
Close Contact Access Number
Ticket Status ID

The API accepts a blank close contact first name or blank close contact last name, as long as one is provided.

If Close Contact Access Number is provided, it must be accompanied by the close contact first and/or last name. The close contact access number must be a telephone number, and can only contain numeric characters if the Enable NPA/NXX Contact Telephone Number Formatting preference is set to Y in MetaSolv Solution. This preference determines whether or not edit masks are used for contact phone numbers in MetaSolv Solution. If a telephone number is stored with formatting, it does not appear correctly when displayed in a field with an edit mask. If this preference is set to Y and the access number is not numeric, an error is returned.

The Ticket Status ID is the numeric ID associated with the ticket status code, and must be passed as a valid numeric value. The numeric ID values are returned with the ticket status codes in the getTicketStatusCodes2 operation. The Ticket Status ID must be associated with the Canceled ticket state as defined in the MetaSolv Solution infrastructure.

You can also pass the cancelTicket operation a sequence of log notes. These notes are displayed in the Cancel Ticket event log entry along with the audit notes that are generated for each attribute that is changed. The log notes are not meant to replace the Closed Comment.

Ticket Linkage and Cancel Ticket

If the ticket being canceled is linked in a common cause relationship as a parent ticket, the cancelTicket operation automatically cancels any child tickets that have not been closed. All of the input information is applied to the child tickets.

If the ticket being canceled is a child ticket, it is automatically unlinked from the parent ticket.

Details Concerning Use of the getTickets_v2 Operation

This operation allows you to query for a trouble ticket or a collection of tickets based on an optional set of criteria and a required sequence of ticket states. This functionality is similar to the MetaSolv Solution Ticket Search window.

The search criteria are passed in the form of a sequence of TicketQueryCriteria structures and a sequence of TicketStateEnum values. The TicketQueryCriteria structures are used to pass all of the searchable criteria that a ticket must meet to be returned by the query. The TicketStateEnum values are used to pass all of the possible ticket states that a ticket may be in to be returned by the query.

Note:

When calling the getTickets_v2 operation, query criteria are optional. However, you must pass at least one ticket state, represented by a TicketStateEnum value, in the TicketStateQuerySeq structure.

If you pass no criteria but do pass a valid state, the response contains all trouble tickets of that state. However, you should exercise caution when doing so to avoid excessive processing time.

If you do not pass at least one valid state, the query fails regardless of the number of criteria you pass

The TicketQueryCriteria structure includes three attributes: TicketSearchableField, which is the field the criteria value must match against; TicketSearchOperation, which is the operator used in the search comparison, and a string value used to compare against the searchable field. (See WDITroubleTypes_v3.idl for the enumerated values for TicketSearchableFields and TicketSearchOperation values).

Use the maxRecords parameter to limit the number of records the query returns. The operation limits the number of records returned to the lesser of the maxRecords parameter and the MetaSolv Solution Query Retrieval Limit preference. The operation returns the WDISearchResultsInfo structure which includes the limit used in the query and a Boolean indicating whether the matching records in the database exceeded the limit.

If no data is found given the query criteria, this operation returns the getTicketsNoDataFound_v2 operation on the Notification object.

The following rules apply to the search criteria:

The following searchable fields must be passed as numeric values:
- InitiatingModeID
- TicketStatusID
- TroubleTypeID
- TroubleFoundID
- PriorityLevelID
- SeverityLevelID
- ResponsibleOrgPartyID
- AdministrativeOrgPartyID
- RespOrgAssingedToPartyID
- AdminOrgAssignedToPartyID
The valid values for ServiceItemTypeCode include:
- EQUIPMENT (used for Equipment)
- CIRCUIT (used for Circuit)
- MSG_TRNKGRP (used for Message Trunk Group)
- EUS_TRUNKGRP (used for End User Special Trunk Group)
- TELNBR (used for Telephone Number)
- INTRNTDLP (used for Internet Dial-Up)
- INTRNTCKT (used for Internet Circuit)
- BWCKT (used Digital Subscriber Line)
The value passed for ServiceItemDescription is compared against the service item description on the trouble ticket. If ServiceItemDescription is passed, it must be accompanied by a ServiceItemTypeCode.
The valid values for PriorityLevelID must be 0, 1, 2, or 3, where these values have the following definitions:
- 0 - Undefined
- 1 - Minor
- 2 - Major
- 3 - Serious
The valid values for SeverityLevelID must be 0, 1, 2, or 3, where these values have the following definitions:
- 0 - Out of Service
- 1 - Back in Service
- 2 - Service Impairment
- 3 - Non Service Affecting Trouble
The DateRangeType identifies which date field to apply the DateRangeFromDate and DateRangeToDate criteria to. Valid values include:
- OPEN DATE
- TROUBLE DETECTION DATE
- CLEARED DATE
- CLOSE DATE
If DateRangeFromDate and DateRangeToDate criteria are passed, then DateRangeType must also be passed.
If either DateRangeFromDate or DateRangeToDate criteria are passed, both must be passed.
The values for DateRangeFromDate and DateRangeToDate must be valid dates and time passed int the format of ”YYYYMMDDHHMMSS” with the hours in 24-hour notation, sometimes referred to as military time. The date and time values are expected to be passed in the GMT time zone. The previous getTickets version expected only the date portion.
If passed, the DateRangeToDate cannot be a date and time prior to DateRangeFromDate.
The TicketSearchableField values listed below may be used with all of the TicketSearchOperation operators. All other ticket searchable fields may only be used with the EQUAL operator.
- DocumentNumber
- TicketID
- CustTroubleTicketNum (Customer Trouble Ticket Number)
- ServiceItemDescription
- CustomerName
- ExtRefTicketNum (External Referral Ticket Number)

The causeCode parameter limits the trouble found codes that are returned to only those that are related to this cause code. If activeOnly is passed as true, the cause code is required and must be a valid active or inactive cause code in the Trouble Management subsystem.

Details Concerning Use of the Service Item Query Operations

The Trouble Management subsystem provides a Service Item query window which may be accessed when editing a trouble ticket in order to find a service item to associate to the ticket. This window presents a different query for each service item type. Query operations that provide similar functionality are available in the Trouble Management API and ICM API. These queries can be used to retrieve the service item identifier that is passed to the createTicket_v3 and updateTicket_v2 operations.

The service item queries for the Circuit and Equipment service item types are not located in the Trouble Management API. To query for circuits, you may use the getQueryCircuits operation located in the ICM API (WDIEquipment.idl). To query for equipment, use the queryEquipInstall_v2 operation, also located in the ICM API (WDIEquipment.idl). For more information about these queries, see "The Inventory and Capacity Management API".

The service item query operations for the remaining service item types, are located in the Trouble Management API. These operations include:

getMsgTrnkGrpServItem (message trunk groups)
getEUSpecialTrnkGrpServItem (end user special trunk groups)
getTelephoneNumberServItem (telephone numbers)
getInternetCircuitServItem (Internet circuits)
getInternetDialupServItem (Internet dial-ups)
getDSLServItem (digital subscriber lines)

In each of these operations in the Trouble Management API, with the exception of getTelephoneNumberServItem, the criteria are passed as a sequence of structures, where the structure includes:

An enumerated field indicating the field to be searched. The enumerated values for this field correspond to the criteria fields on the query window in the Trouble Management subsystem. Only one structure may be passed for a given searchable field.
An enumerated field representing the operator used in the search comparison. For example, EQUAL or LIKE.
A string value which is compared against the field being searched

Each service item query operation in the Trouble Management API is also passed a maxRecords parameter to limit the number of records the query returns. The operation limits the number of records returned to the lesser of the maxRecords parameter and the Query Retrieval Limit preference in MetaSolv Solution. Along with the query results, each operation returns the WDISearchResultsInfo structure which includes the limit used in the query and a Boolean indicating whether the matching records in the database exceeded the limit.

If no data is found given the query criteria, these operations return a ”NoDataFound” operation on the Notification object. For example, getDSLServItemNoDataFound.

Structure Format Criteria for the getTelephoneNumberServItem Operation

To use the getTelephoneNumberServItem operation, you must identify the structure format that applies to the telephone number(s) you are searching for. The structure format defines the components that make up a telephone number. The criteria input for this operation is passed in the StructureFormat structure, which consists of the following attributes:

Structure Type: For this operation, the type must be set to TN (Telephone Number)
Structure Name: This identifies the structure format that applies to the telephone number(s) for which you are searching. For example, TN-US. You can call the getStructureFormatsGivenType operation in the Infrastructure API to get a list of valid telephone number structure formats.
Components: This is a sequence component structures you want to include as criteria. You can get the component details needed to fill out this structure by calling the getComponentsGivenStructureFormat operation in the Infrastructure API with the structure name. The following attributes are included in the SFComponent structure:
- Component ID: This is an internal unique identifier for the component.
- Component Name: This is name of the telephone number component. For example, NPA.
- Component Type: This is a categorization of the component. For example, ”T” (table driven).
- Component Value: This is the component criteria value to be used in the search.

The component ID, name and type must be valid for the structure name, or an error is returned. Only one SFComponent structure may be passed for a given component. A structure format may contain components that are required as criteria in a search. These components can be identified via the output of the getComponentsGivenStructureFormat operation in the Infrastructure API. The requiredIndicator attribute equals Y if the component must be included as criteria.

MetaSolv Solution Software Concepts

This section describes important concepts about the MetaSolv Solution software.

Overview of the Trouble Management Subsystem

Successful development using the Trouble Management API requires an understanding of the Trouble Management subsystem.

The Trouble Management subsystem tracks a reported problem from its initial identification to its resolution. The Trouble Management subsystem maintains information such as contacts, trouble codes, cause codes, and priority and escalation levels. The Trouble Management subsystem records the information necessary to allow the creation of various reports, including DMOQ reports for trouble tickets.

Trouble tickets can be associated with existing circuits, telephone numbers, trunk groups, and customers. The Trouble Management subsystem tracks all activities associated with resolving a ticket and monitors the ticket's state, status and responsible and administrative organizations throughout the ticket's life cycle.

See the online Help for more information.

Permitted Trouble Ticket State Changes

MetaSolv Solution users can change the ticket state of trouble tickets through menu selections within the Trouble Management subsystem.

Figure 13-2 illustrates the ticket state changes permitted by the Trouble Management subsystem.

Figure 13-2 Ticket State Changes Permitted By The Trouble Management Subsystem

Description of "Figure 13-2 Ticket State Changes Permitted By The Trouble Management Subsystem"

The rules that govern ticket state changes through the Trouble Management subsystem are listed below:

Tickets are created in the Open/Active state.
Open Active tickets can be changed to any ticket state except Open Active.
Deferred tickets can be changed to any ticket state except Cleared.
Externally Referred tickets can be changed to any ticket state.
Cleared tickets can be changed to any ticket state except Deferred.
Closed and Canceled tickets cannot change state.

Note:
Closed and canceled are terminal states. Once a trouble ticket is placed in one of these states, the ticket state can never be changed again. Non-reporting details for a closed or canceled trouble ticket can be added or edited. Reportable details cannot be added or edited, except as permitted by the setting of the Allow Editing of Task Completion Date Within the Grace Period preference.

The Trouble Management API allows you to use the updateTicket_v2 operation to change trouble ticket statuses, but only for a subset of the status changes possible through MetaSolv Solution.

Figure 13-3 illustrates the ticket state changes permitted by the Trouble Management API.

Figure 13-3 Ticket State Changes Permitted by The Trouble Management API

Description of "Figure 13-3 Ticket State Changes Permitted by The Trouble Management API"

The rules that govern ticket state changes through the Trouble Management API are listed below:

Tickets are created in the Open/Active state using the createTicket_v3 operation.
Open Active tickets can be changed to Cleared, Closed, and Canceled.
Deferred and Externally Referred tickets an only be changed to Canceled.
Cleared tickets can be changed to Closed and Canceled.
Closed and Canceled tickets cannot change state The updateTicket operation does not permit changes to closed or canceled tickets.

Trouble Management Operational Differences

This section provides information about the operational differences between the Trouble Management subsystem and the Trouble Management API.

Escalation Organizations and Levels and the Trouble Management API

The Trouble Management API does not accept import of the information that fills these editable fields on the Escalations tab of the Trouble Management subsystem's New Ticket window. The Trouble Management API defaults these values when a trouble ticket is created:

Admin Org to Notify - Level
Admin Org to Notify - Notify Ind
Other Org to Notify - Level
Other Org to Notify - Notify Ind
Other Orgs to Notify - Org
Resp Org to Notify - Level
Resp Org to Notify - Notify Ind

The Trouble Management API defaults these values when a ticket is created or when the Administrative Organization, Responsible Organization, or Escalation Method is updated on a ticket.

External Referrals and the Trouble Management API

The Trouble Management subsystem allows a ticket to be externally referred to multiple maintenance center organizations.

The Trouble Management API does not support the creation or maintenance of external referrals. If a ticket has been externally referred, it may be updated using the updateTicket_v2 operation, and it may be canceled using the cancelTicket operation. However, an externally referred ticket cannot be cleared or closed through the Trouble Management API.

User-required Optional Trouble Management Subsystem Fields and the Trouble Management API

The Trouble Management subsystem allows users to require entries for fields that the Trouble Management subsystem defines as optional.

The Trouble Management API does not enforce user-defined requirement of optional Trouble Management subsystem fields when you submit a trouble ticket via the Trouble Management API. Instead, the Trouble Management subsystem requires the first user who updates that trouble ticket in the Trouble Management subsystem to enter the information for the user-required Trouble Management subsystem fields.

User-defined Fields and the Trouble Management API

The Trouble Management subsystem allows users to create user-defined fields and to require entries in those fields on a trouble ticket.

The Trouble Management API does not support import of information for user-defined fields, and user-defined fields are not returned by the getTicketReport_v2 operation.

If a user-defined field is required, the Trouble Management subsystem requires the first user who updates that trouble ticket in the Trouble Management subsystem to enter the information for the field.

Certain Field Values Not Defaulted

In the Trouble Management subsystem, the Customer Status Minutes field and the corresponding Next Customer Status Date and Time field are defaulted in the window display. In earlier releases of the Trouble Management API, the createTicket operation defaulted these field values. Beginning with version M/5, these values are now available in the IDL for the Trouble Management API, which permits your client application to set these values as desired.

When you use the updateTicket _v2 operation to change the Customer Status Minutes field, the updateTicket _v2 operation does not automatically calculate and set the Next Customer Status Date/Time field. Likewise, when you use the updateTicket _v2 operation to clear the Customer Status Minutes field, the updateTicket_v2 operation does not automatically clear the Next Customer Status Date/Time field.

No Default of ETTR, Priority Level or Customer Status Minutes for a Circuit Service Item

In the Trouble Management subsystem, users can set up defaults for the Estimated Time To Restore (ETTR), Priority Level or Customer Status Minutes fields, based on the service type code, service type category, and trouble type for a circuit service item. The updateTicket_v2 operation does not default these fields when an inventoried circuit is set on a ticket.

Repeat and Chronic Trouble Ticket Types

Trouble tickets can either represent real service issues, such as service outages and equipment failures, or can be informational in nature. Whether a given trouble ticket is informational or represents a real service issue is determined by the setting of the Identifies Repeat and Chronic Trouble Indicator check box on the Trouble Management subsystem's Ticket Type window for the ticket's trouble ticket type.

If the Identifies Repeat and Chronic Trouble Indicator check box is selected, the trouble ticket represents a real service issue.
If the Identifies Repeat and Chronic Trouble Indicator check box is deselected, the trouble ticket is informational.

Whenever a new trouble ticket is entered into the database, whether via the Trouble Management subsystem or the Trouble Management API, the ticket is evaluated to determine whether it could constitute an instance of repeat trouble, chronic trouble, or both. In order for a trouble ticket to represent an instance of repeat or chronic trouble, the trouble ticket type's Identifies Repeat and Chronic Trouble Indicator check box must be checked, and the appropriate condition below must be met:

For repeat trouble, at a minimum one trouble ticket that represents a real service issue must have been entered for that service item within the past 30, 60, 90, or greater than 90 days.
For chronic trouble, the service item must have had a minimum number of trouble tickets that represent real service issues within a maximum number of days in the past. These minimum and maximum values are determined by the setting of the Trouble Management subsystem's Chronic Trouble Number of Tickets and Number of Days preference.

A given service item can have multiple informational trouble tickets in an open ticket state at the same time. However, while a given service item has a trouble ticket that represents a real service issue that is in a ticket state other than Closed or Canceled:
The Trouble Management API cannot accept additional trouble tickets that represent a real service issue for that service item.
The Trouble Management subsystem warns users who enter a trouble ticket that represents a real service issue for that service item that the open ticket exists and asks the user if they want to create the new ticket anyway.

Effect of Data Errors in Trouble Reports on Trouble Management API Processing

If your application submits, to the Trouble Management API, a trouble ticket that omits non-critical information or has a non-critical error, the Trouble Management API creates the trouble ticket and adds log notes to the trouble ticket that identify the missing information or data errors. For example, a contact phone number was given, but no contact name was supplied.

If your application submits to the Trouble Management API a trouble ticket that omits critical information or has a critical error, the Trouble Management API rejects the trouble report with an explanation, for example the ticket type code that is passed does not exist in the database.