Skip to content


Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Importing existing profiles and comments

matthewdeutsch edited this page · 62 revisions
Clone this wiki locally

Loading any existing data from a legacy comment system (or user profile system) into our production environment consists of 3 steps:

  1. Provide a sample (up to 1000 records) of your conversation data and user profile data. Sample conversation data can be tested at
  2. Livefyre will perform a test import of the sample data in one of our integration environments.
  3. Any issues encountered in step #2 are resolved iteratively through collaboration of the customer and Livefyre integration teams.
  4. Livefyre will work closely with your team to plan a start time and approximate duration of the data load, and decide on the necessity of providing a "delta" (see #5).
  5. If necessary, an additional dump of the "delta" for conversation data will be created to capture comments/conversations that were added after the initial dump, but during the data load.

Notes on the format of the import files:

  • Each JSON record (Profile or Conversation) should not include any endlines, and each appears on a single line.
  • Each record is followed by a single endline, then the next record's JSON. This implies that the files themselves are not valid JSON, but each line of the file is a single valid JSON string.

Importing Comments Only (w/o User Profiles)

In some cases a customer may wish to import comment data, but not the user profiles that originally authored those comments. This might happen, for example, if you intend to create an entirely new profile system or if you are migrating from a closed user profile system. The sample conversation data JSON format below specifies fields that begin with imported_ which should be used in this case. Only imported_display_name is required. When using these fields, you should omit the author_id field.


If providing a delta, please include any parent comments from any comments referencing a parent_id from a previous import

Sample conversation data

  1. Conversation blobs each appear on a single line, should not include any literal endlines other than a single one at the end of each blob
  2. The top level id field should be unique to the content (URL) (is often a CMS's unique ID) and only appear in a single blob
  3. The file should be UTF-8 formatted, all urls must be fully qualified, and conversation and comment timestamps must be RFC-3339 compliant, with timezone info. Ex: "2010-07-05T23:07:15Z"
  4. Create separate files for each site being imported
  5. Special characters need to be unicode encoded. Ex: "\u0022" for “
  6. Decode all HTML entities for the article title field, user import_display_name field and user display_name field.
  7. Comment bodies only allow the tags/attributes listed below. Any other tags and/or attributes will not be processed.
VALID_TAGS = ['a','span','label','p','br','strong','em','u','blockquote','ul','li','ol','pre','body','b','i']

VALID_ATTRIBUTES = ['href', 'target']

Sample Conversation Data:

 "source": "", 
 "title": "Check out this sneezing panda!", // decode all html entities
 "created": "2010-07-05T23:07:15Z",
 "id": "3042469",

 "comments": [
/* this is a list of comments, in the order they were added to the conversation. the ordering of this list
will affect how livefyre displays comments (this list is ordered oldest first). */

             /************Comment with required fields**************/
               /* id - this is your system's internal comment identifier, 
                  which is used by the importer to relate children using their parent_id (see below) */
               "id": "99770519",
               "imported_display_name": "chris",  // name that will be displayed next to comment, required if no author_id
               "body_html": "<p>OMG I love how cute the video is!</p>", // only the tags listed in will be processed
               "created": "2010-07-05T23:01:15Z" // must include time zone

              /***********Comment with additional fields***************/
               "id": "99770520",
               "body_html": "<p>OMG I love how cute the video is!</p>",
               "created": "2010-07-05T23:01:15Z",

               /* author_id is used when a user profile has been imported from an external system */
               "author_id": "999999",
               "imported_display_name": "chris", // decode all html entities
               "imported_email": "", // not displayed publicly, but used for gravatars
               "imported_url": "", // the user's website for display purposes
               "parent_id": "99770519", // parent_id is optional, provide only if the comment is a reply
                                      // parent comments MUST appear before their children

               /* you may optionally include a list of user ids who have liked (aka "recommended") the comment */
               "likes": ["999998", "999990"]
  "tags": ["blog_post","news","sports"],
  "allow_comments": true /*set to false if you do not wish to allow new comments on the conversation */

Sample user profile data

/* ...notes...
1. profile blobs should not include any endlines, each should appear on a single line
2. each profile is followed by an endline, then an other profile blob
3. the file should be UTF-8 formatted
4. avatars must be imported using remote_profiles and ping to pull (

/***********Required fields****************/
 "display_name": "carolfoster", // what to display as the author of comments (decode all html entities)
 "id": "999999", // an internal identifier from the user auth system

/***********Optional but useful fields*****/
 "autofollow_conversations": false, // should posting a new comment by default cause the user to subscribe?
 "bio": "I like turtles", // brief user biography
 "email": "", 

 // required if email is included, notification settings are highly recommended even if you don't include an email
 "email_notifications": {"comments": "often", 
                         "likes": "immediately",
                         "replies": "immediately",
                         "moderator_comments": "never",
                         "moderator_flags": "never"},
 "location": "NYC, NY", // description of where the user is - city/state, etc. flexible string field.
 "name": {"first": "carol", "last": "foster"},
 "tags": ["subscriber", "power_user"], /* alphanumeric, underscores, 1-63 characters */
 "profile_url": "",
 "settings_url": "",
 "connections": [
        Optional section - identifies credentials for social network connections.
        Your existing social network connections can be leveraged without an additional "allow" dialog by sending tokens for the FB/Twitter session you have obtained on behalf of a user.
        The only required items below are the "provider" and "credentials" (expected data in "credentials" changes depending on which provider it is, see below for examples.)  Providing all the other details, if you have them, will prevent an extra trip to the provider by Livefyre to collect the additional data.  
        Within "profile", "preferredUsername" is optional and we"ll fall back to "displayName" if it is missing.  If neither are present, we"ll ping the provider for a username.
        "provider": "Twitter", 
        "uid": "16358683",
        "credentials": {"oauth_token_secret": "XXXXXXXXXXXXXXXXXXXXX", "type": "OAuth", "oauth_token": "XXXXXXXXXXXXXXXXXXXXX"},
        "profile": {"preferredUsername": "ballerinajen", "displayName": "jennifer c", "url": "", "photo": ""}
        "provider": "Facebook", 
        "uid": "1193610129", 
        "credentials": {"type": "Facebook", "accessToken": "XXXXXXXXXXXXXXXXXXXXX"},
        "profile": {"displayName": "ben goering", "url": "", "photo": ""}
Something went wrong with that request. Please try again.