Janrain ProfileSync

No one can be in two places at the same time and, for the most part, people are fine with that. After all, if you could be in two places at the same time, you might have to sit through a meeting in Portland at the same time you have to sit through a meeting in Brussels. You might have to drive south on the freeway at rush hour at the same time that have to drive north on the freeway at rush hour. You might – well, you get the idea. Like we said, no one can be in two places at the same time and, for the most part, people are fine with that.

When it comes to data, however, it’s a different story: in that case, people want their data to be in two (or even more) places at the same time. For example, through our user profiles, Janrain collects, and securely stores, a wealth of information about your registered users. Furthermore, we provide tools (most notably Customer Insights version 2.0) that help you analyze and make use of that data.

Needless to say, that’s great. And yet …. Suppose you have a CRM (customer relationship management) application; wouldn’t it be nice to have that same user profile information replicated in your CRM? Suppose you have a DMP (data management program) application; wouldn’t that DMP be far more valuable if it contained data from the Janrain user profile? There’s nothing better than having your data stored in a Janrain user profile database, but , still, it would be even better if that data could be stored in more than one place at the same time.

And guess what? Thanks to Janrain data integrations, and thanks to Janrain, your data can be in more than one place at a time. Best of all, this can happen with minimal effort on your part. What does all that mean? We’re just about to tell you.

Note. If you aren’t familiar with the term, a “data integration” involves taking data from multiple sources and presenting users with a unified view of all the retrieved data. For example, an Oracle Responsys user might use the application to look at data; some of that data might have been directly entered into Responsys, and some might have been copied over from a Janrain user profile. The user doesn’t know, or care, where the data came from; he or she is just happy to have a wealth of information at their disposal.

What is ProfileSync?

ProfileSync “extends the Janrain Identity Cloud with reverse API calls to back-end systems.” That’s a complicated-sounding definition for a what turns out to be a fairly simple concept: when notified that a Janrain user profile has been created, modified, or deleted, ProfileSync can use API calls to replicate those changes to a CRM, a DMP, or just about any other system that has a public-facing API, message queue, or file server. To name just a few of these “target APIs,” ProfileSync has been successfully used with:

  • Microsoft Dynamics
  • Oracle Responsys
  • Zuora
  • Salesforce
  • Selligent
  • Sendinblue
  • SmartFocus
  • Qualifio
  • Mulesoft
  • Apigee

And that’s not all. By using webhooks (a standard technology for pushing data from one application to another), data transfers can happen in real-time. As soon as a user updates his or her user profile, a Janrain webhook can notify ProfileSync that a change has taken place. In turn, ProfileSync can identify the nature of the change, then replicate that change to the target API. For example, if Bob Jones registers on your web site, an activity that results in a new user profile, ProfileSync can immediately create a corresponding Salesforce user profile for Bob Jones. And before you ask, yes, this is very secure: all ProfileSync activity takes place over a secure connection, using either an API secret or an OAuth access token.

In other words, ProfileSync: can

  • Call the API of customer’s back-end system; for example, ProfileSync can call Salesforce APIs or Microsoft Dynamics APIs, and use those APIs to update user data.

  • Be triggered by a webhook notification. However, notifications can also come from a CORS-enabled API. CORS (cross-origin resource sharing) is a technology that allows resources from one domain to be used in another domain.

    If you don’t want or don’t need real-time notifications, ProfileSync can also be configured to periodically poll Janrain for user profile changes.

  • Push registrations, profile updates, and forget-me’s (account deletions) to the target API.

  • Provider organizations with custom filtering, field mapping, and conversion and translation rules.

  • Implement data throttling to ensure reliable data delivery. This involves intentionally slowing down a transmission in order to minimize network congestion.

  • Potentially, update a user profile by interpreting the returned API result. Typically, ProfileSync is a one-way transmission mechanism: changes made to a user profile are transmitted to the target API, but changes made in the target API are not replicated to the Janrain user profile. However, ProfileSync can be configured to make at least some user profile updates based on the response returned when ProfileSync calls a backend API.

For more information, see Appendix A: ProfileSync Capabilities.

Why Do We Need Data Integrations?

If you’re familiar with data integrations, you’re probably impressed by the number of different integrations that ProfileSync can handle, and by the fact that ProfileSync can handle these integrations so seamlessly. If you’re not familiar with data integrations, then maybe you aren’t as impressed. After all, at heart, a data integration involves copying data from one data store to another. How hard could that be?

In theory, maybe not hard at all. In practice, however, copying data from one system to another runs headlong into a major problem: there is no universal standard for storing user data. Consider a simple example. A Janrain user profile includes these attributes:

Attribute Value
givenName Bob
familyName Jones
displayName Bob Jones

Now suppose that your target API includes these database fields:

Field Value
first_name
last_name
full_name

Admittedly, most people have little trouble figuring out what needs to be copied and to where; for example, the Janrain givenName attribute seems to correspond to the first_name field in the target API. Computers, however, need some help in a situation like this: computers need to know how to map Janrain attributes to target API database fields. That’s where ProfileSync comes in. When a user profile is changed, Janrain notifies ProfileSync that a change has been made. ProfileSync determines what exactly has been changed; for example, ProfileSync might determine that user Bob Jones has changed his givenName to Robert and his displayName to Robert Jones. ProfileSync consults its data map for your backend system, then contacts the target API and uses standard API calls to update the first_name and the full_name.

That’s known as a “simple transform,” because there’s a simple one-to-one correspondence between Janrain attributes and target API database fields: the givenName attribute equals the first_name database field. But that’s not all that ProfileSync can do; the application can also carry out more-complex transforms. For example, suppose your Janrain user profile formats the displayName attribute like this:

Bob Jones

Meanwhile, the full_name field formats data like this:

Jones, Bob

As you can see, there’s no simple one-to-one correspondence here: you can’t just copy the givenName attribute and paste it into the first_name database field. Instead, you must do a more complex data transformation; for example:

familyName + “, ” + givenName

Can ProfileSync handle complex transformations such as this? Do you even need to ask? That’s the kind of capability that makes ProfileSync so flexible. And so useful.

How Does ProfileSync Work?

Although obviously simplified, the preceding section gives you an idea about what ProfileSync does. But exactly how does ProfileSync do all of this? The basic process is outlined below:

  1. A new user profile is created, or an existing user profile is modified or deleted. These changes are recorded in a Janrain user profile database.

  2. Janrain uses a webhook to notify ProfileSync that a user profile has been created, modified, or deleted. See Appendix B for more information about the webhook notification.

  3. ProfileSync verifies compliance information for the target platform. For example, if you want to add the new email address to your marketing database, ProfileSync verifies that the user has given his or her consent to using their email address for marketing purposes.

  4. If consent has been given, ProfileSync retrieves the user profile from Janrain.

  5. As needed, ProfileSync transforms the data to fit the target platform database. For example, if the Janrain attribute is named email and the target database field is named user-email-address, ProfileSync will make the necessary adjustments to ensure that the data is written to the correct location.

  6. ProfileSync calls the update API on the target platform, and presents the UUID and the updated profile information.

  7. The target platform updates its copy of the user record based on the data received from ProfileSync.

  8. If the data transfer fails, ProfileSync retries the transfer a specified number of times. If the data cannot be copied over, then ProfileSync gives up and the event is logged in the dead-letter-queue (DLQ).

About the Dead-Letter-Queue (DLQ)

As noted in the previous section, the DLQ is used anytime ProfileSync cannot complete a data transfer. Admittedly, failures like this are rare, in part because ProfileSync makes multiple efforts to deliver the data before terminating the delivery process. Nevertheless, there are a number of situations that could result in an event being sent to the DLQ:

  • Communication interruptions. For example, either your network or the target API network could experience an extended period where Internet connectivity is lost. You can often diagnose network connection errors by checking the log of failed API calls against known instances of network connectivity issues.

  • Target API downtime. For example, the target API might have been taken offline for maintenance or upgrading. In the API log, you might see that all API calls for a specified period of time (for example, 4:00 AM to 4:30 AM) failed, but all subsequent API calls succeeded.

  • Changes to the target API. Changes to the target API (for example, changing the API endpoint) will result in all your ProfileSync calls failing. If your API log shows that none of your calls have succeeded since a specified point in time, check to see if any changes have been made to the target API.

  • An expired certificate, or credential changes. If a certificate has expired or if your authentication credentials have changed, then all your ProfileSync calls will fail. If all your calls are failing, check to see when the ProfileSync connector certificates expire, and verify that your credentials are up-to-date.

  • User error. If the API log shows seemingly-random problems with data delivery attempts, that could suggest a mapping problem between the Janrain user profile and the target API; for example, you have incorrectly mapped the user’s email address. In a case like that, changes to the email address will fail, while changes to any other Janrain attribute will succeed.

Each Monday an automated program checks the DLQ to see if any events have been logged there. If there are any events in the DLQ, a ticket is sent informing you that an error has occurred. If you believe that the data delivery problem has been resolved (for example, the database that was temporarily offline is now back online) you can respond to the ticket and ask ProfileSync to try again. Provided you respond within 5 days after receipt of the ticket, ProfileSync will contact the target platform and attempt to transfer the data.

Note. And what if you don’t respond within 5 days? Well, after 5 days, the ticket is automatically closed, and the event is removed from the dead-letter-queue. After the event is removed there’s no longer anything for ProfileSync to reprocess.

As a Janrain client, you do not have access to the dead-letter-queue; you only receive (and can respond to) the notification ticket. Because of that, it’s useful to know that no personally-identifiable information is stored in a webhook event (and, therefore, no personally-identifiable information is stored in the DLQ), Instead, each event consists of a JSON object (in the case of the dead-letter-queue, these events are stored as .txt files). See Appendix B for more information.

Setting Up and Configuring ProfileSync

One of the many great things about Janrain ProfileSync is the fact that implementation, and on-going maintenance, is largely hands-off: after the initial setup, most of the work is handled by Janrain. That said, however, in order to complete setup you must work with Janrain to configure and test the ProfileSync connector between your user profile database with the target API. That work revolves around the following activities:

  • Establishing data governance
  • Providing API documentation
  • Establishing webhooks
  • Establishing data mapping
  • Verifying and validating data throttling
  • Configuring your target API and your Janrain application
  • Configuring the connection
  • Testing with sample data
  • Preparing for change control
  • Establishing a monitoring procedure
  • Establishing a procedure for handling the dead-letter-queue

Each of these activities is described in more detail in the following sections of this document.

Establishing Data Governance

Data governance refers to the processes used to ensure the availability, usability, integrity, and security of all the data employed by your organization. In the case of ProfileSync, data governance involves at least two things. First, you need to understand the type of data stored in a Janrain user profile. In general, this data:

  • Is entered by the user, and is relatively stable. For example, a given user is unlikely to change his or her email address or phone number on a daily basis.
  • Is used operationally, and not for historical purposes.
  • Is non-transactional; that is, the data is not used for things like tracking purchases or making appointments.
  • It not volatile. “Volatile” data is data that is stored only in random access memory (RAM) or exists only in transit, and would disappear in the event of a computer failure.

You should also keep in mind that Janrain user profile data can be returned using the Janrain REST APIs. If you rarely need to retrieve user profile data (and rarely need to copy that data to a target API), you might not need ProfileSync. After all, ProfileSync is designed for situations when “self-service” data retrieval is infeasible. If you routinely need to process a large number of profile changes to your target API, then ProfileSync will be faster, more efficient, and more cost-effective.

Second, you must establish a policy for determining data primacy. For example, suppose you’ve created a Salesforce account for a user. If the user changes that data in his or her user profile, do you want that data to overwrite the existing Salesforce data? In many, if not most, cases, the answer is yes; after all, that’s why you are using ProfileSync in the first place. However, there might be certain attributes (or certain attributes for certain users) that should not be overwritten. That’s something you must determine in advance.

Along similar lines, you must select a unique identifier for each user. We strongly recommend using the Janrain UUID (Universally Unique Identifier) as your foreign key. (In the database world, a foreign key is a database field defined in Database A that, in this case, uniquely identifies a user in Database B.)

Providing API Documentation

In order to transfer data from Janrain to a third-party data store (be it Salesforce, Oracle, Microsoft Dynamics, etc.) Janrain requires detailed information about the target API. Because of that, you must supply:

  • Full documentation for the target API, including examples of both API requests and API responses.

  • A test environment for the target API. You must also provide test data representative of the production environment (in other words, “fake” user accounts that contain attributes and attribute values similar to those found in actual user profiles).

  • A way to verify that ProfileSync calls are successfully processed in the test environment, and that profile data is successfully transferred. This is often done by providing read-only API access to the test database.

Establishing Webhooks

Webhooks provide a way to push data, in real time, from one application to another. In the case of ProfileSync, Janrain webhooks push data regarding user profile changes to ProfileSync; ProfileSync then transforms and repackages that data as needed and pushes it to the target API. As noted previously, all of this activity happens almost-instantly: when a profile is updated, Janrain immediately notifies ProfileSync, which immediately copies that data to the target API. As a result, your CRM database or your marketing database will almost-always be perfectly up-to-date.

Incidentally, this provides a major advantage over traditional API-based applications, where the application periodically polls the source database for changes. In a case like that, your target database will only be as up-to-date as your polling interval: if you poll once-an-hour for updates, then the target database could be as much as an hour out of date.

Note. In addition to that, constant polling – even if there are no changes to be retrieved – adds to network congestion and to server resource use.

Although Janrain will set up your webhooks for you, you need to determine such things as:

  • The type of changes (e.g., profile creations, modifications, and deletions) to be reported.
  • The fields to be copied from the Janrain user profile to the target API.
  • The users for which data will be copied (e.g., all users; only the users who live in the US; only the users who don’t live in the US; etc.).

Establishing Data Mapping

As noted previously, one of the challenges involved in data integrations is mapping field names between the different databases; that is, making sure that ProfileSync knows that Janrain’s familyName attribute is the same thing as the last_name attribute in your target application. Because of that, you will work closely with Janrain to develop the mapping, filtering, and format conversion rules needed to carry out your data integration.

Configuring Your Target API and Your Janrain Application

Before you can connect your target API and your Janrain application, you will typically be required to do some configuration work both on the target API and on your Janrain application. The actual work you need to do will vary depending on both your target API and your data needs; you will work with your Janrain representative to determine exactly what need to be done. For a sample set of tasks, see the Integrating ProfileSync with Salesforce section of this documentation.

Validating and Verifying Data Throttling

ProfileSync can potentially make a large number of requests, large enough to slow down (if not even overwhelm) your target API. This is especially true for large organizations or for organizations where special events or special promotions might result in huge increases in registrations (and the corresponding user profile creation events). Because of that, it is important that you: 1) have some knowledge of the number of transactions ProfileSync will routinely generate on your behalf; and, 2) have reasonable assurance that your target API will be able to handle all that traffic.

For the most part, there’s less concern about ProfileSync’s ability to handle large loads: that’s because the application includes an intelligent retry mechanism. No matter what you throw at it – network latency, platform availability, API congestion – ProfileSync can gracefully recover from a failed API call and then try again. Note that both the number of retries and the frequency of these retries is configurable. Note, too that ProfileSync uses an exponential backoff schedule to help balance retry loads. For example, if the first ProfileSync retry takes place 2 seconds after a failed attempt, the second retry might take place 4 seconds after that, the third retry might take place 8 seconds after that, and so on. In this example, the previous retry interval (e.g., 2 seconds) is multiplied by 2 to determine the time when the next retry takes place (2 x 2 = 4 seconds later).

Configuring the Connection

Although Janrain will handle most of the ProfileSync setup and configuration, you will have to make several decisions (and carry out an activity or two) regarding your network connection. In particular, you need to:

  • Specify the methods used by the target API; you can choose between an HTTP request, a SOAP request, or an sFTP “drop.” (An sFTP drop gives ProfileSync permissions to copy files to the sFTP server, but does not provide permissions to read or to modify those files after they have been copied.)

    Note that, by default, ProfileSync typically transfers data as a JSON file. However, you can optionally choose to have data transferred as an XML or SOAP object.

  • Configure a publicly-accessible endpoint where ProfileSync can push data. Allowed protocols for this endpoint include REST API, SOAP, Amazon S3, or SFTP.

  • Determine the authentication method to be employed by ProfileSync. It’s recommended that you use OAuth 2.0 on a TLS network. However, you can optionally use Basic authentication, an API key in the header, or a digital signature.

When planning security for ProfileSync, keep in mind that the application is cloud-based; because of that, security between ProfileSync and your target API cannot be based on source IP address (a security approach, also known as data origin authentication, in which a specific entity is identified as the source for a given piece of data). As a container-based technology, IP addresses assigned to ProfileSync are highly-volatile: at best, an IP address is only good for 15-to-90 minutes before being changed. This effectively makes it impossible to use source IP address as a security measure.

However, you can “bridge” on-premise security (including IP address whitelisting) with OAuth-based cloud security. If you do this, your API bridge must be accessible from the cloud and should perform the OAuth token handling and key discovery. To avoid potential data loss and data restoration issues, the API bridge should also be configured as a simple pass-through and should not persistently store ProfileSync updates.

Testing the Setup Using Sample Data

Testing and debugging the ProfileSync connector is an important part of setting up and implementing ProfileSync: it’s crucial that ProfileSync pass an end-to-end integration test before the application is used to process and transfer live data. This is why you must set up and configure a test environment (complete with test data): this enables Janrain to work with you to create, modify, and delete user profiles, and then verify that these changes are being correctly processed and then replicated to the target API.

Preparing for Change Control

Change is inevitable, which means you must be prepared for your API target to change at some point: maybe a new endpoint replaces the current endpoint, or maybe you’ll need to change your password or your client secret. Regardless, any time your target API changes ProfileSync needs to change as well: needless to say, if ProfileSync tries to use your old password or client secret, every one of your API calls will fail. If there are changes to the target API that could affect the use of ProfileSync, notify your Janrain representative. The support team will then work with you to ensure that your ProfileSync connector gets updated.

Establishing a Monitoring Procedure

It’s recommended that you periodically monitor and test the ProfileSync connector: that helps ensure that the connector is working as expected. To test the connector:

  1. Begin by setting up one or more test user profiles (that is, profiles that are used exclusively for testing purposes and are not associated with an actual user).

  2. Periodically change an attribute value in the test user profile. For example, you might change the profile’s email address or mobile phone number.

  3. Based on your service level agreement and your consecutive retry level, verify that the change is replicated to the target API within the allotted timeframe. For example, suppose any changes to a Janrain user profile should be replicated to Salesforce within 60 seconds. In that case, change the user profile, wait 60 seconds, then check Salesforce to verify that the new email address or new phone number is present. If the change has been properly replicated, the ProfileSync Connector is healthy.

  4. If the change has not been properly replicated, verify that you have received notification that the event has been logged to the dead-letter-queue. If it has, then the ProfileSync Connector is healthy, and you should begin looking into reasons (a slow network connection, a changed password or client secret, a service failure at the target API) that prevented ProfileSync from completing the data transfer.

Establishing a Procedure for Handling the Dead-Letter-Queue

If an event is recorded in the dead-letter-queue, that indicates a systemic failure that prevented ProfileSync from completing its delivery. If you receive notification that an event has been recorded in the DLQ, you can respond to the notification and ask ProfileSync to try again. Before you do that, however, you should try to determine the cause of the failure and verify that the problem has been resolved. After all, if delivery failed because the target API is unavailable and the target API is still unavailable, then any attempt to retry delivery will also fail.

Example: Integrating ProfileSync with Salesforce

In the preceding section of this documentation, we walked through a generic set of procedures that must be carried out in order to connect ProfileSync to a target API. In this section, we’ll take a closer look at a more specific scenario: integrating ProfileSync with Salesforce. Before reading this section, keep two things in mind:

  • The tasks detailed in this section are specific to integrating ProfileSync with Salesforce. To connect ProfileSync with a different target API requires a different set of procedures.

  • Even if you are connecting ProfileSync to Salesforce, you could still end up with a different set of tasks depending on your environment, on the attributes and attribute values you want to copy to Salesforce, etc.

You will work with your Janrain representative to determine the exact procedures that must be carried out to integrate ProfileSync and Salesforce.

Preparing Salesforce to Integrate with ProfileSync

On the Salesforce side of things, there are two things you must do before you can connect to ProfileSync:

  1. You must create a Salesforce connected app.
  2. You must add new fields that map to the user profile attributes being copied from Janrain. At a minimum, you need to add a field to your Salesforce Contact object that maps to the Janrain UUID. The UUID will act as a foreign key: an attribute from one database (Janrain) that can uniquely identify a user in a second database (Salesforce).

These two activities are discussed in more detail in the following sections.

Creating a Salesforce Connected App

To integrate ProfileSync with Salesforce, you’ll need to get a Salesforce developer’s account and create a Salesforce connected app. Creating a connected app is beyond the scope of this documentation; however, we can tell you that:

  • The connected app must adhere to the requirements spelled out in the document OAuth 2.0 JWT Bearer Token Flow. That document “… defines how a JSON Web Token (JWT) is used to request an OAuth access token from Salesforce when a client wants to use a previous authorization.”

  • You will need an X.509 certificate in order to create the app. You can generate and sign the certificate yourself, or issue a Certificate Signing Request to your Certificate Authority. In addition, the RSA Private Key for that certificate must be stored in your Janrain API Client settings. See the Adding ProfileSync Custom Settings section of this document for more information.

Updating the Salesforce Schema

Each Janrain user profile attribute copied to Salesforce must have a corresponding Salesforce Contact field. In some cases, a one-to-one correspondence already exists: for example, the Janrain user profile has a birthday attribute, while the Salesforce Contact object has a Birthdate field. In other cases, no such correspondence exists: for example, Salesforce does not have a field equivalent to Janrain’s emailVerified field. If you want to keep track of which users have (or have not) verified their Janrain email addresses, you will need to add a new field to the Contact schema.

The following table shows the default mappings between commonly-used Janrain user profile attributes and Salesforce Contact fields. Remember, you do not need to have a Salesforce equivalent for every field in the Janrain profile: you only need to have fields for the attributes you want to copy from Janrain. For example, if you don’t need to track email verifications then there’s no reason to create an emailVerified field in Salesforce.

Note. What happens if an attribute, like emailVerified, is copied over from Janrain, but there is no matching field on the Salesforce side? Nothing: that value simply doesn’t get added to Salesforce. A “missing” field does not cause the rest of the data transfer to fail.

Here are the default mappings:

Janrain User Profile Attribute *Datatype *Salesforce Contact Field *
birthday datetime None. You must create a custom attribute if you want to maintain this data in Salesforce.
created datetime None. You must create a custom attribute if you want to maintain this data in Salesforce.
deactivateAccount datetime None. You must create a custom attribute if you want to maintain this data in Salesforce.
email string Email
emailVerified datetime None. You must create a custom attribute if you want to maintain this data in Salesforce.
familyName string LastName
gender string None. You must create a custom attribute if you want to maintain this data in Salesforce.
givenName string FirstName
lastLogin datetime None. You must create a custom attribute if you want to maintain this data in Salesforce.
lastUpdated datetime None. You must create a custom attribute if you want to maintain this data in Salesforce.
locale string None. You must create a custom attribute if you want to maintain this data in Salesforce.
primaryAddress.address1 string Mailing Address | Street
primaryAddress.city string Mailing Address | City
primaryAddress.country string Mailing Address | CountryCode
primaryAddress.mobile string Mobile
primaryAddress.phone string Home Phone
primaryAddress.region string None. You must create a custom attribute if you want to maintain this data in Salesforce.
primaryAddress. Zip string Mailing Address | PostalCode
title string None. You must create a custom attribute if you want to maintain this data in Salesforce.
uuid uuid None. You must create a custom attribute if you want to maintain this data in Salesforce.

If you need to add a new attribute to the Salesforce Contacts object, you can do so by completing the following procedure. In this example, we’ll add an attribute that maps to the Janrain UUID:

  1. From the Salesforce Developer Home page, expand Objects and Fields and then click Object Manager.
  2. On the Object Manager page, click Contact.
  3. On the Contacts page, click Fields & Relationships.
  4. On the Field & Relationships page, click New.
  5. On the New Custom Field page, for Step 1, select the Text data type and then click Next.
  6. For Step 2, enter the name of the new field (for example, Janrain_UUID) in the Field Label field.
  7. In the Length field, type 32, meaning that the field can contain no more than 32 characters.
  8. Select Do not allow duplicate values, and then select Treat “ABC” and “abc” as duplicate values (case insensitive).
  9. Click Next.
  10. For Step 3, accept the default values and then click Next.
  11. For Step 4, accept the default values and then click Save. The new field appears in your list of fields and relationships.

You now have a Salesforce field that maps to Janrain’s UUID attribute.

Preparing Your Janrain Application to Work with Salesforce

As we just saw, you need to do two things to get Salesforce ready to integrate with ProfileSync. By coincidence, you also need to do two things to get your Janrain application ready to integrate with ProfileSync. In particular, you need to:

  1. Create a new API client.
  2. Add a pair of client settings, one to your Janrain application and one to your new API client.

Creating an API Client

ProfileSync requires a dedicated API client to retrieve user profile data from Janrain. This API client (also referred to as a property) must use the direct_access feature. Do not configure your new client to use login_client (the default feature set).

For additional security, you can also use the Janrain entityType APIs to set an “access schema” on the underlying user profile database. An access schema defines the set of attributes that an API client can access, and also specifies the type of access (read or read/write) that the client has. For example, this Curl command grants the API client with the client ID zng82v8x6q2vchfe3z2dv8xrtxcrjdhf read access to the givenName, familyName, and email attributes:

curl -X POST \
  'https://greg-stemp.us-dev.janraincapture.com/entityType.setAccessSchema?type_name=Documentation&for_client_id=zng82v8x6q2vchfe3z2dv8xrtxcrjdhf&attributes=[%22givenName%22,%22familyName%22,%22email%22]&access_type=read' \

See the setAccessSchema endpoint documentation for more information.

To create a new API client (property), complete the following procedure:

  1. In the Janrain Console, click Manage Properties.
  2. On the Manage Properties page, click Create Property.
  3. On the Create Property page, enter the name of the new API client in the Name field. Although you can give the new API client any name you wish, we recommend that you select a name that indicates that the client will be used with the ProfileSync service.
  4. In the Features list, clear the login_client checkbox and then select direct_access.
  5. Click the Create Property icon to save the new API client.

Adding ProfileSync Custom Settings

After creating the new API client, you must add a pair of settings – prs_target_settings and prs_events – to that client. These two settings are described below.

prs_target_settings

prs_target_settings is a JSON object that contains all the information needed to configure the connection between ProfileSync and Salesforce. The prs_target_settings JSON object looks similar to this:

[
    {
        "target": "salescloud",
        "settings": {
            "tokenurl": "https://login.salesforce.com/services/oauth2/token",
            "serviceurl": "/services/data/v41.0/sobjects/Contact",
            "client_id": "LZdRBOskMwLlkHHxkDkHO1Gu9GaTCUEE.eXwLEewVOPtU4y0mZfhuLobON9",
            "client_secret": "35285136908642478",
            "private_key": "-----BEGIN RSA PRIVATE KEY-----\nMIIEpAIBAAKCAQEAsIxCf2+6RZDKqQfZn0uJ24Tab6v9Hc09WD+ZNNd0WE95+AMM\nXJ8lX55rhNnluSjReNSgbLaOQGSayp0bAm0NBetMAc6b3T1HXnzk9tXF6wwPUU7x\n8SM3yTWK6hfXYUN/V4OEeVL9SZjRo4GcWtKhOQxDBNwVsjCUMJ703vDHEvlOrr2K\nigxYqNYyi3HgrFDGWnT3dKFhcxdXZovNKjzvCyLGYIczCeNDR9ModUEU6GDOlfk6\nocNrWiG63+g1nKNKTCDeLpWLqGeQMnRVSjbH4Z3AMHZrSmdbxlD84GvmB3Q6Yp0M\n7MWU+YhOO1boovVj1l+bmc/vedLRlzkzIH+odwIDAQABAoIBAQCrBSPBiPybONho\nhzczjRwc7wQemy+Vt+RN4UXLH08P4OVY77MA4hV1G+QxjFZxV+4aq3Y/+VOxYwNj\ndG7emb681iMJuRfZZ+wDxt6RkaGowETyUZQjMCdxHRHVFIVKLfVkU/12/YJo0cV6\nKyrH/DO7LHqbcYr+0voqY0D32awuXn9bfe+jN6isg3PMp71zKa5/Pqa2Uo+cLeGu\nhtMu6jlJ2InJOwxLX4Yq1fTG5dQupcRKnuE0xxm2m6ooFlF0y8WW7NRcrjIAhncP\njEG/atziF9oElIC3bl3AOCNp+OtOdnynaJuc+5uTrvgCWzqID3VX9wisuJgn8SlD\nq8bWFBGhAoGBAOjFC0fhotMYsvp9W6Y8XjhyPehiQb/GHCb/R1KH8TxFvDb6Ehui\n1UBKboPDvtvkESYZKgVk/4I1TwJXnm7wTjzxNyJKuCwvoaj1HFFwsr15exHTgFDe\niZy1h/Fcf3xUGG97gRXLT6m/vS5hrTNHyY9YKSGqmnwa9ntNmMvwE4mnAoGBAMIq\n0r7JwVxqTPQbmv8IGnPm8bqqJ2EQmMox/y69hGGyzLUlFolUYp5LSZZQdAlHXvlA\ne7iJB50Rn4SLAyAYpqSnYO+dxT1xbI7YIdFXLTBFistg/uekGCXHGdEAAS7TSMd0\nmD7OGuBBnkTJQgnlL5MWyoNSrA200bHRGb3PjiSxAoGAGeunX+/Oc/dyJtbC1/Ys\n/9go8LHQZIypIeaXiKc+w9l4Jh8e2Rj+6lPfjqjDnjT9e+KdfVBL67IIBFjBedUk\nwUCTRSxQ6gq709bHuoH0RYk7nTaSOW8un9bPNp94St4Kgo+cRlMHof2KEZoq8WTz\nGxVULz2SSnOuMvjnJP6tDk0CgYBYwcaQXB29pwICXFQf3I5rCNjbIUjbAAE3/F7P\n+OX42wjkjU2d/SsPfQ7oXWKNk0iA288ybcFDNXkb14fYNiyG+9Q99HrjOWQMcBQV\nY6pOdJubmH0tWj+HlVnhxgTEaOTN+ChYHVL/zD8S5oT/jPqQXEy6dyIbKdrpU9JW\nh/hMIQKBgQCpBAmT9pioYHBpF86qzpkCHAdZqj4Ve09YRNsG/UAnnluWP8iY/xS0\nJkdeRXN6JIbr+vGbPMwE8sDlkq0mxT4UTTqD5E/QByDJNVic3Yg46qj98wV5rgZk\ndvPkeMqLWLg1FV+EpWZzeewfjm0gysvqpqKXnijd8QBMcpFnBPpNAQ==\n-----END RSA PRIVATE KEY-----",
            "private_key_alternate": "",
            "retry_sequence": "[30, 60, 120, 300, 900]",
            "retry_count": 8,
            "notification_email": "alert@example.com",
            "mappings": [
                { "src": "uuid", "trg": "Uuid"},
                { "src": "email", "trg": "Email"},
                { "src": "givenName", "trg": "FirstName"},
                { "src": "familyName", "trg": "LastName"},
                { "src": "birthday", "trg": "Birthdate"},
                { "src": "primaryAddress.address1", "trg": "Mailing Address.Street"},
                { "src": "primaryAddress.zip", "trg": "Mailing Address.PostalCode"},
                { "src": "primaryAddress.city", "trg": "Mailing Address.City"},
                { "src": "primaryAddress.country", "trg": "Mailing Address.CountryCode"},
                { "src": "primaryAddress.phone", "trg": "Home Phone"},
                { "src": "primaryAddress.mobile", "trg": "Mobile"}
            ]  
        }  
    }
]

Each of these JSON settings – target, tokenurl, serviceurl, etc. – are described in the following table.

Setting *Type * Description
target string Unique identifier used by ProfileSync to differentiate target APIs. The target value for Salesforce is salescloud.
tokenurl string URL for the Salesforce token endpoint. ProfileSync contacts the token endpoint to request an OAuth 2.0 access token. For more information, see the article OAuth 2.0 JWT Bearer Token Flow.
serviceurl string Salesforce service URL used to update the Salesforce Contact object. Although subject to change, the current Salesforce service URL is /services/data/v41.0/sobjects/Contact.
client_id string Consumer key for your Salesforce connected app. The consumer key is found on the app’s home page.
client_secret string Consumer secret for your Salesforce connected app. The consumer secret can also be retrieved from the app’s home page; click Click to reveal to display the secret.
josn_claims json JSON object used to construct the JSON Claim Set for the JWT token. At a minimum, the json_claims setting should contain the iss, sub and aud claims. The exp claim is automatically added by ProfileSync.
private_key string PEM (Privately-Enhanced Mail)-formatted private key used to sign the JSON web tokens used in the ProfileSync-to-Salesforce workflow. See Appendix C: Private Keys for more information.
retry_count integer Number of times that ProfileSync attempts to make a data transfer before giving up and writing the event in the dead letter queue. The default value is 20.
retry_sequence json array of integers Amount of time (in seconds) that ProfileSync waits before retrying a failed data transfer. The retry sequence is specified as an array of integers; for example:

[30, 60, 900]

In this example, after a failed transfer ProfileSync waits 30 seconds before trying again. If the operation fails a second time, ProfileSync waits 60 seconds before making the next attempt. If a third attempt (or fourth or fifth or ….) ProfileSync waits 900 seconds (15 minutes) between tries.

You can specify up to 20 values in the retry_sequence, one for each potential retry. You can also specify a single value:

[30]

In the preceding example, ProfileSync always pauses for 30 seconds between delivery attempts.

The maximum allowed wait time is 9000 seconds (2.5 hours).
notification_email string Email address where dead letter queue notifications are sent. Every Monday an automated program checks the dead letter queue for events that could not be written to the target API. An email notification is then sent to this address; if you do not respond to that notice within 5 days the corresponding event is permanently deleted from the dead letter queue.
mappings json array of objects Maps Janrain attributes (the source, or src, attributes) to their corresponding Salesforce attributes (the target, or trg, attributes). For example, suppose Janrain refers to a user’s last name as the familyName, and Salesforce refers to this same attribute as the FamilyName field. In that case, the mapping would look like this:

{ “src”: “familyName”, “trg”: “LastName”}

A list of the more-common data mappings can be found in the Updating the Salesforce Schema section of this document.

The prs_target_settings setting must be assigned to the application (global) scope: you cannot add this setting to individual API client. To add the prs_events global setting:

  1. In the Janrain Console, on the Manage Application page, click Edit Settings.
  2. On the Edit Settings page, click the Add Setting icon.
  3. In the Select setting key field, type prs_target_settings and then click the Create prs_target_settings button.
  4. In the Value field, paste the JSON object containing the target settings. Note that, as long as this is properly-formatted JSON, you can paste it into the field even though the object contains multiple lines.
  5. Click the Save Changes icon to save the new setting.

prs_events

The prs_events setting maps Janrain events to your target API. Different versions of this setting can be applied to different API clients; this provides flexibility in determining which client is responsible for which events. For example, you could have an API client that is responsible for handling user profile creations, and a separate API client that only handles profile deletions. You will work with your Janrain representative to determine your event/client mappings.

By default, ProfileSync monitors for the following Janrain user profile events, then replicates the updated profile information to Salesforce:

*Janrain Event * Description *Salesforce Event *
add_user A new user profile is created. A new Contact is created.
update_user An existing user profile is updated. Note that this event is only triggered if an attribute mapped to ProfileSync is updated. If you are monitoring email addresses and an email address is changed, this event is fired. If you are not monitoring user first names, however, this event will not be fired if a user changes his or her first name. The appropriate Contact fields for the user (identified by his or her Janrain UUID) are updated.
forget_user A user deactivates his or her account. This event is based on changes to the deactivateAccount attribute. The Salesforce field mapped to the deactivateAccount attribute is updated to indicate that the Contact (identified by Janrain ID) no longer has a Janrain profile.

For Salesforce, the prs_events JSON object will look similar to this:

[
    {
        "event": "add_user",
        "target": "salescloud"
    },
    {
        "event": "update_user",
        "target": "salescloud"
    },
    {
        "event": "forget_user",
        "target": "salescloud"
    }
]

In the preceding example, three events – add_user, update_user, and forget_user – are targeted to salescloud (Salesforce).

The prs_events setting can be added at the global scope or at the local (individual API client) scope. In this example, we’ll add the setting to the API client we just created.

To add the prs_events client setting:

  1. In the Janrain Console, on the Search Properties page, click the name of your API client.
  2. On the Edit page, scroll to the bottom then click Edit Settings.
  3. On the Edit Settings page, click the Add Setting icon.
  4. In the Select setting key field, type prs_events and then click the Create prs_events button.
  5. In the Value field, paste the JSON object containing the event settings. Note that, as long as this is properly-formatted JSON, you can paste it into the field even though the object contains multiple lines.
  6. Click the Save Changes icon to save the new setting.

Appendix A: ProfileSync Capabilities

Technical details about ProfileSync and its capabilities are summarized in the following table:

Data Integration ProfileSync Capability
Data frequency Real-time data delivery by default. However, ProfileSync can also be configured to do batch delivery.
Data delivery Carried out using webhooks and the Janrain API.
Data sent to Any public-facing API, message queue, or file server.
Data scope User profile creation, modifications, and deletions.
Target data format JSON, XML, CSV or other delimiter. ProfileSync can support any data format that has a supporting library.
Transform logic Simple transforms. Complex transforms by using services.
Plural support Yes. (Plurals are Janrain attributes that can contain multiple values.)
Consent awareness Yes, when using Janrain ProfileConnect.
Restrictions No two-way syncs, midstream external calls, custom enrichments, complex ETL (extraction, transform, load), or data analytics.

Appendix B: The Janrain Webhook Event Notification

When a user profile is created, modified, or deleted, a Janrain webhook sends a notification to ProfileSync. If ProfileSync is unable to complete data delivery, that same JSON object is written to the dead-letter-queue. The JSON object in question includes the following fields:

Field *Description
entityType The Janrain entityType (user profile database) that contains the modified user profile.
tenant Internal code used to distinguish target applications.
source Source of the event. This will typically be JANRAIN.
user The UUID of the user whose profile has been created, modified, or deleted.
type Either a null value or a hashed value indicating the type of action that took place (e.g., “update”).
subtype Either a null value or a hashed value indicating the subject of the action that took place (for example, “email” if the action that took place was to update the user’s email address).
client Client ID of the Janrain API client involved in the event.
timestamp Date and time when the event took place.

Appendix C: Private Keys

The access tokens used in the ProfileSync-to-Salesforce workflow are signed by using PEM private keys. PEM (Privately-Enhanced Mail) is a base64-encoded file format commonly used for transmitting data, including cryptographic keys and certificates. A PEM private key looks similar to this:

-----BEGIN RSA PRIVATE KEY-----
BNzc1MUjAT2+R0OIDQVNlT7C+lTBmkgO1jsMiglg681BiHQ4iW1yrwp6EaMefScQ
GXnNg0JskqrecZvz7UH8dreXN5xXQsSQ8qwoogHVhTpOuQd2q6CVDQJyKz/WUUVV
tJDf/4NtQx7l1M5IqcHbdl2kQP3eKwiHOVIYF4TLfJLBAAbiyetYB4i8cdKMtqWz
TCoqfRmfjMBJpyQZRtpEmH1AP2flC/9uh7DoGdc4WX/L92j4bpP6/2Jsv0xhxGgc
GA1RFjJfxtTHdoYGf8Q9oywRMN4yZ6BNA/ZGinufjpKlDGt7vR+raJmJpydUIbBU
jrN0GuJ07p3c3nLb2bjKgyRTTsiKa3FxpowfoibmfFLYiqDN2o6tBBCFn1VV0HrB
hT0QSXnEbPpiivw60i1h3VbCxul5vIGiJGkJYzt2eWxrfXypk+9F2vK2LWnShaal
q44lfLyxJJHtB/bAMmF3+yzYWPIVoqbyuxzD6mau8sl+ffhN+FwkXKoFYEdP0ErJ
NJNTc+0YffbbHniiC7k9Y89ESpnRIqyk6AypMw4du4ERO+GkS9Pn7a8h+vcR2WRY
YdQKAyYQ1+Oo34TTZbAJajYT5CWLsRWYEuDmkeRcEiK26r+eKCq7DgP51xHIvQCD
erMyTvMkfcnmvt1XzzF6TU7bySeHBnate2B0wIBV9eFGxLFhCDXf9kwh47Y/dTLL
tmRLDTsWene+7D+N+tTePZbhA5c4VXN+aH0zTEusAeToeczVeOliv7RYz92qRicT
NxmoWEBOXxXTKOFyq6XxXukNo/sYf0c9Wj3ESssHsOSnAHXh447kyHDB/LLFKyMx
mYZlOPDU8wqB0UwecRnWyP85g10E6kuX2DqOsHZI30NJzQlodIgugO2coW/u068k
k/RXGQ7akpD2H94+0lQlpXN5ZtuCNFAxU3Ee38KfkzROJ9EtVJP3MhA1rOlWppRY
NOyyaB5t1WYGBl0U5+JaL6o1AifanAkdZz1D/tayk159Hf9yhUAMBceGHqejmBZz
eNeOjkitOtgeRibG7KWTbT2GLQxK+2eoeTPNGhSaTW+Wo1wsQTZjj/3M+YMsLyWw
fAmvCU56frsmUcfro75X9KWq8qEIHSvmV8H/52Z0JaX6BgFe9kZj/hv5rXE2EcMP
e3HSzSOwtee7Ud77/GeIgKyKGnfeQ+8Dd2y5PvnHSocmlDMCcW95Zt5Q3y5xpTzM
Qh/Wm7ASE79mAvgC80ZDqtD7mtfZEc/D9j1T5mbF8BxO5nomJgSdPjbjrSiFbFx4
sUKTEGAABG0ZBr1Abm7V5HY90PFGiaTsNcnwzoFz1Uztu0vZgqzlbPDfE/ocAbMI
7wFTw6JrsRPARjtWt/L+rT0LVi/kHJ2RFI7JZHvJfpuGWXR09L+uP2lxuxLq0W1B
j9EINeQ3xb50F+z+R1FHzGwY4Zl4jJbwXGu04Kn7Wp5OT+A7u8QhKNlpoCgP9HW3
xvQtv9vNmLu0XPsoZkc/fCMhb4PAan/GGDCNPNTLEPN21G4cA60OqYFeFPmlGvKG
R27awCAcu2xyUMWdlS3iDPmXRdp320r4wobYq4LApMJqABhzqFttIDwqMw/bDEY3
-----END RSA PRIVATE KEY-----

Although it might not look like it, the preceding private key consists of three lines:

  • The line —–BEGIN RSA PRIVATE KEY—–.
  • The key itself (BNzc1MUjA … qMw/bDEY3).
  • The line —–END RSA PRIVATE KEY—–.

That’s important to know, because this three-line key must be converted to a single line before it can be used in your JSON file; this is done by replacing the newline characters at the end of the first two lines with \n. In other words, the private key must be formatted like this:

-----BEGIN RSA PRIVATE KEY-----\nBNzc1MUjA … qMw/bDEY3\n-----END RSA PRIVATE KEY-----
Scroll ↓