Cocom+ Reseller Guide

Colt Cocom

FTPUser Guide

Netherlands

Cocom Reseller User Guide NL

Table of Contents

1Document History

2Introduction

3Service Outline

3.1Outline Process

3.2Technical Infrastructure

3.2.1Overview

3.2.2Directory Structure

3.2.3File Naming Standard

4Service Requests

4.1Overview

4.2Request File Processing

4.3Validation Rules and Checks

5Service Responses

5.1Colt Responses

6CDR Files

7Maintenance and Support

8Tips, Tricks and Rules

9Glossary

Appendix ARequest File Formats

A.1Request File

A.2Request Job File

A.3Reference Data

Appendix BResponse Files

B.1CLI Responses

B.2CLI Response File Example

B.3CLI Response Job File

B.4CLI Response Job File Example

Appendix CFile Level Errors

C.1Error File Format

Appendix DCDR File

D.1CDR File Format

D.2Call Detail Record Format

D.3Sample Call Detail Record

Appendix EReference Data

E.1Cocom Reference Data

E.2Troubleshooting CoCom......

1Document History

Reseller Guide / Version / Issue Date / Description of change from previous version / Distributed
Generic Body / 6.0 / 14/11/2005 / First version based on User Guide version 6.0 of other countries
6.1 / 08/12/2005 / New chapter 8 Tips, tricks and rules
New chapter E3 Troubleshooting Cocom
Update of E.1.2Request Validation Codes / 8/12/2005
6.3 / 15/04/2009 / Maintenance & support updated.

Cocom Reseller User Guide NL

2Introduction

Colt Telecommunications (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 asCocom.

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. The system will confirm that the CLI is known to Colt and activate the CLI before forwarding the request to the relevant PTT, and passes back the responses received from the PTT.

The CPS part is not available for the Netherlands!

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 requests
Action Codes

3Service Outline

3.1Outline 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.

Figure 1 Colt Reseller support infrastructure

3.2Technical Infrastructure

3.2.1Overview

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 either a dedicated VPN client, provided by Colt, or by dial-up access. These methods aredetailed 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.

3.2.2Directory Structure

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). 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 areas follows:

/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
/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

3.2.3File 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:

The first digits are assigned by Colt Telecommunications and will be your unique identifier, which is a 3 digit number e.g. 999.
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.
A suffix separated by a dot that describes the type of the file

reqrequest file

rspresponse file

errorerror file

cdrCDR file

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

For example a request from a new reseller 999 would be a pair of files:

99900000001.req

99900000001.req.job

The Colt response would be another pair of files:

99900000001.rsp

99900000001.rsp.job

4Service Requests

4.1Overview

Colt allows service activation, and deactivation requests for Resellers’end-customers CLIs on the Colt network.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),

Activate / Deactivate
CLI / CLI must not be active / Only if the CLI is already active

Table 1 - CLI Request Rules

You can include up to 500 individual requests in a single file, and the file must be uniquely identified (see Appendix B 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 4.3 below)

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

4.2Request 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 CLIrequests must comply as per Appendix ARequest File Formats

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

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

For each CLI 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.

4.3Validation Rules and Checks

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

First Level

First, 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:

1)Conform to the Colt file naming standard (3.2.3File Naming Standard)

2)The file sequence number must follow in sequence and be only 1 higher than the last file successfully submitted

3)There must be a matching pair of request and job files

4)Have one and only one Header record, one or more Detail records and one and only one Trailer record

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

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

7)There should be only one CLI 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 alsoAppendix CFile Level Errors).

This file will contain a Header record, a single detail record containing an error message as per Table 18 - File Level Errorsabove, and a Trailer record. The technical detail for file level error notifications is inAppendix CFile 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 Level

After 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.1CLI Responses gives the technical detail of the CLI Response file.

Some examples what will be checked are

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

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

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

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

CLI – to indicate that this is a CLI only request

If any detail record ends with any other value, Colt will attempt to process the record as if it was a CLIonly request. If it is not a CLIonly request then it will fail and the appropriate error will be generated.

5Service Responses

5.1Colt Responses

For each request made, a response will be created by Colt. There will be one Response file for each CLI Request file submitted.

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)

The technical detail for the CLI Response File layouts and examples are given inB.1CLI Responses.

6CDR 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 unrated CDRs collected by the Colt network since the last file, typically each 12 hours.

The files are provided in a pre-defined, fixed length format. These files are country specific and are detailed in Appendix DCDR File.

7Maintenance and Support

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

The Cocom server is generally available around the clock except for brief periods where Colt has to carry out essential system maintenance. These regular maintenance windows are:

21:00 – 22:00 GMT Daily

03:00 – 04:00 GMT Every Sunday

This allows you to submit and retrieve files overnight and at times that suit your own IT processing needs, although help and support is only available during normal office hours.

Should we need to temporarily suspend access to the server, for planned maintenance, you will be notified at least 5 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.

8Tips, Tricks and Rules

How to avoid congestion

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.

There could be up to 500 records in one file. Less 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 the CSR in your country before sending the requests to do this on an agreed timeframe. Otherwise Colt reserve the right to delete mass requests which haven’t been confirmed by Colt. Colt may suggest a dedicated time-frame to accept this mass requests as part of a migration or database cleaning.

Unexpected messages

If error messages will be interpreted automatically check the Response Code and ColtResponse Text. The Description Text may change and new error messages may be added. Please ask Customer Service if you recognize new or different messages if a new Guide is available.

Modify command

The 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.

Miscellaneous

If 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

Please check also chapter E.2Troubleshooting CoCom.

9Glossary

Term / Description
CLI / Calling Line Identifier. A term used within Colt to mean a end-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 end-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. Coltdeals with the following operators: France Telecom (France), Deutsch Telekom (Germany), British Telecom (UK), Telia (Sweden), KPN (Netherlands), Belgacom (Belgium), Austria Telekom, Telecom Italia (Italy), Eircom (Ireland), Portugal PTT, Telefonica (Spain), Teledenmark (Denmark). Swisscom (Switzerland).

Table 2 - Glossary