innovaphone wiki - User contributions [en]

Reference16r1:Concept LDAP Replication

2026-03-27T14:22:45Z

Inno-mst: updated

LDAP replication concepts, mainly the differences between full- and incremental replication are going to be covered within this article. The focus is on replication between PBXs.
= Glossary =
;Admin object: An LDAP DB object named "_ADMIN_".
;Config restore: The act of administratively uploading an configuration file to a box.
;Epoch: A ''RootDSE'' value. The current value of the GUID of the ''Admin object''.
;Flashdir, Flashman: Flash Directory, Flash Manager with Flashdir sitting on-top of Flashman. The Flashdir exchanges API messages with the Flashman to persistently add, replace, and delete LDAP objects.
;Full Replication: Every object is going to be queried by replication partners.
;GUID: A unique 16-byte value. Every object contains an attribute ''GUID''.
;Incremental Replication: Only objects written since a last-known point in time will be queried.
;Master: The replication partner acting as an LDAP server.
;Notify Search: A single LDAP search remains active until a cancellation. A server responds to it with multiple search responses for all objects being modified after the notify search was received.
;Paged Search/Paging: A means to iterate over an entire database in chunks or pages of a fixed maximum size.
;Replication Filter: A static LDAP filter supposed to be active during a replication session.
;RootDSE (Root Directory Service Entry)
: Directory-specific entry. A collection of properties and capabilities that can be read by any LDAP client. The RootDSE is accessible without authentication and by providing a special search filter.
;Slave: The replication partner acting as an LDAP client.
;Tombstones, isDeleted: Deleted objects aren't deleted immediately from storage. Instead, such objects are marked with an attribute ''isDeleted''.
;USN (Update sequence number)
: Unique value incremented by 1 on every write. It is unique within every local LDAP DB.
;RUSN (Remote update sequence number)
: Unique value over the whole system over all LDAP DBs.
; RWR (Replication Write)
: Optional attribute on an object that is incremented by 1 on every update on a slave locally. Indicator that these changes have to be committed to the upper ldap master.

= Technical concept of replication as client =
The replication of a source via LDAP is basically divided into 3 phases that must be passed through when synchronization is started.

;1st phase ''remote''
The first phase is the "remote" phase and ensures a comparison of any delta between the remote data stock and the local data stock. (In other words, objects that are missing locally are created).

The LDAP client requests a paging version of all objects of the LDAP server. The client then receives back page by page (2 objects) per request. If necessary, objects in the local database are updated accordingly.

During this phase the following is shown in the status:
remote: Active
local: Completed

;2nd phase ''local''
The second phase is the "local" phase and ensures a comparison of any delta between the local data stock and the remote data stock. (In other words, objects that need to be deleted locally).

The LDAP client makes an LDAP query per local object (which it knows from its local database) based on the ''guid'' to the LDAP server. If the LDAP server knows this object, it returns the entire object so that the client can update the object locally if necessary. If the object does not exist in the LDAP server, it is removed locally.

During this phase, the status shows the following:
remote: Stopped
local: Active

;3rd phase ''notify''
The third phase is the "notify" phase, in which there is no longer an open delta between the two sources, and future changes are synchronised.
In this phase, a permanent TCP connection exists between the LDAP client and the LDAP server and is used for the LDAP server to notify the LDAP client when a change has occurred so that the client can create or update the record in the local database.

During this phase, the status will show the following:
remote: Completed
local: Completed

It is important to note that:
* if a problem occurs (e.g. due to the interruption of a phase or e.g. loss of the TCP connection to the LDAP server) the synchronisation starts again from the first phase ("local")
* the local attribute ''usn'' will not be replicated. Each ldap node manages its own local ''usn''
* if you use a configured [[{{NAMESPACE}}:Services/LDAP/Replicator|''Poll Timer'']] the notify feature will not be used in this ldap session

=Algorithmic and Technical Details=
This section covers details the incremental replication is based on, enabling the transition from full- to incremental replication and back from incremental- to full replication.
==epoch==
The master's Root DSE contains or does not contain an attribute '''epoch''', reflecting the GUID attribute of an existing object by the name '''_ADMIN_'''. A slave must permanently store the epoch as a persistent VARiable '''epoch'''.
*Slave connects and BINDs to master
*Slave requests Root DSE from master
*Slave evalutates ''epoch''
**''epoch'' is not present
***=>Full replication
***Store copy of ''epoch''
**''epoch'' is present
***''epoch'' matches slave's copy
****=>Incremental replication
***''epoch'' does not match slave's copy
****Delete copy of ''epoch''
****=>Full replication
****Store copy of ''epoch''
*Slave, persistent ''epoch'' storage
**Variable: '''LDAPI/epoc-r/cn=PBX0'''

==USN Processing==
Every object features the attribute '''USN'''. A slave keeps track of the highest USN seen within all objects rx'ed from a master.
*Slave checks USN for objects rx'ed from master
**No local record of a highest USN
***=> Store current USN as highest USN
**Local copy of highest USN existing
***RX'ed USN greater than local USN copy
****=> Store current USN as highest USN
***RX'ed USN less or equal than local USN copy
****=> NOP, nothing to be done

*Slave, persistent USN storage
**Replication completed - at the end of a full or incremental replication. Also, when rx'ing notify search results from a master.
***=> Persistently storing the volatile memorized highest USN
**Variable: '''LDAPI/r-usn/cn=PBX0'''

==Paging==
Incremental paging requires an additional filter term spedifying a USN value.
*1st Search
**Slave
***Filter (&(objectclass=*)'''(usn>=103)''') The USN-Term contains the highest USN rx'ed during last replication run, plus 1.
***Cookie <empty>
**Server
***Evaluate '''(usn>=103)''' and set cursor at corresponding item
***Replies with entries and non-empty(more) or empty(final) cookie

*2nd Search,..
**Slave
***Filter (objectclass=*)
***Cookie <Last Cookie content rx'ed from server>
**Server
***Evaluate cookie and set cursor at corresponding item
***Replies with entries and non-empty(more) or empty(final) cookie

==Root DSE==
Because of the Flash Directory also exporting some infos into the Root DSE it probably makes sense to inform there about the current GUID of the ''_admin_'' object. Following excerpt represents this by an attribute '''epoch'''. A slave can comfortably compare this to its copy of the epoch last seen.
<pre>
Getting 1 entries:
>> Dn:
1> epoch: 0B1581AF783F67018F170050568214B4;
..
1> ldapServiceName: IP6013-50-00-68;
</pre>

==VARs==
Noteable variables for persistent storage of some replication control data within a slave's VARs section.
;Remote highest rusn:
vars create LDAPI/r-rusn/cn=PBX0 p 102

;Remote highest usn:
vars create LDAPI/r-usn/cn=PBX0 p 548

;Remote last seen epoch, saved per view:
vars create LDAPI/epoc-r/cn=KPBX0 pb 5238705224c067016fd10090334117be
vars create LDAPI/epoc-r/cn=PBX0 pb 5238705224c067016fd10090334117be

==Restore on Master==
A mechanism provides information by a replication master to replication slaves that a full replication run shall take place. That mechanism gets triggered by an upload of a configuration to a master. A restore of an older configuration on a master causes a new GUID for the object with the name ''_ADMIN_''.
*A new configuration is going to be uploaded
*The Flash Directory processes the module command <pre>mod cmd FLASHDIR0 erase-all</pre>
**The FLASH Directory erases it's entire database, awaiting further commands
*The FLASH Directory processes a module command <pre>mod cmd FLASHDIR0 add-item 102 (cn=_ADMIN_)..(guid;bin=5238705224C067016FD10090334117BE)</pre>
**This is the Admin object. Before being stored, it will now get assigned a new random GUID
*The Admin object's new GUID gets now promoted as the new ''epoch'' for the master's database. Replication slave's are supposed to detect a change of the DB's epoch and to replicate in full.

==Detecting Obsolete Objects==
Objects with the isDeleted attribute, a.k.a. tombstones, shall persist ideally forever. In practice tombstones get erased after a timeout. Only the most recent tombstone (tombstone with highest USN) remains.
;Current tombstone timeout: 48 hours
===Behaviour during Full Replication===
The local phase takes place in full. The replicator pages over all local objects and compares them with the master to see if they are still present.
===Behaviour during Incremental Replication===
The local phase is completely eliminated, respectively skipped.

Reference16r1:Concept LDAP Replication

2025-03-21T17:10:42Z

Inno-mst: Incremental replication postponed for 15r1

'''Note: The feature has not successfully passed through our quality assurance process yet and will therefore not be included in the 15r1 final release. However, we will release this feature separately at a later date. Up until further notice or until removal of this note, please refer to a pre-15r1 version of this article.'''

LDAP replication concepts, mainly the differences between full- and incremental replication are going to be covered within this article. The focus is on replication between PBXs.

= Glossary =
;Admin Object: An LDAP DB object named "_ADMIN_".
;Config Restore: The act of administratively uploading an old configuration to a box. Can be accomplished via the firmware's maintenance UI or in-part via a PBX UI.
;Epoch: A Root DSE value. The current value of the GUID of the object Admin object.
;Flashdir, Flashman: Flash Directory, Flash Manager with Flashdir sitting on-top of Flashman. The Flashdir exchange API messages with the Flashman to persistently add, replace, delete LDAP objects.
;Full Replication: Every object is going to be queried and or handled by replication partners.
;GUID: A unique 16-byte value. Every object contains an attribute GUID.
;Incremental Replication: Only objects written since a last-known point in time will be queried and or handled.
;Master: The replication partner acting as an LDAP server.
;Notify Search: A single LDAP search remaing active until a cancellation. A server responds to it with multiple search responses for all objects being modified after the notify search was received.
;Paged Search/Paging: A means to iterate over an entire database in chunks or pages of a fixed maximum size.
;Replication Filter: A static LDAP filter supposed to be active during a replication session.
;Root DSE: Directory-specific entry. A collection of few properties and capabilities that can be read by any LDAP client. The Root DSE is accessible without authentication and by providing a special search filter.
;Slave: The replication partner acting as an LDAP client.
;Tombstones, isDeleted: Deleted objects aren't deleted immediately from storage. Instead, such objects are marked with an attribute isDeleted.
;USN: Update Sequence Number, a 64-bit value incremented by 1 on every write. It is deemed to never wrap-around and to be unique within an LDAP DB. Every object contains an attribute USN.

= Technical concept of replication as client =
The replication of a source via LDAP is basically divided into 3 phases that must be passed through when synchronization is started.

;1st phase ''local''
The first phase is the "local" phase and ensures a comparison of any delta between the local data stock and the remote data stock. (In other words, objects that need to be deleted locally).

The LDAP client makes an LDAP query per local object (which it knows from its local database) based on the ''guid'' to the LDAP server. If the LDAP server knows this object, it returns the entire object so that the client can update the object locally if necessary. If the object does not exist in the LDAP server, it is removed locally.

During this phase, the status shows the following:
remote: Stopped
local: Active

;2nd phase ''remote''
The second phase is the "remote" phase and ensures a comparison of any delta between the remote data stock and the local data stock. (In other words, objects that are missing locally are created).

The LDAP client requests a paging version of all objects of the LDAP server. The client then receives back page by page (2 objects) per request. If necessary, objects in the local database are updated accordingly.

During this phase the following is shown in the status:
remote: Active
local: Completed

;3rd phase ''notify''
The third phase is the "notify" phase, in which there is no longer an open delta between the two sources, and future changes are synchronised.
In this phase, a permanent TCP connection exists between the LDAP client and the LDAP server and is used for the LDAP server to notify the LDAP client when a change has occurred so that the client can create or update the record in the local database.

During this phase, the status will show the following:
remote: Completed
local: Completed

It is important to note that:
* if a problem occurs (e.g. due to the interruption of a phase or e.g. loss of the TCP connection to the LDAP server) the synchronisation starts again from the first phase ("local")
* the local attribute ''usn'' will not be replicated. Each ldap node manages its own local ''usn''
* if you use a configured [[{{NAMESPACE}}:Services/LDAP/Replicator|''Poll Timer'']] the notify feature will not be used in this ldap session

=Algorithmic and Technical Details=
This section covers details the incremental replication is based on, enabling the transition from full- to incremental replication and back from incremental- to full replication.
==epoch==
The master's Root DSE contains or does not contain an attribute '''epoch''', reflecting the GUID attribute of an existing object by the name '''_admin_'''. A slave must permanently store the epoch as a persistent VARiable '''epoch'''.
*Slave connects and BINDs to master
*Slave requests Root DSE from master
*Slave evalutates ''epoch''
**''epoch'' is not present
***=>Full replication
***Store copy of ''epoch''
**''epoch'' is present
***''epoch'' matches slave's copy
****=>Incremental replication
***''epoch'' does not match slave's copy
****Delete copy of ''epoch''
****=>Full replication
****Store copy of ''epoch''
*Slave, persistent ''epoch'' storage
**Variable: '''LREPI/epoc-r/cn=PBX0'''

==USN Processing==
Every object features the attribute '''USN'''. A slave keeps track of the highest USN seen within all objects rx'ed from a master.
*Slave checks USN for objects rx'ed from master
**No local record of a highest USN
***=>Store current USN as highest USN
**Local copy of highest USN existing
***RX'ed USN greater than local USN copy
****=>Store current USN as highest USN
***RX'ed USN less or equal than local USN copy
****=>NOP, nothing to be done

*Slave, persistent USN storage
**Replication completed - at the end of a full or incremental replication. Also, when rx'ing notify search results from a master.
***=>Persistently storing the volatile memorized highest USN
**Variable: '''LREPI/u-r/cn=PBX0'''

==Paging==
Incremental paging requires an additional filter term spedifying a USN value.
*1st Search
**Slave
***Filter (&(objectclass=*)'''(usn>=103)''') The USN-Term contains the highest USN rx'ed during last replication run, plus 1.
***Cookie <empty>
**Server
***Evaluate '''(usn>=103)''' and set cursor at corresponding item
***Replies with entries and non-empty(more) or empty(final) cookie

*2nd Search,..
**Slave
***Filter (objectclass=*)
***Cookie <Last Cookie content rx'ed from server>
**Server
***Evaluate cookie and set cursor at corresponding item
***Replies with entries and non-empty(more) or empty(final) cookie

==Root DSE==
Because of the Flash Directory also exporting some infos into the Root DSE it probably makes sense to inform there about the current GUID of the ''_admin_'' object. Following excerpt represents this by an attribute '''epoch'''. A slave can comfortably compare this to its copy of the epoch last seen.
<pre>
Getting 1 entries:
>> Dn:
1> epoch: 0B1581AF783F67018F170050568214B4;
..
1> ldapServiceName: IP6013-50-00-68;
</pre>

==VARs==
Noteable variables for persistent storage of some replication control data within a slave's VARs section.
;LDAP Replication, remote highest USN:
<pre>
vars create LREPI/u-r/cn=PBX0 p 102
..
vars create LREPI/u-r/cn=KBX0 p 105
</pre>
;LDAP Replication, remote last seen epoch:
<pre>
vars create LREPI/epoc-r/cn=KPBX0 pb 5238705224c067016fd10090334117be
..
vars create LREPI/epoc-r/cn=PBX0 pb 5238705224c067016fd10090334117be
</pre>

==Restore on Master==
A mechanism provides information by a replication master to replication slaves that a full replication run shall take place. That mechanism gets triggered by an upload of a configuration to a master. A restore of an older configuration on a master causes a new GUID for the object with the name ''_ADMIN_''.
*A new configuration is going to be uploaded
*The Flash Directory processes the module command <pre>mod cmd FLASHDIR0 erase-all</pre>
**The FLASH Directory erases it's entire database, awaiting further commands
*The FLASH Directory processes a module command <pre>mod cmd FLASHDIR0 add-item 102 (cn=_ADMIN_)..(guid;bin=5238705224C067016FD10090334117BE)</pre>
**This is the Admin object. Before being stored, it will now get assigned a new random GUID
*The Admin object's new GUID gets now promoted as the new ''epoch'' for the master's database. Replication slave's are supposed to detect a change of the DB's epoch and to replicate in full.

==Detecting Obsolete Objects==
Objects with the isDeleted attribute, a.k.a. tombstones, shall persist ideally forever. In practice tombstones get erased after a timeout. Only the most recent tombstone (tombstone with highest USN) remains.
;Current tombstone timeout: 48 hours
===Behaviour during Full Replication===
The local phase takes place in full. The replicator pages over all local objects and compares them with the master to see if they are still present.
===Behaviour during Incremental Replication===
The local phase is completely eliminated, respectively skipped.

Reference15r1:Services/LDAP/Rep-Status

2025-03-18T09:04:08Z

Inno-mst: simplifying

The displayed '''replicator status''' updates every few seconds. The last ten activity messages of the replication are displayed below.

== Status overview ==

'''Server:''' IP-address and port of the remote LDAP server.

'''Full/Incremental Replication:''' Current state of the replication. The states are: ''Stop'', ''Starting'', ''Up'', ''Down, Completed''.

'''remote:''' Displays the state of the replication in poll direction.

'''notify:''' Number of received notifications.

'''modify:''' Number of modified objects.

'''paged:''' Number of objects received from remote directory server in response to paged-search requests.

'''no match:''' (AD-Only) Number of objects received and not matching the LDAP filter condition entered under Configuration/LDAP/Replicator.

'''discarded:''' (AD-Only) Number of objects discarded, because there was no suitable MAP found.

'''local:''' Displays the state of the replication in push direction.

'''add:''' Number of locally added objects.

'''del:''' Number of locally deleted objects.

'''paged:''' Number of objects received from local flash directory in response to paged-search requests.

'''modify:''' Number of locally modified objects.

'''notify:''' Number of notifications that have arisen locally.

'''pending:''' Number of locally waiting objects.

=Related Articles=
* [[{{NAMESPACE}}:Concept LDAP Replication]]

Reference16r1:Concept LDAP Replication

2025-03-18T08:47:25Z

Inno-mst: /* Restore on Master */ Detailing intro and outro

LDAP replication concepts, mainly the differences between full- and incremental replication are going to be covered within this article. The focus is on replication between PBXs.
= Glossary =
;Admin Object: An LDAP DB object named "_ADMIN_".
;Config Restore: The act of administratively uploading an old configuration to a box. Can be accomplished via the firmware's maintenance UI or in-part via a PBX UI.
;Epoch: A Root DSE value. The current value of the GUID of the object Admin object.
;Flashdir, Flashman: Flash Directory, Flash Manager with Flashdir sitting on-top of Flashman. The Flashdir exchange API messages with the Flashman to persistently add, replace, delete LDAP objects.
;Full Replication: Every object is going to be queried and or handled by replication partners.
;GUID: A unique 16-byte value. Every object contains an attribute GUID.
;Incremental Replication: Only objects written since a last-known point in time will be queried and or handled.
;Master: The replication partner acting as an LDAP server.
;Notify Search: A single LDAP search remaing active until a cancellation. A server responds to it with multiple search responses for all objects being modified after the notify search was received.
;Paged Search/Paging: A means to iterate over an entire database in chunks or pages of a fixed maximum size.
;Replication Filter: A static LDAP filter supposed to be active during a replication session.
;Root DSE: Directory-specific entry. A collection of few properties and capabilities that can be read by any LDAP client. The Root DSE is accessible without authentication and by providing a special search filter.
;Slave: The replication partner acting as an LDAP client.
;Tombstones, isDeleted: Deleted objects aren't deleted immediately from storage. Instead, such objects are marked with an attribute isDeleted.
;USN: Update Sequence Number, a 64-bit value incremented by 1 on every write. It is deemed to never wrap-around and to be unique within an LDAP DB. Every object contains an attribute USN.

= Technical concept of replication as client =
The replication of a source via LDAP is basically divided into 3 phases that must be passed through when synchronization is started.

;1st phase ''local''
The first phase is the "local" phase and ensures a comparison of any delta between the local data stock and the remote data stock. (In other words, objects that need to be deleted locally).

The LDAP client makes an LDAP query per local object (which it knows from its local database) based on the ''guid'' to the LDAP server. If the LDAP server knows this object, it returns the entire object so that the client can update the object locally if necessary. If the object does not exist in the LDAP server, it is removed locally.

During this phase, the status shows the following:
remote: Stopped
local: Active

;2nd phase ''remote''
The second phase is the "remote" phase and ensures a comparison of any delta between the remote data stock and the local data stock. (In other words, objects that are missing locally are created).

The LDAP client requests a paging version of all objects of the LDAP server. The client then receives back page by page (2 objects) per request. If necessary, objects in the local database are updated accordingly.

During this phase the following is shown in the status:
remote: Active
local: Completed

;3rd phase ''notify''
The third phase is the "notify" phase, in which there is no longer an open delta between the two sources, and future changes are synchronised.
In this phase, a permanent TCP connection exists between the LDAP client and the LDAP server and is used for the LDAP server to notify the LDAP client when a change has occurred so that the client can create or update the record in the local database.

During this phase, the status will show the following:
remote: Completed
local: Completed

It is important to note that:
* if a problem occurs (e.g. due to the interruption of a phase or e.g. loss of the TCP connection to the LDAP server) the synchronisation starts again from the first phase ("local")
* the local attribute ''usn'' will not be replicated. Each ldap node manages its own local ''usn''
* if you use a configured [[{{NAMESPACE}}:Services/LDAP/Replicator|''Poll Timer'']] the notify feature will not be used in this ldap session

=Algorithmic and Technical Details=
This section covers details the incremental replication is based on, enabling the transition from full- to incremental replication and back from incremental- to full replication.
==epoch==
The master's Root DSE contains or does not contain an attribute '''epoch''', reflecting the GUID attribute of an existing object by the name '''_admin_'''. A slave must permanently store the epoch as a persistent VARiable '''epoch'''.
*Slave connects and BINDs to master
*Slave requests Root DSE from master
*Slave evalutates ''epoch''
**''epoch'' is not present
***=>Full replication
***Store copy of ''epoch''
**''epoch'' is present
***''epoch'' matches slave's copy
****=>Incremental replication
***''epoch'' does not match slave's copy
****Delete copy of ''epoch''
****=>Full replication
****Store copy of ''epoch''
*Slave, persistent ''epoch'' storage
**Variable: '''LREPI/epoc-r/cn=PBX0'''

==USN Processing==
Every object features the attribute '''USN'''. A slave keeps track of the highest USN seen within all objects rx'ed from a master.
*Slave checks USN for objects rx'ed from master
**No local record of a highest USN
***=>Store current USN as highest USN
**Local copy of highest USN existing
***RX'ed USN greater than local USN copy
****=>Store current USN as highest USN
***RX'ed USN less or equal than local USN copy
****=>NOP, nothing to be done

*Slave, persistent USN storage
**Replication completed - at the end of a full or incremental replication. Also, when rx'ing notify search results from a master.
***=>Persistently storing the volatile memorized highest USN
**Variable: '''LREPI/u-r/cn=PBX0'''

==Paging==
Incremental paging requires an additional filter term spedifying a USN value.
*1st Search
**Slave
***Filter (&(objectclass=*)'''(usn>=103)''') The USN-Term contains the highest USN rx'ed during last replication run, plus 1.
***Cookie <empty>
**Server
***Evaluate '''(usn>=103)''' and set cursor at corresponding item
***Replies with entries and non-empty(more) or empty(final) cookie

*2nd Search,..
**Slave
***Filter (objectclass=*)
***Cookie <Last Cookie content rx'ed from server>
**Server
***Evaluate cookie and set cursor at corresponding item
***Replies with entries and non-empty(more) or empty(final) cookie

==Root DSE==
Because of the Flash Directory also exporting some infos into the Root DSE it probably makes sense to inform there about the current GUID of the ''_admin_'' object. Following excerpt represents this by an attribute '''epoch'''. A slave can comfortably compare this to its copy of the epoch last seen.
<pre>
Getting 1 entries:
>> Dn:
1> epoch: 0B1581AF783F67018F170050568214B4;
..
1> ldapServiceName: IP6013-50-00-68;
</pre>

==VARs==
Noteable variables for persistent storage of some replication control data within a slave's VARs section.
;LDAP Replication, remote highest USN:
<pre>
vars create LREPI/u-r/cn=PBX0 p 102
..
vars create LREPI/u-r/cn=KBX0 p 105
</pre>
;LDAP Replication, remote last seen epoch:
<pre>
vars create LREPI/epoc-r/cn=KPBX0 pb 5238705224c067016fd10090334117be
..
vars create LREPI/epoc-r/cn=PBX0 pb 5238705224c067016fd10090334117be
</pre>

==Restore on Master==
A mechanism provides information by a replication master to replication slaves that a full replication run shall take place. That mechanism gets triggered by an upload of a configuration to a master. A restore of an older configuration on a master causes a new GUID for the object with the name ''_ADMIN_''.
*A new configuration is going to be uploaded
*The Flash Directory processes the module command <pre>mod cmd FLASHDIR0 erase-all</pre>
**The FLASH Directory erases it's entire database, awaiting further commands
*The FLASH Directory processes a module command <pre>mod cmd FLASHDIR0 add-item 102 (cn=_ADMIN_)..(guid;bin=5238705224C067016FD10090334117BE)</pre>
**This is the Admin object. Before being stored, it will now get assigned a new random GUID
*The Admin object's new GUID gets now promoted as the new ''epoch'' for the master's database. Replication slave's are supposed to detect a change of the DB's epoch and to replicate in full.

==Detecting Obsolete Objects==
Objects with the isDeleted attribute, a.k.a. tombstones, shall persist ideally forever. In practice tombstones get erased after a timeout. Only the most recent tombstone (tombstone with highest USN) remains.
;Current tombstone timeout: 48 hours
===Behaviour during Full Replication===
The local phase takes place in full. The replicator pages over all local objects and compares them with the master to see if they are still present.
===Behaviour during Incremental Replication===
The local phase is completely eliminated, respectively skipped.

Reference16r1:Concept LDAP Replication

2025-03-18T08:36:19Z

Inno-mst: /* Algorithmic and Technical Details */

LDAP replication concepts, mainly the differences between full- and incremental replication are going to be covered within this article. The focus is on replication between PBXs.
= Glossary =
;Admin Object: An LDAP DB object named "_ADMIN_".
;Config Restore: The act of administratively uploading an old configuration to a box. Can be accomplished via the firmware's maintenance UI or in-part via a PBX UI.
;Epoch: A Root DSE value. The current value of the GUID of the object Admin object.
;Flashdir, Flashman: Flash Directory, Flash Manager with Flashdir sitting on-top of Flashman. The Flashdir exchange API messages with the Flashman to persistently add, replace, delete LDAP objects.
;Full Replication: Every object is going to be queried and or handled by replication partners.
;GUID: A unique 16-byte value. Every object contains an attribute GUID.
;Incremental Replication: Only objects written since a last-known point in time will be queried and or handled.
;Master: The replication partner acting as an LDAP server.
;Notify Search: A single LDAP search remaing active until a cancellation. A server responds to it with multiple search responses for all objects being modified after the notify search was received.
;Paged Search/Paging: A means to iterate over an entire database in chunks or pages of a fixed maximum size.
;Replication Filter: A static LDAP filter supposed to be active during a replication session.
;Root DSE: Directory-specific entry. A collection of few properties and capabilities that can be read by any LDAP client. The Root DSE is accessible without authentication and by providing a special search filter.
;Slave: The replication partner acting as an LDAP client.
;Tombstones, isDeleted: Deleted objects aren't deleted immediately from storage. Instead, such objects are marked with an attribute isDeleted.
;USN: Update Sequence Number, a 64-bit value incremented by 1 on every write. It is deemed to never wrap-around and to be unique within an LDAP DB. Every object contains an attribute USN.

= Technical concept of replication as client =
The replication of a source via LDAP is basically divided into 3 phases that must be passed through when synchronization is started.

;1st phase ''local''
The first phase is the "local" phase and ensures a comparison of any delta between the local data stock and the remote data stock. (In other words, objects that need to be deleted locally).

The LDAP client makes an LDAP query per local object (which it knows from its local database) based on the ''guid'' to the LDAP server. If the LDAP server knows this object, it returns the entire object so that the client can update the object locally if necessary. If the object does not exist in the LDAP server, it is removed locally.

During this phase, the status shows the following:
remote: Stopped
local: Active

;2nd phase ''remote''
The second phase is the "remote" phase and ensures a comparison of any delta between the remote data stock and the local data stock. (In other words, objects that are missing locally are created).

The LDAP client requests a paging version of all objects of the LDAP server. The client then receives back page by page (2 objects) per request. If necessary, objects in the local database are updated accordingly.

During this phase the following is shown in the status:
remote: Active
local: Completed

;3rd phase ''notify''
The third phase is the "notify" phase, in which there is no longer an open delta between the two sources, and future changes are synchronised.
In this phase, a permanent TCP connection exists between the LDAP client and the LDAP server and is used for the LDAP server to notify the LDAP client when a change has occurred so that the client can create or update the record in the local database.

During this phase, the status will show the following:
remote: Completed
local: Completed

It is important to note that:
* if a problem occurs (e.g. due to the interruption of a phase or e.g. loss of the TCP connection to the LDAP server) the synchronisation starts again from the first phase ("local")
* the local attribute ''usn'' will not be replicated. Each ldap node manages its own local ''usn''
* if you use a configured [[{{NAMESPACE}}:Services/LDAP/Replicator|''Poll Timer'']] the notify feature will not be used in this ldap session

=Algorithmic and Technical Details=
This section covers details the incremental replication is based on, enabling the transition from full- to incremental replication and back from incremental- to full replication.
==epoch==
The master's Root DSE contains or does not contain an attribute '''epoch''', reflecting the GUID attribute of an existing object by the name '''_admin_'''. A slave must permanently store the epoch as a persistent VARiable '''epoch'''.
*Slave connects and BINDs to master
*Slave requests Root DSE from master
*Slave evalutates ''epoch''
**''epoch'' is not present
***=>Full replication
***Store copy of ''epoch''
**''epoch'' is present
***''epoch'' matches slave's copy
****=>Incremental replication
***''epoch'' does not match slave's copy
****Delete copy of ''epoch''
****=>Full replication
****Store copy of ''epoch''
*Slave, persistent ''epoch'' storage
**Variable: '''LREPI/epoc-r/cn=PBX0'''

==USN Processing==
Every object features the attribute '''USN'''. A slave keeps track of the highest USN seen within all objects rx'ed from a master.
*Slave checks USN for objects rx'ed from master
**No local record of a highest USN
***=>Store current USN as highest USN
**Local copy of highest USN existing
***RX'ed USN greater than local USN copy
****=>Store current USN as highest USN
***RX'ed USN less or equal than local USN copy
****=>NOP, nothing to be done

*Slave, persistent USN storage
**Replication completed - at the end of a full or incremental replication. Also, when rx'ing notify search results from a master.
***=>Persistently storing the volatile memorized highest USN
**Variable: '''LREPI/u-r/cn=PBX0'''

==Paging==
Incremental paging requires an additional filter term spedifying a USN value.
*1st Search
**Slave
***Filter (&(objectclass=*)'''(usn>=103)''') The USN-Term contains the highest USN rx'ed during last replication run, plus 1.
***Cookie <empty>
**Server
***Evaluate '''(usn>=103)''' and set cursor at corresponding item
***Replies with entries and non-empty(more) or empty(final) cookie

*2nd Search,..
**Slave
***Filter (objectclass=*)
***Cookie <Last Cookie content rx'ed from server>
**Server
***Evaluate cookie and set cursor at corresponding item
***Replies with entries and non-empty(more) or empty(final) cookie

==Root DSE==
Because of the Flash Directory also exporting some infos into the Root DSE it probably makes sense to inform there about the current GUID of the ''_admin_'' object. Following excerpt represents this by an attribute '''epoch'''. A slave can comfortably compare this to its copy of the epoch last seen.
<pre>
Getting 1 entries:
>> Dn:
1> epoch: 0B1581AF783F67018F170050568214B4;
..
1> ldapServiceName: IP6013-50-00-68;
</pre>

==VARs==
Noteable variables for persistent storage of some replication control data within a slave's VARs section.
;LDAP Replication, remote highest USN:
<pre>
vars create LREPI/u-r/cn=PBX0 p 102
..
vars create LREPI/u-r/cn=KBX0 p 105
</pre>
;LDAP Replication, remote last seen epoch:
<pre>
vars create LREPI/epoc-r/cn=KPBX0 pb 5238705224c067016fd10090334117be
..
vars create LREPI/epoc-r/cn=PBX0 pb 5238705224c067016fd10090334117be
</pre>

==Restore on Master==
A restore of an older configuration on a master causes a new GUID for the object with the name ''_ADMIN_''.
*A new configuration is going to be uploaded
*The Flash Directory processes the module command <pre>mod cmd FLASHDIR0 erase-all</pre>
**The FLASH Directory erases it's entire database, awaiting further commands
*The FLASH Directory processes a module command <pre>mod cmd FLASHDIR0 add-item 102 (cn=_ADMIN_)..(guid;bin=5238705224C067016FD10090334117BE)</pre>
**This is the Admin object. Before being stored, it will now get assigned a new random GUID
*The Admin object's new GUID gets now promoted as the new ''epoch'' for the master's database

==Detecting Obsolete Objects==
Objects with the isDeleted attribute, a.k.a. tombstones, shall persist ideally forever. In practice tombstones get erased after a timeout. Only the most recent tombstone (tombstone with highest USN) remains.
;Current tombstone timeout: 48 hours
===Behaviour during Full Replication===
The local phase takes place in full. The replicator pages over all local objects and compares them with the master to see if they are still present.
===Behaviour during Incremental Replication===
The local phase is completely eliminated, respectively skipped.

Reference16r1:Concept LDAP Replication

2025-03-18T08:33:16Z

Inno-mst: Emphasized PBX replication: "The focus is on replication between PBXs."

LDAP replication concepts, mainly the differences between full- and incremental replication are going to be covered within this article. The focus is on replication between PBXs.
= Glossary =
;Admin Object: An LDAP DB object named "_ADMIN_".
;Config Restore: The act of administratively uploading an old configuration to a box. Can be accomplished via the firmware's maintenance UI or in-part via a PBX UI.
;Epoch: A Root DSE value. The current value of the GUID of the object Admin object.
;Flashdir, Flashman: Flash Directory, Flash Manager with Flashdir sitting on-top of Flashman. The Flashdir exchange API messages with the Flashman to persistently add, replace, delete LDAP objects.
;Full Replication: Every object is going to be queried and or handled by replication partners.
;GUID: A unique 16-byte value. Every object contains an attribute GUID.
;Incremental Replication: Only objects written since a last-known point in time will be queried and or handled.
;Master: The replication partner acting as an LDAP server.
;Notify Search: A single LDAP search remaing active until a cancellation. A server responds to it with multiple search responses for all objects being modified after the notify search was received.
;Paged Search/Paging: A means to iterate over an entire database in chunks or pages of a fixed maximum size.
;Replication Filter: A static LDAP filter supposed to be active during a replication session.
;Root DSE: Directory-specific entry. A collection of few properties and capabilities that can be read by any LDAP client. The Root DSE is accessible without authentication and by providing a special search filter.
;Slave: The replication partner acting as an LDAP client.
;Tombstones, isDeleted: Deleted objects aren't deleted immediately from storage. Instead, such objects are marked with an attribute isDeleted.
;USN: Update Sequence Number, a 64-bit value incremented by 1 on every write. It is deemed to never wrap-around and to be unique within an LDAP DB. Every object contains an attribute USN.

= Technical concept of replication as client =
The replication of a source via LDAP is basically divided into 3 phases that must be passed through when synchronization is started.

;1st phase ''local''
The first phase is the "local" phase and ensures a comparison of any delta between the local data stock and the remote data stock. (In other words, objects that need to be deleted locally).

The LDAP client makes an LDAP query per local object (which it knows from its local database) based on the ''guid'' to the LDAP server. If the LDAP server knows this object, it returns the entire object so that the client can update the object locally if necessary. If the object does not exist in the LDAP server, it is removed locally.

During this phase, the status shows the following:
remote: Stopped
local: Active

;2nd phase ''remote''
The second phase is the "remote" phase and ensures a comparison of any delta between the remote data stock and the local data stock. (In other words, objects that are missing locally are created).

The LDAP client requests a paging version of all objects of the LDAP server. The client then receives back page by page (2 objects) per request. If necessary, objects in the local database are updated accordingly.

During this phase the following is shown in the status:
remote: Active
local: Completed

;3rd phase ''notify''
The third phase is the "notify" phase, in which there is no longer an open delta between the two sources, and future changes are synchronised.
In this phase, a permanent TCP connection exists between the LDAP client and the LDAP server and is used for the LDAP server to notify the LDAP client when a change has occurred so that the client can create or update the record in the local database.

During this phase, the status will show the following:
remote: Completed
local: Completed

It is important to note that:
* if a problem occurs (e.g. due to the interruption of a phase or e.g. loss of the TCP connection to the LDAP server) the synchronisation starts again from the first phase ("local")
* the local attribute ''usn'' will not be replicated. Each ldap node manages its own local ''usn''
* if you use a configured [[{{NAMESPACE}}:Services/LDAP/Replicator|''Poll Timer'']] the notify feature will not be used in this ldap session

=Algorithmic and Technical Details=
This section covers details the incremental replication is based on, enabling the transition from full- to incremental replication.
==epoch==
The master's Root DSE contains or does not contain an attribute '''epoch''', reflecting the GUID attribute of an existing object by the name '''_admin_'''. A slave must permanently store the epoch as a persistent VARiable '''epoch'''.
*Slave connects and BINDs to master
*Slave requests Root DSE from master
*Slave evalutates ''epoch''
**''epoch'' is not present
***=>Full replication
***Store copy of ''epoch''
**''epoch'' is present
***''epoch'' matches slave's copy
****=>Incremental replication
***''epoch'' does not match slave's copy
****Delete copy of ''epoch''
****=>Full replication
****Store copy of ''epoch''
*Slave, persistent ''epoch'' storage
**Variable: '''LREPI/epoc-r/cn=PBX0'''

==USN Processing==
Every object features the attribute '''USN'''. A slave keeps track of the highest USN seen within all objects rx'ed from a master.
*Slave checks USN for objects rx'ed from master
**No local record of a highest USN
***=>Store current USN as highest USN
**Local copy of highest USN existing
***RX'ed USN greater than local USN copy
****=>Store current USN as highest USN
***RX'ed USN less or equal than local USN copy
****=>NOP, nothing to be done

*Slave, persistent USN storage
**Replication completed - at the end of a full or incremental replication. Also, when rx'ing notify search results from a master.
***=>Persistently storing the volatile memorized highest USN
**Variable: '''LREPI/u-r/cn=PBX0'''

==Paging==
Incremental paging requires an additional filter term spedifying a USN value.
*1st Search
**Slave
***Filter (&(objectclass=*)'''(usn>=103)''') The USN-Term contains the highest USN rx'ed during last replication run, plus 1.
***Cookie <empty>
**Server
***Evaluate '''(usn>=103)''' and set cursor at corresponding item
***Replies with entries and non-empty(more) or empty(final) cookie

*2nd Search,..
**Slave
***Filter (objectclass=*)
***Cookie <Last Cookie content rx'ed from server>
**Server
***Evaluate cookie and set cursor at corresponding item
***Replies with entries and non-empty(more) or empty(final) cookie

==Root DSE==
Because of the Flash Directory also exporting some infos into the Root DSE it probably makes sense to inform there about the current GUID of the ''_admin_'' object. Following excerpt represents this by an attribute '''epoch'''. A slave can comfortably compare this to its copy of the epoch last seen.
<pre>
Getting 1 entries:
>> Dn:
1> epoch: 0B1581AF783F67018F170050568214B4;
..
1> ldapServiceName: IP6013-50-00-68;
</pre>

==VARs==
Noteable variables for persistent storage of some replication control data within a slave's VARs section.
;LDAP Replication, remote highest USN:
<pre>
vars create LREPI/u-r/cn=PBX0 p 102
..
vars create LREPI/u-r/cn=KBX0 p 105
</pre>
;LDAP Replication, remote last seen epoch:
<pre>
vars create LREPI/epoc-r/cn=KPBX0 pb 5238705224c067016fd10090334117be
..
vars create LREPI/epoc-r/cn=PBX0 pb 5238705224c067016fd10090334117be
</pre>

==Restore on Master==
A restore of an older configuration on a master causes a new GUID for the object with the name ''_ADMIN_''.
*A new configuration is going to be uploaded
*The Flash Directory processes the module command <pre>mod cmd FLASHDIR0 erase-all</pre>
**The FLASH Directory erases it's entire database, awaiting further commands
*The FLASH Directory processes a module command <pre>mod cmd FLASHDIR0 add-item 102 (cn=_ADMIN_)..(guid;bin=5238705224C067016FD10090334117BE)</pre>
**This is the Admin object. Before being stored, it will now get assigned a new random GUID
*The Admin object's new GUID gets now promoted as the new ''epoch'' for the master's database

==Detecting Obsolete Objects==
Objects with the isDeleted attribute, a.k.a. tombstones, shall persist ideally forever. In practice tombstones get erased after a timeout. Only the most recent tombstone (tombstone with highest USN) remains.
;Current tombstone timeout: 48 hours
===Behaviour during Full Replication===
The local phase takes place in full. The replicator pages over all local objects and compares them with the master to see if they are still present.
===Behaviour during Incremental Replication===
The local phase is completely eliminated, respectively skipped.

Reference15r1:Services/LDAP/Rep-Status

2025-03-18T08:28:27Z

Inno-mst: Added status local/paged. Added replication type "Incremental". Added overall state "Completed"

The displayed '''replicator status''' data is automatically updated in 2 second intervals. In addition, the last ten activity messages of the replication are displayed below.

== Status overview ==

'''Server:''' IP-address and port of the remote LDAP server.

'''Full/Incremental Replication:''' Current state of the replication. The states are: ''Stop'', ''Starting'', ''Up'', ''Down, Completed''.

'''remote:''' Displays the state of the replication in poll direction.

'''notify:''' Number of received notifications.

'''modify:''' Number of modified objects.

'''paged:''' Number of objects received from remote directory server in response to paged-search requests.

'''no match:''' (AD-Only) Number of objects received and not matching the LDAP filter condition entered under Configuration/LDAP/Replicator.

'''discarded:''' (AD-Only) Number of objects discarded, because there was no suitable MAP found.

'''local:''' Displays the state of the replication in push direction.

'''add:''' Number of locally added objects.

'''del:''' Number of locally deleted objects.

'''paged:''' Number of objects received from local flash directory in response to paged-search requests.

'''modify:''' Number of locally modified objects.

'''notify:''' Number of notifications that have arisen locally.

'''pending:''' Number of locally waiting objects.

=Related Articles=
* [[{{NAMESPACE}}:Concept LDAP Replication]]

Reference16r1:Concept LDAP Replication

2025-03-17T14:26:18Z

Inno-mst: /* Glossary */ condensed

LDAP replication concepts, mainly the differences between full- and incremental replication are going to be covered within this article.
= Glossary =
;Admin Object: An LDAP DB object named "_ADMIN_".
;Config Restore: The act of administratively uploading an old configuration to a box. Can be accomplished via the firmware's maintenance UI or in-part via a PBX UI.
;Epoch: A Root DSE value. The current value of the GUID of the object Admin object.
;Flashdir, Flashman: Flash Directory, Flash Manager with Flashdir sitting on-top of Flashman. The Flashdir exchange API messages with the Flashman to persistently add, replace, delete LDAP objects.
;Full Replication: Every object is going to be queried and or handled by replication partners.
;GUID: A unique 16-byte value. Every object contains an attribute GUID.
;Incremental Replication: Only objects written since a last-known point in time will be queried and or handled.
;Master: The replication partner acting as an LDAP server.
;Notify Search: A single LDAP search remaing active until a cancellation. A server responds to it with multiple search responses for all objects being modified after the notify search was received.
;Paged Search/Paging: A means to iterate over an entire database in chunks or pages of a fixed maximum size.
;Replication Filter: A static LDAP filter supposed to be active during a replication session.
;Root DSE: Directory-specific entry. A collection of few properties and capabilities that can be read by any LDAP client. The Root DSE is accessible without authentication and by providing a special search filter.
;Slave: The replication partner acting as an LDAP client.
;Tombstones, isDeleted: Deleted objects aren't deleted immediately from storage. Instead, such objects are marked with an attribute isDeleted.
;USN: Update Sequence Number, a 64-bit value incremented by 1 on every write. It is deemed to never wrap-around and to be unique within an LDAP DB. Every object contains an attribute USN.

= Technical concept of replication as client =
The replication of a source via LDAP is basically divided into 3 phases that must be passed through when synchronization is started.

;1st phase ''local''
The first phase is the "local" phase and ensures a comparison of any delta between the local data stock and the remote data stock. (In other words, objects that need to be deleted locally).

The LDAP client makes an LDAP query per local object (which it knows from its local database) based on the ''guid'' to the LDAP server. If the LDAP server knows this object, it returns the entire object so that the client can update the object locally if necessary. If the object does not exist in the LDAP server, it is removed locally.

During this phase, the status shows the following:
remote: Stopped
local: Active

;2nd phase ''remote''
The second phase is the "remote" phase and ensures a comparison of any delta between the remote data stock and the local data stock. (In other words, objects that are missing locally are created).

The LDAP client requests a paging version of all objects of the LDAP server. The client then receives back page by page (2 objects) per request. If necessary, objects in the local database are updated accordingly.

During this phase the following is shown in the status:
remote: Active
local: Completed

;3rd phase ''notify''
The third phase is the "notify" phase, in which there is no longer an open delta between the two sources, and future changes are synchronised.
In this phase, a permanent TCP connection exists between the LDAP client and the LDAP server and is used for the LDAP server to notify the LDAP client when a change has occurred so that the client can create or update the record in the local database.

During this phase, the status will show the following:
remote: Completed
local: Completed

It is important to note that:
* if a problem occurs (e.g. due to the interruption of a phase or e.g. loss of the TCP connection to the LDAP server) the synchronisation starts again from the first phase ("local")
* the local attribute ''usn'' will not be replicated. Each ldap node manages its own local ''usn''
* if you use a configured [[{{NAMESPACE}}:Services/LDAP/Replicator|''Poll Timer'']] the notify feature will not be used in this ldap session

=Algorithmic and Technical Details=
This section covers details the incremental replication is based on, enabling the transition from full- to incremental replication.
==epoch==
The master's Root DSE contains or does not contain an attribute '''epoch''', reflecting the GUID attribute of an existing object by the name '''_admin_'''. A slave must permanently store the epoch as a persistent VARiable '''epoch'''.
*Slave connects and BINDs to master
*Slave requests Root DSE from master
*Slave evalutates ''epoch''
**''epoch'' is not present
***=>Full replication
***Store copy of ''epoch''
**''epoch'' is present
***''epoch'' matches slave's copy
****=>Incremental replication
***''epoch'' does not match slave's copy
****Delete copy of ''epoch''
****=>Full replication
****Store copy of ''epoch''
*Slave, persistent ''epoch'' storage
**Variable: '''LREPI/epoc-r/cn=PBX0'''

==USN Processing==
Every object features the attribute '''USN'''. A slave keeps track of the highest USN seen within all objects rx'ed from a master.
*Slave checks USN for objects rx'ed from master
**No local record of a highest USN
***=>Store current USN as highest USN
**Local copy of highest USN existing
***RX'ed USN greater than local USN copy
****=>Store current USN as highest USN
***RX'ed USN less or equal than local USN copy
****=>NOP, nothing to be done

*Slave, persistent USN storage
**Replication completed - at the end of a full or incremental replication. Also, when rx'ing notify search results from a master.
***=>Persistently storing the volatile memorized highest USN
**Variable: '''LREPI/u-r/cn=PBX0'''

==Paging==
Incremental paging requires an additional filter term spedifying a USN value.
*1st Search
**Slave
***Filter (&(objectclass=*)'''(usn>=103)''') The USN-Term contains the highest USN rx'ed during last replication run, plus 1.
***Cookie <empty>
**Server
***Evaluate '''(usn>=103)''' and set cursor at corresponding item
***Replies with entries and non-empty(more) or empty(final) cookie

*2nd Search,..
**Slave
***Filter (objectclass=*)
***Cookie <Last Cookie content rx'ed from server>
**Server
***Evaluate cookie and set cursor at corresponding item
***Replies with entries and non-empty(more) or empty(final) cookie

==Root DSE==
Because of the Flash Directory also exporting some infos into the Root DSE it probably makes sense to inform there about the current GUID of the ''_admin_'' object. Following excerpt represents this by an attribute '''epoch'''. A slave can comfortably compare this to its copy of the epoch last seen.
<pre>
Getting 1 entries:
>> Dn:
1> epoch: 0B1581AF783F67018F170050568214B4;
..
1> ldapServiceName: IP6013-50-00-68;
</pre>

==VARs==
Noteable variables for persistent storage of some replication control data within a slave's VARs section.
;LDAP Replication, remote highest USN:
<pre>
vars create LREPI/u-r/cn=PBX0 p 102
..
vars create LREPI/u-r/cn=KBX0 p 105
</pre>
;LDAP Replication, remote last seen epoch:
<pre>
vars create LREPI/epoc-r/cn=KPBX0 pb 5238705224c067016fd10090334117be
..
vars create LREPI/epoc-r/cn=PBX0 pb 5238705224c067016fd10090334117be
</pre>

==Restore on Master==
A restore of an older configuration on a master causes a new GUID for the object with the name ''_ADMIN_''.
*A new configuration is going to be uploaded
*The Flash Directory processes the module command <pre>mod cmd FLASHDIR0 erase-all</pre>
**The FLASH Directory erases it's entire database, awaiting further commands
*The FLASH Directory processes a module command <pre>mod cmd FLASHDIR0 add-item 102 (cn=_ADMIN_)..(guid;bin=5238705224C067016FD10090334117BE)</pre>
**This is the Admin object. Before being stored, it will now get assigned a new random GUID
*The Admin object's new GUID gets now promoted as the new ''epoch'' for the master's database

==Detecting Obsolete Objects==
Objects with the isDeleted attribute, a.k.a. tombstones, shall persist ideally forever. In practice tombstones get erased after a timeout. Only the most recent tombstone (tombstone with highest USN) remains.
;Current tombstone timeout: 48 hours
===Behaviour during Full Replication===
The local phase takes place in full. The replicator pages over all local objects and compares them with the master to see if they are still present.
===Behaviour during Incremental Replication===
The local phase is completely eliminated, respectively skipped.

Reference16r1:Concept LDAP Replication

2025-03-17T14:19:47Z

Inno-mst: Merged aspects of incremental replication from the design document for the incremental replication

LDAP replication concepts, mainly the differences between full- and incremental replication are going to be covered within this article.
= Glossary =
;Admin Object: An LDAP DB object named "_ADMIN_".
;Attribute "phys": LDAP attribute reflecting where an (H.323/Sip) client is currently registered.
;Attribute "rep": LDAP attribute playing a role - TO BE DETAILED - within an replication filter.
;Config Restore: The act of administratively uploading an old configuration to a box. Can be accomplished via the firmware's maintenance UI or in-part via a PBX UI.
;Epoch: A Root DSE value. The current value of the GUID of the object Admin object.
;Flashdir, Flashman: Flash Directory, Flash Manager with Flashdir sitting on-top of Flashman. The Flashdir exchange API messages with the Flashman to persistently add, replace, delete LDAP objects.
;Full Replication: Every object is going to be queried and or handled by replication partners.
;GUID: A unique 16-byte value. Every object contains an attribute GUID.
;highestCommitedUSN: A Root DSE value. The current value of the highest USN among all objects within a directory's database.
;Incremental Replication: Only objects written since a last-known point in time will be queried and or handled.
;Master: The replication partner acting as an LDAP server.
;Notify Search: A single LDAP search remaing active until a cancellation. A server responds to it with multiple search responses for all objects being modified after the notify search was received.
;Paged Search/Paging: A means to iterate over an entire database in chunks or pages of a fixed maximum size.
;Replication Filter: A static LDAP filter supposed to be active during a replication session.
;Root DSE: Directory-specific entry. A collection of few properties and capabilities that can be read by any LDAP client. The Root DSE is accessible without authentication and by providing a special search filter.
;Slave: The replication partner acting as an LDAP client.
;Tombstones, isDeleted: Deleted objects aren't deleted immediately from storage. Instead, such objects are marked with an attribute isDeleted.
;USN: Update Sequence Number, a 64-bit value incremented by 1 on every write. It is deemed to never wrap-around and to be unique within an LDAP DB. Every object contains an attribute USN.

= Technical concept of replication as client =
The replication of a source via LDAP is basically divided into 3 phases that must be passed through when synchronization is started.

;1st phase ''local''
The first phase is the "local" phase and ensures a comparison of any delta between the local data stock and the remote data stock. (In other words, objects that need to be deleted locally).

The LDAP client makes an LDAP query per local object (which it knows from its local database) based on the ''guid'' to the LDAP server. If the LDAP server knows this object, it returns the entire object so that the client can update the object locally if necessary. If the object does not exist in the LDAP server, it is removed locally.

During this phase, the status shows the following:
remote: Stopped
local: Active

;2nd phase ''remote''
The second phase is the "remote" phase and ensures a comparison of any delta between the remote data stock and the local data stock. (In other words, objects that are missing locally are created).

The LDAP client requests a paging version of all objects of the LDAP server. The client then receives back page by page (2 objects) per request. If necessary, objects in the local database are updated accordingly.

During this phase the following is shown in the status:
remote: Active
local: Completed

;3rd phase ''notify''
The third phase is the "notify" phase, in which there is no longer an open delta between the two sources, and future changes are synchronised.
In this phase, a permanent TCP connection exists between the LDAP client and the LDAP server and is used for the LDAP server to notify the LDAP client when a change has occurred so that the client can create or update the record in the local database.

During this phase, the status will show the following:
remote: Completed
local: Completed

It is important to note that:
* if a problem occurs (e.g. due to the interruption of a phase or e.g. loss of the TCP connection to the LDAP server) the synchronisation starts again from the first phase ("local")
* the local attribute ''usn'' will not be replicated. Each ldap node manages its own local ''usn''
* if you use a configured [[{{NAMESPACE}}:Services/LDAP/Replicator|''Poll Timer'']] the notify feature will not be used in this ldap session

=Algorithmic and Technical Details=
This section covers details the incremental replication is based on, enabling the transition from full- to incremental replication.
==epoch==
The master's Root DSE contains or does not contain an attribute '''epoch''', reflecting the GUID attribute of an existing object by the name '''_admin_'''. A slave must permanently store the epoch as a persistent VARiable '''epoch'''.
*Slave connects and BINDs to master
*Slave requests Root DSE from master
*Slave evalutates ''epoch''
**''epoch'' is not present
***=>Full replication
***Store copy of ''epoch''
**''epoch'' is present
***''epoch'' matches slave's copy
****=>Incremental replication
***''epoch'' does not match slave's copy
****Delete copy of ''epoch''
****=>Full replication
****Store copy of ''epoch''
*Slave, persistent ''epoch'' storage
**Variable: '''LREPI/epoc-r/cn=PBX0'''

==USN Processing==
Every object features the attribute '''USN'''. A slave keeps track of the highest USN seen within all objects rx'ed from a master.
*Slave checks USN for objects rx'ed from master
**No local record of a highest USN
***=>Store current USN as highest USN
**Local copy of highest USN existing
***RX'ed USN greater than local USN copy
****=>Store current USN as highest USN
***RX'ed USN less or equal than local USN copy
****=>NOP, nothing to be done

*Slave, persistent USN storage
**Replication completed - at the end of a full or incremental replication. Also, when rx'ing notify search results from a master.
***=>Persistently storing the volatile memorized highest USN
**Variable: '''LREPI/u-r/cn=PBX0'''

==Paging==
Incremental paging requires an additional filter term spedifying a USN value.
*1st Search
**Slave
***Filter (&(objectclass=*)'''(usn>=103)''') The USN-Term contains the highest USN rx'ed during last replication run, plus 1.
***Cookie <empty>
**Server
***Evaluate '''(usn>=103)''' and set cursor at corresponding item
***Replies with entries and non-empty(more) or empty(final) cookie

*2nd Search,..
**Slave
***Filter (objectclass=*)
***Cookie <Last Cookie content rx'ed from server>
**Server
***Evaluate cookie and set cursor at corresponding item
***Replies with entries and non-empty(more) or empty(final) cookie

==Root DSE==
Because of the Flash Directory also exporting some infos into the Root DSE it probably makes sense to inform there about the current GUID of the ''_admin_'' object. Following excerpt represents this by an attribute '''epoch'''. A slave can comfortably compare this to its copy of the epoch last seen.
<pre>
Getting 1 entries:
>> Dn:
1> epoch: 0B1581AF783F67018F170050568214B4;
..
1> ldapServiceName: IP6013-50-00-68;
</pre>

==VARs==
Noteable variables for persistent storage of some replication control data within a slave's VARs section.
;LDAP Replication, remote highest USN:
<pre>
vars create LREPI/u-r/cn=PBX0 p 102
..
vars create LREPI/u-r/cn=KBX0 p 105
</pre>
;LDAP Replication, remote last seen epoch:
<pre>
vars create LREPI/epoc-r/cn=KPBX0 pb 5238705224c067016fd10090334117be
..
vars create LREPI/epoc-r/cn=PBX0 pb 5238705224c067016fd10090334117be
</pre>

==Restore on Master==
A restore of an older configuration on a master causes a new GUID for the object with the name ''_ADMIN_''.
*A new configuration is going to be uploaded
*The Flash Directory processes the module command <pre>mod cmd FLASHDIR0 erase-all</pre>
**The FLASH Directory erases it's entire database, awaiting further commands
*The FLASH Directory processes a module command <pre>mod cmd FLASHDIR0 add-item 102 (cn=_ADMIN_)..(guid;bin=5238705224C067016FD10090334117BE)</pre>
**This is the Admin object. Before being stored, it will now get assigned a new random GUID
*The Admin object's new GUID gets now promoted as the new ''epoch'' for the master's database

==Detecting Obsolete Objects==
Objects with the isDeleted attribute, a.k.a. tombstones, shall persist ideally forever. In practice tombstones get erased after a timeout. Only the most recent tombstone (tombstone with highest USN) remains.
;Current tombstone timeout: 48 hours
===Behaviour during Full Replication===
The local phase takes place in full. The replicator pages over all local objects and compares them with the master to see if they are still present.
===Behaviour during Incremental Replication===
The local phase is completely eliminated, respectively skipped.

Reference15r1:Interfaces/ETH/802.1X

2025-03-06T09:57:09Z

Inno-mst: Added 15r1/802.1X

;'''Desired Protocol''': Preferred EAP mechanism. Either EAP-MD5 (default) or EAP-TLS
;'''Identity''': Optional configuration for an identity string within an EAP-Identity-Response.
;'''EAP-MD5''':
* '''User''' Enter the user/identity to authenticate with.
* '''Password''' Enter the shared secret for the MD5 challenge/response handshake.
;'''EAP-TLS''':
* The configuration for an actual certificate, being fed into the EAP-TLS session, can be found at ''General/Certificates/Device Certificate''.
;'''Proxy-Logoff''':
If the phone's PC-port got disconnected, EAPOL-Logoff messages are going to be sent on behalf of participants that were connected to the phone's PC-port.
An EAPOL-Logoff will be sent for each MAC-address learned from traversing EAPOL-Start messages.

=Related Articles=
[[Concept_802.1X|Concept 802.1X]]

[[Howto11r1:802.1X_EAP-TLS_With_FreeRadius|Howto article: 802.1X EAP-TLS With FreeRadius]]

[[Howto:Security_works_with_innovaphone#802.1X_port_security|Howto article:Security_works_with_innovaphone]]

Howto15r1:Implement PBX with zero downtime using IPVA and VMWare Fault Tolerance

2024-12-10T17:46:35Z

Inno-mst: /* Prepare your VM */

{{FIXME|reason=This product is in the beta phase and is not yet finished}}
==Applies To==
This information applies to

* IPVA 15r1
* VMWare ESXi (vSphere) 6.7 - 8
* VMWare vCenter Server 6.7 - 8



==More Information==
===Problem Details===
The standby functionality implemented in the innovaphone PBX enables to start PBX software on the standby gateway in fail over scenario. A drawback in this implementation is following - since the standby PBX is running on other physical gateway, all active calls and connections are interrupted while switching from master to standby. The switch to standby hardware takes a while, so the downtime about 2 minutes must be considered additionally.

To be able to implement a PBX with zero downtime on hardware failures, a VMWare [http://www.vmware.com/de/products/vsphere/features/fault-tolerance.html Fault Tolerance(FT)] feature of the VMWare vSphere can be used. Therefore the PBX must be implemented on the innovaphone Virtual Appliance (IPVA) and the Virtual Machine running IPVA must be hosted on a FT-enabled VMWare Cluster.

===System Requirements===
The VMWare infrastructure must fulfil following requirements to be able to run FT-enabled VMs:
* VMware vSphere Advanced or Enterprise Edition (FT Support included in this editions)
* The CPU and chip-set of the Hosts must support Fault Tolerance.
* The ESXi/vSphere hosts must be equipped with same CPU type and be part of FT-enabled Cluster

===Prepare your VM===
If you want to use FT you need to use the IPVA Version which includes SCSI-Disks, it's not possible to use the "Old" IPVA with IDE-Disks.
To Run the SCSI-IPVA on VMware, you need to do Following steps:
* Download and unzip '''ipva-vmx-scsi.zip'''
* Convert all 4 disks to the VM by using the following command.
<syntaxhighlight lang="bash">
vmkfstools -i /vmfs/volumes/datastore/current-VM-folder/disk.vmdk /vmfs/volumes/datastore/new-VM-folder/disk.vmdk
</syntaxhighlight>
* Now you need to attach the New Disks to your VM:
# You need to detach your old Disks from your IPVA in the settings of your IPVA itself.
# After you removed all the old Disks, you now need to open the Settings of your IPVA itself again and attach the new Disks.
# You need to make sure the Disks are on the correct SCSI controllers
# The Disks need to be on following Positions
## hd.boot.vmdk SCSI-Controller 0 0:0
## hd-cf.vmdk SCSI-Controller 0 0:1
## hd-flash.vmdk SCSI-Controller 1 1:0
## hd-dump.vmdk SCSI-Controller 1 1:1

===Installation===
For detailed implementation of FT-enabled VMWare infrastructure, please refer to the [https://docs.vmware.com/en/VMware-vSphere/8.0/vsphere-availability/GUID-7525F8DD-9B8F-4089-B020-BAA4AC6509D2.html VMWare documentation].

On the IPVA side no special settings or changes must be performed to enable FT.

We have tested the FT functionality with following setup and also in our cloud setup:

[[File:FT Test setup.png|ft_test_setup.png/|ft_test_setup.png/]]

While testing the Softphones where in a conference and also calling a WQ. While in an active call, a failure of ESXi/vSphere host was simulated. While testing multiple times, there were some noticeable interruptions in the media stream were realized, while the failover. Even with Video streams there were no problem and everything worked without noticeable problematic behavior.

===Migration===
To Migrate your existing System to an FT-System, you need to set up a SCSI-IPVA and Download the Config(NOT download with standard password) from your old IPVA. Upload it to your new SCSI-IPVA. Please make sure you give your new VM the same MAC-Address as the old VM, so there won't be any issues.

===Known Problems===
The Fault Tolerance does not protect the system from software failures(e.g. trap of the IPVA).

== Related Articles ==
*[[Reference15r1:Concept Innovaphone Virtual Appliance]]

[[Category:Howto|{{PAGENAME}}]]

Main Page

2024-08-15T12:50:56Z

Inno-mst: /* Latest News */

__NOTOC__

<div style="margin:0px; margin-right:10px; border:1px solid #58C4C3; background-color:#F4F4F4; padding:0em 1em 0em 1em;">
== Remote Support ==
innovaphone only carries out scheduled remote maintenance via our ticket system by prior consultation. 
Please do not accept AnyDesk requests without prior appointment via ticket.

Please ensure that you download the [https://anydesk.com/en/downloads/windows latest AnyDesk version].

Please note: We cannot accept any liability for the external content of AnyDesk. AnyDesk is responsible for the content of its own software.
We are not liable for any damages resulting from the use of a non-updated or non-conforming version of AnyDesk.

== Searching ==
Searching in wiki works, but is sometimes cumbersome. However, you can have Google do the job for you. Try [https://www.google.de/search?q=site%3Ainnovaphone.com+xml+documentation <code>site:innovaphone.com your search terms</code>] to search the innovaphone sites for matches!

If you still don't find what you are looking for, [mailto:presales@innovaphone.com drop us a message]
</div>


<div style="margin:0px; margin-right:10px; margin-top:15px; border:1px solid #58C4C3; background-color:#F4F4F4; padding:0em 1em 0.5em 1em;">



== Latest News ==
[[User:Inno-mst|Inno-mst]] ([[User talk:Inno-mst|talk]]) 14:47, 15 August 2024 (CEST)
[[Support:Firmware V14r2 product/14r2/firmware 1420322 (sr 1) available | Version 14r2 Service Release 1]] is now available from the [http://store.innovaphone.com/release/download.htm download page].

[[User:Inno-mst|Inno-mst]] ([[User talk:Inno-mst|talk]]) 14:47, 15 August 2024 (CEST)
[[Support:Firmware V14r1 product/14r1/firmware 1410555 (sr 6) available | Version 14r1 Service Release 6]] is now available from the [http://store.innovaphone.com/release/download.htm download page].

[[User:Inno-mst|Inno-mst]] ([[User talk:Inno-mst|talk]]) 14:47, 15 August 2024 (CEST)
[[Support:Firmware V13r3 product/13r3/firmware 137975 (sr 18) available | Version 13r3 Service Release 18]] is now available from the [http://store.innovaphone.com/release/download.htm download page].

[[User:Inno-mst|Inno-mst]] ([[User talk:Inno-mst|talk]]) 14:47, 15 August 2024 (CEST)
[[Support:Firmware V12r2 product/12r2/firmware 125883 (sr 68) available | Version 12r2 Service Release 68]] is now available from the [http://store.innovaphone.com/release/download.htm download page].

[[User:Cam|Cam]] 16:22, 18 September 2023 (CEST)
[[App Calculator beta1 available]] is now available from the [http://store.innovaphone.com/release/download.htm download page].

[[User:Sga|Sga]] ([[User talk:Sga|talk]]) 17:43, 15 September 2023 (CEST)
[[Support:Wireless Handset Firmware IP73 1011 (5.0.1) released | Wireless Handset Firmware IP73 1011 (5.0.1)]] is now available from the [https://store.innovaphone.com/release/download.htm App store].

[[User:Gal|Gal]] ([[User talk:Gal|talk]]) 13:39, 31 July 2023 (CEST)
[[Support:Wireless Handset Firmware IP64 10314 (3.0.13)/IP65 10119 (3.0.13) released | Wireless Handset Firmware IP64 10314 (3.0.13)/IP65 10119 (3.0.13)]] is now available from the [https://store.innovaphone.com/release/download.htm App store].

[[User:Cam|Cam]] 12:03, 31 July 2023 (CEST)
[[App Working final available]] is now available from the [http://store.innovaphone.com/release/download.htm download page].

[[User:Afi|Afi]] 15:38, 6 February 2023 (CET)
[[Support:Wireless_Handset_Firmware_IP62_3040621_(6.2.7)_released | Wireless Handset Firmware IP62 3040621 (6.2.7)]] is now available from the [https://store.innovaphone.com/release/download.htm App store].

[[User:Afi|Afi]] 13:13, 6 February 2023 (CET)
[[Support:WinPDM_Software_3130113_%284.1.8%29_released | WinPDM Software 3130113 (4.1.8)]] is now available from the [https://store.innovaphone.com/release/download.htm App store].

[[User:Afi|Afi]] 15:05, 11 February 2022 (CET)
[[Support:Wireless_Handset_Firmware_IP64_10313_(2.12.10)/IP65_10118_(2.12.10)_released | Wireless Handset Firmware IP64 10313 (2.12.10)/IP65 10118 (2.12.10)]] is now available from the [https://store.innovaphone.com/release/download.htm App store].

[[User:kwa|kwa]] 14:00, 16 June 2021 (CEST)
[[Support:iQM_Build_8029100_available | IQM Build 8029100 Hotfix34]] is now available from the [https://store.innovaphone.com/release/download.htm the Software download area].

[[User:Afi|Afi]] 12:46, 16 June 2021 (CEST))
[[Support:TAPI Service Provider 8188 (hotfix21) available|TAPI Service Provider 8188 (hotfix21)]] is now available from [https://store.innovaphone.com/release/download.htm the Software download area].

[[User:Dde|Dde]] 13:17, 2 November 2020 (CET)
[[Support:Linux_Application_Platform_100271_(sr64)_available | Linux Application Platform V10 100271 sr64]] is now available from the [http://store.innovaphone.com/release/download.htm App store].

[[User:Dde|Dde]] 13:17, 2 November 2020 (CET)
[[Support:Innovaphone_Reporting_100271_(sr64)_available | innovaphone Reporting V10 100271 sr64]] is now available from the [http://store.innovaphone.com/release/download.htm App store].

[[User:Dde|Dde]] 13:17, 2 November 2020 (CET)
[[Support:Innovaphone_Fax_100271_(sr64)_available | innovaphone Fax V10 100271 sr64]] is now available from the [http://store.innovaphone.com/release/download.htm App store].

[[User:Dde|Dde]] 13:17, 2 November 2020 (CET)
[[Support:Innovaphone_Exchange_Calendar_Connector_100271_(sr64)_available | innovaphone Exchange Calendar Connector V10 100271 sr64]] is now available from the [http://store.innovaphone.com/release/download.htm App store].

[[User:Afi|Afi]] 18:21, 12 October 2020 (CEST)
[[Support:Wireless_Handset_Firmware_IP61_3022811_(4.7.8)/IP63_3022912_(4.7.8)_released | Wireless Handset Firmware IP61 3022811 (4.7.8)/IP63 3022912 (4.7.8)]] is now available from the [https://store.innovaphone.com/release/download.htm App store].

[[User:Afi|Afi]] 21:30, 27 March 2020 (CET)
[[Support:Wireless_Handset_Firmware_and_Management_Software_product/9.00/wireless_100037_%28hotfix19%29_available | Wireless Package hotfix 19]] is now available from the [http://download.innovaphone.com/ice/9.00#wireless V9 download area].

[[User:Dde|Dde]] 07:56, 9 March 2020 (CET)
[[Support:App_Platform_build_90007_available | App Platform build 90007]] is now available from the [http://store.innovaphone.com/release/download.htm App store].

[[User:kwa|kwa]] 14:00, 02 March 2020 (CET)
[[Support:Recording_Build_121100_available | innovaphone Recording SR29 build 121100]] is now available from the [http://download.innovaphone.com/ice/10.00/#recording V10 download area].
</div>

<div style="margin:0px; margin-right:10px; margin-top:15px; border:1px solid #58C4C3; background-color:#F4F4F4; padding:0em 1em 0.5em 1em;">

== New Articles ==

{{Special:Newestpages/all/20}}
</div>

<div style="margin:0px; margin-right:10px; margin-top:15px; border:1px solid #58C4C3; background-color:#F4F4F4; padding:0em 1em 0.5em 1em; font-size:1">
== More innovaphone Ressources ==
* [http://www.innovaphone.com Home Page]
* [http://download.innovaphone.com Download Site ]
* [http://my.innovaphone.com my.innovaphone ]
* [http://mantis.innovaphone.com/ Ticketing System ]
</div>

Main Page

2024-08-15T12:47:11Z

Inno-mst: /* Latest News */ Patchday August

__NOTOC__

<div style="margin:0px; margin-right:10px; border:1px solid #58C4C3; background-color:#F4F4F4; padding:0em 1em 0em 1em;">
== Remote Support ==
innovaphone only carries out scheduled remote maintenance via our ticket system by prior consultation. 
Please do not accept AnyDesk requests without prior appointment via ticket.

Please ensure that you download the [https://anydesk.com/en/downloads/windows latest AnyDesk version].

Please note: We cannot accept any liability for the external content of AnyDesk. AnyDesk is responsible for the content of its own software.
We are not liable for any damages resulting from the use of a non-updated or non-conforming version of AnyDesk.

== Searching ==
Searching in wiki works, but is sometimes cumbersome. However, you can have Google do the job for you. Try [https://www.google.de/search?q=site%3Ainnovaphone.com+xml+documentation <code>site:innovaphone.com your search terms</code>] to search the innovaphone sites for matches!

If you still don't find what you are looking for, [mailto:presales@innovaphone.com drop us a message]
</div>


<div style="margin:0px; margin-right:10px; margin-top:15px; border:1px solid #58C4C3; background-color:#F4F4F4; padding:0em 1em 0.5em 1em;">



== Latest News ==
[[User:Inno-mst|Inno-mst]] ([[User talk:Inno-mst|talk]]) 14:47, 15 August 2024 (CEST)
[[Support:Firmware V14r2 product/14r2/firmware 1420322 (sr 1) available | Version 14r2 Service Release 1]] is now available from the [http://store.innovaphone.com/release/download.htm download page].

[[User:Inno-mst|Inno-mst]] ([[User talk:Inno-mst|talk]]) 14:47, 15 August 2024 (CEST)
[[Support:Firmware V14r1 product/14r1/firmware 1410555 (sr 6) available | Version 14r1 Service Release 6]] is now available from the [http://store.innovaphone.com/release/download.htm download page].

[[User:Inno-mst|Inno-mst]] ([[User talk:Inno-mst|talk]]) 14:47, 15 August 2024 (CEST)
[[Support:Firmware V13r3 product/13r3/firmware 137975 (sr 18) available | Version 13r3 Service Release 18]] is now available from the [http://store.innovaphone.com/release/download.htm download page].

[[User:Inno-mst|Inno-mst]] ([[User talk:Inno-mst|talk]]) 14:47, 15 August 2024 (CEST)
[[Support:Firmware V12r2 product/12r2/firmware 125883 (sr 68) available | Version 12r2 Service Release 68]] is now available from the [http://store.innovaphone.com/release/download.htm download page].

[[User:Aer|Aer]] ([[User talk:Aer|talk]]) 16:30, 24 May 2024 (CEST)
[[Support:Firmware V12r2 product/12r2/firmware 125882 (sr 67) available | Version 12r2 Service Release 67]] is now available from the [http://store.innovaphone.com/release/download.htm download page].

[[User:Cam|Cam]] 16:22, 18 September 2023 (CEST)
[[App Calculator beta1 available]] is now available from the [http://store.innovaphone.com/release/download.htm download page].

[[User:Sga|Sga]] ([[User talk:Sga|talk]]) 17:43, 15 September 2023 (CEST)
[[Support:Wireless Handset Firmware IP73 1011 (5.0.1) released | Wireless Handset Firmware IP73 1011 (5.0.1)]] is now available from the [https://store.innovaphone.com/release/download.htm App store].

[[User:Gal|Gal]] ([[User talk:Gal|talk]]) 13:39, 31 July 2023 (CEST)
[[Support:Wireless Handset Firmware IP64 10314 (3.0.13)/IP65 10119 (3.0.13) released | Wireless Handset Firmware IP64 10314 (3.0.13)/IP65 10119 (3.0.13)]] is now available from the [https://store.innovaphone.com/release/download.htm App store].

[[User:Cam|Cam]] 12:03, 31 July 2023 (CEST)
[[App Working final available]] is now available from the [http://store.innovaphone.com/release/download.htm download page].

[[User:Afi|Afi]] 15:38, 6 February 2023 (CET)
[[Support:Wireless_Handset_Firmware_IP62_3040621_(6.2.7)_released | Wireless Handset Firmware IP62 3040621 (6.2.7)]] is now available from the [https://store.innovaphone.com/release/download.htm App store].

[[User:Afi|Afi]] 13:13, 6 February 2023 (CET)
[[Support:WinPDM_Software_3130113_%284.1.8%29_released | WinPDM Software 3130113 (4.1.8)]] is now available from the [https://store.innovaphone.com/release/download.htm App store].

[[User:Inno-mst|Inno-mst]] 11:22, 14 April 2022 (CEST)
[[Support:Operator9 90246 (hotfix24) available | Operator9 hotfix24]] is now available from [https://store.innovaphone.com/release/download.htm the Software download area].

[[User:Afi|Afi]] 15:05, 11 February 2022 (CET)
[[Support:Wireless_Handset_Firmware_IP64_10313_(2.12.10)/IP65_10118_(2.12.10)_released | Wireless Handset Firmware IP64 10313 (2.12.10)/IP65 10118 (2.12.10)]] is now available from the [https://store.innovaphone.com/release/download.htm App store].

[[User:kwa|kwa]] 14:00, 16 June 2021 (CEST)
[[Support:iQM_Build_8029100_available | IQM Build 8029100 Hotfix34]] is now available from the [https://store.innovaphone.com/release/download.htm the Software download area].

[[User:Afi|Afi]] 12:46, 16 June 2021 (CEST))
[[Support:TAPI Service Provider 8188 (hotfix21) available|TAPI Service Provider 8188 (hotfix21)]] is now available from [https://store.innovaphone.com/release/download.htm the Software download area].

[[User:Dde|Dde]] 13:17, 2 November 2020 (CET)
[[Support:Linux_Application_Platform_100271_(sr64)_available | Linux Application Platform V10 100271 sr64]] is now available from the [http://store.innovaphone.com/release/download.htm App store].

[[User:Dde|Dde]] 13:17, 2 November 2020 (CET)
[[Support:Innovaphone_Reporting_100271_(sr64)_available | innovaphone Reporting V10 100271 sr64]] is now available from the [http://store.innovaphone.com/release/download.htm App store].

[[User:Dde|Dde]] 13:17, 2 November 2020 (CET)
[[Support:Innovaphone_Fax_100271_(sr64)_available | innovaphone Fax V10 100271 sr64]] is now available from the [http://store.innovaphone.com/release/download.htm App store].

[[User:Dde|Dde]] 13:17, 2 November 2020 (CET)
[[Support:Innovaphone_Exchange_Calendar_Connector_100271_(sr64)_available | innovaphone Exchange Calendar Connector V10 100271 sr64]] is now available from the [http://store.innovaphone.com/release/download.htm App store].

[[User:Afi|Afi]] 18:21, 12 October 2020 (CEST)
[[Support:Wireless_Handset_Firmware_IP61_3022811_(4.7.8)/IP63_3022912_(4.7.8)_released | Wireless Handset Firmware IP61 3022811 (4.7.8)/IP63 3022912 (4.7.8)]] is now available from the [https://store.innovaphone.com/release/download.htm App store].

[[User:Afi|Afi]] 21:30, 27 March 2020 (CET)
[[Support:Wireless_Handset_Firmware_and_Management_Software_product/9.00/wireless_100037_%28hotfix19%29_available | Wireless Package hotfix 19]] is now available from the [http://download.innovaphone.com/ice/9.00#wireless V9 download area].

[[User:Dde|Dde]] 07:56, 9 March 2020 (CET)
[[Support:App_Platform_build_90007_available | App Platform build 90007]] is now available from the [http://store.innovaphone.com/release/download.htm App store].

[[User:kwa|kwa]] 14:00, 02 March 2020 (CET)
[[Support:Recording_Build_121100_available | innovaphone Recording SR29 build 121100]] is now available from the [http://download.innovaphone.com/ice/10.00/#recording V10 download area].
</div>

<div style="margin:0px; margin-right:10px; margin-top:15px; border:1px solid #58C4C3; background-color:#F4F4F4; padding:0em 1em 0.5em 1em;">

== New Articles ==

{{Special:Newestpages/all/20}}
</div>

<div style="margin:0px; margin-right:10px; margin-top:15px; border:1px solid #58C4C3; background-color:#F4F4F4; padding:0em 1em 0.5em 1em; font-size:1">
== More innovaphone Ressources ==
* [http://www.innovaphone.com Home Page]
* [http://download.innovaphone.com Download Site ]
* [http://my.innovaphone.com my.innovaphone ]
* [http://mantis.innovaphone.com/ Ticketing System ]
</div>

Reference14r2:Concept App Service Contacts

2024-07-25T11:34:33Z

Inno-mst: /* Manually Exporting all Contacts */ Removed obsoleted paragraph "Manually Exporting all Contacts"

[[Category:Concept|Apps]]
= Applies To =
* App Contacts version 14r2

= Overview =
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, as well as maintaining personal contact books.

Inside Contacts, personal and general entries can be searched (forward lookup) or be used to resolve incoming numbers to their respective name (reverse lookup).

= Features =
*Import: Semicolon (;) separated CSV file
*Database for contact entries: A user interface for retrieval purposes is available.
*API: Search API for other apps
*Edit Functionality: Contact entries are editable.
*Personal Address Book: Every user can maintain one or more personal address books.
*Access Right Management: Owners can maintain access privileges for single users or even groups of users, in order to control visibility of an address book.
== 14r2 Features ==
Features added to the version 14r2
;User-Interface improvements
: Contact entries retrieved are rendered in a condensed card representation. A '''Details'''-button expands and displays remaining contact information
;Presence Updates
:Useful in federation scenarios. For displayed and currently visible contact entries, presence monitoring calls are placed, in order to display availablity status. Underlying resources are going to be freed immediately for entries scrolled out of visibility.
;Fax button
:Placing a call to a fax number is going to start the fax application
;Adding Contacts from the Softphone App
:Contacts can be added by means of a button '''Softphone/Call List/<entry>/"Add Contact"'''
;Import, export for personal directories
New buttons '''Hamburger/Directories/<directory>/Import,Export''' allow for CSV-download and -upload respectively.

= Requirements =
innovaphone PBX and App Platform from on version 13r3 - version 14r2 is recommended.
==Upgrade Considerations==
From 13r3 to 14r2 no special upgrade scenarios need to be considered as the database structure remains the same. On the other hand, if the new com.innovaphone.contacts API will be used (which helps to add contacts from within the phone apps) and a manual update is performed then the Websocket Checkmark should be set on the PBX App Object.

For prior versions please consider the following:

As always, don't forget to backup an existing App Platform in prior. This 13r3 App Contacts does alter the underlying database scheme.
;13r3 App on 13r1 App Platform, 13r1 PBX:Doesn't work. The 13r3 Contacts App does not work on an 13r1 Application Platform/Environment.
;13r3 App on 13r2 App Platform, 13r2 PBX:The 13r3 Contacts App works with the restriction, that the reverse lookup for private address books doesn't work. For full feature set, also upgrade the App Platform and PBX to 13r3.

=Apps=
=== Contacts App (innovaphone-contacts) ===
The regular app
=== Contacts Admin App (innovaphone-contacts-admin) ===
Features a menu (top-right) to manually upload a CSV file
=== Contacts Search API (innovaphone-contacts-searchapi) ===
This hidden app rovides a search API to other apps, e.g. for the Phone App

= Concept =
General contact entries and entries for personal directories are stored within the same database. With the table '''acl''' which is acting as an access control list, restricted views and edit rights for personal directories can be granted.

This way, only the owner of a personal directory (and granted user or groups) can see the content.

==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)
;Formatted number
:A filter is applied to the original number before saving to remove all non-dialable characters. (This means that only <code>0-9,+,*,#</code> remain after that) This formatted 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 [[Reference13r1:Concept_Number_Adjustments_%28Dialing_Location%29 |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.

==List of Attributes==
The list of currently available attributes for a contacts entry follows:
;extAnchor
: unique id identifying 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
;uuid
:A constant universal unique id as string. Internally assigned during entry creation.

==List of Text-Indexable Attributes==
Attributes to be considered for the full-text index
*cn
*sn
*givenname
*company
*displayname
*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. The purpose of the LDAP server functionality is to service innovaphone LDAP clients, such as desk phones.
The LDAP server only supports a proprietary search by means of a meta attribute<ref>Meta attribute: Here an attribute with a special meaning and that is non-physical, not existing within the database</ref>, 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)''

'''Important:'''

Note, that access to restricted/personal phone books requires the proprietary scheme within the LDAP client, mentioned above.

Currently, this is available in the innovaphone IP phone LDAP clients from 13r3 on, but not on 3rd party devices nor our DECT gateways (IP120x). On these clients, only contact data in unrestricted phone books is searched.

===Sample Phone Configuration, innovaphone===
Phone/User-X/Directories/External LDAP Server
;Enable: Active
;Use TLS: Active
;Server: <host adddress of App Platform>
;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''

= Personal Address Book Details =
Contact entries can be added, edited and deleted. It is also possible to create and maintain personal address book(s), as well as share them with other users or whole user groups.

Only user/groups with sufficient rights, will be able to see other address books. An Access control list (acl) is used, to control these rights.

Groups correspond to PBX-groups. The Contacts App gets to know only active PBX-group memberships.

By default, only the user who created an address book, is able to see the content.

==Maintain a Personal Address Book==
;Creating a Personal Address Book
:Click on '''+Contact''' and proceed. If no directory existed before, one will be automatically created by the name pattern '''Personal Directory: <user's short name>'''.
:Or click on the burger menu in the top right corner inside the Contacts-App, and there on the '''"Directories"'''. Now click on the '''"+"'''-Symbol, choose a suitable name and confirm your name via '''"Save"''' button. A new address book is created.
;Adding a new contact
Click on the '''"+"'''-Symbol in the top right corner inside the Contacts-App and select an address book, where you want the contact to be stored in. Now fill in the contact information (the fields ''"name"'' and ''"last name"'' '''have to be filled''') and save it via '''"Save"'''-button.
;Editing an existing contact
Search for the contact you want to edit via the search box inside the Contacts-App. Click on the '''"Details"'''-field on the right of the contact entry. Now click on the bottom on the '''"Edit"'''-button, click on the entry you want to edit and after your change, save it via '''"Save"'''-button on the bottom.
;Delete an existing contact
Search for the contact you want to edit via the search box inside the Contacts-App. Click on the '''"Details"'''-field on the right of the contact entry. Now click on the bottom on the '''"Edit"'''-button, and on the '''"trashcan"'''-symbol at the top. After confirmation, the entry is deleted.

==Sharing of Address Book==
;Share globally
*Either remove all rules from a personal directory. Such a configuration corresponds to pre-13r3 capabilities. Up to 13r2 there weren't any visibility rules available.
*Or make every PBX user an active member of a group e.g. "everybody" and add a directory rule for that group "everybody".

;Share with single user(s)
Click on the menu in the top right corner inside the Contacts-App, click on '''"directories"''' and select a directory, you want to share.

Now click on the '''"+"'''-symbol and select '''"User"''' as type. In the input field, you can enter and therefore filter for all available users. Select the user, whom you want to give access and select either if the user should have admin-rights or not. Now click on '''Ok''' and submit your change with another click on '''Ok'''.

;Share with a group
Click on the menu in the top right corner inside the Contacts-App, click on '''"directories"''' and select a directory, you want to share.

Now click on the '''"+"'''-symbol and select '''"Group"''' as type. In the input field, you can enter and therefore filter for all available PBX groups. Also select, if the user should have admin-rights or not. Now click on '''Ok''' and submit your change with another click on '''Ok'''-button.

;Revoke of granted rights
You can also revoke previous granted rights by just clicking on the user/group at the access control list, and click on the '''trashcan''' symbol. Now submit your change with another click on '''Ok'''-button.

==Upload a new Directory==
The Contacts Admin App allows uploading a CSV file as known from the 13r2 version ('''Hamburger/Import'''). In the course of an upload operation, a new directory will be created. The newly assigned directory name will be the name of the CSV file.
After uploading, the visibility setting of the new directory should be administrated as stated before under [[#Sharing_of_Address_Book|Sharing of Address Book]]

==Terminology==
;ACL: Access control list. Refers the database table ''acl'' and rows/entries therein.
;Directory: Refers the database table ''dbs'' and rows/entries therein. All contact entries referencing a ''dbs''-row make up the content of a directory.
;Address Book: Synonymous with ''Directory''
;Contacts Admin: A user utilizing the Contacts Admin App (via App URL, ending with ../innovaphone-contacts-admin)
;Directory Admin: A user entitled the admin right for a directory. Either by user-wise or by group-wise ACL entry.
;Directory User/Viewer: A user entitled the viewing right for a directory. Either by user-wise or by group-wise ACL entry.

==Database Changes==
Three tables realize the functionality for personal directories.
*Table '''dbs'''. Each row represents a directory. Two new columns ''displayname, sip'' where added.
**'''displayname''' Name display.
**'''sip''' Creator's sip name, if available.
*Table '''acl'''.New table acting as access control list. Each row references a directory as listed by table ''dbs'' and is going to grant view- and admin-right to a specific user or group.
**'''dbsid''' Reference into table dbs.
**'''name''' The name of a user or a group.
**'''acltype''' A numeric value: user(0), group(1)
**'''admin''' Granting edit right: admin(true), non-admin(false)
*Table '''entries'''. Each row within this pre-exisisting table represents a contact entry. The column ''dbsid'' informs about whether an entry belongs to a specific directory.

<pre>
#Excerpt for an additional directory ''Persönliches Verzeichnis: mst'' with one contact entry.

root@app-platform|/mnt/sda2/home/admin> psql -d "innovaphone.com_contacts" -c "select * from dbs"
id | uri | displayname | sip
----+------------------------------------------------------+--------------------------------+-----
7 | file:///4eaae395-9971-40fb-9a05-dfae1d023f12?sip=mst | Persönliches Verzeichnis: mst | mst # Specification for directory ('Persönliches Verzeichnis: mst')

root@app-platform|/mnt/sda2/home/admin> psql -d "innovaphone.com_contacts" -c "select * from acl"
id | dbsid | name | acltype | admin
----+-------+------+---------+-------
5 | 7 | mst | 0 | t #user 'mst' can view and edit directory with dbsid=7 ('Persönliches Verzeichnis: mst')

root@app-platform|/mnt/sda2/home/admin> psql -d "innovaphone.com_contacts" -c "select sn,givenname,company,id,dbsid from entries where dbsid=7"
sn | givenname | company | id | dbsid
----------+-----------+--------------+-------+-------
Duck | Dagobert | Duck Corp. | 51394 | 7 # main table entries contains 1 entry belonging to ('Persönliches Verzeichnis: mst')

</pre>

==Reverse Number Lookup for Personal Directories==
Queries into directories are access-checked by looking-up and enforcing ACL-rules. The information on whose name is being queried and which group memberships are taking effect is needed for this process.

Websocket connections to the Contacts App service carry those infos within the SDK method ''AppWebsocketConnectComplete()''.
LDAP connections pass this information within a proprietary LDAP control together with an LDAP searchRequest message.

The PBX's centralized Reverse Lookup service (see ''PBX/Config/General/Reverse Lookup URL'') does support this mechanism. That is, for every LDAP searchRequest the affected user's name and active group memberships are going to be sent towards the Contacts App's LDAP server.

See also [[{{NAMESPACE}}:Concept_Reverse_Lookup|concept article on reverse lookup]].

=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<ref>For a windows distribution: e.g.: https://curl.haxx.se/download.html </ref><ref>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</ref>
The required user and password content corresponds to the configuration underneath '''PBX Manager/AP Contacts/Configuration/User(HTTP Post)''' and '''Password(HTTP Post)'''
<syntaxhighlight lang="powershell">
# csv.ps1
# Sample powershell script demonstrating how to HTTP POST a CSV file towards the Contacts App service.
# .\bin\curl must be present, e.g. from https://curl.haxx.se/download.html
# Examples:
# 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 ""
</syntaxhighlight>
== The URL ==
The first part of the URL (''example.com/contacts01'') is the ''Webserver path'' configured for the ''Contacts'' instance in the ''App Platform Manager''. It must be followed by the literal <code>post</code>. 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.

=Troubleshooting=
To collect debugging data, activate the '''''App''''' and '''''App WebSocket''''' trace options at the contacts instance on the App Platform Manager. Now reproduce the issue and save the logfile.

==Manually Deleting an uploaded File==
A directory is deleteable by clicking '''Hamburger/Directories/<directory>/Delete(Symbol: Trash-Can)''' and a progressing through the confirmation dialog afterwards.

==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<ref>putty: https://putty.org</ref>
<syntaxhighlight lang="bash">
#Login
#===================================================================
login as: admin
Using keyboard-interactive authentication.
Password:

#Elevate to super-user rights, Command 'su'
#===================================================================
admin@app-platform|/mnt/sda2/home/admin> su
Password:

#List number of contacts in main table entries
#===================================================================
root@app-platform|/mnt/sda2/home/admin> psql -d "innovaphone.com_contacts" -c "select count(*) from entries"
count
-------
94
(1 row)

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

#List number of contacts in main table entries
#===================================================================
root@app-platform|/mnt/sda2/home/admin> psql -d "innovaphone.com_contacts" -c "select count(*) from entries"
count
-------
0
(1 row)
</syntaxhighlight>



= Known Issues =
* [[Support:Contacts_on_HomeScreen_can%27t_be_open_after_modification_on_ContactsAPP | Contacts on HomeScreen can't be open after modification on ContactsAPP]]
* [[Support:Contacts_Upload_Fails_From_Within_myApps_Launcher | Contacts Upload Fails From Within myApps Launcher]]
* [[Support:Forward_search_shows_no_result | Forward Search shows "no result"]]
== DECT Phones Cannot Access Personal Directories ==
DECT gateways do not support the mechanism required to query into directories with restricted access rules. Hence, DECT mobile phones cannot search into such directories.

== No automatic ACL update on name changes ==
If a users h323 name is changed, all ACL entries in address books, to which the user has rights, also need to be changed manually, since there is no automatic update between the PBX and the address books.

= Related =
<references/>

Reference14r2:Concept App Service Contacts

2024-07-25T11:32:24Z

Inno-mst: /* Manually Deleting an uploaded File */ Advertised new delete button

[[Category:Concept|Apps]]
= Applies To =
* App Contacts version 14r2

= Overview =
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, as well as maintaining personal contact books.

Inside Contacts, personal and general entries can be searched (forward lookup) or be used to resolve incoming numbers to their respective name (reverse lookup).

= Features =
*Import: Semicolon (;) separated CSV file
*Database for contact entries: A user interface for retrieval purposes is available.
*API: Search API for other apps
*Edit Functionality: Contact entries are editable.
*Personal Address Book: Every user can maintain one or more personal address books.
*Access Right Management: Owners can maintain access privileges for single users or even groups of users, in order to control visibility of an address book.
== 14r2 Features ==
Features added to the version 14r2
;User-Interface improvements
: Contact entries retrieved are rendered in a condensed card representation. A '''Details'''-button expands and displays remaining contact information
;Presence Updates
:Useful in federation scenarios. For displayed and currently visible contact entries, presence monitoring calls are placed, in order to display availablity status. Underlying resources are going to be freed immediately for entries scrolled out of visibility.
;Fax button
:Placing a call to a fax number is going to start the fax application
;Adding Contacts from the Softphone App
:Contacts can be added by means of a button '''Softphone/Call List/<entry>/"Add Contact"'''
;Import, export for personal directories
New buttons '''Hamburger/Directories/<directory>/Import,Export''' allow for CSV-download and -upload respectively.

= Requirements =
innovaphone PBX and App Platform from on version 13r3 - version 14r2 is recommended.
==Upgrade Considerations==
From 13r3 to 14r2 no special upgrade scenarios need to be considered as the database structure remains the same. On the other hand, if the new com.innovaphone.contacts API will be used (which helps to add contacts from within the phone apps) and a manual update is performed then the Websocket Checkmark should be set on the PBX App Object.

For prior versions please consider the following:

As always, don't forget to backup an existing App Platform in prior. This 13r3 App Contacts does alter the underlying database scheme.
;13r3 App on 13r1 App Platform, 13r1 PBX:Doesn't work. The 13r3 Contacts App does not work on an 13r1 Application Platform/Environment.
;13r3 App on 13r2 App Platform, 13r2 PBX:The 13r3 Contacts App works with the restriction, that the reverse lookup for private address books doesn't work. For full feature set, also upgrade the App Platform and PBX to 13r3.

=Apps=
=== Contacts App (innovaphone-contacts) ===
The regular app
=== Contacts Admin App (innovaphone-contacts-admin) ===
Features a menu (top-right) to manually upload a CSV file
=== Contacts Search API (innovaphone-contacts-searchapi) ===
This hidden app rovides a search API to other apps, e.g. for the Phone App

= Concept =
General contact entries and entries for personal directories are stored within the same database. With the table '''acl''' which is acting as an access control list, restricted views and edit rights for personal directories can be granted.

This way, only the owner of a personal directory (and granted user or groups) can see the content.

==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)
;Formatted number
:A filter is applied to the original number before saving to remove all non-dialable characters. (This means that only <code>0-9,+,*,#</code> remain after that) This formatted 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 [[Reference13r1:Concept_Number_Adjustments_%28Dialing_Location%29 |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.

==List of Attributes==
The list of currently available attributes for a contacts entry follows:
;extAnchor
: unique id identifying 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
;uuid
:A constant universal unique id as string. Internally assigned during entry creation.

==List of Text-Indexable Attributes==
Attributes to be considered for the full-text index
*cn
*sn
*givenname
*company
*displayname
*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. The purpose of the LDAP server functionality is to service innovaphone LDAP clients, such as desk phones.
The LDAP server only supports a proprietary search by means of a meta attribute<ref>Meta attribute: Here an attribute with a special meaning and that is non-physical, not existing within the database</ref>, 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)''

'''Important:'''

Note, that access to restricted/personal phone books requires the proprietary scheme within the LDAP client, mentioned above.

Currently, this is available in the innovaphone IP phone LDAP clients from 13r3 on, but not on 3rd party devices nor our DECT gateways (IP120x). On these clients, only contact data in unrestricted phone books is searched.

===Sample Phone Configuration, innovaphone===
Phone/User-X/Directories/External LDAP Server
;Enable: Active
;Use TLS: Active
;Server: <host adddress of App Platform>
;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''

= Personal Address Book Details =
Contact entries can be added, edited and deleted. It is also possible to create and maintain personal address book(s), as well as share them with other users or whole user groups.

Only user/groups with sufficient rights, will be able to see other address books. An Access control list (acl) is used, to control these rights.

Groups correspond to PBX-groups. The Contacts App gets to know only active PBX-group memberships.

By default, only the user who created an address book, is able to see the content.

==Maintain a Personal Address Book==
;Creating a Personal Address Book
:Click on '''+Contact''' and proceed. If no directory existed before, one will be automatically created by the name pattern '''Personal Directory: <user's short name>'''.
:Or click on the burger menu in the top right corner inside the Contacts-App, and there on the '''"Directories"'''. Now click on the '''"+"'''-Symbol, choose a suitable name and confirm your name via '''"Save"''' button. A new address book is created.
;Adding a new contact
Click on the '''"+"'''-Symbol in the top right corner inside the Contacts-App and select an address book, where you want the contact to be stored in. Now fill in the contact information (the fields ''"name"'' and ''"last name"'' '''have to be filled''') and save it via '''"Save"'''-button.
;Editing an existing contact
Search for the contact you want to edit via the search box inside the Contacts-App. Click on the '''"Details"'''-field on the right of the contact entry. Now click on the bottom on the '''"Edit"'''-button, click on the entry you want to edit and after your change, save it via '''"Save"'''-button on the bottom.
;Delete an existing contact
Search for the contact you want to edit via the search box inside the Contacts-App. Click on the '''"Details"'''-field on the right of the contact entry. Now click on the bottom on the '''"Edit"'''-button, and on the '''"trashcan"'''-symbol at the top. After confirmation, the entry is deleted.

==Sharing of Address Book==
;Share globally
*Either remove all rules from a personal directory. Such a configuration corresponds to pre-13r3 capabilities. Up to 13r2 there weren't any visibility rules available.
*Or make every PBX user an active member of a group e.g. "everybody" and add a directory rule for that group "everybody".

;Share with single user(s)
Click on the menu in the top right corner inside the Contacts-App, click on '''"directories"''' and select a directory, you want to share.

Now click on the '''"+"'''-symbol and select '''"User"''' as type. In the input field, you can enter and therefore filter for all available users. Select the user, whom you want to give access and select either if the user should have admin-rights or not. Now click on '''Ok''' and submit your change with another click on '''Ok'''.

;Share with a group
Click on the menu in the top right corner inside the Contacts-App, click on '''"directories"''' and select a directory, you want to share.

Now click on the '''"+"'''-symbol and select '''"Group"''' as type. In the input field, you can enter and therefore filter for all available PBX groups. Also select, if the user should have admin-rights or not. Now click on '''Ok''' and submit your change with another click on '''Ok'''-button.

;Revoke of granted rights
You can also revoke previous granted rights by just clicking on the user/group at the access control list, and click on the '''trashcan''' symbol. Now submit your change with another click on '''Ok'''-button.

==Upload a new Directory==
The Contacts Admin App allows uploading a CSV file as known from the 13r2 version ('''Hamburger/Import'''). In the course of an upload operation, a new directory will be created. The newly assigned directory name will be the name of the CSV file.
After uploading, the visibility setting of the new directory should be administrated as stated before under [[#Sharing_of_Address_Book|Sharing of Address Book]]

==Terminology==
;ACL: Access control list. Refers the database table ''acl'' and rows/entries therein.
;Directory: Refers the database table ''dbs'' and rows/entries therein. All contact entries referencing a ''dbs''-row make up the content of a directory.
;Address Book: Synonymous with ''Directory''
;Contacts Admin: A user utilizing the Contacts Admin App (via App URL, ending with ../innovaphone-contacts-admin)
;Directory Admin: A user entitled the admin right for a directory. Either by user-wise or by group-wise ACL entry.
;Directory User/Viewer: A user entitled the viewing right for a directory. Either by user-wise or by group-wise ACL entry.

==Database Changes==
Three tables realize the functionality for personal directories.
*Table '''dbs'''. Each row represents a directory. Two new columns ''displayname, sip'' where added.
**'''displayname''' Name display.
**'''sip''' Creator's sip name, if available.
*Table '''acl'''.New table acting as access control list. Each row references a directory as listed by table ''dbs'' and is going to grant view- and admin-right to a specific user or group.
**'''dbsid''' Reference into table dbs.
**'''name''' The name of a user or a group.
**'''acltype''' A numeric value: user(0), group(1)
**'''admin''' Granting edit right: admin(true), non-admin(false)
*Table '''entries'''. Each row within this pre-exisisting table represents a contact entry. The column ''dbsid'' informs about whether an entry belongs to a specific directory.

<pre>
#Excerpt for an additional directory ''Persönliches Verzeichnis: mst'' with one contact entry.

root@app-platform|/mnt/sda2/home/admin> psql -d "innovaphone.com_contacts" -c "select * from dbs"
id | uri | displayname | sip
----+------------------------------------------------------+--------------------------------+-----
7 | file:///4eaae395-9971-40fb-9a05-dfae1d023f12?sip=mst | Persönliches Verzeichnis: mst | mst # Specification for directory ('Persönliches Verzeichnis: mst')

root@app-platform|/mnt/sda2/home/admin> psql -d "innovaphone.com_contacts" -c "select * from acl"
id | dbsid | name | acltype | admin
----+-------+------+---------+-------
5 | 7 | mst | 0 | t #user 'mst' can view and edit directory with dbsid=7 ('Persönliches Verzeichnis: mst')

root@app-platform|/mnt/sda2/home/admin> psql -d "innovaphone.com_contacts" -c "select sn,givenname,company,id,dbsid from entries where dbsid=7"
sn | givenname | company | id | dbsid
----------+-----------+--------------+-------+-------
Duck | Dagobert | Duck Corp. | 51394 | 7 # main table entries contains 1 entry belonging to ('Persönliches Verzeichnis: mst')

</pre>

==Reverse Number Lookup for Personal Directories==
Queries into directories are access-checked by looking-up and enforcing ACL-rules. The information on whose name is being queried and which group memberships are taking effect is needed for this process.

Websocket connections to the Contacts App service carry those infos within the SDK method ''AppWebsocketConnectComplete()''.
LDAP connections pass this information within a proprietary LDAP control together with an LDAP searchRequest message.

The PBX's centralized Reverse Lookup service (see ''PBX/Config/General/Reverse Lookup URL'') does support this mechanism. That is, for every LDAP searchRequest the affected user's name and active group memberships are going to be sent towards the Contacts App's LDAP server.

See also [[{{NAMESPACE}}:Concept_Reverse_Lookup|concept article on reverse lookup]].

=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<ref>For a windows distribution: e.g.: https://curl.haxx.se/download.html </ref><ref>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</ref>
The required user and password content corresponds to the configuration underneath '''PBX Manager/AP Contacts/Configuration/User(HTTP Post)''' and '''Password(HTTP Post)'''
<syntaxhighlight lang="powershell">
# csv.ps1
# Sample powershell script demonstrating how to HTTP POST a CSV file towards the Contacts App service.
# .\bin\curl must be present, e.g. from https://curl.haxx.se/download.html
# Examples:
# 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 ""
</syntaxhighlight>
== The URL ==
The first part of the URL (''example.com/contacts01'') is the ''Webserver path'' configured for the ''Contacts'' instance in the ''App Platform Manager''. It must be followed by the literal <code>post</code>. 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.

=Troubleshooting=
To collect debugging data, activate the '''''App''''' and '''''App WebSocket''''' trace options at the contacts instance on the App Platform Manager. Now reproduce the issue and save the logfile.

==Manually Deleting an uploaded File==
A directory is deleteable by clicking '''Hamburger/Directories/<directory>/Delete(Symbol: Trash-Can)''' and a progressing through the confirmation dialog afterwards.

==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<ref>putty: https://putty.org</ref>
<syntaxhighlight lang="bash">
#Login
#===================================================================
login as: admin
Using keyboard-interactive authentication.
Password:

#Elevate to super-user rights, Command 'su'
#===================================================================
admin@app-platform|/mnt/sda2/home/admin> su
Password:

#List number of contacts in main table entries
#===================================================================
root@app-platform|/mnt/sda2/home/admin> psql -d "innovaphone.com_contacts" -c "select count(*) from entries"
count
-------
94
(1 row)

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

#List number of contacts in main table entries
#===================================================================
root@app-platform|/mnt/sda2/home/admin> psql -d "innovaphone.com_contacts" -c "select count(*) from entries"
count
-------
0
(1 row)
</syntaxhighlight>

==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<ref>putty: https://putty.org</ref>
<syntaxhighlight lang="bash">
#Login
#===================================================================
login as: admin
Using keyboard-interactive authentication.
Password:

#Elevate to super-user rights, Command 'su'
#===================================================================
admin@app-platform|/mnt/sda2/home/admin> su
Password:

#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

#Retrieve all database entries, separate them by ; and store in file
#===================================================================
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"

</syntaxhighlight>

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 =
* [[Support:Contacts_on_HomeScreen_can%27t_be_open_after_modification_on_ContactsAPP | Contacts on HomeScreen can't be open after modification on ContactsAPP]]
* [[Support:Contacts_Upload_Fails_From_Within_myApps_Launcher | Contacts Upload Fails From Within myApps Launcher]]
* [[Support:Forward_search_shows_no_result | Forward Search shows "no result"]]
== DECT Phones Cannot Access Personal Directories ==
DECT gateways do not support the mechanism required to query into directories with restricted access rules. Hence, DECT mobile phones cannot search into such directories.

== No automatic ACL update on name changes ==
If a users h323 name is changed, all ACL entries in address books, to which the user has rights, also need to be changed manually, since there is no automatic update between the PBX and the address books.

= Related =
<references/>

Reference14r2:Concept App Service Contacts

2024-07-25T11:23:18Z

Inno-mst: /* Maintain a Personal Address Book */ Added directory creation via "+Contact"

[[Category:Concept|Apps]]
= Applies To =
* App Contacts version 14r2

= Overview =
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, as well as maintaining personal contact books.

Inside Contacts, personal and general entries can be searched (forward lookup) or be used to resolve incoming numbers to their respective name (reverse lookup).

= Features =
*Import: Semicolon (;) separated CSV file
*Database for contact entries: A user interface for retrieval purposes is available.
*API: Search API for other apps
*Edit Functionality: Contact entries are editable.
*Personal Address Book: Every user can maintain one or more personal address books.
*Access Right Management: Owners can maintain access privileges for single users or even groups of users, in order to control visibility of an address book.
== 14r2 Features ==
Features added to the version 14r2
;User-Interface improvements
: Contact entries retrieved are rendered in a condensed card representation. A '''Details'''-button expands and displays remaining contact information
;Presence Updates
:Useful in federation scenarios. For displayed and currently visible contact entries, presence monitoring calls are placed, in order to display availablity status. Underlying resources are going to be freed immediately for entries scrolled out of visibility.
;Fax button
:Placing a call to a fax number is going to start the fax application
;Adding Contacts from the Softphone App
:Contacts can be added by means of a button '''Softphone/Call List/<entry>/"Add Contact"'''
;Import, export for personal directories
New buttons '''Hamburger/Directories/<directory>/Import,Export''' allow for CSV-download and -upload respectively.

= Requirements =
innovaphone PBX and App Platform from on version 13r3 - version 14r2 is recommended.
==Upgrade Considerations==
From 13r3 to 14r2 no special upgrade scenarios need to be considered as the database structure remains the same. On the other hand, if the new com.innovaphone.contacts API will be used (which helps to add contacts from within the phone apps) and a manual update is performed then the Websocket Checkmark should be set on the PBX App Object.

For prior versions please consider the following:

As always, don't forget to backup an existing App Platform in prior. This 13r3 App Contacts does alter the underlying database scheme.
;13r3 App on 13r1 App Platform, 13r1 PBX:Doesn't work. The 13r3 Contacts App does not work on an 13r1 Application Platform/Environment.
;13r3 App on 13r2 App Platform, 13r2 PBX:The 13r3 Contacts App works with the restriction, that the reverse lookup for private address books doesn't work. For full feature set, also upgrade the App Platform and PBX to 13r3.

=Apps=
=== Contacts App (innovaphone-contacts) ===
The regular app
=== Contacts Admin App (innovaphone-contacts-admin) ===
Features a menu (top-right) to manually upload a CSV file
=== Contacts Search API (innovaphone-contacts-searchapi) ===
This hidden app rovides a search API to other apps, e.g. for the Phone App

= Concept =
General contact entries and entries for personal directories are stored within the same database. With the table '''acl''' which is acting as an access control list, restricted views and edit rights for personal directories can be granted.

This way, only the owner of a personal directory (and granted user or groups) can see the content.

==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)
;Formatted number
:A filter is applied to the original number before saving to remove all non-dialable characters. (This means that only <code>0-9,+,*,#</code> remain after that) This formatted 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 [[Reference13r1:Concept_Number_Adjustments_%28Dialing_Location%29 |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.

==List of Attributes==
The list of currently available attributes for a contacts entry follows:
;extAnchor
: unique id identifying 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
;uuid
:A constant universal unique id as string. Internally assigned during entry creation.

==List of Text-Indexable Attributes==
Attributes to be considered for the full-text index
*cn
*sn
*givenname
*company
*displayname
*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. The purpose of the LDAP server functionality is to service innovaphone LDAP clients, such as desk phones.
The LDAP server only supports a proprietary search by means of a meta attribute<ref>Meta attribute: Here an attribute with a special meaning and that is non-physical, not existing within the database</ref>, 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)''

'''Important:'''

Note, that access to restricted/personal phone books requires the proprietary scheme within the LDAP client, mentioned above.

Currently, this is available in the innovaphone IP phone LDAP clients from 13r3 on, but not on 3rd party devices nor our DECT gateways (IP120x). On these clients, only contact data in unrestricted phone books is searched.

===Sample Phone Configuration, innovaphone===
Phone/User-X/Directories/External LDAP Server
;Enable: Active
;Use TLS: Active
;Server: <host adddress of App Platform>
;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''

= Personal Address Book Details =
Contact entries can be added, edited and deleted. It is also possible to create and maintain personal address book(s), as well as share them with other users or whole user groups.

Only user/groups with sufficient rights, will be able to see other address books. An Access control list (acl) is used, to control these rights.

Groups correspond to PBX-groups. The Contacts App gets to know only active PBX-group memberships.

By default, only the user who created an address book, is able to see the content.

==Maintain a Personal Address Book==
;Creating a Personal Address Book
:Click on '''+Contact''' and proceed. If no directory existed before, one will be automatically created by the name pattern '''Personal Directory: <user's short name>'''.
:Or click on the burger menu in the top right corner inside the Contacts-App, and there on the '''"Directories"'''. Now click on the '''"+"'''-Symbol, choose a suitable name and confirm your name via '''"Save"''' button. A new address book is created.
;Adding a new contact
Click on the '''"+"'''-Symbol in the top right corner inside the Contacts-App and select an address book, where you want the contact to be stored in. Now fill in the contact information (the fields ''"name"'' and ''"last name"'' '''have to be filled''') and save it via '''"Save"'''-button.
;Editing an existing contact
Search for the contact you want to edit via the search box inside the Contacts-App. Click on the '''"Details"'''-field on the right of the contact entry. Now click on the bottom on the '''"Edit"'''-button, click on the entry you want to edit and after your change, save it via '''"Save"'''-button on the bottom.
;Delete an existing contact
Search for the contact you want to edit via the search box inside the Contacts-App. Click on the '''"Details"'''-field on the right of the contact entry. Now click on the bottom on the '''"Edit"'''-button, and on the '''"trashcan"'''-symbol at the top. After confirmation, the entry is deleted.

==Sharing of Address Book==
;Share globally
*Either remove all rules from a personal directory. Such a configuration corresponds to pre-13r3 capabilities. Up to 13r2 there weren't any visibility rules available.
*Or make every PBX user an active member of a group e.g. "everybody" and add a directory rule for that group "everybody".

;Share with single user(s)
Click on the menu in the top right corner inside the Contacts-App, click on '''"directories"''' and select a directory, you want to share.

Now click on the '''"+"'''-symbol and select '''"User"''' as type. In the input field, you can enter and therefore filter for all available users. Select the user, whom you want to give access and select either if the user should have admin-rights or not. Now click on '''Ok''' and submit your change with another click on '''Ok'''.

;Share with a group
Click on the menu in the top right corner inside the Contacts-App, click on '''"directories"''' and select a directory, you want to share.

Now click on the '''"+"'''-symbol and select '''"Group"''' as type. In the input field, you can enter and therefore filter for all available PBX groups. Also select, if the user should have admin-rights or not. Now click on '''Ok''' and submit your change with another click on '''Ok'''-button.

;Revoke of granted rights
You can also revoke previous granted rights by just clicking on the user/group at the access control list, and click on the '''trashcan''' symbol. Now submit your change with another click on '''Ok'''-button.

==Upload a new Directory==
The Contacts Admin App allows uploading a CSV file as known from the 13r2 version ('''Hamburger/Import'''). In the course of an upload operation, a new directory will be created. The newly assigned directory name will be the name of the CSV file.
After uploading, the visibility setting of the new directory should be administrated as stated before under [[#Sharing_of_Address_Book|Sharing of Address Book]]

==Terminology==
;ACL: Access control list. Refers the database table ''acl'' and rows/entries therein.
;Directory: Refers the database table ''dbs'' and rows/entries therein. All contact entries referencing a ''dbs''-row make up the content of a directory.
;Address Book: Synonymous with ''Directory''
;Contacts Admin: A user utilizing the Contacts Admin App (via App URL, ending with ../innovaphone-contacts-admin)
;Directory Admin: A user entitled the admin right for a directory. Either by user-wise or by group-wise ACL entry.
;Directory User/Viewer: A user entitled the viewing right for a directory. Either by user-wise or by group-wise ACL entry.

==Database Changes==
Three tables realize the functionality for personal directories.
*Table '''dbs'''. Each row represents a directory. Two new columns ''displayname, sip'' where added.
**'''displayname''' Name display.
**'''sip''' Creator's sip name, if available.
*Table '''acl'''.New table acting as access control list. Each row references a directory as listed by table ''dbs'' and is going to grant view- and admin-right to a specific user or group.
**'''dbsid''' Reference into table dbs.
**'''name''' The name of a user or a group.
**'''acltype''' A numeric value: user(0), group(1)
**'''admin''' Granting edit right: admin(true), non-admin(false)
*Table '''entries'''. Each row within this pre-exisisting table represents a contact entry. The column ''dbsid'' informs about whether an entry belongs to a specific directory.

<pre>
#Excerpt for an additional directory ''Persönliches Verzeichnis: mst'' with one contact entry.

root@app-platform|/mnt/sda2/home/admin> psql -d "innovaphone.com_contacts" -c "select * from dbs"
id | uri | displayname | sip
----+------------------------------------------------------+--------------------------------+-----
7 | file:///4eaae395-9971-40fb-9a05-dfae1d023f12?sip=mst | Persönliches Verzeichnis: mst | mst # Specification for directory ('Persönliches Verzeichnis: mst')

root@app-platform|/mnt/sda2/home/admin> psql -d "innovaphone.com_contacts" -c "select * from acl"
id | dbsid | name | acltype | admin
----+-------+------+---------+-------
5 | 7 | mst | 0 | t #user 'mst' can view and edit directory with dbsid=7 ('Persönliches Verzeichnis: mst')

root@app-platform|/mnt/sda2/home/admin> psql -d "innovaphone.com_contacts" -c "select sn,givenname,company,id,dbsid from entries where dbsid=7"
sn | givenname | company | id | dbsid
----------+-----------+--------------+-------+-------
Duck | Dagobert | Duck Corp. | 51394 | 7 # main table entries contains 1 entry belonging to ('Persönliches Verzeichnis: mst')

</pre>

==Reverse Number Lookup for Personal Directories==
Queries into directories are access-checked by looking-up and enforcing ACL-rules. The information on whose name is being queried and which group memberships are taking effect is needed for this process.

Websocket connections to the Contacts App service carry those infos within the SDK method ''AppWebsocketConnectComplete()''.
LDAP connections pass this information within a proprietary LDAP control together with an LDAP searchRequest message.

The PBX's centralized Reverse Lookup service (see ''PBX/Config/General/Reverse Lookup URL'') does support this mechanism. That is, for every LDAP searchRequest the affected user's name and active group memberships are going to be sent towards the Contacts App's LDAP server.

See also [[{{NAMESPACE}}:Concept_Reverse_Lookup|concept article on reverse lookup]].

=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<ref>For a windows distribution: e.g.: https://curl.haxx.se/download.html </ref><ref>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</ref>
The required user and password content corresponds to the configuration underneath '''PBX Manager/AP Contacts/Configuration/User(HTTP Post)''' and '''Password(HTTP Post)'''
<syntaxhighlight lang="powershell">
# csv.ps1
# Sample powershell script demonstrating how to HTTP POST a CSV file towards the Contacts App service.
# .\bin\curl must be present, e.g. from https://curl.haxx.se/download.html
# Examples:
# 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 ""
</syntaxhighlight>
== The URL ==
The first part of the URL (''example.com/contacts01'') is the ''Webserver path'' configured for the ''Contacts'' instance in the ''App Platform Manager''. It must be followed by the literal <code>post</code>. 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.

=Troubleshooting=
To collect debugging data, activate the '''''App''''' and '''''App WebSocket''''' trace options at the contacts instance on the App Platform Manager. Now reproduce the issue and save the logfile.

==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<ref>putty: https://putty.org</ref>
<syntaxhighlight lang="bash">
#Login
#===================================================================
login as: admin
Using keyboard-interactive authentication.
Password:

#Elevate to super-user rights, Command 'su'
#===================================================================
admin@app-platform|/mnt/sda2/home/admin> su
Password:

#Command 'psql'. Printing the table 'dbs'. Contains 2 file names.
#===================================================================
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)

#Delete the file "brs%20testimport.csv" via its table-ID 5.
#===================================================================
root@app-platform|/mnt/sda2/home/admin> psql -d "innovaphone.com_contacts" -c "delete from dbs where id=5"
DELETE 1

#Printing the table 'dbs'. Contains 1 file name.
#===================================================================
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>

</syntaxhighlight>

==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<ref>putty: https://putty.org</ref>
<syntaxhighlight lang="bash">
#Login
#===================================================================
login as: admin
Using keyboard-interactive authentication.
Password:

#Elevate to super-user rights, Command 'su'
#===================================================================
admin@app-platform|/mnt/sda2/home/admin> su
Password:

#List number of contacts in main table entries
#===================================================================
root@app-platform|/mnt/sda2/home/admin> psql -d "innovaphone.com_contacts" -c "select count(*) from entries"
count
-------
94
(1 row)

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

#List number of contacts in main table entries
#===================================================================
root@app-platform|/mnt/sda2/home/admin> psql -d "innovaphone.com_contacts" -c "select count(*) from entries"
count
-------
0
(1 row)
</syntaxhighlight>

==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<ref>putty: https://putty.org</ref>
<syntaxhighlight lang="bash">
#Login
#===================================================================
login as: admin
Using keyboard-interactive authentication.
Password:

#Elevate to super-user rights, Command 'su'
#===================================================================
admin@app-platform|/mnt/sda2/home/admin> su
Password:

#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

#Retrieve all database entries, separate them by ; and store in file
#===================================================================
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"

</syntaxhighlight>

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 =
* [[Support:Contacts_on_HomeScreen_can%27t_be_open_after_modification_on_ContactsAPP | Contacts on HomeScreen can't be open after modification on ContactsAPP]]
* [[Support:Contacts_Upload_Fails_From_Within_myApps_Launcher | Contacts Upload Fails From Within myApps Launcher]]
* [[Support:Forward_search_shows_no_result | Forward Search shows "no result"]]
== DECT Phones Cannot Access Personal Directories ==
DECT gateways do not support the mechanism required to query into directories with restricted access rules. Hence, DECT mobile phones cannot search into such directories.

== No automatic ACL update on name changes ==
If a users h323 name is changed, all ACL entries in address books, to which the user has rights, also need to be changed manually, since there is no automatic update between the PBX and the address books.

= Related =
<references/>

Reference14r2:Concept App Service Contacts

2024-07-25T11:16:39Z

Inno-mst: /* Personal Address Book Details */

[[Category:Concept|Apps]]
= Applies To =
* App Contacts version 14r2

= Overview =
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, as well as maintaining personal contact books.

Inside Contacts, personal and general entries can be searched (forward lookup) or be used to resolve incoming numbers to their respective name (reverse lookup).

= Features =
*Import: Semicolon (;) separated CSV file
*Database for contact entries: A user interface for retrieval purposes is available.
*API: Search API for other apps
*Edit Functionality: Contact entries are editable.
*Personal Address Book: Every user can maintain one or more personal address books.
*Access Right Management: Owners can maintain access privileges for single users or even groups of users, in order to control visibility of an address book.
== 14r2 Features ==
Features added to the version 14r2
;User-Interface improvements
: Contact entries retrieved are rendered in a condensed card representation. A '''Details'''-button expands and displays remaining contact information
;Presence Updates
:Useful in federation scenarios. For displayed and currently visible contact entries, presence monitoring calls are placed, in order to display availablity status. Underlying resources are going to be freed immediately for entries scrolled out of visibility.
;Fax button
:Placing a call to a fax number is going to start the fax application
;Adding Contacts from the Softphone App
:Contacts can be added by means of a button '''Softphone/Call List/<entry>/"Add Contact"'''
;Import, export for personal directories
New buttons '''Hamburger/Directories/<directory>/Import,Export''' allow for CSV-download and -upload respectively.

= Requirements =
innovaphone PBX and App Platform from on version 13r3 - version 14r2 is recommended.
==Upgrade Considerations==
From 13r3 to 14r2 no special upgrade scenarios need to be considered as the database structure remains the same. On the other hand, if the new com.innovaphone.contacts API will be used (which helps to add contacts from within the phone apps) and a manual update is performed then the Websocket Checkmark should be set on the PBX App Object.

For prior versions please consider the following:

As always, don't forget to backup an existing App Platform in prior. This 13r3 App Contacts does alter the underlying database scheme.
;13r3 App on 13r1 App Platform, 13r1 PBX:Doesn't work. The 13r3 Contacts App does not work on an 13r1 Application Platform/Environment.
;13r3 App on 13r2 App Platform, 13r2 PBX:The 13r3 Contacts App works with the restriction, that the reverse lookup for private address books doesn't work. For full feature set, also upgrade the App Platform and PBX to 13r3.

=Apps=
=== Contacts App (innovaphone-contacts) ===
The regular app
=== Contacts Admin App (innovaphone-contacts-admin) ===
Features a menu (top-right) to manually upload a CSV file
=== Contacts Search API (innovaphone-contacts-searchapi) ===
This hidden app rovides a search API to other apps, e.g. for the Phone App

= Concept =
General contact entries and entries for personal directories are stored within the same database. With the table '''acl''' which is acting as an access control list, restricted views and edit rights for personal directories can be granted.

This way, only the owner of a personal directory (and granted user or groups) can see the content.

==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)
;Formatted number
:A filter is applied to the original number before saving to remove all non-dialable characters. (This means that only <code>0-9,+,*,#</code> remain after that) This formatted 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 [[Reference13r1:Concept_Number_Adjustments_%28Dialing_Location%29 |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.

==List of Attributes==
The list of currently available attributes for a contacts entry follows:
;extAnchor
: unique id identifying 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
;uuid
:A constant universal unique id as string. Internally assigned during entry creation.

==List of Text-Indexable Attributes==
Attributes to be considered for the full-text index
*cn
*sn
*givenname
*company
*displayname
*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. The purpose of the LDAP server functionality is to service innovaphone LDAP clients, such as desk phones.
The LDAP server only supports a proprietary search by means of a meta attribute<ref>Meta attribute: Here an attribute with a special meaning and that is non-physical, not existing within the database</ref>, 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)''

'''Important:'''

Note, that access to restricted/personal phone books requires the proprietary scheme within the LDAP client, mentioned above.

Currently, this is available in the innovaphone IP phone LDAP clients from 13r3 on, but not on 3rd party devices nor our DECT gateways (IP120x). On these clients, only contact data in unrestricted phone books is searched.

===Sample Phone Configuration, innovaphone===
Phone/User-X/Directories/External LDAP Server
;Enable: Active
;Use TLS: Active
;Server: <host adddress of App Platform>
;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''

= Personal Address Book Details =
Contact entries can be added, edited and deleted. It is also possible to create and maintain personal address book(s), as well as share them with other users or whole user groups.

Only user/groups with sufficient rights, will be able to see other address books. An Access control list (acl) is used, to control these rights.

Groups correspond to PBX-groups. The Contacts App gets to know only active PBX-group memberships.

By default, only the user who created an address book, is able to see the content.

==Maintain a Personal Address Book==
;Creating a Personal Address Book
Click on the burger menu in the top right corner inside the Contacts-App, and there on the '''"Directories"'''. Now click on the '''"+"'''-Symbol, choose a suitable name and confirm your name via '''"Save"''' button. A new address book is created.
;Adding a new contact
Click on the '''"+"'''-Symbol in the top right corner inside the Contacts-App and select an address book, where you want the contact to be stored in. Now fill in the contact information (the fields ''"name"'' and ''"last name"'' '''have to be filled''') and save it via '''"Save"'''-button.
;Editing an existing contact
Search for the contact you want to edit via the search box inside the Contacts-App. Click on the '''"Details"'''-field on the right of the contact entry. Now click on the bottom on the '''"Edit"'''-button, click on the entry you want to edit and after your change, save it via '''"Save"'''-button on the bottom.
;Delete an existing contact
Search for the contact you want to edit via the search box inside the Contacts-App. Click on the '''"Details"'''-field on the right of the contact entry. Now click on the bottom on the '''"Edit"'''-button, and on the '''"trashcan"'''-symbol at the top. After confirmation, the entry is deleted.

==Sharing of Address Book==
;Share globally
*Either remove all rules from a personal directory. Such a configuration corresponds to pre-13r3 capabilities. Up to 13r2 there weren't any visibility rules available.
*Or make every PBX user an active member of a group e.g. "everybody" and add a directory rule for that group "everybody".

;Share with single user(s)
Click on the menu in the top right corner inside the Contacts-App, click on '''"directories"''' and select a directory, you want to share.

Now click on the '''"+"'''-symbol and select '''"User"''' as type. In the input field, you can enter and therefore filter for all available users. Select the user, whom you want to give access and select either if the user should have admin-rights or not. Now click on '''Ok''' and submit your change with another click on '''Ok'''.

;Share with a group
Click on the menu in the top right corner inside the Contacts-App, click on '''"directories"''' and select a directory, you want to share.

Now click on the '''"+"'''-symbol and select '''"Group"''' as type. In the input field, you can enter and therefore filter for all available PBX groups. Also select, if the user should have admin-rights or not. Now click on '''Ok''' and submit your change with another click on '''Ok'''-button.

;Revoke of granted rights
You can also revoke previous granted rights by just clicking on the user/group at the access control list, and click on the '''trashcan''' symbol. Now submit your change with another click on '''Ok'''-button.

==Upload a new Directory==
The Contacts Admin App allows uploading a CSV file as known from the 13r2 version ('''Hamburger/Import'''). In the course of an upload operation, a new directory will be created. The newly assigned directory name will be the name of the CSV file.
After uploading, the visibility setting of the new directory should be administrated as stated before under [[#Sharing_of_Address_Book|Sharing of Address Book]]

==Terminology==
;ACL: Access control list. Refers the database table ''acl'' and rows/entries therein.
;Directory: Refers the database table ''dbs'' and rows/entries therein. All contact entries referencing a ''dbs''-row make up the content of a directory.
;Address Book: Synonymous with ''Directory''
;Contacts Admin: A user utilizing the Contacts Admin App (via App URL, ending with ../innovaphone-contacts-admin)
;Directory Admin: A user entitled the admin right for a directory. Either by user-wise or by group-wise ACL entry.
;Directory User/Viewer: A user entitled the viewing right for a directory. Either by user-wise or by group-wise ACL entry.

==Database Changes==
Three tables realize the functionality for personal directories.
*Table '''dbs'''. Each row represents a directory. Two new columns ''displayname, sip'' where added.
**'''displayname''' Name display.
**'''sip''' Creator's sip name, if available.
*Table '''acl'''.New table acting as access control list. Each row references a directory as listed by table ''dbs'' and is going to grant view- and admin-right to a specific user or group.
**'''dbsid''' Reference into table dbs.
**'''name''' The name of a user or a group.
**'''acltype''' A numeric value: user(0), group(1)
**'''admin''' Granting edit right: admin(true), non-admin(false)
*Table '''entries'''. Each row within this pre-exisisting table represents a contact entry. The column ''dbsid'' informs about whether an entry belongs to a specific directory.

<pre>
#Excerpt for an additional directory ''Persönliches Verzeichnis: mst'' with one contact entry.

root@app-platform|/mnt/sda2/home/admin> psql -d "innovaphone.com_contacts" -c "select * from dbs"
id | uri | displayname | sip
----+------------------------------------------------------+--------------------------------+-----
7 | file:///4eaae395-9971-40fb-9a05-dfae1d023f12?sip=mst | Persönliches Verzeichnis: mst | mst # Specification for directory ('Persönliches Verzeichnis: mst')

root@app-platform|/mnt/sda2/home/admin> psql -d "innovaphone.com_contacts" -c "select * from acl"
id | dbsid | name | acltype | admin
----+-------+------+---------+-------
5 | 7 | mst | 0 | t #user 'mst' can view and edit directory with dbsid=7 ('Persönliches Verzeichnis: mst')

root@app-platform|/mnt/sda2/home/admin> psql -d "innovaphone.com_contacts" -c "select sn,givenname,company,id,dbsid from entries where dbsid=7"
sn | givenname | company | id | dbsid
----------+-----------+--------------+-------+-------
Duck | Dagobert | Duck Corp. | 51394 | 7 # main table entries contains 1 entry belonging to ('Persönliches Verzeichnis: mst')

</pre>

==Reverse Number Lookup for Personal Directories==
Queries into directories are access-checked by looking-up and enforcing ACL-rules. The information on whose name is being queried and which group memberships are taking effect is needed for this process.

Websocket connections to the Contacts App service carry those infos within the SDK method ''AppWebsocketConnectComplete()''.
LDAP connections pass this information within a proprietary LDAP control together with an LDAP searchRequest message.

The PBX's centralized Reverse Lookup service (see ''PBX/Config/General/Reverse Lookup URL'') does support this mechanism. That is, for every LDAP searchRequest the affected user's name and active group memberships are going to be sent towards the Contacts App's LDAP server.

See also [[{{NAMESPACE}}:Concept_Reverse_Lookup|concept article on reverse lookup]].

=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<ref>For a windows distribution: e.g.: https://curl.haxx.se/download.html </ref><ref>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</ref>
The required user and password content corresponds to the configuration underneath '''PBX Manager/AP Contacts/Configuration/User(HTTP Post)''' and '''Password(HTTP Post)'''
<syntaxhighlight lang="powershell">
# csv.ps1
# Sample powershell script demonstrating how to HTTP POST a CSV file towards the Contacts App service.
# .\bin\curl must be present, e.g. from https://curl.haxx.se/download.html
# Examples:
# 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 ""
</syntaxhighlight>
== The URL ==
The first part of the URL (''example.com/contacts01'') is the ''Webserver path'' configured for the ''Contacts'' instance in the ''App Platform Manager''. It must be followed by the literal <code>post</code>. 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.

=Troubleshooting=
To collect debugging data, activate the '''''App''''' and '''''App WebSocket''''' trace options at the contacts instance on the App Platform Manager. Now reproduce the issue and save the logfile.

==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<ref>putty: https://putty.org</ref>
<syntaxhighlight lang="bash">
#Login
#===================================================================
login as: admin
Using keyboard-interactive authentication.
Password:

#Elevate to super-user rights, Command 'su'
#===================================================================
admin@app-platform|/mnt/sda2/home/admin> su
Password:

#Command 'psql'. Printing the table 'dbs'. Contains 2 file names.
#===================================================================
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)

#Delete the file "brs%20testimport.csv" via its table-ID 5.
#===================================================================
root@app-platform|/mnt/sda2/home/admin> psql -d "innovaphone.com_contacts" -c "delete from dbs where id=5"
DELETE 1

#Printing the table 'dbs'. Contains 1 file name.
#===================================================================
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>

</syntaxhighlight>

==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<ref>putty: https://putty.org</ref>
<syntaxhighlight lang="bash">
#Login
#===================================================================
login as: admin
Using keyboard-interactive authentication.
Password:

#Elevate to super-user rights, Command 'su'
#===================================================================
admin@app-platform|/mnt/sda2/home/admin> su
Password:

#List number of contacts in main table entries
#===================================================================
root@app-platform|/mnt/sda2/home/admin> psql -d "innovaphone.com_contacts" -c "select count(*) from entries"
count
-------
94
(1 row)

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

#List number of contacts in main table entries
#===================================================================
root@app-platform|/mnt/sda2/home/admin> psql -d "innovaphone.com_contacts" -c "select count(*) from entries"
count
-------
0
(1 row)
</syntaxhighlight>

==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<ref>putty: https://putty.org</ref>
<syntaxhighlight lang="bash">
#Login
#===================================================================
login as: admin
Using keyboard-interactive authentication.
Password:

#Elevate to super-user rights, Command 'su'
#===================================================================
admin@app-platform|/mnt/sda2/home/admin> su
Password:

#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

#Retrieve all database entries, separate them by ; and store in file
#===================================================================
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"

</syntaxhighlight>

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 =
* [[Support:Contacts_on_HomeScreen_can%27t_be_open_after_modification_on_ContactsAPP | Contacts on HomeScreen can't be open after modification on ContactsAPP]]
* [[Support:Contacts_Upload_Fails_From_Within_myApps_Launcher | Contacts Upload Fails From Within myApps Launcher]]
* [[Support:Forward_search_shows_no_result | Forward Search shows "no result"]]
== DECT Phones Cannot Access Personal Directories ==
DECT gateways do not support the mechanism required to query into directories with restricted access rules. Hence, DECT mobile phones cannot search into such directories.

== No automatic ACL update on name changes ==
If a users h323 name is changed, all ACL entries in address books, to which the user has rights, also need to be changed manually, since there is no automatic update between the PBX and the address books.

= Related =
<references/>

Reference14r2:Concept App Service Contacts

2024-07-25T11:11:51Z

Inno-mst: /* Features */ Added 14r2 Features

[[Category:Concept|Apps]]
= Applies To =
* App Contacts version 14r2

= Overview =
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, as well as maintaining personal contact books.

Inside Contacts, personal and general entries can be searched (forward lookup) or be used to resolve incoming numbers to their respective name (reverse lookup).

= Features =
*Import: Semicolon (;) separated CSV file
*Database for contact entries: A user interface for retrieval purposes is available.
*API: Search API for other apps
*Edit Functionality: Contact entries are editable.
*Personal Address Book: Every user can maintain one or more personal address books.
*Access Right Management: Owners can maintain access privileges for single users or even groups of users, in order to control visibility of an address book.
== 14r2 Features ==
Features added to the version 14r2
;User-Interface improvements
: Contact entries retrieved are rendered in a condensed card representation. A '''Details'''-button expands and displays remaining contact information
;Presence Updates
:Useful in federation scenarios. For displayed and currently visible contact entries, presence monitoring calls are placed, in order to display availablity status. Underlying resources are going to be freed immediately for entries scrolled out of visibility.
;Fax button
:Placing a call to a fax number is going to start the fax application
;Adding Contacts from the Softphone App
:Contacts can be added by means of a button '''Softphone/Call List/<entry>/"Add Contact"'''
;Import, export for personal directories
New buttons '''Hamburger/Directories/<directory>/Import,Export''' allow for CSV-download and -upload respectively.

= Requirements =
innovaphone PBX and App Platform from on version 13r3 - version 14r2 is recommended.
==Upgrade Considerations==
From 13r3 to 14r2 no special upgrade scenarios need to be considered as the database structure remains the same. On the other hand, if the new com.innovaphone.contacts API will be used (which helps to add contacts from within the phone apps) and a manual update is performed then the Websocket Checkmark should be set on the PBX App Object.

For prior versions please consider the following:

As always, don't forget to backup an existing App Platform in prior. This 13r3 App Contacts does alter the underlying database scheme.
;13r3 App on 13r1 App Platform, 13r1 PBX:Doesn't work. The 13r3 Contacts App does not work on an 13r1 Application Platform/Environment.
;13r3 App on 13r2 App Platform, 13r2 PBX:The 13r3 Contacts App works with the restriction, that the reverse lookup for private address books doesn't work. For full feature set, also upgrade the App Platform and PBX to 13r3.

=Apps=
=== Contacts App (innovaphone-contacts) ===
The regular app
=== Contacts Admin App (innovaphone-contacts-admin) ===
Features a menu (top-right) to manually upload a CSV file
=== Contacts Search API (innovaphone-contacts-searchapi) ===
This hidden app rovides a search API to other apps, e.g. for the Phone App

= Concept =
General contact entries and entries for personal directories are stored within the same database. With the table '''acl''' which is acting as an access control list, restricted views and edit rights for personal directories can be granted.

This way, only the owner of a personal directory (and granted user or groups) can see the content.

==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)
;Formatted number
:A filter is applied to the original number before saving to remove all non-dialable characters. (This means that only <code>0-9,+,*,#</code> remain after that) This formatted 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 [[Reference13r1:Concept_Number_Adjustments_%28Dialing_Location%29 |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.

==List of Attributes==
The list of currently available attributes for a contacts entry follows:
;extAnchor
: unique id identifying 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
;uuid
:A constant universal unique id as string. Internally assigned during entry creation.

==List of Text-Indexable Attributes==
Attributes to be considered for the full-text index
*cn
*sn
*givenname
*company
*displayname
*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. The purpose of the LDAP server functionality is to service innovaphone LDAP clients, such as desk phones.
The LDAP server only supports a proprietary search by means of a meta attribute<ref>Meta attribute: Here an attribute with a special meaning and that is non-physical, not existing within the database</ref>, 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)''

'''Important:'''

Note, that access to restricted/personal phone books requires the proprietary scheme within the LDAP client, mentioned above.

Currently, this is available in the innovaphone IP phone LDAP clients from 13r3 on, but not on 3rd party devices nor our DECT gateways (IP120x). On these clients, only contact data in unrestricted phone books is searched.

===Sample Phone Configuration, innovaphone===
Phone/User-X/Directories/External LDAP Server
;Enable: Active
;Use TLS: Active
;Server: <host adddress of App Platform>
;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''

= Personal Address Book Details =
From version 13r3 on it is possible, to add, editing and delete contacts. It is also possible to create and maintain personal address book(s), as well as share them with other users or whole user groups.

Only user/groups with sufficient rights, will be able to see other address books. An Access control list (acl) is used, to control these rights.

Groups correspond to PBX-groups. The Contacts App gets to know only active PBX-group memberships.

By default, only the user who created an address book, is able to see the content.

==Maintain a Personal Address Book==
;Creating a Personal Address Book
Click on the burger menu in the top right corner inside the Contacts-App, and there on the '''"Directories"'''. Now click on the '''"+"'''-Symbol, choose a suitable name and confirm your name via '''"Save"''' button. A new address book is created.
;Adding a new contact
Click on the '''"+"'''-Symbol in the top right corner inside the Contacts-App and select an address book, where you want the contact to be stored in. Now fill in the contact information (the fields ''"name"'' and ''"last name"'' '''have to be filled''') and save it via '''"Save"'''-button.
;Editing an existing contact
Search for the contact you want to edit via the search box inside the Contacts-App. Click on the '''"Details"'''-field on the right of the contact entry. Now click on the bottom on the '''"Edit"'''-button, click on the entry you want to edit and after your change, save it via '''"Save"'''-button on the bottom.
;Delete an existing contact
Search for the contact you want to edit via the search box inside the Contacts-App. Click on the '''"Details"'''-field on the right of the contact entry. Now click on the bottom on the '''"Edit"'''-button, and on the '''"trashcan"'''-symbol at the top. After confirmation, the entry is deleted.

==Sharing of Address Book==
;Share globally
*Either remove all rules from a personal directory. Such a configuration corresponds to pre-13r3 capabilities. Up to 13r2 there weren't any visibility rules available.
*Or make every PBX user an active member of a group e.g. "everybody" and add a directory rule for that group "everybody".

;Share with single user(s)
Click on the menu in the top right corner inside the Contacts-App, click on '''"directories"''' and select a directory, you want to share.

Now click on the '''"+"'''-symbol and select '''"User"''' as type. In the input field, you can enter and therefore filter for all available users. Select the user, whom you want to give access and select either if the user should have admin-rights or not. Now click on '''Ok''' and submit your change with another click on '''Ok'''.

;Share with a group
Click on the menu in the top right corner inside the Contacts-App, click on '''"directories"''' and select a directory, you want to share.

Now click on the '''"+"'''-symbol and select '''"Group"''' as type. In the input field, you can enter and therefore filter for all available PBX groups. Also select, if the user should have admin-rights or not. Now click on '''Ok''' and submit your change with another click on '''Ok'''-button.

;Revoke of granted rights
You can also revoke previous granted rights by just clicking on the user/group at the access control list, and click on the '''trashcan''' symbol. Now submit your change with another click on '''Ok'''-button.

==Upload a new Directory==
The Contacts Admin App allows uploading a CSV file as known from the 13r2 version ('''Hamburger/Import'''). In the course of an upload operation, a new directory will be created. The newly assigned directory name will be the name of the CSV file.
After uploading, the visibility setting of the new directory should be administrated as stated before under [[#Sharing_of_Address_Book|Sharing of Address Book]]

==Terminology==
;ACL: Access control list. Refers the database table ''acl'' and rows/entries therein.
;Directory: Refers the database table ''dbs'' and rows/entries therein. All contact entries referencing a ''dbs''-row make up the content of a directory.
;Address Book: Synonymous with ''Directory''
;Contacts Admin: A user utilizing the Contacts Admin App (via App URL, ending with ../innovaphone-contacts-admin)
;Directory Admin: A user entitled the admin right for a directory. Either by user-wise or by group-wise ACL entry.
;Directory User/Viewer: A user entitled the viewing right for a directory. Either by user-wise or by group-wise ACL entry.

==Database Changes==
Three tables realize the functionality for personal directories.
*Table '''dbs'''. Each row represents a directory. Two new columns ''displayname, sip'' where added.
**'''displayname''' Name display.
**'''sip''' Creator's sip name, if available.
*Table '''acl'''.New table acting as access control list. Each row references a directory as listed by table ''dbs'' and is going to grant view- and admin-right to a specific user or group.
**'''dbsid''' Reference into table dbs.
**'''name''' The name of a user or a group.
**'''acltype''' A numeric value: user(0), group(1)
**'''admin''' Granting edit right: admin(true), non-admin(false)
*Table '''entries'''. Each row within this pre-exisisting table represents a contact entry. The column ''dbsid'' informs about whether an entry belongs to a specific directory.

<pre>
#Excerpt for an additional directory ''Persönliches Verzeichnis: mst'' with one contact entry.

root@app-platform|/mnt/sda2/home/admin> psql -d "innovaphone.com_contacts" -c "select * from dbs"
id | uri | displayname | sip
----+------------------------------------------------------+--------------------------------+-----
7 | file:///4eaae395-9971-40fb-9a05-dfae1d023f12?sip=mst | Persönliches Verzeichnis: mst | mst # Specification for directory ('Persönliches Verzeichnis: mst')

root@app-platform|/mnt/sda2/home/admin> psql -d "innovaphone.com_contacts" -c "select * from acl"
id | dbsid | name | acltype | admin
----+-------+------+---------+-------
5 | 7 | mst | 0 | t #user 'mst' can view and edit directory with dbsid=7 ('Persönliches Verzeichnis: mst')

root@app-platform|/mnt/sda2/home/admin> psql -d "innovaphone.com_contacts" -c "select sn,givenname,company,id,dbsid from entries where dbsid=7"
sn | givenname | company | id | dbsid
----------+-----------+--------------+-------+-------
Duck | Dagobert | Duck Corp. | 51394 | 7 # main table entries contains 1 entry belonging to ('Persönliches Verzeichnis: mst')

</pre>

==Reverse Number Lookup for Personal Directories==
Queries into directories are access-checked by looking-up and enforcing ACL-rules. The information on whose name is being queried and which group memberships are taking effect is needed for this process.

Websocket connections to the Contacts App service carry those infos within the SDK method ''AppWebsocketConnectComplete()''.
LDAP connections pass this information within a proprietary LDAP control together with an LDAP searchRequest message.

The PBX's centralized Reverse Lookup service (see ''PBX/Config/General/Reverse Lookup URL'') does support this mechanism. That is, for every LDAP searchRequest the affected user's name and active group memberships are going to be sent towards the Contacts App's LDAP server.

See also [[{{NAMESPACE}}:Concept_Reverse_Lookup|concept article on reverse lookup]].

=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<ref>For a windows distribution: e.g.: https://curl.haxx.se/download.html </ref><ref>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</ref>
The required user and password content corresponds to the configuration underneath '''PBX Manager/AP Contacts/Configuration/User(HTTP Post)''' and '''Password(HTTP Post)'''
<syntaxhighlight lang="powershell">
# csv.ps1
# Sample powershell script demonstrating how to HTTP POST a CSV file towards the Contacts App service.
# .\bin\curl must be present, e.g. from https://curl.haxx.se/download.html
# Examples:
# 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 ""
</syntaxhighlight>
== The URL ==
The first part of the URL (''example.com/contacts01'') is the ''Webserver path'' configured for the ''Contacts'' instance in the ''App Platform Manager''. It must be followed by the literal <code>post</code>. 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.

=Troubleshooting=
To collect debugging data, activate the '''''App''''' and '''''App WebSocket''''' trace options at the contacts instance on the App Platform Manager. Now reproduce the issue and save the logfile.

==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<ref>putty: https://putty.org</ref>
<syntaxhighlight lang="bash">
#Login
#===================================================================
login as: admin
Using keyboard-interactive authentication.
Password:

#Elevate to super-user rights, Command 'su'
#===================================================================
admin@app-platform|/mnt/sda2/home/admin> su
Password:

#Command 'psql'. Printing the table 'dbs'. Contains 2 file names.
#===================================================================
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)

#Delete the file "brs%20testimport.csv" via its table-ID 5.
#===================================================================
root@app-platform|/mnt/sda2/home/admin> psql -d "innovaphone.com_contacts" -c "delete from dbs where id=5"
DELETE 1

#Printing the table 'dbs'. Contains 1 file name.
#===================================================================
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>

</syntaxhighlight>

==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<ref>putty: https://putty.org</ref>
<syntaxhighlight lang="bash">
#Login
#===================================================================
login as: admin
Using keyboard-interactive authentication.
Password:

#Elevate to super-user rights, Command 'su'
#===================================================================
admin@app-platform|/mnt/sda2/home/admin> su
Password:

#List number of contacts in main table entries
#===================================================================
root@app-platform|/mnt/sda2/home/admin> psql -d "innovaphone.com_contacts" -c "select count(*) from entries"
count
-------
94
(1 row)

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

#List number of contacts in main table entries
#===================================================================
root@app-platform|/mnt/sda2/home/admin> psql -d "innovaphone.com_contacts" -c "select count(*) from entries"
count
-------
0
(1 row)
</syntaxhighlight>

==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<ref>putty: https://putty.org</ref>
<syntaxhighlight lang="bash">
#Login
#===================================================================
login as: admin
Using keyboard-interactive authentication.
Password:

#Elevate to super-user rights, Command 'su'
#===================================================================
admin@app-platform|/mnt/sda2/home/admin> su
Password:

#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

#Retrieve all database entries, separate them by ; and store in file
#===================================================================
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"

</syntaxhighlight>

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 =
* [[Support:Contacts_on_HomeScreen_can%27t_be_open_after_modification_on_ContactsAPP | Contacts on HomeScreen can't be open after modification on ContactsAPP]]
* [[Support:Contacts_Upload_Fails_From_Within_myApps_Launcher | Contacts Upload Fails From Within myApps Launcher]]
* [[Support:Forward_search_shows_no_result | Forward Search shows "no result"]]
== DECT Phones Cannot Access Personal Directories ==
DECT gateways do not support the mechanism required to query into directories with restricted access rules. Hence, DECT mobile phones cannot search into such directories.

== No automatic ACL update on name changes ==
If a users h323 name is changed, all ACL entries in address books, to which the user has rights, also need to be changed manually, since there is no automatic update between the PBX and the address books.

= Related =
<references/>

Reference14r2:Concept App Service Contacts

2024-07-25T10:44:54Z

Inno-mst: /* List of Attributes */ added uuid

[[Category:Concept|Apps]]
= Applies To =
* App Contacts version 14r2

= Overview =
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, as well as maintaining personal contact books.

Inside Contacts, personal and general entries can be searched (forward lookup) or be used to resolve incoming numbers to their respective name (reverse lookup).

= Features =
*Import: Semicolon (;) separated CSV file
*Database for contact entries: A user interface for retrieval purposes is available.
*API: Search API for other apps
*Edit Functionality: Contact entries are editable.
*Personal Address Book: Every user can maintain one or more personal address books.
*Access Right Management: Owners can maintain access privileges for single users or even groups of users, in order to control visibility of an address book.

= Requirements =
innovaphone PBX and App Platform from on version 13r3 - version 14r2 is recommended.
==Upgrade Considerations==
From 13r3 to 14r2 no special upgrade scenarios need to be considered as the database structure remains the same. On the other hand, if the new com.innovaphone.contacts API will be used (which helps to add contacts from within the phone apps) and a manual update is performed then the Websocket Checkmark should be set on the PBX App Object.

For prior versions please consider the following:

As always, don't forget to backup an existing App Platform in prior. This 13r3 App Contacts does alter the underlying database scheme.
;13r3 App on 13r1 App Platform, 13r1 PBX:Doesn't work. The 13r3 Contacts App does not work on an 13r1 Application Platform/Environment.
;13r3 App on 13r2 App Platform, 13r2 PBX:The 13r3 Contacts App works with the restriction, that the reverse lookup for private address books doesn't work. For full feature set, also upgrade the App Platform and PBX to 13r3.

=Apps=
=== Contacts App (innovaphone-contacts) ===
The regular app
=== Contacts Admin App (innovaphone-contacts-admin) ===
Features a menu (top-right) to manually upload a CSV file
=== Contacts Search API (innovaphone-contacts-searchapi) ===
This hidden app rovides a search API to other apps, e.g. for the Phone App

= Concept =
General contact entries and entries for personal directories are stored within the same database. With the table '''acl''' which is acting as an access control list, restricted views and edit rights for personal directories can be granted.

This way, only the owner of a personal directory (and granted user or groups) can see the content.

==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)
;Formatted number
:A filter is applied to the original number before saving to remove all non-dialable characters. (This means that only <code>0-9,+,*,#</code> remain after that) This formatted 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 [[Reference13r1:Concept_Number_Adjustments_%28Dialing_Location%29 |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.

==List of Attributes==
The list of currently available attributes for a contacts entry follows:
;extAnchor
: unique id identifying 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
;uuid
:A constant universal unique id as string. Internally assigned during entry creation.

==List of Text-Indexable Attributes==
Attributes to be considered for the full-text index
*cn
*sn
*givenname
*company
*displayname
*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. The purpose of the LDAP server functionality is to service innovaphone LDAP clients, such as desk phones.
The LDAP server only supports a proprietary search by means of a meta attribute<ref>Meta attribute: Here an attribute with a special meaning and that is non-physical, not existing within the database</ref>, 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)''

'''Important:'''

Note, that access to restricted/personal phone books requires the proprietary scheme within the LDAP client, mentioned above.

Currently, this is available in the innovaphone IP phone LDAP clients from 13r3 on, but not on 3rd party devices nor our DECT gateways (IP120x). On these clients, only contact data in unrestricted phone books is searched.

===Sample Phone Configuration, innovaphone===
Phone/User-X/Directories/External LDAP Server
;Enable: Active
;Use TLS: Active
;Server: <host adddress of App Platform>
;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''

= Personal Address Book Details =
From version 13r3 on it is possible, to add, editing and delete contacts. It is also possible to create and maintain personal address book(s), as well as share them with other users or whole user groups.

Only user/groups with sufficient rights, will be able to see other address books. An Access control list (acl) is used, to control these rights.

Groups correspond to PBX-groups. The Contacts App gets to know only active PBX-group memberships.

By default, only the user who created an address book, is able to see the content.

==Maintain a Personal Address Book==
;Creating a Personal Address Book
Click on the burger menu in the top right corner inside the Contacts-App, and there on the '''"Directories"'''. Now click on the '''"+"'''-Symbol, choose a suitable name and confirm your name via '''"Save"''' button. A new address book is created.
;Adding a new contact
Click on the '''"+"'''-Symbol in the top right corner inside the Contacts-App and select an address book, where you want the contact to be stored in. Now fill in the contact information (the fields ''"name"'' and ''"last name"'' '''have to be filled''') and save it via '''"Save"'''-button.
;Editing an existing contact
Search for the contact you want to edit via the search box inside the Contacts-App. Click on the '''"Details"'''-field on the right of the contact entry. Now click on the bottom on the '''"Edit"'''-button, click on the entry you want to edit and after your change, save it via '''"Save"'''-button on the bottom.
;Delete an existing contact
Search for the contact you want to edit via the search box inside the Contacts-App. Click on the '''"Details"'''-field on the right of the contact entry. Now click on the bottom on the '''"Edit"'''-button, and on the '''"trashcan"'''-symbol at the top. After confirmation, the entry is deleted.

==Sharing of Address Book==
;Share globally
*Either remove all rules from a personal directory. Such a configuration corresponds to pre-13r3 capabilities. Up to 13r2 there weren't any visibility rules available.
*Or make every PBX user an active member of a group e.g. "everybody" and add a directory rule for that group "everybody".

;Share with single user(s)
Click on the menu in the top right corner inside the Contacts-App, click on '''"directories"''' and select a directory, you want to share.

Now click on the '''"+"'''-symbol and select '''"User"''' as type. In the input field, you can enter and therefore filter for all available users. Select the user, whom you want to give access and select either if the user should have admin-rights or not. Now click on '''Ok''' and submit your change with another click on '''Ok'''.

;Share with a group
Click on the menu in the top right corner inside the Contacts-App, click on '''"directories"''' and select a directory, you want to share.

Now click on the '''"+"'''-symbol and select '''"Group"''' as type. In the input field, you can enter and therefore filter for all available PBX groups. Also select, if the user should have admin-rights or not. Now click on '''Ok''' and submit your change with another click on '''Ok'''-button.

;Revoke of granted rights
You can also revoke previous granted rights by just clicking on the user/group at the access control list, and click on the '''trashcan''' symbol. Now submit your change with another click on '''Ok'''-button.

==Upload a new Directory==
The Contacts Admin App allows uploading a CSV file as known from the 13r2 version ('''Hamburger/Import'''). In the course of an upload operation, a new directory will be created. The newly assigned directory name will be the name of the CSV file.
After uploading, the visibility setting of the new directory should be administrated as stated before under [[#Sharing_of_Address_Book|Sharing of Address Book]]

==Terminology==
;ACL: Access control list. Refers the database table ''acl'' and rows/entries therein.
;Directory: Refers the database table ''dbs'' and rows/entries therein. All contact entries referencing a ''dbs''-row make up the content of a directory.
;Address Book: Synonymous with ''Directory''
;Contacts Admin: A user utilizing the Contacts Admin App (via App URL, ending with ../innovaphone-contacts-admin)
;Directory Admin: A user entitled the admin right for a directory. Either by user-wise or by group-wise ACL entry.
;Directory User/Viewer: A user entitled the viewing right for a directory. Either by user-wise or by group-wise ACL entry.

==Database Changes==
Three tables realize the functionality for personal directories.
*Table '''dbs'''. Each row represents a directory. Two new columns ''displayname, sip'' where added.
**'''displayname''' Name display.
**'''sip''' Creator's sip name, if available.
*Table '''acl'''.New table acting as access control list. Each row references a directory as listed by table ''dbs'' and is going to grant view- and admin-right to a specific user or group.
**'''dbsid''' Reference into table dbs.
**'''name''' The name of a user or a group.
**'''acltype''' A numeric value: user(0), group(1)
**'''admin''' Granting edit right: admin(true), non-admin(false)
*Table '''entries'''. Each row within this pre-exisisting table represents a contact entry. The column ''dbsid'' informs about whether an entry belongs to a specific directory.

<pre>
#Excerpt for an additional directory ''Persönliches Verzeichnis: mst'' with one contact entry.

root@app-platform|/mnt/sda2/home/admin> psql -d "innovaphone.com_contacts" -c "select * from dbs"
id | uri | displayname | sip
----+------------------------------------------------------+--------------------------------+-----
7 | file:///4eaae395-9971-40fb-9a05-dfae1d023f12?sip=mst | Persönliches Verzeichnis: mst | mst # Specification for directory ('Persönliches Verzeichnis: mst')

root@app-platform|/mnt/sda2/home/admin> psql -d "innovaphone.com_contacts" -c "select * from acl"
id | dbsid | name | acltype | admin
----+-------+------+---------+-------
5 | 7 | mst | 0 | t #user 'mst' can view and edit directory with dbsid=7 ('Persönliches Verzeichnis: mst')

root@app-platform|/mnt/sda2/home/admin> psql -d "innovaphone.com_contacts" -c "select sn,givenname,company,id,dbsid from entries where dbsid=7"
sn | givenname | company | id | dbsid
----------+-----------+--------------+-------+-------
Duck | Dagobert | Duck Corp. | 51394 | 7 # main table entries contains 1 entry belonging to ('Persönliches Verzeichnis: mst')

</pre>

==Reverse Number Lookup for Personal Directories==
Queries into directories are access-checked by looking-up and enforcing ACL-rules. The information on whose name is being queried and which group memberships are taking effect is needed for this process.

Websocket connections to the Contacts App service carry those infos within the SDK method ''AppWebsocketConnectComplete()''.
LDAP connections pass this information within a proprietary LDAP control together with an LDAP searchRequest message.

The PBX's centralized Reverse Lookup service (see ''PBX/Config/General/Reverse Lookup URL'') does support this mechanism. That is, for every LDAP searchRequest the affected user's name and active group memberships are going to be sent towards the Contacts App's LDAP server.

See also [[{{NAMESPACE}}:Concept_Reverse_Lookup|concept article on reverse lookup]].

=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<ref>For a windows distribution: e.g.: https://curl.haxx.se/download.html </ref><ref>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</ref>
The required user and password content corresponds to the configuration underneath '''PBX Manager/AP Contacts/Configuration/User(HTTP Post)''' and '''Password(HTTP Post)'''
<syntaxhighlight lang="powershell">
# csv.ps1
# Sample powershell script demonstrating how to HTTP POST a CSV file towards the Contacts App service.
# .\bin\curl must be present, e.g. from https://curl.haxx.se/download.html
# Examples:
# 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 ""
</syntaxhighlight>
== The URL ==
The first part of the URL (''example.com/contacts01'') is the ''Webserver path'' configured for the ''Contacts'' instance in the ''App Platform Manager''. It must be followed by the literal <code>post</code>. 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.

=Troubleshooting=
To collect debugging data, activate the '''''App''''' and '''''App WebSocket''''' trace options at the contacts instance on the App Platform Manager. Now reproduce the issue and save the logfile.

==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<ref>putty: https://putty.org</ref>
<syntaxhighlight lang="bash">
#Login
#===================================================================
login as: admin
Using keyboard-interactive authentication.
Password:

#Elevate to super-user rights, Command 'su'
#===================================================================
admin@app-platform|/mnt/sda2/home/admin> su
Password:

#Command 'psql'. Printing the table 'dbs'. Contains 2 file names.
#===================================================================
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)

#Delete the file "brs%20testimport.csv" via its table-ID 5.
#===================================================================
root@app-platform|/mnt/sda2/home/admin> psql -d "innovaphone.com_contacts" -c "delete from dbs where id=5"
DELETE 1

#Printing the table 'dbs'. Contains 1 file name.
#===================================================================
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>

</syntaxhighlight>

==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<ref>putty: https://putty.org</ref>
<syntaxhighlight lang="bash">
#Login
#===================================================================
login as: admin
Using keyboard-interactive authentication.
Password:

#Elevate to super-user rights, Command 'su'
#===================================================================
admin@app-platform|/mnt/sda2/home/admin> su
Password:

#List number of contacts in main table entries
#===================================================================
root@app-platform|/mnt/sda2/home/admin> psql -d "innovaphone.com_contacts" -c "select count(*) from entries"
count
-------
94
(1 row)

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

#List number of contacts in main table entries
#===================================================================
root@app-platform|/mnt/sda2/home/admin> psql -d "innovaphone.com_contacts" -c "select count(*) from entries"
count
-------
0
(1 row)
</syntaxhighlight>

==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<ref>putty: https://putty.org</ref>
<syntaxhighlight lang="bash">
#Login
#===================================================================
login as: admin
Using keyboard-interactive authentication.
Password:

#Elevate to super-user rights, Command 'su'
#===================================================================
admin@app-platform|/mnt/sda2/home/admin> su
Password:

#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

#Retrieve all database entries, separate them by ; and store in file
#===================================================================
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"

</syntaxhighlight>

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 =
* [[Support:Contacts_on_HomeScreen_can%27t_be_open_after_modification_on_ContactsAPP | Contacts on HomeScreen can't be open after modification on ContactsAPP]]
* [[Support:Contacts_Upload_Fails_From_Within_myApps_Launcher | Contacts Upload Fails From Within myApps Launcher]]
* [[Support:Forward_search_shows_no_result | Forward Search shows "no result"]]
== DECT Phones Cannot Access Personal Directories ==
DECT gateways do not support the mechanism required to query into directories with restricted access rules. Hence, DECT mobile phones cannot search into such directories.

== No automatic ACL update on name changes ==
If a users h323 name is changed, all ACL entries in address books, to which the user has rights, also need to be changed manually, since there is no automatic update between the PBX and the address books.

= Related =
<references/>

Reference13r3:Concept App Service Contacts

2024-02-20T15:54:47Z

Inno-mst: /* List of Text-Indexable Attributes */ Removed 'Info'

[[Category:Concept|Apps]]
= Applies To =
* App Contacts version 13r3

= Overview =
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, as well as maintaining personal contact books.

Inside Contacts, personal and general entries can be searched (forward lookup) or be used to resolve incoming numbers to their respective name (reverse lookup).

= Features =
*Import: Semicolon (;) separated CSV file
*Database for contact entries: A user interface for retrieval purposes is available.
*API: Search API for other apps
*Edit Functionality: Contact entries are editable.
*Personal Address Book: Every user can maintain one or more personal address books.
*Access Right Management: Owners can maintain access privileges for single users or even groups of users, in order to control visibility of an address book.

= Requirements =
innovaphone PBX and App Platform from on version 13r3.
==Upgrade Considerations==
As always, don't forget to backup an existing App Platform in prior. This 13r3 App Contacts does alter the underlying database scheme.
;13r3 App on 13r1 App Platform, 13r1 PBX:Doesn't work. This 13r3 Contacts App does not work on an 13r1 Application Platform/Environment.
;13r3 App on 13r2 App Platform, 13r2 PBX:The 13r3 Contacts App works with the restriction, that the reverse lookup for private address books doesn't work. For full feature set, also upgrade the App Platform and PBX to 13r3.

=Apps=
=== Contacts App (innovaphone-contacts) ===
The regular app
=== Contacts Admin App (innovaphone-contacts-admin) ===
Features a menu (top-right) to manually upload a CSV file
=== Contacts Search API (innovaphone-contacts-searchapi) ===
This hidden app rovides a search API to other apps, e.g. for the Phone App

= Concept =
General contact entries and entries for personal directories are stored within the same database. With the table '''acl''' which is acting as an access control list, restricted views and edit rights for personal directories can be granted.

This way, only the owner of a personal directory (and granted user or groups) can see the content.

==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)
;Formatted number
:A filter is applied to the original number before saving to remove all non-dialable characters. (This means that only <code>0-9,+,*,#</code> remain after that) This formatted 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 [[Reference13r1:Concept_Number_Adjustments_%28Dialing_Location%29 |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.

==List of Attributes==
The list of currently available attributes for a contacts entry follows:
;extAnchor
: unique id identifying 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
*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. The purpose of the LDAP server functionality is to service innovaphone LDAP clients, such as desk phones.
The LDAP server only supports a proprietary search by means of a meta attribute<ref>Meta attribute: Here an attribute with a special meaning and that is non-physical, not existing within the database</ref>, 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)''

'''Important:'''

Note, that access to restricted/personal phone books requires the proprietary scheme within the LDAP client, mentioned above.

Currently, this is available in the innovaphone IP phone LDAP clients from 13r3 on, but not on 3rd party devices nor our DECT gateways (IP120x). On these clients, only contact data in unrestricted phone books is searched.

===Sample Phone Configuration, innovaphone===
Phone/User-X/Directories/External LDAP Server
;Enable: Active
;Use TLS: Active
;Server: <host adddress of App Platform>
;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''

= Personal Address Book Details =
With version 13r3 it is now possible, to add, editing and delete contacts. It is also possible to create and maintain personal address book(s), as well as share them with other users or whole user groups.

Only user/groups with sufficient rights, will be able to see other address books. An Access control list (acl) is used, to control these rights.

Groups correspond to PBX-groups. The Contacts App gets to know only active PBX-group memberships.

By default, only the user who created an address book, is able to see the content.

==Maintain a Personal Address Book==
;Creating a Personal Address Book
Click on the burger menu in the top right corner inside the Contacts-App, and there on the '''"Directories"'''. Now click on the '''"+"'''-Symbol, choose a suitable name and confirm your name via '''"Save"''' button. A new address book is created.
;Adding a new contact
Click on the '''"+"'''-Symbol in the top right corner inside the Contacts-App and select an address book, where you want the contact to be stored in. Now fill in the contact information (the fields ''"name"'' and ''"last name"'' '''have to be filled''') and save it via '''"Save"'''-button.
;Editing an existing contact
Search for the contact you want to edit via the search box inside the Contacts-App. Click on the '''"Details"'''-field on the right of the contact entry. Now click on the bottom on the '''"Edit"'''-button, click on the entry you want to edit and after your change, save it via '''"Save"'''-button on the bottom.
;Delete an existing contact
Search for the contact you want to edit via the search box inside the Contacts-App. Click on the '''"Details"'''-field on the right of the contact entry. Now click on the bottom on the '''"Edit"'''-button, and on the '''"trashcan"'''-symbol at the top. After confirmation, the entry is deleted.

==Sharing of Address Book==
;Share globally
*Either remove all rules from a personal directory. Such a configuration corresponds to pre-13r3 capabilities. Up to 13r2 there weren't any visibility rules available.
*Or make every PBX user an active member of a group e.g. "everybody" and add a directory rule for that group "everybody".

;Share with single user(s)
Click on the menu in the top right corner inside the Contacts-App, click on '''"directories"''' and select a directory, you want to share.

Now click on the '''"+"'''-symbol and select '''"User"''' as type. In the input field, you can enter and therefore filter for all available users. Select the user, whom you want to give access and select either if the user should have admin-rights or not. Now click on '''Ok''' and submit your change with another click on '''Ok'''.

;Share with a group
Click on the menu in the top right corner inside the Contacts-App, click on '''"directories"''' and select a directory, you want to share.

Now click on the '''"+"'''-symbol and select '''"Group"''' as type. In the input field, you can enter and therefore filter for all available PBX groups. Also select, if the user should have admin-rights or not. Now click on '''Ok''' and submit your change with another click on '''Ok'''-button.

;Revoke of granted rights
You can also revoke previous granted rights by just clicking on the user/group at the access control list, and click on the '''trashcan''' symbol. Now submit your change with another click on '''Ok'''-button.

==Upload a new Directory==
The Contacts Admin App allows uploading a CSV file as known from the 13r2 version ('''Hamburger/Import'''). In the course of an upload operation, a new directory will be created. The newly assigned directory name will be the name of the CSV file.
After uploading, the visibility setting of the new directory should be administrated as stated before under [[#Sharing_of_Address_Book|Sharing of Address Book]]

==Terminology==
;ACL: Access control list. Refers the database table ''acl'' and rows/entries therein.
;Directory: Refers the database table ''dbs'' and rows/entries therein. All contact entries referencing a ''dbs''-row make up the content of a directory.
;Address Book: Synonymous with ''Directory''
;Contacts Admin: A user utilizing the Contacts Admin App (via App URL, ending with ../innovaphone-contacts-admin)
;Directory Admin: A user entitled the admin right for a directory. Either by user-wise or by group-wise ACL entry.
;Directory User/Viewer: A user entitled the viewing right for a directory. Either by user-wise or by group-wise ACL entry.

==Database Changes==
Three tables realize the functionality for personal directories.
*Table '''dbs'''. Each row represents a directory. Two new columns ''displayname, sip'' where added.
**'''displayname''' Name display.
**'''sip''' Creator's sip name, if available.
*Table '''acl'''.New table acting as access control list. Each row references a directory as listed by table ''dbs'' and is going to grant view- and admin-right to a specific user or group.
**'''dbsid''' Reference into table dbs.
**'''name''' The name of a user or a group.
**'''acltype''' A numeric value: user(0), group(1)
**'''admin''' Granting edit right: admin(true), non-admin(false)
*Table '''entries'''. Each row within this pre-exisisting table represents a contact entry. The column ''dbsid'' informs about whether an entry belongs to a specific directory.

<pre>
#Excerpt for an additional directory ''Persönliches Verzeichnis: mst'' with one contact entry.

root@app-platform|/mnt/sda2/home/admin> psql -d "innovaphone.com_contacts" -c "select * from dbs"
id | uri | displayname | sip
----+------------------------------------------------------+--------------------------------+-----
7 | file:///4eaae395-9971-40fb-9a05-dfae1d023f12?sip=mst | Persönliches Verzeichnis: mst | mst # Specification for directory ('Persönliches Verzeichnis: mst')

root@app-platform|/mnt/sda2/home/admin> psql -d "innovaphone.com_contacts" -c "select * from acl"
id | dbsid | name | acltype | admin
----+-------+------+---------+-------
5 | 7 | mst | 0 | t #user 'mst' can view and edit directory with dbsid=7 ('Persönliches Verzeichnis: mst')

root@app-platform|/mnt/sda2/home/admin> psql -d "innovaphone.com_contacts" -c "select sn,givenname,company,id,dbsid from entries where dbsid=7"
sn | givenname | company | id | dbsid
----------+-----------+--------------+-------+-------
Duck | Dagobert | Duck Corp. | 51394 | 7 # main table entries contains 1 entry belonging to ('Persönliches Verzeichnis: mst')

</pre>

==Reverse Number Lookup for Personal Directories==
Queries into directories are access-checked by looking-up and enforcing ACL-rules. The information on whose name is being queried and which group memberships are taking effect is needed for this process.

Websocket connections to the Contacts App service carry those infos within the SDK method ''AppWebsocketConnectComplete()''.
LDAP connections pass this information within a proprietary LDAP control together with an LDAP searchRequest message.

The PBX's centralized Reverse Lookup service (see ''PBX/Config/General/Reverse Lookup URL'') does support this mechanism. That is, for every LDAP searchRequest the affected user's name and active group memberships are going to be sent towards the Contacts App's LDAP server.

See also [[{{NAMESPACE}}:Concept_Reverse_Lookup|concept article on reverse lookup]].

=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<ref>For a windows distribution: e.g.: https://curl.haxx.se/download.html </ref><ref>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</ref>
The required user and password content corresponds to the configuration underneath '''PBX Manager/AP Contacts/Configuration/User(HTTP Post)''' and '''Password(HTTP Post)'''
<syntaxhighlight lang="powershell">
# csv.ps1
# Sample powershell script demonstrating how to HTTP POST a CSV file towards the Contacts App service.
# .\bin\curl must be present, e.g. from https://curl.haxx.se/download.html
# Examples:
# 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 ""
</syntaxhighlight>
== The URL ==
The first part of the URL (''example.com/contacts01'') is the ''Webserver path'' configured for the ''Contacts'' instance in the ''App Platform Manager''. It must be followed by the literal <code>post</code>. 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.

=Troubleshooting=
To collect debugging data, activate the '''''App''''' and App '''''WebSocket''''' trace options at the contacts instance on the App Platform Manager. Now reproduce the issue and save the logfile.

==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<ref>putty: https://putty.org</ref>
<syntaxhighlight lang="bash">
#Login
#===================================================================
login as: admin
Using keyboard-interactive authentication.
Password:

#Elevate to super-user rights, Command 'su'
#===================================================================
admin@app-platform|/mnt/sda2/home/admin> su
Password:

#Command 'psql'. Printing the table 'dbs'. Contains 2 file names.
#===================================================================
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)

#Delete the file "brs%20testimport.csv" via its table-ID 5.
#===================================================================
root@app-platform|/mnt/sda2/home/admin> psql -d "innovaphone.com_contacts" -c "delete from dbs where id=5"
DELETE 1

#Printing the table 'dbs'. Contains 1 file name.
#===================================================================
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>

</syntaxhighlight>

==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<ref>putty: https://putty.org</ref>
<syntaxhighlight lang="bash">
#Login
#===================================================================
login as: admin
Using keyboard-interactive authentication.
Password:

#Elevate to super-user rights, Command 'su'
#===================================================================
admin@app-platform|/mnt/sda2/home/admin> su
Password:

#List number of contacts in main table entries
#===================================================================
root@app-platform|/mnt/sda2/home/admin> psql -d "innovaphone.com_contacts" -c "select count(*) from entries"
count
-------
94
(1 row)

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

#List number of contacts in main table entries
#===================================================================
root@app-platform|/mnt/sda2/home/admin> psql -d "innovaphone.com_contacts" -c "select count(*) from entries"
count
-------
0
(1 row)
</syntaxhighlight>

==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<ref>putty: https://putty.org</ref>
<syntaxhighlight lang="bash">
#Login
#===================================================================
login as: admin
Using keyboard-interactive authentication.
Password:

#Elevate to super-user rights, Command 'su'
#===================================================================
admin@app-platform|/mnt/sda2/home/admin> su
Password:

#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

#Retrieve all database entries, separate them by ; and store in file
#===================================================================
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"

</syntaxhighlight>

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 =
* [[Support:Contacts_on_HomeScreen_can%27t_be_open_after_modification_on_ContactsAPP | Contacts on HomeScreen can't be open after modification on ContactsAPP]]
* [[Support:Contacts_Upload_Fails_From_Within_myApps_Launcher | Contacts Upload Fails From Within myApps Launcher]]
* [[Support:Forward_search_shows_no_result | Forward Search shows "no result"]]
== DECT Phones Cannot Access Personal Directories ==
DECT gateways do not support the mechanism required to query into directories with restricted access rules. Hence, DECT mobile phones cannot search into such directories.

== No automatic ACL update on name changes ==
If a users h323 name is changed, all ACL entries in address books, to which the user has rights, also need to be changed manually, since there is no automatic update between the PBX and the address books.

= Related =
<references/>

Reference14r1:Concept Innovaphone Virtual Appliance (IPVA)

2023-12-01T11:47:59Z

Inno-mst: Added Upgrade to Version 14

[[Category:Concept12r1|{{PAGENAME}}]]
{{FIXME|reason=This product is in the beta phase and is not yet finished}}

==Applies To==
This information applies to:
*V14r1
*innovaphone Virtual Appliance
*Intel/AMD CPUs
* Virtualization platforms
**VMware
*** Workstation
*** Player
*** vSphere 4.x-6.x
*** ESXi 6.0
**Microsoft Hyper-V ([[{{NAMESPACE}}:Concept IPVA On Hyper-V]])
*** Windows 8.1
*** Windows 10
*** Windows Server 2012 R2
*** Windows Server 2016 CTP4
**Linux based Hypervisors with [https://en.wikipedia.org/wiki/Kernel-based_Virtual_Machine KVM] and [https://en.wikipedia.org/wiki/QEMU QEMU] support
*** Proxmox VE 8.0 / 8.1

''Disclaimer: Manufacturers/versions of VM platforms other than those specified here have not been tested, so use at your own risk.''

==More Information==
The innovaphone Virtual Appliance (IPVA) is a virtual machine to be run on a virtualization platform.

The IPVA is a software-only solution. It appears and behaves like an innovaphone "hard-box" without physical resources such as hardware DSP or ISDN interface.

==Package Overview==
We supply an OVF ('''O'''pen '''V'''irtualization '''F'''ormat) import or - depending on the virtualization platform - a suitable variant.
OVF is an open standard that contains several files in one package. The .ovf file is therefore an archive that contains all the necessary files.

=== Sample VMware ===
;ipva-ovf.zip:
The compressed archive ''ipva-ovf.zip'' contains the file ipva.ova. A deployment of ipva.ova will result in a set of 5 files - the file names may differ from the following list:
*ipva.vmx: The virtual machine configuration file
*hd-boot.vmdk: The virtual boot disk on IDE 0:0
*hd-cf.vmdk: The disk for emulation of a Compact Flash card on IDE 0:1
*hd-flash.vmdk: The disk for emulation of flash memory on IDE 1:0
*hd-dump.vmdk: The disk serving as a store for a crash dump on IDE 1:1

;ipva.bin:
The file ''ipva.bin'' is the firmware file, which is only needed for update purposes.

== Virtualization platforms ==

===VMware Player / VMware Workstation===
==== Import new Machine ====
*Copy the file ipva.ova to e.g. your desktop and Double-click on ipva.ova.
*Edit the file ipva.vmx according to [[#What_Can_I_Do_In_Case_Of_Boot-Problem:_perf-counter_not_enabled.21 | What Can I Do In Case Of Boot-Problem: ''perf-counter not enabled!'']]

===VMware vSphere===
==== Import new Machine ====
*Import ipva.ova by means of '''File/Deploy OVF-Template...''' (de: '''Datei/OFV-Vorlage bereitstellen...''') and follow instructions.
*Edit the file ipva.vmx according to [[#What_Can_I_Do_In_Case_Of_Boot-Problem:_perf-counter_not_enabled.21 | What Can I Do In Case Of Boot-Problem: ''perf-counter not enabled!'']]

===Microsoft Hyper-V===
==== Import new Machine ====
* Use the UI Wizard to Import a new machine
* Browse to the directory where the downloaded package was extracted to. Browse to the subdirectory Virtual Machines and click Ok
* Select ''Copy the Virtual Machine'' as ''Import Type''

===Proxmox VE===
==== Import new Machine ====
Proxmox does not offer a UI option to import existing machines via ovf. The machine must be imported via shell.

* Unzip ipva-qemu.zip and copy ipva-qemu.ova to a suitable disk location on Proxmox
* Navigate to your desired folder, extract and import the VM (''think about the vm-id concept in Proxmox! - In this example, we use ID 503)
** <code>cd /mnt/pve/my-storage/images/ipva</code>
** <code>tar -xvf ipva-qemu.ova</code>
** <code>qm importovf 503 ipva-qemu.ovf local-lvm</code>
* Before you start up the VM in the UI you have to configure the following:
** Hardware -> Add -> Network Device
*** add a new network adapter with model ''VirtIO''
** Hardware -> Processors
*** adjust "Extra Cpu Flags" -> "aes" if required

==Configuration==

===Network Configuration===
Manufacturer-configured as DHCP client only. I.e. a DHCP server must be available. Afterwards the network configuration may be administrated as used to within the web ui of other innovaphone boxes. If there's in no case a DHCP server available for the 1st-time configuration, read through [[#What_Is_The_Console_Good_For?|What Is The Console Good For?]].

====MAC/serial number====
Take care that you use a MAC address which is supported by my.innovaphone, see [[Reference:My_Innovaphone#IPVA_MAC_exists]].

==Upgrade to Version 14==
Upgrading from a version prior to 14 to version 14r1.
===VMWare===
After deploying the new firmware modify the guest configuration file (stemming from ipva.vmx) as such:
Modify e.g. <code type="text">ethernet0.virtualDev = "vlance"</code> to become <code type="text">ethernet0.virtualDev = "vmxnet3"</code>

==Troubleshooting==
Support procedures are commonly identical to the ones known from innovaphones' physical appliances. Except for:
*'''Post-Mortem Logs''' A post-mortem log must be retrieved by clicking on ''Maintenance/Diagnostics/Tracing/'''trace(crash-dump)''''' (alternatively: http://a.b.c.d/crash_dump.txt).

Some known issues are listed further below under [[#FAQ | FAQ]].

==Known Issues==

=== Restored IPVA may not run ===
We have seen issues where an IPVA which had been backed up using one of the available backup tools for VMWare do not start up properly when they have been restored.

We strongly suggest to not rely on VMWare backup mechanism but instead to use the standard innovaphone backup scheme (that is, save the configuration on a regular basis).

==== How to run a restored backup that fails to start ====
Here is the procedure to run an IPVA from an IPVA if the restored virtual machine does not boot up properly:

* restore the backed up V10 IPVA
* create a new, empty V11r1 IPVA (you will need this merely to copy the boot disk from)
*replace the boot disk of the failing V10 IPVA by the boot disk of the fresh V11r1 IPVA (see [[#How_To_Replace_The_Boot_Disk_On_vSphere.3F | How To Replace The Boot Disk On vSphere]] for details)
* start the restored and fixed V10 IPVA (it should run fine now)
* downgrade this V10 IPVA to desired V10 firmware
* remove the fresh V11r1 IPVA

Some Customer who are running Fw v12r1 (up to sr6) with ESXi 6.0 and VEEAM 9 reported that after a backup with VEEAM 9, the restored IPVA was not starting.
At this point, there is no possibility to solve this problem. The only workaround in that case is to delete the machine, reinstall a new one, and restore a configuration saved before.

If you did not run into the problem yet, for prevention, we recommend to replace the Boot disk of your working IPVA.vmx with one of the IPVA.ova. Please follow the steps below (be aware that this will upgrade the firmware on the IPVA to 12r2, due to the fact that actually, IPVA.ova is only available from version 12r2):

1. Remove the Boot disk of the virtual machine (vmx)(is normaly the first one). 
* Power off the VM
* Select the Virtual Machine > Settings.
* On the Hardware tab, select the virtual hard disk and click ''Remove''.
* Click ''OK'' to save your changes.

2. Add the Boot disk of the ova virtual machine to the vmx one.
* Identify the size of the boot disk of the ova virtual machine (will be needed on the step when navigating to boot disk)
* On the powered off VM, Select the Virtual Machine > Settings.
* On the Hardware tab, select the virtual hard disk and click ''Add''.
* Select Use “an existing virtual disk” then click ''Next''.
* Navigate to the boot disk of the ova Virtual machine then click ''next''.
* Click ''Finish''.
Now the vmx virtual machine should have the Fw version 12r2.

The .ova version will be available also in V12r1 sr7

=== IPVA does not run on Citrix Cloud Platform ===
Reportedly, the Citrix cloud platform - although based on VMware - cannot run the IPVA. Amongst other issues, the platform does not allow 4 virtual disks, which are required for the IPVA.

=== IPVA does not run on VCloud Air ===
VCloud Air apparently does not support the timekeeping mechanism required by the IPVA.

[[User:Ckl|ckl]] 15:50, 30 November 2016 (CET) We have seen the IPVA v12r2 running on vCloud Air. Use the ova import.

=== IPVA on ESX 6.5 ===
We have reports that the IPVA does not run properly on ESX 6.5. The IPVA boots up properly but the clock does not run. Running the .ova based variation available in v12r2 fixed the issue or edit the file ipva.vmx according to [[#What_Can_I_Do_In_Case_Of_Boot-Problem:_perf-counter_not_enabled.21 | What Can I Do In Case Of Boot-Problem: ''perf-counter not enabled!'']]

=== Administration: Avoid 'reboot' Command. Use 'reset' Command ===
Alwas use the 'reset' command to restart an IPVA.
The 'reboot' command makes sense only on physical applicances, where its purpose is to deploy a new bootcode by means of a forced watchdog trap. The resulting post-reboot state will be as if an unsolicited trap/crash had occurred.

=== No Fault Tolerance Support from VMWare vSphere 6.5 ===
We have reports that VMWare vSphere 6.5 Fault Tolerance (FT) no longer works. For further information regarding this feature, please refer to the respective note in [[Howto:Implement_PBX_with_zero_downtime_using_IPVA_and_VMWare_Fault_Tolerance | Implement PBX with zero downtime using IPVA and VMWare Fault_Tolerance]].

=== Voice Quality Issues ===
When dealing with media streams (e.g. for announcements), the IPVA needs to fulfil real-time processing requirements, for example to process RTP packets in a timely fashion. To do so, the IPVA relies on the capabilities of the virtualization platform it runs on.

It is therefore important to configure the platform so that it supports real-time applications best. If you experience voice quality or latency issues, consider
* to make sure that all of the IPVAs memory is ''reserved'' to the IPVA (''Latency Sensitivity'' set to ''High'')
* to guarantee exclusive PCPU access
This helps to reduce CPU halt/wake-up states.

===Additional vCPUs may cause problems===
The Multi-Core functionality of version 13r2 is a beta functionality. Additional virtual CPUs(vCPUs) should not be utilized in production environments.

==FAQ==
===Can The Emulated CompactFlash Be Increased In Size?===
Yes, from within the ''Edit Virtual Machine'' dialog. Doing so just increases the size of the virtual harddisk. The emulated CompactFlash must be formatted afterwards and accordingly to benefit from the increased size. That step can be administrated from ''Administration/Compact Flash/Format''. Note: A recommendation for an upper size limit is not given.

'''vSphere / vSphere Client'''

1. At first backup all of your files from CF card 
2. Shutdown the corresponding IPVA 
3. Choose "Properties" of the IPVA 
4. Delete "Harddrive 2" (Hardrive file xxx/xxx_1.vmdk) 

hd-boot.vmdk > xxx.vmdk
hd-cf.vmdk > xxx_1.vmdk
hd-flash.vmdk > xxx_2.vmdk
hd-dump.vmdk > xxx_3.vmdk

5. Create new harddrive 
6. Configure the required size 
7. As "Node of virtual device" select "IDE(0:1)" 
8. Start the IPVA. 
9. "Format" the CF Card and "mount" it (General/Compact-Flash/General)

===What Is The Size Of the emulated Flash Storage on the IPVA?===
The virtual flash storage used to store configuration file of the IPVA and LDAP directory of the PBX is defined with 64 MB and can not be changed. This is two times more than on IP6010. The VMDK-File hd-flash.vmdk is allocated with 100 MB, because VMWare can not handle smaller virtual disks.

===What Is The Size Of the Flash Directory on the IPVA?===
As noted above, the virtual flash memory on the IPVA is fixed to a size of 64MB. Most of the flash is used by the ''flash directory'' (FLASHDIR0) which amongst other things provides storage for PBX objects.

The size of the flash directory depends on the available RAM. The maximum of 900 segments á 64KB, i.e. ~56MB, is available if 192MB or more RAM is available. If less RAM is available, the size of the flash directory is decreased accordingly. For this reason, it is unsafe to reduce RAM size in a given IPVA, as the flash directory size may be decreased so that objects from the flash directory get lost.

The easiest method to see how much flash directory space is available is to investigate the boot trace. For the standard configuration of 64MB the respective trace output is going to look as follows and informs about a size of 14MB:

0:0000:081:4 - start flashdir FLASHDIR0
0:0000:081:4 - fdir: segments=901->224(14.0MB)

===How Much RAM Is Required Per IPVA Instance?===
Since 12r2sr27/13r1sr5 the downloadable virtual appliance comes preconfigured with 256MB RAM. This amount is seen as a good trade-off for the majority of all installations.
The RAM-size can be administrated by VMware-means.

===What Is The Maximum Amount Of RAM?===
The maximum meaningful RAM setting is 3GB. Memory space beyond that limit will be left unused. Assigning more than 3GB to an IPVA instance doesn't provide any benefit.

===Why Does ''General/Info/DRAM'' Show Less Than the Configured Memory?===
Not all of the configured memory is available to the IPVA. E.g. a bit of memory is occupied by the VMM<ref>Virtual Machine Monitor: A component belonging to the virtualization platform</ref>. The indicator ''General/Info/DRAM'' displays the memory available to the IPVA and is truncated down to a whole number. A boot-trace reveals a bit more about IPVA-available memory as shown in the following excerpt:
<pre>
...
0:0000:030:4 - Intel(R) Core(TM)2 Duo CPU E8400 @ 3.00GHz
0:0000:030:4 - mem(64946176)=61.93MB ...
</pre>

===How Many IPVA Instances Are Possible Per Host?===
There's no worst-case estimate available. For a best-case calculation,
*see [http://www.vmware.com/pdf/vsphere4/r41/vsp_41_config_max.pdf Configuration Maximums VMware vSphere 4.1]
*see [[#How_Much_RAM_Is_Required_Per_IPVA_Instance.3F | How Much RAM Is Required Per IPVA Instance?]]
Additional preformance reflections
*see [[HOWTO:A_rough_estimate_of_IPVA_Performance | A rough estimate of IPVA Performance]]

===How do I perform a factory reset?===

replace the 3rd disk, served on IDE 1:0, named hd-flash.vmdk with an empty disk:

[[Image:VM_Settings.png]]

1)download the IPVA and watch out for the file hd-flash.vmdk

2)Power-off the IPVA instance

3)Replace hd-flash.vmdk with the one downloaded in step 1). If on vsphere it may have been assigned a different name. Ensure it’s the one on IDE 1:0.

4)Power-on the IPVA instance

===What About VMware Tools?===
VMware Tools are not supported.

===What Is The Console Good For?===
The console is a remains of the early development phase. It resembles the IP3000's serial console. It doesn't offer any convenience like command history or backspace funtionality. Nevertheless may the console be of help in exceptional situations where e.g. the required DHCP server isn't available for 1st-time configuration or in situations where the ip configuration was misconfigured. Thereby any command from a device's config is acceptable.

For instance to configure the static IP address 1.2.3.4/24 on ETH0:
*Click into the console
*Press ENTER
*Enter credentials
*Enter
<pre>
config change IP0 ETH0 /addr 192.168.0.10 /mask 255.255.255.0
config change IP0 RT0 /gateway 192.168.0.1
config change DHCP0 /mode off
config write
reset
</pre>
Since no backspace is offered it may become a daring task to enter a single line without typos. In case of a typo hit ENTER and input the same line again.
The keyboard layout is the US layout.
[[Image:Ip-via-console.png|center|thumb|200px|Console-edit of IP address]]

Display the IP configuration for ETH0:
<pre>
config show IP0 ETH0
</pre>

Display the DHCP configuration for ETH0:
<pre>
config show DHCP0
</pre>

Additional the DNS-server(s) and the default gateway can be configured:
<pre>
config change IP0 ETH0 /addr 1.2.3.4 /mask 255.255.255.0 /dns 8.8.8.8 /dns2 8.8.4.4
config change IP0 RT0 /gateway 1.2.3.254
config change DHCP0 /mode off
config write
reset
</pre>

Also some simple diagnostics (ping and traceroute) are possible via the console (output is given in the console):
<pre>
mod cmd PING0 tracert 8.8.8.8
mod cmd PING0 ping 8.8.8.8
</pre>

Resetting the entire FLASH space - '''Note, all configuration will get lost'''. this is similar method to the manufacturer reset method from above [[#How_do_I_perform_a_factory_reset.3F|How do I perform a factory reset?]]
<pre>
mod cmd FLASHMAN0 reset all
reset
</pre>

===What Can I Do In Case Of A Checksum Boot Error?===
This paragraph applies, if you experience the following start-up problem.

'''Symptom'''
*the IPVA doesn't start properly
*the console displays
<pre>
checksum wrong! Loading failed for image=IPVA BIN
</pre>
[[Image:ipva-crc-wrong.jpg|center|thumb|200px|Console displays CRC boot error]]

'''Solution'''
*Power-off the IPVA
*Replace the boot harddisk by a fresh one. The boot harddisk is the 1st hd(originally named ''hd-boot.vmdk'').

'''Remarks'''

This problem may occur on a system crash while a firmware update is taking place.

===What Can I Do In Case Of Boot-Problem: ''NIC unavailable!''===
This paragraph applies, if you experience the following start-up problem.

'''Symptom'''
*the IPVA doesn't start properly
*the console displays
<pre>
NIC unavailable!
</pre>
[[Image:ipva-nic-unavailable.jpg|center|thumb|200px|Console displays ''NIC unavailable!'']]

'''Solution'''
*Power-off the IPVA
*Administrate by VMware means: Ensure the correct/expected type of network interface controller(NIC) is going to be offered by the hypervisor.

The IPVA offers driver support for:
*AMD NIC: Am79C970A PCnet-PCI II Single-Chip Full-Duplex Ethernet Controller
**a.k.a ''PCNet32''
**a.k.a ''Vlance''

The AMD-NIC is kind of default. However, the NIC type may be overriden manually and accordingly within the configuration file ipva.vmx as follows
<pre>
ethernet0.virtualDev = "vlance"
</pre>

'''Remarks'''

This problem may occur after a VMware re-configuration of the network settings.

===What Can I Do In Case Of Boot-Problem: ''perf-counter not enabled!''===
This paragraph applies, if you experience the following start-up problem.

'''Symptom'''
*the IPVA doesn't start properly
*the console displays
<pre>
perfcounter-not enabled!!!
</pre>
[[Image:screenshot-ipva-perfcounter-nok.jpg|center|thumb|200px|Console displays ''perfcounter-not enabled!!!'']]

'''Solution''' 
This problem is likely caused by an OVA-import of the IPVA. The appliance's configuration file ''ipva.vmx'' requires a VMware proprietary configuration line that's not specifiable within an OVA-file.

The IPVA utilizes a VMware proprietary mechanism for its internal timekeeping<ref>Timekeeping in Virtual Machines http://www.vmware.com/pdf/vmware_timekeeping.pdf</ref>. That mechanism is only available after adding the following line to the configuration file ''ipva.vmx'':
<pre>
monitor_control.pseudo_perfctr = TRUE
</pre>
If that line is not present, the hypervisor is going to throw a CPU exception. Hint: In vSphere a VMX-file can be edited under '''Edit Settings/Options/Advanced/General/Configuration Parameters'''<ref>vmware Labs - How to edit vmx file in ESXi vSphere: https://www.youtube.com/watch?v=ICICoq-maB0</ref>

'''Remarks'''
*The vmx file should be edited after the installation of the IPVA.
*The vmx file should NOT be edited with Text editor (use vSphere as shown above)
*To our knowledge, a converter is always necessary for the installation with vmx.

===What Can I Do In Case Of Boot-Problem: ''Loading failed for image=IPVA BIN''===
This paragraph applies, if you experience the following start-up problem.

'''Symptom'''
*the IPVA doesn't start properly
*the console displays
<pre>
Loading failed for image=IPVA BIN
</pre>
[[Image:Ipva-fw-load-failed.png|center|thumb|200px|Console displays ''Loading failed for image=IPVA BIN'']]

'''Solution''' 
This problem is likely caused by a calculation fault within the boot-code.
*The solution requires a replacement of the boot disk hd-boot.vmdk.
**Download an IPVA package from on 11r2 sr22.
**Replace the 1st disk with the one from the downloaded package

===Are Additional vCPUs useful?===
The Multi-Core functionality of version 13r2 is a beta functionality. Additional virtual CPUs(vCPUs) should not be utilized in production environments.

===How To Replace The Boot Disk On vSphere?===
The recommended way is as follows:
*With ipva.ova deploy a fresh IPVA by means of '''File/Deploy OVF-Template...''' (de: '''Datei/OFV-Vorlage bereitstellen...''') and follow instructions.
**Its use to just serve as a copy source.
*Power-Off the old IPVA.
*In the old IPVA remove the 1st disk on IDE 0:0.
*From the new IPVA copy the 1st harddisk(on IDE 0:0) towards the old IPVA's directory.
*In the old IPVA add the 1st disk on IDE 0:0.
*In the old IPVA confirm and start the machine

===What do the counters mean under Interface/Ethx/Statistic?===
;rx-drop: Accumulates register CSR112 <ref>Command and Status Register</ref> of the emulated chip AM79C970. CSR112: Missed Frame Count. An increase of this value indicates the IPVA was not able to process the network frames fast enough.
;ifInDiscards: Sum of rx-drop, frames dropped due to interface link not up, unsupported ethernet type, internal receive queue full, drop frames of different vlan, drop non vlan frames if vlan is configured
;rx-frame-blocked: Unsupported IP protocol

==Notes==
<references/>

==Related Articles==
[[{{NAMESPACE}}:Licenses]]

[[Howto:A_rough_estimate_of_IPVA_Performance | Howto:A_rough_estimate_of_IPVA_Performance]]

[[Category:Concept|Innovaphone Virtual Appliance]]

Reference14r1:Concept Innovaphone Virtual Appliance (IPVA)

2023-12-01T11:28:13Z

Inno-mst: /* Import new Machine */ Reference to downloadable ipva-qemu.zip

[[Category:Concept12r1|{{PAGENAME}}]]
{{FIXME|reason=This product is in the beta phase and is not yet finished}}

==Applies To==
This information applies to:
*V14r1
*innovaphone Virtual Appliance
*Intel/AMD CPUs
* Virtualization platforms
**VMware
*** Workstation
*** Player
*** vSphere 4.x-6.x
*** ESXi 6.0
**Microsoft Hyper-V ([[{{NAMESPACE}}:Concept IPVA On Hyper-V]])
*** Windows 8.1
*** Windows 10
*** Windows Server 2012 R2
*** Windows Server 2016 CTP4
**Linux based Hypervisors with [https://en.wikipedia.org/wiki/Kernel-based_Virtual_Machine KVM] and [https://en.wikipedia.org/wiki/QEMU QEMU] support
*** Proxmox VE 8.0 / 8.1

''Disclaimer: Manufacturers/versions of VM platforms other than those specified here have not been tested, so use at your own risk.''

==More Information==
The innovaphone Virtual Appliance (IPVA) is a virtual machine to be run on a virtualization platform.

The IPVA is a software-only solution. It appears and behaves like an innovaphone "hard-box" without physical resources such as hardware DSP or ISDN interface.

==Package Overview==
We supply an OVF ('''O'''pen '''V'''irtualization '''F'''ormat) import or - depending on the virtualization platform - a suitable variant.
OVF is an open standard that contains several files in one package. The .ovf file is therefore an archive that contains all the necessary files.

=== Sample VMware ===
;ipva-ovf.zip:
The compressed archive ''ipva-ovf.zip'' contains the file ipva.ova. A deployment of ipva.ova will result in a set of 5 files - the file names may differ from the following list:
*ipva.vmx: The virtual machine configuration file
*hd-boot.vmdk: The virtual boot disk on IDE 0:0
*hd-cf.vmdk: The disk for emulation of a Compact Flash card on IDE 0:1
*hd-flash.vmdk: The disk for emulation of flash memory on IDE 1:0
*hd-dump.vmdk: The disk serving as a store for a crash dump on IDE 1:1

;ipva.bin:
The file ''ipva.bin'' is the firmware file, which is only needed for update purposes.

== Virtualization platforms ==

===VMware Player / VMware Workstation===
==== Import new Machine ====
*Copy the file ipva.ova to e.g. your desktop and Double-click on ipva.ova.
*Edit the file ipva.vmx according to [[#What_Can_I_Do_In_Case_Of_Boot-Problem:_perf-counter_not_enabled.21 | What Can I Do In Case Of Boot-Problem: ''perf-counter not enabled!'']]

===VMware vSphere===
==== Import new Machine ====
*Import ipva.ova by means of '''File/Deploy OVF-Template...''' (de: '''Datei/OFV-Vorlage bereitstellen...''') and follow instructions.
*Edit the file ipva.vmx according to [[#What_Can_I_Do_In_Case_Of_Boot-Problem:_perf-counter_not_enabled.21 | What Can I Do In Case Of Boot-Problem: ''perf-counter not enabled!'']]

===Microsoft Hyper-V===
==== Import new Machine ====
* Use the UI Wizard to Import a new machine
* Browse to the directory where the downloaded package was extracted to. Browse to the subdirectory Virtual Machines and click Ok
* Select ''Copy the Virtual Machine'' as ''Import Type''

===Proxmox VE===
==== Import new Machine ====
Proxmox does not offer a UI option to import existing machines via ovf. The machine must be imported via shell.

* Unzip ipva-qemu.zip and copy ipva-qemu.ova to a suitable disk location on Proxmox
* Navigate to your desired folder, extract and import the VM (''think about the vm-id concept in Proxmox! - In this example, we use ID 503)
** <code>cd /mnt/pve/my-storage/images/ipva</code>
** <code>tar -xvf ipva-qemu.ova</code>
** <code>qm importovf 503 ipva-qemu.ovf local-lvm</code>
* Before you start up the VM in the UI you have to configure the following:
** Hardware -> Add -> Network Device
*** add a new network adapter with model ''VirtIO''
** Hardware -> Processors
*** adjust "Extra Cpu Flags" -> "aes" if required

==Configuration==

===Network Configuration===
Manufacturer-configured as DHCP client only. I.e. a DHCP server must be available. Afterwards the network configuration may be administrated as used to within the web ui of other innovaphone boxes. If there's in no case a DHCP server available for the 1st-time configuration, read through [[#What_Is_The_Console_Good_For?|What Is The Console Good For?]].

====MAC/serial number====
Take care that you use a MAC address which is supported by my.innovaphone, see [[Reference:My_Innovaphone#IPVA_MAC_exists]].

==Troubleshooting==
Support procedures are commonly identical to the ones known from innovaphones' physical appliances. Except for:
*'''Post-Mortem Logs''' A post-mortem log must be retrieved by clicking on ''Maintenance/Diagnostics/Tracing/'''trace(crash-dump)''''' (alternatively: http://a.b.c.d/crash_dump.txt).

Some known issues are listed further below under [[#FAQ | FAQ]].

==Known Issues==

=== Restored IPVA may not run ===
We have seen issues where an IPVA which had been backed up using one of the available backup tools for VMWare do not start up properly when they have been restored.

We strongly suggest to not rely on VMWare backup mechanism but instead to use the standard innovaphone backup scheme (that is, save the configuration on a regular basis).

==== How to run a restored backup that fails to start ====
Here is the procedure to run an IPVA from an IPVA if the restored virtual machine does not boot up properly:

* restore the backed up V10 IPVA
* create a new, empty V11r1 IPVA (you will need this merely to copy the boot disk from)
*replace the boot disk of the failing V10 IPVA by the boot disk of the fresh V11r1 IPVA (see [[#How_To_Replace_The_Boot_Disk_On_vSphere.3F | How To Replace The Boot Disk On vSphere]] for details)
* start the restored and fixed V10 IPVA (it should run fine now)
* downgrade this V10 IPVA to desired V10 firmware
* remove the fresh V11r1 IPVA

Some Customer who are running Fw v12r1 (up to sr6) with ESXi 6.0 and VEEAM 9 reported that after a backup with VEEAM 9, the restored IPVA was not starting.
At this point, there is no possibility to solve this problem. The only workaround in that case is to delete the machine, reinstall a new one, and restore a configuration saved before.

If you did not run into the problem yet, for prevention, we recommend to replace the Boot disk of your working IPVA.vmx with one of the IPVA.ova. Please follow the steps below (be aware that this will upgrade the firmware on the IPVA to 12r2, due to the fact that actually, IPVA.ova is only available from version 12r2):

1. Remove the Boot disk of the virtual machine (vmx)(is normaly the first one). 
* Power off the VM
* Select the Virtual Machine > Settings.
* On the Hardware tab, select the virtual hard disk and click ''Remove''.
* Click ''OK'' to save your changes.

2. Add the Boot disk of the ova virtual machine to the vmx one.
* Identify the size of the boot disk of the ova virtual machine (will be needed on the step when navigating to boot disk)
* On the powered off VM, Select the Virtual Machine > Settings.
* On the Hardware tab, select the virtual hard disk and click ''Add''.
* Select Use “an existing virtual disk” then click ''Next''.
* Navigate to the boot disk of the ova Virtual machine then click ''next''.
* Click ''Finish''.
Now the vmx virtual machine should have the Fw version 12r2.

The .ova version will be available also in V12r1 sr7

=== IPVA does not run on Citrix Cloud Platform ===
Reportedly, the Citrix cloud platform - although based on VMware - cannot run the IPVA. Amongst other issues, the platform does not allow 4 virtual disks, which are required for the IPVA.

=== IPVA does not run on VCloud Air ===
VCloud Air apparently does not support the timekeeping mechanism required by the IPVA.

[[User:Ckl|ckl]] 15:50, 30 November 2016 (CET) We have seen the IPVA v12r2 running on vCloud Air. Use the ova import.

=== IPVA on ESX 6.5 ===
We have reports that the IPVA does not run properly on ESX 6.5. The IPVA boots up properly but the clock does not run. Running the .ova based variation available in v12r2 fixed the issue or edit the file ipva.vmx according to [[#What_Can_I_Do_In_Case_Of_Boot-Problem:_perf-counter_not_enabled.21 | What Can I Do In Case Of Boot-Problem: ''perf-counter not enabled!'']]

=== Administration: Avoid 'reboot' Command. Use 'reset' Command ===
Alwas use the 'reset' command to restart an IPVA.
The 'reboot' command makes sense only on physical applicances, where its purpose is to deploy a new bootcode by means of a forced watchdog trap. The resulting post-reboot state will be as if an unsolicited trap/crash had occurred.

=== No Fault Tolerance Support from VMWare vSphere 6.5 ===
We have reports that VMWare vSphere 6.5 Fault Tolerance (FT) no longer works. For further information regarding this feature, please refer to the respective note in [[Howto:Implement_PBX_with_zero_downtime_using_IPVA_and_VMWare_Fault_Tolerance | Implement PBX with zero downtime using IPVA and VMWare Fault_Tolerance]].

=== Voice Quality Issues ===
When dealing with media streams (e.g. for announcements), the IPVA needs to fulfil real-time processing requirements, for example to process RTP packets in a timely fashion. To do so, the IPVA relies on the capabilities of the virtualization platform it runs on.

It is therefore important to configure the platform so that it supports real-time applications best. If you experience voice quality or latency issues, consider
* to make sure that all of the IPVAs memory is ''reserved'' to the IPVA (''Latency Sensitivity'' set to ''High'')
* to guarantee exclusive PCPU access
This helps to reduce CPU halt/wake-up states.

===Additional vCPUs may cause problems===
The Multi-Core functionality of version 13r2 is a beta functionality. Additional virtual CPUs(vCPUs) should not be utilized in production environments.

==FAQ==
===Can The Emulated CompactFlash Be Increased In Size?===
Yes, from within the ''Edit Virtual Machine'' dialog. Doing so just increases the size of the virtual harddisk. The emulated CompactFlash must be formatted afterwards and accordingly to benefit from the increased size. That step can be administrated from ''Administration/Compact Flash/Format''. Note: A recommendation for an upper size limit is not given.

'''vSphere / vSphere Client'''

1. At first backup all of your files from CF card 
2. Shutdown the corresponding IPVA 
3. Choose "Properties" of the IPVA 
4. Delete "Harddrive 2" (Hardrive file xxx/xxx_1.vmdk) 

hd-boot.vmdk > xxx.vmdk
hd-cf.vmdk > xxx_1.vmdk
hd-flash.vmdk > xxx_2.vmdk
hd-dump.vmdk > xxx_3.vmdk

5. Create new harddrive 
6. Configure the required size 
7. As "Node of virtual device" select "IDE(0:1)" 
8. Start the IPVA. 
9. "Format" the CF Card and "mount" it (General/Compact-Flash/General)

===What Is The Size Of the emulated Flash Storage on the IPVA?===
The virtual flash storage used to store configuration file of the IPVA and LDAP directory of the PBX is defined with 64 MB and can not be changed. This is two times more than on IP6010. The VMDK-File hd-flash.vmdk is allocated with 100 MB, because VMWare can not handle smaller virtual disks.

===What Is The Size Of the Flash Directory on the IPVA?===
As noted above, the virtual flash memory on the IPVA is fixed to a size of 64MB. Most of the flash is used by the ''flash directory'' (FLASHDIR0) which amongst other things provides storage for PBX objects.

The size of the flash directory depends on the available RAM. The maximum of 900 segments á 64KB, i.e. ~56MB, is available if 192MB or more RAM is available. If less RAM is available, the size of the flash directory is decreased accordingly. For this reason, it is unsafe to reduce RAM size in a given IPVA, as the flash directory size may be decreased so that objects from the flash directory get lost.

The easiest method to see how much flash directory space is available is to investigate the boot trace. For the standard configuration of 64MB the respective trace output is going to look as follows and informs about a size of 14MB:

0:0000:081:4 - start flashdir FLASHDIR0
0:0000:081:4 - fdir: segments=901->224(14.0MB)

===How Much RAM Is Required Per IPVA Instance?===
Since 12r2sr27/13r1sr5 the downloadable virtual appliance comes preconfigured with 256MB RAM. This amount is seen as a good trade-off for the majority of all installations.
The RAM-size can be administrated by VMware-means.

===What Is The Maximum Amount Of RAM?===
The maximum meaningful RAM setting is 3GB. Memory space beyond that limit will be left unused. Assigning more than 3GB to an IPVA instance doesn't provide any benefit.

===Why Does ''General/Info/DRAM'' Show Less Than the Configured Memory?===
Not all of the configured memory is available to the IPVA. E.g. a bit of memory is occupied by the VMM<ref>Virtual Machine Monitor: A component belonging to the virtualization platform</ref>. The indicator ''General/Info/DRAM'' displays the memory available to the IPVA and is truncated down to a whole number. A boot-trace reveals a bit more about IPVA-available memory as shown in the following excerpt:
<pre>
...
0:0000:030:4 - Intel(R) Core(TM)2 Duo CPU E8400 @ 3.00GHz
0:0000:030:4 - mem(64946176)=61.93MB ...
</pre>

===How Many IPVA Instances Are Possible Per Host?===
There's no worst-case estimate available. For a best-case calculation,
*see [http://www.vmware.com/pdf/vsphere4/r41/vsp_41_config_max.pdf Configuration Maximums VMware vSphere 4.1]
*see [[#How_Much_RAM_Is_Required_Per_IPVA_Instance.3F | How Much RAM Is Required Per IPVA Instance?]]
Additional preformance reflections
*see [[HOWTO:A_rough_estimate_of_IPVA_Performance | A rough estimate of IPVA Performance]]

===How do I perform a factory reset?===

replace the 3rd disk, served on IDE 1:0, named hd-flash.vmdk with an empty disk:

[[Image:VM_Settings.png]]

1)download the IPVA and watch out for the file hd-flash.vmdk

2)Power-off the IPVA instance

3)Replace hd-flash.vmdk with the one downloaded in step 1). If on vsphere it may have been assigned a different name. Ensure it’s the one on IDE 1:0.

4)Power-on the IPVA instance

===What About VMware Tools?===
VMware Tools are not supported.

===What Is The Console Good For?===
The console is a remains of the early development phase. It resembles the IP3000's serial console. It doesn't offer any convenience like command history or backspace funtionality. Nevertheless may the console be of help in exceptional situations where e.g. the required DHCP server isn't available for 1st-time configuration or in situations where the ip configuration was misconfigured. Thereby any command from a device's config is acceptable.

For instance to configure the static IP address 1.2.3.4/24 on ETH0:
*Click into the console
*Press ENTER
*Enter credentials
*Enter
<pre>
config change IP0 ETH0 /addr 192.168.0.10 /mask 255.255.255.0
config change IP0 RT0 /gateway 192.168.0.1
config change DHCP0 /mode off
config write
reset
</pre>
Since no backspace is offered it may become a daring task to enter a single line without typos. In case of a typo hit ENTER and input the same line again.
The keyboard layout is the US layout.
[[Image:Ip-via-console.png|center|thumb|200px|Console-edit of IP address]]

Display the IP configuration for ETH0:
<pre>
config show IP0 ETH0
</pre>

Display the DHCP configuration for ETH0:
<pre>
config show DHCP0
</pre>

Additional the DNS-server(s) and the default gateway can be configured:
<pre>
config change IP0 ETH0 /addr 1.2.3.4 /mask 255.255.255.0 /dns 8.8.8.8 /dns2 8.8.4.4
config change IP0 RT0 /gateway 1.2.3.254
config change DHCP0 /mode off
config write
reset
</pre>

Also some simple diagnostics (ping and traceroute) are possible via the console (output is given in the console):
<pre>
mod cmd PING0 tracert 8.8.8.8
mod cmd PING0 ping 8.8.8.8
</pre>

Resetting the entire FLASH space - '''Note, all configuration will get lost'''. this is similar method to the manufacturer reset method from above [[#How_do_I_perform_a_factory_reset.3F|How do I perform a factory reset?]]
<pre>
mod cmd FLASHMAN0 reset all
reset
</pre>

===What Can I Do In Case Of A Checksum Boot Error?===
This paragraph applies, if you experience the following start-up problem.

'''Symptom'''
*the IPVA doesn't start properly
*the console displays
<pre>
checksum wrong! Loading failed for image=IPVA BIN
</pre>
[[Image:ipva-crc-wrong.jpg|center|thumb|200px|Console displays CRC boot error]]

'''Solution'''
*Power-off the IPVA
*Replace the boot harddisk by a fresh one. The boot harddisk is the 1st hd(originally named ''hd-boot.vmdk'').

'''Remarks'''

This problem may occur on a system crash while a firmware update is taking place.

===What Can I Do In Case Of Boot-Problem: ''NIC unavailable!''===
This paragraph applies, if you experience the following start-up problem.

'''Symptom'''
*the IPVA doesn't start properly
*the console displays
<pre>
NIC unavailable!
</pre>
[[Image:ipva-nic-unavailable.jpg|center|thumb|200px|Console displays ''NIC unavailable!'']]

'''Solution'''
*Power-off the IPVA
*Administrate by VMware means: Ensure the correct/expected type of network interface controller(NIC) is going to be offered by the hypervisor.

The IPVA offers driver support for:
*AMD NIC: Am79C970A PCnet-PCI II Single-Chip Full-Duplex Ethernet Controller
**a.k.a ''PCNet32''
**a.k.a ''Vlance''

The AMD-NIC is kind of default. However, the NIC type may be overriden manually and accordingly within the configuration file ipva.vmx as follows
<pre>
ethernet0.virtualDev = "vlance"
</pre>

'''Remarks'''

This problem may occur after a VMware re-configuration of the network settings.

===What Can I Do In Case Of Boot-Problem: ''perf-counter not enabled!''===
This paragraph applies, if you experience the following start-up problem.

'''Symptom'''
*the IPVA doesn't start properly
*the console displays
<pre>
perfcounter-not enabled!!!
</pre>
[[Image:screenshot-ipva-perfcounter-nok.jpg|center|thumb|200px|Console displays ''perfcounter-not enabled!!!'']]

'''Solution''' 
This problem is likely caused by an OVA-import of the IPVA. The appliance's configuration file ''ipva.vmx'' requires a VMware proprietary configuration line that's not specifiable within an OVA-file.

The IPVA utilizes a VMware proprietary mechanism for its internal timekeeping<ref>Timekeeping in Virtual Machines http://www.vmware.com/pdf/vmware_timekeeping.pdf</ref>. That mechanism is only available after adding the following line to the configuration file ''ipva.vmx'':
<pre>
monitor_control.pseudo_perfctr = TRUE
</pre>
If that line is not present, the hypervisor is going to throw a CPU exception. Hint: In vSphere a VMX-file can be edited under '''Edit Settings/Options/Advanced/General/Configuration Parameters'''<ref>vmware Labs - How to edit vmx file in ESXi vSphere: https://www.youtube.com/watch?v=ICICoq-maB0</ref>

'''Remarks'''
*The vmx file should be edited after the installation of the IPVA.
*The vmx file should NOT be edited with Text editor (use vSphere as shown above)
*To our knowledge, a converter is always necessary for the installation with vmx.

===What Can I Do In Case Of Boot-Problem: ''Loading failed for image=IPVA BIN''===
This paragraph applies, if you experience the following start-up problem.

'''Symptom'''
*the IPVA doesn't start properly
*the console displays
<pre>
Loading failed for image=IPVA BIN
</pre>
[[Image:Ipva-fw-load-failed.png|center|thumb|200px|Console displays ''Loading failed for image=IPVA BIN'']]

'''Solution''' 
This problem is likely caused by a calculation fault within the boot-code.
*The solution requires a replacement of the boot disk hd-boot.vmdk.
**Download an IPVA package from on 11r2 sr22.
**Replace the 1st disk with the one from the downloaded package

===Are Additional vCPUs useful?===
The Multi-Core functionality of version 13r2 is a beta functionality. Additional virtual CPUs(vCPUs) should not be utilized in production environments.

===How To Replace The Boot Disk On vSphere?===
The recommended way is as follows:
*With ipva.ova deploy a fresh IPVA by means of '''File/Deploy OVF-Template...''' (de: '''Datei/OFV-Vorlage bereitstellen...''') and follow instructions.
**Its use to just serve as a copy source.
*Power-Off the old IPVA.
*In the old IPVA remove the 1st disk on IDE 0:0.
*From the new IPVA copy the 1st harddisk(on IDE 0:0) towards the old IPVA's directory.
*In the old IPVA add the 1st disk on IDE 0:0.
*In the old IPVA confirm and start the machine

===What do the counters mean under Interface/Ethx/Statistic?===
;rx-drop: Accumulates register CSR112 <ref>Command and Status Register</ref> of the emulated chip AM79C970. CSR112: Missed Frame Count. An increase of this value indicates the IPVA was not able to process the network frames fast enough.
;ifInDiscards: Sum of rx-drop, frames dropped due to interface link not up, unsupported ethernet type, internal receive queue full, drop frames of different vlan, drop non vlan frames if vlan is configured
;rx-frame-blocked: Unsupported IP protocol

==Notes==
<references/>

==Related Articles==
[[{{NAMESPACE}}:Licenses]]

[[Howto:A_rough_estimate_of_IPVA_Performance | Howto:A_rough_estimate_of_IPVA_Performance]]

[[Category:Concept|Innovaphone Virtual Appliance]]

Reference13r3:Concept App Service Contacts

2022-07-14T14:49:27Z

Inno-mst: /* DECT Phones Cannot Access Personal Directories */

[[Category:Concept|Apps]]
{{FIXME|reason=This product is in the beta phase and is not yet finished}}

= Applies To =
* App Contacts version 13r3

= Overview =
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, as well as maintaining personal contact books.

Inside Contacts, personal and general entries can be searched (forward lookup) or be used to resolve incoming numbers to their respective name (reverse lookup).

= Features =
*Import: Comma-separated files
*Database for contact entries: A user interface for retrieval purposes is available.
*API: Search API for other apps
*Edit Functionality: Contact entries are editable.
*Personal Address Book: Every user can maintain one or more personal address books.
*Access Right Management: Owners can maintain access privileges for single users or even groups of users, in order to control viewability of an address book.

= Requirements =
innovaphone PBX and App Platform from on version 13r3.
==Upgrade Considerations==
As always, don't forget to backup an existing App Platform in prior. This 13r3 App Contacts does alter the underlying database scheme.
;13r3 App on 13r1 App Platform, 13r1 PBX:Doesn't work. This 13r3 Contacts App does not work on an 13r1 Application Platform/Environment.
;13r3 App on 13r2 App Platform, 13r2 PBX:The 13r3 Contacts App works with the restriction, that the reverse lookup for private address books doesn't work. For full feature set, also upgrade the App Platform and PBX to 13r3.

=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

= Concept =
General contact entries and entries for personal directories are stored within the same database. With the table '''acl''' which is acting as an access control list, restricted views and edit rights for personal directories can be granted.

This way, only the owner of a personal directory (and granted user or groups) can see the content.

==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 <code>0-9,+,*,#</code> 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 [[Reference13r1:Concept_Number_Adjustments_%28Dialing_Location%29 |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.

==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. 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<ref>Meta attribute: Here an attribute with a special meaning and that is non-physical, not existing within the database</ref>, 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 App Platform>
;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''

= Personal Address Book Details =
With version 13r3 it is now possible, to add, editing and delete contacts. It is also possible to create and maintain personal address book(s), as well as share them with other users or whole user groups.

Only user/groups with sufficient rights, will be able to see other address books. An Access control list (acl) is used, to control these rights.

Groups correspond to PBX-groups. The Contacts App gets to know only active PBX-group memberships.

By default, only the user who created an address book, is able to see the content.

==Maintain a Personal Address Book==
;Creating a Personal Address Book
Click on the burger menu in the top right corner inside the Contacts-App, and there on the '''"Directories"'''. Now click on the '''"+"'''-Sympbol, choose a suitable name and confirm your name via '''"Save"''' button. A new address book is created.
;Adding a new contact
Click on the '''"+"'''-Sympbol in the top right corner inside the Contacts-App and select an address book, where you want the contact to be stored in. Now fill in the contact information (the fields ''"name"'' and ''"last name"'' '''have to be filled''') and save it via '''"Save"'''-button.
;Editing an existing contact
Search for the contact you want to edit via the search box inside the Contacts-App. Click on the '''"Details"'''-field on the right of the contact entry. Now click on the bottom on the '''"Edit"'''-button, click on the entry you want to edit and after your change, save it via '''"Save"'''-button on the bottom.
;Delete an existing contact
Search for the contact you want to edit via the search box inside the Contacts-App. Click on the '''"Details"'''-field on the right of the contact entry. Now click on the bottom on the '''"Edit"'''-button, and on the '''"trashcan"'''-symbol at the top. After confirmation, the entry is deleted.

==Sharing of Address Book==
;Share globally
*Either remove all rules from a personal directory. Such a configuration corresponds to pre-13r3 capabilities. Up to 13r2 there weren't any visibility rules available.
*Or make every PBX user an active member of a group e.g. "everybody" and add a directory rule for that group "everybody".

;Share with single user(s)
Click on the menu in the top right corner inside the Contacts-App, click on '''"directories"''' and select a directory, you want to share.

Now click on the '''"+"'''-symbol and select '''"User"''' as type. Enter the h323 name of the user, whom you want to give access (field '''Name''' in a user object) and select either if the user should have admin-rights or not. Now click on '''Ok''' and submit your change with another click on '''Ok'''.

;Share with a group
Click on the menu in the top right corner inside the Contacts-App, click on '''"directories"''' and select a directory, you want to share.

Now click on the '''"+"'''-symbol and select '''"Group"''' as type. Enter the name of the PBX group and select either if the user should have admin-rights or not. Now click on '''Ok''' and submit your change with another click on '''Ok'''-button.

;Revoke of granted rights
You can also revoke previous granted rights by just clicking on the user/group at the access control list, and click on the '''trashcan''' symbol. Now submit your change with another click on '''Ok'''-button.

==Upload a new Directory==
As of Beta-Functionality: The Contacts Admin App allows to upload a CSV file as known from the 13r2 version ('''Hamburger/Import'''). In the course of an upload operation a new directory will be created. The newly assigned directory name will be the name of the CSV file.
After uploading the visibility setting of the new directory should be administrated as stated before under [[#Sharing_of_Address_Book|Sharing of Address Book]]

==Terminology==
;ACL: Access control list. Refers the database table ''acl'' and rows/entries therein.
;Directory: Refers the database table ''dbs'' and rows/entries therein. All contact entries referencing a ''dbs''-row make up the content of a directory.
;Address Book: Synonymous with ''Directory''
;Contacts Admin: A user utilizing the Contacts Admin App (via App URL, ending with ../innovaphone-contacts-admin)
;Directory Admin: A user entitled the admin right for a directory. Either by user-wise or by group-wise ACL entry.
;Directory User/Viewer: A user entitled the viewing right for a directory. Either by user-wise or by group-wise ACL entry.

==Database Changes==
Three tables realize the functionality for personal directories.
*Table '''dbs'''. Each row represents a directory. Two new columns ''displayname, sip'' where added.
**'''displayname''' Name display.
**'''sip''' Creator's sip name, if available.
*Table '''acl'''.New table acting as access control list. Each row references a directory as listed by table ''dbs'' and is going to grant view- and admin-right to a specific user or group.
**'''dbsid''' Reference into table dbs.
**'''name''' The name of a user or a group.
**'''acltype''' A numeric value: user(0), group(1)
**'''admin''' Granting edit right: admin(true), non-admin(false)
*Table '''entries'''. Each row within this pre-exisisting table represents a contact entry. The column ''dbsid'' informs about whether an entry belongs to a specific directory.<code type="sql">
#Excerpt for an additional directory ''Persönliches Verzeichnis: mst'' with one contact entry.

root@app-platform|/mnt/sda2/home/admin> psql -d "innovaphone.com_contacts" -c "select * from dbs"
id | uri | displayname | sip
----+------------------------------------------------------+--------------------------------+-----
7 | file:///4eaae395-9971-40fb-9a05-dfae1d023f12?sip=mst | Persönliches Verzeichnis: mst | mst # Specification for directory ('Persönliches Verzeichnis: mst')

root@app-platform|/mnt/sda2/home/admin> psql -d "innovaphone.com_contacts" -c "select * from acl"
id | dbsid | name | acltype | admin
----+-------+------+---------+-------
5 | 7 | mst | 0 | t #user 'mst' can view and edit directory with dbsid=7 ('Persönliches Verzeichnis: mst')

root@app-platform|/mnt/sda2/home/admin> psql -d "innovaphone.com_contacts" -c "select sn,givenname,company,id,dbsid from entries where dbsid=7"
sn | givenname | company | id | dbsid
----------+-----------+--------------+-------+-------
Duck | Dagobert | Duck Corp. | 51394 | 7 # main table entries contains 1 entry belonging to ('Persönliches Verzeichnis: mst')

</code>

==Reverse Number Lookup for Personal Directories==
Queries into directories are access-checked by looking-up and enforcing ACL-rules. The information on whose name is being queried and which group memberships are taking effect is needed for this process.

Websocket connections to the Contacts App service carry those infos within the SDK method ''AppWebsocketConnectComplete()''.
LDAP connections pass this information within a proprietary LDAP control together with an LDAP searchRequest message.

The PBX's centralized Reverse Lookup service (see ''PBX/Config/General/Reverse Lookup URL'') does support this mechanism. That is, for every LDAP searchRequest the affected user's name and active group memberships are going to be sent towards the Contacts App's LDAP server.

See also [[Reference13r1:Concept_Reverse_Lookup|concept article on reverse lookup]].

=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<ref>For a windows distribution: e.g.: https://curl.haxx.se/download.html </ref><ref>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</ref>
The required user and password content corresponds to the configuration underneath '''PBX Manager/AP Contacts/Configuration/User(HTTP Post)''' and '''Password(HTTP Post)'''
<code type="powershell">
# csv.ps1
# Sample powershell script demonstrating how to HTTP POST a CSV file towards the Contacts App service.
# .\bin\curl must be present, e.g. from https://curl.haxx.se/download.html
# Examples:
# 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 ""
</code>
== The URL ==
The first part of the URL (''example.com/contacts01'') is the ''Webserver path'' configured for the ''Contacts'' instance in the ''App Platform Manager''. It must be followed by the literal <code>post</code>. 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.

=Troubleshooting=
To collect debugging data, activate the '''''App''''' and App '''''WebSocket''''' trace options at the contacts instance on the App Platform Manager. Now reproduce the issue and save the logfile.

==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<ref>putty: https://putty.org</ref>
<code type="bash">
#Login
#===================================================================
login as: admin
Using keyboard-interactive authentication.
Password:

#Elevate to super-user rights, Command 'su'
#===================================================================
admin@app-platform|/mnt/sda2/home/admin> su
Password:

#Command 'psql'. Printing the table 'dbs'. Contains 2 file names.
#===================================================================
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)

#Delete the file "brs%20testimport.csv" via its table-ID 5.
#===================================================================
root@app-platform|/mnt/sda2/home/admin> psql -d "innovaphone.com_contacts" -c "delete from dbs where id=5"
DELETE 1

#Printing the table 'dbs'. Contains 1 file name.
#===================================================================
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>

</code>

==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<ref>putty: https://putty.org</ref>
<code type="bash">
#Login
#===================================================================
login as: admin
Using keyboard-interactive authentication.
Password:

#Elevate to super-user rights, Command 'su'
#===================================================================
admin@app-platform|/mnt/sda2/home/admin> su
Password:

#List number of contacts in main table entries
#===================================================================
root@app-platform|/mnt/sda2/home/admin> psql -d "innovaphone.com_contacts" -c "select count(*) from entries"
count
-------
94
(1 row)

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

#List number of contacts in main table entries
#===================================================================
root@app-platform|/mnt/sda2/home/admin> psql -d "innovaphone.com_contacts" -c "select count(*) from entries"
count
-------
0
(1 row)
</code>

==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<ref>putty: https://putty.org</ref>
<code type="bash">
#Login
#===================================================================
login as: admin
Using keyboard-interactive authentication.
Password:

#Elevate to super-user rights, Command 'su'
#===================================================================
admin@app-platform|/mnt/sda2/home/admin> su
Password:

#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

#Retrieve all database entries, separate them by ; and store in file
#===================================================================
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"

</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 Issues =
* [[Support:Contacts_on_HomeScreen_can%27t_be_open_after_modification_on_ContactsAPP | Contacts on HomeScreen can't be open after modification on ContactsAPP]]
* [[Support:Contacts_Upload_Fails_From_Within_myApps_Launcher | Contacts Upload Fails From Within myApps Launcher]]
* [[Support:Forward_search_shows_no_result | Forward Search shows "no result"]]
== DECT Phones Cannot Access Personal Directories ==
DECT gateways do not support the mechanism required to query into directories with restricted access rules. Hence, DECT mobile phones cannot search into such directories.

= Related =
<references/>

Reference13r3:Concept App Service Contacts

2022-07-14T14:47:30Z

Inno-mst: /* Known Issues */ Added "DECT Phones Cannot Access Personal Directories"

2021-09-10T14:13:58Z

Inno-mst: correcting proxy logoff mechanism

;'''EAP-MD5''':
* '''User''' Enter the user/identity to authenticate with.
* '''Password''' Enter the shared secret for the MD5 challenge/response handshake.
;'''EAP-TLS''':
The EAP-MD5 settings are going to reused for EAP-TLS needs. I.e. there's currently no extra setting for EAP-TLS. The configuration for an actual certificate, being fed into the EAP-TLS session, can be found at ''General/Certificates/Device Certificate''.

* '''User''' Enter the user/identity<ref>EAP-TLS doesn't mandate that identity to necessarily be the same as the certificates subject/CN</ref> to be sent within the EAP Identity request.<ref name="user-pw">A non-empty user/password just serves as an "on"-switch</ref>
* '''Password''' Enter arbitrary content.<ref name="user-pw"/>
* '''General/Certificates/Device Certificate'''
;'''Proxy-Logoff''':
If the phone's PC-port got disconnected, EAPOL-Logoff messages are going to be sent on behalf of participants that were connected to the phone's PC-port.
An EAPOL-Logoff will be sent for each MAC-address learned from traversing EAPOL-Start messages.

=Notes=
<references/>

=Related Articles=
[[Concept_802.1X|Concept 802.1X]]

[[Howto:802.1X_EAP-TLS_With_FreeRadius|Howto article: 802.1X EAP-TLS With FreeRadius]]

[[Howto:Security_works_with_innovaphone#802.1X_port_security|Howto article:Security_works_with_innovaphone]]

Reference13r2:Concept Innovaphone Virtual Appliance (IPVA)

2021-08-25T15:01:46Z

Inno-mst: Documenting 13r2 multi-core functionality as beta

[[Category:Concept12r1|{{PAGENAME}}]]

==Applies To==
This information applies to:
*V13r2
*innovaphone Virtual Appliance
*Intel/AMD CPUs
*VMware
**Workstation
**Player <ref>VMware Player Download(free): http://vmware.com/download/player/</ref>
**vSphere 4.x-6.x
**ESXi 6.0
*For support of Hyper-V, refer to [[Reference12r2:Concept IPVA On Hyper-V]].

==More Information==
The innovaphone Virtual Appliance (IPVA) is a virtual machine to be run on a virtualization platform.
Whereby, VMware<ref>http://www.vmware.com</ref> and Hyper-V<ref>https://docs.microsoft.com/en-us/virtualization/hyper-v-on-windows/about/</ref> are the solely supported virtualization platforms to-date. This aticle describes teh use of VMware, for support of Hyper-V, refer to this [[Concept_IPVA_On_Hyper-V|article]].

The IPVA is a software-only solution. It appears as and performs as an innovaphone "hard-box" excluding DSP-, ISDN-/AB-resources.

The following core-components are contained within the IPVA:
*innovaphone PBX
*innovaphone Gateway (a.k.a ''Relay'')
*integrated mass-storage (alike innovaphones' CF-card support)


==Configuration==
[[#Download|Download]] the IPVA.

;ipva-ovf.zip:
The compressed archive ''ipva-ovf.zip'' contains the file ipva.ova. A virtual machine according to the '''O'''pen '''V'''irtualization '''F'''ormat specification. A deployment of ipva.ova will result in a set of 5 files - the file names may differ from the following list:
*ipva.vmx: The virtual machine configuration file
*hd-boot.vmdk: The virtual boot harddisk (hd)
**On IDE 0:0
*hd-cf.vmdk: The hd for emulation of a Compact Flash card
**On IDE 0:1
*hd-flash.vmdk: The hd for emulation of flash memory
**On IDE 1:0
*hd-dump.vmdk: The hd serving as a store for a crash dump
**On IDE 1:1

;ipva.bin:
The file ''ipva.bin'' is the firmware file, which is only needed for update purposes.

;ipva-vmx.zip:
A legacy zip file containing the IPVA according to a VMware proprietary format.

===VMware Player And VMware Workstation===
*Copy the file ipva.ova to e.g. your desktop
*Double-click on ipva.ova.
**The IPVA is going to be imported.
*Edit the file ipva.vmx according to [[#What_Can_I_Do_In_Case_Of_Boot-Problem:_perf-counter_not_enabled.21 | What Can I Do In Case Of Boot-Problem: ''perf-counter not enabled!'']]
**'''Note''': Skipping this configuration setting will let the IPVA crash
*Power-on the machine

===VMware vSphere===
*Import ipva.ova by means of '''File/Deploy OVF-Template...''' (de: '''Datei/OFV-Vorlage bereitstellen...''') and follow instructions.
*Edit the file ipva.vmx according to [[#What_Can_I_Do_In_Case_Of_Boot-Problem:_perf-counter_not_enabled.21 | What Can I Do In Case Of Boot-Problem: ''perf-counter not enabled!'']]
**'''Note''': Skipping this configuration step will let the IPVA crash
*Power-on the machine

===Network Configuration===
Manufacturer-configured as DHCP client only. I.e. a DHCP server must be available. Afterwards the network configuration may be administrated as used to within the web ui of other innovaphone boxes. If there's in no case a DHCP server available for the 1st-time configuration, read through [[#What_Is_The_Console_Good_For?|What Is The Console Good For?]].

==Download==

IPVA.zip
* v12r1: https://download.innovaphone.com/ice/12r1/#firmware
* v12r2: https://download.innovaphone.com/ice/12r2/#firmware

==Troubleshooting==
Support procedures are commonly identical to the ones known from innovaphones' physical appliances. Except for:
*'''Post-Mortem Logs''' A post-mortem log must be retrieved by clicking on ''Maintenance/Diagnostics/Tracing/'''trace(crash-dump)''''' (alternatively: http://a.b.c.d/crash_dump.txt).

Some known issues are listed further below under [[#FAQ | FAQ]].

==Known Issues==

=== Restored IPVA may not run ===
We have seen issues where an IPVA which had been backed up using one of the available backup tools for VMWare do not start up properly when they have been restored.

We strongly suggest to not rely on VMWare backup mechanism but instead to use the standard innovaphone backup scheme (that is, save the configuration on a regular basis).

==== How to run a restored backup that fails to start ====
Here is the procedure to run an IPVA from an IPVA if the restored virtual machine does not boot up properly:

* restore the backed up V10 IPVA
* create a new, empty V11r1 IPVA (you will need this merely to copy the boot disk from)
*replace the boot disk of the failing V10 IPVA by the boot disk of the fresh V11r1 IPVA (see [[#How_To_Replace_The_Boot_Disk_On_vSphere.3F | How To Replace The Boot Disk On vSphere]] for details)
* start the restored and fixed V10 IPVA (it should run fine now)
* downgrade this V10 IPVA to desired V10 firmware
* remove the fresh V11r1 IPVA

Some Customer who are running Fw v12r1 (up to sr6) with ESXi 6.0 and VEEAM 9 reported that after a backup with VEEAM 9, the restored IPVA was not starting.
At this point, there is no possibility to solve this problem. The only workaround in that case is to delete the machine, reinstall a new one, and restore a configuration saved before.

If you did not run into the problem yet, for prevention, we recommend to replace the Boot disk of your working IPVA.vmx with one of the IPVA.ova. Please follow the steps below (be aware that this will upgrade the firmware on the IPVA to 12r2, due to the fact that actually, IPVA.ova is only available from version 12r2):

1. Remove the Boot disk of the virtual machine (vmx)(is normaly the first one). 
* Power off the VM
* Select the Virtual Machine > Settings.
* On the Hardware tab, select the virtual hard disk and click ''Remove''.
* Click ''OK'' to save your changes.

2. Add the Boot disk of the ova virtual machine to the vmx one.
* Identify the size of the boot disk of the ova virtual machine (will be needed on the step when navigating to boot disk)
* On the powered off VM, Select the Virtual Machine > Settings.
* On the Hardware tab, select the virtual hard disk and click ''Add''.
* Select Use “an existing virtual disk” then click ''Next''.
* Navigate to the boot disk of the ova Virtual machine then click ''next''.
* Click ''Finish''.
Now the vmx virtual machine should have the Fw version 12r2.

The .ova version will be available also in V12r1 sr7

=== IPVA does not run on Citrix Cloud Platform ===
Reportedly, the Citrix cloud platform - although based on VMware - cannot run the IPVA. Amongst other issues, the platform does not allow 4 virtual disks, which are required for the IPVA.

=== IPVA does not run on VCloud Air ===
VCloud Air apparently does not support the timekeeping mechanism required by the IPVA.

[[User:Ckl|ckl]] 15:50, 30 November 2016 (CET) We have seen the IPVA v12r2 running on vCloud Air. Use the ova import.

=== IPVA on ESX 6.5 ===
We have reports that the IPVA does not run properly on ESX 6.5. The IPVA boots up properly but the clock does not run. Running the .ova based variation available in v12r2 fixed the issue or edit the file ipva.vmx according to [[#What_Can_I_Do_In_Case_Of_Boot-Problem:_perf-counter_not_enabled.21 | What Can I Do In Case Of Boot-Problem: ''perf-counter not enabled!'']]

=== Administration: Avoid 'reboot' Command. Use 'reset' Command ===
Alwas use the 'reset' command to restart an IPVA.
The 'reboot' command makes sense only on physical applicances, where its purpose is to deploy a new bootcode by means of a forced watchdog trap. The resulting post-reboot state will be as if an unsolicited trap/crash had occurred.

=== No Fault Tolerance Support from VMWare vSphere 6.5 ===
We have reports that VMWare vSphere 6.5 Fault Tolerance (FT) no longer works. For further information regarding this feature, please refer to the respective note in [[Howto:Implement_PBX_with_zero_downtime_using_IPVA_and_VMWare_Fault_Tolerance | Implement PBX with zero downtime using IPVA and VMWare Fault_Tolerance]].

=== Voice Quality Issues ===
When dealing with media streams (e.g. for announcements), the IPVA needs to fulfil real-time processing requirements, for example to process RTP packets in a timely fashion. To do so, the IPVA relies on the capabilities of the virtualization platform it runs on.

It is therefore important to configure the platform so that it supports real-time applications best. If you experience voice quality or latency issues, consider
* to make sure that all of the IPVAs memory is ''reserved'' to the IPVA (''Latency Sensitivity'' set to ''High'')
* to guarantee exclusive PCPU access
This helps to reduce CPU halt/wake-up states.

===Additional vCPUs may cause problems===
The Multi-Core functionality of version 13r2 is a beta functionality. Additional virtual CPUs(vCPUs) should not be utilized in production environments.

==FAQ==
===Can The Emulated CompactFlash Be Increased In Size?===
Yes, from within the ''Edit Virtual Machine'' dialog. Doing so just increases the size of the virtual harddisk. The emulated CompactFlash must be formatted afterwards and accordingly to benefit from the increased size. That step can be administrated from ''Administration/Compact Flash/Format''. Note: A recommendation for an upper size limit is not given.

'''vSphere / vSphere Client'''

1. At first backup all of your files from CF card 
2. Shutdown the corresponding IPVA 
3. Choose "Properties" of the IPVA 
4. Delete "Harddrive 2" (Hardrive file xxx/xxx_1.vmdk) 

hd-boot.vmdk > xxx.vmdk
hd-cf.vmdk > xxx_1.vmdk
hd-flash.vmdk > xxx_2.vmdk
hd-dump.vmdk > xxx_3.vmdk

5. Create new harddrive 
6. Configure the required size 
7. As "Node of virtual device" select "IDE(0:1)" 
8. Start the IPVA. 
9. "Format" the CF Card and "mount" it (General/Compact-Flash/General)

===What Is The Size Of the emulated Flash Storage on the IPVA?===
The virtual flash storage used to store configuration file of the IPVA and LDAP directory of the PBX is defined with 64 MB and can not be changed. This is two times more than on IP6010. The VMDK-File hd-flash.vmdk is allocated with 100 MB, because VMWare can not handle smaller virtual disks.

===What Is The Size Of the Flash Directory on the IPVA?===
As noted above, the virtual flash memory on the IPVA is fixed to a size of 64MB. Most of the flash is used by the ''flash directory'' (FLASHDIR0) which amongst other things provides storage for PBX objects.

The size of the flash directory depends on the available RAM. The maximum of 900 segments á 64KB, i.e. ~56MB, is available if 192MB or more RAM is available. If less RAM is available, the size of the flash directory is decreased accordingly. For this reason, it is unsafe to reduce RAM size in a given IPVA, as the flash directory size may be decreased so that objects from the flash directory get lost.

The easiest method to see how much flash directory space is available is to investigate the boot trace. For the standard configuration of 64MB the respective trace output is going to look as follows and informs about a size of 14MB:

<code type="text">
0:0000:081:4 - start flashdir FLASHDIR0
0:0000:081:4 - fdir: segments=901->224(14.0MB)
</code>

===How Much RAM Is Required Per IPVA Instance?===
Since 12r2sr27/13r1sr5 the downloadable virtual appliance comes preconfigured with 256MB RAM. This amount is seen as a good trade-off for the majority of all installations.
The RAM-size can be administrated by VMware-means.

The minimum RAM size allocatable to an IPVA in VMware is 20MB. This results in a DRAM size seen by the IPVA of 17MB and roughly 8MB allocatable runtime memory after boot. Note though that even a small IP302 model has 17MB allocatable runtime memory after boot.

===What Is The Maximum Amount Of RAM?===
The maximum meaningful RAM setting is 3GB. Memory space beyond that limit will be left unused. Assigning more than 3GB to an IPVA instance doesn't provide any benefit.

===Why Does ''General/Info/DRAM'' Show Less Than the Configured Memory?===
Not all of the configured memory is available to the IPVA. E.g. a bit of memory is occupied by the VMM<ref>Virtual Machine Monitor: A component belonging to the virtualization platform</ref>. The indicator ''General/Info/DRAM'' displays the memory available to the IPVA and is truncated down to a whole number. A boot-trace reveals a bit more about IPVA-available memory as shown in the following excerpt:
<pre>
...
0:0000:030:4 - Intel(R) Core(TM)2 Duo CPU E8400 @ 3.00GHz
0:0000:030:4 - mem(64946176)=61.93MB ...
</pre>

===How Many IPVA Instances Are Possible Per Host?===
There's no worst-case estimate available. For a best-case calculation,
*see [http://www.vmware.com/pdf/vsphere4/r41/vsp_41_config_max.pdf Configuration Maximums VMware vSphere 4.1]
*see [[#How_Much_RAM_Is_Required_Per_IPVA_Instance.3F | How Much RAM Is Required Per IPVA Instance?]]
Additional preformance reflections
*see [[HOWTO:A_rough_estimate_of_IPVA_Performance | A rough estimate of IPVA Performance]]

===How do I perform a factory reset?===

replace the 3rd disk, served on IDE 1:0, named hd-flash.vmdk with an empty disk:

[[Image:VM_Settings.png]]

1)download the IPVA and watch out for the file hd-flash.vmdk

2)Power-off the IPVA instance

3)Replace hd-flash.vmdk with the one downloaded in step 1). If on vsphere it may have been assigned a different name. Ensure it’s the one on IDE 1:0.

4)Power-on the IPVA instance

===What About VMware Tools?===
VMware Tools are not supported.

===What Is The Console Good For?===
The console is a remains of the early development phase. It resembles the IP3000's serial console. It doesn't offer any convenience like command history or backspace funtionality. Nevertheless may the console be of help in exceptional situations where e.g. the required DHCP server isn't available for 1st-time configuration or in situations where the ip configuration was misconfigured. Thereby any command from a device's config is acceptable.

For instance to configure the static IP address 1.2.3.4/24 on ETH0:
*Click into the console
*Press ENTER
*Enter credentials
*Enter
<pre>
config change IP0 ETH0 /addr 1.2.3.4 /mask 255.255.255.0
config change DHCP0 /mode off
config write
reset
</pre>
Since no backspace is offered it may become a daring task to enter a single line without typos. In case of a typo hit ENTER and input the same line again.
The keyboard layout is the US layout.
[[Image:Ip-via-console.png|center|thumb|200px|Console-edit of IP address]]

Display the IP configuration for ETH0:
<pre>
config show IP0 ETH0
</pre>

Display the DHCP configuration for ETH0:
<pre>
config show DHCP0
</pre>

Additional the DNS-server(s) and the default gateway can be configured:
<pre>
config change IP0 ETH0 /addr 1.2.3.4 /mask 255.255.255.0 /dns 8.8.8.8 /dns2 8.8.4.4
config change IP0 RT0 /gateway 1.2.3.254
config change DHCP0 /mode off
config write
reset
</pre>

Also some simple diagnostics (ping and traceroute) are possible via the console (output is given in the console):
<pre>
mod cmd PING0 tracert 8.8.8.8
mod cmd PING0 ping 8.8.8.8
</pre>

Resetting the entire FLASH space - '''Note, all configuration will get lost'''. this is similar method to the manufacturer reset method from above [[#How_do_I_perform_a_factory_reset.3F|How do I perform a factory reset?]]
<pre>
mod cmd FLASHMAN0 reset all
reset
</pre>

===What Can I Do In Case Of A Checksum Boot Error?===
This paragraph applies, if you experience the following start-up problem.

'''Symptom'''
*the IPVA doesn't start properly
*the console displays
<pre>
checksum wrong! Loading failed for image=IPVA BIN
</pre>
[[Image:ipva-crc-wrong.jpg|center|thumb|200px|Console displays CRC boot error]]

'''Solution'''
*Power-off the IPVA
*Replace the boot harddisk by a fresh one. The boot harddisk is the 1st hd(originally named ''hd-boot.vmdk'').

'''Remarks'''

This problem may occur on a system crash while a firmware update is taking place.

===What Can I Do In Case Of Boot-Problem: ''NIC unavailable!''===
This paragraph applies, if you experience the following start-up problem.

'''Symptom'''
*the IPVA doesn't start properly
*the console displays
<pre>
NIC unavailable!
</pre>
[[Image:ipva-nic-unavailable.jpg|center|thumb|200px|Console displays ''NIC unavailable!'']]

'''Solution'''
*Power-off the IPVA
*Administrate by VMware means: Ensure the correct/expected type of network interface controller(NIC) is going to be offered by the hypervisor.

The IPVA offers driver support for:
*AMD NIC: Am79C970A PCnet-PCI II Single-Chip Full-Duplex Ethernet Controller
**a.k.a ''PCNet32''
**a.k.a ''Vlance''

The AMD-NIC is kind of default. However, the NIC type may be overriden manually and accordingly within the configuration file ipva.vmx as follows
<pre>
ethernet0.virtualDev = "vlance"
</pre>

'''Remarks'''

This problem may occur after a VMware re-configuration of the network settings.

===What Can I Do In Case Of Boot-Problem: ''perf-counter not enabled!''===
This paragraph applies, if you experience the following start-up problem.

'''Symptom'''
*the IPVA doesn't start properly
*the console displays
<pre>
perfcounter-not enabled!!!
</pre>
[[Image:screenshot-ipva-perfcounter-nok.jpg|center|thumb|200px|Console displays ''perfcounter-not enabled!!!'']]

'''Solution''' 
This problem is likely caused by an OVA-import of the IPVA. The appliance's configuration file ''ipva.vmx'' requires a VMware proprietary configuration line that's not specifiable within an OVA-file.

The IPVA utilizes a VMware proprietary mechanism for its internal timekeeping<ref>Timekeeping in Virtual Machines http://www.vmware.com/pdf/vmware_timekeeping.pdf</ref>. That mechanism is only available after adding the following line to the configuration file ''ipva.vmx'':
<pre>
monitor_control.pseudo_perfctr = TRUE
</pre>
If that line is not present, the hypervisor is going to throw a CPU exception. Hint: In vSphere a VMX-file can be edited under '''Edit Settings/Options/Advanced/General/Configuration Parameters'''<ref>vmware Labs - How to edit vmx file in ESXi vSphere: https://www.youtube.com/watch?v=ICICoq-maB0</ref>

'''Remarks'''
*The vmx file should be edited after the installation of the IPVA.
*The vmx file should NOT be edited with Text editor (use vSphere as shown above)
*To our knowledge, a converter is always necessary for the installation with vmx.

===What Can I Do In Case Of Boot-Problem: ''Loading failed for image=IPVA BIN''===
This paragraph applies, if you experience the following start-up problem.

'''Symptom'''
*the IPVA doesn't start properly
*the console displays
<pre>
Loading failed for image=IPVA BIN
</pre>
[[Image:Ipva-fw-load-failed.png|center|thumb|200px|Console displays ''Loading failed for image=IPVA BIN'']]

'''Solution''' 
This problem is likely caused by a calculation fault within the boot-code.
*The solution requires a replacement of the boot disk hd-boot.vmdk.
**Download an IPVA package from on 11r2 sr22.
**Replace the 1st disk with the one from the downloaded package

===Are Additional vCPUs useful?===
The Multi-Core functionality of version 13r2 is a beta functionality. Additional virtual CPUs(vCPUs) should not be utilized in production environments.

===How To Replace The Boot Disk On vSphere?===
The recommended way is as follows:
*With ipva.ova deploy a fresh IPVA by means of '''File/Deploy OVF-Template...''' (de: '''Datei/OFV-Vorlage bereitstellen...''') and follow instructions.
**Its use to just serve as a copy source.
*Power-Off the old IPVA.
*In the old IPVA remove the 1st disk on IDE 0:0.
*From the new IPVA copy the 1st harddisk(on IDE 0:0) towards the old IPVA's directory.
*In the old IPVA add the 1st disk on IDE 0:0.
*In the old IPVA confirm and start the machine

===What do the counters mean under Interface/Ethx/Statistic?===
;rx-drop: Accumulates register CSR112 <ref>Command and Status Register</ref> of the emulated chip AM79C970. CSR112: Missed Frame Count. An increase of this value indicates the IPVA was not able to process the network frames fast enough.
;ifInDiscards: Sum of rx-drop, frames dropped due to interface link not up, unsupported ethernet type, internal receive queue full, drop frames of different vlan, drop non vlan frames if vlan is configured
;rx-frame-blocked: Unsupported IP protocol

==Notes==
<references/>

==Related Articles==
[[Reference10:Licenses]]

[[Howto:A_rough_estimate_of_IPVA_Performance | Howto:A_rough_estimate_of_IPVA_Performance]]

[[Category:Concept|Innovaphone Virtual Appliance]]