fh-wfm-sync
Advanced tools
A sync module for FeedHenry WFM providing :
This module makes uses the $fh.sync Client and $fh.sync Cloud APIs to provide the data synchronisation functionality.
Version 1.x of this module requires fh-mbaas-api 7.x.
Version 0.x of this module supports older versions of fh-mbaas-api.
This module is packaged in a CommonJS format, exporting the name of the Angular namespace. The module can be included in an angular.js as follows:
angular.module('app', [require('fh-wfm-sync')], function(syncService){
// ...
});
The sync service must first be initialized using the syncService.init(). Generally, the syncService will be injected into another Angular service (or in a config block) :
.factory('workorderSync', function($q, $timeout, syncService) {
syncService.init($fh, config.syncOptions);
});
Once initialized the syncService can manage multiple datasets using the following function:
var config = {
...
datasetId: "workorders"
...
};
var queryParams = {
//Optional object passed with dataset sync requests.
};
syncService.manage(config.datasetId, null, queryParams);
Each of the topics takes an object as a parameter. The topicUid parameter is an optional parameter used to allow the unique identifier to be appended to the done and error topics published.
This allows for the scenario where a developer wishes to limit the response of the topic.
E.g
//Generate a random number / string
var topicUid = Math.floor(Math.random() * 100000000);
//Subscribing to the done state for the list topic.
//The topicUid is appended to limit the response of the wfm:sync:datasetid:list topic to this subscriber
mediator.subscribe("done:wfm:sync:datasetid:list:" + topicUid, function(arrayOfItems) {
...
handleListSuccess(arrayOfItems);
...
});
//Subscribing to the error state for the list topic.
//The topicUid is appended to limit the response of the wfm:sync:datasetid:list topic to this subscriber
mediator.subscribe("error:wfm:sync:datasetid:list:" + topicUid, function(error) {
handleError(error);
});
mediator.publish("wfm:sync:datasetid:list", {
topicUid: topicUid
});
Developers may also wish to not include the topicUid parameter. This will mean that the done and error topics will not have any unique identifiers appended.
This is useful if the developer wishes to have global subscribers to the topics. E.g. a global subscriber to the done:wfm:sync:list topic that handles the completion of the list topic.
The syncService.manage function automatically subscribes to the following topics for a dataset. For a dataset with an ID datasetid, the following topics are published:
Creating a new item in the dataset.
var parameters = {
itemToCreate: {
//A Valid JSON Object
},
//Optional topic unique identifier.
topicUid: "uniquetopicid"
}
mediator.publish("wfm:sync:datasetid:create", parameters);
Updating an existing item in the dataset.
var datasetItemToUpdate = {
...
...
}
var parameters = {
itemToUpdate: {
//A Valid JSON Object
},
//Optional topic unique identifier.
topicUid: "uniquetopicid"
};
mediator.publish("wfm:sync:datasetid:update", parameters);
Removing a single item from the dataset.
var parameters = {
id: "idofdataitemtoremove",
//Optional topic unique identifier.
topicUid: "uniquetopicid"
};
mediator.publish("wfm:sync:datasetid:remove", parameters);
Listing all of the items in the dataset.
var parameters = {
//Optional topic unique identifier.
topicUid: "uniquetopicid"
};
mediator.publish("wfm:sync:datasetid:list", parameters);
Start the synchronisation process from client to cloud for this dataset.
var parameters = {
//Optional topic unique identifier.
topicUid: "uniquetopicid"
};
mediator.publish("wfm:sync:datasetid:start", parameters);
Stop the synchronisation process from client to cloud for this dataset.
var parameters = {
//Optional topic unique identifier.
topicUid: "uniquetopicid"
};
mediator.publish("wfm:sync:datasetid:stop", parameters);
Force the synchronisation of client and cloud data for this dataset.
var parameters = {
//Optional topic unique identifier.
topicUid: "uniquetopicid"
};
mediator.publish("wfm:sync:datasetid:force_sync", parameters);
The following topics are published by the module for each dataset.
Each of the topics will have the topicUid parameter appended to the topic if it is passed as a parameter when published.
See the Topic Unique Identifiers section for more details.
The item was created for a dataset with id datasetid.
mediator.subscribe("done:wfm:sync:datasetid:create", function(createdItem) {
...
/**
*
* createdItem = {
...
//A unique ID assigned to the data item created
* _localuid: "localid"
...
* }
*
*/
...
});
An error occurred when creating an item.
mediator.subscribe("error:wfm:sync:datasetid:create", function(error) {
...
console.log(error.message);
...
});
An item for the dataset with ID datasetid was updated.
mediator.subscribe("done:wfm:sync:datasetid:update", function(updatedItem) {
...
/**
*
* updatedItem = {
* ...
* ...
* }
*
*/
...
});
An error occurred when updating an item for the dataset with ID datasetid.
mediator.subscribe("error:wfm:sync:datasetid:update", function(error) {
...
console.log(error.message);
...
});
An item was removed from the dataset.
mediator.subscribe("done:wfm:sync:datasetid:remove", function() {
...
...
});
An error occurred when removing an item from the dataset.
mediator.subscribe("error:wfm:sync:datasetid:remove:datasetitemid", function(error) {
...
console.log(error.message);
...
});
A list of items for a dataset with ID datasetid completed successfully.
mediator.subscribe("done:wfm:sync:datasetid:list", function(listOfItems) {
...
/**
*
* listOfItems = [{
* ...
* ...
* }, {
* ...
* ...
* }]
*
*/
...
});
An error occurred when listing items for a dataset with ID datasetid
mediator.subscribe("error:wfm:sync:datasetid:list", function(error) {
...
console.log(error.message);
...
});
The client-cloud sync process for a dataset with ID datasetid started successfully.
mediator.subscribe("done:wfm:sync:datasetid:start", function() {
...
...
});
An error occurred when starting the client cloud sync process for a dataset with ID datasetid
mediator.subscribe("error:wfm:sync:datasetid:start", function(error) {
...
console.log(error.message);
...
});
The client-cloud sync process for a dataset with ID datasetid stopped successfully.
mediator.subscribe("done:wfm:sync:datasetid:stop", function() {
...
...
});
An error occurred when stopping the client cloud sync process for a dataset with ID datasetid
mediator.subscribe("error:wfm:sync:datasetid:stop", function(error) {
...
console.log(error.message);
...
});
The module publishes topics covering all of the notification codes available to the $fh.sync Client API.
The list of notification codes published are:
| Topic | Description |
|---|---|
| wfm:sync:datasetid:client_storage_failed | Loading or saving to client storage failed. This is a critical error and the Sync Client will not work properly without client storage. |
| wfm:sync:datasetid:sync_started | A synchronization cycle with the server has been started. |
| wfm:sync:datasetid:sync_complete | A synchronization cycle with the server has been completed. |
| wfm:sync:datasetid:offline_update | An attempt was made to update or delete a record while offline. |
| wfm:sync:datasetid:collision_detected | Update failed due to data collision. |
| wfm:sync:datasetid:remote_update_failed | Update failed for a reason other than data collision. |
| wfm:sync:datasetid:remote_update_applied | An update was applied to the remote data store. |
| wfm:sync:datasetid:local_update_applied | An update was applied to the local data store. |
| wfm:sync:datasetid:delta_received | A change was received from the remote data store for the dataset. |
| wfm:sync:datasetid:sync_failed | Synchronization loop failed to complete. |
Each of these topics will be published with an object describing the event:
{
//The dataset that the notification is associated with
dataset_id: "workorders",
// The unique identifier that the notification is associated with.
// This will be the unique identifier for a record if the notification is related to an individual record,
// or the current hash of the dataset if the notification is associated with a full dataset
// (for example, sync_complete)
uid: "workorder1234",
// Optional free text message with additional information
message: "A remote update failed for this data set"
// The notification message code (See above)
code: "remote_update_failed"
}
The server-side component of this WFM module exports a function that takes express and mediator instances as parameters, as in:
var sync = require('fh-wfm-sync/lib/server');
var config = require('../config');
module.exports = function(mediator, app, mbaasApi) {
sync.init(mediator, mbaasApi, config.datasetId, config.syncOptions);
};
Check a complete example here
{
datasetId : 'workorders',
syncOptions : {
"syncFrequency": 5,
"sync_frequency" : 5,
"storage_strategy": "dom",
"do_console_log": false
}
}
Sync frequency is set individually for the client and the server.
sync_frequency.syncFrequency.It is recommended that these settings share the same value.
A custom data collision handler can be used by the sync module by assigning your own custom collision handler function to the sync config options syncOptions.dataCollisionHandler property. This may be configured like the example below:
var syncOptions = config.syncOptions;
syncOptions.dataCollisionHandler = function() {
//Custom data collision handler
};
sync.init(mediator, mbaasApi, config.datasetId, syncOptions);
Check a complete example here
For further information about sync data collision handlers, please refer to the $fh.sync documentation
FAQs
An sync module for WFM
We found that fh-wfm-sync demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 6 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
A Stanford study reveals 9.5% of engineers contribute almost nothing, costing tech $90B annually, with remote work fueling the rise of "ghost engineers."
Research
Security News
Socket’s threat research team has detected six malicious npm packages typosquatting popular libraries to insert SSH backdoors.
Security News
MITRE's 2024 CWE Top 25 highlights critical software vulnerabilities like XSS, SQL Injection, and CSRF, reflecting shifts due to a refined ranking methodology.