Introduction

The information in this article targets Telepo BCS version 3.6 or later.

This article describes how a Meridix Studio installation is connected against a Telepo BCS installation both regarding retrieval of CDR (Call Detail Record) information through the Telepo Web API and how the catalog synchronization is handled. This is the default "off-the-shelf" way of handling the integration but the handling can be customized if a customer has special requirements.

Participating parts/systems

This is from a customer perspective and only sub-systems that partake in the integration is included

The Meridix installation hosted off-site in Microsoft Windows Azure (possibly load balanced between multiple servers in the Azure data center)
- Meridix Studio HTTPS Web API - Synchronization feature *
- Meridix-Telepo Catalog synchronization manager *
- Meridix-Telepo CDR client *
- Meridix Import Service - Handles CDR parser and data back-end import *
The on-site Telepo BCS Management-node(s)
- The HTTP Web API - Administration features

* Is installed and run off-site.

The integration consists of two separate parts where one part handles the synchronization of the catalog data from the Telepo BCS platform and the other part handles the retrieval and importing of CDR data from the Telepo BCS platform to the Meridix data back-end. Each of these parts is described in the following sections:

CDR Retrieval

The CDR data is made available for external systems by Telepo BCS through a HTTPS based API. To get the CDR data a HTTPS request is made against the management node CDR APIs. The request need to include a valid system ticket that is defined in the file cdr-pipelines.xml on the management node. (See Telepo document TelepoBCS_CDRs_xxxx.pdf section 7.2 regarding path etc). This service ticket will be appended to the HTTPS request that will return CDR information in the Response body as comma separated data (CSV).
Example of the HTTPS request URL that is used:

http://mn_ip/api/admin/cdrs?year=2013&month=03&date=21&t=system_token_for_management_node

Meridix has an application that makes these calls to the management node from which CDR should be retrieved. The only technical requirement is that the management node IP address is accessible from the Meridix server (off-site). The access can be setup as a IP rule or through an VPN connection into the sub net where the Telepo service nodes reside. It is not recommended to make the management node publicly available from the outside.

Example of a valid section that defines the token in the cdr-pipelines.xml

<system-tickets>
	<token>fsafghgdsfhjgfdjhvcir67iujytedrsf7eu65</token>
</system-tickets>

Meridix requires

Meridix needs to have access to the management node IP address and have valid system tickets for it.
No Meridix software needs to be installed on-site.

Catalog synchronization

Meridix is used as a slave catalog to the (master) Telepo catalog and synchronizes changes made in Telepo at a defined interval (usually once every 24 hours, but can be done more often if required). The information that Meridix loads from Telepo is used in a read only way i.e. changes is never published from Meridix back to Telepo.

The catalog data contains information about the organizations, user ids and function numbers that exist in the Telepo system. The data is used to translate these Telepo specific items to their Meridix equivalent so that once synchronized the Meridix installation will contain an complete Meridix version of the Telepo catalog that is ready to be used from the Meridix web user interface. So when there are no need to administrate available user ids etc. in multiple places since Meridix mirrors the Telepo catalog.

This information is exposed by Telepo through their Web API and multiple calls need to be made against the API to get all the required information. This is also handled by an off-site Meridix software that uses the Administration API part on the management-node. Since only the User API is by default publicly available on a Telepo installation the off-site Meridix server need to have access to the HA address of the management node.

API calls made against the Administration API needs to be signed with an system ticket (token and secret combination) that has access to the Administration APIs.

This only applies to Telepo versions prior to 4.0 SP2

One limitation in the Telepo API is that the orgId that maps the CDR logs with the organization that the belong to is not available through the API but since Meridix need to know each organizations orgId to be able to know which CDR logs that belongs to a specific organization this information need to be supplied as well. This mapping information between an organization usually identified by the domain and the corresponding orgId (integer) is available in the Telepo database. A commonly used solution to this is that a custom script is setup that writes this mapping (domain->orgId) to a csv file that is made available on a FTP share on-site (accessible from Meridix) or uploaded to a Meridix FTP server.

An alternative approach is that each customer manually need to have the org id added in the Meridix user interface. (Only needed for active customers).

The management API ticket need the be granted the following rights (see yellow marks).

Meridix requires

Meridix needs to have access to the management nodes administration API and have a valid system ticket (token and secret) with access to the Administration API methods. This is a read only operation from Meridix so changes are never pushed back to Telepo from Meridix.
No Meridix software needs to be installed on-site.

Summary

No Meridix software needs to be installed on-site, the only requirements is that the management-node is accessible from the Meridix off-site server and that Meridix has valid tickets and tokens for each of the required API operations.

Requirement	Reason	Notes
IP address to the Management node Administration API. With access rights from the Meridix off-site server.	To allow catalog synchronization (organizations, user ids, function numbers) To allow retrieval of CDR information (call logs)	Access can be granted through IP access rules or through a VPN connection.
API Ticket (token/secret) with rights to access the administration API methods.	To be able to sign the requests.
System token for the management node.	To be able to make the CDR API calls.
Organization domain to org id mapping	To be able to add the missing mapping between the CDR logs and the catalog data.	This is optional since it can be handled manually but its recommended that its automated to minimize errors.

The following information should to be supplied to Meridix.

	Type
The management-node IP addresses HA, Primary and Secondary	IP addresses
System ticket	Ticket (token and secret)
Information about mapping	(depends on customer preference)

Browser not supported