Creating Publications and Subscriptions Using the Web Admin Console

Pervasync enables you to synchronize distributed local databases with a central database without writing a single line of code. You start with a central DB with existing schemas and schema objects. The local DB should be initially empty. You use the web based admin console to publish central database objects and subscribe clients to the publications. Then on the client machine you use a shell script (pvc.sh or pvc.bat) to invoke the sync agent to initiate a sync session. The very first sync session will create the subscribed sync schemas and schema objects in local DB. The second sync will copy the central DB schema data to client schemas. After that, synchronization will be incremental – only changes on client and server will be exchanged.

Alternatively you can use the server and client side Java API to do publication, subscription and synchronization from your Java application.

You use the web based sync server admin console to publish sync objects and create subscriptions. Besides publications and subscriptions, the admin console is also used to monitor and control the sync servlet and sync engine, manage devices, users and groups.

Logging in to the Admin Console

Once the Pervasync web application is deployed in the J2EE servlet container, the admin console will be available at http://<server>:<port>/pervasync, e.g. http://localhost:8080/pervasync. The following is the login page.

Use the admin user name and password you specified when you setup the Pervasync server to login.

Admin Console Home

Once logged in, you will see the admin console home page.

The admin console allows you to check the status of the sync servlet and the sync engine as well as startup/shutdown them.

The Sync Engine helps preparing server side logical transactions to be used to refresh client side databases and folders to new states. Sync Servlet serves sync clients receiving transactions (Check-Ins) from clients and sending transactions to clients. You need to have both Sync Servlet and Sync Engine up for synchronization to work. However, when you are creating publications and subscriptions, it is better to temporally shutdown both.

The Publish and Subscribe Model

Pervasync employs a publish and subscribe model. You first define sync schemas and sync folders as publications. Then you subscribe sync clients or groups to a set of publications. Publications may have parameters defined. At subscription time, you supply values to the parameters to customize the subscription. For example, you may define “region” as a parameter of your publications. Then at subscription time, you assign a value to region for subscribers so that they get data related to a specific region.

Click on the Publications tab to show all available publications. There are two types of publications: sync schemas and sync folders. A sync schema is a container for database tables and other objects while a sync folder is a container for files.

Publishing Sync Schemas

A sync schema corresponds to a physical DB schema. You may create multiple sync schemas for a single DB schema. However, one table can only belong to one sync schema.

On the Publications page click on “Add Sync Schema” button under Sync Schemas header to add a schema.

Move mouse cursor over the fields for tooltips.

The No-Init-Sync Networks and No-Sync Networks fields are for the “sync based on network characteristics” feature. This enables you to automatically skip (initial or all) synchronization of a publication if certain network card is used (for reasons such as being too expensive or too slow etc.). If you do not need to use this feature, just keep the default value, which is “NONE”, unchanged.

To use “sync based on network characteristics” feature, first, you need to gather information about network characteristics of your client machines. After you setup Pervasync client, you can use the utility listnetworks.bat (or listnetworks.sh for Linux) in the bin folder of Pervasync client home to list the display names, hardware addresses and IP addresses of your network cards on client machines. Then, on Pervasync admin console, you need to change the value of the No-Init-Sync Networks and No-Sync Networks fields from the default value “NONE” into a value which contain matching strings that identify the network cards. You may use full strings or sub-strings of the following network card attributes: display name, hardware address and IP address. You may also have “&&” and/or “||” between the strings to indicate whether it’s “match all” or “match any” respectively. Here when you add new sync schema, you specify global values of the no-sync lists that apply to all user devices. At subscription time you have a chance to overwrite the values for a specific user device or group. For more information and explanation regarding “sync based on network characteristics” feature, refer to chapter 5, section 13, i.e., 5.13, “Sync Based on Network Characteristics”.

After the schema is created, you go back to the Publications page and click on the “Tables” link under “Schema Objects” to find the published tables of the schema.

Initially there is no sync table. Click on “Add Sync Table” to select a table and specify columns and rows to sync.

In the above screen shot, we selected table “employees” and chose to sync all columns and rows to clients that subscribe to the schema “schema_1”.

Note: Table names and column names cannot contain spaces. For example, table name “xxxx table” is not supported. We suggest you replace spaces with underscores. For example, use “xxxx_table” instead of “xxxx table”.

Rank is used to indicate the referential relationship among the sync tables. Parent tables should have a smaller rank number than child tables. When you insert new records, you would insert first to a parent table and then to a child table as the child table records reference columns in the parent table.

If “Allow Refresh” is checked, Pervasync server will refresh changes to the table to Pervasync clients. If “Allow CheckIn” is checked, sync clients can check in client changes to this table on server. “CheckIn SuperUsers” takes a comma-separated list of users who are allowed to check in even when “Allow CheckIn” is not checked.

Subsetting mode and query are used to identify the rows of the table to be synced to clients. Use subsetting query to specify the primary key query as row filters. The query should return the set of the primary key values of the selected rows. The query can have parameters enclosed in “${}”. The parameter values are set at subscription time.

Subsetting mode SIMPLE is different from COMPLEX in that a SIMPLE query can select from only one table, which could be the sync table itself or a different table.

“Query Referenced Tables” takes a comma-separated list of tables that are referenced in the subsetting query. This is only for subsetting mode COMPLEX.

Note: Subsetting is an advanced and complicated topic. If you are confused, you can leave all fields with default values. To further understand data subsetting, see section 5.3.1 A Step by Step Example of Data Subsetting and section 5.3.2 Subsetting Modes: SIMPLE and COMPLEX.

Publishing Sync Folders

If you need to sync files in a folder, you can achieve it by publishing sync folders, which is what this section is about. If you do not need to do this, you can skip this section.

On the Publications page click on “Add Sync Folder” button under “Sync Folders” header to add a folder for synchronization.

Move mouse cursor over the fields for tooltips.

Sync Folder Name: A unique name for the sync folder, e.g., “folder_1”.

Server Folder Path: The server side folder path, e.g., “c:\ server_folder”. If not starting with “/” or drive letter and “:”, it will be treated as relative to Pervasync server root folder.

 

Client Folder Path: The sync client side folder path, e.g., “c:\ client_folder”. It can have parameters to bind to values at subscription time. Parameters are enclosed by “${}”. If not starting with “/” or drive letter and “:”, it will be treated as relative to Pervasync client root folder. You can also have env variables in client folder path. These env variables should be enclosed in a pair of % signs. They will be substituted with env variable values on client side.

 

NOTE: Use % pairs instead of ${} for env variables regardless of whether your client machine is Windows or Linux.

 

Prefix Filters: Filters on file relative paths. All files in the server root folder have a relative path. For example, “c:\ server_folder\user_1\ images\file1.gif” has a relative path of “user_1\images\file1.gif”. The prefix filters apply to the file relative path. For example, if the value of prefix filter is set to “user_1\images\”, any file whose relative path starts with “user_1\images\” will be synced. Multiple filters can be supplied using comma as separator. A file would pass this “starts with” test if it passes any one of the prefix filters. However, a file has to pass both the “starts with” (Prefix Filter) and the “ends with” (Suffix Filter – see below) tests to be selected. It can have parameters to bind to values at subscription time. Parameters are enclosed by “${}”. If you do not need to use this, simply leave the field empty.

 

Suffix Filters: File filter by filename suffix or extension, which corresponds to what filename ends with. These are comma (“,”) separated file filters by file name suffix. For example: if “.gif,.jpeg,.png,.PNG,.doc” is set, any file whose name ends with “.gif” , “.jpeg”, “.png”, “.PNG”, or “.doc” will be synced. If you do not need to use this, simply leave the field empty.

 

Check In Super Users: Comma (“,”) separated list of users who are allowed to check in even when “Allow Check In” is set to false. If you do not need to use this, simply leave the field empty.

 

No-Init-Sync Networks: Refer to last section (Publishing Sync Schemas) for explanations.

No-Sync Networks: Refer to last section (Publishing Sync Schemas) for explanations.

You can publish a server folder by specifying its path. The folder will be synced to client machine. The client folder name does not have to be the same as the server’s. You can even put parameters in the client folder path so that different clients could have a different folder. Parameters should be enclosed in ${}, just as in table subsetting query. These parameters should be assigned a value at subscription time.

Once a folder is published, you can associate it with one or more clients by creating a folder subscription.

Managing Groups

Publications can be subscribed in two ways. One is direct subscription by sync clients on user devices (See section 5.1.7 and 5.1.8); the other is indirect subscription through groups. In this section, we are going to discuss the latter, i.e., managing groups.

Very often you have a group of clients that share the same set of publications and even subscription parameters. In this case it is more convenient to create groups and group subscriptions first and then add/remove clients to/from the groups. Clients will inherit group subscriptions.

You can choose either indirect or direct subscription based on your situation. If you do not need to manage groups, you can skip this section and go ahead to read section 5.1.7 and 5.1.8 for direct subscription by sync clients.

Click on Groups tab to view existing groups.

When you delete a group, you have an option to keep the group members (sync clients). The clients’ group will be set to NULL if you choose “Delete Group Only”.

Initially you may not have any groups. Click on “Add Client Group” to add one.

Go back to Groups page, find the group and click on button “Subscriptions”.

The Group Subscriptions page lists all the available publications, subscribed or not. Subscribed publications (including sync schemas and sync folders) have their name bold-typed and you can select and un-subscribe them. For publications that are currently not subscribed, you can click on the “Add” button to add them to the group’s subscriptions.

Before you click the Add button, fill in the values for the parameters to customize the subscription. These values will be shared by all clients that will later be added to this group.

Refer to section 5.1.4 Publishing Sync Schemas for explanations of fields “No-Init-Sync Networks” and No-Sync Networks”. Note that you can set the no-sync list values at three levels: publication, group subscription and client subscription. Publication level values are inherited and can be overridden by group subscription values, which in turn are inherited and can be overridden by client subscription values.

Similarly, you can add sync folder publications to a group subscription.

If you un-subscribe a group from a publication, all clients that belong to the group would lose the subscription.

In the following we will create a user-device (client) and do the subscription.

Managing Sync Clients

Click on the “Clients” tab.

Initially you may not have any sync clients. Click on “Add New Sync Client”.

Here we create user “john.doe” and add device “DEFAULT”. We put in a password and check “Create User” to create the user in Pervasync repository. Alternatively, you could choose to manage users and their passwords yourself. See javadoc for interface pervasync.server.UserManager for details. In that case you need and only need to specify User Name and Device name to add the sync client.

When you create a client you can assign it to a group.

Creating Subscriptions

Click on “Subscriptions” button on the row of the sync client on the Clients page.

If you have assigned a group for the client, you would see the client has all the group subscriptions. Click on Update (or Add if not subscribed) button on the row of the publication.

A subscription is an association of a client with a publication, in our case, user john.doe’s DEFAULT device and schema “schema1”. Edit the parameter values if needed and click button “Update” to update the client subscription.

Once you have successfully created publications, user-devices and subscriptions using the web admin console, you are ready to execute synchronizations using a sync client as described in 5.2.

Checking Client Sync History

On the admin console Home click on link “Sync Session History” under section “Sync Servlet”. This page is useful for admin to identify client sync issues in the field and track user synchronization trends.

The “Clients” page also shows each client’s last sync status and provides a link to sync history for a specific client.

Advertisements

2 thoughts on “Creating Publications and Subscriptions Using the Web Admin Console

  1. Can you please tell me how I can get around with the following problem.
    I have added a new user to the system. So data point of view only 1 table is changed. But there are tables which are based on this data change and the subscriptions are also created based on that. But data in any of the other tables are syncing unless I manually update the subscriptions for all these tables again. What is the right way to do this? How do I trigger a sync of related tables when data changes

    • Search for “Query Referenced Tables” in the documentation.

      When you publish the tables whose subsetting depends on other tables(s), nake the subsetting mode “Complex” and put the referenced tables in “Query Referenced Tables”. Then when the referenced tables are changed, the depending table will also be synced.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s