Parent | Child | Previous | Next

Web Application Security Functions

IN THIS PAGE

A5WS_Add_Group Function
- Example
a5ws_ChangeLoggedInUserPassword Function
- Example
A5WS_CreateSecurityFiles Function
A5WS_Delete_Group Function
- Example
A5WS_Delete_User Function
A5WS_ExportUsers Function
A5WS_Get_Group_Assignments Function
A5WS_Get_Groups Function
- Example
A5WS_Get_GUID_From_Group Function
A5WS_Get_GUID_From_Ulink Function
A5WS_Get_GUID_From_User Function
A5WS_Get_LockedOutUsers Function
A5WS_Get_Page_List Function
- Example
A5WS_Get_Security_Ques Function
- Example
A5WS_Get_Ulink_From_GUID Function
A5WS_Get_User_Assignments Function
A5WS_Get_User_From_GUID Function
A5WS_Get_User_Values Function
- Example
- Using the Function Outside of a Dialog Component
A5WS_Get_Users Function
A5WS_Get_WebUser_Values Function
- Example
- Using the Function Outside of a Dialog Component
A5ws_GetCurrentUser Function
a5ws_GetGroupsDialog Function
a5ws_getUserValuesActiveDirectory Function
- Examples
A5WS_Login_User Function
- Example
A5WS_LogoutUser Function
A5WS_OpenWebSecurity Function
A5WS_PageSecurity Function
a5ws_RevalidatePassword Function
A5WS_Save_User_Values Function
- Using the Function Outside of a Dialog Component
A5WS_Save_WebUser_Values Function
- Example
- Using the Function Outside of a Dialog Component
A5WS_SecurityActive Function
A5WS_SecurityQues Function
A5WS_SecurityQuestions Function
A5WS_SecuritySettings Function
A5WS_User_File_Field_List Function
A5WS_User_Groups_Dialog Function
A5WS_Validate_WebUser_Values Function
- Example
- Using the Function Outside of a Dialog Component
A5WS_WebUser_Exists Function
- Example

Description

Alpha Anywhere provides the following functions for working with web application security.

A5WS_Add_Group Function

This function cannot be used to add roles to Active Directory. See Active Directory Integration for more information.

Syntax

Result_Flag as L = a5ws_Add_Group(C group_name [,* Localrequest ])

Arguments

group_nameCharacter: The name of the new security group to be added.
LocalrequestLogical: The Request system variable. It is added automatically by the server when run from a web page.

Returns

Result_FlagLogical: .T. = The group was added. .F. = The group was not added. Result_Flag will be .F. if the group name already exists.

Description

Add a group to the list of security groups for the current project.

Discussion

The A5WS_Add_Group() adds a security group to the web security system with the name supplied in group_name. If the group value was not added or already exists, the Result_Flag will return 'False'. Request is added automatically by the server when run from a web page.

Example

The following example attempts to add a group using the group name.

?a5ws_Add_Group("newGroup")
 = .T.

Limitations

Web applications only.

See Also

a5ws_ChangeLoggedInUserPassword Function

Syntax

P Result = a5ws_ChangeLoggedInUserPassword(C OriginalPassword ,C NewPassword ,C ConfirmPassword [,* request [,* session ]])

Arguments

Result: Holds status. Result.errors will return TRUE if any errors are found during processing. result.error_text holds any messages returned
OriginalPassword: The current password for the current logged in user
NewPassword: New password to enter
ConfirmPassword: Double entry of new password
request: (optional) The Request system variable. This variable explicitly passes the request object to the function.
session: (optional) The Session System variable. This variable explicitly passes the session object to the function.

Description

Web Security - Change a logged in user's password. This can only be run from the Application Server

Discussion

Web Security - Change a logged in user's password. The a5ws_ChangeLoggedInUserPassword() function populates a dot variable with two possible return values. Result.errors will return False if security is not active, a password is not required for the current security configuration, or a password change was successful. All other conditions return Result.errors = true. Messages will almost always be returned in Result.error_text. The following conditions give the message shown

Security is not active. "Security is Not Active"
A password is not required. "Security Does Not Require a Password"
The password change was successful. "Password Changed"
The function was not run from a page or component on the App server. "This option can only be run from the Application Server"
No user is logged in when the function is called. "No User is Logged In"
The security does not allow password change. "Password Change is Not Allowed"
The data did not validate. "Invalid Data Supplied"
The password data is valid, but not accepted by rule. "Password Information Not Accepted"

Example

dim pResult as p
pResult = a5ws_ChangeLoggedInUserPassword(OriginalPassword,NewPassword ,ConfirmPassword ,request, session)

Limitations

Can only be run from the Application Server

See Also

Web Security Functions

A5WS_CreateSecurityFiles Function

Syntax

Result_Flag as L = a5ws_CreateSecurityFiles([C projpath ])

Arguments

Result_Flag: .T. = Indicates that security files were created. .F. = Indicates that security files were not created.
projpath: Character

Description

Create Default Web Security Files for Web Project. Used in V8 Web Application Server and later

Discussion

The A5WS_CreateSecurityFiles() function creates default security files for a web publishing project. A5WS_CreateSecurityFiles() has limited use for an end user, because, if no security files have been created, Alpha Anywhere automatically creates security files as part of the publishing process. If run in Version 8, A5WS_CreateSecurityFiles() will not overwrite any existing security files, just create default files if none exist. If run in Version 7, the function will always overwrite any existing security files and create default files with security turned off.

Example

? A5WS_CreateSecurityFiles(
= .T.

Limitations

Web publishing applications only.

See Also

A5WS_Delete_Group Function

Syntax

Result_Flag as L = a5ws_Delete_Group(C group_value [,L confirm_empty [,* Localrequest ]])

Arguments

Result_Flag: .T. = The group was deleted. .F. = The group was not deleted.
group_value: A unique value assigned to a security group in the web security system. It can be a group 'guid' or a valid group name.
confirm_empty: If True, the group will only be deleted if no users are assigned to the group. The default is .F. and the group will be deleted even if users are assigned to the group.
Localrequest: Optional. The Request system variable. It is added automatically by the server when run from a web page.

Description

Delete a web security group in the current project. Group_value can be a group 'name' or a group 'guid'. Default for 'confirm_empty' is False. If True, the group will only be deleted if no users are assigned to group. 'Request' pointer must be provided if run in web page.

Discussion

The A5WS_Delete_Group() deletes a security group from the web security system as identified by the group value. Group_value can be a group 'guid' or a valid group name. If the group value is not found, the Result_Flag will return 'False'. If confirm_empty is .T. and there are users assigned to the group, the group is not deleted and the Result_Flag will be .F.. Request is added automatically by the server when run from a web page.

Example

The following example attempts to delete a valid group using the group name. Confirm_Delete is set to .T. and there are users assigned to the group.

?a5ws_Delete_Group("administrators",.T.)
 = .F.

Limitations

Web applications only.

See Also

A5WS_Delete_User Function

Syntax

Result_Flag as L = a5ws_Delete_User(C user_value [,* Localrequest ])

Arguments

Result_Flag: .T. = The user was deleted. .F. = The user was not deleted.
user_value: A unique user value assigned to a user in the web security system. It can be a user 'guid' or a user 'userid'.
Localrequest: Optional. The Request system variable. It is added automatically by the server when run from a web page.

Description

Delete a web security user in the current project. User_value can be a user 'guid' or a user 'userid'. 'Request' pointer must be provided if run in web page.

Discussion

The A5WS_Delete_User() deletes a user identified by the user value from the web security system. User_value can be a user 'guid' or a user 'userid'. If the user value is not found, the Result_Flag will return 'False'. Request is added automatically by the server when run from a web page.

Example

?a5ws_Delete_User("[email protected]")
 = .T.

Limitations

Web applications only.

See Also

A5WS_ExportUsers Function

Syntax

L a5ws_ExportUsers()

Description

Export selected records from the current project web users table to an external table

Discussion

The A5WS_ExportUsers() function displays a dialog to export selected records from the current project web users table to an external table. It is normally called from an option on the web Users and Groups dialog.

Example

A5WS_ExportUsers()

Limitations

Web publishing applications only.

See Also

A5WS_Get_Group_Assignments Function

Syntax

User_List as C = a5ws_Get_Group_Assignments(C group_name [,* Localrequest [,L FlagWeb ]])

Arguments

User_List: CR-LF delimited list of users by userid assigned to a particular group in the current project.
group_name: The name of a group in the current project.
Localrequest: Optional. The Request system variable. This variable explicitly passes all request variables to the function.
FlagWeb: Optional. Default = .T. when run in the web server. .F. when run in the desktop. .T. = Format suitable for use in a list, checkbox, or radio control on a web page .F. = CR-LF delimited list of userid values only

Description

Return a CR-LF delimited list of users assigned to a particular group in the current project. FlagWeb default value is .F. FlagWeb = .T. will output list in a format used in web components for checkboxes, radio buttons, list boxes and dropdowns. 'Request' pointer must be provided if run in web page.

Discussion

The A5WS_Get_Group_Assignments() function returns a list of members of a named group.

Limitations

Web applications only.

See Also

A5WS_Get_Groups Function

Use of this function to retrieve security groups in newer applications is discouraged. Use Context.Security.GetRoles() instead.

Syntax

Group_List as C = a5ws_Get_Groups([* Localrequest [,L FlagWeb ]])

Arguments

LocalrequestPointer: The Request system variable. This variable explicitly passes all request variables to the function. Required if run from a web page.
FlagWebLogical: Default = .F.. If .T., groups are formatted for use in a list, checkbox, or radio control. If .F., groups returned as a CR-LF delimited list.

Returns

Group_ListCharacter: A list of security groups in the current web project.

Description

Show a CR-LF list of web groups for the current project. FlagWeb default value is .F. FlagWeb = .T. will output list in a format used in web components for checkboxes, radio buttons, list boxes and dropdowns. 'Request' pointer must be provided if run in web page.

Discussion

The A5WS_Get_Groups() function returns a list of security groups defined for the current web project. It can be used without parameters to return a list of groups defined for the current selected web project.

It can be used on a web page or in a web component event to retrieve a list of user security groups for use in a check box control, a dropdown list, a radio button list, or a listbox control in a legacy dialog component. Typically used in the Server Activate event of a legacy dialog component.

Display the Form > Properties menu page of the legacy Dialog Builder.
Click in the Server Events > Activate property.

Example

? A5WS_Get_Groups()
= Accounting
Administrators
Marketing

'on web page or in component event
grouplist = a5ws_get_groups(request,.T.)

Limitations

Web applications only.

See Also

A5WS_Get_GUID_From_Group Function

Syntax

GUID as C = a5ws_Get_GUID_From_Group(C group_name [,* Localrequest ])

Arguments

GUID: The unique ID assigned to the group.
group_name: The group_name value of a group in the group table.
Localrequest: Optional. The request variable. Required if run from a web page.

Description

Returns a group GUID from a group name. 'Request' must be provided if run in web page.

Discussion

The A5WS_Get_GUID_From_Group() returns the unique ID assigned to a security group in the group table.

Example

?A5WS_Get_GUID_From_Group("Administrators")
= "78f972bb35644ffc95fbf894bc524382"

Limitations

Web applications only.

See Also

A5WS_Get_GUID_From_Ulink Function

Syntax

GUID as C = a5ws_Get_GUID_From_Ulink(C ulink [,* request ])

Arguments

GUID: The unique ID assigned to a user in the web security system.
ulink: The ulink value of a person in the web security user table.
request: Optional. The Request system variable. It is added automatically by the server when run from a web page.

Description

Returns a user GUID from a user ulink value if the ulink option is configured and a value is found. 'Request' is added automatically by the server when run from a web page.

Discussion

The A5WS_Get_GUID_From_Ulink() returns a user GUID from a user ulink value if the ulink option is configured and a value is found. If the Ulink option is not configured, a blank value is returned.

Example

?a5ws_Get_GUID_From_Ulink("00000029")
= "432f3df278a24df0a39219be1f356019"

Limitations

Web applications only.

See Also

A5WS_Get_GUID_From_User Function

Syntax

GUID as C = a5ws_Get_GUID_From_User(C userid [,* Localrequest ])

Arguments

GUID: The unique ID assigned to a user in the web security system
userid: The userid value of a person in the user table in the web security system.
Localrequest: Optional. The Request system variable. It is added automatically by the server when run from a web page.

Description

Returns a user GUID from a userid.

Discussion

The A5WS_Get_GUID_From_User() returns the unique ID assigned to a user ID in the user table. Returns the unique ID assigned to a user ID.

Example

?a5ws_Get_GUID_From_User("doris")
= "9036155807a2443782ba61ed2a974471"

Limitations

Web applications only.

See Also

A5WS_Get_LockedOutUsers Function

Syntax

LockedOut_User_List as C = a5ws_Get_LockedOutUsers([C Format [,* NotUsed ]])

Arguments

LockedOut_User_List: A CR-LF delimited list of userid values currently defined as locked out in web security.
Format: Optional. A display format information to use to output field information. Options are:"U" = Userid "T" = Logged out 'until time' as character Default is Userid only.
NotUsed: Optional. The Request system variable. It is added automatically by the server when run from a web page.

Description

Returns a crlf() delimited list of userid's currently locked out by the web security. Returns blank if no one is locked out. If a format is specified, returns output in that format (U=userid,T=untiltime as character).

Discussion

The A5WS_Get_LockedOutUsers() returns a CR-LF delimited list of user IDs currently locked out by the web security. Returns blank if no one is locked out. If a format is specified, returns output in that format. Request is added automatically by the server when run from a web page. An 'until time' of '01/01/9999 12:00:00 00 pm' will be returned if the security settings are set tol lock out a user until reset by an administrator.

Example

?a5ws_Get_LockedOutUsers("U-T")
= john at email.com-01/01/9999 12:00:00 00 pm
sam at email.com-03/04/2011 08:37:58 73 pm

Limitations

Web applications only.

See Also

A5WS_Get_Page_List Function

Syntax

Page_List as C = a5ws_Get_Page_List([* Request ])

Arguments

Page_List: A CR-LF delimited list of pages defined as allowed or login required in published project
Request: The Request variable. This system variable explicitly passes all request variables to the function.

Description

Get a List of Pages Currently allowed by the Web Security settings. Use in Web Dialog component

Discussion

The A5WS_Get_Page_list() function retrieves a list of pages for use in a drop down list control in a dialog component. The pages are those allowed or defined as needing login for the current project security. Typically used in the Server Activate event of a dialog component.

1. Display the Form > Properties menu page of the Dialog Builder.
2. Click in the Server Events > Activate property.

Example

Note that Request is the name of a variable created by the Application Server.

Pagelist = A5WS_Get_Page_List(request)

Limitations

May only be used in a web component.

See Also

A5WS_Get_Security_Ques Function

Syntax

Question_List as C = a5ws_Get_Security_Ques([* LocalRequest ])

Arguments

Question_List: A CR-LF delimited list of security questions defined for the published project.
LocalRequest: The Request variable. This system variable explicitly passes all request variables to the function.

Description

Get Web Security Questions in CR-LF list. Use in Web Dialog component.

Discussion

The A5WS_Get_Security_Ques() function retrieves a list of security questions for use in a drop down list control in a dialog component. Typically used in the Server Activate event of a dialog component.

Display the Form > Properties menu page of the Dialog Builder.
Click in the Server Events > Activate property.

Example

Note that Request is the name of a variable created by the Application Server.

queslist = a5ws_get_security_ques(request)

Limitations

May only be used in a web component.

See Also

A5WS_Get_Ulink_From_GUID Function

Syntax

Ulink as C = a5ws_Get_Ulink_From_GUID(C user_guid [,* request ])

Arguments

Ulink: The ulink value of a person in the web security user table.
user_guid: The unique ID assigned to a user in the web security system.
request: Optional. The Request system variable. It is added automatically by the server when run from a web page.

Description

Returns a users 'ulink' value from a user_guid in the current project. If the user link field is not activated, an empty value is returned. 'Request' is added automatically by the server when run from a web page

Discussion

The A5WS_Get_Ulink_From_GUID() returns a user's 'ulink' value from the unique identifier assigned to them in web security. If the user link field is not activated, an empty value is returned. 'Request' is added automatically by the server when run from a web page.

Example

?a5ws_Get_Ulink_From_GUID("432f3df278a24df0a39219be1f356019")
= "00000029"

Limitations

Web applications only.

See Also

A5WS_Get_User_Assignments Function

Syntax

Group_List as C = a5ws_Get_User_Assignments(C uservalue [,* Localrequest ])

Arguments

Group_List: A list of groups to which the specified user belongs.
uservalue: The userid of a person in the user table.
Localrequest: Optional. The Request system variable. This variable explicitly passes all request variables to the function. Required if run from a web page.

Description

Return a CR-LF delimited list of groups assigned to a particular web security user in the current project. Accepts uservalue as 'ulink' or 'userid'

Discussion

The A5WS_Get_User_Assignments() function returns a list of the groups to which a person belongs. Returns a list of groups to which a user belongs

Example

? A5WS_Get_User_Assignments("doris")
= "Marketing"

Limitations

Web applications only.

See Also

A5WS_Get_User_From_GUID Function

Syntax

User as C = a5ws_Get_User_From_GUID(C user_guid [,* Localrequest ])

Arguments

User: The userid of a person in the user table.
user_guid: The guid of a person in the user table.
Localrequest: Optional. The request variable. Required if run from a web page.

Description

Returns a userid from a user_guid in the current project. 'Request' pointer must be provided if run in web page.

Discussion

The A5WS_Get_User_From_GUID() function returns the guid for a userid value in the user table. Returns the guid for a userid value in the user table.

Example

dim guid as C
guid = A5WS_Get_GUID_From_User("doris")

? guid
= "9036155807a2443782ba61ed2a974471"

? A5WS_Get_User_From_GUID(guid)
= doris

Limitations

Web applications only.

See Also

A5WS_Get_User_Values Function

This function is deprecated and this page will be removed in the near future. Use A5WS_Get_WebUser_Values().

Syntax

Result as P = a5ws_Get_User_Values(P CurrentForm [,* request ])

Arguments

Result

The result value is not meaningful if the function is being used in a web component.

result.errors = Will return TRUE if any errors are found during processing.
result.error_text = Error messages returned.

CurrentForm

The CurrentForm variable.

request

The Request system variable. This variable explicitly passes all request variables to the function. Users are found by three possible values passed in the request.variables property of the request variable. There are checked in sequence until a match is found.

request.variables.guid = The user GUID value for the desired user record
request.variables.userid = The 'userid' value for the desired user record
request.variables.ulink = The 'ulink' value saved in the desired user record

A5WS_Get_WebUser_Values() should be used instead."/>

Description

This function is deprecated and this page will be removed in the near future. The function A5WS_Get_WebUser_Values() should be used instead.

Discussion

This function is deprecated and this page will be removed in the near future. The function A5WS_Get_WebUser_Values() should be used instead.

The A5WS_Get_User_Values() function populates control values in a dialog component from fields in the User table. The function returns values from web user table as CurrentForm.Controls..value for each field in table. Accepts user identification as request.variables.guid, request.variables.userid or request.variables.ulink.

The name of each control in the dialog must exactly match the name of the field in the user table. A list of valid field names can be found by using the A5WS_User_File_Field_List() function. Typically used in the Server Initialize event of a dialog component. You can also use this function in the Server After Validate event to repopulate values after a save. Adding Users with a Web Component shows how the function is used in dialog component events.

Display the Form > Properties menu page of the Dialog Builder.
Click in the Server Events > Initialize property.

Example

a5ws_get_user_values(CurrentForm,request)

Using the Function Outside of a Dialog Component

The function is designed to be used within Server Events of a dialog component. However, it can be used on any Xbasic code section on a web page or component to return various values for a specific user. It is helpful to get a list of valid field names currently being used in the user security table by using the A5WS_User_File_Field_List() function. One additional field named groups can be returned. It will contain a comma delimited list of the security groups assigned to the user. The group values returned will be the group_guid value for each group, not the group names. A list of group names assigned to the user can be found using the function A5WS_Get_User_Assignments.

? a5ws_User_File_Field_List()
= Email
Guid
Password
Ulink
Userid

The fields to be output from the function must be defined. The function will only return values for field names passed to the function as .Controls..value and will only return values for fields currently being used by the security system.

dim output as p
dim output.controls as p
dim output.controls.email.value as c
dim output.controls.userid.value as c
dim output.controls.groups.value as c
dim output.controls.guid.value as c

A value must be passed to the function in the Request system variable to find the current user. This can be in the form request.variables.guid, request.variables.userid or request.variables.ulink.

dim request.variables.ulink as c
request.variables.ulink = "00000008"

The function will return the values found in the output.controls..value. The result.errors value can be tested to determine if any errors occurred during processing. Any error messages will be should in the result.error_text value. The userid value can be used to get a list of group names for the user using the function A5WS_Get_User_Assignments.

dim result as p
dim error_message as c
dim group_list as c
result = a5ws_Get_User_Values(output,request)
if result.errors = .T. then
    error_message = result.error_text
    end
end if 
group_list = a5ws_get_user_assignments(output.controls.userid.value,request)
group_list = crlf_to_comma(group_list)

Limitations

DEPRECATED

See Also

A5WS_Get_Users Function

Syntax

User_List as C = a5ws_Get_Users([* Nullrequest [,L FlagWeb ]])

Arguments

User_List: A list of the userid values in the user table.
Nullrequest: The Request system variable. This variable explicitly passes all request variables to the function.
FlagWeb: Optional. Default = .F. . .T. = Format suitable for use in a list control on a web page .F. = CR-LF delimited list

Description

Show a CR-LF list of users for the current project. FlagWeb default value is .F. FlagWeb = .T. will output list in a format used in web components for checkboxes, radio buttons, list boxes and dropdowns. 'Request' pointer must be provided if run in web page.

Discussion

The A5WS_Get_Users() function returns a list of the userid values in the user table.

Example

? A5WS_Get_Users()
= alfred
betty
charles
doris

Limitations

Web applications only.

See Also

A5WS_Get_WebUser_Values Function

Syntax

Result as P = a5ws_Get_WebUser_Values(P CurrentForm [,* UserValue [,* LocalRequest ]])

Arguments

Result

The result value is not meaningful if the function is being used in a web component.

result.errors = Will return TRUE if any errors are found during processing.
result.error_text = Error messages returned.

CurrentForm

The CurrentForm variable.

UserValue

Optional. A pointer variable used to pass user defined values to the function. These will override the same values passed by the Request system variable. Users can be found by three possible values passed in the variable. They are checked in sequence until a match is found. If no UserValue variables are specified, the function will use the values passed by the Request system variable.

UserValue.guid = The user GUID value for the desired user record
UserValue.userid = The 'userid' value for the desired user record
userValue.ulink = The 'ulink' value saved in the desired user record

LocalRequest

Optional. The Request system variable. The request variable should be considered READ ONLY. It is added automatically by the server when run from a web page. Users may be found by

request.variables.guid = The user GUID value for the desired user record
request.variables.userid = The 'userid' value for the desired user record
request.variables.ulink = The 'ulink' value saved in the desired user record

Description

Return values from web user table as 'CurrentForm.Controls.<fieldname>.value' for each field in table. 'UserValue' overrides values passed by the request system variable. Accepts user identification as 'UserValue.guid','UserValue.userid' or 'UserValue.ulink'.

Discussion

The A5WS_Get_WebUser_Values() function populates control values in a dialog component from fields in the User table. The function returns values from web user table as CurrentForm.Controls..value for each field in table. Accepts user identification as UserValue.guid, UserValue.userid or UserValue.ulink. If the UserValue variable is empty or not supplied, the function will use the same values passed by the system request variable. The name of each control in the dialog must exactly match the name of the field in the user table. A list of valid field names can be found by using the A5WS_User_File_Field_List() function. Typically used in the Server Initialize event of a dialog component. You can also use this function in the Server After Validate event to repopulate values after a save. Adding Users with a Web Component shows how the function is used in dialog component events.

1. Display the Form > Properties menu page of the Dialog Builder.
2. Click in the Server Events > Initialize property.

Example

a5ws_get_webuser_values(CurrentForm)

Using the Function Outside of a Dialog Component

put description here

?a5ws_User_File_Field_List()
= Email
Guid
Password
Ulink
Userid

dim output as p
dim output.controls as p
dim output.controls.email.value as c
dim output.controls.userid.value as c
dim output.controls.groups.value as c
dim output.controls.guid.value as c

A value must be passed to the function in the Request system variable to find the current user. This can be in the form request.variables.guid, request.variables.userid or request.variables.ulink.

dim UserValue as p
dim UserValue.ulink as c
UserValue.ulink = "00000008"

The function will return the values found in the output.controls..value. The result.errors value can be tested to determine if any errors occured during processing. Any error messages will be should in the result.error_text value. The userid value can be used to get a list of group names for the user using the function A5WS_Get_User_Assignments.

dim result as p
dim error_message as c
dim group_list as c
result = a5ws_Get_WebUser_Values(output,UserValue)
if result.errors = .T. then
    error_message = result.error_text
    end
end if 
group_list = a5ws_get_user_assignments(output.controls.userid.value,request)
group_list = crlf_to_comma(group_list)

Limitations

May only be used in a web component or web page.

See Also

A5ws_GetCurrentUser Function

Syntax

C Result = A5ws_GetCurrentUser()

Description

Get the 'UserName (UserId) of the current logged in user.

Discussion

Get the UserName (UserId) of the current logged in user

Limitations

Can only be used on a web page or component.

See Also

Web Security Functions

a5ws_GetGroupsDialog Function

Syntax

C Result = a5ws_GetGroupsDialog()

Returns

ResultCharacter: List of security groups

Description

Returns a list of security groups defined for the current web project. Used in UX server-side events

Discussion

The a5ws_GetGroupsDialog() gets a list of security groups defined for the current web project. It has no input parameters and should be used in place of the a5ws_Get_Groups() function used in old versions of Alpha Anywhere.

See also the Context.Security.GetRoles() function.

Example

? a5ws_GetGroupsDialog()
= Accounting|80aa8d06b36249c3bb46a4df87088524
Administrator|4796f42a0eff4367917ec5a7fe312ce9
Management|76840e8905644031aaca76a285be4d8f
Staff|af3862f1d6a44457911d0acfb250848f
Users|6e62c4f28c5049fbbd172ccdf35b503e

See Also

Context.Security.GetRoles()

Xbasic

a5ws_getUserValuesActiveDirectory Function

Syntax

dim userValues as P = a5ws_GetUserValuesActiveDirectory([C UserName [,C AdditionalAttributes ]])

Arguments

UserNameCharacter: The user to lookup.
The UserName is required if a5ws_getUserValuesActiveDirectory() is used in Alpha Anywhere 4.4.4 or prior. Starting with Alpha Anywhere build 4449, the user name is optional. If no user name is specified, values for the currently logged in user will be fetched.
AdditionalAttributesCharacter: A comma or CR-LF delimited list of additional properties to retrieve that are available in Active Directory but are not listed by default. See http://www.kouti.com/tables/userattributes.htm for a list of possible properties that may be available.

Returns

userValuesPointer

Returns a dot variable with the properties listed below plus any additional properties requested using the AdditionalAttributes parameter. If the Alpha Anywhere Application Server is not configured to use Active Directory, the Active Directory server cannot be reached, or the user does not exist, no properties will be returned.

If a property has no value, it will have a type of Z.

AccountExpirationDateTime: The account's expiration date.
AccountLockedOutLogical: Indicates whether or not the account is locked.
AccountLockoutTimeTime: LDAP lockout time
BadLogonCountNumeric: The number of failed login attempts.
DescriptionCharacter: Typically a job description or some other user defined information.
DisplayNameCharacter: The account display name.
DistinguishedNameCharacter: The LDAP address for the user (see https://technet.microsoft.com/en-us/library/cc977992.aspx for more information.)
EmailAddressCharacter: The user's email address.
EmployeeIdCharacter: The employee ID.
EnabledLogical: Indicates whether or not the user is active in Active Directory.
GivenNameCharacter: The user's first name.
GuidCharacter: LDAP object GUID - A modified unique identifier with hyphens removed, similar to the userGuid in Alpha Anywhere security. Unique for each user and doesn't change.
HomeDirectoryCharacter: The path to the user's home directory. See https://msdn.microsoft.com/en-us/library/ms676190(v=vs.85).aspx for more information.
HomeDriveCharacter: The home drive.
LastBadPasswordAttemptTime: The time for the last time the login failed due to incorrect password.
LastLogonTime: The time the user last logged on.
LastPasswordSetTime: The last password set for the user's account.
MiddleNameCharacter: The user's middle name.
NameCharacter: The user's full name - first and last name.
PasswordNeverExpiresLogical: Indicates whether or not the password expires.
PasswordNotRequiredLogical: Indicates whether or not a password is required.
RolesCharacter: A CR-LF delimited list of the user's roles.
SamAccountNameCharacter: The user logon name.
ScriptPathCharacter: The path to the login script.
SidCharacter: LDAP ObjectSid - A system identifier and can change for a user. See https://technet.microsoft.com/en-us/library/cc961625.aspx for more details.
SmartcardLogonRequiredLogical: If .t., two-factor authentication is required to logon. See https://blogs.technet.microsoft.com/poshchap/2015/05/08/security-focus-resetting-smart-card-is-required-for-interactive-logon/ for more information.
SurnameCharacter: The user's last name.
UserCannotChangePasswordLogical: Indicate whether or not the user can change their password.
UserPrincipalNameCharacter: The user's name in Active Directory. This is the login name + domain. For example [email protected].
VoiceTelephoneNumberCharacter: The user's telephone number.

Description

Get the Active Directory properties for a user. Alpha Anywhere must be configured to use active directory.

Discussion

The a5ws_getUserValuesActiveDirectory function returns a list of properties for the specified user. A default set of properties is always returned. Proeprties that are available in Active Directory but are not included by default can also be retrieved by passing the list of additional attributes into the AdditionalAttributes parameter.

Examples

This example demonstrates how to get the phone number for the currently logged in user. The property is a default property, VoiceTelephoneNumber:

dim user as p
dim phone as c
user = a5ws_GetUserValuesActiveDirectory("")
'--- optional method to pass in current user
'user = a5ws_GetUserValuesActiveDirectory(Context.Security.CurrentUser)
if variable_exists("user.SamAccountName") ' User data was found
    phone = user.VoiceTelephoneNumber
else
    'error - no user data found
end if

This next example demonstrates how to get the phone number for a specific user:

dim user as p
dim phone as c
user = a5ws_GetUserValuesActiveDirectory("UserLoginName")
if variable_exists("user.SamAccountName") ' User data was found
    phone = user.VoiceTelephoneNumber
end if

This example demonstrates getting an optional parameter (physicalDeliveryOfficeName):

dim user as p
dim office as c
user = a5ws_GetUserValuesActiveDirectory("","physicalDeliveryOfficeName")
if variable_exists("user.SamAccountName") ' User data was found
    office= user.physicalDeliveryOfficeName
end if

In this example, two optional parameters are fetched (physicalDeliveryOfficeName and homePhone):

dim user as p
dim office as c
dim home_phone as c
user = a5ws_GetUserValuesActiveDirectory("","physicalDeliveryOfficeName,homePhone")
if variable_exists("user.SamAccountName") ' User data was found
    office= user.physicalDeliveryOfficeName
    home_phone = user.homePhone
end if

If the additional properties is too long, the values can be passed in as a list:

dim addProps as c
addProps = <<%txt%
physicalDeliveryOfficeName
homePhone
%txt%

dim user as p
dim UserLoginName as c = "jsmith"
dim office as c
dim home_phone as c
user = a5ws_GetUserValuesActiveDirectory(UserLoginName ,addProps)
if variable_exists("user.SamAccountName") ' User data was found
    office= user.physicalDeliveryOfficeName
    home_phone = user.homePhone
end if

A5WS_Login_User Function

Syntax

Result as P = a5ws_Login_User(C userid ,C password [,C targetpage [,* Localrequest [,* Localsession [,* Localresponse ]]]])

Arguments

Result: result.error = Will return FALSE if the login is successful. result.RedirectURL Successful Login - Will contain the name of the page set as the redirect page after login from the web security configuration. If TargetPage has a value, result.RedirectURL will have the value from TargetPage. Failed Login - Will contain the name of the page set as the "Redirect page - login" from the web security settings.
userid: A valid Userid for a user in the security system
password: A valid password for a user in clear text (not encrypted) .
targetpage: Optional. The name of a page to navigate to after a successful login. This overrides any page defined in the security settings.
Localrequest: *
Localsession: *
Localresponse: *

Description

Log in user on a web page using supplied values. Returns <pointer>.error, <pointer>.RedirectURL. If error = .F. , RedirectURL will contain the target page. If error = .T., it will return the login redirect page.

Discussion

The A5WS_Login_User() will login a user using the web security system. the UserID and Password must match the values saved in the security system for a valid user. If the login suceeds, Result.Error will return 'FALSE' and Result.RedirectURL will contain name of the page set as the "Redirect page after login" from the web the security settings . If TargetPage has a value, result.RedirectURL will have the value from TargetPage. If the login fails, Result.Error will return 'TRUE' and Result.RedirectURL will contain the page designated in the security settings as the "Redirect page - Login".

Example

The following example attempts to login a user with a UserID = "[email protected]" and a password = "Password". This user does NOT exist in the system. The page designated as the login page in the security configuration is "login.a5w"

dim pResult as p
pResult = a5ws_Login_User("[email protected]","Password")
?pResult
= error = .T.
RedirectURL = "login.a5w"

The following example attempts to login a user with a UserID = "[email protected]" and a password = "Password". This user DOES exist in the system. A TargetPage is supplied.

dim pResult as p
pResult = a5ws_Login_User("[email protected]","Password","administration.a5w")
?pResult
= error = .F.
RedirectURL = "administration.a5w"

Note - once you have a value for RedirectURL, you need to redirect the user, for example:

if return.error = .f.
   response.redirect("index.a5w") ' login success page
else
   response.redirect("message.a5w") ' login failed message page
end if

Limitations

Web applications only.

See Also

A5WS_LogoutUser Function

Syntax

Result_Flag as L = a5ws_LogoutUser([* Localsession [,* Localrequest [,* Localresponse ]]])

Arguments

Result_Flag: .T. = The user was logged out. .F. = The user was not logged out.
Localsession: *
Localrequest: *
Localresponse: *

Description

Log out the current user and remove the remember me cookie. This can only be used on a web page.

Discussion

Removes all login information for the current user from the session. The A5WS_LogoutUser() function removes all login information for the current logged in user

Example

A5WS_LogoutUser()

Limitations

May be used on A5W pages in web applications only.

See Also

A5WS_OpenWebSecurity Function

Syntax

C a5ws_OpenWebSecurity([C project ])

Arguments

project: Optional. The name of a project.

Description

Display the Web Security options available for this project

Discussion

Displays the Web Security dialog. The A5WS_OpenWebSecurity() function displays the Web Security dialog.

Limitations

Web applications only

See Also

A5WS_PageSecurity Function

Syntax

V a5ws_Pagesecurity([C pagename ])

Arguments

pagename: The name of a page.

Description

Assign security permissions for web pages

Discussion

Displays the Page Security Assignment dialog. The A5WS_PageSecurity() function displays the Page Security Assignment dialog.

Limitations

Web applications only.

See Also

a5ws_RevalidatePassword Function

Syntax

L a5ws_RevalidatePassword(C Password [,* Localrequest ])

Arguments

Password: Password to validate for the current user
Localrequest: (optional) Request object

Description

Web Security - Verify the currently logged in user's password ONLY. This can only be run from the Application Server

Discussion

Web Security - Verify the currently logged in user's password ONLY. The function tests if the supplied password matches the password for the currently logged in user only. It returns only true or false, request is required, and it only runs in a published application. If no one is logged in, or it is run from the local project, it returns false.

Limitations

This can only be run from the Application Server

See Also

Web Security Functions

A5WS_Save_User_Values Function

This function is deprecated and this page will be removed in the near future. Use A5WS_Save_WebUser_Values().

Syntax

Result as P = a5ws_Save_User_Values(P CurrentForm [,* request ])

Arguments

Result: The result value is not meaningful if the function is being used in a web component. result.errors = Will return TRUE if any errors are found during processing. result.error_text = Error messages returned.
CurrentForm: The CurrentForm variable, a system variable that refers to the contents of the dialog component.
request: The Request system variable. This variable explicitly passes all request variables to the function. Users are identified by a value in the request.variables property of the request variable. request.variables.guid = The user GUID value for the desired user record

Description

This function is deprecated after Alpha Five Version 9. The function A5WS_Save_WebUser_Values() should be used instead.

Discussion

This function is deprecated after Alpha Five Version 9. The function A5WS_Save_WebUser_Values() should be used instead.

The A5WS_Save_User_Values() function validates values from controls in a dialog component and then saves the values to fields in the Web Security User table. Only values passed in the request.variables property of the request variable are saved.

The name of each control in the dialog must exactly match the name of the field in the user table. A list of valid field names can be found by using the A5WS_User_File_Field_List() function. It is used in the Server Validate event of a dialog component. Adding Users with a Web Component shows how the function is used in dialog component event.

If validation errors are detected, the form will be redisplayed with the error message shown at the top of the form and the variable CurrentForm.Has_Error will be TRUE. The user can then make corrections and resubmit the form. If the variable CurrentForm.Has_Error = .T. prior to calling the function, the function will test the security control values for validation and return any errors, but will not save the values. The security values will only be saved if CurrentForm.Has_Error =.F.

1. Display the Form > Properties menu page of the Dialog Builder.
2. Click in the Server Events > Validate property.

Note that CurrentForm and Request are the names of variables created by the Application Server.

A5WS_Save_User_Values(CurrentForm, Request)

Using the Function Outside of a Dialog Component

The function is designed to be used within Server Events of a dialog component. However, it can be used on any Xbasic code section on a web page or component to save various values for a specific user. It is helpful to get a list of valid field names currently being used in the user security table by using the A5WS_User_File_Field_List() function. One additional field named groups can be saved. Groups should contain a comma delimited or CR-LF delimited list of the security groups assigned to the user. The group values can be the group_guid value for each group or the group_name of each group.

? a5ws_User_File_Field_List()
= Email
Guid
Password
Ulink
Userid

The function will only save values for fields passed to the function in the Request system variable as request.variables. and will only save values for fields currently being used by the security system.

Security Settings may be defined to require values in certain User Verification Fields during data entry on the web. If these fields are included in the Request variables, they can not be blank, or the record will not be saved and an error message will be returned.

A value MUST be passed to the function to find the current user. This MUST be request.variables.guid. No other input value can be used to find an existing record.

If the guid value is not passed to the function, the guid value is blank, or the guid value doesn't match an existing record, a new record will be created. A userid value must be an input value for a new record, or the save is cancelled and returns an error message. Userid does not have to be entered for an existing record unless the value for userid is being changed.

This code will find the user with a guid="20860aa66cfa4feb83ba25887d303f59" and change the email address to "[email protected]". If no user is found with that guid, nothing is saved and an error message is returned.

dim request.variables.guid as c
dim request.variables.email as c
request.variables.guid = "20860aa66cfa4feb83ba25887d303f59"
request.variables.email = "[email protected]"

This code will enter a new user record with a userid = "[email protected]" and an email address with the same value. The new user record will have a password added with the value of "password". Since no guid is input, a new record is created. The function will automatically create a new guid value for the record when the record is saved.

dim request.variables.userid as c
dim request.variables.email as c
dim request.variables.password as c
request.variables.userid = "[email protected]"
request.variables.email = "[email protected]"
request.variables.password = "password"

This code will set the user's group assignments to "Administrators" and "Marketing". The function will only save groups that are valid values in security groups definitions.

dim request.variables.groups as c
request.variables.groups = "Administrators,Marketing"

An output pointer must be defined. The function will always return the guid value for a saved record as .Controls.guid.value. The function will also return values for any fields passed to the function in the Request system variable.

dim output as p
dim output.controls as p
dim output.controls.guid.value as c

The function will return the values saved as .controls..value. The result.errors value can be tested to determine if any errors occurred during processing. Any error messages will be should in the result.error_text value.

dim result as p
dim error_message as c
dim group_list as c
result = a5ws_Save_User_Values(output,request)
if result.errors = .T. then
    error_message = result.error_text
    end
end if 
user_guid = output.controls.guid.value

Limitations

DEPRECATED

See Also

A5WS_Save_WebUser_Values Function

Syntax

Result as P = a5ws_Save_WebUser_Values(P CurrentForm [,* UserValue [,* request ]])

Arguments

Result

The result value is not meaningful if the function is being used in a web component.

result.errors = Will return TRUE if any errors are found during processing.
result.error_text = Error messages returned.

CurrentForm

UserValue

Optional. A pointer variable used to pass user defined value to the function. These will override the same values passed by the Request system variable. Users are identified by a value in the guid property of UserValue. If UserValue.guid is not specified, the function will use the value passed by the Request system variable.

UserValue.guid = The user GUID value for the desired user record

request

Optional. The Request system variable. The request variable should be considered READ ONLY. It is added automatically by the server when run from a web page. Users may be found by

request.variable.guid = The user GUID value for the desired user record

Description

The CurrentForm variable, a system variable that refers to the contents of the dialog component.

Validate & Save values in the 'CurrentForm' controls that match fields in the user table for the current project. 'UserValue' overrides values passed by the request system variable. Accepts values as 'UserValue.Email', 'UserValue.Ulink', etc

Discussion

The A5WS_Save_WebUser_Values() function validates values from controls in a dialog component and then saves the values to fields in the Web Security User table. If you only want to validate the values without saving, use the function A5WS_Validate_WebUser_Values. Only values passed in the request.variable property of the request variable, or values passed by the pointer UserValue, are saved. The value in request.variable.guid will be used to find an existing record. An optional value can be supplied in UserValue.guid to override the value in request.variable.guid. If both values are blank, the record will be considered a new record. The name of each control in the dialog must exactly match the name of the field in the user table. A list of valid field names can be found by using the A5WS_User_File_Field_List() function. It is used in the Server Validate event of a dialog component. Adding Users with a Web Component shows how the function is used in dialog component event. If validation errors are detected, the form will be redisplayed with the error message shown at the top of the form and the variable CurrentForm.Has_Error will be TRUE. The user can then make corrections and resubmit the form. If the variable CurrentForm.Has_Error = .T. prior to calling the function, the function will test the security control values for validation and return any errors, but will not save the values. The security values will only be saved if CurrentForm.Has_Error =.F.

1. Display the Form > Properties menu page of the Dialog Builder.
2. Click in the Server Events > Validate property.

Example

Note that CurrentForm and Request are the names of variables created by the Application Server.

A5WS_Save_WebUser_Values(CurrentForm)

Using the Function Outside of a Dialog Component

?a5ws_User_File_Field_List()
= Email
Guid
Password
Ulink
Userid

The function will only save values for fields passed to the function in the Request system variable as request.variable. and will only save values for fields currently being used by the security system. NOTE: Security Settings may be defined to require values in certain User Verification Fields during data entry on the web. If these fields are included in the Request or UserValue variables, they can not be blank, or the record will not be saved and an error message will be returned. A value MUST be passed to the function to find the current user. This MUST be provided by either the system supplied request.variable.guid or a user supplied value in UserValue.guid. No other input value can be used to find an existing record. WARNING: If the guid value is not passed to the function, the guid value is blank, or the guid value doesn't match an existing record, a new record will be created. A userid value must be an input value for a new record, or the save is cancelled and returns an error message. Userid does not have to be entered for an existing record unless the value for userid is being changed. Only values sent to the function will be saved. If the record already exists, any values not sent to the function are unchanged. If the record is a new record, the security settings may have defined required fields. If required fields as not supplied for a new record, validation may fail, and nothing wil be saved. This code below will set the parameters to send to the function to find the user with a guid="20860aa66cfa4feb83ba25887d303f59" and change the email address to "[email protected]".

dim uservalue as p
dim uservalue.guid as c
dim uservalue.email as c
uservalue.guid = "20860aa66cfa4feb83ba25887d303f59"
uservalue.email = "[email protected]"

This code could be used in place of the code above to set the parameters to send to the function to enter a new user record with a userid = "[email protected]" and an email address with the same value. The new user record will have a password added with the value of "password". Since no guid is input, a new record is created. The function will automatically create a new guid value for the record when the record is saved.

dim uservalue.userid as c
dim uservalue.email as c
dim uservalue.password as c
uservalue.userid = "[email protected]"
uservalue.email = "[email protected]"
uservalue.password = "password"

This code will set the parameters to set the user's group assignments to "Administrators" and "Marketing" if the user groups are being added or edited. The function will only save groups that are valid values in security groups definitions.

dim uservalue.groups as c
uservalue.groups = "Administrators,Marketing"

An output pointer must be defined before the function is run. The function will always return the guid value for a saved record as .Controls.guid.value. If a new record was created, the function will NOT update the value in request.variable.guid if request variables were passed to the function. Request.variable.guid may be blank for a new record. The function will also return values for any fields passed to the function in the Request system variable.

dim output as p
dim output.controls as p
dim output.controls.guid.value as c

The parameters to send to the function, and the output pointers must be set before the function is run. When the function is run, it will return the values saved as .controls..value. The result.errors value can be tested to determine if any errors occured during processing. Any error messages will be should be returned in the result.error_text value.

dim result as p
dim error_message as c
result = a5ws_Save_WebUser_Values(output,uservalue)
if result.errors = .T. then
    error_message = result.error_text
    end
end if 
user_guid = output.controls.guid.value

You can reload the values saved by the function back into the pointer variable output with the function A5WS_Get_WebUser_Values after the save function was run.

dim uservalue as p
dim uservalue.guid as c
uservalue.guid = output.controls.guid.value ' this was populated when the record was saved above. 
dim result as p
dim error_message as c
result = a5ws_Get_WebUser_Values(output,uservalue)
if result.errors = .T. then
    error_message = result.error_text
    end
end if 
user_id = output.controls.user.value

Limitations

May only be used in a web component or web page.

See Also

A5WS_SecurityActive Function

Syntax

Result_Flag as L = a5ws_SecurityActive([* localrequest [,* r ]])

Arguments

Result_Flag: .T. = Web security is active in the current web security settings. .F. = Web security is not active in the current web security settings.
localrequest: The Request system variable. This variable explicitly passes all request variables to the function.
r: *

Description

Determine if web security is active. Used only in web pages and components

Discussion

Determine if web security is active. May be used on A5W pages and web components.

This code can be added to a web page to show a message about the security status.

<%a5 
if A5WS_SecurityActive(request) then 
?"Security is Active" 
else 
?"Security is Not Active" 
end if 
%>

Limitations

Web applications only

See Also

A5WS_SecurityQues Function

Syntax

C a5ws_SecurityQues()

Description

Deprecated - use a5ws_SecurityQuestions()

Discussion

Deprecated. Use A5WS_SecurityQuestions Function instead. The A5WS_SecurityQues() function displays the Login Recovery Security Questions dialog, which allows you to edit the list of security questions for project.

Limitations

Web publishing applications only.

See Also

A5WS_SecurityQuestions Function

Syntax

C a5ws_SecurityQuestions()

Description

Web Security - Enter / Edit the list of security questions used for user validation

Discussion

The A5WS_SecurityQuestions() function displays the Login Recovery Security Questions dialog, which allows you to edit the list of security questions for project.

Limitations

Web publishing applications only.

See Also

A5WS_SecuritySettings Function

Syntax

C a5ws_SecuritySettings([C project ])

Arguments

project: Optional. The name of the project that will use these security settings. If not specified, Alpha Anywhere will use the current project.

Description

Enter / Edit web security properties for current project

Discussion

The A5WS_SecuritySettings() function displays the Security Settings dialog box.

Limitations

Web publishing applications only.

See Also

A5WS_User_File_Field_List Function

Syntax

Field_List as C = a5ws_User_File_Field_List([C format [,* request ]])

Arguments

Field_List

A CR-LF list of user table fields used in the current web project.

format

Optional. A display format information to use to output field information. Options are:

"n" = fieldname
"t" = simple field type
"w" = field width
Default is fieldname only. If format is specified, the output will use the "|" delimiter between values.

request

Optional. The Request system variable. This variable explicitly passes all request variables to the function. Required if run from a web page.

Description

Retrieve a list of active fields in CR-LF list for web user table in the current project. Format - n - fieldnames, t - simple field type, w - field width.

Discussion

Retrieve a list of active fields in CR-LF list for web user table in the current project. The field list will be determined by the current security settings and will show only fields currently used. The Request system variable is only needed if the function is used on a web page or in a web component.

The following code run in the interactive window will return a list of user table fields for the current selected web project profile.

?a5ws_User_File_Field_List()
= Email
Guid
PassEnt
PassExp
Password
RedirPage
RememberMe
Ulink
Userid

The following code run in the interactive window will return a list of user table fields and information about the fields. The width information is helpful when building a web component.

?a5ws_User_File_Field_List("ntw")
= Email|C|40
Guid|C|36
PassEnt|T|17
PassExp|T|17
Password|C|40
RedirPage|C|60
RememberMe|L|1
Ulink|C|40
Userid|C|60

Limitations

Web applications only.

See Also

A5WS_User_Groups_Dialog Function

Syntax

C a5ws_User_Groups_Dialog([C project ])

Arguments

project: The name of a web project. A blank entry uses the currently selected project.

Description

Displays the add user and groups dialog for the current Web project

Discussion

The A5WS_User_Groups_Dialog() function displays the web Users and Groups dialog.

Example

A5WS_User_Groups_Dialog()

Limitations

Web applications only.

See Also

A5WS_Validate_WebUser_Values Function

Syntax

Result as P = a5ws_Validate_WebUser_Values(P CurrentForm [,P UserValue ,P request ])

Arguments

Result

The result value is not meaningful if the function is being used in a web component.

result.errors = Will return TRUE if any errors are found during processing.
result.error_text = Error messages returned.

CurrentForm

The CurrentForm variable, a system variable that refers to the contents of the dialog component.

UserValue

request

Optional. The Request system variable. The request variable should be considered READ ONLY. It is added automatically by the server when run from a web page. Users may be found by request.variable.guid = The user GUID value for the desired user record

Description

Validate values only in the 'CurrentForm' controls that match fields in the user table for the current project. a5ws_Validate_WebUser_Values.errors = .F. if validated 'UserValue' overrides values passed by the request system variable. Accepts values as 'UserValue.Email', 'UserValue.Ulink', etc

Discussion

The A5WS_Validate_WebUser_Values() function validates values from controls in a dialog component but does NOT save the values to fields in the Web Security User table. If you need to validate and save values, use the function A5WS_Save_WebUser_Values. Only values passed in the request.variable property of the request variable are saved. The value in request.variable.guid will be used to find an existing record. An optional value can be supplied in UserValue.guid to override the value in request.variable.guid. If both values are blank, the record will be considered a new record. The name of each control in the dialog must exactly match the name of the field in the user table. A list of valid field names can be found by using the A5WS_User_File_Field_List() function. It is used in the Server Validate event of a dialog component. Adding Users with a Web Component shows how the function is used in dialog component event. If validation errors are detected, the form will be redisplayed with the error message shown at the top of the form and the variable CurrentForm.Has_Error will be TRUE. The user can then make corrections and resubmit the form. If the variable CurrentForm.Has_Error = .T. prior to calling the function, the function will test the security control values for validation and return any errors, but will not save the values. The security values will only be saved if CurrentForm.Has_Error =.F.

Display the Form > Properties menu page of the Dialog Builder.
Click in the Server Events > Validate property.

Example

Note that CurrentForm and Request are the names of variables created by the Application Server.

A5WS_Validate_WebUser_Values(CurrentForm)

Using the Function Outside of a Dialog Component

The function is designed to be used within Server Events of a dialog component. However, it can be used on any Xbasic code section on a web page or component to validate various values for a specific user. It is helpful to get a list of valid field names currently being used in the user security table by using the A5WS_User_File_Field_List() function. One additional field named groups can be checked. Groups should contain a comma delimited or CR-LF delimited list of the security groups assigned to the user. The group values can be the group_guid value for each group or the group_name of each group.

?a5ws_User_File_Field_List()
= Email
Guid
Password
Ulink
Userid

The function will only validate values for fields passed to the function in the Request system variable as request.variable. and will only validate values for fields currently being used by the security system. NOTE: Security Settings may be defined to require values in certain User Verification Fields during data entry on the web. If these fields are included in the Request or UserValue variables, they can not be blank, or the record will not be validated and an error message will be returned. A value MUST be passed to the function to find the current user. This MUST be provided by either the system supplied request.variable.guid or a user supplied value in UserValue.guid. No other input value can be used to find an existing record. WARNING: If the guid value is not passed to the function, the guid value is blank, or the guid value doesn't match an existing record, the validate will assume this is a new record. A userid value must be an input value for a new record, or the validate is cancelled and returns an error message. Userid does not have to be entered for an existing record unless the value for userid is being changed. This code below will set the parameters to send to the function to find the user with a guid="20860aa66cfa4feb83ba25887d303f59" and validate the email address of "[email protected]".

dim uservalue as p
dim uservalue.guid as c
dim uservalue.email as c
uservalue.guid = "20860aa66cfa4feb83ba25887d303f59"
uservalue.email = "[email protected]"

This code could be used in place of the code above to set the parameters to send to the function to validate a new user record with a userid = "[email protected]" and an email address with the same value. The new user record will have a password tested using the value of "password". Since no guid is input, this is considered a new record. The function will automatically create a new guid value for the record only when the record is saved using A5WS_Save_WebUser_Values.

dim uservalue.userid as c
dim uservalue.email as c
dim uservalue.password as c
uservalue.userid = "[email protected]"
uservalue.email = "[email protected]"
uservalue.password = "password"

This code will test the user's group assignments of "Administrators" and "Marketing". The function will only validate groups that are valid values in security groups definitions.

dim uservalue.groups as c
uservalue.groups = "Administrators,Marketing"

An output pointer must be defined before the function is run. The function will always return the guid value for an existing record as .Controls.guid.value. The function will NOT cahnge the value in request.variable.guid if request variables were passed to the function. The function will also test values for any fields passed to the function in the Request system variable.

dim output as p
dim output.controls as p
dim output.controls.guid.value as c

The function will return the results of the validation in two ways. If the values passed validation, .has_error = .F., and result.errors = .F.. If the values failed validation, .has_error = .T., and result.errors = .T. Error messages will be shown in in .error_text and result.error_text. The actual fieldname values that failed validation will have .controls..has_error = .T. and may have an error message in .controls..error_message. The result.errors value can be tested to determine if any errors occured during processing.

dim result as p
dim error_message as c
result = a5ws_Validate_WebUser_Values(output,uservalue)
if result.errors = .T. then
    error_message = result.error_text
    end
end if 
user_guid = output.controls.guid.value

Limitations

May only be used in a web component or web page.

See Also

A5WS_WebUser_Exists Function

Syntax

Result_Flag as L = a5ws_WebUser_Exists(C Userid [,* Localrequest ])

Arguments

Result_Flag: .T. = A user with this userid exists in the Web Security. .F. = A user with this userid does NOT exist in the Web Security.
Userid: A userID to test.
Localrequest: Optional. The Request system variable. It is added automatically by the server when run from a web page.

Description

Will return .T. if a user with this userid exists in the Web Security

Discussion

The A5WS_WebUser_Exists() tests whether a user exists in the web security system having the user ID supplied in UserID. If the Userid value is not found, the Result_Flag will return 'False'. Request is added automatically by the server when run from a web page.

Example

The following example tests if a record with a userid of "[email protected]" exists in web security.

?a5ws_WebUser_Exists("[email protected]")
 = .T.

Limitations

Web applications only.

See Also

Report an issue with this page