--- title: Action class description: The Node class returns an Action instance from its process() method. component: pingam version: 8.1 page_id: pingam:auth-nodes:core-action canonical_url: https://docs.pingidentity.com/pingam/8.1/auth-nodes/core-action.html keywords: ["Extensibility", "Nodes & Trees", "Scripts"] section_ids: action_fields_and_methods: Action fields and methods --- # Action class The `Node` class returns an `Action` instance from its `process()` method. The `Action` class encapsulates changes to authentication tree state and flow control. For example, the following implementation demonstrates an authentication level decision: ```java @Override public Action process(TreeContext context) throws NodeProcessException { NodeState state = context.getStateFor(this); if (!state.isDefined(authLevel)) { throw new NodeProcessException("Auth level is required"); } JsonValue authLevel = state.get(authLevel); boolean authLevelSufficient = !authLevel.isNull() && authLevel.asInteger() >= config.authLevelRequirement(); return goTo(authLevelSufficient).build(); } ``` Learn more in the [Action](../_attachments/apidocs/org/forgerock/openam/auth/node/api/Action.html) class. ## Action fields and methods The `Action` class uses the following fields: | Fields | Description | | ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `callbacks` | A list of the callbacks requested by the node. This list may be `null`. | | `errorMessage` | A custom error message string included in the response JSON if the authentication tree reaches the [Failure node](https://docs.pingidentity.com/auth-node-ref/8.1/failure.html).Each node in a tree can replace or update the error message string as the user traverses through the authentication tree.If required, your custom node or custom UI must localize the error string. | | `identifiedIdentity` | The identity that's confirmed to exist in an identity store. | | `lockoutMessage` | A custom lockout message string included in the response JSON when the user is locked out.If required, your custom node or custom UI must localize the error string. | | `logoutHooks` | The list of logout hooks that run synchronously after logout. | | `maxIdleTime` | The maximum idle time for the user. | | `maxSessionTime` | The maximum session time for the user. | | `maxTreeDuration` | The maximum duration of the journey session. | | `outcome` | The result of the node. | | `returnProperties` | A map of properties returned to the client.Use the `withHeader`, `withStage`, and `withDescription` methods to add a property to the map. | | `sessionHooks` | The list of classes implementing the TreeHook interface that run after a successful login. | | `sessionProperties` | A map of properties added to the final session if the authentication tree completes successfully.Use `putSessionProperty(String key, String value)` and `removeSessionProperty(String key)` to add or remove entries from the map. | | `sharedState` and `transientState` | *Deprecated*.Use the `NodeState` object instead. Learn more in [Store values in a tree's node states](store-values-shared-state.html#store-values-in-transient-state). | | `suspendDuration` | The length of time a journey session is suspended. | | `webhooks` | The list of webhooks that run after logout.Use the `addWebhook` and `addWebhooks` methods to populate this list. | The `Action` class provides the following static methods to create an `ActionBuilder`: | Methods | Description | | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `goTo` | Specify the exit path to take, and move on to the next node in the tree.For example:```java return goTo(false).build(); ``` | | `send` | Send the specified callbacks to the user for them to interact with.For example, the [Username Collector node](https://docs.pingidentity.com/auth-node-ref/8.1/am-only/username-collector.html) uses the following code to send the `NameCallback` callback to the user to request the `USERNAME` value:```java return send(new NameCallback(bundle.getString("callback.username"))).build(); ``` | | `sendingCallbacks` | Returns true if the action is a request for input from the user. | | `suspend` | Suspends the authentication tree and lets the user resume it from the point it was suspended. You can also control how long it is suspended for.For example, the following call is taken from the [Email Suspend node](https://docs.pingidentity.com/auth-node-ref/8.1/email-suspend.html):```java return suspend(resumeURI -> createSuspendOutcome(context, resumeURI, recipient, templateObject)).build(); ```Use the [SuspensionHandler](../_attachments/apidocs/org/forgerock/openam/auth/node/api/SuspensionHandler.html) interface for handling the suspension request. | The inner class `ActionBuilder` provides the following methods for constructing the `Action` object and setting action-related properties: | Methods | Description | | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `addNodeType` | Add a node type to the session properties and shared state. Replace any existing shared state with the specified TreeContext's shared state. | | `addSessionHook` and `addSessionHooks` | Add one or more session hook classes for AM to run after a successful login.Learn more in [Register an authentication tree hook](../am-authentication/post-authn-plugins-treehook.html#register-tree-hook). | | `addWebhook` and `addWebhooks` | Add one or more webhook names to the list of webhooks. | | `build` | Creates and returns an Action instance providing the mandatory fields are set. | | `putSessionProperty` | Add a new session property. | | `registerLogoutHook` | Register a logout hook.Learn more in [Register a logout hook](../am-authentication/create-logout-hook.html#register-logout-hook). | | `removeSessionProperty` | Remove the specified session property. | | `replaceSharedState` and `replaceTransientState` | *Deprecated*.Use the `NodeState` object instead. Learn more in [Store values in a tree's node states](store-values-shared-state.html#store-values-in-transient-state). | | `withDescription` | Set a description for this action. | | `withErrorMessage` | Set a custom message for when the authentication tree reaches the failure node. | | `withHeader` | Set a header for this action. | | `withIdentifiedIdentity` | Add an identity, authenticated or not, that's confirmed to exist in an identity store. Specify the username and identity type or an `AMIdentity` object.Use this method to record the type of identified user. If the advanced server property, `org.forgerock.am.auth.trees.authenticate.identified.identity` is set to true, AM uses the stored identified identities to decide which user to log in.This lets the authentication tree engine correctly resolve identities that have the same username.Learn more in [advanced server properties](../setup/deployment-configuration-reference.html#org.forgerock.am.auth.trees.authenticate.identified.identity). | | `withLockoutMessage` | Set a custom message for when the user is locked out. | | `withMaxIdleTime` | Set the maximum idle time for the authenticated session in minutes.This overrides the [maximum idle time](../am-sessions/session-state-session-termination.html#auth-session-termination-config) set in the journey or the Session service. If a user has session timeouts set, the user-specific settings are always used. | | `withMaxSessionTime` | Set the maximum authenticated session time in minutes.This overrides the [maximum authenticated session time](../am-sessions/session-state-session-termination.html#auth-session-termination-config) set in the journey or the Session service. If a user has session timeouts set, the user-specific settings are always used. | | `withMaxTreeDuration` | Set the maximum duration of a journey session in minutes.This overrides the [maximum duration](../am-authentication/suspended-auth.html#maximum-duration) set in the journey or authentication settings. | | `withStage` | Set a stage name to return to the client to aid the rendering of the UI. The property is only sent if the node also sends callbacks. | | `withUniversalId` | *Deprecated*.Use `withIdentifiedIdentity` instead. | Learn more about the supported methods in [ActionBuilder](../_attachments/apidocs/org/forgerock/openam/auth/node/api/Action.ActionBuilder.html).