Version 22.214.171.124 for VETtrak 19.2.0 - 10/09/2019
Breaking changes have been made to the API for compatibility with VETtrak's 19.2's enhanced password management functionality. The major changes that may affect integrations with the API are:
- Removal of employer username and password. It is no longer possible to log into the API with an employer username/password, as these fields no longer exist. If you are using employer usernames and passwords, you will need to make changes so that users instead log in with their individual client username and password, then you can call GetEmployersForClient to get a list of employers that client is associated with (perhaps having the user select one), for calling employer-related functions. This also means that a number of functions with employer-restricted access have been changed to protected-level access.
- New setting to use email address as username. Users can now optionally configure VETtrak to use email addresses for the usernames for newly-created clients. This setting will be on by default in any new VETtrak databases, but is opt-in in all existing VETtrak databases. This means that, if this setting is on, you should specify an email address whenever a new client is created (otherwise the client will not have a username and cannot log in until they are given one), and the email address must not match the username of an existing client - this is the case for the AddClient and AddClientAfterCheck functions, and any web clients or employees should have UpdateWebClient or UpdateWebEmployee called to give them an email address in case ProcessWebEnrolment or ProcessWebWaitlist needs to create a new client. If you update a client's email address using UpdateClientDetails or via a web enrolment/waitlist, and the client's username originally matched their email address, the username will also be updated to match the new email address - this will cause an error if there's another client that already has a username matching the new email address. Note that the UpdateClientUsernamePassword function, and the additional data update functions UpdateAdditionalDataForWebRecord and UpdateClientAdditionalFields, still allow you to update the username independently of the email address if required. You can use the new GetPasswordPolicy function to see if VETtrak is using email addresses as usernames. If VETtrak is using email addresses for usernames, ValidateUser and ValidateClient will check your specified username against the clients' email addresses if no client with that username was found, and will allow login with that email address if only one client has that email address.
- Password policy settings. VETtrak can now be configured with password policy settings such as minimum password length and the categories of characters required. UpdateClientUsernamePassword will validate the new password against this policy. The new GetPasswordPolicy function returns the current password policy settings that you can use to validate new passwords.
To avoid additional breaking changes, the API does not enforce the new "Force password change on next login if current password doesn't comply with policy", "Require passwords to be changed every X days", or "User must change password at next login" settings in VETtrak. You can continue to log into the API with a username/password for a client to whom any of these conditions apply without being forced to change the password. However, if the default vettrak/trakker credentials are being used for the API, and a user logs into VETtrak with those default credentials, VETtrak will force the user to change the password, which may then require your configured password to log into the API be changed. It is strongly recommended to set up and use a dedicated client with its own strong username/password, configured with security access to the API application but not the VETtrak application, to avoid such issues.
- GetEmployersForClient: Returns a list of employers that a specified client is a contact for and/or an employee of.
- GetPasswordPolicy: Returns information about the password policy settings configured in VETtrak, allowing you to validate passwords before calling UpdateClientUsernamePassword.
- AddAward: Added completionStatement boolean parameter to indicate whether the statement award being recorded is a completion. Ignored if award type is not a statement or doesn't have a qualification:
- If the award is a licence or has no qualification, this is false as it is not a completion.
- If the award is a certificate and has a qualification, this is true as it is a completion.
- UpdateEnrolledTask: Fixed an error that occurs when recording a completed task status when the "Automatically complete unit when all its tasks are completed" preference is on, the enrolled task is linked to at least one incomplete enrolled unit, and any of those incomplete enrolled units are linked to any other enrolled task that has no status recorded.
- UpdateClientUsernamePassword: Now returns an error if the specified new password does not meet the password policy settings configured in VETtrak.
- ValidateUser, ValidateClient: These two functions are now equivalent, because ValidateUser cannot log in as an employer.
- ValidateEmployer: Employers no longer have a username or password. Change to ValidateUser or ValidateClient instead, to log in as an individual client, and use GetEmployersForClient to determine which employers the client is associated with.
- UpdateEmployerUsernamePassword: Employers no longer have a username or password.
Security level changes
Due to the removal of employer login, the following functions have been changed from employer restricted to protected level, meaning that only users that have explicitly been granted permission to the API can access them:
Additional data field changes
These changes affect the QueryAdditionalData, GetAdditionalDataFieldsForEntity, GetAdditionalDataForWebRecord, UpdateAdditionalDataForWebRecord, UpdateClientAdditionalFields and UpdateEmployerAdditionalFields functions.
- Username: Employers no longer have a username and password.