• Publicity: Public Only All

community-core-procs.tcl

Community routines (dealing with users, parties, etc.).

Location:
packages/acs-tcl/tcl/community-core-procs.tcl
Created:
11 Aug 2000
Author:
Jon Salz <jsalz@arsdigita.com>
CVS Identification:
$Id: community-core-procs.tcl,v 1.100 2024/09/11 06:15:48 gustafn Exp $

Procedures in this file

Detailed information

acs_user::ScreenName (public)

 acs_user::ScreenName

Get the value of the ScreenName parameter. Checked to ensure that it only returns none, solicit, or require.

Testcases:
user_screen_name_conf

acs_user::approve (public)

 acs_user::approve -user_id user_id

Approve a user

Switches:
-user_id (required)

Testcases:
acs_user__registered_user_p, acs_user__ban_approve

acs_user::ban (public)

 acs_user::ban -user_id user_id

Ban a user

Switches:
-user_id (required)

Testcases:
acs_user__registered_user_p, acs_user__ban_approve

acs_user::change_state (public)

 acs_user::change_state -user_id user_id -state state

Change the membership state of a user.

Switches:
-user_id (required)
-state (required)

Testcases:
auth_authenticate

acs_user::create_portrait (public)

 acs_user::create_portrait -user_id user_id \
    [ -description description ] [ -filename filename ] \
    [ -mime_type mime_type ] -file file

Sets (or resets) the portraif for current user to the one specified.

Switches:
-user_id (required)
user_id of user whose portrait we want to set.
-description (optional)
A caption for the portrait.
-filename (optional)
Original filename of the portrait. Used to guess the mimetype if an explicit one is not specified.
-mime_type (optional)
mimetype of the portrait. If missing, filename will be used to guess one.
-file (required)
Actual file containing the portrait
Returns:
item_id of the new content item

Testcases:
acs_admin_merge_MergeUserInfo, auth_authenticate, demote_promote_a_user

acs_user::delete (public)

 acs_user::delete -user_id user_id [ -permanent ]

Delete a user

Switches:
-user_id (required)
-permanent (optional, boolean)
If provided the user will be deleted permanently from the database. Otherwise the user state will merely be set to "deleted".

Testcases:
auth_authenticate, auth_create_user, auth_password_change, auth_password_reset, acs_subsite_expose_bug_1144, acs_subsite_test_email_confirmation

acs_user::demote_user (public)

 acs_user::demote_user [ -user_id user_id ] [ -delete_portrait ]

Demotes an ACS user to a person/party. This will fail if other tables have content referencing the users table. It is probably best for tables created in other packages to reference persons, parties, or acs_objects instead. This proc could be extended with an option to find all referenced tables and remove rows referencing this user.

Switches:
-user_id (optional)
the user_id in the acs system that should be demoted.
-delete_portrait (optional, boolean)
Delete the portrait of the user
Error:
An error is thrown if user_id is not in the users table.

Testcases:
demote_promote_a_user

acs_user::erase_portrait (public)

 acs_user::erase_portrait -user_id user_id

Erases portrait of a user

Switches:
-user_id (required)
user_id of user whose portrait we want to delete

Testcases:
auth_authenticate, demote_promote_a_user

acs_user::flush_cache (public)

 acs_user::flush_cache -user_id user_id

Flush all caches for specified user. This makes sense when we really want all user information to be flushed. Finer-grained procs exist and should be used when is clear what we want to delete.

Switches:
-user_id (required)
Author:
Peter Marklund
See Also:

Testcases:
auth_confirm_email, demote_promote_a_user

acs_user::flush_user_info (public)

 acs_user::flush_user_info -user_id user_id

Flush only info coming from acs_user::get_user_info proc. This includes also lookup by username, because username and authority_id might also have changed.

Switches:
-user_id (required)
See Also:

Testcases:
demote_promote_a_user

acs_user::get (public)

 acs_user::get [ -user_id user_id ] [ -authority_id authority_id ] \
    [ -username username ] [ -element element ] [ -array array ] \
    [ -include_bio ]

Get all information about a user, together with related person, party and object information. In case only user-specific information was needed, probably a better alternative could be acs_user::get_person_info.

The attributes returned are all those retrieved by person::get and acs_user::get_person_info.

Switches:
-user_id (optional)
User id to retrieve. Defaults to currently connected user.
-authority_id (optional)
if user_id was not specified, but a username was given, this proc will try to retrieve a user_id from username and authority. If authority_id is left blank, will default to the local authority.
-username (optional)
if specified and no user_id was give, will be used to retrieve user_id from the authority. If no user_id and no username were specified, proc will default to currently connected user.
-element (optional)
If specified, only this element in the dict will be returned. If an array was specified, This function will contain only this element.
-array (optional)
The name of an array into which you want the information put. This parameter is not mandatory, and the actual suggested way to retrieve information from this proc is to just set a variable from the return value and use it as a dict.
-include_bio (optional, boolean)
Options:
-include_bio
Whether to include the bio in the user information. This flag is deprecated and bio will be now always returned.
Returns:
dict or a single string value if the -element parameter was specified.
Author:
Lars Pind <lars@collaboraid.biz>
See Also:

Testcases:
auth_create_user, auth_password_reset, auth_authentication_implementations, sync_actions, sync_snapshot, sync_batch_ims_test, ad_proc_change_state_member

acs_user::get_by_username (public)

 acs_user::get_by_username [ -authority_id authority_id ] \
    -username username

Returns user_id from authority and username. Returns the empty string if no user found.

Switches:
-authority_id (optional)
The authority. Defaults to local authority.
-username (required)
The username of the user you're trying to find.
Returns:
user_id of the user, or the empty string if no user found.

Testcases:
auth_authenticate, auth_create_user, auth_password_reset

acs_user::get_element (public)

 acs_user::get_element [ -user_id user_id ] \
    [ -authority_id authority_id ] [ -username username ] \
    -element element

Get a particular element from the basic information about a user returned by acs_user::get. Throws an error if the element does not exist. It is recommended to use use acs_user::get instead. This function will be probably deprecated after the release of 5.10.

Switches:
-user_id (optional)
-authority_id (optional)
-username (optional)
-element (required)
Options:
-user_id
The user_id of the user to get the bio for. Leave blank for current user.
-element
Which element you want to retrieve.
Returns:
The element asked for.
See Also:

Testcases:
auth_confirm_email

acs_user::get_portrait_id (public)

 acs_user::get_portrait_id -user_id user_id

Return the image_id of the portrait of a user, if it does not exist, return 0

Switches:
-user_id (required)
user_id of the user for whom we need the portrait

Testcases:
acs_admin_merge_MergeUserInfo, auth_authenticate

acs_user::get_user_id_by_screen_name (public)

 acs_user::get_user_id_by_screen_name -screen_name screen_name

Returns the user_id from a screen_name, or empty string if no user found. Searches all users, including banned, deleted, unapproved, etc.

Switches:
-screen_name (required)

Testcases:
demote_promote_a_user

acs_user::get_user_info (public)

 acs_user::get_user_info -user_id user_id [ -element element ]

Extracts user information. Differently from acs_user::get this proc won't return generic party information.

Switches:
-user_id (required)
-element (optional)
if specified, only value with this key in the dict will be returned.
Returns:
dict or a single string value if the -element parameter was specified.
See Also:

Testcases:
auth_authenticate, auth_email_on_password_change, sync_actions, sync_batch_ims_test, acs_subsite_test_email_confirmation, demote_promote_a_user

acs_user::promote_person_to_user (public)

 acs_user::promote_person_to_user [ -person_id person_id ] \
    [ -authority_id authority_id ] [ -username username ] \
    [ -password password ] [ -locale locale ]

Promotes a person/party to an ACS user.

Switches:
-person_id (optional)
the person_id in the acs system that should be promoted to a user.
-authority_id (optional)
the authority that will be used for the user.
-username (optional)
the username to be used for this user. Defaults to the person's email
-password (optional)
the password to be used for this user. Defaults to a randomly generated password.
-locale (optional)
locale to be used in user preferences. Defaults to the site-wide locale is taken.
Returns:
The user_id of the person promoted to user
Error:
An error is thrown if the username is already in use, or the person_id has no email address, or if person_id is not in the persons table.
See Also:

Testcases:
demote_promote_a_user

acs_user::registered_user_p (public)

 acs_user::registered_user_p [ -user_id user_id ]

Return 1 if the specified user (defaults to logged-in user) is a registered user and 0 otherwise. A registered user is a user who is in the view registered_users and this is primarily true for any user who is approved and has a verified e-mail.

Switches:
-user_id (optional)
The id of the user to check.
Author:
Malte Sussdorff <malte.sussdorff@cognovis.de>

Testcases:
auth__delete_local_account, acs_user__registered_user_p, acs_user__ban_approve

acs_user::reject (public)

 acs_user::reject -user_id user_id

Reject a user

Switches:
-user_id (required)

Testcases:
demote_promote_a_user

acs_user::site_wide_admin_p (public)

 acs_user::site_wide_admin_p [ -user_id user_id ]

Return 1 if the specified user (defaults to logged-in user) is site-wide administrator and 0 otherwise.

Switches:
-user_id (optional)
The id of the user to check for admin privilege.
Author:
Peter Marklund

Testcases:
demote_promote_a_user

acs_user::unapprove (public)

 acs_user::unapprove -user_id user_id

Unapprove a user

Switches:
-user_id (required)

Testcases:
demote_promote_a_user

acs_user::update (public)

 acs_user::update -user_id user_id [ -authority_id authority_id ] \
    [ -username username ] [ -screen_name screen_name ] \
    [ -password_question password_question ] \
    [ -password_answer password_answer ] \
    [ -email_verified_p email_verified_p ]

Update information about a user. Feel free to expand this with more switches later as needed, as long as they're optional.

Switches:
-user_id (required)
The ID of the user to edit
-authority_id (optional)
-username (optional)
-screen_name (optional)
-password_question (optional)
-password_answer (optional)
-email_verified_p (optional)
Options:
-authority_id
Authority
-username
Username
-screen_name
The new screen_name for the user
-password_question
The new password_question for the user
-password_answer
The new password_question for the user
-email_verified_p
Whether the email address has been verified
Author:
Lars Pind <lars@collaboraid.biz>

Testcases:
auth_authentication_implementations, demote_promote_a_user

party::approved_members (public)

 party::approved_members -party_id party_id \
    [ -object_type object_type ]

Get a list of approved members of the given party.

Switches:
-party_id (required)
The id of the party to get members for
-object_type (optional)
Restrict to only members of this object type. For example, if you are only interested in users, set to "user".
Author:
Peter Marklund

Testcases:
No testcase defined.

party::email (public)

 party::email -party_id party_id

Return the parties email. This function will be probably deprecated in the future: please use the new generic party API.

Switches:
-party_id (required)
Returns:
the parties email.
See Also:

Testcases:
community_cc_procs, person_procs_test

party::flush_cache (public)

 party::flush_cache -party_id party_id

Flush the party cache

Switches:
-party_id (required)

Testcases:
No testcase defined.

party::get (public)

 party::get [ -party_id party_id ] [ -email email ] \
    [ -element element ]

Returns party information. Will also retrieve whether this party is also a person, a group, a user or a registered user and in this case also extra information belonging in referenced table will be extracted.

Switches:
-party_id (optional)
id of the party
-email (optional)
if specified and no party_id is given, party lookup will happen by email.
-element (optional)
if specified, only this attribute will be returned from the whole dict.
Returns:
dict containing party information, or an empty dict if no party was found. A string if 'element' was specified.

Testcases:
acs_subsite_test_email_confirmation

party::get_by_email (public)

 party::get_by_email -email email

Return the party_id of the party with the given email. Uses a lowercase comparison as we don't allow for parties to have emails that only differ in case. Returns empty string if no party found.

Switches:
-email (required)
Returns:
party_id

Testcases:
acs_mail_lite_inbound_procs_check, community_cc_procs, party_procs_test

party::get_by_email_not_cached (public)

 party::get_by_email_not_cached -email email

Return the party_id of the party with the given email. Uses a lowercase comparison as we don't allow for parties to have emails that only differ in case. Returns empty string if no party found.

Switches:
-email (required)
Returns:
party_id

Testcases:
No testcase defined.

party::name (public)

 party::name [ -party_id party_id ] [ -email email ]

Gets the party name of the provided party_id

Switches:
-party_id (optional)
The party_id to get the name from.
-email (optional)
The email of the party
Returns:
The party name
Authors:
Miguel Marin <miguelmarin@viaro.net>
Viaro Networks www.viaro.net
Malte Sussdorff <malte.sussdorff@cognovis.de>

Testcases:
No testcase defined.

party::new (public)

 party::new [ -form_id form_id ] [ -variable_prefix variable_prefix ] \
    [ -creation_user creation_user ] [ -creation_ip creation_ip ] \
    [ -party_id party_id ] [ -context_id context_id ] [ -email email ] \
    party_type

Creates a party of this type by calling the .new function for the package associated with the given party_type. This function will fail if there is no package.

There are now several ways to create a party of a given type. You can use this Tcl API with or without a form from the form system, or you can directly use the PL/SQL API for the party type.

Examples: 


    # OPTION 1: Create the party using the Tcl Procedure. Useful if the
    # only attribute you need to specify is the party name

    db_transaction {
        set party_id [party::new -email "joe@foo.com" $party_type]
    }


    # OPTION 2: Create the party using the Tcl API with a templating
    # form. Useful when there are multiple attributes to specify for the
    # party

    template::form create add_party
    template::element create add_party email -value "joe@foo.com"

    db_transaction {
        set party_id [party::new -form_id add_party $party_type ]
    }

    # OPTION 3: Create the party using the PL/SQL package automatically
    # created for it

    # creating the new party
    set party_id [db_exec_plsql add_party "
      begin
        :1 := ${party_type}.new (email => 'joe@foo.com');
      end;
    "]

Switches:
-form_id (optional)
The form id from templating form system (see example above)
-variable_prefix (optional)
-creation_user (optional)
-creation_ip (optional)
-party_id (optional)
-context_id (optional)
-email (optional)
The email of this party. Note that if email is specified explicitly, this value will be used even if there is a email attribute in the form specified by form_id.
Parameters:
party_type (required)
The type of party we are creating
Returns:
party_id of the newly created party
Author:
Oumi Mehrotra <oumi@arsdigita.com>
Created:
2001-02-08

Testcases:
No testcase defined.

party::party_p (public)

 party::party_p -object_id object_id
Switches:
-object_id (required)
object_id which is checked if it is a party
Returns:
true if object_id is a party
Author:
Malte Sussdorff
Created:
2007-01-26

Testcases:
No testcase defined.

party::types_valid_for_rel_type_multirow (public)

 party::types_valid_for_rel_type_multirow \
    [ -datasource_name datasource_name ] [ -start_with start_with ] \
    [ -rel_type rel_type ]

creates multirow datasource containing party types starting with the $start_with party type. The datasource has columns that are identical to the relation_types_allowed_to_group_multirow, which is why the columns are broadly named "object_*" instead of "party_*". A common template can be used for generating select widgets etc. for both this datasource and the relation_types_allowed_to_groups_multirow datasource. All subtypes of $start_with are returned, but the "valid_p" column in the datasource indicates whether the type is a valid one for $group_id. Includes fields that are useful for presentation in a hierarchical select widget:

  • object_type
  • object_type_enc - encoded object type
  • indent - an HTML indentation string
  • pretty_name - pretty name of object type
  • valid_p - 1 or 0 depending on whether the type is valid

Switches:
-datasource_name (optional, defaults to "object_types")
-start_with (optional, defaults to "party")
-rel_type (optional, defaults to "membership_rel")
- if unspecified, then membership_rel is used
Author:
Oumi Mehrotra <oumi@arsdigita.com>
Created:
2000-02-07

Testcases:
No testcase defined.

party::update (public)

 party::update -party_id party_id [ -email email ] [ -url url ]

Update information about a party.

Switches:
-party_id (required)
The ID of the party to edit
-email (optional)
The new email for the party
-url (optional)
The new URL for the party
Author:
Lars Pind <lars@collaboraid.biz>

Testcases:
auth_authentication_implementations, party_procs_test

person::delete (public)

 person::delete -person_id person_id

delete a person

Switches:
-person_id (required)

Testcases:
person_procs_test

person::flush_cache (public)

 person::flush_cache -person_id person_id

Flush all caches for specified person. This makes sense when we really want all person information to be flushed. Finer-grained procs exist and should be used when is clear what we want to delete.

Switches:
-person_id (required)
See Also:

Testcases:
demote_promote_a_user

person::flush_person_info (public)

 person::flush_person_info -person_id person_id

Flush only info coming from person::get_person_info proc.

Switches:
-person_id (required)
See Also:

Testcases:
No testcase defined.

person::get (public)

 person::get -person_id person_id [ -element element ]

Get person information together with inherited party and object one. If person-only information is what you need, probably a better choice would be person::get_person_info.

Switches:
-person_id (required)
-element (optional)
if specified, only value in dict with this key will be returned.
Returns:
a dict or a single string value if -element was specified.
See Also:

Testcases:
person_procs_test, process_objects_csv

person::get_bio (public)

 person::get_bio [ -person_id person_id ] [ -exists_var exists_var ]

Get the value of the user's bio(graphy) field.

Switches:
-person_id (optional)
-exists_var (optional)
Options:
-person_id
The person_id of the person to get the bio for. Leave blank for currently logged-in user.
-exists_var
The name of a variable in the caller's namespace, which will be set to 1 if the bio column is not null. Leave blank if you're not interested in this information.
Returns:
The bio of the user as a text string.
Author:
Lars Pind <lars@collaboraid.biz>

Testcases:
person_procs_test

person::get_person_info (public)

 person::get_person_info -person_id person_id [ -element element ]

Extracts person information. Differently from person::get this proc won't return generic party information.

Switches:
-person_id (required)
-element (optional)
if specified, only value in dict with this key will be returned.
Returns:
a dict or a single string value if -element was specified.
See Also:

Testcases:
demote_promote_a_user

person::get_person_info_not_cached (public)

 person::get_person_info_not_cached -person_id person_id

Extracts person information. Differently from person::get this proc won't return generic party information.

Switches:
-person_id (required)
See Also:

Testcases:
No testcase defined.

person::name (public)

 person::name [ -person_id person_id ] [ -email email ]

Return the name of a person.

Switches:
-person_id (optional)
-email (optional)
See Also:

Testcases:
person_procs_test

person::name_flush (public, deprecated)

 person::name_flush -person_id person_id [ -email email ]
Deprecated. Invoking this procedure generates a warning.

Flush the person::name cache. Deprecated: please use suggested alternative.

Switches:
-person_id (required)
-email (optional)
See Also:

Testcases:
No testcase defined.

person::new (public)

 person::new -first_names first_names -last_name last_name \
    [ -email email ]

create a new person

Switches:
-first_names (required)
-last_name (required)
-email (optional)

Testcases:
person_procs_test

person::person_p (public)

 person::person_p -party_id party_id

Is this party a person?

Switches:
-party_id (required)

Testcases:
person_procs_test

person::update (public)

 person::update -person_id person_id [ -first_names first_names ] \
    [ -last_name last_name ] [ -bio bio ]

Update person information.

Switches:
-person_id (required)
-first_names (optional)
-last_name (optional)
-bio (optional)

Testcases:
person_procs_test

person::update_bio (public, deprecated)

 person::update_bio -person_id person_id -bio bio
Deprecated. Invoking this procedure generates a warning.

Update the bio for a person. Deprecated: please use person::update as now supports optional parameters.

Switches:
-person_id (required)
The ID of the person to edit bio for
-bio (required)
The new bio for the person
Author:
Lars Pind <lars@collaboraid.biz>
See Also:

Testcases:
No testcase defined.
[ show source ]