The LogonUser() API function is an XmlHttp function to validate username and password details and pass back the active status of the user along with a security token. If the user is not active or found on the system then the token field will be blank.
Important: The security token should be passed on all subsequent API calls in the current session to validate that the user has successfully logged on to the Web interface. The session is defined as being the time the user logs on to TrackerRMS until they either Logoff or the token times out (8 hours).
The input format XML for this function is as follows:
<?xml version="1.0"?> <TrackerRMS> <WebAPI> <LogonUser> <UserCredentials> <Username></Username> <Password></Password> </UserCredentials> </LogonUser> </WebAPI> </TrackerRMS>
|<Username>||The username is typically the email address for the user in the format firstname.lastname@example.org|
|<Password>||The password will be the same as their web based password and can contain a combination of upper case, lower case and alpha-numeric characters|
The function will return the active state of the user and the security token, which is to be used on all subsequent API calls.
The security token will be stored against the user’s database record and checked for validity. Should the token not match against the users record, the standard “RequestStatus” section will be returned with the appropriate code (see RequestStatus section towards the end of this document).
<?xml version="1.0"?> <TrackerRMS> <WebAPI> <RequestStatus> <ReturnCode></ReturnCode> <ReturnDescription></ReturnDescription> <ReturnRecordCount></ReturnRecordCount> </RequestStatus> <LogonUser_Return> <ActiveStatus></ActiveStatus> <SecurityToken></SecurityToken> <LastAccess></LastAccess> <CompanyName></CompanyName> </LogonUser_Return> </WebAPI> </TrackerRMS>
|<ActiveStatus>||This parameter will return one of 4 status codes depending on the main status of the user.
“Active” User is Active “Inactive” User is Inactive “NotFound” User details not found “Locked” User’s account has been locked
Example Security Token:“3E5g7ht5rFe3GHti5481SwqI8Rfk840GfrpzXak2”
|The security token will be a 40 character key consisting of random upper case, lower case alphanumeric characters and will be stored against the users account on execution of the LogonUser() function. This same token is returned from this function. This token should be stored by the Web application and used on all subsequent calls during the duration of the session. The session ends when the user either runs the LogoffUser() function or the Application is closed on the Web.
A Security Token will only be passed back from this function if the user has an “Active” status, otherwise it will be blank.
|<Last Access>Example: 2010-07-01 12:34||The date and time that this user last accessed the WebAPI interface in the format
|<CompanyName>||The friendly name or company name given to the system being logged on to.|
Note: Should the user’s active status return as “Inactive”, “Locked” or “Not Found”, the Web application should clear down the data stored on the Web and prevent the user accessing any of the functions until such time as an “Active” status is returned.
Example of a valid return:
<?xml version="1.0"?> <TrackerRMS> <WebAPI> <RequestStatus> <ReturnCode>0</ReturnCode> <ReturnDescription>Success</ReturnDescription> <ReturnRecordCount>4</ReturnRecordCount> </RequestStatus> <LogonUser_Return> <ActiveStatus>Active</ActiveStatus> <SecurityToken>3E5g7ht5rFe3GHti5481SwqI8Rfk840GfrpzXak2</SecurityToken> <LastAccess>2010-07-01 12:34</LastAccess> <CompanyName>ABC Company Limited</CompanyName> </LogonUser_Return> </WebAPI> </TrackerRMS>