Reference13r1:Concept App Service Contacts: Difference between revisions

From innovaphone wiki
Jump to navigation Jump to search
Line 314: Line 314:
</code>
</code>


 
The generated csv-file can be downloaded by use of an sftp-client (e.g. WinSCP) and login to the AP with admin credentials.


<!-- =Known Problems=== -->
<!-- =Known Problems=== -->

Revision as of 13:29, 25 May 2022

The App Service Contacts is an App Service which can be installed on an innovaphone App Platform. It is used for information retrieval of a database of contact entries.

Features

Database for contact entries. A user interface for retrieval purposes is available.

  • Import of comma-separated files
  • API for other apps

Requirements

  • innovaphone PBX and App Platform from on version 13r1

Details

Number handling

In principle, two versions of a phone number are always stored in the contacts database.

Original Number
This is the unchanged number imported by the user. This version includes all decorative characters, spaces, etc. (eg. +49-(7031) 730090)
Formated number
A filter is applied to the original number before saving to remove all non-dialable characters. (This means that only 0-9,+,*,# remain after that) This formated version of the call number is saved in addition to the data set. (eg. +497031730090)

If a number is searched for (reverse lookup), the cleaned version is searched for. Thus, it does not matter which decorative characters or formats are imported. If an entry is displayed to the user, the originally entered call number (incl. decoration characters) is displayed.

It is therefore best practice to import only international format numbers (Decorations can be imported as they will be removed anyway), as the PBX always converts the number into the international format for a reverse lookup, if the dialing location was configured correct.

Assign unique IDs for contacts entries

It is recommended to upload CSV files with an additional column extAnchor. The column extAnchor allows to identify individual entries uniquely and independent of renaming operations. The column extAnchor is supposed to contain an external unique database id, alike a guid. If extAnchor was provided the import procedure will perform an UPDATE of previously existing entries, instead of deleting and re-INSERTing the entries. Entries pinned on home are going to remain functional.

Upload Data by HTTP Post

A CSV file can be uploaded by means of an HTTP POST request. The following powershell script aims to demonstrate this procedure with the help of CURL[1][2] The required user and password content corresponds to the configuration underneath PBX Manager/AP Contacts/Configuration/User(HTTP Post) and Password(HTTP Post)

  1. csv.ps1
  2. Sample powershell script demonstrating how to HTTP POST a CSV file towards the Contacts App service.
  3. .\bin\curl must be present, e.g. from https://curl.haxx.se/download.html
  4. Examples:
  5. powershell -ExecutionPolicy Bypass -Command .\csv.ps1 -Dest 172.16.18.215 -File ".\myContacts.utf8" -User "contacts01" -Pw "pwd01" -Url "/example.com/contacts01/post/myContacts.utf8?op=csv"

param( [Parameter(Mandatory=$false, HelpMessage="Destination host")] [string]$Dest, [Parameter(Mandatory=$false, HelpMessage="Name of file to be POSTed")] [string]$File, [Parameter(Mandatory=$false, HelpMessage="Authentication: User")] [string]$User, [Parameter(Mandatory=$false, HelpMessage="Authentication: Password")] [string]$Pw, [Parameter(Mandatory=$false, HelpMessage="URL, e.g.: /example.com/contacts01/post/myContacts.csv?op=csv&xml-stats=true")] [string]$Url )

Add-Type -AssemblyName System.Web

$Uri = "http://" + $Dest + $Url

function UploadToContacts { # Ensure file's there and has content if (!(Test-Path -Path $File)) { echo $File+" not downloaded!" exit 1 } $lines = 0 Get-Content $File |%{ $lines++ } echo "Lines of $File=$lines" if($lines -le 2) { echo "No Data to upload!" exit 1 }

$auth = "${User}:${Pw}"

echo "POSTing towards $Uri" .\bin\curl "--digest" -s -S --trace-time -u $auth -i -H "Content-Type:application/octet-stream" -X POST --data-binary "@${File}" "${Uri}" echo "POSTed towards $Dest" }

$timeStart = Get-Date echo "===Begin: ${timeStart} ===" UploadToContacts $timeEnd = Get-Date echo "===End: ${timeEnd} ===" echo ""

The URL

The first part of the URL (example.com/contacts01) is the Webserver path configured for the Contacts instance in the AP Manager. It must be followed by the literal post. The last part (myContacts.csv) can be chosen freely.

Note that the last part of the URL used to post the file (myContacts.csv in the example above) needs to be chose carefully. Contacts will remember this name as source for each of the uploaded entries. When the file is posted again (that is, when a new POST using this last URL part is done), Contacts will first delete all existing entries previously uploaded with this name and then add the new ones.

List of Attributes

The list of currently available attributes for a contacts entry follows:

extAnchor
unique id identifiing the entry within the database
givenname
First name
sn
Surname/Family name
company
Corporation
displayname
Name to be displayed
email
e.g. example@example.com
telephonenumber
Internationalized land-line telephone number, e.g. +49 7031 730090
mobile
Internationalized mobile telephone number
homephone
Internationalized home phone number
facsimiletelephonenumber
Internationalized fax number
city
City/Town, e.g. Milano
street
postalcode
state
Federal state, e.g. some US states: Ca, Wa, Fl
country
e.g. Deutschland, Italia
privatecity
Home address
privatestreet
privatepostalcode
privatestate
privatecountry
title
Academic title
position
Position within company, department
department
description
Common description
roomnumber
info
Common info
url
Company URL
sip
Dialable SIP address

List of Text-Indexable Attributes

Attributes to be considered for the full-text index

  • cn
  • sn
  • givenname
  • company
  • displayname
  • info
  • city
  • street
  • postalcode
  • country
  • state
  • private_city
  • private_street
  • private_postalcode
  • private_country
  • private_state
  • title
  • position
  • department
  • description
  • roomnumber
  • sip

Built-in LDAP Server

The App incorporates a proprietary LDAP server functionality, which is neither commercial-grade nor full-fledged. The purpose of the LDAP server functionality is to service innnovaphone LDAP clients, such as desk phones. The LDAP server only supports a proprietary search by means of a meta attribute[3], whereby LDAP is just utilized as a transport vehicle for a user's search input one-to-one.

  • E.g. a user searching for John Doe innovaphone
    • Possible user input jo do inno
    • Resulting LDAP filter (metaSearchText=jo do inno)

Sample Phone Configuration, innovaphone

Phone/User-X/Directories/External LDAP Server

Enable
Active
Use TLS
Active
Server
<host adddress of AP>
Port
<can be left empty>
Username,Pw
<Credentials for LDAP Bind operation>
Search Base
dc=entries
Mode
<can be left on "basic">
Object Filter
<leave empty>
Sort Results
Inactive
Name Attributes
givenName,sn,company
Number Attributes
<can be left empty>
H323 ID Attribute
sip
Detail Attributes
title,company,street,postalCode,city,country,email,url
Meta Name Attribute
metaSearchText
Meta Number Attribute
metaSearchNumber

Apps

  • innovaphone-contacts
    • The reqular app
  • innovaphone-contacts-admin
    • Features a menu (top-right) to manually upload a CSV file
  • innovaphone-contacts-searchapi
    • Provides a search API to other apps, e.g. for the Phone App

Troubleshooting

Manually Deleting an uploaded File

If multiple files or multiple versions of a CSV file were uploaded, it might not be clear how to delete an old data set. Here is an example for how to accomplish a deletion of a particular data set related to an imported CSV file:

  • 2 Files were previously imported
    • allcontacts.csv
    • brs%20testimport.csv
  • The file brs%20testimport.csv shall be deleted
  • Hints
    • Within the Contacts database, the table dbs contains the names of files once imported.
    • The database name, here: innovaphone.com_contacts can be retrieved from the settings within in the App Manager for the Contacts App.

Establish an SSH-session by means of e.g. putty[4]

  1. Login
  2. ===================================================================

login as: admin Using keyboard-interactive authentication. Password:

  1. Elevate to super-user rights, Command 'su'
  2. ===================================================================

admin@app-platform|/mnt/sda2/home/admin> su Password:

  1. Command 'psql'. Printing the table 'dbs'. Contains 2 file names.
  2. ===================================================================

root@app-platform|/mnt/sda2/home/admin> psql -d "innovaphone.com_contacts" -c "select * from dbs"

id |         uri

+----------------------

 1 | allcontacts.csv
 5 | brs%20testimport.csv

(2 rows)

  1. Delete the file "brs%20testimport.csv" via its table-ID 5.
  2. ===================================================================

root@app-platform|/mnt/sda2/home/admin> psql -d "innovaphone.com_contacts" -c "delete from dbs where id=5" DELETE 1


  1. Printing the table 'dbs'. Contains 1 file name.
  2. ===================================================================

root@app-platform|/mnt/sda2/home/admin> psql -d "innovaphone.com_contacts" -c "select * from dbs"

id |       uri

+-----------------

 1 | allcontacts.csv

(1 row)

root@app-platform|/mnt/sda2/home/admin>

Manually Deleting all Contacts

Sometimes it may become necessary to delete all contacts from the database. This task can be accomplished by simply deleting the main table entries. The deletion will cascade from there into all sub-tables.

  • The database name, here: innovaphone.com_contacts can be retrieved from the settings within in the App Manager for the Contacts App.

Establish an SSH-session by means of e.g. putty[5]

  1. Login
  2. ===================================================================

login as: admin Using keyboard-interactive authentication. Password:

  1. Elevate to super-user rights, Command 'su'
  2. ===================================================================

admin@app-platform|/mnt/sda2/home/admin> su Password:

  1. List number of contacts in main table entries
  2. ===================================================================

root@app-platform|/mnt/sda2/home/admin> psql -d "innovaphone.com_contacts" -c "select count(*) from entries"

count

   94

(1 row)

  1. Delete
  2. ===================================================================

root@app-platform|/mnt/sda2/home/admin> psql -d "innovaphone.com_contacts" -c "delete from entries *" DELETE 94

  1. List number of contacts in main table entries
  2. ===================================================================

root@app-platform|/mnt/sda2/home/admin> psql -d "innovaphone.com_contacts" -c "select count(*) from entries"

count

    0

(1 row)

Manually Exporting all Contacts

Sometimes it may become necessary to export all contacts from the database. This task can be accomplished by reading the main table entries, separate attributes by ; and store the result in a given csv-file. The csv-file has to be located in a separate folder with appropriate access rights.

  • The database name, here: innovaphone.com_contacts can be retrieved from the settings within in the App Manager for the Contacts App.

Establish an SSH-session by means of e.g. putty[6]

  1. Login
  2. ===================================================================

login as: admin Using keyboard-interactive authentication. Password:

  1. Elevate to super-user rights, Command 'su'
  2. ===================================================================

admin@app-platform|/mnt/sda2/home/admin> su Password:

  1. create new folder export and grant access rights

root@app-platform|/mnt/sda2/home/admin> mkdir export root@app-platform|/mnt/sda2/home/admin> chmod 777 export

  1. Retrieve all database entries, separate them by ; and store in file
  2. ===================================================================

root@app-platform|/mnt/sda2/home/admin> psql -d "innovaphone.com_contacts" -c "copy entries to '/mnt/sda2/home/admin/export/contacts.csv' delimiter ';' CSV HEADER"

The generated csv-file can be downloaded by use of an sftp-client (e.g. WinSCP) and login to the AP with admin credentials.


Known Issues

Related Articles

  1. For a windows distribution: e.g.: https://curl.haxx.se/download.html
  2. CURL is recommended(rather required), because it supports the simple POST mechanism with an initial tentative POST with the data length of 0, in order to get through the authentication phase
  3. Meta attribute: Here an attribute with a special meaning and that is non-physical, not existing within the database
  4. putty: https://putty.org
  5. putty: https://putty.org
  6. putty: https://putty.org