Find a User ID and Update User Information Using the API

This case covers how to use the WISEflow API to find the userId and update user information using the API. 

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

Updating a user using the API requires that a user has at least one unique ID that can be used to match up against all other WISEflow users.

Examples of How to Find a User ID

Find a User ID

The userId is used to uniquely identify users in WISEflow. The userId is only used internally in WISEflow.

There are different ways to find a userId depending on what user information you have available:

Endpoint	Details
GET /flows/{flowId}/participants GET /flow/{flowId}/assessors GET /flows/{flowId}/managers GET /flows/{flowId}/reviewers GET /flows/{flowId}/invigilators GET /flows/{flowId}/authors	Use this endpoint if the user has already been added to a flow, and you know the flow ID.
GET /user/eduPrincipalName/{orgId}	Use this endpoint if you know the users organisation ID. This would always be the eduPersonPrincipalName. See the example below. Where the ID in the response is the userId.
GET /user/userDataType/{userDataType}/{value}	Use this endpoint if you have the userDataType of the user. See the example below. Where ID in the response is the userId.
POST /license/user	Creating a new user will return a userId.

The GET /user/eduPrincipalName/{orgId} endpoint will return information on a user based on the eduPersonPrincipalName.

orgId: [e-mail]

Will return:

{
  "id": 2358,
  "firstName": "Mr",
  "lastName": "WISEflow",
  "phone": "0000000",
  "externalIds": [
    {
      "name": "Personal Organisation Id",
      "value": "[e-mail]"
    }
  ],
  "language": "da",
  "roles": [
    {
      "name": "Participant",
      "relationIds": [
        1
      ]
    }
  ],
  "emails": [
    "[e-mail]"
  ]
}

GET /user/userDataType/{userDataType}/{value} will return the same information as above but requires the userDataType.

To return user information on Mr WISEflow, you should first use the GET /license/info endpoint to get information on the userDataType. For Mr WISEflow, the userDataType and the value is:

userDataType: 529

value: [e-mail]

Examples of How to Edit a User

Edit Basic User Information

With the userId, you can edit users on your licence. Using PUT /users/{userId} you can update basic user information (name, phone, language, and deactivate/active login). 

{
  "firstName": "Mr",
  "lastName": "WISEflow",
  "phone": "00000000",
  "language": "en",
  "loginDeactivated": false
}

All parameters in the body are mandatory. A value that is the same as an already existing one will not be updated. In this example, language is changed from da to en.

The endpoint will return the updated user information or any errors. In this case, the update did not return any errors.

{
  "id": 2358,
  "firstName": "Mr",
  "lastName": "WISEflow",
  "phone": "0000000",
  "externalIds": [
    {
      "name": "Personal Organisation Id",
      "value": "[e-mail]"
    }
  ],
  "language": "en",
  "roles": [
    {
      "name": "Participant",
      "relationIds": [
        1
      ]
    }
  ],
  "emails": [
    "[e-mail]"
  ]
}

Edit User Email

With POST /users/{userId}/emails you can create emails on a user. The body takes a mandatory email which can be set to be the primary email and to receive notifications, these options are optional:

[
  {
    "email": "[e-mail]",
    "primary": true,
    "receiveNotifications": true
  }
]

Rules for creating new emails:

• If a new primary email is sent, the existing primary email will be marked as non-primary 
• A non-primary email will be automatically activated
• On licences with standard login, creating a primary email will deactivate the user; WISEflow will send an email with an activation link to the user's primary email

If all mandatory information is set, the response will tell what information has been sent successfully and what information has resulted in an error:

{
  "success": true,
  "data": [
    {
      "emailId": 1547,
      "email": "[e-mail]",
      "primary": true,
      "fromExternalSource": true,
      "receiveNotifications": true,
      "activated": true
    }
  ],
  "error": null
  }

Mr WISEflow now has a new primary email address: [e-mail]

Some typical errors are:

• Two identical emails are sent
• More than one primary email is sent
• It is not possible to add an email that already exists on the user
• The email exists on multiple users (depending on if the license requires a unique email)

With PATCH /users/{userId}/emails you can update emails on a user. 

[
  {
    "emailId": 249,
    "email": "[e-mail]",
    "primary": true
  }
]

The body takes an emailId, which you can find using the GET /users/{userId}/emails endpoint. The emailId is the ID of the email to be updated. When updating an email, the same rules will apply as when creating an email. The response is also the same.

The user Mr WISEflow now has two emails:

Primary email: [e-mail]

Alternative email: [e-mail]

Using DELETE ​/users​/{userId}​/emails​/{emailId} you can remove an email from a user. You need the userId to identify the user and the emailId to identify the email. The endpoint will return the email that has been removed or any errors:

Removing the primary email [e-mail] will require:

userId: 2358
emailId: 1547

However, as it is not possible to remove a primary email address, an error will be returned:

{
  "success": false,
  "data": null
  "error": {
    "code": "400",
    "message": "Cannot delete primary email",
    "errors": [
      {
        "reason": "",
        "message": ""
      }
    ]
  }
}