Version 2.0.1
25-10-2024
Update/Insert one user from/to the database
updateUserAltId(p_companyID, p_wsAltUserId , p_PIN, p_Achternaam, p_Voornaam, p_Admin, p_Security, p_StartDate, p_ExpireDate, p_infoFields, p_groupName, p_groupUpdate, p_cardId, p_cardCustom, p_licensePlate, p_isVisitor, p_locationID, p_phone, p_syncToTapkey)
You can use this endpoint to insert/update one user from/to our database.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| p_companyID | string | Yes | The security code you have been provided with, string (32) |
| p_wsAltUserId | string | Yes | The wsAltUserId of the user from the EasySecure database |
| p_PIN | string | Yes | the PIN of the user, numeric. NOTE* in case user doesn't have PIN, empty string should be sent to ESWS |
| p_Achternaam | string | Yes | The lastname of the user |
| p_Voornaam | string | Yes | The firstname of the user |
| p_Admin | integer | Yes | 0 if not admin, 1 if admin |
| p_Security | integer | Yes | 0 if not admin, 1 if admin |
| p_StartDate | string | Yes | Starting with this date the user is active within EasySecure. Accepted formats: - yyyy-mm-dd hh:ii:ss (ss is not saved in EasySecure) - yyyy-mm-dd hh:ii - yyyy-mm-dd (if no hh:ii is supplied, EasySecure saves the default values) If p_StartDate is not provided or the format is not ok we will add the current date as start date |
| p_ExpireDate | string | Yes | When the user becomes unavailable for EasySecure actions. Accepted formats: - yyyy-mm-dd hh:ii:ss (ss is not saved in EasySecure) - yyyy-mm-dd hh:ii - yyyy-mm-dd (if no hh:ii is supplied, EasySecure saves the default values) If p_ExpireDate is not provided or the format is not ok we will add as end date = 2030-12-31. |
| p_infoFields | array | Yes | an associative array of type |
| p_groupName | string | Required in case the company is type Branches | he name of the group or the group names splitted by ';' (as example: Group1;Group2) the user belongs to, string. NOTE* The group name must exist in the database in case of Branch type companies. |
| p_groupUpdate | integer | No | 0 or 1 |
| p_cardId | string | No | The id of the card as read on a SDK2 device. If the following string 'Remove' is provided the card details will be deleted for the user |
| p_cardCustom | string | No | the custom number of a card as read on a SDK2 device. If p_cardId or p_cardCustom value are not as the same as read on SDK2 devices the details card details will not be saved. |
| p_licensePlate | string | No | the license plate for the user |
| p_isVisitor | integer | No | 0 or 1. In case 1 is added we mark the user as visitor |
| p_locationId | integer | No | id of the location, If the company is type branch and the location ID is provided we will remove only the groups that are linked to the provided location ID and link the user to the provided Groups |
| p_phone | string | No | The phone number of the user where the Tapkey card will be sent |
| p_syncToTapkey | string | No | 1 if the user needs to be synched to Tapkey (in which case his Tapkey card number will be the user's id * 10), any other value will be considered as if the user doesn't needs to be synched to Tapkey |
NOTE1*:
- If p_infoFieldName is not one of the info1, ..., info14 values than the search based on user info fields will not take place.
- When creating a new user/update an existing one the wsAltUserId value which is set as parameter p_wsAltUserId needs to be added also in the corresponding infofield parameter from p_infoFields.
NOTE2*:WsAltUserId value accepts only numbers, small letters, capital letters and the '-' character. If the wsAltUserId string contains other character, the value for wsAltUserId will not be saved.
NOTE3*:
- When updating a user if the start date of the user which is provided in the updateUser call is between the start date and end date of the user in the company database, the start date will not be updated during the updateUser process.
Return values
'NO_ID_RECEIVED' - no p_wsAltUserId provided in the call.
'NO_WS_ALT_USER_ID_INFOFIELD_SET' - the company doens't have the wsAltUserId infofield set on which we can check if the user exists.
'UPDATED' - the user details have been updated.
'NOT_UPDATED_ERROR' - the user details could not be updated
'INSERTED' - the user details have been added and the user has been created.
'NOT_INSERTED_ERROR' - the user details could not be inserted.
any of these strings, or a more detailed string message with specific error message
How it works
We are checking if a p_Id was provided, if it wasn't we return a 'NO_ID_RECEIVED' message.
We are checking if the p_Id provided is valid or not (must be between 1 and 400000000 inclusive), if it is not valid we return a 'INCORRECT_ID_RECEIVED' message.
We are checking if a user with the provided p_Id exists within our database already, or not. If exists, we just make an update to the fields provided within the parameters (in this case, we ignore everything that is related to the group of the user).
If the user is not yet in our database, we insert it.
If no p_groupName was provided, we search in the EasySecure database if we have a default group defined or not. If we do, we assign the user to that group.
If a p_groupName is provided, we check if a group with that name exists or not. If exists, we assign the user to the existing group, if doesn't, we create a new group and assign the user to it.
If a p_groupUpdate is provided and the value is 1 then each user will be linked/updated to the new group provided via p_groupName. If the value is 0 then the user/users will not be linked to the new p_groupName provided.
If the user exists in the database, p_groupUpdate value is 1 and the linking with the new p_groupName provided is a success - only then we change the modified/modified_by fields in the database.
We are also checking for the card details to not be duplicate, so 1 card can not be added twice to different users. If we receive a p_cardId and p_cardCustom combination which is already assigned to a different user, we return error message 'Card details already exist, can not save user' and the new user will not be saved on our side.
Branches specials rules
The parameter $p_groupName is optional in case of EasySecure, but it's mandatory in case of Branches. If no value is passed by, we return the following error: “Company is Branches but no group name specified. It is required for this type of company.”.
If the company using ESWS is Branches and the value passed by in the $p_groupName does not exists in I3, we return the following error: “Company is Branches but the group name specified does not exists.”.
In case of Branches the default group from I3 is not playing any part, it's unused. The 3rd party always must supply a valid $p_groupName
As noted before, we do not update the linking of a user to a group when we update an already existing user. The linking to a group of a user is done only when inserting to user into I3.
In order for a Branches company to work properly with ESWS the groups from I3 must be created properly. This means each location admin must create his own I3 group to which we link the inserted user. If the user is about to linked to an I3 group created by a Branch admin, the user will be linked to all locations for which that Branch admin has access to. If the user is about to be linked to an I3 group create by Main admin, the user will be linked to all I3 locations
Sync details when modifying a user in ESWS
When modifying a user from ESWS, the fields which are taken in consideration for the sync are the following:
- groups assignation change, start_date, end_date, cardid or card_custom change
Sample
Response