Manual synchronization of selected records

Overview:

Sync 2.0 module exposes methods for manual synchronization of records in any chosen category. The category has to be defined in the Atomfeed configuration. See Atomfeed for Sync 2.0 for more details. This feature allows creating custom widgets for manual synchronization of data only in a specific category. 

Usage:

Desired methods can be found in SyncPushService and SyncPullService classes. All you have to do is to execute pullAndSaveObjectsFromParent or readAndPushObjectsToParent method, with the category as a parameter.

It is also possible to execute readAndPushObjectToParent or pullAndSaveObjectFromParent method, where category is one of the parameters but entity uuid is also specified. Using those methods will push/pull only the object of this category with provided uuid.

Example of use:

There are several ways of using the methods in other modules. Below you can find one of them, but if you're familiar with UI fragments, you can customize it to fit your needs. The provided example will allow you to add a simple button that executes the push/pull method.

Adding dependency on sync2-api module:

At first, you need to add a dependency on sync2-api module, if your module doesn't have it yet. To do that, add simple maven dependency in the pom.xml file:

<dependency>
	<groupId>org.openmrs.module</groupId>
	<artifactId>sync2-api</artifactId>
	<version>${sync2Version}</version>
</dependency>

and require the module in config.xml file:

<require_module version="${sync2Version}">
	org.openmrs.module.sync2
</require_module>

Creating a fragment to be displayed on the UI:

Create a new .js file in ../webapp/resources/scripts package, and a new java controller in ../fragment/controller/. The controller name must have FragmentController postfix.

In the java controller, you should add a method, that'll connect with SyncService and execute push/pull. You'll need to provide an atomfeed category of the objects to sync, so you can add @RequestParam("category") String category as a method parameter. Additionally, you'll need SyncPushService instance, so the best way is to add @SpringBean("sync2.syncPushService") SyncPushService syncPushService (or syncPullService) as a method parameter, and add an @Controller annotation above the class.

If you want to push objects to the parent execute syncPushService.readAndPushObjectsToParent(category) method. If you want to pull them, use syncPullService.pullAndSaveObjectsFromParent(category).

Finally, your controller should look like:

package org.openmrs.module.coreapps.fragment.controller;

import org.openmrs.Patient;
import org.openmrs.api.context.Context;
import org.openmrs.module.sync2.api.service.SyncPushService;
import org.openmrs.ui.framework.UiUtils;
import org.openmrs.ui.framework.annotation.FragmentParam;
import org.openmrs.ui.framework.annotation.SpringBean;
import org.openmrs.ui.framework.fragment.FragmentModel;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.RequestParam;

import javax.servlet.http.HttpSession;

@Controller
public class ManualSyncFragmentController {

	public void push(@RequestParam("category") String category, @SpringBean("sync2.syncPushService") SyncPushService syncPushService) {
		syncPushService.readAndPushObjectsToParent(category);
	}
}

Next, add following method, to the js file, where 'manualSync' is the name of your controller (without postfix), and 'push' is the name of your method:

function manualPush(category) {
	jq.post('/' + OPENMRS_CONTEXT_PATH + '/coreapps/manualSync/push.action', {category: category});
}

The last part is to add a place to execute the method on the UI, for example in some existing fragment. To do it, add reference to your js file:

<% ui.includeJavascript("coreapps", "manualSyncWidget.js") %>

And link the method, for example to the button:

<button type="button" class="confirm" onclick="manualPush('patient')"></button>

And that's it. Compile the module, deploy it, and you should be able to push/pull objects of specified category from the parent instance.