npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

fh-wfm-sync

v1.0.2-sync2.0

Published

An sync module for WFM

Downloads

46

Readme

FeedHenry WFM sync

A sync module for FeedHenry WFM providing :

  • A Server-side sync module
  • A Front-end (Angular Service) sync module

This module makes uses the $fh.sync Client and $fh.sync Cloud APIs to provide the data synchronisation functionality.

Notice

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.

Client-side usage

Setup

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){
// ...
});

Integration

Angular service

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);
});
Managing Datasets

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);

Topic Unique Identifiers

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.

Dataset Topic Subscriptions

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:

wfm:sync:datasetid:create

Description

Creating a new item in the dataset.

Example
var parameters = {
  itemToCreate: {
    //A Valid JSON Object
  },
  //Optional topic unique identifier.
  topicUid: "uniquetopicid"
}

mediator.publish("wfm:sync:datasetid:create", parameters);

wfm:sync:datasetid:update

Description

Updating an existing item in the dataset.

Example
var datasetItemToUpdate = {
  ...
  ...
}

var parameters = {
  itemToUpdate: {
    //A Valid JSON Object
  },
  //Optional topic unique identifier.
  topicUid: "uniquetopicid"
};

mediator.publish("wfm:sync:datasetid:update", parameters);

wfm:sync:datasetid:remove

Description

Removing a single item from the dataset.

Example

var parameters = {
  id: "idofdataitemtoremove",
  //Optional topic unique identifier.
  topicUid: "uniquetopicid"
};

mediator.publish("wfm:sync:datasetid:remove", parameters);

wfm:sync:datasetid:list

Description

Listing all of the items in the dataset.

Example

var parameters = {
  //Optional topic unique identifier.
  topicUid: "uniquetopicid"
};

mediator.publish("wfm:sync:datasetid:list", parameters);

wfm:sync:datasetid:start

Description

Start the synchronisation process from client to cloud for this dataset.

Example
var parameters = {
  //Optional topic unique identifier.
  topicUid: "uniquetopicid"
};

mediator.publish("wfm:sync:datasetid:start", parameters);

wfm:sync:datasetid:stop

Description

Stop the synchronisation process from client to cloud for this dataset.

Example
var parameters = {
  //Optional topic unique identifier.
  topicUid: "uniquetopicid"
};

mediator.publish("wfm:sync:datasetid:stop", parameters);

wfm:sync:datasetid:force_sync

Description

Force the synchronisation of client and cloud data for this dataset.

Example
var parameters = {
  //Optional topic unique identifier.
  topicUid: "uniquetopicid"
};

mediator.publish("wfm:sync:datasetid:force_sync", parameters);

Dataset Published Topics

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.

done:wfm:sync:datasetid:create

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"
       ...
  *  }
  *
  */
  ...
});
 

error:wfm:sync:datasetid:create

An error occurred when creating an item.


mediator.subscribe("error:wfm:sync:datasetid:create", function(error) {
  ...
  
  console.log(error.message);
  ...
});
 

done:wfm:sync:datasetid:update

An item for the dataset with ID datasetid was updated.


mediator.subscribe("done:wfm:sync:datasetid:update", function(updatedItem) {
  ...
  /**
  *
  *  updatedItem = {
  *    ...
  *    ...
  *  }
  *
  */
  ...
});
 

error:wfm:sync:datasetid:update

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);
  ...
});
 

done:wfm:sync:datasetid:remove

An item was removed from the dataset.


mediator.subscribe("done:wfm:sync:datasetid:remove", function() {
  ...
  
  ...
});
 

error:wfm:sync:datasetid:remove

An error occurred when removing an item from the dataset.


mediator.subscribe("error:wfm:sync:datasetid:remove:datasetitemid", function(error) {
  ...
  
  console.log(error.message);
  ...
});
 

done:wfm:sync:datasetid:list

A list of items for a dataset with ID datasetid completed successfully.


mediator.subscribe("done:wfm:sync:datasetid:list", function(listOfItems) {
  ...
  /**
  *
  *  listOfItems = [{
  *    ...
  *    ...
  *  }, {
  *     ...
  *     ...
  *   }]
  *
  */
  ...
});
 

error:wfm:sync:datasetid:list

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);
  ...
});
 

done:wfm:sync:datasetid:start

The client-cloud sync process for a dataset with ID datasetid started successfully.


mediator.subscribe("done:wfm:sync:datasetid:start", function() {
  ...
  ...
});
 

error:wfm:sync:datasetid:start

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);
  ...
});
 

done:wfm:sync:datasetid:stop

The client-cloud sync process for a dataset with ID datasetid stopped successfully.


mediator.subscribe("done:wfm:sync:datasetid:stop", function() {
  ...
  ...
});
 

error:wfm:sync:datasetid:stop

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);
  ...
});
 

Notification Topics

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. |

Topic Parameters

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"
}

Usage in an express backend

Setup

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);
};

Sync config options

Check a complete example here

{
  datasetId : 'workorders',
  syncOptions : {
    "syncFrequency": 5,
    "sync_frequency" : 5,
    "storage_strategy": "dom",
    "do_console_log": false
  }
}
Sync frequencies

Sync frequency is set individually for the client and the server.

  • On the client the setting is named sync_frequency.
  • On the server the setting is named syncFrequency.

It is recommended that these settings share the same value.

Custom data collision handler setup

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