All Classes Namespaces Functions Properties Pages
Public Member Functions | List of all members
UserService Class Reference

Provides methods to log users on and off and manage their settings. More...

Public Member Functions

void ChangeForgottenPassword (string sessionId, string newPassword)
 Changes the password for a resource after validating the resource with the new password provided and user is logged off. More...
 
LogonState ChangePassword (string sessionId, string oldPassword, string newPassword)
 Changes the password once the old password is confirmed. The newPassword must match with Password Format defined in Server Settings. When old password is incorrect and Maximum number of logon attempts has reached, the account will be locked out untill the lockout duration has expired. More...
 
string FederatedLogOff (string sessionId)
 Logs the user out of TotalAgility. If Authentication Provider ‘Logout’ option is set to TotalAgility and Provider, returns a URL which can be used to log out of the Provider; otherwise returns an empty string. More...
 
void ForgotPassword (string emailAddress)
 Sends an email to change the password to the email address you have provided. User need to complete all the required steps mentioned in the email to change the password. More...
 
AuthenticationProvidersForSignIn GetFederatedAuthenticationProvidersForSignIn (string callbackUrl, short callbackProtocol, string origin)
 Gets a list of Authentication Providers for Sign In More...
 
AuthenticationProvidersForSignIn2 GetFederatedAuthenticationProvidersForSignIn2 (string callbackUrl, short callbackProtocol, string origin)
 Gets a list of Authentication Providers for Sign In More...
 
string GetFederatedAuthenticationSignInUrl (string callbackUrl, AuthenticationProviderIdentity authenticationProviderIdentity, short callbackProtocol, string origin)
 Creates the sign-in url to the specified authentication provider More...
 
LoggedOnUserCollection GetLoggedOnUsers (string sessionId)
 Retrieves the logged on users for the current session. More...
 
LoggedOnUser2Collection GetLoggedOnUsers2 (string sessionId)
 Retrieves the logged on users for the current session. More...
 
Session GetSession (UserIdentity2 userIdentity)
 Retrieves session details for the specified user. More...
 
Session GetSessionWithPassword (UserIdentityWithPassword userIdentity)
 Retrieves session details for the specified user. More...
 
Session GetSingleSignOnSession (string systemSessionId, UserIdentity2 userIdentity)
 Gets the session for specified user for the System Session Id. More...
 
void LogOff (string sessionId)
 Logs off the user associated with the specified session Id. More...
 
void LogOffUsers (string sessionId, StringCollection sessionIds)
 Logs off users associated with each of the specified session Ids. More...
 
void LogOffUsers2 (string sessionId, StringCollection resourceIds)
 Logs off users associated with each of the specified resource Ids. More...
 
Session2 LogOn2 (UserIdentity userIdentity)
 Logs the specified user on to the system. The user will be validated and their security rights will ve verified. More...
 
Session2 LogOnWithEmailAddress2 (UserEmailIdentity userEmailIdentity)
 Logs in the user that has the specified email address. More...
 
Session2 LogOnWithPassword2 (UserIdentityWithPassword userIdentityWithPassword)
 Logs the specified user on to the system. The user will be validated and their security rights will ve verified. More...
 
LogonState SupplyPasscode (string sessionId, string passcode)
 Accepts the passcode from the user, validates it, updates passcode's verifiedtime if the validation succeeds(i.e LogonState.LogonStateType == Loggedon) the service will add a cookie to the response with the details populated in the logonstate returned More...
 
Session ValidateSession (string sessionId)
 Validates that the specified session is valid. More...
 

Description

Provides methods to log users on and off and manage their settings.

Member Functions

void ChangeForgottenPassword ( string  sessionId,
string  newPassword 
)

Changes the password for a resource after validating the resource with the new password provided and user is logged off.

Parameters
sessionIdA string that uniquely identifies the Session for the current logged on user. If the SessionId is invalid then an exception will be raised.
newPasswordThe new password.
Security
No restrictions apply.
LogonState ChangePassword ( string  sessionId,
string  oldPassword,
string  newPassword 
)

Changes the password once the old password is confirmed. The newPassword must match with Password Format defined in Server Settings. When old password is incorrect and Maximum number of logon attempts has reached, the account will be locked out untill the lockout duration has expired.

Parameters
sessionIdA string that uniquely identifies the Session for the current logged on user. If the SessionId is invalid then an exception will be raised.
oldPasswordThe old password.
newPasswordThe new password.
Returns
A LogonState object containing details of state of the session.
Security
No restrictions apply.
string FederatedLogOff ( string  sessionId)

Logs the user out of TotalAgility. If Authentication Provider ‘Logout’ option is set to TotalAgility and Provider, returns a URL which can be used to log out of the Provider; otherwise returns an empty string.

Parameters
sessionIdA string that uniquely identifies the Session for the current logged on user. If the SessionId is invalid then an exception will be raised.
Returns
The logOff Url
Security
No restrictions apply.
void ForgotPassword ( string  emailAddress)

Sends an email to change the password to the email address you have provided. User need to complete all the required steps mentioned in the email to change the password.

Parameters
emailAddressThe email address.
Security
No restrictions apply.
AuthenticationProvidersForSignIn GetFederatedAuthenticationProvidersForSignIn ( string  callbackUrl,
short  callbackProtocol,
string  origin 
)

Gets a list of Authentication Providers for Sign In

Parameters
callbackUrlThe callback URL.
callbackProtocolThe Authentication Provider callback protocol. See Remarks below for relevant values
originThe origin URL
Returns
The Authentication Providers
Remarks
The enumeration for callbackProtocol setting follows.
Enumeration Description
0 Designer
1 Workspace
Security
No restrictions apply.
AuthenticationProvidersForSignIn2 GetFederatedAuthenticationProvidersForSignIn2 ( string  callbackUrl,
short  callbackProtocol,
string  origin 
)

Gets a list of Authentication Providers for Sign In

Parameters
callbackUrlThe callback URL.
callbackProtocolThe Authentication Provider callback protocol. See Remarks below for relevant values
originThe origin URL
Returns
The Authentication Providers
Remarks
The enumeration for callbackProtocol setting follows.
Enumeration Description
0 Designer
1 Workspace
Security
No restrictions apply.
string GetFederatedAuthenticationSignInUrl ( string  callbackUrl,
AuthenticationProviderIdentity  authenticationProviderIdentity,
short  callbackProtocol,
string  origin 
)

Creates the sign-in url to the specified authentication provider

Parameters
callbackUrlThe callback URL.
authenticationProviderIdentityThe Authentication Provider Identity.
callbackProtocolThe Authentication Provider callback protocol. See Remarks below for relevant values
originThe origin URL
Returns
The SignIn URL
Remarks
The enumeration for callbackProtocol setting follows.
Enumeration Description
0 Designer
1 Workspace
Security
No restrictions apply.
LoggedOnUserCollection GetLoggedOnUsers ( string  sessionId)

Retrieves the logged on users for the current session.

Parameters
sessionIdA string that uniquely identifies the Session for the current logged on user. If the SessionId is invalid then an exception will be raised.
Returns
Returns a LoggedOnUserCollection object list of LoggedOnUser that has the Ids and other information for each of them.
Name Type Comment
Resource Identity Id, Name and ResourceType of the logged in user
UserId String Nt name of the user
SessionId String The user's session ID
Logon Protocol Int16 Logon protocol for the user
LastActiveTime DateTime? The date and time the user last performed an action while logged on
LastAccessTime DateTime? The date and time the user last accessed.
Security
No restrictions apply.
LoggedOnUser2Collection GetLoggedOnUsers2 ( string  sessionId)

Retrieves the logged on users for the current session.

Parameters
sessionIdA string that uniquely identifies the Session for the current logged on user. If the SessionId is invalid then an exception will be raised.
Returns
Returns a LoggedOnUser2Collection object list of LoggedOnUser that has the Ids and other information for each of them.
Name Type Comment
Resource Identity Id, Name and ResourceType of the logged in user
UserId String User name of the user
logonprotocols String This contains list of comma seperated Logon protocols for the user
LastAccessTime DateTime The date and time the user last accessed.
Security
No restrictions apply.
Session GetSession ( UserIdentity2  userIdentity)

Retrieves session details for the specified user.

Parameters
userIdentityA Model.Users.UserIdentity2 object that is used to identify the user to get the session.
Name Type Comment Required
UserId String Username of the resource Yes
Logon Protocol Int16 Logon protocol for the user No
Returns
Returns a Session object that contains the session information.
Name Type Comment
SessionId String The user's session ID
ResourceId String The user's user ID
DisplayName String The user's name
isValid Boolean Will be true if the session is valid
LogonState LogonState The logon state information
Remarks
If "Disable Logon without Password" property is set to Yes in Server Settings, this method will generate an exception.
If specified then Logon Protocol must be correct
If the user is already logged on, existing session is returned; else, a new session is created and returned.
Security
No restrictions apply.
Session GetSessionWithPassword ( UserIdentityWithPassword  userIdentity)

Retrieves session details for the specified user.

Parameters
userIdentityA UserIdentityWithPassword object that is used to identify the user to get the session.
Name Type Comment Required
UserId String Username of the resource Yes
Password String Password for the resource Yes
Logon Protocol Int16 Logon protocol for the user No
UnconditionalLogOn Boolean Not used No
Returns
Returns a Session object that contains session information.
Name Type Comment
SessionId String The user's session ID
ResourceId String The user's user ID
DisplayName String The user's name
isValid Boolean Will be true if the session is valid
LogonState LogonState The logon state information
Remarks
If the user is already logged on, existing session is returned; else, a new session is created and returned.
An exception is thrown, if the user account is locked out
Security
No restrictions apply.
Session GetSingleSignOnSession ( string  systemSessionId,
UserIdentity2  userIdentity 
)

Gets the session for specified user for the System Session Id.

Parameters
systemSessionIdThe system session identifier. An exception is generated if session is not provided.
userIdentityA UserIdentity2 object that identifies a KTA user.
Name Type Comment Required
UserId String Username of the user Yes
LogOnProtocol Int16 Logon protocol to use. See Remarks below for relevant values Yes
Returns
Returns a Session object that contains the session information.
Name Type Comment
SessionId String The user's session ID
ResourceId String The user's user ID
DisplayName String The user's name
isValid Boolean Will be true if the session is valid
LogonState LogonState The logon state information
Remarks
The enumeration for LogOnProtocol setting follows.
Enumeration Description
5 Ide
7 Internet
8 Transformation Ide
Security
No restrictions apply.
void LogOff ( string  sessionId)

Logs off the user associated with the specified session Id.

Parameters
sessionIdA string that uniquely identifies the Session for the current logged on user. If the SessionId is invalid then an exception will be raised.
Remarks
The activities that are taken are reset to pending.
Security
No restrictions apply.
void LogOffUsers ( string  sessionId,
StringCollection  sessionIds 
)

Logs off users associated with each of the specified session Ids.

Parameters
sessionIdA string that uniquely identifies the Session for the current logged on user. If the SessionId is invalid then an exception will be raised.
sessionIdsA StringCollection object that contains list of session Ids to logoff.
Name Type Comment Required
String String Id of the resource Yes
Remarks
If sessionIds has no entries then the call will do nothing.
Security
No restrictions apply.
void LogOffUsers2 ( string  sessionId,
StringCollection  resourceIds 
)

Logs off users associated with each of the specified resource Ids.

Parameters
sessionIdA string that uniquely identifies the Session for the current logged on user. If the SessionId is invalid then an exception will be raised.
resourceIdsA StringCollection object that contains list of resource Ids to logoff.
Name Type Comment Required
String String Id of the resource Yes
Remarks
If resourceIds has no entries then the call will do nothing.
Security
No restrictions apply.
Session2 LogOn2 ( UserIdentity  userIdentity)

Logs the specified user on to the system. The user will be validated and their security rights will ve verified.

Parameters
userIdentityA UserIdentity object that is used to identify the user to logon.
Name Type Comment Required
UserId String Username of the resource Yes
Logon Protocol Int16 Logon protocol for the user No
UnconditionalLogOn Boolean Indicates that a new session should be created if the user is already logged on No
Returns
Returns a Session2 object that contains the session information and an indicator of whether a reserve license was used.
Name Type Comment
ReserveLicenseUsed Boolean Indicates whether the user uses a reserve license
SessionId String The user's session ID
ResourceId String The user's user ID
DisplayName String The user's name
isValid Boolean Will be true if the session is valid
LogonState LogonState The logon state information
Remarks
This API is not supported in multi-tenancy environment.
If "Disable Logon without Password" property is set to Yes in Server Settings, this method will generate an exception.
If the server setting Allow Mulitple Logon is set to true then UnconditionalLogOn has no effect. New session will be created irrespective of the user already logged in.
If Allow Mulitple Logon is set to false and UnconditionalLogOn is also false then an exception will be raised if the user is already logged on. If they were not logged on then a new session will created.
If Allow Mulitple Logon is set to false and UnconditionalLogOn is true then:
  • If the user was already logged on then they will be logged off and a new session created.
  • If the user was not already logged on then a new session will be created for them. When the user logs on and if Allow Mulitple Logon is false, all the taken activities are reset to pending.
Security
No restrictions apply.
Session2 LogOnWithEmailAddress2 ( UserEmailIdentity  userEmailIdentity)

Logs in the user that has the specified email address.

Parameters
userEmailIdentityA UserEmailIdentity object containing the email address and the logon protocol to logon to the system.
Name Type Comment Required
EmailAddress String Email address of the resource Yes
Logon Protocol Int16 Logon protocol for the user No
Returns
Returns a Session2 object that contains the session information and an indicator of whether a reserve license was used.
Name Type Comment
ReserveLicenseUsed Boolean Indicates whether the user uses a reserve license
SessionId String The user's session ID
ResourceId String The user's user ID
DisplayName String The user's name
isValid Boolean Will be true if the session is valid
LogonState LogonState The logon state information
Remarks
This API is not supported in multi-tenancy environment.
When the user logs on and if Allow Mulitple Logon is false, all the taken activities are reset to pending.
Security
No restrictions apply.
Session2 LogOnWithPassword2 ( UserIdentityWithPassword  userIdentityWithPassword)

Logs the specified user on to the system. The user will be validated and their security rights will ve verified.

Parameters
userIdentityWithPasswordA UserIdentityWithPassword object that is used to identify the user to logon with password.
Name Type Comment Required
UserId String Username of the resource Yes
Password String Password of the resource Yes
Logon Protocol Int16 Logon protocol for the user No
UnconditionalLogOn Boolean Indicates that a new session should be created if the user is already logged on No
Returns
Returns a Session2 object that contains the session information and an indicator of whether a reserve license was used.
Name Type Comment
ReserveLicenseUsed Boolean Indicates whether the user uses a reserve license
SessionId String The user's session ID
ResourceId String The user's user ID
DisplayName String The user's name
isValid Boolean Will be true if the session is valid
LogonState LogonState The logon state information
Remarks
If the server setting Allow Mulitple Logon is set to true then UnconditionalLogOn has no effect. New session will be created irrespective of the user already logged in.
If Allow Mulitple Logon is set to false and UnconditionalLogOn is also false then an exception will be raised if the user is already logged on. If they were not logged on then a new session will created.
If Allow Mulitple Logon is set to false and UnconditionalLogOn is true then:
  • If the user was already logged on then they will be logged off and a new session created.
  • If the user was not already logged on then a new session will be created for them. When the user logs on and if Allow Mulitple Logon is false, all the taken activities are reset to pending.
Security
No restrictions apply.
LogonState SupplyPasscode ( string  sessionId,
string  passcode 
)

Accepts the passcode from the user, validates it, updates passcode's verifiedtime if the validation succeeds(i.e LogonState.LogonStateType == Loggedon) the service will add a cookie to the response with the details populated in the logonstate returned

Parameters
sessionIdA string that uniquely identifies the Session for the current logged on user. If the SessionId is invalid then an exception will be raised.
passcodeThe passcode.
Returns
A LogonState object containing details of state of the session.
Security
No restrictions apply.
Session ValidateSession ( string  sessionId)

Validates that the specified session is valid.

Parameters
sessionIdA string that uniquely identifies the Session for the current logged on user. If the SessionId is invalid then an exception will be raised.
Returns
Returns a Session object that contains session information.
Name Type Comment
SessionId String The user's session ID
ResourceId String The user's user ID
DisplayName String The user's name
isValid Boolean Will be true if the session is valid
LogonState LogonState The logon state information
Security
No restrictions apply.