Configure a Progressive Profile Completion Form

If you're testing progressive profile completion, you can start from the selfservice-profile.json file in the following directory: openidm/samples/example-configurations/self-service/

Copy this file to your project's conf/ directory and start IDM. After the conditions shown in this configuration file are met, end users will see a form prompting them to add a telephone number. 

{
    "stageConfigs" : [
        {
            "name" : "conditionaluser",
            "identityServiceUrl" : "managed/user",
            "condition" : {
                "type" : "loginCount",
                "interval" : "at",
                "amount" : 25
            },
            "evaluateConditionOnField" : "user",
            "onConditionTrue" : {
                "name" : "attributecollection",
                "identityServiceUrl" : "managed/user",
                "uiConfig" : {
                    "displayName" : "Add your telephone number",
                    "purpose" : "Help us verify your identity",
                    "buttonText" : "Save"
                },
                "attributes" : [
                    {
                        "name" : "telephoneNumber",
                        "isRequired" : true
                    }
                ]
            }
        }
    ]
}

The following table includes a detailed list of each property shown in this file:

The selfservice-profile.json File
PropertyDescription
stageConfigsProgressive profile completion is a stage of user self-service.
nameconditionaluser sets up conditions for end users.
identityServiceUrlmanaged/user specifies IDM Managed Users.
conditionCondition when to display the form.
typeType of condition; for a list of conditions, see "Progressive Profile Completion Conditions".
evaluateConditionOnFieldIDM evaluates the condition, per user.
onConditionTruePresents the form with the following properties.
nameData that you collect with the form is an attributeCollection.
uiConfigLabels to include the in the form seen by the end user.
displayNameForm title.
purposeForm explanation.
buttonTextCustomizable.
attributesAttribute name from managed.json.
isRequiredIf an end user has to enter data to complete a connection to IDM.

The default progressive profile completion process involves two mandatory stages:

With the previous configuration, users logging in to the End User UI must submit a telephone number on the 25th login.

Progressive Profile Completion Conditions

You can set up a number of different conditions for when users are prompted to add information to their profiles. IDM includes the following pre-defined criteria:

loginCount

May specify at or every number of logins, as defined by the following value: amount.

Note

End users can bypass progressive profile completion screens, when configured with a loginCount. Every time they see such a request, they can open a new browser window to bypass that request, and log in to the End User UI. They won't have to provide the information requested, even if you've set the attribute as Required under the Attributes tab.

timeSince

May specify a time since the user was created, the createDate, in years, months, weeks, days, hours, and minutes.

profileCompleteness

Based on the number of items completed by the user from managed.json, in percent, as defined by percentLessThan; for more information, see "Defining Overall Profile Completion".

propertyValue

Based on the value of a specific user entry, such as postalAddress, which can be defined by "Presence Expressions".

Custom Progressive Profile Conditions

You can also set up custom conditions with query filters and scripts. These criteria may deviate from standard query filters described in "Construct Queries" and standard scripted conditions described in "Add Conditional Policy Definitions".

  • A queryFilter. For example, the following query filter checks user information for users who live in the city of Portland: 

    "condition" : {
       "type" : "queryFilter",
       "filter" : "/city eq \"Portland\""
       },

    In addition, you can also reference metadata, as described in "Track User Metadata". For example, the following query filter searches for users with:

    • A loginCount greater than or equal to five.

    • Does not have a telephone number:

    "filter" : "(/_meta/loginCount ge 5 and !(/telephoneNumber pr))"

    Warning

    If you include _meta in query filters, the Admin UI will not work for the subject progressive profiling form.

    While it's technically possible to include a number like 5 in the Admin UI with the query filter, IDM would write the number as a string to the selfservice-profile.json file. You'd still have to change that number directly in the noted file.

  • An inline script (scripted), or a reference to a script file; IDM works with scripts written in either JavaScript or Groovy. For example, you could set up a script here: 

    "condition" : {
       "type" : "scripted",
       "script" : {
       "type" : "text/javascript",
       "globals" : { },
       "source" : "<some script code>"
       },

    Alternatively, you could point to some JavaScript or Groovy file: 

    "condition" : {
       "type" : "scripted",
       "script" : {
       "type" : "text/javascript",
       "globals" : { },
       "file" : "path/to/someScript.js"
       },

    For the script code, you'll need to reference fields directly, and not by object.field. For example, the following code would test for the presence of a telephone number: 

    typeof telephoneNumber === 'undefined' || telephoneNumber === ''

    While you can also reference metadata for scripts, you can't check for all available fields, as there is no outer object field. However, you can refer to fields that are part of the user object.

Configuring Progressive Profile Completion Through the Admin UI

The UI is straightforward; in the Admin UI, when you select Configure > Progressive Profile, you'll add a New Form, with:

  • Attributes defined in managed.json.

  • Conditions that may be based on a query filter, a script, or pre-defined criteria such as number of logins.

What you configure in the Admin UI is written to the selfservice-profile.json file. The information under the following Admin UI Progressive Profile Completion page tabs is written to the following code blocks in that file:

  • Details: uiConfig

  • Display Condition: condition

  • Attributes: attributes

Warning

When you use the UI, you must specify a property under the Attributes tab. Otherwise, IDM won't display a Progressive Profile form. To specify a property, select Configure > Progressive Profile. Select a Progressive Profile form > Attributes tab > Add a Property. Be sure to select an Attribute Name based on user properties configured in the managed.json file.

Read a different version of :