Workflow API Tutorial
This tutorial demonstrates how you can use the workflow API in a custom workflow UI, rather than using the out-of-the-box Material UI.
User onboarding involves the registration and activation flows. The registration flow typically creates a user with the bare minimum information, and the InActive state. After a user is created in the InActive state, the activation workflow starts. First it sends a verification email to the user, then the user clicks the link to verify that the email address belongs to them, and finally you can ask the user to share more information, according to the onboarding requirements.
InsurCar registration flow
Review the registration flow Business Process Model and Notation (BPMN) for the InsurCar brand, which is available at https://insurgroup-edge.test.onewelcome.io/insurcar/registration/
1. InsurCar registration flow obtains a processToken
Use the API from the Start Registration Flow request.
The start initiation flow initiates a process instance of the registration BPMN and returns a processToken that you can use to refer to the process instance in future requests.
It also indicates that the next UserTask in the BPMN is registration_selection_step. After the response, it is up to you to redirect the user to a UI page that requests the information that is required for registration.
After the user enters those details in the UI page, you can invoke the API to resume the workflow with the next API call.
To continue with the workflow, you need to capture the processToken from the response and use that for the next request. That information is captured in the processToken variable through the tests tab in the previous request. Use this variable to refer to the processToken in your future calls.
2. Email address and policy number
In the InsurCar registration flow, the registration_selection_step expects the user to specify the following information:
-
Email address
-
An existing policy number
You can invoke the next API with this information, along with the processToken captured in the previous request. If the user provided valid information, all validation succeeds, and the user is created successfully, the workflow proceeds with the next steps until the next UserTask, which in this case is the email_sent step.
At this point, the user is created in the inactive state, which means that the activation flow gets initiated and sends a verification email to the email address that the user provided. The verification link in the email contains a processToken and token, which is needed in the next steps for verifying the user and continuing with the rest of the flow.
To capture the ProcessToken and token from the email, right-click the Continue registration button and copy the link address. You need to capture the processToken and token to make your next API call, which verifies the user.
This processTokenis different from the processToken in the registration flow, because this processToken is for an instance of the activation flow. Use this process token to continue with the activation flow execution.
For the remaining Postman requests, change the endpoint to point to the activation process token that you obtained from your email confirmation link.
3. Simulate user click
To simulate the user click for registration, use the following call:
{{baseUrl}}/workflowapi/process/2dd9e729-b136-4038-bb89-193304e493a5
This simulates the user clicking the verify button, and gets to the display_buttons UserTask.
You can show the user a UI page that allows the user to choose an identity provider (IDP) that can fill in their details. In this case, keep it simple and use the continue button (which means use the OneWelcome Identity Platform as the IDP).
4. Set the identity provider
To set the OneWelcome Identity Platform as the identity provider (IDP), use the request below:
5. Set the user password
With the OneWelcome Identity Platform as the IDP, the BPMN expects the user to first set a password and confirm the password with registration_step3. To achieve that, use the call below:
Detailed response
You can review the detailed response:
The response contains the processing purposes and privacy documents, which you can use for the next UI page for user consent. For example, the UI page might resemble the following page:
6. Complete the registration
The user can enter the details and complete the registration. Make the next call to perform that operation:
Congratulations! If you notice thanks in the response, that's because it was the last step in the workflow. The workflow completes successfully.
You used the registration and activation flow, but you can use any flow in a similar way.
Activation flow
For your reference, here is a visual representation of the activation workflow:
