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 User import file format is a JSON file containing information for each user and associated social identities. If you are importing into Gigya's Registration-as-a-Service, please reference the RaaS Import Guide.
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 that 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.
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.
Accessing Social Data
In most cases, you should continue using any previously configured Social Network Apps. If you create new social network apps, users who have previously given permission to your old app will have to give permission to your new app. In addition, if you have stored auth tokens for your users and can provide them in the import file, at time of import Gigya will automatically download the social data available for users whose auth tokens are still valid. Since authTokens expire after finite amounts of time, we will only be able to download social data for users who have logged in recently (exact timeframe depends on the social network). If you do not include authTokens in your import file, social data will be downloaded for users the next time they log in socially.
Retaining Social Identity Account Links
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.
Object Fields
Note that ALL parameters are CASE SENSITIVE, as they are in the Gigya API.
User
Required | Field Name | Type | Description |
| UID | string | A 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. |
| userInfo | JSON object | This parameter allows you to provide Gigya with a site users profile data. This will ensure a consistent user experience. Gigya will use this information, for example, in Add-ons that show user info, such as the Comments Add-ons. Note: When using Gigya Add-ons, notifyLogin must be called with userInfo for site users who don't have a social identity in order for them to interact with the Add-ons. The object may include the following fields: nickname, photoURL, thumbnailURL, firstName, lastName, gender, age, email. "userInfo": { "firstName": "John", "lastName": "Smith", "nickname": "john.smith", "email": "john.smith@acme.com", "photoURL": "http://my.profile.example.com/photos/original/john.smith.png", "gender": "m", "age": 32 } |
Site Identity (Profile)
The site identity accepts a wide array of fields, many of which your site may not currently use. However, if your current site profiles do include any of the following fields, you should include them. Keep in mind that data pulled from social networks should not be imported to the users site identity.
Gigya validates that the profile fields meet the requirements that are defined in the Schema.
Field Name | Type | Description |
address | string | The person's address. |
bio | string | A description of the person's professional profile. |
birthDay | number | The day in month in which the person was born. |
birthMonth | number | The month in which the person was born. |
birthYear | number | The year in which the person was born. |
certifications | array of objects | The person's certifications' details. |
city | string | The person's city. |
country | string | The person's country. |
education | array of objects | The person's education details. |
string | The person's email. | |
favorites | JSON object | The person's favorite things, including favorite books, movies, etc. |
firstName | string | The person's first name. |
gender | string | The person's gender. The value may be 'm', 'f', or 'u', for male, female, or unspecified. |
hometown | string | The person's hometown. |
honors | string | A comma-separated list of the person's honors. |
industry | string | The industry in which the person's company operates. |
interestedIn | string | The gender in which the person is interested. |
languages | string | A comma-separated list of languages that the person speaks. |
lastName | string | The person's last name. |
locale | string | The person's locale. |
nickname | string | The person's nickname, this may be either the nickname provided by the connected provider or a concatenation of first and last name. |
patents | array of objects | The person's patents' details. |
phones | array of objects | The person's phone numbers. |
photoURL | string | The URL of person's full size photo. |
politicalView | string | The person's political views. |
professionalHeadline | string | The person's professional headline, often the job title at the company. |
profileURL | string | The URL of the person's profile. |
publications | array of objects | The person's publications' details. |
relationshipStatus | string | The relationship status of the person. |
skills | array of objects | A collection of the person's skills. |
specialties | string | The person's specialties. |
state | string | The person's state. |
timezone | string | The person's timezone. |
work | array of objects | A collection of the person's work experience. |
zip | string | The 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.
Required | Field Name | Type | Description |
| provider | string | The name of the connected provider for this identity, in lowercase letters (facebook, yahoo, etc.). |
| providerUID | string | The person's ID on the connected provider. |
| authToken | string | The session authentication token. |
| tokenSecret | string | The session token secret. |
| tokenExpiration | integer | The absolute time when the session token expires in UNIX time format. |
| sessionHandle | string | The session handle encoded in BASE64. |
| sessionHandleExpiration | integer | The absolute time when the session expires in UNIX time format. |
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 object schema. The purpose of this object is to store any custom data associated with the user, which is not part of the Site Identity. Gigya validates that the data fields meet the requirements that are defined in the Schema. Please note that storing data in the data schema requires Identity Storage.
JSON Samples
The samples provided on the subsequent pages 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.
User and Social Identities
{ "settings": { "importFormat": "gigya-users-import", "apiKey": "<APIKEY-TO-IMPORT-DATA>", "finalizeRegistration": true, "skipVerification": true, "totalRecords": 8274 }, "accounts": [ { "UID": "<YOUR-SITE-UID>", "userInfo": { "firstName": "John", "lastName": "Smith", "nickname": "john.smith", "email": "john.smith@acme.com", "photoURL": "http://my.profile.example.com/photos/original/john.smith.png", "gender": "m", "age": 32 }, "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" } } }] }