Importing Comments

Skip to end of metadata
Go to start of metadata

Overview

A migration to the Gigya platform is performed by exporting data from your current system to a JSON file and sending it to Gigya to import. This guide will help you develop an export schema that will seamlessly import into our platform.

The native Gigya Comments import file format is a JSON file containing information for each category, stream, author, and comment. The information included about authors depends largely on whether the comments will be imported with associated users in the Gigya database or as guest comments.

In addition to our native JSON format, Gigya supports a number of export formats from other commercial vendors. Please contact Support via the Gigya Console to determine whether the vendor from which you are migrating is supported out of the box.

JSON Structure

In most cases, you may only have a single category. Categories are used primarily to distinguish between distinct settings for different streams or limit the scope of moderation for different moderators. If all of your streams will use the same settings and moderators, there is no reason to break them up into separate categories.

The settings object must be at the top of the file. It should be followed by categories, streams, userscomments, and votes (specifically in that order, though users may alternatively be listed before categories).

Parameters with empty values for any given object may be omitted. Separate each object (e.g. comment) by a line break. Lines breaks are not necessary between individual parameters within an object.

There is no limit to the file size, so all of your data can be in a single file.

Tying Comments to Users

In most cases, if the comment authors are users who registered on your site, you will want to tie their comments to their login identity. If the users already exist in the Gigya database or are being imported in a separate task, you only need to include the UID of the user as it exists in Gigya. For any user you have not already imported, you should include either firstName and lastName or a nickname so that it will be displayed as the person who commented. Otherwise the commentor will be displayed as “anonymous”. It is also important that you include email so that users logging in socially will be able to link to the existing UID.

Guest Comments

In the case where you do not have users records in the system to represent the comment authors, you can import them as guest comments. In this case, you must set guestName. You can also choose to set profileURL and photoURL, which will be used in the display of the comment.

Combining Comments and Ratings & Reviews

All Comments and Ratings & Reviews data for a single site should be included in a single file that can be imported in a single run. Please see the Gigya R&R; Import Guide for more information on the data structures and fields for R&R comments.

Object Fields

Please note that ALL parameters are CASE SENSITIVE, just like the Gigya API.

Settings

 

RequiredField NameTypeDescription
apiKeystringThe apiKey into which the content is to be imported.
importFormatstringThe format of the file you are providing. It should be gigya-comments-combined-json.
totalCategoriesintegerThe number of categories included in the file.
totalStreamsintegerThe number of streams included in the file.
totalUsersintegerThe number of new users to import in the file.
totalCommentsintegerThe number of comments included in the file.
totalVotesintegerThe number of votes included in the file.

 

Categories

 

RequiredField NameTypeDescription
categoryIDstringThe identifier of the comments category. Streams and comments within this category must contain a categoryID exactly matching an ID listed in the categories array.
operationModestringThe operation mode determines whether the category contains Comments or Ratings & Reviews.

 

Streams

 

RequiredField NameTypeDescription
categoryIDstringThe identifier of the comments category to which the stream of discussion belongs.
streamIDstringThe unique ID of the stream to which you would like to set information. Note: the string is limited to 150 characters and is case-sensitive.
streamTitlestringThe title assigned to the commenting stream. This title you assign here will be assigned to each comment posted to be used for RSS & HTML outputs.
streamURLstringThe stream URL assigned to the commenting stream (usually the URL of the page where the commenting stream is presented). This URL you assign will be assigned to each comment posted to be used for RSS & HTML outputs. This URL will link back from the RSS or HTML page to the original post where the comment was added.
Note: Gigya will verify that the streamURL belongs to your site (as configured for your API key in the Dashboard section on Gigya's website).
createDateintegerThe date the stream was created as a unix timestamp in milliseconds.
streamTagsstring or arrayEither a comma-separated list or an array of tags (strings) that should be associated with the stream. The tags you assign here will be assigned to each comment posted to be used for RSS and HTML outputs.
moderationModestringThe values accepted for the moderation mode are:
  • inherit - the stream will use the category moderation mode settings (this is the default if not set)
  • pre - all comments will be pending moderator approval
  • post - all comments will be approved automatically (per spamming & other auto moderation rules)
  • guest - all comments submitted by guests will remain hidden until moderation
readOnlybooleanDetermines whether the stream is read only or not. The default value is 'false', meaning not read only.
disabledbooleanDetermines whether the stream is disabled or enabled. The default value is 'false', meaning enabled.

 

Users

 

RequiredField NameTypeDescription
UIDstringThe unique ID of a logged-in user, with which this method call is associated. See User.UID for more information. If the user is not a guest (guestName parameter is not defined) this field is Required

Note: If you are using account linking then the UID would be your site user ID. To learn more about Social Login with account linking (best practice), please refer to the Login Implementation guide.

firstNamestringThe first name of the user who commented. This field is only necessary when the user does not already exist in the Gigya database, and you are not including nickname.
lastNamestringThe last name of the user who commented. This field is only necessary when the user does not already exist in the Gigya database, and you are not including nickname.
nicknamestringThe display name of the user who commented. This is shown as the commenter's name in place of firstName and lastName. This field is only necessary when the user does not already exist in the Gigya database, and you are not including firstName and lastName.
emailstringThe email of the user who commented. This field is only necessary when the user does not already exist in the Gigya database. If that is the case, it is necessary for account linking if the user subsequently logs in socially.
photoURLstringThe photo of the commenter.
profileURLstringThe profile URL of the commenter.

 

Comments

 

RequiredField NameTypeDescription
categoryIDstringThe identifier of the comments category to which the stream of discussion belongs.
streamIDstringThe unique ID of the stream to which you would like to set information. Note: the string is limited to 150 characters and is case-sensitive.
IDstringThe unique identifier for the comment.
commentTextstringThe content of the comment to post. The string may be maximum 5000 characters long.
UIDstringThe unique ID of a logged-in user, with which this method call is associated. See User.UID for more information. If the user is not a guest (guestName parameter is not defined) this field is Required

Note: If you are using account linking then the UID would be your site user ID. To learn more about Social Login with account linking (best practice), please refer to the Login Implementation guide.

guestNamestringGuest user name. This field is relevant if the user who posted this comment is a guest user, in which case this field is Required.
guestEmailstringGuest user email. This field is relevant if the user who posted this comment is a guest user.
parentIDstringThe identifier of the parent comment. In case this comment is a reply to another comment, this field is the ID of the comment to which this comment replies.
cidstringA string of maximum 100 characters length. This string is associated with each transaction and will later appear on reports generated by Gigya in the "Context ID" combo box. The cid allows you to associate the report information with your own internal data. For example, to identify a specific widget or page on your site/application. The "Context ID" combo box lets you filter the report data by site/application context.
tagsarrayThis parameter is a strings array representing a list of tags, e.g.: ["tag_a","tag_b"]. Each tag in the array is assigned to the posted comment. Tags can be used to filter comments when calling comments.getComments, to get only comments that match the tag.
statestringThe state of the comments for import. The optional values for this parameter are: 'approved' (default), 'pending', or 'rejected'.
createDateintegerThe date the comment was created as a unix timestamp in milliseconds.
ipstringThe IP address from which the comment was posted.
photoURLstringThe photo of the commenter.
profileURLstringThe profile URL of the commenter.

 

Votes

 

RequiredField NameTypeDescription
categoryIDstringThe category identifier to which the comment on which to vote belongs.
streamIDstringThe stream identifier to which the comment on which to vote belongs.
commentIDstringThe identifier of the comment on which to vote.
UIDstringThe unique ID of the user, with which this method call is associated. See User.UID for more information.
votestringThe vote on the comment. The vote value may be one of the following:
  • "pos" - a positive vote, in favor of the specified comment.
  • "neg" - a negative vote, opposite the specified comment.
  • "none" - no vote. This will undo a previous vote on the specified comment.

 

JSON Samples

The samples provided on the subsequent pages represent all of the possible fields. Please see above to identify which fields are required and which are optional. Your existing data may only represent a subset of the fields shown in the samples so long as the required fields are present.

Flat JSON

 

{
    "settings": {
        "apiKey": "<YOUR-­API-KEY>",
        "importFormat": "gigya-comments-­combined-json",
        "totalCategories": 1,
        "totalStreams": 2,
        "totalUsers": 3,
        "totalComments": 3,
        "totalVotes": 1 },
    "categories": [ {
        "categoryID": "Restaurants",
        "operationMode": "Comments" } ],
    "streams": [ {
        "streamID": "849273",
        "categoryID": "Restaurants",
        "streamTitle": "Siam Thai",
        "streamURL": "http://mysite.com/reviews/siam-­thai.html",
        "streamTags": ["thai","asian"],
        "moderationMode": "inherit",
        "status": "enabled",
        "createDate": 1297087491153 },
        {
        "streamID": "820742",
        "categoryID": "Restaurants",
        "streamTitle": "Corner Grill",
        "streamURL": "http://mysite.com/reviews/corner-­grill.html" } ],
    "users": [ {
    	"UID": "john.smith@commentor.com.127477523",
        "nickname": "johnsmith"
        } ],
    "comments": [ {
        "ID": "7812397",
        "streamID": "849273",
        "categoryID": "Restaurants",
        "UID": "john.smith@commentor.com.127477523",
        "commentText": "This was sooo yummy!",
        "state": "approved",
        "tags": ["mytags"],
        "createDate": 1297087491153 },
        {
        "ID": "7812399",
        "streamID": "849273",
        "categoryID": "Restaurants",
        "guestName": "Jason Smith",
        "guestEmail": "jason.smith@commentor.com",
        "photoURL": "http://sn.site/avatars/123.png",
        "profileURL": "http://sn.site/profile/123",
        "commentText": "It was pretty good and had great service",
        "createDate": 1297087491153 },
        {
        "ID": "7812284",
        "parentID": "7812397",
        "streamID": "849273",
        "categoryID": "Restaurants",
        "UID": "judy.smith@commentor.com.4812734",
        "commentText": "I totally agree!",
        "createDate": 1297087491153
        } ],
    "votes": [ {
        "commentID": "7812284",
        "streamID": "849273",
        "categoryID": "Restaurants",
        "UID": "judy.smith@commentor.com.4812734",
        "vote": "pos" } ]
}