POST /process/start/{processName}

Content

Overview

The Process Start API creates and initializes a unique instance of a ULM Process. In most cases, this is the standard method of Process initiation from a client application.

Note: The complete processName includes the category, name, and version, with each item separated by a period. For example, to invoke the Onboard User with Email and Mobile Process, version 1.0, use this API (refer to the individual Process topics for the full name and invocation URL of each Process):

  • POST {url}/process/start/onboard.OnboardUserWithEmailMobile.v1.0

Example API URLs

  • POST {url}/process/start/recovery.PasswordRecovery.v1.0
  • POST {url}/process/start/userManagement.UpdatePassword.v1.0
  • POST {url}/process/start/socialFederation.AssociateSocialMedia.v1.0

Request Parameters

This API optionally accepts no payload. Instead, it derives its action from the name provided in the URL. The first response from most Processes is a specification of the information that the Process needs to proceed. However, the Process framework supports cases where the UI provides the required parameters upfront in the initial API request URL:

  • POST url/process/start/{processName}.v1.0?{paramName}={paramValue}&{paramName}={paramValue}

For example, when the UI invokes the Onboard and Authenticate User with Social Account Process, the Process first responds with a request for the user's chosen social provider, or providerID. To skip this step, the application can invoke the Process with that providerId in the request URL:

  • POST /process/start/socialFederation.SocialMediaAssistedOnboarding.v1.0?providerId=facebook
  • POST /process/start/socialFederation.SocialMediaAssistedOnboarding.v1.0?providerId=google

This enables a client application to display social media badges on the sign-in and sign-up UI, and then invoke the proper variation when a user clicks on a badge.

If you have use cases where the UI will know required data that is otherwise asked for in the first response, you can skip a step and simply provide the required information in the POST process/start/ URL.

Response Parameters

The Process START API 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.

Note: This is not an exhaustive list. Data fields specified in the parameters and output objects will vary from Process to Process. You can refer to the Process Walkthrough section of each Process topic for full, step-by-step details.

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.