Consolidated CDR Request - colt.net … · Web viewThis document describes the necessary...

Cocom- Reseller Connect

FTP User Guide

France

Colt Cocom FTP User Guide FR 6.9 1/ 84

Document History Soft copies of this document are maintained under change control, but hard copies are not.

This may not be a printout of the latest version.

Revision history

Version Issue Date

Description of change from previous version

Distributed

5.0 Added section 3.4 VPN to advise Resellers to

refer to VPN reseller guide

Updated section 4.1 Table 2 CLI & CPS requests

– CLI/CPS requests can now be submitted for

active or inactive CLIs

5.3 02/03/2005 Updated with correct file naming for CDR file

Added Document History table

Updated field 4 of section C.2.7 – Request Job

File.

6.0 06/05/2005 - Updated to standard template

- Examples updated to latest request/response

formats

6.1 29/07/2005 Updated error messages, new brand

6.2 07/11/2005 Update Request Validation codes (E 1.2)

Change of CPS request (4.1 Table 1)

6.3 Add new description of Error Code in Table 27

Added in Table 1 that an error message will be

send for CPS-Requests if CLI activation request

is in progress

6.4 15/04/2009 Maintenance & Supported updated.

6.5 14/03/2012 Updated to reflect enhanced Cocom and

consolidated CDR feature

6.6 02/12/2013 Updated to reflect Reseller Connect with

Wholesale Line Rental

6.7 30/07/2015 Updated to reflect the France Regulatory impacts

on the unrated CDRs for calls to non-geographic


numbers.

6.8 03/02/2016 Updated to reflect Colt rebranding.

6.9 04/03/2017 Replaced VoIP Access with SIP Trunking and

change in the notification period for planned

maintenance work in section 5


ContentsINTRODUCTION......................................................................................................6

1 SERVICE OUTLINE..............................................................................................71.1 OUTLINE PROCESS.........................................................................................7

1.2 TECHNICAL INFRASTRUCTURE.........................................................................8

1.2.1 Overview...................................................................................................8

1.2.2 Directory Structure....................................................................................8

1.2.3 File Naming Standard.............................................................................11

2 SERVICE REQUESTS.......................................................................................122.1 OVERVIEW....................................................................................................12

2.2 REQUEST FILE PROCESSING.........................................................................14

2.3 VALIDATION RULES AND CHECKS..................................................................15

3 SERVICE RESPONSES....................................................................................173.1 COLT RESPONSES........................................................................................17

3.2 PTT RESPONSES..........................................................................................17

4 CDR FILES.........................................................................................................18

4.1 CONSOLIDATED CDR REQUEST....................................................................19

4.2 CONSOLIDATED CDR DOWNLOAD.................................................................21

4.3 CONSOLIDATED CDR FILE FORMAT...............................................................21

5 MAINTENANCE AND SUPPORT......................................................................22

6 TIPS, TRICKS & RULES...................................................................................23

7 GLOSSARY........................................................................................................24

APPENDIX A REQUEST FILE FORMATS...........................................................25

APPENDIX B RESPONSE FILES.........................................................................39

APPENDIX C FILE LEVEL ERRORS...................................................................60

APPENDIX D CDR FILE.......................................................................................63

APPENDIX E REFERENCE DATA........................................................................72

APPENDIX F RESELLER CONNECT WITH WLR................................................84

F.1 FILE NAME.........................................................................................................84

Colt Cocom FTP User Guide FR 6.8 of 84

F.2 CALL DETAIL RECORD FORMAT..........................................................................82

F.3 SAMPLE CALL DETAIL RECORD...........................................................................83


Introduction

Colt Technology Services (Colt) has provided you with an electronic interface for the

activation and deactivation of Colt Wholesale Products on your end-customer CLIs (Calling

Line Identifier) and for the daily transfer of call detail records (CDR). This system is referred

to as Cocom.

This interface allows you to submit individual and bulk requests to Colt, and in return allows

you to retrieve the results of your requests and to retrieve the CDRs resulting from your end-

customers’ traffic within the Colt network.

Cocom can also be used for Carrier Pre-Selection (CPS) requests on end-customer CLIs

that are already active within the Colt Network. The system will confirm that the CLI is known

to Colt before forwarding the request to the relevant PTT. The responses received from the

PTT will be processed and passed back to you.

This document describes the necessary technical details and the processes that allow you to

Set up your internal systems and processes

Successfully submit and retrieve requests

Successfully retrieve CDR files from Colt

The information specific to each country is defined in Appendices to this document.

Examples of this information are:

CLI and CPS requests

Action codes

Switch Profiles

PTT messages

Reseller Connect with WLRIf resellers are selling Reseller Connect with Wholesale Line Rental, then Colt will have

setup access to both Cocom and to the VGA portal. Resellers must use the VGA portal to

do all their end-customer activations & deactivations and to view the status of their

transactions for Wholesale Line Rental. Cocom must only be used to download unrated

CDRs. There is a separate VGA portal user guide which is available from the VGA portal –

please use your VGA portal login details and follow the instructions in your welcome letter.


1. Service Outline

1.1 Outline Process

The communications server itself is generally available except when Colt needs to carry out

essential housekeeping and maintenance work. So, you have considerable flexibility in

deciding how often you choose to upload and retrieve files.

There are three main activities that you will need to carry out on a regular basis. During a

typical session you will:

Upload a request file, followed by a matching job file

Retrieve response and any error files from previous upload sessions

And twice a day retrieve CDR files for processing within your own systems

Each of these activities is described in greater detail in later sections.

Resellers

VPN

Cocom

Colt network

Colt Billing Systems

Figure 1 - Colt Reseller support infrastructure


1.2 Technical Infrastructure

1.2.1 Overview

The Cocom server currently supports FTP access to dedicated and protected directories that

have been created specifically for your business. Additionally access via XML and a

graphical user interface is available.

Access to the server is via a dedicated VPN client, provided by Colt. These methods are

detailed in separate documents accompanying this guide. Colt will assign a temporary IP

address on successful access that will remain valid and available only for the duration of

your connection to the service.

When you connect with Colt, you will be prompted to enter two User IDs and passwords; the

first to gain access to Colt’s customer network, and the second to gain access to your home

directory on the Cocom server.

After you have successfully gained access to the server you will be connected to your home

directory. Your home directory has been created specifically for you and can only be

accessed using the User ID provided to you by Colt.

To use the service you will need to integrate these processes and file interface into your own

IT environment. For a stand-alone operation you can use a standard FTP client. Any of the

commonly available FTP clients should be satisfactory, for example ReflectionFTP.

1.2.2 Directory Structure

Files within this directory are protected from access by others in a secure environment. The

key directories in your home directory on the Cocom Server are shown in the diagram below.

From here you can download your unrated CDRs for existing Colt products which you resell

and across one or more Colt countries. You can also do Reseller Connect transactions – i.e.

place CLI activation / deactivation and CPS requests.


Figure 2 - Directory StructureDiagram notes

Note lower case values above

Reseller Domain ID is an auto-generated ID, a combination of your company name &

random digits, minimum length of 5 and max length of 8

Country code in ISO 2 character format, note ‘FR’ is used

The product will be one of the following - all lower case:-

reseller-connect

sip-trunking

voice-line

carrier-voip

ip-voice-line

in-for-resellers


/bin/cdr/cli_list/err_in/err_out/jobin/jobout/lib/request/response

a02

reseller-connect

fr

colt123

Profile

Product/

cdr/

/bin/cdr/cli_list/err_in/err_out/jobin/jobout/lib/request/response

Product

Country Code

Reseller Domain ID

The profile is up to 5 alphanumeric and is either the account profile or the service

profile

Account profiles are set up based on your billing account (BCN), whereas service profiles

are set up per service instance. Account profiles will apply to products such as SIP Trunking

and Voice Line, and service profiles will apply to Reseller Connect.

If you have more than one product on the same billing account (BCN), e.g. SIP Trunking &

Voice Line, then they will have the same account profile. The unrated CDR files will be

generated in separate files by product and made available under each product as per the

FTP folder structure above.

The files provided by Colt such as CDR files, and response files are available in separate

sub-directories in a standard format (detailed in the Appendices to this Guide):

/request the directory where you must upload your request files

/response the directory where Colt will deposit response files

/jobin the directory where you must upload job request files, one for each request file

/jobout the directory where Colt will deposit job files, one for each response file

/err_in this is the directory that will contain any error files

/cdr this directory will contain your CDR files, delivered twice daily as well as any

consolidated CDR files you have requested using the consolidated CDR request

feature in Cocom Web Manager

/cli_list at the end of each day, Colt will provide a report of your CLI activity for the day

and leave these in this directory for your collection

Table 1 – Sub directories description


1.2.3 File Naming Standard

Files transferred to and from Colt are all uniquely identified and adhere to the following

naming convention.

The file names will consist of three parts:

1. The first digits are assigned by Colt Technology Services (Colt) and will be your unique

identifier, which is up to 5 alphanumeric e.g. a02.

2. The next eight (8) digits are the file sequence number with leading zeros, for example

00000001. These must follow strictly in sequence for each request file submitted to Colt

and each response file will always match its corresponding request file.

3. A suffix separated by a dot that describes the type of the file

req- request file

rsp- response file

error- error files

cdr- CDR file

The corresponding job files have the additional suffix “job”.

For example a request from a new reseller with service profile a02 would be a pair of files:

a0200000001.req

a0200000001.req.job

The Colt response would be another pair of files:

a0200000001.rsp

a0200000001.rsp.job


2Service Requests

2.1 Overview

Colt allows service activation, and deactivation requests for Resellers’ end-customers CLIs

on the Colt network and optionally, for Carrier Pre-Selection (CPS) service through the local

PTT. Colt also allows you to request the transfer of an existing CLI to you from another

reseller, through a Modify request, but this feature is restricted and available only on special

request.

At any time you may be required to provide written proof that the end-customer has signed

up for service with you. This may be to verify that the end-customer has consented to

transfer their service to you, or may be as a result of a demand from the local PTT to verify

that a CPS request is valid. If this is required you will be contacted by Colt directly.

You can request service to be activated or deactivated for a given CLI,

on the Colt network only (CLI only),

on the Colt network with CPS enabled (CPS or CLI/CPS)


Please Note: If you have been setup with a new service profile for Reseller Connect with

Wholesale Line Rental and wish to add Wholesale Line Rental to an existing end-customer

who already has Carrier Pre-selection with Colt, please do the Wholesale Line Retnal

transaction in the VGA portal only and the end-customer’s CLI will be automatically

modified across to your new service profile in Cocom.

Activate DeactivateCLI CLI must not be active Only if the CLI is already active

CPS CLI may be inactive or active

If the CLI is active – no warning

message given but CPS request is

processed

If the CLI is inactive – CLI is

activated on the Switch then the

CPS is processed

If activation process for CLI is in

progress – warning message will be

send

Only if CPS is already active on the

CLI.

And only if permitted by PTT (e.g.

some PTTs will only accept CPS

deactivation requests directly from

the end-customer)

CLI & CPS Combined (obsolete)

CLI may be inactive or active

If the CLI is active – warning

message given but CPS request is

processed

If the CLI is inactive – CLI is

activated on the Switch then the

CPS is processed

Not Permitted.

You need to deactivate CPS first,

and then submit another request to

deactivate the CLI after the CPS has

been deactivated.

Table 2 - CLI and CPS Request Rules

You can include up to 500 individual requests in a single file, and the file must be uniquely

identified (see 1.2.3 File Naming Standard for the File Naming Specification). Each request

file must also be accompanied by a Job File, and it is the Job File that triggers processing of

the Request file by Colt.

The normal sequence of events is as follows:

1) You will upload a request file

2) Followed by uploading the corresponding job file

3) Colt detects the job file and automatically looks for the corresponding request file.

If no request file is found then the system generates an error.

It is very important that the request file is uploaded BEFORE its corresponding Job file. If

you upload a Job file first then the system will start to search for the request file, and will


continue to look for up to 90 seconds. If it cannot find the file, or more likely it cannot read

the file because it cannot get exclusive access to it, the server will create an error response.

The request file will then be ignored by the system.

Colt will check the request file, and carry some basic validation (detailed in Section 2.3

below)

Carry out the request within the Colt network, and return the result

If the file contains a CPS request, then Colt will activate the CLI and forward the request

to the local PTT. In the case the CLI is already active and no error occurs no message

will be send. If the CLI is not active an acknowledgement will be send.

If the file contains combined CLI/CPS requests then Colt will generate an

acknowledgement for the CLI element and forward the request to the local PTT for the

CPS element, if the CLI request is successful.

The local PTT (incumbent Network Operator) normally has a fixed period of time to process

a CPS request, typically between 5 and 10 working days. Their response to the request will

be sent at any time in the period from your submission, up to the time limit. When Colt

receives these responses they are returned directly to you via the response directory within

your home directory on the Colt server.

2.2 Request File Processing

Colt carries out some basic validation of requests and request files before accepting them for

processing. The rules are simple and are as follows:

Each file pair, Job and Request file, must conform to the naming standard, detailed in

Appendix A.

Each request file must be numbered sequentially, starting at 1. The file will be rejected if

it has a sequence number that is lower or the same or more than 1 higher than the last

file submitted.

Each file must contain no more than 500 records excluding the file Header and Trailer

records.

If several requests should be send it is strongly recommended to put not more than one file

every 1-2 minutes in the jobin resp. /request Directory, to avoid rejections from the system.


The CLI within each request record must comply with your National standard, detailed in

Appendix A. The CLI and CPS requests must comply as per Appendix A (Request File

Formats)

If the validation is passed successfully then each CLI request will be sent to the Colt

network, and where appropriate to the local PTT.

The technical detail for Request File layouts and examples are given in Appendix A.

For each CLI and CPS request, Colt expects an ‘action code’ to be provided. This indicates

whether you want the CLI to be activated, deactivated, etc. The valid codes are defined in

Appendix A together with the Request File Format definition.

2.3 Validation Rules and Checks

As indicated above, Colt will carry out basic validation at two levels on each request file

received.

First LevelFirst, there are a series of checks to confirm that the request file is in the correct format and

is complete. To pass this level of validation the file must:

Conform to the Colt file naming standard (1.2.3)

The file sequence number must follow in sequence and be only 1 higher than the last file

successfully submitted

There must be a matching pair of request and job files

Have one and only one Header record, one or more Detail records and one and only one

Trailer record

The Header, Detail and Trailer records must be in the specified format (See also

Appendix A)

There must be no more than 500 Detail records in the file.

There should be only one CLI or CPS request for each Detail record.

If the file is incorrect or fails at this stage, a single error file (with a suffix of ‘.error’) is

generated and left in your \err_in directory (see also Appendix C File Level Errors).

This file will contain a Header record, a single detail record containing an error message as

per Table 28 - File Level Errors above, and a Trailer record. The technical detail for file level

error notifications is in Appendix C File Level Errors.


The original request and job file are renamed with an extra “.failed” at the end and left in their

original directory. The Resellers should correct as appropriate and

Either rename the original files removing the “.failed” extension (the request 1st then the

job);

Or create new files

Note that if a file fails file-level validation, the SAME file sequence number should be used, because the system does not move the file sequence counter in the case of file

error.

Second LevelAfter file-level validation the file will be processed and it will be validated to ensure that the

requests are valid. This may result in further error or warning messages, which are notified in

the Response file. There will be one Response file containing one line for each request

record within the corresponding Request File. Appendix B.1 CLI Responses gives the

technical detail of the CLI Response file. Appendix B.4 CPS Response File contains the

technical detail on the CPS Response file.

Some examples what will be checked are

The request action codes must be valid (A.3 Reference Data)

The date needs to be in the right format (See also Appendix A)

Country specific information in a CPS-Request is existing and in the right format (See

also Appendix A)

The possible error messages in the Response file can be found in E.1.2 Request Validation

Codes

Note that each Job File Detail record must end with the value

CLI – to indicate that this is a CLI only request

CPS – to indicate that this is a CPS request

CLI/CPS – indicating that this is a combined request

If any detail record ends with any other value, Colt will attempt to process the record as if it

was a CLI only request. If it is not a CLI only request then it will fail and the appropriate error

will be generated.

Finally, for CPS and combined CLI/CPS requests, if the previous stages were successful the

request will be forwarded to the local PTT. They will respond with the result of the request,

typically within 5 to 10 working days.


3Service Responses

3.1 Colt Responses

For each request made, a response will be created by Colt. For CPS requests this will be the

response that Colt receives from the local PTT. There will be one Response file for each CLI

Request file submitted and a separate response file for each CPS request.

For example,

If a CLI request file contained

150 CLI activation requests,

25 CLI deactivation requests

Then there will be one response file containing 175 lines (CLI requests)

If a CPS request file contains 225 CPS activation requests there will be 225 separate

response files; one for each CPS activation.

The technical detail for the CLI Response File layouts and examples are given in B.1 CLI

Responses.

The technical detail for the CPS Response File layouts and examples are given in B.5 CPSResponse File

3.2 PTT Responses

For each response from the local PTT, there will be a status code and a response code. This

information will be included in the Colt Response File for CPS requests.

The potential status and response codes that may be returned as a result of a CPS request

are given in E.2 PTT Reference Data.


4CDR Files

Twice a day, every day of the week, Colt will deposit a file of Call Detail Records (CDR) into

your /cdr directory on the server. This will contain all of the CDRs collected by the Colt

network since the last file, typically each 12 hours. The CDR files are provided in a pre-

defined, fixed length format. CDR file format description has been detailed in Appendix D.

CDR file naming standard

Files transferred to and from Colt are all uniquely identified and adhere to the following file

format

<countrycode>_<profile>_<productidentifier>_<sequence no>_<date>.cdr.gz

Where:

<countrycode> in ISO 2 character format, note FR to be used

<profile> is up to 5 alphanumerics and is the applicable profile for the product

<productidentifier> is the product identifier (1-2 alphanumerics) – see table below

<sequence no> is a rolling four digit sequence per <profile>_<product> combination

<date> is YYYYMMDDHHmmss

cdr.gz is where the file is zipped

Product Identifier Product name

01 Reseller Connect

00 Voice Line

10 SIP Trunking

11 IP Voice Line

12 IN for Resellers

13 Carrier VoIP


Please Note: The first CDR file will appear in Cocom FTP after the first call has been made.

4.1 Consolidated CDR Request

This feature enables you to place a request for a consolidated CDR file through Cocom Web

Manager, accessed via Colt Online. Up to 90 days of CDRs can be requested, e.g. a

consolidated file of a week's worth of CDRs and these files will be delivered to both Cocom

Web Manager & Cocom FTP.

In Cocom Web Manager, click on “CDR” and on the left side of the screen select

“Consolidated CDR Request”. Search for the specific Profile.

Figure 3: Consolidated CDR request - Select profile


1 2

Please Note: When you wish to consolidate unrated CDRs, these CDRs will be delivered

to Cocom Web Manager & FTP in a compressed/zipped format. If your twice daily CDR

files are already over 5MB in size, then please allow time to download a consolidated file

from Cocom Web Manager or you may find it easier to download files greater than 5MB

directly from Cocom FTP.

1

2

Figure 4: Consolidated CDR Request

Select Start (From) and End (To) date by clicking on the calendar Symbol and

choose the preferred date. Click on the Button “Consolidate CDR”

Your Consolidated CDR request will be processed. A transaction ID will be displayed to

the user, along with a message “You can download your consolidated CDR file “

<profile><transactionID>.cdr.zip” within the next 2 hours from under Cocom Web Manager

and/or from Cocom FTP”.

Figure 5: Consolidated CDR Request: Transaction Result


3 4 5

6

5

6

3 4

4.2 Consolidated CDR Download

Within 2 hours the consolidated CDR file will be available in the Cocom FTP /cdr file under

the product & profile which you used in your request.

4.3 Consolidated CDR File Format

. All Consolidated CDR files delivered to Cocom Web Manager and FTP have a filename in

the following format:-

<profile><transactionID>.cdr.zip.

Where:

<profile> is up to 5 alphanumeric and is the applicable profile for the product

<transactionID> is the combination of date and unique number, this can be used in Cocom Web Manager to search for Consolidated CDR

.cdr is the extension

.zip is where the file is zipped

Example: 8MU2011082402.cdr.zip

The content of the consolidated CDR file is the same as the standard twice daily delivered

CDRs, as described in Appendix D.

Unrated CDRs will be available for Reseller Connect with Wholesale Line Rental in the same

format as described in this section and in APPENDIX D. In addition France Telecom/Orange

will provide a separate file of Wholesale Line Rental unrated CDRs which can be found

under your service profile in Cocom. For more details please refer to APPENDIX F.


5Maintenance and Support

Customer Service is available during normal office hours, from Monday to Friday except

during Public Holidays.

Should we need to temporarily suspend access to the server, for planned maintenance, you

will be notified at least 10 days in advance and be told how long it will be suspended for.

Generally, this is an unusual occurrence (approximately once a month) and service

interruptions are brief.

While Colt may, from time to time, remove files that are more than 90 days old from the

server, it is your responsibility to ensure that files are collected and deleted from our servers

on a regular basis.


6 Tips, Tricks & Rules

How to avoid congestionIf several requests are to be sent, it is strongly recommended to put not more than one file

every 1-2 minutes in the jobin resp. /request Directory, to avoid rejections from the system.

There could be up to 500 records in one file. Fewer files with more records will be processed

faster than a lot of files with a low number of records.

If there is a need to send more than 5000 CLI/CPS (single records) in a short time frame (1-2

hours) please contact Customer Services before sending the requests to do this on an

agreed timeframe. Otherwise Colt reserves the right to delete mass requests which haven’t

been confirmed by Colt. Colt may suggest a dedicated timeframe to accept these mass

requests as part of a migration or database cleaning.

Unexpected messagesIf error messages are to be interpreted automatically, check the Response Code and Colt

Response Text. The Description Text may change and new error messages may be added.

Please ask Customer Services if you recognize new or different messages if a new Guide is

available.

Modify commandThe modify command is used to change the ownership of a CLI to the requesting reseller.

Rights to use the modify command is restricted and has to be requested separately. The

modify command will automatically include a CLI activation.

MiscellaneousIf you are using Cocom for different countries, please be aware that the syntax for the

different countries varies from country to country. Please ask your Customer Service

representative for the country-specific user guide.


7 Glossary

Term DescriptionCLI Calling Line Identifier. A term used within Colt to mean a customer telephone

number such as a Directory number.

Cocom Colt Communications server. The FTP server and internal applications that

provide a file level interface allowing resellers to request bulk activation and

deactivation of CLIs and CPS services.

CPS Carrier Pre-Selection.

CDR Call Detail Record. A record that contains the details of a call made on the Colt

network. Normally used for customer billing purposes. Typically this will be

unrated, i.e. contains no charges but indicates the service used during the call and

the tariff band(s) that apply. If the CDR is rated, then it will include the charge due

for the call.

PTT Public Telegraph Telephony [operator]. Any fixed-line network operator but

typically the major incumbent operator within the country. Colt deals with the

following operators: France Telecom (France), Deutsche Telekom (Germany),

British Telecom (UK), Telia (Sweden), KPN (Netherlands), Belgacom (Belgium),

Austria Telekom, France Telecom (Italy), Eircom (Ireland), Portugal PTT,

Telefonica (Spain), Teledenmark (Denmark), Swisscom (Switzerland).

Table 3 - Glossary


Reseller Request

Header Record{1 per file}

Detail Records{1 to 500}

Trailer Record{1 per file}

Appendix A Request File Formats

This section describes the format of the Reseller Request file and its associated Job file.

There is exactly one Job file for one Request file.

The Reseller Request file passes the list of requests to Cocom for processing. The list may

contain either pure CLI or pure CPS or CLI+CPS requests. The requested processing may

be, where authorised, for activation, change, deactivation and modification of CLI or CPS.

See the tables in section A.3.1 Action Types for valid request types.

A.1 Request File

A.1.1 File/Message Structure

Figure 6 - Reseller Request Structure

Each Reseller Request consists of a

Header Record, describing the type of request (CLI, CPS, combined CLI/CPS)

Detail Record, describing the end-customer details

Trailer Record, including a checksum


Please Note: A List of all CLIs will appear in the “all_cli” Folder in FTP after the first

request was successfully processed.

A.1.2 Header Record

There is just one Header record per file, which must be the first record in the file.

Ref Identifier/ Field Name

Data Type

MaxLength

M/O Default Field Description / Notes

1 Header Id Alphanu

meric

1 Mandator

y

H Must equal character “H”

(without quotes)

2 Format

Description

Alphanu

meric

35 Optional none Free format text for

information only. For

example “CLI Requests”

3 Version Alphanu

meric

6 Mandator

y

0.02.1 File Format Version. This is

a required value and

should be the default value

unless otherwise instructed

by Colt

4 Country ID Alpha 2 Mandator

y

FR Country ID in ISO-3166

Code

Value ”FR” for France

5 Service

Profile

Alphanu

meric

3 or 5 Mandator

y

None Unique ID allocated by

Colt.

3 Alphanumeric in case of

profile auto generated

And 5 Alphanumeric in

case profile is not auto

generated

6 Customer

Group

Alphanu

meric

30 Optional None “R_” + Reseller name


Please Note: When you want to place a request in the “request”-folder in FTP make sure

you either start with the sequence number 000001 or continue with the sequence

Number if you already placed requests before. It is also very important that the Service

Profile ID in the file-name is written in lower cases since UNIX Server can’t process files

with capital letters in the file name.


Data Type

MaxLength

M/O Default Field Description / Notes

7 Tariff Plan Alphanu

meric

2 Optional None Last 2 digits of Service

Profile

Example: 02

8 CLISERV

Screening

Index

Integer 3 Optional None Service Profile Example:

a02

9 The number

of Current

block

Integer 2 Optional 01 01-99; Currently only 01 is

supported

10 Total number

of blocks

Integer 2 Optional 01 01-99; Currently only 01 is

supported

11 Creation Date Timestam

p

17 Mandator

y

Current

Date

Current Date in format

YYYYMMDD-hh:mm:ss

Example:

20110430-13:42:27

Table 4 - Request Header Record

A.1.3 Detail Records

There can be up to 500 detail records per Request file.

Ref

Identifier/ Field Name

MaxLength

Actions

Mandatory/Optional

Field Description / Notes

1 Data Record

Identifier

1ALL

Mandatory D for Detail


Please Note: Each field must be delimited by a semi-colon (;) and the line should end

with a semi-colon.

Ref


MaxLength

Actions

Mandatory/Optional


2 Request

Number

22

ALL

Mandatory Record number

Starting at 1, increase by 1 with a

maximum of 500 per file. No gaps

or duplicates allowed.

The sequence is Reseller-

maintained.

3 CLI 10

ALL

Mandatory Telephone number

Numeric, 10 digits (including a

leading zero)

4 Action 1 ALL Mandatory CLI Action Types

A-Add CLI

D-Delete CLI

M-Modify CLI

CLI/CPS Action Types

A- Activate the CLI on the switch

and request Pre-selection

CPS Action Types

A - Activate Pre-selection but CLI

will be activated automatically.

D - Deactivate Pre-selection

5 ToneBurst 1 ALL Optional ToneBurst does not apply

Values: “0” or NULL

6 Job date 17 ALL Mandatory Date and time the request was

produced.

Format is YYYYMMDD-hh:mm:ss

7 Customer

Request Date

8 CPS

ALL

Optional Date that the Customer requires

the action to take place.

Format is YYYYMMDD


Ref


MaxLength

Actions

Mandatory/Optional


8 CPS Level

Or

CLI Service

CPS

ALL

CLI Request:

n/a

CPS Request:

mandatory

CLI/CPS:

mandatory

The CPS level is the same for all

customers in France – NI

(National/International)

9 Title

(Civilite)

CPS

ALL

CLI Request:

n/a

CPS Request:

Optional

Must be left blank

10 Family Name

(Nom)

CPS

ALL

CLI Request:

n/a

CPS Request:

Optional

Must be left blank

11 First Name

(Prenom)

CPS

ALL

CLI Request:

n/a

CPS Request:

Optional

Must be left blank

12 Company

Code

(SIRET)

CPS

ALL

CLI Request:

n/a

CPS Request:

Optional

Must be left blank

13 Cease NTF

number

CPS

ALL

CLI Request:

n/a

CPS Request:

Optional

Must be left blank

Table 5 - Request Detail Record


Please Note: Each field must be delimited by a semi-colon (;) and the line should end with

a semi-colon.

A.1.4 Trailer Record


MaxLength

M/O Field Description / Notes

1 Trailer Id 1 Mandator

y

T for Trailer

Must be first field on last line in file

2 Number of

Records in

this block

3 Optional Maintained by Reseller

3 Checksum 10 Optional Value generated running Unix checksum on this

block’s data records. By default no checksum is

performed and the field is empty

4 Number of

current block

2 Optional 01-99; Currently only 01 is supported. By default

the field is empty.

5 Total number

of blocks

2 Optional 01-99; Currently only 01 is supported. By default

the field is empty.

Table 6 - Request Trailer Record

A.1.5 Request File Example

File name:

a0200000001.req

Header line:H;CLI Requests;0.02.1;FR;a02;R_EQUITEL;02;a02;01;01;20040312-

11:31:11;

Detail line(s):D;1;0444444447;D;0;20040616-09:50:28;;;;;;;;

D;2;0444444449;A;0;20040616-09:50:28;;;;;;;;

Trailer line:T;2;;01;01;



with a semi-colon.

Reseller Request Job file


Detail Record{1 per file}


A.2 Request Job File

The Request Job file is a flat file containing the name of a Request file and the Type of

Request. The file acts as a trigger for Cocom to start looking for a Request file. There is

exactly one job file for one Reseller Request file.

A.2.1 File/Message Structure

Figure 7 - Request Job File Structure

A.2.2 Character Coding

ASCII

A.2.3 File Mark-up Coding

No structured Mark-Up used

Semi- colon separators used

Variable length records

A.2.4 Compression/Decompression Algorithms

None used.


A.2.5 File Name

The file name is formatted by concatenating:

The Service Profile – up to 5 alphanumeric

The file sequence number – 8 characters left padded with zeros

File extension “.req.job”

Example:

a0200000001.req.job

(Service Profile) a02 + 00000001 (File sequence number)


A.2.6 Header Record


MaxLength


1 Header Id 1 Mandatory H for Header

Must be the first Field on the First line of the file

2 Format

Description

N/A Optional Free format text for support

”Example:

CLI Requests

3 Version N/A Mandatory Format version

Must be 0.02.1 unless advised otherwise by your

Colt Account Manager

4 Creation Date N/A Mandatory Current Date in format YYYYMMDD-hh:mm:ss

Example:

20110430-13:42:27

Table 7 - Job Header Record



with a semi-colon.

A.2.7 Detail Record


MaxLength


1 Data Record

Identifier

1 Mandatory D for Detail

2 Request File

name

N/A Mandatory Name of the associated Reseller

Request file

Format: Dir/filename

Example: request/a0200000001.req

3 Format N/A Mandatory Format of compression of the Request

file. This should be the text value ‘plain’.

4 Request Type N/A Mandatory Defines the type of Request:

CLI

CPS

CLI/CPS

Table 8 - Job Detail Record

A.2.8 Trailer Record


MaxLength


1 Trailer Id 1 Mandatory T for Trailer

Must be the First field

2 Number of lines 3 Mandatory Number of detail lines

3 Checksum N/A Optional Value generated running Unix checksum

on this block’s data records. By default no

checksum is performed and the field is

empty

Table 9 - Job Trailer Record


Please Note: Each field must be delimited by a semi-colon (;) and the line should end with a

semi-colon.

A.2.9 Request Job File Example

File name:

a0200000001.req.job

Records:H;CPS request job;0.02.1;20041030-11:31:11;

D;request/a0200000001.req;plain;CPS;

T;1;;


Please Note: Each field must be delimited by a semi-colon (;) and the line should end with a

semi-colon.

A.3 Reference Data

A.3.1 Action Types

The following tables list the types of requests that you can submit for CLI and CPS.

CLI Action Types

Action Code

Action Rules

A Add to switch CLI must not be active

D Delete from switch CLI must be already active

M Modify CLI ownership to this

Reseller

CLI must be active with another Reseller. The

action will transfer the ownership of the CLI.

Table 10 - CLI Action Types

CLI/CPS Action Types

Action Code Action Rules

A CLI/CPS Request

Activate the CLI on the switch

and request Pre-selection


If the CLI is active – warning message given

but CPS request is processed

If the CLI is inactive – CLI is activated on the

Switch then the CPS is processed

Table 11 – CLI/CPS Action Types

CPS Action Types

Action Code Action Rules

A Activate Pre-selection but CLI

will be activated automatically.


If the CLI is active – no warning message

given but CPS request is processed

If the CLI is inactive – CLI is activated on the

Switch then the CPS is processed

D Deactivate Pre-selection Only if CPS is already active on the CLI.

Only the CPS is deactivated, the CLI will

remain active on the Switch.

Table 12 - CPS Action Types


A.4 Request Examples

The following example requests are for Reseller with service profile a02.

A.4.1 CLI-only Requests

This is from French (FR) reseller with service profile a02 to Deactivate CLI

0444444447, and to Activate CLIs 0444444448, and 0444444449.

Request File:H;CLI Request

file;0.02.1;FR;a02;R_Resellername;02;a02;01;01;20040616-

09:50:28;

D;1;0444444447;D;0;20040616-09:50:28;;NI;;;;;;

D;2;0444444449;A;0;20040616-09:50:28;;NI;;;;;;

D;3;0444444448;A;0;20040616-09:50:28;;NI;;;;;;

T;3;;01;01;

Job File:H;CLI request job;0.02.1;20040616-09:50:28;

D;request/a0200000006.req;plain;CLI;

T;1;;


A.4.2 CPS Only Requests

This is from France (FR) reseller with service profile a02 to Deactivate CPS on

0144400011, and to activate CPSs on CLIs 0144400021, and 0144400022.

Request File:H;CPS Request


16:38:44;

D;1;0144400011;D;0;20040617-16:38:44;;NI;;;;;;

D;2;0144400021;A;0;20040617-16:38:44;;NI;;;;;;

D;3;0144400022;A;0;20040617-16:38:44;;NI;;;;;;

T;3;;01;01;

Job File:H;CPS request job;0.02.1;20040617-16:38:44;

D;request/a0200000033.req;plain;CPS;

T;1;;

A.4.3 Combined CLI/CPS Requests

This is from French (FR) reseller a02 to Activate CLIs 0177777770, 1, 2, 3 and to

Activate CPS service on each.

Request File:H;CLI_CPS Request


16:42:20;

D;1;0177777770;A;0;20040618-16:42:20;;NI;;;;;;

D;2;0177777771;A;0;20040618-16:42:20;;NI;;;;;;

D;3;0177777772;A;0;20040618-16:42:20;;NI;;;;;;

D;4;0177777773;A;0;20040618-16:42:20;;NI;;;;;;

T;4;;01;01;

Job File:H;CLI/CPS request job;0.02.1;20040618-16:42:20;

D;request/a0200000029.req;plain;CLI/CPS;

T;1;;


Appendix B Response Files

B.1 CLI Responses

This section describes the layout of a CLI Response file and the CLI Response Job file.

The Response file will contain an entry for each CLI request showing the status of the

request and will give the errors that are generated if a request fails validation. These

errors occur if there is something logically wrong with the actual request, rather than the

format of the request file. The errors will appear in the Response file, not in a separate

error file.

B.1.1 CLI Response Files

The CLI Response File is in the format of a flat file containing details of all the CLI

requests in the associated Request file. For each CLI or CLI/CPS Request File that

passes file-level validation one Response file and one Job File will be returned.

The Response file returns the result of the processing of all the CLI Requests submitted

to Cocom. The detail line defines whether the activation/ deactivation/ modification/

change request has been successful or has been rejected.

Notes:

When the CLI is successfully processed the “Error Code” field will contain 0 (zero)

and the “Error Text” field will contain ‘OK’.

When a CPS request is for a range of individual CLIs, the CLI response file will

contain one detail line for each number in the range.

The Response message is placed in a dedicated Reseller directory on the Colt

server /response.


CLI Response


Detail Record{n per file}


B.1.2 File/Message Structure

Figure 8 - CLI Response Structure


B.1.3 File Naming

The file name is the same as the associated Request file name with a file extension of

“.rsp”.

Example:

For a request file: a0200000002.req

Response file will be: a0200000002.rsp

B.1.4 Header Record



1 Header Id H for Header

2 Format

Description

The type of response file

3 Version Format version

4 Creation Date Current Date in format YYYYMMDD-hh:mm:ss

Example: 20110430-13:42:27

Table 13 - CLI Response Header Record



with a semi-colon.

B.1.5 Detail Record

Field # Field Name Format Description

1 Data Record

Identifier

Must be “D” (without quotes)

2 Request No. Request No. provided in the request.

3 CLI CLI which has been processed. Inherited from Request.

4 Action Populated from the corresponding original ACTION value in Reseller

Request Data record. For invalid action types the value is “?”

5 Colt Response

Date

Date and time when the response is processed by Colt

6 Colt Response

Code

Cocom Error Code – refer to E.1.1 File Validation Codes

7 Colt Response

Text

Cocom Error Text – refer to E.1.1 File Validation Codes

Table 14 - CLI Response Detail Record

Fields holding data from the PTT may or may not be populated.



with a semi-colon.

Please Note: If Resellers are using automated procedure we strongly recommend that

only field number 6 (Colt Response Code) is been programmed to deduct further error

processing.

B.1.6 Trailer Record



1 Trailer Id T for Trailer

2 Number of Detail

Lines

Number of Detail Lines

3 Checksum Value generated running Unix checksum on this block’s data

records. By default no checksum is performed and the field is

empty.

Table 15 - CLI Response Trailer Record

B.1.7 Response File Example

File name:

a0200000001.rsp

Header line:H;Cocom Activation/Deactivation Response;0.02.1;20050212-

11:31:13;

Detail line(s):D;1;0113001110;A;20040816-18:05:49;0;OK;

D;2;0113001134;D;20040816-18:05:49;0;OK;

D;3;0113001138;?;20040816-18:05:49;1;DATA OUT OF RANGE(unknown

activity-code (known codes: ACTIVATE, DEACTIVATE, MODIFY));

Trailer line:T;3;;



with a semi-colon.

B.2 CLI Response File Example

This is an example of a response to a CLI request with one successful CLI activation, one

successful CLI deactivation and one unsuccessful request because of unknown activity

code.

Response FileH;Cocom Response Activation/Deactivation;0.02.1;20040816-18:05:49;

D;1;0113001110;A;20040816-18:05:49;0;OK;

D;2;0113001134;D;20040816-18:05:49;0;OK;

D;3;0113001138;?;20040816-18:05:49;1;DATA OUT OF RANGE(unknown

activity-code (known codes: ACTIVATE, DEACTIVATE, MODIFY));

T;3;;

B.3 CLI Response Job File

The Response Job file is a flat file containing the name of a Response file and the Type of

Response. There is exactly one Job file for one Response file.

The file is created and transmitted after the CLI Response file processing is complete. The

aim is to prevent access of the Response file by the Reseller while it is still open for writing

by Colt. Therefore, the Reseller must not attempt to access the Response file, before a job

file is transmitted by Colt.

Job files are always stored in the /job_out directory.


CLI Response job file





Figure 9 - CLI Response Job File Structure

B.3.2 File Name

The file name is formatted by concatenating the file name of the associated CPS Response

file with an additional extension “.job”

Example:

a0200000002.rsp.job

B.3.3 Header Record




2 Format

Description

Description of the type of job file



Example:

20110430-13:42:27

Table 16 - Response Job Detail Record



with a semi-colon.

B.3.4 Detail Record



1 Data Record

Identifier

D for Detail

2 Response File

name

Name of the associated CLI Response file


Example: Response/a0200000002.rsp

3 Format Format of compression of the Response file. Should be text value

‘plain’

Table 17 - Response Job Detail Record



with a semi-colon.





2 Number of lines Number of detail lines

3 Checksum Value generated running Unix checksum on this block’s data

records. By default no checksum is performed and the field is

empty

Table 18 - Response Job Trailer Record

B.3.6 CLI Response - Job File Example

File name:

a0200000002.rsp.job

Job FileH;Cocom Response Jobfile;0.02.1;20050429-18:05:49;

D;response/a0200000002.rsp;plain;

T;1;;

B.4 CPS Response File

This section describes the format of the Cocom Response file and its associated Job file.

There is always one Job file for one Response file.

The CPS Response File is in the format of a flat file containing details of exactly 1 processed

CPS request.

The Response file returns the result of the processing of the individual CPS Requests

submitted to France Telecom.

The possible codes send by France Telecom can be found in E.2 PTT Reference Data



with a semi-colon.

Notes:

When a CPS request is for a range of individual CLIs, there will be one CPS response

file for each CLI within the range.

The Response message is placed in a dedicated Reseller directory on the Colt server

/response.

B.4.1 Response Times

The SLA for completion of requests is up to 10 days.

B.4.2 Character Coding

ASCII

B.4.3 File Mark-up Coding


Semi-column separators used

Variable line length

B.4.4 Compression/Decompression Algorithms

None used.


CPS Response





Figure 10 - CPS Response Structure

B.4.6 File Naming – CPS Response file for a single CLI

This section describes the name of the CPS response file for a single CLI request.


The associated Request file name

“_”

Record number (the Line info value of an individual CPS request within the

Request file)

Response number – the number of the response file (usually there will be up to

3 for one request)

File extension “.rsp”

Example:

a0200000001_17_1.rsp

Where:

a02 Unique Colt assigned Service Profile

00000001 File sequence number

17 The Line Info of an individual CPS request within the Request file

1Response number – 1 response expected providing PTT and Colt

systems work correctly


B.4.7 File Naming – CPS Unsolicited Cease

This section describes the name of the CPS response file for an unsolicited cease

CPS can be deactivated on request by the Reseller. CPS can also be deactivated by

France Telecom directly or activated to a different Reseller. In this case, France

Telecom sends Colt 2 notifications – 1 to notify that number will be ceased (“Cease

Pending” message) and 1 to notify the number has been ceased (a “Cease Actual”

message).. CPSs deactivated in this manner are treated by the Colt system as

Unsolicited Ceases.

For Unsolicited Ceases there is no associated file number, as there was no

Deactivation CPS request from the Reseller through Cocom. Therefore the file naming

convention uses the Service Profile and the CLI.


Service Profile“_”

CLI

“_”

Response number – 2 responses expected (a “Cease Pending” followed by a

“Cease Actual”)

File extension “.rsp”

Example:

a02_0207123456_1.rsp

Where:

a02 Unique Colt assigned Service Profile

0207123456 CLI

1 Response number – the first cease message


B.4.8 Header Record

Ref Identifier/ Field Name Field Description / Notes


2 Format Description The type of Response file

Example: CPS Deactivation Response



Example: 20110430-13:42:27

Table 19 - CPS Response Header Record



with a semi-colon.

B.4.9 Detail Record

Ref Field Name Format Description

1 Data Record Identifier Fixed value “D”

2 Request No. Request Number provided in the request.

3 CLI CLI which has been processed. Inherited from Request, or originated from PTT in the case of Unsolicited Ceases

and similar messages.

4 Action Populated from the corresponding original ACTION value

in Reseller Request Data record.

For Unsolicited Ceases the value is “U”

5 CPS Status “Switched”

Ready for service as of “Switchover Date & Time”

“Reject”

According to Error Code/Text – see France Telecom

Rejection/Notification Responses

“Cease Actual”

Result of successful Deactivation Request or Cease by

End Customer

6 Date received from PTT The date on which the PTT received the request

YYYYMMDD

7 CPS Level Not used

8 Switch-over Date The date on which the service is/will be Installed

9 Colt Response Date Date and time when the response is processed by Colt

10 Colt Response Code See E.1.1 File Validation Codes

11 Colt Response Text See E.1.1 File Validation Codes

12 PTT Response Code The PTT message code

13 PTT Response

Description

The PTT message text

France Telecom Rejection/Notification Responses

Table 20 - CPS Response Detail Record



with a semi-colon.

B.4.10Trailer Record



2 Number of Detail Lines Number of Detail Lines

3 Checksum Value generated running Unix checksum on this block’s

data records. By default no checksum is performed and the

field is empty.

Table 21 - CPS Response Trailer Record

B.4.11CPS Response File Example

Response message example - Activation:File name:

a0200000001_17_1.rsp

Header line:H;Cocom CPS Response;0.02.1;20050217-15:32:46;

Detail line:D;33;0146270048;A;Switched;04042005;;20050405-00:00:00;20050408-

09:26:06;0;OK;;;;;;;;;;;;;

Trailer Line:T;1;;

Response message example - Unsolicited Cease:File name:

a02_06235614_1.rsp

Header line:H;Cocom CPS Response;0.02.1;20050217-15:37:46;



with a semi-colon.

Detail line(s):D;;0494892946;U;Cease Actual;22042005;;20050425-

00:00:00;20050427-02:28:27;0;OK;YB;RESILIATION PAR

CLIENT;;;;;;;;;;;

Trailer line:T;1;;


CPS Response job file




B.5 CPS Response Job File

The Response Job file is a flat file containing the name of a Response file and the Type of

Response. There is exactly one job file for one Response file.

The file is created and transmitted after the CPS Response file processing is complete. The

aim is to prevent access of the Response file by the Resellers while it is still open for writing

by Colt. Therefore, the Reseller must not attempt to access the Response file, before a job

file is transmitted by Colt. Job files are always stored in the /job_out directory.

B.5.1 Character Coding

ASCII

B.5.2 File Mark-up Coding


Semi column separators used

Variable length records

B.5.3 Compression/Decompression Algorithms

None used.


Figure 11 - CPS Response Job File Structure


B.5.5 File Name


The file name of the associated CPS Response file

Additional extension “.job”

Example:

a0200000001_17_1.rsp.job

B.5.6 Header Record




2 Format Description The type of job file

e.g. Cocom CPS Response job file

3Version

Format version

Must be 0.02.1


Example: 20110410-13:42:27

Table 22 - CPS Response Job Header Record

B.5.7 Detail Record



1 Data Record Identifier D for Detail

2 Response File name Name of the associated Response file


Example: Response/a0200000001_17_1.rsp

3 Format Format of compression of the Request file. Should be text

value ‘plain’



with a semi-colon.



4 Request Type Defines the type of Request:

CPS

Table 23 - CPS Response Job Detail Record





2 Number of lines Number of detail lines

3 Checksum Value generated running Unix checksum on this block’s

data records. By default no checksum is performed and the

field is empty

Table 24 - CPS Response Job Trailer Record

B.5.9 CPS Response Job File Example

File name:

a0200000001_17_1.rsp.job

Header Record:H;Cocom CPS Response Jobfile;0.02.1;20050417-15:32:47;

Detail Record:D;response/a0200000001_17_1.rsp;plain;CPS;

Trailer Record:T;1;;



with a semi-colon.


with a semi-colon.

B.6 Sample Response Files

B.6.1 CPS Only Request

This is an example of a response to a CPS request that contains one successful CPS

activation, two successful CPS deactivation and four requests that were rejected because

the object does not exists.a0200000003.rsp

H;Cocom Response Activation/Deactivation;0.02.1;20120124-12:42:39;

D;1;0344574985;D;20120125-14:58:00;8;OBJECT DOES NOT EXIST;

D;2;0561351080;D;20120125-14:58:00;0;OK;

D;3;0557125296;D;20120125-14:58:01;8;OBJECT DOES NOT EXIST;

D;4;0561740854;D;20120125-14:58:01;0;OK;

D;5;0595678000;A;20120125-14:58:01;8;OBJECT DOES NOT EXIST;

D;6;0595678001;A;20120125-14:58:01;0;OK;

D;7;0595678002;A;20120125-14:58:01;8;OBJECT DOES NOT EXIST;

T;7;;

B.6.2 Combined CLI/CPS Request

This is an example of a response to a CLI/CPS request that contains one unsuccessful CPS

activation request as the action code ‘D’ is invalid for CLI/CPS request, the second detail

record is for successful response, where CPS response is pending. The last detail record id

for unsuccessful CPS request as the user can not submit a CPS activation request of

another account’s CLI.a0200000003.rsp

H;Cocom Response Activation/Deactivation;0.02.1;20040617-17:40:31;

D;1;0144400011;D;20040617-17:40:31;1;DATA OUT OF RANGE (Action is

invalid.);

D;2;0144400021;A;20040617-17:40:31;0;OK (Ok CPS pending);

D;3;0549272145;A;20051025-14:02:09;8;OBJECT DOES NOT EXIST (Account

<a02> cannot submit CPS requests for CLI of another account (direct

conflict));

T;3;;

Response file for Switched of Activate CLI (successful):a0200000003_1_1.rsp


H;CPS Response;0.02.1;20040619-15:36:51;

D;2;0144400021;A;Switched;18062004;;20040619-

00:00:00;200406191536;0;OK;;;;;;;;;;;;;

T;1;;

Response file for CLI Activate with incorrect action code (rejected by Cocom):a0200000003_1_2.rsp

H;CPS Response;0.02.1;20040617-17:40:32;

D;1;0144400011;D;;;;;20040617-17:40:32;1;DATA OUT OF RANGE

(Action is invalid.);;;;;;;;;;;;;

T;1;;


Appendix C File Level Errors

This section describes the Error file generated by the system if a Reseller Request file is

in the wrong format.

If a Request file is in the wrong format (it fails file-level validation) a single Error file will

be created in the form of a flat file containing the result of the file-level validation of the

Request. It is generated only if an error has been found. In addition, when an error is

found, the request file and the associated job file are renamed by appending “.failed” at

the end of the original file names.

Example:

a0200000001.req -> a0200000001.req.failed

a0200000001.req.job -> a0200000001.req.job.failed

C.1 Error File Format

C.1.1 Character Coding

ASCII

C.1.2 File Mark-up Coding


2 spaces are used as a separator between the fields

Variable line length

C.1.3 Compression / Decompression Algorithms

None used

Cocom-SG-EN-FR-25-01-2016-v01.9 60 / 84

Error

Detail Record{Exactly 1}

C.1.4 File/Message Structure

Figure 12 - Error File Structure

C.1.5 File Name

The file name is formatted by appending “.error” at the end of the original request

file

Example:

a0200000001.req -> a0200000001.req.error

C.1.6 Detail Record

There are no header or trailer records in this file.


1 Request file name Request file name

2 Date of Error Date Format:

DD.MM.YYYY HH:MM:SS

3 Error Code Error code maintained by Cocom

See E.1.1 File Validation Codes

4 Error Message See Details E.1.1 File Validation Codes

Table 25 - Error Detail Record

Cocom-SG-EN-FR-25-01-2016-v01.9 61 / 84


with a semi-colon.

C.1.7 File Error Example

File name:

a0200000001.req.error

Detail Record(s):

a0200000001 30.04.2004 11:31:11 Error 10: Version number is incorrect

Cocom-SG-EN-FR-25-01-2016-v01.9 62 / 84

Appendix D CDR File

The CDR file contains only CDR records in a fixed length format. A CDR file is made

available twice per day – once in the morning and once in the afternoon. The files are

delivered at approximately 9AM and 5PM CET.

The 9 AM CET file contains calls from 4 PM CET the previous day until 8AM CET

on the current day

The 5 PM CET file contains calls from 8AM CET to 4PM CET on the current day

D.1 CDR File Format

D.1.1 Character Coding

ASCII

D.1.2 File Mark-up Coding


Fixed length records

Fixed length fields, space filled

Seven fields with no separators

D.1.3 Compression/Decompression Algorithms

CDR files are delivered in Zip format (Unix GZip, MS Windows Zip). However, Colt

recognizes that this can be difficult for certain companies to receive and the CDR files

can be delivered in plain text if required. Please notify the Colt Customer Services if you

need the CDR files to be delivered as plain text (Uncompressed) files.

Cocom-SG-EN-FR-25-01-2016-v01.9 63 / 84

Please Note: CDR files are delivered to your directory 7 days a week and will vary in

size depending on the level of traffic that your customers generate.

D.1.4 File Naming

D.1.4.1 Twice Daily CDR

All unrated CDR files delivered to Cocom Web Manager and FTP have a filename in the

following format:-

<countrycode>_<profile>_<productidentifier>_<sequence no>_<date>.cdr.gz

Where:

<countrycode> in ISO 2 character format, note FR is used


<productidentifier> is the product identifier (1-2 alphanumerics) – see table

below

<sequence no> is a rolling four digit sequence per <profile>_<product>

combination



.gz is where the file is zipped


01 Reseller Connect

00 Voice Line

10 SIP Trunking

11 IP Voice Line

12 IN for Resellers

13 Carrier VoIP

Table 26 – Product Identifier

Example:

FR_A02_01_0007_20110204170001.cdr.gz

Unrated CDRs will be available for Reseller Connect with Wholesale Line Rental in the

same format as described in this section. In addition France Telecom/Orange will

Cocom-SG-EN-FR-25-01-2016-v01.9 64 / 84

provide a separate file of Wholesale Line Rental unrated CDRs which can be found

under your service profile in Cocom. For more details please refer to APPENDIX F.

D.1.4.2 Consolidated CDRs

All Consolidated CDR files delivered to Cocom Web Manager and FTP have a

filename in the following format:-

<profile><transactionID>.cdr.zip.

Where:


<transactionID> is the combination of date and unique number


.zip is where the file is zipped

Example: ANP20120105171.cdr.zip

Cocom-SG-EN-FR-25-01-2016-v01.9 65 / 84

D.2 Call Detail Record Format

Following call detail format is applicable for both CDR and Consolidated CDR.

The data lines are 229 bytes in length and organised as:

Ref Name Bytes/Length

Position

Alpha/Numeric

Format &Description

1 Origin 20 1 N Originating CLI with leading 0. Filler spaces

must be added to fill in the spaces

designated for a field.

2 Destination

(Terminating

)

20 21 N Destination 0 = Domestic and National,

Destination 00 = International

3 Product Type 2 41 N ‘01’=Indirect Service

4 Date 8 43 N YYYYMMDD

5 Time 8 51 N HHMMSSss . Time duration is broken up

into tenths of a second. Fractions of a

second will be ignored.

6 Duration 8 59 N Duration of the call to the nearest 1/10th of

a second SSSSSSSs

7 Continuation 1 67 N ‘0’, ‘1’, ‘2’, ‘3’ or ‘5’ – normally a 0; will be

ignored for our purposes. To be used only if

calls are greater than 6 hours

8 Switch ID 25 68 N Unique switch identifier

9 Trunk

incoming

25 93 N Internal use only

10 Trunk

outgoing

25 118 N Internal use only

11 Account

Code

20 143 A Not in use

12 Pulses in 6 163 N Not in use

13 Pulses

generated

6 169 N Not in use

14 Pulses sent 6 175 A In use for all Reseller Connect services in

Cocom-SG-EN-FR-25-01-2016-v01.9 66 / 84

FR: Charge Band defined by

Regulator(Arcep FR). If no Charge Band is

available, the field is blank.

15 Service

Indicator

4 181 N 0000 for standard calls, 0001 for ISDN calls

16 Charged (C-

Num)

20 185 N Not in use

17 Dialled (D-

Num)

20 205 N Not in use

18 Carrier 3 225 A The Reseller profile of up to 3 alphanumeric

19 End of

Record

1 228 A Value of zero is shown

20 Line Feed 1 229 ASCII

Control

Character

Line Feed (ASCII Control Character not

visible in plain text editors)

Table 27 - Call Detail Record Format

D.3 Sample Call Detail Record

Sample CDR file:-

FR_A46_01_0007_20150723170001.cdr.gz

Sample unrated CDRs in the standard format:

0173430194 0659301524012015072313184660000144320 MDA

CXPAT0130173430194 0000 A460 A46AS

0173430224 0892691691012015072313485930000000040 MDA

CXPAT0130173430224 D0400000 A460 A46AS

0173430215 0298102929012015072313465840000012620 MDA

CXWAT0130173430215 0000 A460 A46AS

Cocom-SG-EN-FR-25-01-2016-v01.9 67 / 84

Please Note: There is an ASCII Control Character (Line Feed, HEX 0A) after the last field

19 “End of record”. This Control character generates a new line for the next CDR and shows

that the actual CDR ends. Normally you can ignore this control character except you use a

HEX-Editor to process your CDRs.

.

0173430215 0327202590012015072313484420000012720 MDA

CXWAT0130173430215 0000 A460 A46AS

Cocom-SG-EN-FR-25-01-2016-v01.9 68 / 84

Appendix E Reference Data

E.1 Cocom Reference Data

E.1.1 File Validation Codes

The following table lists the potential error codes that may result from File level

errors:

Code Field Description / Notes1 Too many CLIs for one Request. Number must be lower than {500}

2 Incorrect checksum

3 Sequence number too low, the expected sequence number is {n}

4 Sequence number too high, the expected sequence number is {n}

5 There are too many or too few header records, there should be 1

6 Wrong header format

7 There are too many or too few trailer records, there should be 1

8 Wrong trailer format

9 Wrong number of detail records

10 Version number is incorrect

11 Request file does not exist or is unreadable

12 Job file does not exist or is unreadable

13 Configuration file could not be read for the given reseller!

14 Error during sequence processing!

15 Cannot write the reseller error file!

16 Cannot determine the checksum!

17 Wrong header format in job file!

18 Wrong data format in job file!

19 Wrong trailer format in job file!

20 Could not create request for service id <a>

Table 28 - File Level Errors

Cocom-SG-EN-FR-25-01-2016-v01.9 69 / 84

E.1.2 Request Validation Codes

The following are examples of messages that may appear in the response file

after a CLI request has been processed by Cocom.

Note that if a CLI request is successfully validated the response code will be “0”

and the error text “OK”.

Additional responses may appear that are not listed below.

Colt Response Code

Colt Response Text

Description Request type

Countries

Explanation

0 ok Comment:

Activated for Action

Change

CLI ALL The requested action has been

successfully completed

Ok CPS

pending

CPS

CLI/C

PS

ALL CLI activation has been successfully

completed, CPS request is pending

1 Data out of

range

cli with unknown

character

ALL ALL The format of CLI is invalid. CLI must be

a number.

cli should start with

0 and its length

should be between

10 and 10

ALL ALL

If length of CLI is not of 10 digits or does

not contain leading zero.

unknown activity-

code (known

codes: ACTIVATE,

DEACTIVATE,

MODIFY)

CLI ALL Invalid Action for provisioning was

requested (only A, D, M is allowed)

CLI is invalid. ALL ALL The format of CLI is invalid. CLI must be

a number (10 digits including a leading

zero)

Action is invalid. ALL ALL Invalid Action for provisioning was

requested (only A, D, M, see A.3.1

Action Types)

Cocom-SG-EN-FR-25-01-2016-v01.9 70 / 84

Colt Response Code

Colt Response Text


Countries

Explanation

Job Date is invalid. ALL ALL The date format is wrong.

Invalid CPS level CPS

CLI/C

PS

ALL CPS Level is wrongly specified. Value

for this field is “NI”

unknown activity-

code (known

codes: ADD CPS,

REMOVE CPS)

CPS ALL Invalid Action for provisioning was

requested.

cli should not start

with <areacode>

CLI ALL Area code present in the CLI is found in

negative List

Service

<SwitchProfile> is

not available for

this Reseller - CLI

combination

CLI ALL If Switch profile is empty or Deny Default

Serv value of the Service profile is 1.

invalid customer

request date

CPS

CLI/C

PS

ALL Possible Causes of Error – Wrong Data

Format supplied for Carrier Pre-

selection.

cps level is

mandatory

CPS

CLI/C

PS

ALL if cps level is null

cannot unsuspend

CLI <> - service not

suspended

CLI ALL If requested switch profile is CS and CLI

is not suspended.

cannot suspend

CLI <> - service

already suspended

CLI ALL For activity Modify CLI and Change CLI,

if requested switch profile is SC and CLI

is already suspended.

Cocom-SG-EN-FR-25-01-2016-v01.9 71 / 84

Colt Response Code

Colt Response Text


Countries

Explanation

cannot use profile

<Cancel

Suspension> to

add CLI <>

CLI ALL For activity Activate CLI, if requested

switch profile is CS.

cannot use profile

<Suspend CLI> to

add CLI <>

CLI ALL For activity Activate CLI, if requested

switch profile is SC.

Integer

Expected

Integer Expected

<> - but coming as

String

CLI ALL If value of attribute CLISERV or

TARIFFPLAN is not numeric

Cannot

deactivate

suspended CLI

Cannot deactivate

already suspended

CLI: <>

CLI ALL For activity Deactivate CLI, if CLI is

already suspended.

2 object already object already

exists

CPS Pending,

object already

exists

CLI/

CPS

ALL CLI is already active, however CPS is

pending

CLI <cli> already

active

ALL ALL

CLI already active ALL ALL

the target account

must be different

from the original

account

ALL ALL Will only be seen by Colt. It indicates

that CS has attempted to transfer a CLI

to a reseller who already owns the CLI.

The message that would be delivered to

a reseller in that case would be ’2 object

already exists account <account id>

cannot modify its own cli’

Cocom-SG-EN-FR-25-01-2016-v01.9 72 / 84

Colt Response Code

Colt Response Text


Countries

Explanation

direct conflict with

cli <cli>

CPS

CLI/C

PS

DE,IT The CLI is already provisioned and has

been tried to provisioned again. The

request has been submitted for a range

of CLIs. The CLI this response relates to

is already active on the switch. The CPS

request is proceeding normally.

You will probably get a response for

each CLI in the range.

If this is a single occurrence in the range

investigation is required.

cli is already

activated

CLI ALL CLI activation has already been send

and is now in process.

Or if the request is for CLI Activate and a

request is pending on CLI for activity

Change CLI

cli already activated

by modify

ALL ALL A CLI modification request is already in

process and the reseller requested a CLI

activate request.

Account of cli has

been modified

ALL ALL Will be sent if and only if there is a

pending modify request on the CLI and

the Reseller requested a deactivate OR

modify has been issued by a different

Reseller

Account of cli has

been modified

CLI ALL If the request is for CLI Change and a


Modify.

original account for

cli has changed

ALL ALL Will be sent if and only if there is a

pending modify request on the CLI that

the Reseller requested to activate.

Cocom-SG-EN-FR-25-01-2016-v01.9 73 / 84

Colt Response Code

Colt Response Text


Countries

Explanation


cli <>

CLI ALL If the request is for CLI Activate and a


Deactivate. If Pending CLI and current

CLI is equal direct matched.


cli <>



Activate. If Pending CLI and current CLI

is equal direct matched.

Could not process

current request -

Pending CPS

request

CPS

CLI/C

PS

ALL Will be sent in case the Reseller

requests any action on a cli while there

is a CPS requests that is either still

pending in Cocom OR no final response

has been received from the PTT.

Account <account>

cannot modify its

own cli

CLI ALL Reseller has tried to modify a CLI which

has already been assigned to him

8 These error messages can only occur

for deactivation requests

object does not

exist

Account of cli has

been modified

ALL ALL A CLI modification request is already in

process and the reseller requested a CLI

deactivate request.

range not available ALL ALL

No CPS found for

action

DEACTIVATE

CPS

CLI/C

PS

ALL When user requested a CPS Deactivate

activity and no CPS is present on the

CLI.

Reseller Profile

<service profile id>

does not exist.

ALL ALL If the provisioning request service profile

id account details does not exists

Cocom-SG-EN-FR-25-01-2016-v01.9 74 / 84

Colt Response Code

Colt Response Text


Countries

Explanation

Profile <profileId>

cannot submit CPS

requests for CLI of

another account

(best match)

CPS

CLI/

CPS

DE,IT If the request is a CPS Activity and the

CLI is already switched and the service

profile of the switched CLI does matches

with the service profile in the request but

the CLI does not matches with the BEST

MATCHED CLI

Profile < profileId>

cannot submit CPS

requests for CLI of

another account

(direct conflict)

CPS

CLI/

CPS

DE,IT If the request is a CPS Activity and the

CLI is already switched and the service

profile of the switched CLI does not

matches with the service profile in the

request

object does not

exist

CLI ALL If the request is Deactivate CLI and the

CLI is not active on the switch

cannot suspend

unknown CLI

<entry cli>

CLI ALL If the request is CLI Change or Modify

CLI and the action is suspend CLI and

the CLI is not switched

cannot unsuspend

unknown CLI

<entry cli>

CLI ALL If the request is CLI Change or CLI

Modify and the action is unsuspend CLI

and the CLI is not switched

account

<accountId> cannot

change cli of

another account

ALL ALL If the user requested for CLI Change

activity and CLI is already switched and

the service profile of the switched CLI

does not matches with the service profile

in the request

Account <account>

cannot deactivate

cli of another

account

ALL ALL If the user requested for CLI Deactivate

and CLI belongs to another profile id.

object does not

exist

CPS ALL For CPS activity, if CLI is not active.

Cocom-SG-EN-FR-25-01-2016-v01.9 75 / 84

Colt Response Code

Colt Response Text


Countries

Explanation

object does not

exist

CLI ALL If the request is for CLI Deactivate and a


Deactivate. If the same deactivate

request exists.

account <Service

Profile Id> cannot

deactivate cli of

another account



Deactivate. If the service profile Ids are

not equal.

object does not

exist



Activate. If service profile id doesn’t

match

account of cli has

been modified



Modify.

object does not

exist


request is pending on CLI for activity CLI

Change. If service profile id doesn’t

match

object does not

exist

CLI ALL If the request is for CLI Modify and a


Deactivate.

object does not

exist



Deactivate.

16 unknown error Reseller has insufficient rights or

privileges to process the requested

action

account is not

allowed to perform

a CPS activate

CPS

CLI/C

PS

ALL

Cocom-SG-EN-FR-25-01-2016-v01.9 76 / 84

Colt Response Code

Colt Response Text


Countries

Explanation

Account is locked ALL ALL If the reseller account is disabled or not

active.

account is not

allowed to activate

ALL ALL If the user doesn’t have the rights to

perform CLI Activate activity.

account is not

allowed to

deactivate


perform CLI Deactivate activity.

account is not

allowed to modify


perform CLI Modify activity.

account is not

allowed to change

CLI

CLI ALL If the user cannot does not have the

rights to perform CHANGE CLI activity.

account is not

allowed to activate

CPS ALL If the user cannot does not have the

rights to perform ACTIVATE CPS

activity.

account is not

allowed to

deactivate

CPS ALL If the user cannot does not have the

rights to perform DEACTIVATE CPS

activity.

Ring fenced

profile found

Ring fenced profile

<> found

ALL ALL If the provisioning request service profile

id is ring fenced.

Profile is locked Profile <> is locked ALL ALL If the provisioning request service profile

id is locked.

Profile ceased Profile <> is ceased ALL ALL If the provisioning request service profile

id is not active.

Table 29 - Cocom Validation Codes and Text

Cocom-SG-EN-FR-25-01-2016-v01.9 77 / 84

Message Code

Message Type

Message Description Explanation

0 B2BGateway Success Message/OK

-1 B2BGateway Unable to process your request

[additional explanation]

Validation Failed,

Infrastructure Error, e.g.

missing request file,

wrong characters

0 Cocom OK – Success

99 Cocom Cannot process your request!

Please contact customer

service support!

No connection between

B2B Gateway and

Cocom

Table 30 – B2B Gateway error Codes

Cocom-SG-EN-FR-25-01-2016-v01.9 78 / 84

E.2 PTT Reference Data

The following tables are from documents produced by the Telecoms Regulator of

France.

France Telecom Rejection/Notification Responses

Code Field Description

French

Field Description

English

00 OK (OK) Successful Request

02 LIGNE INEXISTANTE Non Existing telephone line

17 NOM DU TITULAIRE INCOHERENT Incoherent Name

25 LIGNE DEJA DANS L’ETAT ATTENDU Line already pre-selected

26 NUMERO SDA SDA number

77 SIRET DU TITULAIRE INCOHERENT Wrong SIRET

P5 INCOMPATIBILITE PUBLIPHONE Incompatibility

P6 INCOMPATIBILITE LIGNE

TEMPORAIRE

Incompatibility – temporary line

P9 INCOMPATIBILITE ABT MODERE Incompatibility – Switch

YA INCOMPATIBILITE AUTOCOM 11F Incompatibility – Autocom

YY AUTRE ANOMALIE Other

YB RESILIATION PAR CLIENT Cancellation by Customer (unsolicited cease)

Table 31 – France Telecom CPS Rejection / Notification Responses

Cocom-SG-EN-FR-25-01-2016-v01.9 79 / 84

E.3 Troubleshooting Cocom

Validation was not successful, request files have to be resend:

Error 3: Sequence number too low, the expected sequence number is {n}Error 4: Sequence number too high, the expected sequence number is {n}Please check if you have used the right sequence number. If several job files have been put

together at the same time into the jobin-directory it could happen that the system will reject

several files because of wrong sequence number (see note in 2.2 Request File Processing).

Please resend the files by putting the job files one after the other into the jobin directory.

Error -1: Unable to process your request: Unrecognized Sender/Receiver - Unknown Document TypeThere is a connectivity problem between Cocom and a Colt integration server. Please contact

Customer Service Support.

Error 18: Wrong data format in job file!The format of the Job file is wrong. E.g there is a line feed character or any other unknown

character in the file, that the system is not able to read it. Please check if the right format is used

to save the file. Character Coding needs to be ASCII. These issues may occur if you transfer data

between different operating systems like Windows and UNIX.

Error 11: Request file does not exist or is unreadablePlease check if the request file has been put in the directory before the job file. If this is the case

please check the format of the Job file which may be wrong. E.g. there is a line feed character or

any other unknown character in the file, that the system is not able to read it. Please check if the

right format is used to save the file. Character Coding needs to be ASCII.

Error codes in the response file, follow-up action is dependent on the error code:

2;OBJECT ALREADY EXISTS (cli is already activated)

As long as a CLI-activation process is pending (error message: 2 object already exists cli is

already activated), no other action on this CLI will be processed. All actions send during this time

will be rejected and have to be send again.

Cocom-SG-EN-FR-25-01-2016-v01.9 80 / 84

Appendix F Reseller Connect with WLR

If resellers are selling Reseller Connect with Wholesale Line Rental, then Colt will have

setup access to both Cocom and to the VGA portal. Resellers must use the VGA portal

to do all their end-customer activations & deactivations and to view the status of their

transactions for Wholesale Line Rental. Cocom must only be used to download unrated

CDRs. There is a separate VGA portal user guide which is available from the VGA

portal – please use your VGA portal login details and follow the instructions in your

welcome letter.

Unrated CDRs will be available for Reseller Connect with Wholesale Line Rental in the

same format as described in Appendix D. In addition France Telecom/Orange will

provide a separate file of Wholesale Line Rental unrated CDRs which can be found

under your service profile in Cocom. For more details please see below.

F.1 File Name

The France Telecom/Orange unrated CDRs delivered to Cocom have a filename in the

following format:-

<country_code>_<service profile>_<product>_PTT_< sequence no>_<date>.cdr

Where:

<countrycode> is in ISO 2 character format, note FR is used

<service profile> is up to 3 alphanumerics and is the applicable profile for the product

<productidentifier> is the product identifier (1-2 alphanumeric) – see table below

PTT is used to indicate that it is France Telecom/Orange CDR file

<sequence no> is a rolling four digit sequence per <profile>_<product> combination




01 Reseller Connect

Cocom-SG-EN-FR-25-01-2016-v01.9 81 / 84

Eg: FR_ALZ_01_PTT_0001_20131003114015.cdr

F.2 Call Detail Record Format

The following call detail format is applicable for the unrated CDRs delivered to Cocom

from France Telecom/Orange for Wholesale Line Rental “Type 1” calls.

The data lines are 229 bytes in length and organized as:

Ref NameBytes/Length

PositionAlpha/Numeric

Format &Description

1 Origin 20 1 N

Originating CLI with leading 0. Filler

spaces must be added to fill in the

spaces designated for a field.

2Destination

(Terminating)20 21 N

Destination 0= Domestic and National,

Destination 00 = International

3 Product Type 2 41 N ‘01’=Indirect Service

4 Date 8 43 N YYYYMMDD

5 Time 8 51 N

HHMMSSss . Time duration is broken

up into tenths of a second. Fractions of

a second will be ignored.

6 Duration 8 59 NDuration of the call to the nearest

1/10th of a second SSSSSSSs

7 Continuation 1 67 N

‘0’, ‘1’, ‘2’, ‘3’ or ‘5’ – normally a 0; will

be ignored for our purposes. To be

used only if calls are greater than 6

hours

8 Switch ID 25 68 NUnique switch identifier will contain

‘00000’

9Trunk

incoming25 93 N Internal use only

10Trunk

outgoing25 118 N Will contain ‘FR-WLR’

11 Account 20 143 A Originating CLI with leading 0

Cocom-SG-EN-FR-25-01-2016-v01.9 82 / 84

Code

12 Pulses in 6 163 N Not in use

13Pulses

generated6 169 N Not in use

14 Pulses sent 6 175 A

In use for all Reseller Connect services

in FR: Charge Band defined by

Regulator(Arcep FR). If no Charge

Band is available, the field is blank.

15Service

Indicator4 181 N 1000 for WLR type 1 calls

16Charged (C-

Num)20 185 N Not in use

17Dialled (D-

Num)20 205 N Not in use

18 Carrier 3 225 AThe Reseller profile of up to 3

alphanumerics

19End of

Record1 228 A Value of zero is shown

20 Line Feed 1 229

ASCII

Control

Character

Line Feed (ASCII Control Character

not visible in plain text editors

F.3 Sample Call Detail Record

0142975230 0820903503012013091812405700000016000 00000

1 FR-WLR0142975230 1000 ALW0

0142975230 0820903503012013091814271300000016000 00000

1 FR-WLR0142975230 1000 ALW0

0142975230 0821023610012013091815000700000024000 00000

1 FR-WLR0142975230 1000 ALW0

Cocom-SG-EN-FR-25-01-2016-v01.9 83 / 84

0559207970 0825009119012013091813591800000137000 00000

1 FR-WLR0559207970 1000 ALW0

0559207970 0825009119012013091814012000000007000 00000

1 FR-WLR0559207970 1000 ALW0

Cocom-SG-EN-FR-25-01-2016-v01.9 84 / 84

Consolidated CDR Request - colt.net … · Web viewThis document describes the necessary...

Documents

Transcript of Consolidated CDR Request - colt.net … · Web viewThis document describes the necessary...