Tutorial: Replicate the users from the PBX

In this tutorial you will learn how replicate the users data from the PBX to your app.

Conventions

The used file and class names in this example are based on a newly created App with the name NewApp1 and the company name innovaphone. Your filenames might be different according to your settings. To be able to replicate, the app needs to have access to PbxTableUsers and need the name of the PBX.

Testing and expected behaviour

For testing the app we need to have several users on the PBX. When editing an user, the changes should be relicated to your database. You could check if the users and the changes are been replicated to your app by checking your database using for example Putty. You can connect to your database with Putty setting as Host Name the IP address of your AP Platform, as Port the 22 and as Connection type SSH. Then you have to login using your admin credentials provided by the installer and connecting to your database using PostgreSQL commands.

Connecting to your database

psql -d databasename;

Reading your users table

select * from users;

Step by step

Task 1: Create your replicator object

On the constructor of your app instance, the replicator has to be declared. Here you can check the Replicator functions. After declaring the object, you can add fields to the replicator. There you can link the name of a data field from the PBX to a column from your database.

Include the replicator and tasks_postgresql header files.
Allow the AppInstance class to use JsonApiContext as base class and the UReplicator.
Declare the replicator object as public global variable from the app instance class on the header file.
Create a new object replicator using the IReplicator class on your app instance constructor.
Register your replicator object as a Json Api calling the function RegisterJsonApi.
Call the AddColumn function to start the synchronization of h323 field to your username column.
Do the same for the cn field and your cn column.
When an AppWebsocket connection is established, it needs to be added to the JsonApiContext.

Include the replicator and tasks_postgresql header file NewApp1.h

#include "common/interface/replication.h"
#include "common/lib/tasks_postgresql.h"

Include the replicator header file also on NewApp1-main.cpp

#include "common/interface/replication.h"

The AppInstance class needs to use JsonApiContext as base class and the UReplicator.

class NewApp1 : public AppInstance, ... , public UReplicator, public JsonApiContext

Declare the replicator object as public global variable from the app instance class on the header file.

class IReplicator * replicator;

Declaration of the replicator object

replicator = IReplicator::createReplicator(this, "PbxTableUsers", 0, 0, "domain", "pbx", database, "users", true, true);

After createReplicator has been called the interface has to be registered in the JsonApiContext

RegisterJsonApi(replicator);

Add h323 and cn fields to the replicator

replicator->AddColumn("h323", "username", ReplicationString, true);
replicator->AddColumn("cn", "cn", ReplicationString, true);

When an AppWebsocket connection is established, this AppWebsocket connection needs to be added to the JsonApiContext

class NewApp1Session : ..., public AppWebsocket, ... {
...
}
void NewApp1Session::AppWebsocketMessage(class json_io& msg, word base, const char* mt, const char* src)
{
...
    if (!strcmp(mt, "PbxInfo")) {
        class JsonApi * jsonApi = newapp1->CreateJsonApi("PbxTableUsers", this, msg, base);
        if (jsonApi) jsonApi->JsonApiStart();
    }
}

Task 2: Adding the callback functions for the replicator

Now we need to add the callback functions for the replicator.

Add the ReplicatorInitialized function.
Add the ReplicatorAdded function.
Add the ReplicatorDeleted function.
Add the ReplicatorDeletedConfirm function.
Add the ReplicatorDeletedConfirmComplete function.
Add the ReplicatorUpdated function.
Add the ReplicatorUpdate function.
Add the ReplicatorStopped function.
Add the ReplicatorStart function.

Include the functions on the header file NewApp1.h

void ReplicatorInitialized();
void ReplicatorAdded(ulong64 id);
void ReplicatorDeleted(ulong64 id);
void ReplicatorDeletedConfirm(ulong64 id);
void ReplicatorDeletedConfirmComplete(ulong64 id);
void ReplicatorUpdated(ulong64 id, ulong64 mask);
void ReplicatorUpdate(class json_io& msg, word base, bool initial);
void ReplicatorStopped();
void ReplicatorStart(class json_io& msg, word base, char*& tmp) override;

Add the ReplicatorInitialized function

void NewApp1::ReplicatorInitialized()
{
}

Add the ReplicatorAdded function

void NewApp1::ReplicatorAdded(ulong64 id)
{
}

Add the ReplicatorDeleted function

void NewApp1::ReplicatorDeleted(ulong64 id)
{
    replicator->DeletedConfirm(id);
}

Add the ReplicatorDeletedConfirm function

void NewApp1::ReplicatorDeletedConfirm(ulong64 id)
{
    currentTask = new TaskDeleteUser(this->database, id);
    currentTask->Start(&taskDeleteUser);
}

Add the ReplicatorDeletedConfirmComplete function

void NewApp1::ReplicatorDeletedConfirmComplete(ulong64 id)
{
}

Add the ReplicatorUpdated function

void NewApp1::ReplicatorUpdated(ulong64 id, ulong64 mask)
{
}

Add the ReplicatorUpdate function

void NewApp1::ReplicatorUpdate(class json_io & msg, word base, bool initial)
{
}

Add the ReplicatorStopped function

void NewApp1::ReplicatorStopped()
{
    delete replicator;
    replicator = 0;
    TryStop();
}

Add the ReplicatorStart function

void NewApp1::ReplicatorStart(class json_io & msg, word base, char * & tmp)
{
    word handle = msg.add_array(base, "pseudo");
    msg.add_string(handle, nullptr, "");
    msg.add_string(handle, nullptr, "executive");
}

Task 3: Add users table to your database

The table to save the replicated data from the PBX needs to be added. Here you can check the Database functions. You can also check this Database Tutorial about how to use the database.

Initialize the users table.
Add id, username and cn columns to the table.
Add a constraint to the username, which must be unique.
Add the Init callbacks to the NewApp1 class and the TaskDatabaseInit task.

Initialize the users table and add id, username and cn columns to the table.

AppTaskDatabaseInit::AppTaskDatabaseInit(IDatabase * database) :
initUsers(database, "users")
{
    this->database = database;
    initUsers.AddColumn("id", "BIGSERIAL PRIMARY KEY NOT NULL");
    initUsers.AddColumn("username", "VARCHAR");
    initUsers.AddColumn("cn", "VARCHAR");
    initUsers.AddConstraint("const_username", "UNIQUE (username)");
}
AppTaskDatabaseInit::~AppTaskDatabaseInit()
{
}
void AppTaskDatabaseInit::Start(class UTask * user)
{
    this->user = user;
    initUsers.Start(this);
}
void AppTaskDatabaseInit::TaskComplete(class ITask * const task)
{
    user->TaskComplete(this);
}
void AppTaskDatabaseInit::TaskFailed(class ITask * const task)
{
    user->TaskFailed(this);
}
void AppTaskDatabaseInit::DatabaseError(IDatabase * const database, db_error_t error)
{
    user->TaskFailed(this);
}
void AppTaskDatabaseInit::DatabaseExecSQLResult(IDatabase * const database, IDataSet * dataset)
{
    delete dataset;
    dataset = 0;
}

Add the Init callbacks to the NewApp1 class and the TaskDatabaseInit task to the header file NewApp1.h.

void DatabaseInitComplete(class TaskDatabaseInit * task);
void DatabaseInitFailed(class TaskDatabaseInit * task);
class UTaskTemplate<NewApp1, class TaskDatabaseInit> taskDatabaseInit;
class ITask * tableSetup;

And to the NewApp1.cpp file.

NewApp1::NewApp1(...) : 
AppInstance(service, args),
taskDatabaseInit(this, &NewApp1::DatabaseInitComplete, &NewApp1::DatabaseInitFailed)
{
    ...
void NewApp1::DatabaseInitComplete(class TaskDatabaseInit* task)
{
}

void NewApp1::DatabaseInitFailed(class TaskDatabaseInit* task)
{
	TryStop();
}
}

Task 4: Start the replicator

The table to save the replicated data from the PBX needs to be added. Here you can check the Database functions. You can also check this Database Tutorial about how to use the database.

When DatabaseConnectComplete is called the database can be initialized.
When DatabaseInitComplete is called the replicator must be started.
When the replicator has started, the webserverPlugin Listen functions can be called. The replicator->Update() function has to be called to set the PBX name.

When DatabaseConnectComplete is called the database can be initialized.

void NewApp1::DatabaseConnectComplete(IDatabase * const database)
{
    this->tableSetup = new AppTaskDatabaseInit(database);
    this->tableSetup->Start(&taskDatabaseInit);
}

When DatabaseInitComplete the replicator must be started.

void NewApp1::DatabaseInitComplete(class TaskDatabaseInit * task)
{
    replicator->Initialize("BIGINT REFERENCES users(id) ON DELETE CASCADE NOT NULL");
}

When the replicator has started, the webserverPlugin Listen functions can be called. The replicator->Update() function has to be called to set the PBX name.

void NewApp1::ReplicatorInitialized()
{
    this->webserverPlugin->HttpListen(0, 0, 0, 0, _BUILD_STRING_);
    this->webserverPlugin->WebsocketListen();
    replicator->Update(args.appDomain, pbxName);  
}

Task 5: Add and configure your App Object on the PBX

You need to configure for App Object on the PBX and give it access to the PbxTableUsers and the Websocket flags.

Open your App Platform Manager and when you click on edit your app instance you should see the URL of your app.
Add your App Object on the PBX and enter this URL on the URL field.
Select the TableUsers and Websokect checkmarks.

Open your App Platform Manager and when you click on edit your app instance you should see the URL of your app. It should be something like this:

http://XXX.XX.XXX.XXX/domain.com/newapp1/helloworld

Task 6: Add groups table to your database and replicate the groups data

The table to save the replicated data from the PBX needs to be added. Here you can check the Database functions. You can also check this Database Tutorial about how to use the database.

Add the groups table and the id, group_name, active, mode and dyn columns.
Add id, group_name, active, mode and dyn columns to the replicator.

Add the groups table and the id, group_name, active, mode and dyn columns.

AppTaskDatabaseInit::AppTaskDatabaseInit(IDatabase * database) :
initUsers(database, "users"),
initGroups(database, "groups")
{
    this->database = database;
    initUsers.AddColumn("id", "BIGSERIAL PRIMARY KEY NOT NULL");
    initUsers.AddColumn("guid", "UUID UNIQUE NOT NULL");
    initUsers.AddColumn("username", "VARCHAR");
    initUsers.AddColumn("cn", "VARCHAR");
    initGroups.AddColumn("id", "BIGSERIAL PRIMARY KEY NOT NULL");
    initGroups.AddColumn("group_name", "VARCHAR");
    initGroups.AddColumn("active", "BOOLEAN");
    initGroups.AddColumn("mode", "VARCHAR");
    initGroups.AddColumn("dyn", "VARCHAR");
    initGroups.AddColumn("user_id", "BIGINT REFERENCES users(id) ON DELETE CASCADE NOT NULL");
}
AppTaskDatabaseInit::~AppTaskDatabaseInit()
{
}
void AppTaskDatabaseInit::Start(class UTask * user)
{
    this->user = user;
    initUsers.Start(this);
}
void AppTaskDatabaseInit::TaskComplete(class ITask * const task)
{
    if (task == &initUsers) initGroups.Start(this);
    else if (task == &initGroups) user->TaskComplete(this);
    else user->TaskComplete(this);
}

Add id, group_name, active, mode and dyn columns to the replicator.

replicator = IReplicator::createReplicator(this, "PbxTableUsers", 0, 0, "domain", "pbx", database, "users", true, true);
RegisterJsonApi(replicator);
replicator->AddColumn("guid", "guid", ReplicationString, false);
replicator->AddColumn("h323", "username", ReplicationString, true);
replicator->AddColumn("cn", "cn", ReplicationString, true);
class IReplicatorArray * rArrayGroups = replicator->AddArray("grps", "groups", true, "user_id");
rArrayGroups->AddColumn("name", "group_name", ReplicationString, true);
rArrayGroups->AddColumn("mode", "mode", ReplicationString, true);
rArrayGroups->AddColumn("dyn", "dyn", ReplicationString, true);

Other considerations

The are functions that must be called when your database changes (when a user is added, updated or deleted):

newapp1->replicator->Added(id)	This must be called when a user is added on your database, so that the replicator will add it too.
newapp1->replicator->Updated(id)	This must be called when a user is updated on your database, so that the replicator will update it too.
newapp1->replicator->Deleted(id)	This must be called when you would like to delete a user from your database.

List of data fields that can be replicated

Table `users`

Table with the user data

ReplicationString	guid	Globally unique identifier
ReplicationString	h323	Username
ReplicationString	pwd	Password
ReplicationString	cn	Common name
ReplicationString	dn	Display name
ReplicationString	apps-my	List of the apps displayed on the home screen
ReplicationString	config	Config template
ReplicationString	node	Node
ReplicationString	loc	Location
ReplicationBool	hide	Hide from LDAP
ReplicationString	e164	Phone number
ReplicationTristate	cfpr	Call forward based on Presence
ReplicationTristate	t-cfpr	Call forward based on Presence inherited from the config template
ReplicationString	pseudo	Pseudo information of the object
ReplicationBool	h323-email	If true, the email is the username
ReplicationString	apps	List of the apps that the user has rights to access
ReplicationBool	fax	If true, the user has a fax license

Table `emails`

Table with the emails of the users

ReplicationString

email

Table `allows`

Table with the visibility filters defined for the user

ReplicationString	name	Filter name
ReplicationString	grp	If true, the name is a group name
ReplicationBool	visible	Visible
ReplicationBool	online	Online
ReplicationBool	presence	Presence
ReplicationBool	otf	On the phone
ReplicationBool	note	Presence note
ReplicationBool	dialog	Calls
ReplicationBool	ids	Calls with id

Table `t-allows`

Table with the visibility filters defined on the config templates

ReplicationString	name	Filter name
ReplicationString	grp	If true, the name is a group name
ReplicationBool	visible	Visible
ReplicationBool	online	Online
ReplicationBool	presence	Presence
ReplicationBool	otf	On the phone
ReplicationBool	note	Presence note
ReplicationBool	dialog	Calls
ReplicationBool	ids	Calls with id

Table `grps`

Table with the users groups

ReplicationString	name	Group name
ReplicationString	mode	Mode
ReplicationString	dyn	Dynamic

Table `devices`

Table with the users devices

ReplicationString	hw	Hardware ID
ReplicationString	text	Name
ReplicationString	app	App
ReplicationBool	admin	PBX Pwd
ReplicationBool	no-filter	No IP Filter
ReplicationBool	tls	TLS only
ReplicationBool	no-mob	No Mobility
ReplicationBool	trusted	Reverse Proxy
ReplicationBool	sreg	Single Reg.
ReplicationBool	mr	Media Relay
ReplicationString	voip	Config VOIP
ReplicationString	gk-id	Gatekeeper ID
ReplicationString	prim	Primary gatekeeper

Table `cds`

Table with the users call diversions

ReplicationString	type	Diversion type (cfu, cfb or cfnr)
ReplicationString	bool	Boolean object
ReplicationBool	bool-not	Not flag (boolean object)
ReplicationString	e164	Phone number
ReplicationString	h323	Username
ReplicationString	src	Filters data on XML format

Table `forks`

Table with the users forks

ReplicationString	e164	Phone number
ReplicationString	h323	Username
ReplicationString	bool	Boolean object
ReplicationBool	bool-not	Not flag (boolean object)
ReplicationString	mobility	Mobility object
ReplicationString	app	App
ReplicationUnsigned	delay	Delay
ReplicationString	hw	Device
ReplicationBool	off	Disable
ReplicationBool	cw	Call-Waiting
ReplicationUnsigned	min	Min-Alert
ReplicationUnsigned	max	Max-Alert

Tutorial: Replicate the users from the PBX

Conventions

Testing and expected behaviour

Connecting to your database

Reading your users table

Step by step

Task 1: Create your replicator object

Task 2: Adding the callback functions for the replicator

Task 3: Add users table to your database

Task 4: Start the replicator

Task 5: Add and configure your App Object on the PBX

Task 6: Add groups table to your database and replicate the groups data

Other considerations

List of data fields that can be replicated

Table users

Table emails

Table allows

Table t-allows

Table grps

Table devices

Table cds

Table forks

Useful documentation

Table `users`

Table `emails`

Table `allows`

Table `t-allows`

Table `grps`

Table `devices`

Table `cds`

Table `forks`