ULM Processes: Overview

Content

• Overview
• Process Framework
• How Process Interactions Work (with Examples)
• Versioning
• Authorities
• Revision History

Overview

Amdocs' MarketONE User Lifecycle Management Cloud (or ULM Cloud) is powered by set of business Processes that shape and streamline user journeys.

Process Framework

ULM Cloud includes the ULM Process framework. This framework executes workflows through a suite of lightweight, digestible, and predictable REST APIs. Unlike traditional APIs which behave in an atomic manner, ULM Processes enable more complex, multi-step journeys that simple APIs do not.

Each Process is comprised of a number of Process Steps. In each step, the Process requests and/or returns resources to and from the frontend UI. The framework executes each workflow according Process business logic, configurable application settings, and user input on the client application.

The Process framework does not requires extensive upfront knowledge of how a Process works to execute it. A client application simply hits the appropriate API without the need for any payload in the request body.

Once invoked, ULM initiates a unique instance of that Process. The Process then "takes its first step" (processing on the backend) and then, if needed, responds to the client application with a prompt for required data.

The client application then provides that data – usually in the form of user input – in the body of a subsequent request, and the Process then "takes its next step" based on that data. If more data is required, ULM again responds with a prompt, and the exchange goes back and forth until the Process confirms the task is complete.

This framework enables clients (i.e., JavaScript UIs) to easily create abstraction layers around ULM Processes.

Process Steps

Whereas a standard REST API tasks consist of a single request and response, Processes can perform multiple steps. A Process takes each step based on the request sent from the client application.

Process IDs

Once a client initiates a Process, ULM Cloud issues a unique processID that identifies that particular Process' execution context. The processID is included in the initial Process response, and it must be retained by the client and provided in subsequent process step requests.

A Process automatically times out if it has not been accessed for a length of time, and must be restarted.

Multiple Points of Entry

Processes are optimized for workflows where multiple points of interaction may be required with a user. In other words, certain tasks might require a user to navigate away from the UI and then re-enter the Process from a separate location where critical information retained by the UI is not available.

To get a better idea, consider the Authenticate User Process as an example. In the simplest use case, this Process consumes and validates a user's credentials (e.g., email and password) and then opens a user session.

However, this Process optionally supports two-factor authentication (2FA) wherein a user registers an additional means by which to prove who they are, such as a backup email or mobile address. In a 2FA-enabled scenario, the Process consumes a user's credentials, checks to see if the user has a registered and required 2FA, generates a ULM Action Tokens, and sends it to that second factor as a short-form access code.

The Process then prompts the user to supply that code to the UI before they can Proceed. Once the code is provided in a PUT /process/step request, ULM Cloud validates the token and then authenticates the user.

Note: Our existing 2FA feature is currently suspended, and being re-tooled to support more user options, such as externally generated action tokens like Google Authenticator and similar third-party authenticator apps. Stay tuned for a near-future release where we'll roll out a newer, more robust 2FA that you can configure and enable for your users.

How Process Interactions Work (with Examples)

Most interactions with the Process framework executed through two basic APIs:

1. An initial API request from the client that starts up a Process.
   
   POST {{url}}/process/start/{{processName}}
   
   This API optionally requires no payload, and derives the specific task from the name and version in the invoked URL. After the request, ULM Cloud responds with a prompt for additional information
   
   
2. One or more subsequent API requests from the client continue or finish that Process.
   
   PUT {url}/process/step
   
   Information provided in each subsequent PUT /process/step request must reference the processID that ULM Cloud issued in the initial process response.
   

See the example below for a better idea of a standard Process interaction.

Note: Although POST process/start and PUT process/step are the two primary APIs that facilitate Process execution, there are additional APIs that are used in the Process framework. See the Process APIs section for more information.

API Walkthrough Example: Update Password

In this example, an application application invokes the Update Password Process.

Initial Step Request

The user is currently authenticated, and sitting in their profile.

The user clicks Update Password, and the application then invokes the following API:

POST /process/start/userManagement.UpdatePassword.v1.0

Once ULM Cloud receives the request, it then:

• Initiates a new, unique instance of the Update Password Process within ULM Cloud
• Assigns that instance a unique identifier (delivered as a processId field in the response)
• Responds to the application with a request for further input

Step Response

When the Process responds with request for further data, it includes three key items in the payload:

• A processId that identifies the unique instance of this Process
• A parameters object that contains the required data (data fields and their required format)
• A lastStep boolean that indicates whether or not this was the last step in the process

In our example, the Process asks for the user's oldPassword and newPassword as simple string values:

{
    "processId": "50212c50-d2b6-454e-a617-b30bb66eecd8",
    "processName": "userManagement.UpdatePassword.v1.0",
    "displayMessage": "Please input required information",
    "parameters": {
        "oldPassword": "String",
        "newPassword": "String"
    },
    "stepName": "PasswordPrompt",
    "lastStep": false
}

Next Step Request

Once the user provides their input, the application then invokes the PUT {url}/process/step API and passes the input back to ULM Cloud. In our example, the oldPassword and newPassword parameters would be provided like this:

{
    "processId": "50212c50-d2b6-454e-a617-b30bb66eecd8",
    "parameters": {
        "oldPassword": "letmein",
        "newPassword": "ds897!yh"
    }
}

Note: Any Process response may include a variety of key parameters as well as parameters it can ignore. See each individual Process topic for a fuller view of the key information for each Process on a step-by-step basis.

Final Step Response

The Process consumes and validates the user's passwords, and then invokes its business logic to complete the password update. ULM Cloud then sends a final response confirming the process completion.

{
    "processId": "50212c50-d2b6-454e-a617-b30bb66eecd8",
    "processName": "userManagement.UpdatePassword.v1.0",
    "lastStep": true
}

The response indicates that this was the last step by displaying lastStep as true.

The user's password has been successfully updated.

Tip: The POST /process/start/{processName}optionally consumes no payload, but the Process Framework supports use cases where the client application can add the required data upfront in the initial API request. For example:

POST /process/start/socialFederation.SocialMediaAssistedOnboarding.v1.0?provider=google

Errors and Retries

If an error occurs during process execution (e.g., incorrect user input), then the process returns a comprehensive error output that describes the error. The response also includes a description of the previous request from ULM, so that the user can attempt a retry.

Continuing from the above example, if the user provides an incorrect oldPassword value that does not match their current password, and the UI passes that along in the PUT process/step request, then ULM Cloud returns the following response:

{
    "processId": "50212c50-d2b6-454e-a617-b30bb66eecd8",
    "lastStep": false,
    "processName": "userManagement.UpdatePassword.v1.0",
    "operationError": [
        {
            "code": "invalid-credential",
            "type": "com.uxpsystems.mint.framework.ulm.process.service.ServiceStep.GeneralFailure",
            "message": "Bad credentials",
            "authorities": [
                {
                    "authority": "ROLE_USER"
                }
            ]
        }
    ],
    "stepName": "PasswordPrompt",
    "lastFailedStepAction": {
        "processId": "50212c50-d2b6-454e-a617-b30bb66eecd8",
        "processName": "userManagement.UpdatePassword.v1.0",
        "displayMessage": "Please input required information",
        "parameters": {
            "oldPassword": "String",
            "newPassword": "String"
        },
        "stepName": "PasswordPrompt"
    }
}

The response includes an operationError array of error(s) that describe the reason(s) for failure. Each error contains a unique code and a message.

The response also includes a lastFailedStepAction object that repeats the previous Step response prompt, so that the UI may prompt the user to re-enter their information again.

Sequence Diagram Example: Onboard User with Email/Mobile

Consider the below sequence diagram, which demonstrates the (highly simplified) flow of the Onbard User with Email and Mobile Process. It demonstrates how clients (e.g., web and mobile application UIs) interact with ULM Cloud to execute Process business logic:

Similar flows and diagrams are available in the ULM Action Tokens topic, as well as each process-specific topics in this guide.

Versioning

ULM Processes are versioned. While providing version information is not strictly required, it is recommended so workflows do not unexpectedly change as Amdocs evolves the Process catalogue over time. Version information can be specified when starting a process, and is remembered by the framework throughout Process execution, so clients do not need to pass version information on every subsequent step (request) of that Process.

Authorities

ULM restricts Process execution based on security authorities. Once a process is invoked, ULM Cloud validates that processes' list of valid security authorities against the current user (e.g., a regular user, an Administrative user), and rejects any attempts to initiate processes that the requesting user is not allowed to access.

This restriction is not limited to administrative/non-administrative contexts. The ID Recovery (or "forgot password") Process can only be initiated by an anonymous user (i.e., a user who is not authenticated to ULM). Conversely, the Update Password Process can only be invoked by an authenticated user.

Revision History