Introduction
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 HTTP Web API - Synchronization feature *
- Meridix-Telepo Catalog synchronization manager *
- Meridix-Telepo CDR retrieval manager *
- 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
- The on-site Telepo BCS Service-nodes(s)
- The HTTP Web API - CDR retrieval feature
* 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 HTTP based API. To get the CDR data a HTTP request is made against each of the services nodes CDR APIs. The request need to include a valid system ticket that is defined in the file /opt/servicenode/application/conf/cdr-pipelines.xml on each service node. (See Telepo document TelepoBCS_CDRs_xxxx.pdf section 7.2). This service ticket will be appended to the HTTP request that will return CDR information in the Response body as comma separated data (CSV).
Example of the HTTP request URL that is used:
http://servicenode_ip/api/admin/cdrs?year=2013&month=03&date=21&t=system_token_for_service_node
Meridix has an application that makes these calls to each of the servicenodes from which CDR should be retrieved. The only technical requirement is that the servicenode 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 servicenode 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 each of the servicenodes IP addresses and have valid system tickets for each of them.
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 managementnodes 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.
Multiple Meridix Studio installations for one or multiple Telepo servicenodes
If a Telepo system contains separate end customers that has their organizations provisioned on separate servicenodes, for example if Company A owns the Telepo system but Company B has its own part of the system with a custom branding etc. and all Company B data is located on a specific servicenode multiple completely separate Meridix Studio installations can be setup and allow Company A and Company B to have separate Meridix installations. This is possible since the catalog synchronization has information about which servicenode a organization resides in and the Meridix catalog synchronization can be setup in a way so that Meridix installation A only synchronizes organizations that is located on servicenodes that belongs to Company A and the organizations that belongs to Company B is synchronized against Meridix installation B which will then only contain information about Company Bs organizations.
This give a Telepo provider that for example have multiple resellers with their own branding the possibility to have their own report system as well.
Summary
No Meridix software needs to be installed on-site, the only requirements is that the management-node and the servicenodes 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) | 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. | |
| IP addresses to the Service nodes CDR API. With access rights from the Meridix off-site server. | To allow retrieval of CDR information (call logs) | Access can be granted through IP access rules or through a VPN connection. |
| System token for each service 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) |
| The servicenodes IP addresses (HA, Primary and Secondary) | IP addresses |
| Service node system ticket (one for each service node) | Tickets (token) |
| Information about mapping | (depends on customer preference) |