This chapter includes sections about the CallCoordinator application programming interfaces (APIs) and an exit related to data collection. These sections are:
This API allows adding a control number or business value to be added to the call data that CallCoordinator writes to the MIS log.
This API allows updating the ANI data associated with a call.
This API allows programs to write business data to the MIS log.
This exit can access a customized version of the MIS Interface Manager for writing records to the MIS Log.
Each section of this chapter explains the function of the API or module and describes when it would be useful. It defines the CICS communication data area required for each API. It also explains how to use the APIs and customize the module.
There are other CallCoordinator interfaces and APIs used to collect data. They are described in the following sections of this book:
The APIs are defined as general-use programming interfaces. The exit is a product-sensitive programming interface. See "Programming Interfaces" for definitions of general-use and product-sensitive programming interfaces.
This API allows an application program to add, change, or delete the control number and business value of a call entry in the Call Management Control Table (CMCT). CallCoordinator writes this information to the MIS log.
By adding a control number to the Call Management Control Table (CMCT) entry for a call, the number is recorded and maintained for all telephony event records generated for the call. The number can be used to identify records sent to the MIS log.
For example, an insurance company can use policy numbers to identify events of calls from its policy holders. It can then generate policy reports by sorting the MIS log data by policy number.
By adding the business value to an event record for a transaction, a company can tie together certain revenue and/or overhead information with the telephony event data for calls. This enhances the value of business reports generated from the MIS log.
Another use of this API is to enable your screen control program to determine which transaction to START. This API is used to get the control number. The CallCoordinator Screen Control Interface is used to pass the information to your screen control program.
See Chapter 5, "Screen Control" for more information about using the CallCoordinator Screen Control Interface and writing user screen control programs.
To use the Set Control Number API in your application program, do the following:
If calling the API from COBOL II or later, INITIALIZE the Communication data area (CAMC730-COMMAREA-DATA) before setting any of the fields.
Table 32. CICS Communication Data Area for the Set Control Number API (CAMC730)
| Field | Attributes | In/out | Description |
|---|---|---|---|
| COMMAREA | N/A | N/A | 01 level name. |
| COMMAREA-LEN | PIC S9(04) COMP VALUE +1024 | N/A | Length in bytes of the CICS communication data area. |
| COMMAREA -DATA | N/A | N/A | 03 level name. |
| FROM-PROGRAM-NAME | PIC X(08) | In | The name of the program invoking this API. |
| TO-PROGRAM-NAME | PIC X(08) | In | The name of this API (CAMI730C). |
| RETURN-CODE | PIC X(04) | Out | Indicates the result of the attempted operation.
|
| TERM-ID | PIC X(08) | In | Identification number of the CallCoordinator agent's terminal.
When specified, it requires no other input.
It is not required if the following input is provided:
|
| SWITCH-ID | PIC X(10) | In | The switch ID of the called party. SWITCH-ID is required with CALLED-PARTY or CALLER. |
| CALLED-PARTY-EQUIP | PIC X(01) | In | Identifies the type of equipment used by the called party.
Required if CALLED-PARTY is specified.
Values are:
When specified, it requires additional input of CALLED-PARTY. It is not required if the following input is provided:
|
| CALLED-PARTY | PIC X(10) | In | CallCoordinator agent's telephone number.
When specified, it requires additional input of CALLED-PARTY-EQUIP. It is not required if the following input is provided:
|
| CALLER-EQUIP | PIC X(01) | In | Identifies the type of equipment used by the caller.
Required when CALLER is specified.
For this release, values are:
When specified, it requires additional input of CALLER. It is not required if the following input is provided:
|
| CALLER | PIC X(10) | In | The caller's telephone number.
When specified, it requires additional input of CALLER-EQUIP. It is not required if the following input is provided:
|
| CNTL-NBR | PIC X(30) | In | The existing control number for an entry in the CMCT. Can be alphanumeric and in any format. CNTL-NBR is not required. When provided, they are checked for agreement. |
| NEW-CNTL-NBR | PIC X(30) | In | The number to be added or used to replace an existing control number. Can be alphanumeric and in any format. To delete a control number for the current and subsequent events, move spaces to this field. |
| CHNG-REQ | PIC X(01) | In | Type of change requested.
|
| BUS-VLU | PIC X(12) | In | Business value of the transaction. Limited to a value no higher than 2147483647. |
| BUS-VLU-SIGN | PIC X(01) | Input | Business value sign.
|
| FILLER | PIC X(01) | N/A | Reserved for future use. |
| REASON-CODE | PIC X(04) | N/A |
|
| CMCT-INDEX | PIC X(5) | In | The call's CMCT-INDEX. |
| COR-SYSID | PIC X(04) | In | CICS SysId of the COR in which the API is to be invoked if CMCT-INDEX is used in a sysplex environment. |
| FILLER | PIC X(874) | N/A | Spaces. Reserved for future use. |
Required input data must specify the CMCT entry by including:
Input should also specify the type of change being requested, a new control number or business value and business value sign, and CSA release. See Table 32 for descriptions of the input fields for the data area of the API.
EXEC CICS LINK PROGRAM('CAMI730C')
COMMAREA(CAMC730-COMMAREA)
LENGTH(CAMC730-COMMAREA-LEN)
END-EXEC.
If operation of the API was successful, the CMCT record indicated by the request contains a new control number and/or a business value associated with the call.
The CallCoordinator system automatically captures the number of the telephone from which the caller has dialed. This number is provided by the Automatic Number Identification service of your central office. It is called the ANI number. It becomes part of the CMCT record for an active call.
The Set ANI ID API permits updating the ANI number in the CMCT record. When it is invoked by an application program, an agent can enter a number to replace the ANI number that came in with the call.
After the operation of this API, the ANI Source field of the CMCT contains a two digit code:
This indicates the ANI number was updated using the Set ANI ID API.
This provides other information about the ANI number update. For example, it can indicate which agent was responsible for the update. This code is input using the ANI-ID-CODE field of this API.
Application programs can use incoming ANI numbers in processing calls. See "Initiate With Data Interface (CAMC500)" for ways application programs can use ANI numbers.
Sometimes, calls come in with meaningless ANI numbers and without ANI numbers:
In cases such as these, an IVR or live agent can get a meaningful telephone number from the caller. Using this API, the application program updates the ANI number. Then the application program has the ANI number it needs to process the call.
For example, an IVR is set up to screen and route calls. CallCoordinator STARTs the initial transaction for the IVR and passes it the ANI number in the Initiate With Data Interface. It accesses a database to verify the ANI number received with the call. If not found, the IVR instructs the caller to enter the correct ANI number. The IVR transfers the call to an ACD group that can handle the call. CallCoordinator STARTs the initial transaction for agents in this group and passes the updated ANI number in the Initiate With Data Interface. The application program uses it to get the account data the agent needs to handle the call. See "Initiate With Data Interface (CAMC500)" for more information about using the Initiate With Data Interface.
In addition to the Initiate With Data Interface, the Inquire Call Data API can supply the ANI number to an application program. See "Inquire Call Data API (CAMI726C)" for more information.
To use the Set ANI ID API in your application program, do the following:
If calling the API from COBOL II or later, INITIALIZE
the Communication data area
(CAMC786-COMMAREA-DATA)
before setting any of the fields.
Table 33. CICS Communication Data Area for the Set ANI ID API (CAMC786)
| Field | Attributes | In/out | Description |
|---|---|---|---|
| COMMAREA | N/A | N/A | 01 level name. |
| COMMAREA-LEN | PIC S9(04) | I/O | Length in bytes of the CICS communication data area. |
| COMMAREA-DATA | N/A | N/A | 03 level name. |
| FROM-PROGRAM-NAME | PIC X(08) | In | The name of the program invoking this API. |
| TO-PROGRAM-NAME | PIC X(08) | In | The name of this API (CAMI786C). |
| RETURN-CODE | PIC X(04) | Out | Indicates the result of the attempted operation.
|
| INTERNAL-COMMAREA | PIC X(8) | N/A | Do not use. |
| CMCT-INDEX | PIC X(5) | In | The call's CMCT-INDEX used for programs that do not have a TERMINAL associated with them. |
| COR-SYSID | PIC X(4) | In | In a sysplex environment this is required. The CICS SysId of the COR in which the API is to execute. |
| REASON-CODE | PIC S9(04) COMP | Out | For routing errors see "API Router".
|
| FILLER | PIC X(37) | N/A | Spaces. Reserved for future use. |
| ANI-ID-CODE | PIC X | In | A user-defined code indicating something about the update of the ANI number, such as the agent responsible for the update. It is stored in the second position of the ANI number in the CMCT. |
| NEW-ANI-ID | PIC X(32) | In | The new ANI number to be stored in the CMCT. |
| FILLER | PIC X(911) | N/A | Spaces. Reserved for future use. |
EXEC CICS LINK PROGRAM('CAMI786C')
COMMAREA(CAMC786-COMMAREA)
LENGTH(CAMC786-COMMAREA-LEN)
END-EXEC.
If operation of the API was successful, the CMCT entry contains the new ANI number and the user-defined code indicating that the ANI number was updated using this API.
The Write MIS Record API allows writing records from your business application programs to the CallCoordinator MIS Log.
Records that you write using this API are processed by the CallCoordinator MIS Interface Manager. You can write your own version of this module to customize the MIS process for CallCoordinator. Customizing the MIS Interface Manager could affect the records you attempt to add using this API. See "MIS Log Exit" for information about customizing this module.
The MIS Log is the CallCoordinator event log that stores records of all CallCoordinator telephony activity events. CallCoordinator writes event records (in the order they occur) to this file.
Using this API, you can add business-related events and historical data from your application to the MIS log. This permits you to have one file containing both telephony and business-related data. You can use this file when generating reports. See Chapter 9, "Data Reporting" for more information about generating reports.
Your business-related data can include the following:
For example, to determine costs associated with making a sale, your application program can use the API to write a record to the MIS Log. The record could include the following data:
Another way to tie in business records with CallCoordinator telephony records is to add control numbers from your business application (such as the policy number of an insurance policy) to the associated CallCoordinator records. This requires using the Set Control Number API. See "Set Control Number API (CAMI730C)" for more information.
You can also include agent information in your business application records by using the Inquire Agents API to get the agent data from CallCoordinator. See "Inquire Agents API (CAMI720C)" for more information.
When generating reports, you can use the call indices or control numbers when sorting the MIS records. For example, sorting records by Party Index can set up the file to produce a report of all parties involved in calls.
See Figure 9 for a flowchart that shows the complete process of MIS data collection.
In a sysplex environment, write your MIS record to the COR associated with the call. You can do this by passing the CICS SysId of the COR to the API in CAMC700 (MIS-COR-SYSID). The SysId can be obtained from a call to the Inquire Call Data API (CAM1726C), from the Start-with-data area passed to the Initial transaction, or from the Trigger-data area passed to the host-based routing transaction. If no SysId is passed, the API is routed to the first active COR in the CAMTCORS TS Queue.
In a non-sysplex environment, the API is routed to the active COR.
To tie in business data with CallCoordinator data, you can include call index data in records sent to the MIS Log. The call indices are:
Related calls are those made to begin a transfer, consultation, or conference. If the agent puts a caller on hold and starts a new call without indicating intent (transfer, consultation, or conference), the new call gets a new Unit of Work Index.
If the party is involved in two calls at the same time (one on hold, one active), the party index is the same.
See "Inquire Call Data API (CAMI726C)" for information on how to obtain call index data from the CMCT.
Call indices recorded for each telephony event record are written to the MIS Log. Indices are self-maintaining.
To use the Write MIS Record API in your application program, do the following:
In addition, you might want to format the record in a structure comparable to CallCoordinator MIS records. This would assist you in associating user-written records with CallCoordinator records and in later sorting the records for analysis. For the CallCoordinator MIS record formats, see the following tables:
If calling the API from COBOL II or later, INITIALIZE
the Communication data area
(CAMC700-MIS-COMMAREA-DATA)
before setting any of the fields.
Table 34. CICS Communication Data Area for the Write MIS Record API (CAMC700)
| Field | Attributes | In/out | Description |
|---|---|---|---|
| MIS-COMMAREA | N/A | N/A | 01 level name. |
| MIS-COMMAREA-LEN | PIC S9(04) COMP VALUE +850 | In | The length of the CICS communication data area in bytes. |
| MIS-COMMAREA-DATA | N/A | N/A | 03 level name. |
| FROM-PROGRAM-NAME | PIC X(08) | In | The name of the program invoking this API. |
| TO-PROGRAM-NAME | PIC X(08) | In | The name of this API (CAMI700C). |
| MIS-RETURN-CODE | PIC X | Out | Indicates the result of the attempted operation:
|
| MIS-REASON-CODE | PIC S9(4) COMP | Out | For routing errors see "API Router".
|
| MIS-COR-SYSID | PIC X(04) | In | The CICS SysId of the COR in which to write the message. If not provided, the message is written to the first active COR found in the CAMTCORS TS Queue. The COR SysId for the current call can be found from the Inquire Call Data API (CAMI726C). |
| FILLER | PIC X(113) | N/A | Spaces. Reserved for future use. |
| MIS-MESSAGE | PIC X(460) | In | Data to be written to the MIS Log. |
| FILLER | PIC X(252) | N/A | Spaces. Reserved for future use. |
EXEC CICS LINK PROGRAM('CAMI700C')
COMMAREA(CAMC700-MIS-COMMAREA)
LENGTH(CAMC700-MIS-COMMAREA-LEN)
END-EXEC.
If operation of the API was successful, the specified record is written on the MIS Log.
+-------------Product-sensitive programming interface information--------------+
The MIS Log Exit is an interface that provides input to the MIS Interface Manager.
You can use this exit, for example, to identify and log abandoned calls for future client call-backs.
The MIS Interface Manager receives call records and error messages from the switch (or switches) and from the CallCoordinator CMCT. It writes the call records and error messages to a CICS user journal called the MIS log.
Refer to the chapter "What Call Management Does" in the CallPath CallCoordinator/CICS General Information for a detailed description of the Data Collection for Reports Feature of CallCoordinator.
The MIS data collected by CallCoordinator and put on the MIS Log includes the following data types:
For easier sorting and correlating, these record types all begin with a record header and a common data section. The complete formats for each record type are described in the following sections. A layout is provided in the CallCoordinator SEZPCOPY target library, member name CAMR002.
A processed event record contains data for a call that was processed normally by the CallCoordinator Call Tracking Manager. It has common and message-related sections and a section for the attributes of the call. This is followed by data for up to three parties:
If there are more than three parties (perhaps because a conference call ended), the additional parties are written in continuation records which repeat the record header, the common data, the message-related data, and the call-related data. The record format for this record type is shown in Table 36. Refer to the library member for the actual field names.
These records are written after a processed event record. They contain data for the additional parties that changed state as a result of the event record. The first continuation record contains the data for the fourth, fifth, and sixth parties. The second one contains data for seventh, eighth, and ninth parties, and so on. The record format for this record type is shown in Table 37. Refer to the library member for the actual field names.
A non-processed event record results when a message did not contain enough information for Call Tracking Manager (CTM) to process or when the message referenced one or more calls that were not in the current CMCT.
If a disconnected message is sent for a call that is not current, the party data is written in a non-processed record. No error message is written. Other non-processed records are accompanied by error records that give the reason for the failure. The record format for this record type is shown in Table 38. Refer to the library member for the actual field names.
The call-combining record is written when telephony action results in adding parties from one unit of work into another unit of work. These records allow the replacement of the unit of work fields in the added call so that the records will sort together when processed. The date and time from host are set to zero so that the record will be found before the records for which unit of work is to be changed. The record format for this record type is shown in Table 39. Refer to the library member for the actual field names.
Error records sent to the MIS Log indicate problems in the processing of event data. They are written near the messages that caused them. To help in problem determination, they can be sorted with call-related records. The record format for this record type is shown in Table 40. Refer to the library member for the actual field names.
The status change record reflects a notification from CallPath/CICS that the status of a switch link, or the CallPath/CICS Subsystem itself, has changed. The record format for this record type is shown in Table 41. Refer to the library member for the actual field names.
The account code record is produced when CallCoordinator receives a message that contains data entered by an agent through his telephone. If the agent is involved with a call at the time of the data entry, the call-related sections of the MIS record will reference the most recent call with a call purpose of service.
If the agent is not involved with a call, the alphabetic fields of the call-related data are set to spaces and the numeric fields to zeros. In the common data section, the following fields are set to spaces:
In the common data section, the Application connect index field is set to zeros. The record format for this record type is shown in Table 42. Refer to the library member for the actual field names.
You can customize the writing of records to the MIS log by writing your own version of the MIS Interface Manager and using the MIS Log exit. Your customized program can reformat, edit, filter, or delete call records.
The reasons for customizing this process include:
To write and use your own version of the MIS Interface Manager, do the following:
To ensure the integrity of the data do not change the fields of this interface or their attributes.
Table 35. CICS Communication Data Area between the Interface Manager and
MIS logging options are available. These options control the logging of and access to the CallPath/CICS messages being received from the switch and CallCoordinator's call tracking component.
These options are specified under MIS Log in the COR Telephony Settings panel (VA32). On this panel, there are three fields. They are:
MIS Option.
Exit Name.
User Journal ID.
The 'User Journal ID' field is the CICS User Journal to which the the MIS records are written if the MIS option is set to 'J'.
+----------End of Product-sensitive programming interface information----------+
