PUT /process/step

Content

Overview

The Process Step API continues or completes an existing instance of a Process identified by a processId.

API URL

  • PUT {url}/process/step

Process Request Parameters

Unlike the POST /process/start/{processName}, this API requires a payload of data specified in the preceding Process response.

Broadly speaking, the Process Step API will always require at least two key items: the processId that identifies this particular instance of a Process, and a parameters object that consists of various data fields that were explicitly specified in the preceding Process response.

Parameter Description
processId Unique identifier for the current instance of this Process.
parameters

Data object that the Process requires in order to continue its task, typically in the form of user input. The required data in the object are context-dependent, based on the preceding Process response.

All fields must be provided in simple string values.

For example: A user invokes the Recover ID process, and the first Process response looks like this:

Response Body 
{
    "processId": "80d248a2-ec15-428f-be42-500426fabec9",
    "processName": "recovery.PasswordRecovery.v1.0",
    "displayMessage": "Please provide your email or mobile",
    "parameters": {
        "authnIdentifier": "String"
    },
    "stepName": "UsernamePrompt",
    "lastStep": false,
}

This response indicates that the Process needs the user to provide their registered authentication identifier (or authN ID), as listed under the parameters object. The UI then passes that data through the PUT /process/step request:

PUT /process/step 
{
    "processId": "80d248a2-ec15-428f-be42-500426fabec9",
    "parameters": {
        "authnIdentifier": "jane_email@example.com"
    }
}

Process Response Parameters

Depending on the current Process, it may return some or most of the following key properties:

Parameter Description
processId Unique identifier for the current instance of this Process. The client application UI must provide this ID in every subsequent PUT /process/step request in order to continue and complete the Process.
processName Full name of the Process, including the category and version number.
stepName Name of the specific step that the Process is currently on. In some cases, stepName can be useful for application UIs so that they know what screen to render.
lastStep Boolean that indicates whether or not this was the last step in the Process.
displayMessage Descriptive message that the UI can optionally display to the end user.
parameters Object that specifies the info this Process requires to continue its task, usually in the form of user input. The client application must provide the required data, inside the same parameters in the subsequent PUT /process/step request.
output

Additional data object with information that ULM Cloud provides to the client application in order to render the user interface. The information may indicate what has been done (e.g., the ID of an object which has been created), or include data useful for asking a question about the next step (e.g., a list of available options to provide to the end user).

For example, the Onboard and Authenticate User with Social Account Process initially responds with a request for the social provider's providerId, and also supplies a list of available options to present to the user:

"parameters": {
    "providerId": "String"
},
"output": {
    "providers": [
        "google",
        "facebook",
        "apple"
    ]
}

Unlike parameters, output is only for the client application's consumption. The application does not need to provide it in any request to ULM Cloud.

pkat Unique Proof Key for Action Token (PKAT) that corresponds to an action token that has been issued and sent to a user's contact channel (email or mobile number). The PKAT is used for OTP verification and a quick token resend functionality. See ULM Action Tokens for more details.
userAuthenticated Boolean that indicates if the user was authenticated into ULM. Appears at the final Step response from a Process.

This is not an exhaustive list. Data fields specified in the parameters and output objects will vary from Process to Process.

Error Codes

See Common Process Error Codes for more information. Individual Process topics also contain examples of error scenarios.

Revision History

Version Description
2020.09 Added this topic.