Implementation Release BT/OLO Interface Technical Specification Interim Carrier Pre-Select Interim Carrier Pre-Select BT/OLO Interface Technical Specification Version 2.16 Electronic Location: Not Posted at This Time. Ref: ICPS ITS – 2.16 TRIAL VERSION 1 Authored by: Yves Orton/Rich Morgan Authorised by: ICPS Automation Group 15-07-2001 page 1 of 24 Implementation Release BT/OLO Interface Technical Specification Interim Carrier Pre-Select Table of Contents 1. Design Intentions ....................................................................................................................................... 4 2. Transport Mechanism ................................................................................................................................ 4 2.1. Security and Authentication ...................................................................................................................... 4 2.1.1. Authentication and Permitted Users ...................................................................................................... 4 2.1.2. Checksums............................................................................................................................................ 5 2.2. Delivery Times and Quotas ...................................................................................................................... 5 2.3. Receipts ................................................................................................................................................... 5 3. Interface Structure ..................................................................................................................................... 6 4. The Message ............................................................................................................................................. 6 4.1. Message Identifiers .................................................................................................................................. 6 4.1.1. Reserved Message Identifiers. .............................................................................................................. 7 4.2. Validation.................................................................................................................................................. 7 5. The File ..................................................................................................................................................... 7 5.1. Filename Specification ............................................................................................................................. 7 5.1.1. File Classes ........................................................................................................................................... 8 5.1.2. File Types .............................................................................................................................................. 8 5.1.2.1 “Semantic” Validation Request File ...................................................................................................... 8 5.1.2.2 “Semantic” Validation Request Response File ..................................................................................... 8 5.1.2.3 Error Files ............................................................................................................................................ 9 5.2. File Validation ........................................................................................................................................... 9 5.3. Well-Formed Files .................................................................................................................................... 9 6. The Record.............................................................................................................................................. 10 6.1. Well-Formed Records ............................................................................................................................. 10 6.2. “Grammatically” Valid Records ............................................................................................................... 10 6.3. Record Type Codes ................................................................................................................................ 11 7. Record Specification................................................................................................................................ 11 7.1. End of Record Marker............................................................................................................................. 11 7.2. Data Type Specification .......................................................................................................................... 12 7.3. (H) Header Record Format ..................................................................................................................... 13 7.4. (T) Trailer (Footer) Record Format .......................................................................................................... 13 7.5. (N) New Validation Request Record ....................................................................................................... 14 7.6. (N) New Validation Response Record..................................................................................................... 14 7.7. (S) Serial Change Validation Request Record ........................................................................................ 15 7.8. (S) Change Serial Validation Response Record ..................................................................................... 15 7.9. (E) Error Record ..................................................................................................................................... 16 8. Sequence Numbers ................................................................................................................................. 16 9. Error System ........................................................................................................................................... 16 9.1. Validation................................................................................................................................................ 16 9.2. Error and Response (Reject Reason) Codes .......................................................................................... 17 9.2.1. 9.2.2. Error Code Specification ...................................................................................................................... 17 Response (Reject Reason) Codes ....................................................................................................... 18 9.3. Message Level Errors ............................................................................................................................. 18 9.4. File Level Errors ..................................................................................................................................... 19 9.4.1. 9.4.2. Fatal Errors (Well-Formedness Error) .................................................................................................. 19 Non-Fatal Errors (Grammatically Invalid Records) ............................................................................... 19 10. Example Validation Request and Response Files.................................................................................... 20 11. Example of Poorly Formed Request and Error Files ................................................................................ 20 12. Example of Grammatically Invalid Request and Error Files ..................................................................... 21 Ref: ICPS ITS – 2.16 TRIAL VERSION 1 Authored by: Yves Orton/Rich Morgan Authorised by: ICPS Automation Group 15-07-2001 page 2 of 24 Implementation Release BT/OLO Interface Technical Specification Interim Carrier Pre-Select List of Tables Table 4-A Message Identifiers ................................................................................................................................ 6 Table 4-B Rules for Validating Messages ............................................................................................................... 7 Table 5-A Filename Specifications.......................................................................................................................... 7 Table 5-B Validation Request File Details ............................................................................................................... 8 Table 5-C Validation Request Response File Details .............................................................................................. 8 Table 5-D Error File Details .................................................................................................................................... 9 Table 5-E Rules for a Well-Formed File .................................................................................................................. 9 Table 6-A Rules for a Well-Formed Record .......................................................................................................... 10 Table 6-B Rules for Validating a Record ............................................................................................................... 10 Table 6-C Record Type Codes ............................................................................................................................. 11 Table 7-A Terms used to Define Records ............................................................................................................. 11 Table 7-B Field Type Specifications ...................................................................................................................... 12 Table 7-C Header Record Specification ................................................................................................................ 13 Table 7-D Footer Record Specification ................................................................................................................. 13 Table 7-E Validation Record Specification ............................................................................................................ 14 Table 7-F New Record Validation Response......................................................................................................... 14 Table 7-G Change Serial Number Validation Request Record .............................................................................. 15 Table 7-H Change Serial Validation Response ..................................................................................................... 15 Table 7-I Error Record .......................................................................................................................................... 16 Table 9-A Error Code Specifcation ....................................................................................................................... 17 Table 9-B Response Code Specification ............................................................................................................... 18 Table 10-A Sample "Good" Validation Request File............................................................................................... 20 Table 10-B Sample of a Validation Response File ................................................................................................. 20 Table 11-A Sample Poorly Formed File ................................................................................................................ 20 Table 11-B Error response to a Poorly Formed File .............................................................................................. 20 Table 12-A Grammatically Invalid Request File .................................................................................................... 21 Table 12-B Error File Example .............................................................................................................................. 21 Introduction This is the implementation release of the specification of how BT and the OLO’s will exchange data regarding the ICPS product. It is derived from two previously released specifications: BT Change Request Response -- Interim Carrier Pre-Selection: File Transfer v1.1 dated 2000/06/23, authored by Sally Brinkley. (BTRESPONSE) NCS Auditor Functional Specification v1.2 dated 2000/05/12, author Unknown. (AFS) Ref: ICPS ITS – 2.16 TRIAL VERSION 1 Authored by: Yves Orton/Rich Morgan Authorised by: ICPS Automation Group 15-07-2001 page 3 of 24 Implementation Release BT/OLO Interface Technical Specification Interim Carrier Pre-Select 1. Design Intentions The primary design intentions for this specification are as follows: 1. Easy to implement by hand using spreadsheet style software capable of saving CSV (comma separated value) files, as well as components that can interface with commonly used business/office software. 2. Easy and Inexpensive to implement using off-the-shelf code modules and development tools. Open Source modules would satisfy these requirements. 3. To conform as closely as possible to AFS and BTRESPONSE where this does not contradict the objectives above. 2. Transport Mechanism Electronic mail (SMTP email) has been proposed as the transport mechanism for this interface. While using a non point-to-point transport layer presents problems it is felt that other characteristics, such as ease of implementation, of this type of solution outweigh the drawbacks, and that as long as these drawbacks are recognised they can be neutralised. In the following subsections the issues that may arise and the methods of resolving such issues are detailed. 2.1. Security and Authentication Security represents one of the primary issues of using email as a transport mechanism. Email communications are easily forged and intercepted, and therefore a strategy is needed to eliminate such possibilities. The means to resolve the bulk of security issues is through the use of a digital message signature/digest. This signature serves a dual purpose, that of making it difficult to forge an email, and of preventing a signed email from being considered valid after being modified in transit either deliberately by a hostile party or inadvertently by line noise or some other form of corruption. A number of solutions are available off-the-shelf to facilitate this signature mechanism, all of which use S/MIME (the standard file attachment system used in email) as their carrier mechanism. BT proposed to use the BT Trustwise system which is a reseller of the Verisign system. These systems are obviously compatible, and also compatible with such software as OpenSSL. The Industry therefore agrees with BT that these tools provide the functionality necessary for this interface, and will support its use. The specific s/mime name of the message digest protocol that to be used is x-pkcs7signature, MD5 will be the ‘Hash Algorithm’ setting for this protocol. All parties using this interface must obtain an authentication certificate from an independent certificate authority. Trustwise or Verisign are examples of such companies. These certificates are specific to the email addresses involved so should there be a change of address for any party up-to date certificates must be obtained by said parties. It is a requirement that all parties involved with ICPS that use email (BT, NCS, OLOs’ and OLO Resellers) must use Digital Signatures on the email address used. Caution It should be understood that the use of a message digest does not prevent hostile interception of sensitive commercial data being transferred by this system. 2.1.1. Authentication and Permitted Users Digital message digests only enable a receiver to ensure that the mail received was from whom it says it is from, and that it has not been tampered with en-route. It does not Ref: ICPS ITS – 2.16 TRIAL VERSION 1 Authored by: Yves Orton/Rich Morgan Authorised by: ICPS Automation Group 15-07-2001 page 4 of 24 Implementation Release BT/OLO Interface Technical Specification Interim Carrier Pre-Select determine if the mail was sent by a party permitted to participate in ICPS. BT and the OLO’s must ensure that the sending party is a permitted user of the system. 2.1.2. Checksums The use of a digital message digest removes the need for file level checksums and therefore the checksums could be removed from the footer records of the file format. However, in order to minimize changes by those that have already implemented the original specifications these have not been removed, instead they have been disabled, and the field where they should go now must contain a mandatory eight zeros.(‘00000000’) 2.2. Delivery Times and Quotas Caution This section is currently out of synch with agreements made in the industry meetings. A formal clarification of the quota rules is required from the Industry Meetings. 1. BT committed (BTRESPONSE) to accept emails Monday to Friday up to 8pm (note that start time was not specified). 2. BT also committed to make reasonable endeavours to return receipts or authentication error messages within one hour. BT wishes to make it clear that it cannot be held responsible for late delivery of receipts due to Internet failure. 3. BT commits to process files in queue within 22 working days. 4. Only files that are semantically valid will count towards any sort of quota, should a quota be contractually agreed. 5. Should quotas be contractually agreed then it has been agreed that it will be the OLO’s responsibility to not exceed whatever levels are determined. There is no way to guarantee the delivery time of an email by any party involved in this project. This may have an effect on such issues like daily quotas. The primary risk is the “snow-ball” scenario where an email is inadvertently delayed enroute to BT, causing it arrive later than the cut-off time, and consequently not be processed until the next day. The processing of this delayed email then uses that days quota, causing the email sent on that day to be cached and processed the day after, which then of course uses that days quota. Ad infinitum. It has been agreed that this scenario is to be avoided by BT maintaining a queue of mails, and processing them in order. BT has committed to provide a delivery receipt within one hour irrespective of the status of the queue. (See point 2 above) 2.3. Receipts Receipts will be sent by receiving parties within one hour. The format of the receipts (in terms of message identifier) is specified in the message identifier table. (Table 4-A) This will occur irrelevant to whether the message identifier is a duplicate as the duplicate may have been sent because the prior receipt failed to arrive at its destination. Receipts have three types, a positive receipt, indicating that a message and file have been received and are well formed, and lastly a negative receipt indicating that the message was not satisfactorily authenticated. Receipts should contain the mail headers from the mail they are a receipt for in their text section. While this is not required by this specification, doing so will provide data necessary to resolve potential disputes, especially where Internet delays result in contractual deadlines being breached. Ref: ICPS ITS – 2.16 TRIAL VERSION 1 Authored by: Yves Orton/Rich Morgan Authorised by: ICPS Automation Group 15-07-2001 page 5 of 24 Implementation Release BT/OLO Interface Technical Specification Interim Carrier Pre-Select As it is not an error to send a message multiple times (the duplicates will be ignored) it is suggested that the various parties implement some kind of timeout mechanism that causes the retransmission of the message. The type of implementation to accomplish this goal is at the various parties’ discretion, however it is suggested that such a time-out does not occur until significantly after the 1 hour receipt time line. 3. Interface Structure The basic level of communication is the email or message. A message can contain one and only one attached files. Each file will contain at minimum two different types of record, a header and a footer, with various data records as well. The types of data records that are allowed in a file are determined by the file type. For instance an Error File may only contain one header record, zero to many ‘E’ records, and one footer record, and nothing else. The sections that follow outline the different layers of the interface and the role that they play. Errors that will be generated by the various layers are specified in Section 9 Error Subsystem. 4. The Message As mentioned in section 2, the transport layer of the interface is to be SMTP using S/MIME. In simpler terms this means email with authentication and checksums. Messages will have their own validation, in addition to their own means of unique identification. Emails that arrive that duplicate the identifier of a previously received message should be ignored, and should not generate an error response. 4.1. Message Identifiers Email messages will possess a unique identifier in the subject line. The format of this identifier is specified below, along with various other details about the message flow. Type of Mail Unsolicited Outgoing Email From OLO Receipt from BT. Email Failed Authentication Receipt from BT. Email Valid and Quedued. Error Response to OLO’s Email By BT Response to OLO’s Email By BT Receipt from OLO. Failed Authentication Receipt from OLO. Email Valid. (ACK) Format [MESSG:ooo-nnnnnnnn] [M-INV:ooo-nnnnnnnn] [M-REC:ooo-nnnnnnnn] [REPLY:ooo-NNNNNNNN] [REPLY:ooo-NNNNNNNN] [R-INV:ooo-NNNNNNNN] [R-REC:ooo-NNNNNNNN] OLO BT Timeframe File N/A VS 1 Hour of Receipt None 1 Hour of Receipt 22 Work Days 1 Hour of Receipt VE VR None Table 4-A Message Identifiers The letters ooo correspond to the OLO id of the company sending the original (unsolicited) email, and the nnnnnnnn and NNNNNNNN corresponds to different eight-digit sequence numbers. (In other words the MESSG and REPLY need not have the same sequence number, but the MESSG and M-INV or M-REC sequence numbers must be the same, likewise with REPLY and R-INV and R-REC.) The text, colon, square brackets and hyphens (‘:’, ‘[‘, ‘]’ and ‘-‘) are required. The sequence number is intended to proceed in order from 000001, but emails may arrive out of sequence. Ref: ICPS ITS – 2.16 TRIAL VERSION 1 Authored by: Yves Orton/Rich Morgan Authorised by: ICPS Automation Group 15-07-2001 page 6 of 24 Implementation Release BT/OLO Interface Technical Specification Interim Carrier Pre-Select 4.1.1. Reserved Message Identifiers. British Telecom has reserved the message identifiers from 99950000 to 99999999 for resending invalid messages. OLOs should be capable of receiving and responding to (ie sending receipts) for identifiers in this range, but should not use these numbers otherwise. 4.2. Validation Messages will be validated by ensuring that they follow the rules below Rule 1 2 3 4 Description Have a valid unique identifier. (Key is that the OLO id is appropriate.) Have been signed using a compatible and appropriate digital message digest. That the digital message digest indicates that the file has not been altered or corrupted in any way. Where a message is of a type that should contain a file (MESSG and REPLY) that it contains one and only one file, and that the file is of a legal file specification. See table 5-A for filename specifications. Table 4-B Rules for Validating Messages Emails that fail this validation will result in no further processing (including any attached files) and an error response (not file) being generated. See Section 4.1 for invalid message response specification. 5. The File The file is the carrier of the different types of data being transferred between the various parties. On a simple level a file contains a header and a footer record as well as zero to many data records. The data records may be of different types as specified for each particular type of file. 5.1. Filename Specification Files may be broken into different classes. Send, Receive and Error. As there is only one file type, validation request, there are three different files which are listed below. File Name Format Message Type File Type Number Sender Validation Request File VSnnnnnn.ooo MESSG 4 OLO Validation Response File VRnnnnnn.ooo 7 BT 9 BT Type of File Validation Request Error File VEnnnnnn.ooo REPLY Table 5-A Filename Specifications The letters nnnnnn refer to the sequence number of the file. The letters ooo refer to the OLO id of the company the files data refers to. (See Section 8 on sequence numbers) There is a one to one relationship between VS and VE sequence numbers, however there is no such relationship between VS and VR sequence numbers. This means that should a VS file contain errors then the VE error file that contains the error list encountered will have the same sequence number. However the responses to an error free VS file may come in several VR files, and accordingly these files will have different sequence numbers. An illustration follows below. If the file VS123456.123 contained errors the error file would be called Ref: ICPS ITS – 2.16 TRIAL VERSION 1 Authored by: Yves Orton/Rich Morgan Authorised by: ICPS Automation Group 15-07-2001 page 7 of 24 Implementation Release BT/OLO Interface Technical Specification Interim Carrier Pre-Select VE123456.123 But it did not then the reply, which in this case is contained in several messages and files, could be called VR123456.123, VR125000.123, VR126000.123 5.1.1. File Classes There are three classes of file, request (Send), Response and Error. A send file is used by the OLO to send data to B. Response files are used by BT to reply to a specific send file. Error files are used by both parties to inform their counterpart about errors in the files. Error files that are themselves in error should be dealt with by human contact with the offending party and do not generate error files themselves. (This is anticipated to be an uncommon situation.) 5.1.2. File Types There is only one file type, that of Validation. All other functionality has either been eliminated or is covered by this file. 5.1.2.1 “Semantic” Validation Request File This type of file is the primary carrier of the data. In fact it is proposed that this file subsume the functionality of the Change file. This can be easily accomplished by adding one field to the earlier spec, adding three new record types to the file, without changing the field structure of the records, except to make various fields NULL based on the record type. Filename: VSnnnnnn.olo Corresponding error file: VEnnnnnn.olo Has Header? Yes Has Footer? Yes Original Data Record Types: D New Data Record Types: N,C,S,O File Type Number 4 Table 5-B Validation Request File Details 5.1.2.2 “Semantic” Validation Request Response File This is the file that will be sent by BT in reply to a validation request by the OLO’s. It essentially contains a report per valid record in the request file of whether the request was correct or not, and if not an enumerated value specifying the reason it failed semantic validation. This file has been modified to enable to handle the new records provided by the enhanced validation request files. Filename: VRnnnnnn.olo Has Header? Yes Has Footer? Yes Original Data Record Type: D New Data Record Types: N,C,S,O File Type Number 7 Table 5-C Validation Request Response File Details Ref: ICPS ITS – 2.16 TRIAL VERSION 1 Authored by: Yves Orton/Rich Morgan Authorised by: ICPS Automation Group 15-07-2001 page 8 of 24 Implementation Release BT/OLO Interface Technical Specification Interim Carrier Pre-Select 5.1.2.3 Error Files These files contain one and only one record for every grammatically invalid record in their corresponding file. Every main file has a corresponding error file with a unique name format, but the internal contents of these files are the same. An error file may be for one and only one source file. Note Error files are the only files in the system that do not cause the generation of an error file. Should this occur some form of manual correspondence must be used to rectify the matter. This problem should be resolved during the testing process. Filename: VEnnnnnn.ooo Corresponding error file: None. Has Header? Yes Has Footer? Yes Data Record Types: E File Type Number None. Table 5-D Error File Details 5.2. File Validation For a file to be processed, or considered valid, it must be a well-formed file, the rules for which are specified in section 5.3. A file that is not well-formed will be rejected in entirety and a error file will be returned to its sender containing only one error record, indicating that the file is not well-formed, and the type of format infraction that occurred. A file that is well-formed, but contains grammatically invalid records will not have any records processed, instead an error file will be generated which will contain one error record for every invalid record that it contained. This reply is to made as quickly as possible after receipt. 5.3. Well-Formed Files A file will be considered well-formed as long as it complies with the following rules: Rule Description 1 Each file contains a header record as specified in section 7.3 2 Each file contains a footer record as specified in section 7.4 3 The data in the 2nd, 3rd and 4th fields of the header and footer match. 4 The number of records in the file corresponds with the number of records stated in the footer record. 5 Each record complies with rules of a well formed record (See Table 6-A) 6 (BT Only) That the file does not contain more records than are allowed under the quota regime. 7 The file identifier is not a duplicate. Table 5-E Rules for a Well-Formed File Ref: ICPS ITS – 2.16 TRIAL VERSION 1 Authored by: Yves Orton/Rich Morgan Authorised by: ICPS Automation Group 15-07-2001 page 9 of 24 Implementation Release BT/OLO Interface Technical Specification Interim Carrier Pre-Select 6. The Record The data being transferred by this interface ultimately resides in records. All records in a given file must be well formed for the file to be processed. Grammatically invalid records will generate a corresponding error record to be returned specifying the first validation rule (in no specific order) that they violated and cause the valid records to be ignored. 6.1. Well-Formed Records A well-formed record will comply with following rules (in no particular order) Rule Description 1 Be comma separated 2 Have a single letter identifier or Record Type Code for its first field, determining its type. This identifier must be a valid identifier for the type of file that the record is in. 3 Have a terminating field containing only a ‘#’ 4 Have the correct number of fields or field separators Table 6-A Rules for a Well-Formed Record 6.2. “Grammatically” Valid Records The use of the Term Valid records is made in this document in two different contexts. The first is that of Grammatical Validation (requiring no access to a DB)), and the second is Semantic Validation (necessitating access to a DB). This section specifies the rules for Grammatical Validation. Semantic Validation is covered under the section about Validation Response Records. A record will be considered valid if it complies with the following Rule Description 1 Each mandatory field contains a value. 2 Each field that contains a data value must be of the correct type 3 Each field that contains a data value must be of the correct format 4 Each field is no longer than the maximum length specified. 5 The data in each field must be within the prescribed range (including the validation of dates) Table 6-B Rules for Validating a Record Ref: ICPS ITS – 2.16 TRIAL VERSION 1 Authored by: Yves Orton/Rich Morgan Authorised by: ICPS Automation Group 15-07-2001 page 10 of 24 Implementation Release BT/OLO Interface Technical Specification Interim Carrier Pre-Select 6.3. Record Type Codes There are a number of different record types, some of which must exists in every file, some of which may only exist in certain types. Each record type has a specific one digit code letter by which it may be recognized. Record Type Code Record Type Description Specifying Section File types or classes that May or Must contain it H Header 7.3 All Must T Trailer 7.4 All Must N New validation 7.5 / 7.9 Validation Files May (V) S Change Serial Number 7.7 / 7.11 Validation Files May (V) E Error record 7.13 Error files Must (E) Table 6-C Record Type Codes 7. Record Specification In the following subsections each record type is exactly specified. The following terms are used to describe each records fields. Term Num Name Type Len Mand. Description Description This is the number of the field. Note that this is 1 based. The descriptive name that will be used when referring to a specific field in this document This is type for the specified field. Specification of the types in greater detail follows this list. The maximum size that a field may be. Whether the field may be NULL (empty) or not. This may be conditional on the record type code. Any comments about field, or in the case of an enumeration the legal values and their description Table 7-A Terms used to Define Records 7.1. End of Record Marker End of record markers will be considered to be their own field, and as such will be separated from the data by a comma. An example of how a record would look with this EOR marker would be N,0250000001,02/01/2001,02071234567,Y,N,ABCD0123,N,S,2,A,1,1,A,1,1,01/01/2001,,# Ref: ICPS ITS – 2.16 TRIAL VERSION 1 Authored by: Yves Orton/Rich Morgan Authorised by: ICPS Automation Group 15-07-2001 page 11 of 24 Implementation Release BT/OLO Interface Technical Specification Interim Carrier Pre-Select 7.2. Data Type Specification Each field must satisfy the requirements determined by its type. The following table specifies these types. Type Name Alpha Numeric (Num.) AlphaNum. Legal Characters Format Min Len Padding [A-Z, a-z, space (‘ ‘)] - - - [0-9] - - Right Optional [A-Z, a-z, 0-9, space] - - - Date [0-9, slash (‘/’)] DD/MM/YYYY 10 Number groups must be 0 left padded. DateTime [0-9, slash (‘/’), colon (‘:’), space (‘ ‘)] DD/MM/YYYY_HH:MM:SS 19 See Date above A-Enum [A-Z] - - None Bool. [Y,N] - - - N-Enum [0-9] - - None EOR [hash (‘#’)] # 1 None Specific (Spec.) - - - None NULL None - 0 None CHKSUM [0] 00000000 8 None Comments Min length is 1 if mandatory. Min Length is 1 if mandatory Min Length is 1 if mandatory DD is day of month, MM is number of the month with January being 01, YYYY is the current year common era. See Caution below. Underbar (‘_’) refers to a space. See Date above and caution below. Alphabetic enumeration. Legal values are specified in the description. Boolean. Y=Yes, N=No Numeric Enumeration. Legal values in the description. End of Record field. Only one legal value, specified in the description. This is a field that must be empty. Must be 8 zeros. Table 7-B Field Type Specifications Ref: ICPS ITS – 2.16 TRIAL VERSION 1 Authored by: Yves Orton/Rich Morgan Authorised by: ICPS Automation Group 15-07-2001 page 12 of 24 Implementation Release BT/OLO Interface Technical Specification Interim Carrier Pre-Select 7.3. (H) Header Record Format All files must contain a header as their first record. Num. Name Type Len 1 Record Type Spec. 1 Y 2 File Type Number N-Enum 2 Y 3 OLO Num. 3 Y Creation Date/Time EOR DateTime EOR 19 Y 1 Y 4 5 Mand Description, Values & Validation H = Header 4 = Validation Requests (VS File) 7 = Validation Response (VR File) 9 = Error File (VE File) 3-digit identifier of the OLO that the data relates to. The date and time that the file was created. # = End of Record Marker Table 7-C Header Record Specification 7.4. (T) Trailer (Footer) Record Format All files must contain a footer as their last record. Num. Type Len 1 Record Type Code Spec. 1 Y 2 File Type Number N-Enum 2 Y 3 OLO Num. 3 Y 4 Creation Date/Time DateTime 19 Y 5 Records Num. 10 Y CHKSUM 8 Y Must be ‘00000000’ EOR 1 Y # = End of Record Marker 6 7 NullChecksum EOR Mand Description, Values & Validation Name T = Trailer 4 = Validation Requests (VS File) 7 = Validation Response (VR File) 9 = Error File (VE File) 3-digit identifier of the OLO that the data relates to. The date and time that the file was created. Number of records including header and trailer. Table 7-D Footer Record Specification Ref: ICPS ITS – 2.16 TRIAL VERSION 1 Authored by: Yves Orton/Rich Morgan Authorised by: ICPS Automation Group 15-07-2001 page 13 of 24 Implementation Release BT/OLO Interface Technical Specification Interim Carrier Pre-Select 7.5. (N) New Validation Request Record This record is essentially the same as the older Validation File data record. The only modification has been the addition of a mandatory null field before the EOR marker. Num. Name Type Len 1 Record Type Code Spec. 1 Y 2 RefNo Num. 10 Y 3 Submit Date Date 10 Y 4 CLI Num. 11 Y Bool. 1 Y Bool. 1 N AlphaNum. 22 Y A-Enum 1 Y A-Enum 1 Y 5 6 7 8 9 Customer Informed Customer has ICPS Dialler Serial No Dialler Status Dialler Capacity Mand 10 Line Type N-Enum 1 Y 11 Line Service Type A-Enum 1 Y 12 Lines Num. 13 Lines Claimed Num. 4 Y 14 Service Config A-Enum 1 Y 15 ICPS Option N-Enum 1 Y 16 Auto Dialler type N-Enum 1 Y Date 10 Y NULL EOR 0 1 Y Y 17 18 19 Provision Date New Value EOR 4 Y Description, Values & Validation N = New request record First 3 chars are OLO-ID, last 7 chars are unique ID, suggest sequence in order The date that the transaction was submitted to the BT. Telephone number, starting with 01 or 02. Has customer been informed they have a dialler Dialler serial number. Free format, used by the OLOs N = New R = Refurbished S = Single Line/Chn/Ext M = Multi Line/Chn/Ext 1 = BT Retail Line 2 = Calls & Access F = Featureline. B = ISDN2 P = ISDN30. A = Analogue Number of lines, channels or extensions. Number of lines (or channels or extensions) claimed under ICPS. A = Single CLI/Single Line B = More Lines Than CLIs C = More CLIs Than Lines D = Multi Lines And Multi CLIs 1 = International. 2 = National 3 = All.4 = International & National 1 = Single. 2 = 4 line 3 = 8 line. 4 = 16 line 5 = ISDN2. 6 = ISDN30 The autodialler installation date. DD/MM/YYYY Empty. Used for other record types. # = End of Record Marker Table 7-E Validation Record Specification 7.6. (N) New Validation Response Record This type of record is used to reply to new validation requests Validation requests. Num. Field Name Type Len 1 2 Record Type RefNo Spec. Num. 1 10 Y Y 3 Submit Date Date 10 Y 4 CLI Date Validated Validation Results NULL NULL Response (Reject) Code EOR Num. 10-11 Y Date 10 Y A-Enum 1 Y NULL NULL 0 0 Y Y N-Enum 2 Y Legal Values are 0 to 8 Inclusive and 19. See section 9.2.2 EOR 1 Y # = EOR 5 6 7 8 9 10 Mand Description, Values & Validation N = New Record Response 1st 3 characters are OLO-ID BT Receipt date. DD/MM/YYYY Phone Num, starting with 01 or 02 BT validation date. DD/MM/YYYY V – Valid. I – Invalid Must be null Must be null Table 7-F New Record Validation Response Ref: ICPS ITS – 2.16 TRIAL VERSION 1 Authored by: Yves Orton/Rich Morgan Authorised by: ICPS Automation Group 15-07-2001 page 14 of 24 Implementation Release BT/OLO Interface Technical Specification Interim Carrier Pre-Select 7.7. (S) Serial Change Validation Request Record This record replaces the Change Serial Number Request Record. It is derived from the New Validation Request Record, with the fields that are not relevant to such a change being NULL (and marked in light grey.) The new serial number is to be contained in field 18. Num. Name Type 1 Record Type Code Spec. 1 Y 2 RefNo Num. 10 Y 3 Submit Date Date 10 Y 4 CLI Num. 11 Y 5 6 NULL NULL (Old)Dialler Serial No NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL New Dialer Serial No. EOR NULL NULL AlphaNum. NULL NULL NULL NULL NULL NULL NULL NULL NULL NULL AlphaNum. EOR 0 0 Y Y 22 Y 0 0 0 0 0 0 0 0 0 0 Y Y Y Y Y Y Y Y Y Y 22 Y 1 Y 7 8 9 10 11 12 13 14 15 16 17 18 19 Len Mand Description, Values & Validation S = Change Serial request record This value MUST match the RefNo of the original record. See same field in New Validation Request for description. The date that the transaction was submitted to the BT. DD/MM/YYYY The telephone number, starting with 01 or 02. Must be null Must be null The old dialler serial number. Free format, used by the OLOs Must be null Must be null Must be null Must be null Must be null Must be null Must be null Must be null Must be null Must be null The new dialler serial number. Free format, used by the OLOs # = End of Record Marker Table 7-G Change Serial Number Validation Request Record 7.8. (S) Change Serial Validation Response Record Num. Field Name Type Len 1 Record Type Spec. 1 Y 2 RefNo Num. 10 Y 3 Submit Date Date 10 Y 4 Old CLI Num. 10-11 Y Date 10 Y A-Enum 1 Y 22 Y 22 Y N-Enum 2 Y Legal values are 0, 16,17,18. See section 9.2.2 EOR 1 Y # = EOR 5 6 Date Validated Validation Results 7 Old Serial 8 New Serial 9 10 Response (Reject) Code EOR AlphaNum. AlphaNum. Mand Description, Values & Validation S = Change Serial Validation Response 1st 3 characters are OLO-ID BT Receipt date. DD/MM/YYYY Telephone number, starting with 01 or 02 BT validation date. DD/MM/YYYY V – Valid I – Invalid The old dialler serial number. Free format, used by the OLOs The old dialler serial number. Free format, used by the OLOs Table 7-H Change Serial Validation Response Ref: ICPS ITS – 2.16 TRIAL VERSION 1 Authored by: Yves Orton/Rich Morgan Authorised by: ICPS Automation Group 15-07-2001 page 15 of 24 Implementation Release BT/OLO Interface Technical Specification Interim Carrier Pre-Select 7.9. (E) Error Record Num Len Mand Record Type Original File Type Number Name Spec. 1 Y E = Error record N-Enum 2 Y 4 = Validation Requests (VS File) 7 = Validation Response (VR File) 3 Original OLO Num. 3 Y 3 digit identifier of the OLO that the data relates to. 4 Original Creation Date/Time DateTime 19 Y The date that the original file or files header record was created. 5 ErrorType N-Enum 2 Y 6 Line Num. 10 N 7 Element Num. 4 N 8 EOR EOR 1 Y 1 2 Type Description, Values & Validation Legal values are 0 to 4 and 16 to 21 inclusive. See section 9.2.1 The line number of where the error was encountered. Header record is line 1. The field number where the error was encountered. Field 1 is the RecordType identifier. # = End Of Record Table 7-I Error Record 8. Sequence Numbers This system specifies the use of two different type of sequence numbers, those used in the file naming convention (6 digits) and those used by the message identification system (8 digits). Considering that this project is intended as an interim measure it is not anticipated that the sequence numbers will overflow, and accordingly this document does not specify an means by which a reset of the sequence numbers may occur. 9. Error System The term ‘Validation’ and ‘Error Code’ have been used in many respects inside this and other documents that may give rise to ambiguities about these terms. The next two subsections attempt to resolve these ambiguities. 9.1. Validation The following list gives the order of when validation occurs (at least conceptually) along with an explanation of the nature of the validation. 1. Authentication or Message Level Validation Determines if the message come from who it says it does, has not been received before and if it has been corrupted, or if it is empty. 2. Well-Formedness Determines if the files in a message have been constructed correctly. That they have headers and footers, the number of records they say they have. That EORs are present and similer type checks. 3. Grammatical Validation This is validation that may be preformed without consulting a database to determine if the records are meaningful. It simply says that they are essentially correctly constructed. 4. Semantic Validation or Transaction Processing This is where records are interpreted with the use of a database. Ref: ICPS ITS – 2.16 TRIAL VERSION 1 Authored by: Yves Orton/Rich Morgan Authorised by: ICPS Automation Group 15-07-2001 page 16 of 24 Implementation Release BT/OLO Interface Technical Specification Interim Carrier Pre-Select 9.2. Error and Response (Reject Reason) Codes The term error code has been used in related documents about ICPS to refer both to actual errors and also to codes used to indicate the reason a validation request was rejected. This document uses the term error code only for the former, and reserves the term ‘Reject Reason’ for the later. Below are tables spelling out the error codes and reject reasons. 9.2.1. Error Code Specification Error codes are divided into Fatal and Non-Fatal errors. These refer to whether the error terminates the parse process immediately or not. Should a fatal error occur then it and only it shall be reported back to the sender. Multiple non-fatal errors, on the other hand, can occur in an error file. Gaps have been provided in the error codes to provide for future expansion should it be necessary. Error Code Description 0 Fatal Non-Well-Formed Error Codes (Codes 0 – 15) Missing Header and/or Footer. 1 Mismatching Header & Footer. 2 Incorrect Record Count. 3 Invalid Record Type Field 1 (Line supplied). 4 5 6 7 8-15 Missing EOR (Line supplied) Processing file would exceed weekly portion of quota. (Quota remaining in field 6 –- BT has tentatively agreed to this. Finally approval will follow) Processing file would exceed monthly quota. (Quota remaining in field 6 –- BT has tentatively agreed to this. Finally approval will follow) File rejected because it is a duplicate of an existing file. RESERVED FOR FUTURE USE Non-Fatal Validity Errors (16-99) 16 Invalid field Count (Line Supplied) 17 Missing Mandatory field. (Line and Element supplied). 18 Invalid data type or format (Line and Element supplied). 19 Field Must be NULL (Line and element supplied) 20 Data exceeds prescribed length (Line and Element supplied). 21 Data out of prescribed range (Line and Element supplied). 22-99 RESERVED FOR FUTURE USE Table 9-A Error Code Specifcation Ref: ICPS ITS – 2.16 TRIAL VERSION 1 Authored by: Yves Orton/Rich Morgan Authorised by: ICPS Automation Group 15-07-2001 page 17 of 24 Implementation Release BT/OLO Interface Technical Specification Interim Carrier Pre-Select 9.2.2. Response (Reject Reason) Codes There are three types of reject reason codes. The first is a valid transaction, which is a code 0. The second is codes specified for commercial reasons, as specified in ICPS Product Description v3. The third is for codes that are necessary for the technical workings of the interface. Gaps have been provided should new error codes be necessary. Response Code 0 Description Valid Transaction, Not Rejected. Commercial Invalid Transaction Rejection Codes (1-15) 1 2 3 4 5 Incompatible service. BT Social Telephony Customer (including Light User Scheme (LUS), Limited Outgoing Calling (LOC) and In Contact Customers Incorrect type of customer - BT Retail Access Customers or BT Calls & Access Customers (if the ICPSO has wrongly classified them - this is to ensure that the ICPSO has authority from the correct party) Incompatible Line Type – Featureline (VPN) customers, Incoming only lines (including Call Sign), and managed and public payphones (with the exception of renters coin boxes) Invalid due to change of customer number at same address (existing ICPS customer) Invalid Change of customer address with no change of customer number (existing ICPS Customer) 6 Exceeds Maximum permitted Operator Churn 7 Invalid because CLI has permanent CPS (PCPS in place before ICPS dialler installation date. Note: BT will not reject a validation request where the ICPS dialler was in place before PCPS). 8 Service out of date. (CPS National after 12/12) 9 Invalid number of lines claimed. The number of lines claimed for the detailed multiline dialler detailed is greater than the actual lines installed at the customers site. 10-15 RESERVED FOR FUTURE USE Technical Invalid Transaction Rejection Codes (16-99) 16 Rejected due to no record of reference number 17 Rejected due to no record of CLI 18 Reject Serial Number Change Validation Request record as no New Validation Request record with this Refnum received previously or old dialler does not match 19 Reject duplicate reference number in a New Validation Request record. 20-99 RESERVED FOR FUTURE USE Table 9-B Response Code Specification 9.3. Message Level Errors Message level errors are caused by a failure of the validation rules of a message. This includes such things as a corrupted email, or an email that fails the authentication check. In this situation a response is made by returning an email with the appropriate subject line identifier. (See the section on message identifiers.) For instance an email with the identifier [MESSG:123-01234567] Arrives at BT and fails the authentication check. BT would reply with an email with the identifier [M-INV:123-01234567] is sent informing the sending OLO that message 01234567 arrived corrupted. It is then up to the OLO to resolve the issue, ultimately by sending a new message with a new Ref: ICPS ITS – 2.16 TRIAL VERSION 1 Authored by: Yves Orton/Rich Morgan Authorised by: ICPS Automation Group 15-07-2001 page 18 of 24 Implementation Release BT/OLO Interface Technical Specification Interim Carrier Pre-Select identifier. Likewise in the case of an email arriving from BT that fails authentication checks the identifier of the response would be an R-INV. The contents of the email will be ignored so text intended for humans may be communicated if so desired. The very presence of an INV class email is all that is required to determine that an email arrived in an improper state. Section 4 for further details about the messages. 9.4. File Level Errors File level errors come in two flavours Fatal errors resulting from a non well formed file. Non-Fatal errors caused by grammatically invalid records inside of a well formed file. See Section 5 for further details of files and their errors. 9.4.1. Fatal Errors (Well-Formedness Error) Files that are not well formed will not be processed at all. Upon the first instance of a file being not well formed an error file containing only one error record, specifying the error encountered, will be generated and returned with the reply. See section 5.3 for the rules of a well formed file. 9.4.2. Non-Fatal Errors (Grammatically Invalid Records) Files containing Grammatically Invalid records will not be processed, however the error file generated will contain a list of all errors encountered. See section 5.2 for the rules of validation. Ref: ICPS ITS – 2.16 TRIAL VERSION 1 Authored by: Yves Orton/Rich Morgan Authorised by: ICPS Automation Group 15-07-2001 page 19 of 24 Implementation Release BT/OLO Interface Technical Specification Interim Carrier Pre-Select 10. Example Validation Request and Response Files This is an example of a Validation Request File. All lines are grammatically valid and the file is well formed. Message Identifier: File Name: [MESSG:025-00000001] VS000001.025 H,4,025,01/02/2001 00:00:00,# N,0250000001,02/01/2001,02071234567,Y,N,ABCD0123,N,S,2,A,1,1,A,1,1,01/01/2001,,# S,0250000005,02/01/2001,02073214569,,,DEF9876,,,,,,,,,,,POL4365,# N,0250000011,02/01/2001,02072345678,Y,N,ABCD0123,N,S,2,A,1,1,A,1,1,01/01/2001,,# S,0250000015,02/01/2001,02079874569,,,DDD9876,,,,,,,,,,,EEE4365,# T,4,025,01/02/2001 00:00:00,6,00000000,# Table 10-A Sample "Good" Validation Request File The response, also grammatically correct, would look like this: Message Identifier: File Name: [REPLY:025-00000001] VR000001.025 H,4,025,01/02/2001 00:00:00,# N,0250000001,01/02/2001,02071234567,01/02/2001,V,,,0,# S,0250000005,01/02/2001,02073214569,01/02/2001,V,DEF9876,POL4365,0,# N,0250000011,01/02/2001,02072345678,01/02/2001,I,,,1,# S,0250000015,01/02/2001,02079874569,01/02/2001,I,DDD9876,EEE4365,18,# T,4,025,01/02/2001 00:00:00,6,00000000,# Table 10-B Sample of a Validation Response File The first two data lines of the request are semantically valid, the second two (in italics) are not. The reject reasons are (in order), incompatible service and serial number does not match current. 11. Example of Poorly Formed Request and Error Files The following empty validation request would produce an error file because its header and footer don’t match. Message Identifier: File Name: [MESSG:025-00000666] VR000666.025 H,4,025,01/02/2001 00:00:00,# T,4,052,01/02/2001 00:00:00,0,00000000,# Table 11-A Sample Poorly Formed File Would result in Message Identifier: File Name: [REPLY:025-00000666] VS000666.025 H,4,025,01/04/2001 00:01:00,# E,4,025,01/04/2001,1,,,# T,4,025,01/02/2001 00:01:00,1,00000000,# Table 11-B Error response to a Poorly Formed File Ref: ICPS ITS – 2.16 TRIAL VERSION 1 Authored by: Yves Orton/Rich Morgan Authorised by: ICPS Automation Group 15-07-2001 page 20 of 24 Implementation Release BT/OLO Interface Technical Specification Interim Carrier Pre-Select 12. Example of Grammatically Invalid Request and Error Files The following file contains only invalid records (excluding header and footer) Message Identifier: File Name: [MESSG:025-00000002] VS000002.025 H,4,025,01/02/2001 00:00:00,# N,0250000002,02/01/2001,,Y,N,ABCD0123,N,S,2,A,1,1,A,1,1,01/01/2001,,# S,0250000006,2001/01/02,02074214569,,,D9B2E3F1,,,,,,,,,,,E9C7E4G9,# T,4,025,01/02/2001 00:00:00,4,00000000,# Table 12-A Grammatically Invalid Request File Which would result in the following error file Message Identifier: File Name: H,4,025,01/02/2001 E,4,025,01/02/2001 E,4,025,01/02/2001 F,4,025,01/02/2001 [REPLY:025-00000002] VE000002.025 20:00:00,# 00:00:00,17,2,4,# 00:00:00,18,3,3,# 00:00:00,4,00000000,# Table 12-B Error File Example These errors are: line 2 has a mandatory field (CLI) which is missing line 3 has a date in the wrong format, End Of Document Ref: ICPS ITS – 2.16 TRIAL VERSION 1 Authored by: Yves Orton/Rich Morgan Authorised by: ICPS Automation Group 15-07-2001 page 21 of 24 Implementation Release BT/OLO Interface Technical Specification Interim Carrier Pre-Select Revision Log Issue Date 1 Feb 2 1.1 Feb 4 1.2 12 Feb 2001 1.3 14 Feb 2001 1.31 16 Feb 2001 2.0 23 Feb 2001 2.01 26 Feb 2001 Ref: ICPS ITS – 2.16 TRIAL VERSION 1 Authored by: Yves Orton/Rich Morgan Authorised by: ICPS Automation Group Revisions Original Release (released as 0.1 Sorry.) Bug Fix (Also released as 0.1. Sorry.) Added 1. EOR field to error record. 2. Added Examples (sections 10,11,12) 3. Fixed Description of field 3 of Error Record Spec. 4. Fixed Record type of Footer record to match the agreed ‘T’ 5. Added ‘or format’ to description of ErrorCode 8 in Error Record 6. Cleaned up introduction 1. Removed references to RERR messages 2. Removed references to Cease/Halt files and responses. 3. Changed wording of Message level validation to authentication. 4. Removed incorrect “example goes here” 5. Added section 2.1.1 1. Made changes that were specified in the minutes of the 13-Feb 2000 Automation Meeting. Removed WCOM from the document ID in footer, swapped fields 3 and 4 in records defined in sections 7.9 and 7.11 Clarification changes as required by the 21-Feb-2001 Automation Meeting, including reworking section 4.1, and other request made by BT, also removed ‘dead’ sections and other minor clarification statements. Also: Resolved minor inconsistencies brought about by earlier changes. Added sections on Reject Reasons, and Error codes. Changed Reject Reason to mandatory max 2 char field, with success being indicated by a 0 instead of a null. Change from 1 char to 2 char was necessary due to volume of codes. Some sections have been renumbered with respect to previous editions due to the above changes. Fixed some minor errors in the examples. Authored Authorised Yves Orton R. Morgan Yves Orton D. Blagodzi Yves Orton D. Blagodzi Yves Orton D. Blagodzi Yves Orton D. Blagodzi Yves Orton D. Blagodzi Yves Orton D. Blagodzi 15-07-2001 page 22 of 24 Implementation Release BT/OLO Interface Technical Specification Interim Carrier Pre-Select Issue Date 2.10 27 Feb 2001 2.11 28 Feb 2001 2.12 10 April 2001 2.14 18 April 2001 Revisions Repaginated document, and compressed some table contents to prevent tables from spanning pages where possible and to get related record specifications on same pages. Made minor alterations as requested in Automation Meeting of 27 Feb, (Section 2.2 point 2, 2.3 para 1, 4.2 Rule 4, Table 5-A.) Also changed Featurenet to Featureline throughout document. Removed ‘Invalid CLI’ from response code 3 in section 9.2.2 Added new Error Code for operators exceeding weekly and/or monthly quotas. Added new response code for incorrect number of lines claimed for by an operator on a multi-line dialler Made modifications to Tables 4-A,5-A,9-A, Section 5.1.2.1, Section 5.1.2.2 To reflect minor clarifications and modifications from Automation, Trialist and Implementation Groups. Also minor error fixes in tables 12A,12B and 9-B. Removed A. Chaddha from enquiries list as he is no longer involved. Authored Authorised Yves Orton IT Automation Group Yves Orton IT Automation Group Richard Morgan IT Automation Group Yves Orton IT Automation Group Richard Morgan Following authorisatio n, this document is to be frozen until the end of the trial phase. Modified the tables of section 9.2.2 by clarifying description of Error Codes 18 and 19 2.15 3 May 2001 2.15 Trial 1.0 7 June 2001 2.16 15 July 2001 Ref: ICPS ITS – 2.16 TRIAL VERSION 1 Authored by: Yves Orton/Rich Morgan Authorised by: ICPS Automation Group Added a line in section 2.1 to state that all parties using email must have digital signatures Added error codes 6 and 7. Reworded error code 5. BT needs to decide if they will be providing their quota data in case of error. (They have tentatively agreed.) Added note regarding BT reserving a section of the sequence numbers. Added a caution to section 2.2 regarding the fact that the quota specification in that section is not what was agreed in the industry meeting and that a formal clarification is required. Update and Issue Official Version of this document Trialist Group. Yves Orton Richard Morgan THIS IS A TRIALIST VERSION. IT HAS ONLY BEEN AGREED WITHIN THE CONTEXT OF THE TRIALS. FURTHER APPROVAL WILL BE REQUIRED POST TRIAL. Live version of this document 15-07-2001 page 23 of 24 Implementation Release BT/OLO Interface Technical Specification Interim Carrier Pre-Select Document References Ref Num Document Title Author Comments BT Change Request Response -Interim Carrier PreSelection:File Transfer NCS Auditor Functional Specification v1.1 Sally Brinkley v1.2 Unknown. ICPS Product Description V3 Committee Contributors Name Yves Orton Position David Blagodzi S. Brinkley Software Developer De-Softdev Worldcom Project Manager (?) Energis Project Manager MIS Worldcom Worldcom British Telecom NCS Mark Ludolf Reg Taylor Richard Morgan Comments Consulted over a number of the proposed changes. Many parts of this doc are derived from her original document. Many parts of this doc are derived from their original document. Enquiries Name Richard Morgan Yves Orton Ref: ICPS ITS – 2.16 TRIAL VERSION 1 Authored by: Yves Orton/Rich Morgan Authorised by: ICPS Automation Group Phone +44 207 675 2054 +49 69 972 68 166 E-mail Richard.morgan@wcom.co.uk yves.orton@mciworldcom.de 15-07-2001 page 24 of 24