PingOne Advanced Identity Cloud

Create a script in a journey to record last login time

Description

Estimated time to complete: 20 minutes

In this use case, you duplicate an existing journey and modify it to record the time the user logs in to the Advanced Identity Cloud end-user UI. You use a script in your journey to record the login time.

Goals

After completing this use case, you will know how to do the following:

  • Create a script to use in a journey, referred to as a journey decision script.

  • Change a field name in the end user profile.

  • Adapt a journey to record shared state data in the end user profile.

Prerequisites

Before you start work on this use case, make sure you have:

  • A basic understanding of:

    • JavaScript.

    • Journeys and nodes.

    • Realms.

    • The Advanced Identity Cloud admin UI.

    • The Advanced Identity Cloud end-user UI.

    • The managed/alpha_user object schema.

  • Access to your Advanced Identity Cloud development environment as an administrator.

  • A test identity in Advanced Identity Cloud.

Tasks

Task 1: Create a journey decision script

A journey decision script runs in Advanced Identity Cloud during an authentication journey. It’s called a decision script because it’s programmed to decide how the journey continues.

When the script runs, it can also read and change the shared state of the journey. In this example, the script adds a timestamp to record when it runs in the shared state.

Later, nodes can use the shared state data to take action. You can configure nodes to use shared state data and script the actions Advanced Identity Cloud takes. In this example, a later node writes the timestamp in the authenticating user’s profile.

  1. Log in to the Advanced Identity Cloud admin UI as an administrator.

    Select the alpha realm if it is not selected by default.

  2. In the left menu pane, select Scripts > Auth scripts and click + New script.

  3. Select Journey Decision Node and click Next to open the script editor.

  4. Set the fields as follows and click Save and Close:

    Field Value

    Name

    last-login-time

    Description

    Set last login time. Use this after successful authentication.

    JavaScript

    		 
    function tag(message) {
    return '*** last-login-time: '.concat(message)
}

var lastLoginAttribute = 'frUnindexedDate1'
var lastLoginTime = new Date().toISOString()
sharedState.get('objectAttributes').put(lastLoginAttribute, lastLoginTime)
logger.message(tag('Setting ' + lastLoginAttribute + ' to ' + lastLoginTime))
outcome = 'Success'

    The script sets the shared state objectAttributes.frUnindexedDate1 to the current time as an ISO date string. Managed users have many optional fields. The frUnindexedDate1 field is one of them. The script sets this field in objectAttributes, the attributes of the managed user object, so a later node can write the updated frUnindexedDate1 value from shared state to the user’s profile.

    The frUnindexedDate1 field is an unindexed field, meaning Advanced Identity Cloud does not maintain a search index for the field. If applications look up profiles based on the last login time, use one of the frIndexedDate* fields instead.

    Notice the following objects from Advanced Identity Cloud bound to the journey decision script execution context; the script uses them directly without having to define them first:

    • sharedState: Use this to access the shared journey state.

    • logger: Use this to log debug messages.

    • outcome: Set the outcome to a string as the last processing step.

    There is no authentication decision to make, so the script’s only outcome is Success. You include each outcome in the Scripted Decision node Outcomes setting when using the script in a journey.

Check in

At this point, you:

Created a script to add last login time to the journey’s shared state data.

Task 2: Update the target managed user field

By default, the label in the Advanced Identity Cloud end-user UI for the frUnindexedDate1 field is Generic Unindexed Date 1. The journey uses this field for last login times; therefore, you change the label to Last Login Time for readability.

  1. In the left menu pane of Advanced Identity Cloud admin UI, select Native Consoles > Identity Management.

    The IDM admin UI dashboard displays.

  2. In the top menu of the IDM admin UI, select Configure > Managed Objects and click the card for Alpha_user to edit the managed object properties.

  3. Scroll to the frUnindexedDate1 row and click it to edit the property.

  4. Set the fields as follows and click Save:

    Field Value

    Readable Title

    Last Login Time

    This changes the label in the Advanced Identity Cloud end-user UI.

    Show advanced options > Searchable

    Enable this.

    Show advanced options > User Editable

    Disable this.
Check in

At this point, you:

Created a script to add last login time to the journey’s shared state data.

Configured the Last Login Time label in the Advanced Identity Cloud end-user UI.

Task 3: Create a last login journey

You base the last login journey on the default Login journey. To reference the script, you add a Scripted Decision node. To write the last login time to the user’s profile, you add a Patch Object node.

Duplicate the default login journey

  1. In the left menu pane of Advanced Identity Cloud admin UI, select Journeys

  2. Select the More () menu for the default Login journey and select Duplicate to display the Duplicate Journey modal.

  3. Set the fields as follows and click Save:

    Field Value

    Name

    Log in and set last login time

    Identity Object

    Alpha realm - Users managed/alpha_user

    Description

    Duplicate of default Login journey that also sets last login time

    The Advanced Identity Cloud admin UI displays the journey editor.

Configure your last login time journey

  1. In the journey editor, find these nodes to drag and drop them onto the journey canvas:

    • Scripted Decision node

    • Patch Object node

  2. Select the Scripted Decision node and set the fields as follows:

    Field Value

    Name

    Last login time

    Script

    last-login-time

    Outcomes

    Success

    Leave the default settings for other fields.

    When the journey reaches this node, your journey decision script runs.

  3. Select the Patch Object node and set the fields as follows:

    Field Value

    Identity Resource

    managed/alpha_user

    Leave the default settings for other fields.

    When the journey reaches this node, it updates the managed/alpha_user object properties with the shared state objectAttributes fields including the frUnindexedDate1 field set by your script. This update stores the last login time in the end user’s profile.

  4. Reconnect the Scripted Decision node True outcome to the Last login time node input.

  5. Connect the Last login time node outcome to the Patch Object node input.

  6. Connect the Patch Object node Patched outcome to the Increment Login Count node input.

  7. Connect the Patch Object node Failed outcome to the Failure node.

At this point, the authentication journey is complete. The following shows a rectangle around the nodes you added after duplicating the default journey:

Last login time journey

  • a Collects the username and password.

  • b Validates the username and password.

  • c Records the time in the shared state object attributes on frUnindexedDate1.

  • d Writes the time to the user’s profile.

  • e Increments the number of authentications.

  • f Triggers an inner journey; in this case, a journey for progressive profiling.

Check in

At this point, you:

Created a script to add last login time to the journey’s shared state data.

Configured the Last Login Time label in the Advanced Identity Cloud end-user UI.

Duplicate and configured a journey to record the last Login time.

Task 4: Check journey path connections

Use the following table to check the connections for each node in the Log in and set last login time journey.

Some nodes have more than one outcome. The → symbol means the node only has one outcome path.

Source node Outcome path Target node

Start (person icon)

→

Page node

Page node containing:

  • Platform Username node

  • Platform Password node

→

Data Store Decision node

Data Store Decision node

True

Scripted Decision node

(Last login time)

False

Failure node

Scripted Decision node

(Last login time)

→

Patch Object node

Patch Object node

Patched

Increment Login Count node

Failed

Failure node

Increment Login Count node

→

Inner Tree Evaluator node

Inner Tree Evaluator node

True

Success node

False

Failure node

Validation

Now that you have created your script, updated a label in the Advanced Identity Cloud end-user UI, duplicated the default Login journey, and updated the copy to record the last login time in the user’s profile, you are ready to validate the journey.

Before validating, make sure you have a test user in the alpha realm.

Steps

  1. Get a URL you can use to test the journey:

    1. Log in to the Advanced Identity Cloud admin UI as an administrator.

    2. Select Journeys.

    3. Select the journey you created, Log in and set last login time.

      A preview screen of the journey displays.

    4. Click the copy icon next to Preview URL, a URL you can use to test the journey as an end user:

      Copy the test URL for the journey

  2. Log in to the Advanced Identity Cloud end-user UI:

    1. Paste the URL into an incognito window.

      Use incognito mode for testing to avoid caching issues and interference with any current sessions.

      The Advanced Identity Cloud end-user UI displays the login screen.

    2. Enter the test user’s username and password.

    3. Click Next.

      The Advanced Identity Cloud end-user UI displays the test user’s profile.

  3. Click Edit Your Profile to display the profile screen then Edit Personal Info to display the profile fields.

  4. Scroll to the Last Login Time field.

    The field contains the timestamp written when the test user logged in:

    Last login timestamp

    The Advanced Identity Cloud end-user UI appends (optional) to the field name for managed object properties without Required enabled.

Video of validation

From the end user’s perspective, the journey works as follows. The video starts with the test user logged in before trying the last login time journey:

Explore further

Reference material

Reference Description

Admin interfaces in Advanced Identity Cloud

Get to know the admin interfaces; Advanced Identity Cloud admin UI, AM admin UI, and IDM admin UI.

Journeys

Conceptual information on journeys and their purpose in Advanced Identity Cloud.

Introduction to journeys with ForgeRock University

A guided video of journeys in Advanced Identity Cloud and how to use them.

Nodes for journeys

Learn about the configurable nodes Advanced Identity Cloud offers for use in journeys.

User identity attributes and properties reference

Reference information for end user profile properties.

Scripted decision node API

Reference information for journey decision node scripts.

Nodes used

The last login time journey uses the following nodes: