'S3 framework function
Designed to be called when a user is created through:
- prepop
- approved automatically during registration
- approved by admin
- added by admin
- updated by admin
Does the following:
- Adds user to the \'Authenticated\' role
- Adds any default roles for the user
- @ToDo: adds them to the Org_x Access role
@param user: the user Storage() or Row
@param password: optional password to include in a custom welcome_email'

def s3_approve_user(self, user, password=None):

    user_id = user.id
    if (not user_id):
        return None
    db = current.db
    s3db = current.s3db
    deployment_settings = current.deployment_settings
    settings = self.settings
    utable = settings.table_user
    authenticated = self.id_group('Authenticated')
    add_membership = self.add_membership
    add_membership(authenticated, user_id)
    organisation_id = user.organisation_id
    entity_roles = deployment_settings.get_auth_registration_roles()
    if entity_roles:
        gtable = settings.table_group
        get_pe_id = s3db.pr_get_pe_id
        for entity in entity_roles.keys():
            roles = entity_roles[entity]
            if (entity in ('organisation_id', 'org_group_id', 'site_id')):
                tablename = ('org_%s' % entity.split('_')[0])
                entity = get_pe_id(tablename, user[entity])
                if (not entity):
                    continue
            rows = db(gtable.uuid.belongs(roles)).select(gtable.id)
            for role in rows:
                add_membership(role.id, user_id, entity=entity)
    if (organisation_id and deployment_settings.get_auth_org_admin_to_first()):
        entity = s3db.pr_get_pe_id('org_organisation', organisation_id)
        gtable = settings.table_group
        ORG_ADMIN = db((gtable.uuid == 'ORG_ADMIN')).select(gtable.id, limitby=(0, 1)).first().id
        mtable = settings.table_membership
        query = ((mtable.group_id == ORG_ADMIN) & (mtable.pe_id == entity))
        exists = db(query).select(mtable.id, limitby=(0, 1))
        if (not exists):
            add_membership(ORG_ADMIN, user_id, entity=entity)
    if deployment_settings.has_module('delphi'):
        table = s3db.delphi_group
        group = db((table.uuid == 'DEFAULT')).select(table.id, limitby=(0, 1)).first()
        if group:
            table = s3db.delphi_membership
            table.insert(group_id=group.id, user_id=user_id, status=3)
    self.s3_link_user(user)
    if (current.response.s3.bulk is True):
        user_email = db((utable.id == user_id)).select(utable.email).first().email
        self.auth_user_onaccept(user_email, user_id)
        return
    db((utable.id == user_id)).update(registration_key='')
    if (organisation_id and ('org_organisation' in deployment_settings.get_auth_record_approval_required_for())):
        org_resource = s3db.resource('org_organisation', organisation_id, approved=False, unapproved=True)
        approved = org_resource.approve()
        if (not approved):
            org_resource.approve(approved_by=0)
    user_email = db((utable.id == user_id)).select(utable.email).first().email
    self.auth_user_onaccept(user_email, user_id)
    self.s3_send_welcome_email(user, password)
