Course13:IT Connect - 09.0 Contacts

From innovaphone wiki
Revision as of 16:59, 12 February 2019 by Sga (talk | contribs)
Jump to navigation Jump to search

Book on Contacts App

The Contacts App

The Contacts App allows you to upload your contacts and provide them to other Apps and phones:
  • the PBX will augment incoming and outgoing call information with a name-id by looking up the calling/called party-id in Contacts (and add them to the CDR information)
  • the phone App will use Contacts to lookup names for outgoing calls as well as retrieve detail information for incoming calls)
  • the IP phones will use Contacts (via LDAP) to do name resolution for incoming and outgoing calls

Create contact entries manually

Before Contacts can provide your contact information to Apps and phones, you have to create them. The easiest way to generate entries is to create them manually.

Please open your screenshot.png Contacts App and click on the screenshot.png +Contact icon on the right side.

A drop-down menu is displayed in the upper part of the new window. screenshot.png In this dropdown menu you can select for which directory you want to create a contact. At the moment there is no other directory than your own personal directory so we will use this for now.

screenshot.png In the Numbers section of this window you can assign different numbers, SIP URIs or email addresses to this contact.You can assigne different attributes like Work, Private or Mobile to this numbers in order to distinguish them from each other. To add more properties to a user, you can click screenshot.png the +Property icon and select an attribute to add.

screenshot.png In the Common section of this window you can set the basic settings of this contact such as Name, Surname and Company name. Underneath you can screenshot.png set an optional address of this contact.

If you click screenshot.png on +Field you can set screenshot.png even more parameters for this contact like a private address or screenshot.png further details.

Please create a entry which the following properties
  • Work: +1-632-555-0105
  • Mobile: +1-917-987654
  • Email: clark.kent@dailyplanet.net
  • Name: Clark
  • Surname: Kent
  • Company: Daily Planet
  • Street: 2525 Broadway
  • ZIP Code: 10025
  • City: Metropolis
  • State: NY
  • Country: USA
  • Details->Department: Newsroom
  • Details->Info: He is Superman
  • Details->URL: www.dailyplanet.net
Please screenshot.png use the search function of contacts to find Clark.

Uploading contact information

Another possibility to enter contacts to your Contacts App is uploading a CSV file. Please note that the CSV file upload feature is only part of your Contacts Admin app. This App should be available to administrators only and is therefor enabled screenshot.png in the list of Apps in the Config Admin template.

As we have seen before with other Apps, Contacts also has an API that allows other Apps to access contact information. This is known as Contacts-SearchApi in the list of Apps and it is ticked in the Config User template so that all users have access to it.

Add the Contacts-Admin App to your home screen and start it.

Searching for names does not make sense at this point, as only your manually created name can be found.

But you can video2.png import a sample CSV file which we have prepared (download https://class.innovaphone.com/moodle2/pix/f/web.gif contact-sample.utf8 and save it to your computer):
  • in myApps, start Contacts Admin (you may want to open it in a separate window)
  • click on the hamburger menu on the upper right
  • click on + Import Contacts
  • select contact-sample.utf8 from your computer
  • confirm the will overwrite ... question
  • type an e in to the search field
  • and eh voilà, you get screenshot.png the result
(Further Hints) Please note that you cannot upload contacts via a .csv file into a personal directory.

Phone number format

You need to maintain the phone numbers in your directory in a proper format so that both dialing them from the directory (forward lookup) and resolving incoming numbers to names (reverse lookup) work well. This is true for both the manually created entries and numbers from the CSV file. Please keep that in mind when you instruct users.

Fortunately, the rules are not that difficult:
  • numbers must be full international numbers including country code, area code (if you have them in your country) and subscriber number
  • it must start with a plus sign (+)
  • all sort of decoration (such as parentheses (), dashes -, white space etc.) are allowed
  • an extra 0 preceding the area code is ok
  • there must be no international (00) or national (0) access codes
For example, all of these examples
  • +49 (7031) 73009-0
  • +49(7031)73009-0
  • +497031730090
  • +49/7031/730090
  • +49 (07031) 73009-0
  • +49 07031 73009 0
  • +49 (0) 703173009-0
are OK and represent the same phone number.

However
  • +0049 (7031) 73009-0 (bad international access code 00)
  • 0049 (7031) 73009-0 (no +)
  • 07031 73009-0 (missing country code)
  • +49 7031 73009#0 (# and * are not valid decoration)
are not OK.

Note that some of these formats can still be dialed but reverse lookup will not work.

Maintaining a Contacts File

An input file for Contacts is basically a semicolon (;) separated CSV file.

The first line of this file must contain predefined column headers as follows:

givenname;sn;company;displayname;email;telephonenumber;mobile;...;url;sip

The following lines contain the contact data and must have the same column order as the first line has. The order of the columns does not matter as long as all lines follow the same order. Also, you can remove entire columns (from both the header and the data lines).

This is a quite familiar file structure known as comma separated values (CSV) file. However, one thing makes it a bit difficult: its content must be encoded as UTF8. This is why our sample file uses file extension .utf8.

If you can handle this, it is the format to go with. However, if you think you could easily open and edit this with Excel, then the answer "is No, unfortunately not". The reason for this is that Excel expects the file to be encoded differently. If you try to open it with Excel anyway, you will see that the screenshot.png names look strange in parts. Newer Excel versions (2016 and up) can handle UTF8, but it is less than obvious how to work with this.

Using Excel

Many people do prefer using Excel however. This can be done using a real Excel file where the contact data is maintained. We provide it as https://class.innovaphone.com/moodle2/pix/f/excel.gif contacts.sample.xls. You can download it to your computer.

This file (should be compatible down to Excel 97, we tested it down to Excel 2010) can be edited as usual with Excel screenshot.png without any encoding hassle.

However, you can't upload the file to Contacts. Instead, when you're done editing in Excel, you would click on the Save as UTF8 button which creates an UTF8 CSV file version of your excel file. You can then upload this file.


Maintaining the column headers

The first lines (before the empty line) are considered column headers. You can use Excel's hide row function to hide the header rows in the languages you are not interested in (and also the first line that contains the technical column headers we talked about before). You could even remove these lines, except for the first line and the empty line that follows the header lines. We therefore recommend to rather hide the lines so you do not run the risk of accidentally deleting the wrong ones.

If you do not need a column, you can either hide or delete it (except for the extAnchor column which can be hidden but not deleted, see below).

You can even re-order the columns to better suit your needs.

Using the extAnchor column

When you have a closer look at the provided Excel file, you will notice that the first column (A) is hidden. If you un-hide it, you will see that it has extAnchor as column header.

This column (as described in fish-help.png Concept App Service Contacts) serves to identify a specific entry so that Contacts can relate the line to its internal database entries. Fortunately, you do not need to maintain it yourself. Instead, the Save as UTF8 button will do it for you. The only thing you need to understand is that this column needs to be present in your Excel file. So best just hide it again and forget about it then wink.

Importing contacts from Outlook

Outlook can export contact data to a .csv file. However, it also does not use UTF8 and besides that, the export process is tedious and slow.

But you can simply copy and paste your contact data to Excel. The way to go is as follows:
  • open your contacts in Outlook
  • switch to the List view
  • open your contacts XLS file
  • arrange the columns so that they match the column order in your Outlook view
  • copy the desired contacts
  • paste them in to Excel

Using multiple sources

You can maintain your contacts in multiple sources (for example, you have an Excel file per department). When you upload a file, Contacts will check if this file name already exists. If it does, Contacts removes any existing entries uploaded from a previous CSV file with the same filename and adds new entries. If you upload a file with a different name, a second directory is created.

So when you maintain several files with different names, you can upload some of them individually without doing harm to contacts that originate from another file.


Sharing a directory

You can see all directories video2.png by clicking the Burger Menu and then Directories in your Contacts Admin app. screenshot.png A list of all personal and CSV file directories is displayed.

If you click on the screenshot.png +Directory icon, you can create directory which can then be used as a shared personal directory.

Please create a directory named soccer club. Next, add a teammate to your soccer club screenshot.png by clicking the +Contact icon and screenshot.png select the soccer club directory from the drop down menu. For simplicity, just screenshot.png add the name and number of a contact you like.

As a next step, we want to share this phone-book with Mario Rossi, as he wants to see all contacts of the soccer club as well.

To do this, let's go back to our directories and add a rule for our soccer club. screenshot.png Select the Type User and add mro from the dropdown menu. Afterwards please save.

If you log in to Mario's myApps you can open his Contacts App and search for the newly created entry. This will be successful. To log into Mario's myApps please use a different browser than you already use. Browse to http://hq.dvl-ckl2.net and use the Username and Password you configured for Mario in the Users Admin App. Afterwards you need to confirm your login attempt for the two factor authentication. Therefore, go to link_intern.png training-mail.innovaphone.com: owa and use the following credentials to log in and click the confirm link in your received mail:

Email username: mario.rossi.dvl-ckl2@class.local
Email password: ckl-pw

If you want to add a contact from Mario's Contacts app to the Soccer club directory, you will not be successful. Mario does not have sufficient rights to do this.

In order to give Mario rights to add contacts to your soccer club directory, you need to enable screenshot.png the Admin checkmark in his rule. Once you activated it, you will see a screenshot.png shield icon as it is the case with your user. Any user with this icon can add, edit or delete contacts in this directory.



Sharing a directory with a group

You can also share a directory with a PBX group. This is not that difficult but we first need to create this group in the PBX so we can use it for this purpose.

screenshot.png Please open the Groups plugin in PBX Manager and create a group called soccer. screenshot.png Add Lisa and Jean as active members to this group. The active membership is important in this case.

Going back to our soccer club directory in our Contacts Admin app (Burger Menu/Directories),we can now create a new rule. This rule should allow every member of the PBX group access to the soccer club directory. Therefore please click on +Rule and select the Type Group. Select the group soccer from the dropdown menu. screenshot.png Afterwards please save this rule.

To see if this configuration is working you have to log in to Lisa's or Jean's myApps. We recommend to use another browser for this. Browse to http://hq.dvl-ckl2.net and use the Username and Password you configured for Lisa or Jean in the Users Admin App. Afterwards you need to confirm your login attempt for the two factor authentication. Therefore, go to link_intern.png training-mail.innovaphone.com: owa and use the following credentials to log in and click the confirm link in your received mail:

Email username: jean.dupont.dvl-ckl2@class.local
Email password: ckl-pw

or

Email username: lisa.svensson.dvl-ckl2@class.local
Email password: ckl-pw

If you search for the contact entry you created for the soccer club, you will be successful.

Personal directories versus imported files

If you compare the screenshot.png access rights for an imported CSV such as contacts-sample.utf8 to the screenshot.png access rights for a personal directory, you will notice that the imported CSV directory simply has defined no access right at all. In contrast to that, the personal only has a single rule, which is screenshot.png yourself as a user with Admin rights.

(Further Hints) A directory with no access rules at all is available to anyone but cannot be edited by anybody, except when using the Contacts Admin App (which usually is restricted to administrators). An imported CSV is created this way.

(Further Hints) A personal directory is an ordinary directory with only a single access rule specifying yourself with Admin rights. It is created implicitly for each user (that is, you do not need to create it explicitly).

Directories and PBX reverse lookup

When the PBX performs a reverse lookup to find a name id for an incoming CDPN or CGPN, it will send the user information to the Contacts LDAP server along with the search request.

(Further Hints) In other words, the name resolution in the PBX takes into account all directories that are available to the user.