RaaS Import Guide

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 RaaS import file format is a JSON file containing information for each account and associated social identities. The content of each user record depends largely on what data you currently have and whether you already have support for Social Login on your site.

In addition to our native JSON format, Gigya supports a number of export formats from other commercial vendors. Please check with your Implementation Consultant to determine whether the vendor from which you are migrating is supported out of the box.

 

Password Formats

We accept numerous password formats including md5, bcrypt, sha1, sha256, and pbkdf2, among others. In some cases, compoundHash should be used. In others, a combination of hash and algorithm and other fields are necessary. Please work with your Implementation Consultant to confirm the appropriate fields for your specific password structure.

Note: You are required to include either compoundHash or some combination of hash and the password related parameters.

 

Required Schema Fields

All fields that are required in your schema should be included in the import file. If a user is missing any of the required fields, their account registration will stay in a pending state and they will be asked to complete the required fields the next time they log in through the Registration Completion flow.

Note: All required fields must be included in your registration completion screen-set or users missing required fields will not be able to complete their registrations.

 

Dynamic Schema

By default, the data schema is dynamic and will automatically create fields that do not exist if there is a new data set on a record. If the field has not already been created, the data type of the field will be automatically derived from the first value being set. Once a field contains data, its type may not be changed. Therefore, it is very important that the data type set on the schema and the type in your import file match and are the desired type. Specific examples to watch out for are boolean values, which should be set as true and false (without quotes), and not "true" or "false", which are strings, or 0 or 1, which are integers.

The importer will automatically create a string field called data.gigyaImportJob, which contains the ID of the job to identify when a record was imported or last modified by an importer. If you wish to turn dynamicSchema off by setting it to false on the datasSchema, please be sure to add this field (as a string data type) to your dataSchema.

Site Data vs. Social Data

It is important to note that Site Data overrides Social Data when Gigya is merging field values into the profile. Therefore, you should only include fields in the Site Identity that have been previously entered as site fields by the user. Otherwise, if a value was originally collected from a Social Identity and the user later changes it in their social profile, the updated value will not be reflected in their Gigya profile.

In order to retain the links between social accounts and site accounts, you should provide us with the providerUIDs from each provider mapping to a siteUID. When the user logs in socially, we will then be able to automatically link them to their site profile. Pre-mapping the providerUIDs to siteUIDs is a better user experience because it avoids asking the user to re-link their accounts when they log in socially.

Profile Photos

In order for Gigya to recognize which photos need to be imported, we ask that you include a profilePhotoDomains value in the settings hash of the import file. This will enable us to recognize which photoURLs should be imported into our system, versus left in their original location.

If your profile photos are currently hosted in multiple locations, you should include a comma-separated list of domains. If we should import all photos regardless of domain, you may set it to “*”. If the field is left blank, we will not import any photos.

For the best quality and flexibility, we recommend you include a URL to the original file size and let Gigya create re-sized versions. The supported photo file types are: gif, png, and jpg.

Object Fields

Please note that ALL parameters are CASE SENSITIVE, just like the Gigya API. You need only include parameters for fields that have values on a particular record. Data schema fields that are nodes to arrays or objects may not be set to "null", only empty arrays [ ] or objects { } should be passed. Booleans and numbers should not be enclosed in quotes. It should be noted that if you are performing a delta update import, then fields without data should not be passed as empty or they may overwrite (delete) existing data.

 

Accounts

 

RequiredField NameTypeDescription
UIDstringA unique identifier used by your site to identify the user. You may use the user's account ID that you have designated for this user in your database. The parameter accepts only ASCII characters (not Unicode) and can contain up to 252 characters. The UID is case-sensitive. See User.UID for more information.
username *stringA string that the user enters to identify his account. Can be a simple username string, but should not be an email address. Email addresses should be stored in the email field instead.
email *stringThe account's user's email address.
 *You are required to pass username and/or email, depending on your site's Login Identifier policy.
securityQuestionstringThe secret question that can be used for email verification. This parameter is required if specified so in the site's requireSecurityQuestion Policy.
securityAnswerstringThe answer to the secret question. This parameter is required if specified so in the site's requireSecurityQuestion Policy .
langstringThe language to use in error messages and validation emails. See also Email Templates.
skipVerificationBooleanIf set to true, this API call skips email verification. The default value is false.
finalizeRegistrationBooleanIf set to true, this API call will also finalize the registration process for the user. If there are missing fields, the registration will remain pending. The default value is 'false'.
isActiveBooleanThis parameter allows disabling the account. This is only permitted when calling this method from server-side, attempting to disable an account from a client SDK will return an error.
passwordJSON object

This property can be passed 2 different ways as shown in the code example below, the password property may include:

  • hash - string - The user's password, hashed using the algorithm defined by the algorithm parameter using BASE64 encoding. The max number of hash bits is 512. If compoundHash is not passed, this parameter is required.
  • hashSettings - object - Includes:
    • algorithm - string - The algoritm used for the password, i.e., "md5". If compoundHash is not passed, this parameter is required.

       Click to expand the algorithm specifications

      The hash algorithm used to encrypt the password. The supported hash algorithms are: md5, sha1, sha256, md5_crypt, bcrypt, pbkdf2 and drupal.

      Note: The algorithm param will not be accepted if a compoundHash is set. You will typically want to pass md5-crypt, bcrypt, and drupal password hashes using their compoundHash representation. You should specify these algorithms only if your user management system stored the raw form of these password hashes (as byte arrays). Be wary of passing existing base64-encoded hashes to hash (below); these algorithms typically string-encode their hashes using non-standard (MIME) base64 encodings.


      If algorithm is md5, sha1, or sha256, then you can optionally specify rounds, format and salt.
      If algorithm is md5_crypt, bcrypt, pbkdf2 or drupal, then you must pass rounds, salt, and optionally format (but it mustn't specify $salt

      If compoundHash is not passed, this parameter is required.

    • salt - string - The BASE64 encoded value of the salt. If format is specified and it contains $salt, salt is required and should be clear text, not BASE64-encoded. The max number of salt bits is 1024.
    • format - string - A template describing how to merge the clear-text password that is entered by the user with a salt. The string must contain $password, which will be replaced with the clear-text password. It may also contain $salt which will be replaced with whatever value you passed to the salt parameter (or you can pass the salt directly in the template and omit the salt parameter). For example, Wikipedia hashes passwords that include a constant salt ("wikipedia") along with a per-user random salt, as per this template: wikipedia$salt$password. Example:

      "format": "$password::$salt"
  • compoundHash - string

     Click to show compoundHash specification

    A string in which a user's password hash as well as the hashing algorithm and various algorithm settings are encoded. Such a compound string packs all information that would otherwise need to be passed through the algorithm, salt and rounds parameters. There are several semi-standard formats floating around. We currently support two formats, to some extent:

     
     Modular Crypt Format (MCF) strings typically start with a "$...$" pattern. These strings are typically used by PHP and Python-based user management platforms. We support MCF strings that start with either:

    • "$1$" : for a md5-crypt hash
    • "$2$" or "$2a$" : for a bcrypt hash
    • "$pbkdf2$" or "pbkdf2-sha1" : for a PBKDF2 hash based on SHA1
    • "$S$": for a Drupal version 7 or above hash
    • "$des_crypt$ : for a Unix Crypt DES hash

    Refer to http://packages.python.org/passlib/modular_crypt_format.html for more information about MCF hashes.

    Lightweight Directory Access Protocol (LDAP) strings typically start with a "{...}" pattern. We support LDAP strings that start with either:

    • "{MD5}": for simple MD5 hashed passwords
    • "{SHA}": for simple SHA-1 hashed passwords
    • "{SMD5}": for salted MD5 hashed passwords
    • "{SSHA}": for salted SHA-1 hashed passwords

    If you do not pass this parameter, you need to pass some combination of hash and the other password related parameters; see notes below.


Password object code examples:
// Example A
"password": {
	"compoundHash": "$S$D27r.aObIYkw3I8tO9VDYs.FfuF/4ZjBKDDMx0hxVvB3Kt2iCPEY"
}
 
// Example B
"password": {
	"hash": "Y2FlOTkzNThhYjRlYzE2YmZhYTMyYWI2MzFiMGFhOTc=",
	"hashSettings": {
		"algorithm": "md5",
	    "salt": "lYzE2YmZhYTMy",
	    "format": "$password::$salt"
	}
}
roundsintegerSpecifies the number of iterations to perform the hashing. The default value is 1, e.g., one iteration of hashing. The max value for this parameter is 10000.
If algorithm is bcrypt, then this value must be a power of 2.
createddateThe time (in UTC) the account was created in ISO 8601 format, "YYYY-MM-DDThh:mm:ss.nnn" , e.g., "2014-07-16T19:20:30Z".

 

Site Identity (Profile)

The site identity accepts a wide array of fields, many of which you may not currently use. If your current site profiles include any of the following fields, you should include them. Keep in mind that data pulled from social networks should not be imported in the site identity. Gigya validates that the profile fields meet the requirements that are defined in the Schema.

Field NameTypeDescription
addressstringThe person's address.
biostringA description of the person's professional profile.
birthDaynumberThe day in month in which the person was born.
birthMonthnumberThe month in which the person was born.
birthYearnumberThe year in which the person was born.
certificationsarray of objectsThe person's certifications' details.
citystringThe person's city.
countrystringThe person's country.
educationarray of objectsThe person's education details.
emailstringThe person's email.
favoritesJSON objectThe person's favorite things, including favorite books, movies, etc.
firstNamestringThe person's first name.
genderstringThe person's gender. The value may be 'm', 'f', or 'u', for male, female, or unspecified.
hometownstringThe person's hometown.
honorsstringA comma-separated list of the person's honors.
industrystringThe industry in which the person's company operates.
interestedInstringThe gender in which the person is interested.
languagesstringA comma-separated list of languages that the person speaks.
lastNamestringThe person's last name.
localestringThe person's locale.
nicknamestringThe person's nickname, this may be either the nickname provided by the connected provider or a concatenation of first and last name.
patentsarray of objectsThe person's patents' details.
phonesarray of objectsThe person's phone numbers.
photoURLstringThe URL of person's full size photo.
politicalViewstringThe person's political views.
professionalHeadlinestringThe person's professional headline, often the job title at the company.
profileURLstringThe URL of the person's profile.
publicationsarray of objectsThe person's publications' details.
relationshipStatusstringThe relationship status of the person.
skillsarray of objectsA collection of the person's skills.
specialtiesstringThe person's specialties.
statestringThe person's state.
timezonestringThe person's timezone.
workarray of objectsA collection of the person's work experience.
zipstringThe person's zip code.

 

Social Identities

If your current system stores the authTokens for your social users, you should include them in the identities array. If not, the provider and providerUID fields will allow us to pre-link social accounts to site accounts so that they will not have to re-link their accounts when they log in socially or create duplicate accounts.

 

RequiredField NameTypeDescription
providerstringThe name of the connected provider for this identity, in all lowercase letters ("facebook", "yahoo", etc.).
providerUIDstringThe person's ID on the connected provider.
authTokenstringThe session authentication token.
tokenSecretstringThe session token secret.
tokenExpirationintegerThe absolute time when the session token expires in UNIX time format.
sessionHandlestringThe session handle encoded in BASE64.
sessionHandleExpirationintegerThe absolute time when the session expires in UNIX time format (e.g., number of seconds since January 1st, 1970).

 

Data Schema

In addition to the generic fields stored in the site identity, you can pass fields and data structures in a JSON object to be stored in the data schema. The purpose of this object is to store any custom data associated with the user, but which is not part of the Site Identity. Gigya validates that the data fields meet the requirements that are defined in the Schema.

JSON Samples

The samples provided in the subsequent examples do not represent all of the possible fields. Please see above to identify which fields are required and which are optional. Please note that the inclusion of “email” and “username” on the account level should match your Login Identifier policy. Though the samples demonstrate separating parameters on different lines, the most effective format is one account per line with no line breaks between parameters. We prefer line breaks between accounts so it is easier to inspect the dataset.

 

Account with Site Identity Only

 

// **Example without a social identity**
{
  "accounts": [
    {
      "UID": "<YOUR-­INTERNAL-­UID>",
      "profile": {
     "firstName": "John", 
     "lastName": "Smith", 
     "nickname": "john.smith", 
     "email": "john.smith@acme.com", 
     "photoURL": "http://my.photos.example.com/photos/original/john.smith.png", 
     "profileURL": "", 
     "birthDay": 12, 
     "birthMonth": 9, 
     "birthYear": 1965, 
     "city": "Mountain View", 
     "state": "CA", 
     "zip": "94043"
      },
      "data": {
     "customfield1": "customvalue1", 
     "customfield2": "customvalue2", 
     "customobject3": { 
            "subfield4": "subvalue4", 
            "subfield5": "subvalue5" }
      },
      "loginIDs": {
        "emails": [
          "john.smith@acme.com"
        ],
        "username": "johnsmith"
      },
      "password": {
        "hash": "sadfgasdfggsdfsdgh",
        "hashSettings": {
          "algorithm": "md5"
        }
      },
      "isVerified": true,
      "isActive": true
    }
  ]
}

 

Account with Site and Social Identities

 

// **Example with a social identity**
{
  "accounts": [
    {
      "UID": "<YOUR-­INTERNAL-­UID>",
      "profile": {
     "firstName": "John", 
     "lastName": "Smith", 
     "nickname": "john.smith", 
     "email": "john.smith@acme.com", 
     "photoURL": "http://my.photos.example.com/photos/original/john.smith.png", 
     "profileURL": "", 
     "birthDay": 12, 
     "birthMonth": 9, 
     "birthYear": 1965, 
     "city": "Mountain View", 
     "state": "CA", 
     "zip": "94043"
      },
 "identities": [ { 
       "provider": "facebook", 
       "providerUID": "81827657", 
       "authToken": "08kjasdfo81hasdf8h", 
        "tokenExpiration": 81857623 }, 
        { 
        "provider": "yahoo", 
        "providerUID": "81047123", 
        "authToken": "08kjasdfo81hasdf8h", 
        "tokenSecret": "asdflkgas82345", 
        "tokenExpiration": 81857623 } ],
      "data": {
     "customfield1": "customvalue1", 
     "customfield2": "customvalue2", 
     "customobject3": { 
            "subfield4": "subvalue4", 
            "subfield5": "subvalue5" }
      },
      "loginIDs": {
        "emails": [
          "john.smith@acme.com"
        ],
        "username": "johnsmith"
      },
      "password": {
        "hash": "sadfgasdfggsdfsdgh",
        "hashSettings": {
          "algorithm": "md5"
        }
      },
      "isVerified": true,
      "isActive": true
    }
  ]
}