Creation of New Caller ID Sources

Superfecta v2.1.0+ Method--

Creation of New Caller ID Sources

With the release of 2.1.0, create of new caller id sources becomes easier, particularly for those sources which require custom values to be defined. It is recommend that you take a look at the scripts used for some of the other sources for best practices, particularly for the debug output.

Here are some guidelines to help you in the creation of your new source script.

  • Your script should be placed in the bin folder and should be named "source-[name_of_source][_CountryCode].php" Where CountryCode is the two letter country code. If the source is valid for multiple countries this field is omitted. For example your script file name could be: source-Example_Source_UK.php. The UI will immediately recognize the addition of new sources to the bin folder and present the source to users based on the file name you specify, with underscores (_) replaced with spaces.
  • There are a few variables used to for the definition of source.
  • $source_desc -> Used for a description of the source. The description line can contain some limited HTML, but <a> tags will not work properly. <br> tags will work, other HTML tags may break the script, so test.
  • $source_param -> An array that defines parameters that your script will need. Take a look at the SugarCRM source script for a better understanding of the usage of this array. This array will create the form elements in the FreePBX user interface to the right of the list of sources. Basic usages of this array is as follows:
  • $source_param['field_name'] -> The first dimension of the array is used to define the name of a field. This name should have no spaces. Underscores will be replaced in the UI by spaces for display purposes only. As always, case is important here.
  • $source_param['field_name'][elements] -> The second dimension of the array is used for several purposes, you can define the element with the key 'desc' and set the value for a description, give the key 'type' to provide the form element type (only valid entries right now are 'text','password','textarea','select','checkbox' and 'number'). You can provide the key 'option' for definition of the options available if your type is 'select'.
  • $source_param['field_name']['default'] -> To allocate an initial default value to an element. It is important to set this value as a variable without value can generate unexpected behavior in your script.
  • The script that actually retrieves caller id data should be put inside of the following if statement "if($usage_mode 'get caller id') { //code goes here }". The source code you create will be included into bin/callerid.php when it is run. This means that any variable set in bin/callerid.php is available to your script.
  • If a phone number is determined to be SPAM, the boolean variable $spam should be set to true. When $spam is set to true, a user defined value (set in the UI) will be prefixed to the caller id returned. Determination of a call as SPAM does not stop the script from running.
  • When a caller id name is determined, the variable $caller_id should be set to that name, and if a caller id name cannot be determined, $caller_id should be left blank. The filling of this variable with some value indicates to the script that it should discontinue seeking caller id from other sources.

Source scripts can be used for both retrieval of caller ID data, and post retrieval processing for things such as posting information to outside services.
Code for retrieval should be enclosed in the if statement as noted above, but code used post retrieval processing should be placed inside of the following if statement "if($usage_mode 'post processing') { //code goes here }". For example code, take a look at the Superfacta Cache source file.

Be careful not to modify a variables already used by bin/callerid.php as their value need to be used by other sources.

In order to be accepted for inclusion in Caller ID Superfecta project, and the live update feature, every data source script should accept numbers presented in ALL the following formats:

- National format: the format that you are dialing the number for an in country call (ie for the NANPA: NXXNXXXXXX, for France: 0ZNNNNNNNN)

- International format (e164): country code + number (ie for the NANPA: 1NXXNXXXXXX, for France: 33ZNNNNNNNNN)

- International dialing: international access code + country code + number. The international access code can change depending on the country. It could be 00, 011 or +

Naming Conventions
All Data source scripts are named in the format source-sourcename.php. NOTE: The first character after "source-" must not be numeric.

Example: If you name a source "source-411_CA.php" it will not work. "source-CA_411.php" does work.

Caution - coding errors can lead to your CID sources not being displayed
There is at least one potential source of confusion for new users who are first starting out at coding a lookup source. If the php code for your new lookup source contains even a tiny syntax error, and the file is stored in the superfecta /bin/ directory, then none of the lookup sources will be displayed when you try to create or edit a new CID lookup scheme. It is an easy fix, once the coding error has been fixed, the Superfeca module will resume normal behavior.

Stray characters, spaces, etc.
It is critical when creating new or editing old lookup sources not to have any characters outside of the 

<? ... ?>
that indicate the limits of the PHP code. Any stray characters (especially a space) will appear in the CNAM data reported to FreePBX, and are difficult to track down.

--Old Version 2.0.x Method--

Note: This form has been depreciated and is not valid for Superfecta 2.2.0 and later. It is provided here for reference purposes ONLY.

Creation / Addition of new Caller ID Sources

The addition of new caller ID sources is very easy, only a few rules must be followed to ensure that your script operates properly and returns the result you desired. It is recommend that you take a look at the scripts used for some of the other sources for best practices, particularly for the debug output.
Here are a few simple rules to follow.

1. Your script should be placed in the bin folder and should be named "source-[name_of_source].php" For example your script file name could be: source-Example_Source.php. The UI will immediately recognize the addition of new sources to the bin folder and present the source to users based on the file name you specify, with underscores (_) replaced with spaces.

2. The second line in the source file is reserved for a description of the source. The description line can contain some limited HTML, but <a> tags will not work properly.

3. The source code you create will be included into bin/callerid.php when it is run. This means that any variable set in bin/callerid.php is available to your script.

4. If a phone number is determined to be SPAM, the boolean variable $spam should be set to true. When $spam is set to true, a user defined value (set in the UI) will be prefixed to the caller id returned. Determination of a call as SPAM does not stop the script from running.

5. When a caller id name is determined, the variable $caller_id should be set to that name, and if a caller id name cannot be determined, $caller_id should be left blank. The filling of this variable with some value indicates to the script that it should discontinue seeking caller id from other sources.

Note: This method works ONLY in version 2.0.x of the Caller ID Superfecta.

Also available in: HTML TXT