Update/Insert one user from/to the database

updateUserContractor(p_companyID, p_Id, p_Contractor_Code, p_Contractor_name, 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_groupId, p_licensePlate, p_isVisitor, p_locationID)

 

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_ID string Yes The Id of the user from the EasySecure database
p_Contractor_Code numeric Yes The code of the Contractor
p_Contractor_Name string Yes The name of the Contractor
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 , with the keys info1, info2, ..., info14.
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_groupId string No deprecated, empty string
p_licensePlate string No the license plate for the user
p_isVisitor integer Yes 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


NOTE*:
If p_infoFieldName is not one of the info1, ..., info14 values than the search based on user info fields will not take place.


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.

Return values

'NO_ID_RECEIVED' - no p_ID value provided in the call.

'INCORRECT_ID_RECEIVED' - the p_ID value provided is either a negative number or too big (>400000000)

'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' - 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

<soapenv:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:uen="uen:esws">
<soapenv:Header/>
<soapenv:Body>
<uen:Esws.updateUserContractor soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<p_companyID xsi:type="xsd:string">^4p;tU0Q+#dEIhTWkuj5FnLD^aKWqVu0</p_companyID>
<p_Id xsi:type="xsd:string">1</p_Id>
<p_Contractor_Code xsi:type="xsd:string">2564</p_Contractor_Code>
<p_Contractor_Name xsi:type="xsd:string">Contrractor 1</p_Contractor_Name>
<p_PIN xsi:type="xsd:string">1234</p_PIN>
<p_Achternaam xsi:type="xsd:string">Lastname</p_Achternaam>
<p_Voornaam xsi:type="xsd:string">Firstname</p_Voornaam>
<p_Admin xsi:type="xsd:string">1</p_Admin>
<p_Security xsi:type="xsd:string">1</p_Security>
<p_StartDate xsi:type="xsd:string">2021-01-01</p_StartDate>
<p_ExpireDate xsi:type="xsd:string">2021-12-31</p_ExpireDate>
<p_infoFields xsi:type="uen:updateUserInfosObject">
<info1 xsi:type="xsd:string">info1</info1>
<info2 xsi:type="xsd:string">info2</info2>
<info3 xsi:type="xsd:string">info3</info3>
<info4 xsi:type="xsd:string">info4</info4>
<info5 xsi:type="xsd:string">info5</info5>
<info6 xsi:type="xsd:string">info6</info6>
<info7 xsi:type="xsd:string">info7</info7>
<info8 xsi:type="xsd:string">info8</info8>
<info9 xsi:type="xsd:string">info9</info9>
<info10 xsi:type="xsd:string">info10</info10>
<info11 xsi:type="xsd:string">info11</info11>
<info12 xsi:type="xsd:string">info12</info12>
<info13 xsi:type="xsd:string">info13</info13>
<info14 xsi:type="xsd:string">info14</info14>
</p_infoFields>
<p_groupName xsi:type="xsd:string">Group Name</p_groupName>
<p_groupUpdate xsi:type="xsd:string">1</p_groupUpdate>
<p_cardId xsi:type="xsd:string"></p_cardId>
<p_cardCustom xsi:type="xsd:string"></p_cardCustom>
<p_groupId xsi:type="xsd:string"></p_groupId>
<p_licensePlate xsi:type="xsd:string">GH23-89</p_licensePlate>
<p_isVisitor xsi:type="xsd:string">0</p_isVisitor>
<p_locationID xsi:type="xsd:string"></p_locationID>
</uen:Esws.updateUserContractor>
</soapenv:Body>
</soapenv:Envelope>

Response

<SOAP-ENV:Envelope SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/">
<SOAP-ENV:Body>
<ns1:Esws.updateUserContractorResponse xmlns:ns1="uen:esws">
<return xsi:type="xsd:string">INSERTED</return>
</ns1:Esws.updateUserContractorResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>