Data and Access Management Overview

Janrain provides a powerful and secure customer profile database that gives you the tools you need to access and manage your data. Using the Registration API, you can securely add, remove, update, and export user profiles while tightly controlling read and write access to user data.

You should be familiar with the following concepts to effectively manage Janrain’s profile data storage solution:

  • API Client - API clients control access to the Registration API. They are used for authentication when making direct API calls, and they control site-specific behavior when users interact with the Registration UI. Client permissions are managed with the /clients API. Client settings are managed with the /settings API.

  • Entity - An entity is a user record in your Registration application. Entities are managed with the /entity API.

  • Entity Type - Entity types are distinct profile data stores within a Capture application. A JSON schema defines the profile attributes to be stored for user records and any global validation rules or constraints that should be applied. Entity types are managed with the /entityType API.

  • Flow - Flows provide a configuration layer that sits the between client-side user interface elements of Registration and the entity type where user data is stored, allowing different data validation rules to be defined across sites all using the same database schema. Flows are managed with the Configuration API.

Managing Your Schema

Entity Types

Entity types are distinct profile data stores within a Registration application. A JSON schema defines the profile attributes to be stored for user records and any global validation rules or constraints that should be applied.

The Default Schema

Every Registration application is provisioned with a default entity type called user. This schema should only be expanded upon; deleting attributes from the default user schema may result in unexpected behavior. In particular, the following attributes are part of the default schema and are pertinent to the functionality implemented by the Janrain registration process:

  • The profiles plural aggragates the user data returned from the different social providers. Each provider linked to a user account will be added as a separate object to the profiles plural, but will share a common structure.
  • The clients plural stores information about when and where a user has authenticated (including at initial registration). This includes the client ID in use on the site where the login occurred, the timestamp of the user’s first login on that site, and the timestamp of the user’s last login on that site. Each time a user logs into a new site, a new entry will be added with its client ID. Subsequent logins on the same site will not create an additional object, but instead update the last login value.
  • The janrain object stores metadata information that Janrain needs for integrations with other systems such as Salesforce Marketing Cloud or other parts of the Janrain platform.

Note: The attributes in the default user entity type provisioned with new applications is occasionally updated, so not all customers will have the attributes listed above.

Adding Entity Types

In most cases the default user entity type is used for all site registrations. Occasionally you may want to utilize multiple entity types for the purpose of keeping registrations of different user types or customer verticals separate. We recommend that you consult with the Janrain Professional Services team if you are considering taking this approach.

Additional entity types may be created with the entityType.create API. Once an entity type has been created, you can add and remove schema attributes associated with it by using the entityType.addAttribute and entityType.removeAttribute endpoints.

Schema Attribute Types

The following attribute types are available for storing different types of user data.

Type Primitive ? JSON Type Notes
boolean Yes Boolean
date Yes String Subject to the Timestamp format. See Timestamp Formats.
dateTime Yes String Subject to the Timestamp format. See Timestamp Formats.
decimal Yes Number
id Yes Number Not an externally usable type.
integer Yes Number
ipAddress Yes String
json Yes (any type) The JSON type is unstructured data; it only has to be valid parsable JSON.
object No Object
password Yes String The default password encoding is bcrypt.
plural No Array Primitive child attributes of plurals can have the constraint.
string Yes String
uuid Yes String Not an externally usable type.

Note: all primitive types can have the constraints unique and required. For more information on constraints, please see the Constraints topic.

Objects

Objects are used for nesting related attributes under a parent attribute within the schema. For example, in the default schema the primaryAddress object holds address1, city, zip, and other related attributes. When making API calls targeting an attribute within an object, you can refer to the parent and child attributes with either / or . notation between. For example: primaryAddress.city or primaryAddress/city.

Plurals

Plurals are a special object type used for storing an indefinite number of nested objects or attributes of a like construct. Common use cases include opt-in lists, addresses, and subscriptions. Plurals are not supported by the Registration UI or OAuth API endpoints and require a custom integration with the user profile.

Reserved Attributes

The following attributes are read-only, automatically generated, and required in all schemas.

Attribute Description
created  Automatically-generated timestamp marking the entity’s creation.
id  A unique identifier for for an entity. The ID is automatically created during registration and is unique to the entity.
lastUpdated  Automatically-updated timestamp marking the last change made to an entity.
parent_id  The ID used when implementing plurals.
uuid  Unique identifier for the entity.

Timestamp Formats

Capture accepts and renders the dateTime and date attributes in ISO 8601 format, but it also accepts many other variations.

Note that users can enter the month, day, and year of the date in any order, as long as they are unambiguous (for example, if you use four digits for the year or spell out the month). When they are ambiguous, registration will always interpret the order as month-date-year.

The following keywords are also accepted in dateTime and date attributes: today, yesterday, and now.

All timestamp attributes are rendered in the UTC time zone, and include the ‘-0000’ time zone offset tag at the end of the timestamp. Attributes are accepted in any time zone, and are interpreted as UTC when no time zone is specified.

The Janrain servers interpret each of the following as the same dateTime value:

  • 2003-01-02 6:15pm
  • 2 Jan 03 18:15:00.00
  • 01-02-03 6:15pm
  • January 2, 2003 11:15am -0700

Supported Password Hashing Algorithms

For importing legacy user passwords into Janrain profile data storage, Janrain supports the following password hashing algorithms. For custom or non-standard hashing password encryption, please contact your Janrain representative.

  • password-atlassian-pbkdf2-sha1
  • password-base64
  • password-bcrypt
  • password-crypt-des
  • password-crypt-md5
  • password-crypt-sha256
  • password-crypt-sha512
  • password-hc
  • password-md5
  • password-md5-rightsalt-240
  • password-md5-salted-left-base64
  • password-md5-salted-right-base64
  • password-md5-ucs32-be
  • password-md5-ucs32-le
  • password-md5-utf16-be
  • password-md5-utf16-le
  • password-netforum
  • password-phpass-md5
  • password-phpass-sha512 - - DRUPAL
  • password-phpass-sha512-truncated-55 - - DRUPAL
  • password-plain
  • password-rr
  • password-saltedsha-1-left-base64
  • password-saltedsha-1-rrr
  • password-saltedsha-256-left-256-base64
  • password-sha
  • password-sha-256
  • password-sha-512

Data Constraints and Features

Constraints

The following constraints may be applied to attributes of the string data type using the /entityType.setAttributeConstraints API.

Constraint Description
alphabetic  Data may only contain characters A–Z.
alphanumeric  Data may contain characters A–Z and 0–9.
unicode-letters  Data may only contain characters encoded using the Unicode standard.
unicode-printable  Data may only contain Unicode-encoded characters that can be printed to the screen in HTML. The excluded characters are: u0000–u001F, u007F–u009F, \n, \t, and \r.
email-address  Data must contain an @ symbol and top level domain suffix, such as .com.
length  Used only with attributes of type string. Defines the number of characters allowed. By default, string length must be specified for the attribute to be indexed.
required Data must contain a non-null value.
unique  Data must be globally unique across all entities in an entityType.
locally-unique  Data must be locally unique across plurals within a single entity.

When added to an attribute, constraints are applied only to data saved to user records after the constraint is applied. The exceptions to this rule are the unique and locally-unique constraints, which apply retroactively to data already collected. If existing data violates the constraint, adding the rule will result in an error. Error responses are explained in detail in the Error Codes topic.

Constraints set on a schema attribute will apply globally to all records. If you need to apply different constraints or validations on data collected at different sites or properties, the Configuration API will allow you to apply those in the flow configuration layer.

Features

The following features may be applied to attributes of the string data type. These features may only be applied by the Janrain team.

Feature Description
primary-key  Makes the attribute a primary key for the plural or entity type it exists in, providing the ability to target a specific record in a plural in API calls without knowing the actual identifier for that record. Requires both required and either unique or locally-unique constraints.
query  Adds an index to an attribute to optimize the performance of entity.find API calls.

Data Validation Rules

The following data validation rules may be applied to attributes using the entityType.addRule API. The table below notes which attribute type each rule may be applied to and what type of argument each rule will accept, if any. Filters that transform input are applied before filters that validate input.

Rule Description Transforms Input? Attribute Type Argument Type
match Data must contain a match from a POSIX-style regular expression. no string string
match-all Data must completely match a POSIX-style regular expression. no string string
min-length Data must be less than or equal to the argument supplied. no string integer
max-length Data must be greater than or equal to the argument supplied. no string integer
less-than Data must be less than the argument supplied. no integer number
greater-than Data must be greater than the argument supplied. no integer number
required Data must contain a non-null value. no any none
min-age The date submitted must be at least n years ago. no date integer
default Data will be pre-populated with the argument supplied. yes any integer or string
ignore-update yes any none
truncate Stores only the first n characters of the value submitted. yes string integer
to-lower Converts a string value to lower case. yes string none
to-upper Converts a string value to upper case. yes string none
and Combines a list of filters and fails if one of the filters fails. maybe array of rules array of strings and/or objects
or Combines a list of filters and fails if all of the filters failed. maybe array of rules array of strings and/or objects
not Turns a failed filter result into a successful filter result. maybe rule string or object

When added to an attribute, rules are applied only to data saved to user records after the rules are applied. When a rule is violated, a 360 (constraint_violation) error is returned. Error responses are explained in detail in the Error Codes topic.

Rules set on a schema attribute will apply globally to all records. If you need to apply different constraints or validations on data collected at different sites or properties, the Configuration API will allow you to apply those in the flow configuration layer.

Rule Definition Examples

Values are truncated to 100 characters if their length is over 100 and converted to lower case:

    {
      "and": [
          { "truncate": 100 }
        , "to-lower"
      ]
    }

Values are rejected if they are less than six characters long or contain any 3s or fs:

    {
      "and": [
          { "min-length": 6 },
          { "not": {
                "match": "[3f]"
            }
          }
      ]
    }

Sets a minimum age of 16:

    {
       "and":[
          {
             "min-age":16
          },
          "required"
       ]
    }

Managing User Data

User data can be managed using the /entity API:

Endpoint Description
/entity retrieves a single user record
/entity.find retrieves a set of user records, determine by the filter applied
/entity.create creates a single user record
/entity.bulkCreate creates multiple user records in a single API call
/entity.update updates only the specified attributes for an existing user record
/entity.replace replaces all attributes for an existing user record; any attributes not specified will be replaced with null values

Querying Large Data Sets

When using the entity.find endpoint to iterate over large sets of data (> 100,000) the first_result and show_total_count convenience parameters should not be used. The queries should be optimized using natural database sorting by sorting on the id attribute. This has two benefits:

  • Records created between when the time iteration begins and when the time iteration ends are included in the results.
  • Efficient and consistent performance querying and loading for each page of results.

The following tips will help you optimize your queries:

  • Use the attributes parameter to limit the number of attributes returned for each record to minimize the size of the HTTP payload.
  • Experiment with the max_results parameter to optimize for responses under 10 seconds.
  • Include the timeout parameter (up to 60 seconds) if, and only if, you are unable to keep responses under 10 seconds using the max_results parameter.
  • Do not use the first_result parameter for large data sets as it will incur an incremental performance cost with each additional page of results.
  • Do not use the show_total_count parameter for large data sets as it will incur an additional query (count) with every request.

The sample code below (written in Python) shows how to iterate over every record updated since January 1, 2016. Only the id, uuid, and email attributes will be returned in the result set, and up to 100 records will be returned with each request.

import requests
import json

last_id = 0
while True:
    response = requests.get(
        'https://YOUR_APP.janraincapture.com/entity.find',
        headers={
            'Authorization': 'Basic aW1fYV...NfbXk='
        },
        data={
            'type_name': 'user',
            'max_results': '100',
            'attributes': '["id", "uuid", "email"]',
            'sort_on': '["id"]',
            'filter': "id > {} and lastUpdated >= '2016-01-01'".format(last_id),
        }
    )
    json_resp = json.loads(response.text)
    if json_resp['stat'] == 'ok' and json_resp.get('result_count', 0) > 0:
        for record in json_resp['results']:
            # do something with record
            print(record)
            # update last_id variable with last record in the results
            last_id = record['id']
    else:
        # stop iterating when there are no more results
        break

Bulk Data Imports

If you need to import user records from an existing data store into the Janrain platform, the /entity.bulkCreate API can be used for bulk loading data. The Janrain Data Loader is an example script utilizing this API that you may use to perform your own data migrations.

If you are considering utilizing this script, we recommend that you consult with Janrain Professional Services on setting appropriate arguments for batch size and rate limit. Always alert Janrain of the date and time you plan to run any bulk data events by submitting a Traffic Event request through the Support Portal.