Creating a Flow with Multiple Participants and an Assessor

This use case covers how to use the WISEflow API to create a flow and how to add participants and an assessor.

This use case is ideal for institutions relying on the WISEflow API and has built their own middleware to control key aspects of WISEflow.

When a flow has been created in WISEflow using the API, it will be created with a title, a subtitle, a flow type and one or more managers. Any other values will be your WISEflow licence defaults. 

High level walkthrough

Automating flow creation will enable you to create multiple flows in a short time:

Upon creation, each flow is given a unique ID (flowId) that is used throughout the API to further utilise key aspects of WISEflow. Participants and assessors are added through the middleware using the flowId. This ensures that participants and assessors are added to the correct flow.

Using the API

Creating a Flow

A flow can be created with the POST /license/create/flow endpoint. To create a flow, enter a title, a type, and a manager in the body, the subtitle is optional:

{
  "title": "Mathematics entry exam summer 2021",
  "subTitle": "Written 2 hour",
  "type": 4,
  "managers": [
    541
  ]
}

The type defines the type of flow and can be found using the GET /license/flow-types endpoint.

Managers are a list of userIds to be added as managers. If a manager has already been created as a user, the manager userId can be fetched from different endpoints. If you need to create a manager, see Create a User Using the API in this article.

When a flow has been successfully created, a flowId will be returned:

{
  "flowId": 225
}

Creating a User

Before you can add users to your newly created flow, you must first create one or more users. You can batch-create users with the POST /license/user endpoint.

To fetch externalIds use the GET /license/user-data-types endpoint.

Creating Users with Different Roles
All users are created with the same endpoint; POST /license/user. The difference is the values in the "roles" array.
Roles can be fetched from the GET /license/roles endpoint.

Creating Users
The following example will create users with the "Participation" role and the "Assessor" role.

First, two participants are created:

The first participant:

{
  "firstName": "Mr",
  "lastName": "WISEflow",
  "phone": "00000000",
  "externalIds": [
    {
      "userDataTypeId": 529,
      "value": "[e-mail]"
    }
  ],
  "language": "da",
  "roles": [
    37
  ],
  "emails": [
    "[e-mail]"
  ]
}

Mr WISEflow has been successfully created as a participant, and the userId is returned:

{
  "userId": 1524
}

The second participant:

{
  "firstName": "Mr",
  "lastName": "WISEflow 2",
  "phone": "00000000",
  "externalIds": [
    {
      "userDataTypeId": 529,
      "value": "[e-mail]"
    }
  ],
  "language": "da",
  "roles": [
    37
  ],
  "emails": [
    "[e-mail]"
  ]
}

Mr WISEflow 2 has been successfully created as a participant, and the userId is returned:

{
  "userId": 1525
}

Next, an assessor will be created:

{
  "firstName": "Test",
  "lastName": "Assessor",
  "phone": "00000000",
  "externalIds": [
    {
      "userDataTypeId": 529,
      "value": "[e-mail]"
    }
  ],
  "language": "da",
  "roles": [
    40
  ],
  "emails": [
    "[e-mail]"
  ]
}

Test Assessor has been successfully created as an assessor, and the userId is returned:

{
  "userId": 1526
}

The two participants, Mr WISEflow and Mr WISEflow 2, the marker Test Assessor can now be added to the newly created flow.

Add Users to a Flow

Adding participants to a flow is done with the POST /flow/{flowId}/participants/add endpoint.

Using the flowId from the newly created flow, you can add one or more participants using the same externalIds as you did when creating the participants:

[
  {
    "userData": {
      "userDataTypeId": 529,
      "value": "[e-mail]"
    },
    "email": "string",
    "uniqueExamId": "string"
  },
     "userData": {
      "userDataTypeId": 529,
      "value": "[e-mail]"
    },
    "email": "string",
    "uniqueExamId": "string"
]

You can also use an email or a uniqueExamId, but this depends on how your licence is set up.

Add Assessors to a Flow

Next Test Assessor is added as an assessor. To add assessors to a flow, you need the assessor type (0 = internal (default), 1 = external). The email is optional, if provided it has to be a unique email of the user and fails if your licence is not set up to require unique emails. UserData is mandatory. Assessors are added with the POST /flow/{flowId}/assessors/add endpoint:

[
  {
    "type": 0,
    "email": "",
    "userData": {
      "userDataTypeId": 529,
      "value": "[e-mail]"
    }
  }
]