user.py

"""User API view functions"""
from datetime import datetime, timedelta

from dateutil.relativedelta import relativedelta
from flask import (
    Blueprint,
    abort,
    current_app,
    jsonify,
    make_response,
    redirect,
    request,
    session,
    url_for,
)
from flask_babel import force_locale
from flask_user import roles_required
from sqlalchemy import and_, func
from sqlalchemy.orm.exc import NoResultFound
from werkzeug.exceptions import Unauthorized

from ..audit import auditable_event
from ..cache import cache
from ..database import db
from ..date_tools import FHIR_datetime
from ..extensions import oauth, user_manager
from ..models.app_text import MailResource, UserInviteEmail_ATMA, app_text
from ..models.audit import Audit
from ..models.auth import Token
from ..models.client import Client, client_event_dispatch
from ..models.communication import load_template_args
from ..models.group import Group
from ..models.intervention import Intervention
from ..models.message import EmailMessage
from ..models.organization import Organization
from ..models.questionnaire_bank import trigger_date
from ..models.qb_timeline import QB_StatusCacheKey, invalidate_users_QBT
from ..models.questionnaire_response import QuestionnaireResponse
from ..models.relationship import Relationship
from ..models.research_study import EMPRO_RS_ID
from ..models.role import ROLE, Role
from ..models.table_preference import TablePreference
from ..models.url_token import url_token
from ..models.user import (
    INVITE_PREFIX,
    User,
    UserRelationship,
    current_user,
    get_user,
    permanently_delete_user,
    validate_email,
)
from ..models.user_consent import UserConsent, consent_withdrawal_dates
from ..models.user_document import UserDocument
from ..type_tools import check_int
from .auth import logout
from .crossdomain import crossdomain

user_api = Blueprint('user_api', __name__, url_prefix='/api')


@user_api.route('/me')
@crossdomain()
@oauth.require_oauth()
def me():
    """Access basics for current user

    returns authenticated user's id, username and email in JSON
    ---
    tags:
      - User
    operationId: me
    produces:
      - application/json
    responses:
      200:
        description: successful operation
        schema:
          id: user
          required:
            - id
            - username
            - email
          properties:
            id:
              type: integer
              format: int64
              description: TrueNTH ID for user
            username:
              type: string
              description: User's username - which will always match the email
            email:
              type: string
              description: User's preferred email address, same as username
      401:
        description: if missing valid OAuth token
    security:
      - ServiceToken: []

    """
    user = current_user()

    # only return user id, if auth came from a URL such as embedded within an email
    encounter = user.current_encounter(generate_failsafe_if_missing=False)
    if encounter and encounter.auth_method == 'url_authenticated':
        return jsonify(id=user.id)

    return jsonify(
        id=user.id, username=user.username, email=user.email)


@user_api.route('/account', methods=('POST',))
@crossdomain()
@oauth.require_oauth()  # for service token access, oauth must come first
@roles_required(
    [ROLE.APPLICATION_DEVELOPER.value, ROLE.ADMIN.value, ROLE.SERVICE.value,
     ROLE.STAFF.value, ROLE.STAFF_ADMIN.value])
def account():
    """Create a user account

    Due to complicated rules with respect to staff users being able to edit
    the account generated by this endpoint, all data necessary to secure edit
    rights on the new account must be included in the initial call.  This will
    typically include `organizations`, `consents` and `roles`.

    On success, a simple JSON object is returned defining the new user's id.

    If the user creating the account doesn't provide adequate details to secure
    edit rights, a 400 will be generated.

    Beyond account creation, additional endpoints may be used to adjust the
    account details including:

    1. PUT /api/demographics/{id}, with known details for the new user
    2. PUT /api/user/{id}/roles to grant additional user role(s)
    3. PUT /api/intervention/{name} grants the user access to the intervention.
    ---
    tags:
      - User
    operationId: createAccount
    parameters:
      - in: body
        name: body
        schema:
          id: account_args
          properties:
            organizations:
              type: array
              items:
                type: object
                required:
                  - organization_id
                properties:
                  organization_id:
                      type: string
                      description:
                        Optional organization identifier defining the
                        organization the new user will belong to.
            consents:
              type: array
              items:
                type: object
                required:
                  - organization_id
                  - agreement_url
                properties:
                  organization_id:
                    type: integer
                    format: int64
                    description:
                      Organization identifier defining with whom the consent
                      agreement applies
                  acceptance_date:
                    type: string
                    format: date-time
                    description:
                      optional UTC date-time for when the agreement expires,
                      defaults to utcnow
                  expires:
                    type: string
                    format: date-time
                    description:
                      optional UTC date-time for when the agreement expires,
                      defaults to utcnow plus 5 years
                  agreement_url:
                    type: string
                    description: URL pointing to agreement text
                  staff_editable:
                    type: boolean
                    description:
                      set True if consenting to enable account editing by staff
                  include_in_reports:
                    type: boolean
                    description:
                      set True if consenting to share data in reports
                  send_reminders:
                    type: boolean
                    description:
                      set True if consenting to receive reminders when
                      assessments are due
            roles:
              type: array
              items:
                type: object
                required:
                  - name
                properties:
                  name:
                    type: string
                    description:
                      Role name, always a lower case string
                      with no white space.
                  description:
                    type: string
                    description: Plain text describing the role.
    produces:
      - application/json
    responses:
      200:
        description:
            "Returns {user_id: id}"
      401:
        description:
          if missing valid OAuth token or if the authorized user lacks
          permission to view requested user_id
    security:
      - ServiceToken: []
      - OAuth2AuthzFlow: []
    """
    acting_user = current_user()
    if acting_user.has_role(ROLE.ADMIN.value, ROLE.SERVICE.value):
        adequate_perms = True
    else:
        adequate_perms = False
        error = ('without organizations, consents and roles, subsequent '
                 'calls on this user object will fail with a 401')
        if not request.json:
            abort(400, error)
        if not all(required in request.json for required in (
                'organizations', 'consents', 'roles')):
            abort(400, error)
    user = User()
    db.session.add(user)

    if request.json and 'organizations' in request.json:
        try:
            org_list = [Organization.query.filter_by(
                id=org['organization_id']).one()
                for org in request.json['organizations']]
            user.update_orgs(org_list, acting_user=acting_user,
                             excuse_top_check=True)
            if org_list:
                user.timezone = org_list[0].timezone
        except NoResultFound:
            abort(
                400,
                "Organization in {} not found, check "
                "/api/organization for existence.".format(
                    request.json['organizations']))

    if request.json and 'consents' in request.json:
        try:
            consent_list = []
            for consent in request.json['consents']:
                if 'user_id' not in consent:
                    consent['user_id'] = user.id
                elif consent['user_id'] != user.id:
                    raise ValueError("consent user_id differs from path")
                if 'research_study_id' not in consent:
                    consent['research_study_id'] = 0
                consent_list.append(UserConsent.from_json(consent))
            user.update_consents(consent_list, acting_user=acting_user)
        except ValueError as e:
            abort(400, "ill formed consents:".format(e))

    if request.json and 'roles' in request.json:
        try:
            role_list = [Role.query.filter_by(name=role.get('name')).one()
                         for role in request.json.get('roles')]
            user.update_roles(role_list, acting_user=current_user())
        except NoResultFound:
            abort(400, "one or more roles ill defined "
                       "{}".format(request.json.get('roles')))

    db.session.commit()
    auditable_event(
        "new account generated for {} <{}>".format(user, user._email),
        user_id=current_user().id, subject_id=user.id,
        context='account')
    if not adequate_perms:
        # Make sure acting user has permission to edit the newly
        # created user, or generate a 400 and purge the user.
        try:
            acting_user.check_role('edit', other_id=user.id)
        except Unauthorized:
            permanently_delete_user(
                username=user.username, user_id=user.id,
                acting_user=acting_user)
            abort(400, "Inaccessible user created - review consent and roles")

    # Force a renewal of the visit / qb_status cache so the new user has
    # accurate info.  Pad by a second to get around microsecond floor problems
    now = datetime.utcnow() + relativedelta(seconds=1)
    QB_StatusCacheKey().update(now)
    return jsonify(user_id=user.id)


@user_api.route('/user/<int:user_id>', methods=('DELETE',))
@crossdomain()
@roles_required([ROLE.ADMIN.value, ROLE.STAFF_ADMIN.value])
@oauth.require_oauth()
def delete_user(user_id):
    """Delete the named user from the system

    Mark the given user as deleted.  The user isn't actually deleted,
    but marked as such to maintain the audit trail.  After deletion,
    all other operations on said user are prohibited.

    ---
    tags:
      - User
    operationId: delete_user
    parameters:
      - name: user_id
        in: path
        description: TrueNTH user ID to delete
        required: true
        type: integer
        format: int64
    produces:
      - application/json
    responses:
      200:
        description: successful operation
        schema:
          id: response_deleted
          required:
            - message
          properties:
            message:
              type: string
              description: Result, typically "deleted"
      400:
        description:
          Invalid requests, such as deleting a user owning client applications.
      401:
        description:
          if missing valid OAuth token or if the authorized user lacks
          permission to edit requested user_id
      404:
        description: if the user isn't found
    security:
      - ServiceToken: []
      - OAuth2AuthzFlow: []

    """
    user = get_user(user_id, 'edit')
    try:
        user.delete_user(acting_user=current_user())
    except ValueError as v:
        return jsonify(message=str(v))
    return jsonify(message="deleted")


@user_api.route('/user/<int:user_id>/reactivate', methods=('POST',))
@crossdomain()
@roles_required([ROLE.ADMIN.value, ROLE.STAFF_ADMIN.value])
@oauth.require_oauth()
def reactivate_user(user_id):
    """Reactivate a previously deleted user

    Reactivate a previously deleted user - brings the account back to
    valid status.

    ---
    tags:
      - User
    operationId: reactivate_user
    parameters:
      - name: user_id
        in: path
        description: TrueNTH user ID to reactivate
        required: true
        type: integer
        format: int64
    produces:
      - application/json
    responses:
      200:
        description: successful operation
        schema:
          id: response_reactivated
          required:
            - message
          properties:
            message:
              type: string
              description: Result, typically "reactivated"
      400:
        description:
          Invalid requests, such as reactivating a user that wasn't in a
          deleted state.
      401:
        description:
          if missing valid OAuth token or if the authorized user lacks
          permission to edit requested user_id
      404:
        description: if the user isn't found
    security:
      - ServiceToken: []
      - OAuth2AuthzFlow: []

    """
    user = get_user(user_id, permission='edit', include_deleted=True)
    try:
        user.reactivate_user(acting_user=current_user())
    except ValueError as v:
        response = jsonify(message="{}".format(v))
        response.status_code = 400
        return response
    return jsonify(message="reactivated")


@user_api.route('/user/<int:user_id>/access_url')
@crossdomain()
@oauth.require_oauth()  # for service token access, oauth must come first
@roles_required(
    [ROLE.APPLICATION_DEVELOPER.value, ROLE.ADMIN.value, ROLE.SERVICE.value,
     ROLE.STAFF.value, ROLE.STAFF_ADMIN.value])
def access_url(user_id):
    """Returns simple JSON with one-time, unique access URL for given user

    Generates a single use access token for the given user as a
    one click, weak authentication access to the system.

    NB - user must be a member of the WRITE_ONLY role or ACCESS_ON_VERIFY,
    and not a member of privileged roles, as a safeguard from abuse.

    ---
    tags:
      - User
    operationId: access_url
    parameters:
      - name: user_id
        in: path
        description: TrueNTH user ID to grant access via unique URL
        required: true
        type: integer
        format: int64
    produces:
      - application/json
    responses:
      200:
        description: successful operation
        schema:
          id: response_unique_URL
          required:
            - access_url
          properties:
            access_url:
              type: string
              description: The unique URL providing one time access
      400:
        description:
          if the user has too many privileges for weak authentication
      401:
        description:
          if missing valid OAuth token or if the authorized user lacks
          permission to view requested user_id
      404:
        description: if the user isn't found
    security:
      - ServiceToken: []
      - OAuth2AuthzFlow: []

    """
    user = get_user(user_id, permission='edit')
    not_allowed = {
        ROLE.ADMIN.value,
        ROLE.APPLICATION_DEVELOPER.value,
        ROLE.SERVICE.value}
    has = {role.name for role in user.roles}
    if not has.isdisjoint(not_allowed):
        abort(400, "Access URL not provided for privileged accounts")

    if {ROLE.ACCESS_ON_VERIFY.value, ROLE.WRITE_ONLY.value}.isdisjoint(has):
        # KEEP this restriction.  Weak authentication (which the
        # returned URL provides) should only be available for these roles
        abort(
            400,
            "Access URL restricted to ACCESS_ON_VERIFY or WRITE_ONLY roles")

    # generate URL token
    token = url_token(user_id)

    url = url_for(
        'portal.access_via_token', token=token, _external=True)
    auditable_event("generated URL token {}".format(token),
                    user_id=current_user().id, subject_id=user.id,
                    context='authentication')
    return jsonify(access_url=url)


@user_api.route('/user/<int:user_id>/consent')
@crossdomain()
@oauth.require_oauth()
def user_consents(user_id):
    """Returns simple JSON listing user's valid consent agreements

    Returns the list of consent agreements between the requested user
    and the respective organizations.  Consents are ordered by
    ``acceptance_date``, most recent first.

    NB does include deleted and expired consents.  Deleted consents will
    include audit details regarding the deletion.  The expires timestamp in UTC
    is also returned for all consents.

    Consents include a number of options, each of which will only be in the
    returned JSON if defined.

    ---
    tags:
      - User
      - Consent
      - Organization
    operationId: user_consents
    parameters:
      - name: user_id
        in: path
        description: TrueNTH user ID
        required: true
        type: integer
        format: int64
    produces:
      - application/json
    responses:
      200:
        description:
          Returns the list of consent agreements for the requested user.
        schema:
          id: consents
          properties:
            consent_agreements:
              type: array
              items:
                type: object
                required:
                  - user_id
                  - organization_id
                  - acceptance_date
                  - recorded
                  - expires
                  - agreement_url
                  - research_study_id
                properties:
                  user_id:
                    type: string
                    description:
                      User identifier defining with whom the consent agreement
                      applies
                  organization_id:
                    type: string
                    description:
                      Organization identifier defining with whom the consent
                      agreement applies
                  acceptance_date:
                    type: string
                    format: date-time
                    description:
                      Original UTC date-time from the moment the agreement was
                      signed or put in place by some other workflow
                  recorded:
                    $ref: "#/definitions/audits"
                  expires:
                    type: string
                    format: date-time
                    description:
                      UTC date-time for when the agreement expires, typically 5
                      years from the original signing date
                  agreement_url:
                    type: string
                    description: URL pointing to agreement text
                  staff_editable:
                    type: boolean
                    description:
                      True if consenting to enable account editing by staff
                  include_in_reports:
                    type: boolean
                    description:
                      True if consenting to share data in reports
                  send_reminders:
                    type: boolean
                    description:
                      True if consenting to receive reminders when
                      assessments are due
                  research_study_id:
                    type: string
                    description:
                      Research Study identifier to which the consent
                      agreement applies
      401:
        description:
          if missing valid OAuth token or if the authorized user lacks
          permission to view requested user_id
    security:
      - ServiceToken: []

    """
    user = get_user(user_id, 'view')
    return jsonify(consent_agreements=[c.as_json() for c in
                                       user.all_consents])


@user_api.route('/user/<int:user_id>/consent', methods=('POST',))
@crossdomain()
@oauth.require_oauth()
def set_user_consents(user_id):
    """Add a consent agreement for the user with named organization

    Used to add a consent agreements between a user and an organization.
    Assumed to have just been agreed to.  Include 'expires' if
    necessary, defaults to now and five years from now (both in UTC).

    NB only one valid consent should be in place between a user and an
    organization per research study.  Therefore, if this POST would create
    a second consent on the given (user, organization, research study), the
    existing consent will be marked deleted.

    Research Studies were added since the initial implementation of this API.
    Therefore, exclusion of a ``research_study_id`` will implicitly use a value
    of 0 (zero) as the research_study_id.

    ---
    tags:
      - User
      - Consent
      - Organization
    operationId: post_user_consent
    produces:
      - application/json
    parameters:
      - name: user_id
        in: path
        description: TrueNTH user ID
        required: true
        type: integer
        format: int64
      - in: body
        name: body
        schema:
          id: post_consent_agreement
          required:
            - organization_id
            - agreement_url
          properties:
            organization_id:
              type: integer
              format: int64
              description:
                Organization identifier defining with whom the consent
                agreement applies
            acceptance_date:
              type: string
              format: date-time
              description:
                optional UTC date-time for when the agreement is initially
                valid, defaults to utcnow.  Dates in the future are not valid
            expires:
              type: string
              format: date-time
              description:
                optional UTC date-time for when the agreement expires,
                defaults to utcnow plus 5 years
            agreement_url:
              type: string
              description: URL pointing to agreement text
            staff_editable:
              type: boolean
              description:
                set True if consenting to enable account editing by staff
            include_in_reports:
              type: boolean
              description:
                set True if consenting to share data in reports
            send_reminders:
              type: boolean
              description:
                set True if consenting to receive reminders when
                assessments are due
            research_study_id:
              type: integer
              format: int64
              description:
                Research Study identifier defining which research study the
                consent agreement applies to.  Include to override the default
                value of 0 (zero).
    responses:
      200:
        description: successful operation
        schema:
          id: response_ok
          required:
            - message
          properties:
            message:
              type: string
              description: Result, typically "ok"
      400:
        description: if the request includes invalid data
      401:
        description:
          if missing valid OAuth token or if the authorized user lacks
          permission to edit requested user_id
      404:
        description: if user_id doesn't exist
    security:
      - ServiceToken: []

    """
    current_app.logger.debug('post user consent called w/: {}'.format(
        request.json))
    user = get_user(user_id, 'edit')
    if not request.json:
        abort(400, "Requires JSON with submission including "
                   "HEADER 'Content-Type: application/json'")
    if ('acceptance_date' in request.json
            and FHIR_datetime.parse(request.json['acceptance_date'])
            > (relativedelta(minutes=90) + datetime.utcnow())):
        abort(400, "Future `acceptance_date` not permitted")

    request.json['user_id'] = user_id
    try:
        consent = UserConsent.from_json(request.json)
        if 'research_study_id' not in request.json:
            consent.research_study_id = 0
        consent_list = [consent, ]
        user.update_consents(
            consent_list=consent_list, acting_user=current_user())

        # Moving consent dates potentially invalidates
        # (questionnaire_response: visit_name) associations.
        cache.delete_memoized(trigger_date)
        QuestionnaireResponse.purge_qb_relationship(
            subject_id=user.id,
            research_study_id=consent.research_study_id,
            acting_user_id=current_user().id)

        # The updated consent may have altered the cached assessment
        # status - invalidate this user's data at this time.
        invalidate_users_QBT(
            user_id=user.id, research_study_id=consent.research_study_id)
    except ValueError as e:
        abort(400, str(e))

    return jsonify(message="ok")


@user_api.route('/user/<int:user_id>/consent/withdraw',
                methods=('POST', 'PUT'))
@crossdomain()
@oauth.require_oauth()
def withdraw_user_consent(user_id):
    """Withdraw existing consent agreement for the user with named organization

    Used to withdraw a consent agreements between a user and an organization.
    If a consent exists for the given user/org, the consent will be marked
    deleted, and a matching consent (with new status/option values) will be
    created in its place.  If the user was already withdrawn, a new row will
    be created also with status `suspended`, the prior will retain its
    `suspended` status and marked deleted.

    NB Invalid to request a withdrawal date prior to current consent.

    ---
    tags:
      - User
      - Consent
      - Organization
    operationId: withdraw_user_consent
    produces:
      - application/json
    parameters:
      - name: user_id
        in: path
        description: TrueNTH user ID
        required: true
        type: integer
        format: int64
      - in: body
        name: body
        schema:
          id: withdraw_consent_agreement
          required:
            - organization_id
          properties:
            acceptance_date:
              type: string
              format: date-time
              description:
                optional UTC date-time for when the withdrawal occurred if
                other than the defaults of utcnow.
                Dates in the future are not valid
            organization_id:
              type: integer
              format: int64
              description:
                Organization identifier defining with whom the consent
                agreement applies
            research_study_id:
              type: integer
              format: int64
              description:
                Research Study identifier defining which research study the
                consent agreement applies to.  Include to override the default
                value of 0 (zero).
    responses:
      200:
        description: successful operation
        schema:
          id: response_ok
          required:
            - message
          properties:
            message:
              type: string
              description: Result, typically "ok"
      400:
        description: if the request includes invalid data
      401:
        description:
          if missing valid OAuth token or if the authorized user lacks
          permission to edit requested user_id
      404:
        description:
          if user_id doesn't exist, or it no consent found
          for given user org combination
    security:
      - ServiceToken: []

    """
    current_app.logger.debug('withdraw user consent called w/: '
                             '{}'.format(request.json))
    user = get_user(user_id, permission='edit')
    if not request.json:
        abort(400, "Requires JSON with submission including "
                   "HEADER 'Content-Type: application/json'")

    org_id = request.json.get('organization_id')
    if not org_id:
        abort(400, "missing required organization ID")
    research_study_id = int(request.json.get('research_study_id', 0))
    acceptance_date = None
    if 'acceptance_date' in request.json:
        acceptance_date = FHIR_datetime.parse(request.json['acceptance_date'])
        if acceptance_date > datetime.utcnow():
            abort(400, "Future `acceptance_date` not permitted")

    current_app.logger.debug('withdraw user consent called for user {} '
                             'and org {}'.format(user.id, org_id))
    return withdraw_consent(
        user=user, org_id=org_id, acceptance_date=acceptance_date,
        acting_user=current_user(), research_study_id=research_study_id)


def withdraw_consent(
        user, org_id, acceptance_date, acting_user, research_study_id):
    """execute consent withdrawal - view and test friendly function"""
    uc = UserConsent.query.filter_by(
        user_id=user.id, organization_id=org_id, status='consented',
        research_study_id=research_study_id).first()
    try:
        if not uc:
            # Possible replacement of existing withdrawal
            wc = UserConsent.query.filter_by(
                user_id=user.id, organization_id=org_id, status='suspended',
                research_study_id=research_study_id).first()

            if not wc:
                abort(
                    404,
                    "no UserConsent found for user ID {}, org ID {}, research study "
                    "ID {}".format(user.id, org_id, research_study_id))

            # replace with requested time, provided it's in a valid window
            prior_consent, prior_withdrawal = consent_withdrawal_dates(user, research_study_id)
            if prior_withdrawal and acceptance_date == prior_withdrawal:
                # valid nop, leave.
                return jsonify(wc.as_json())
            if prior_consent and acceptance_date < prior_consent:
                raise ValueError(
                    f"Can't suspend with acceptance date {acceptance_date} "
                    f"prior to last valid consent {prior_consent}")
            if acceptance_date > datetime.utcnow() + timedelta(days=1):
                raise ValueError(
                    "Can't suspend with acceptance date in the future")
            prior_withdrawal_date = wc.acceptance_date
            wc.acceptance_date = acceptance_date
            db.session.commit()
            # Audit the change
            auditable_event(
                f"Consent agreement {wc.id} updated from {prior_withdrawal_date} "
                f"to {acceptance_date}",
                user_id=current_user().id,
                subject_id=user.id,
                context="consent"
            )

            # As withdrawal time just changed, force recalculation
            invalidate_users_QBT(
                user_id=user.id, research_study_id=research_study_id)
            return jsonify(wc.as_json())

        if not acceptance_date:
            acceptance_date = datetime.utcnow()
        if acceptance_date <= uc.acceptance_date:
            raise ValueError(
                "Can't suspend with acceptance date prior to existing consent")
        suspended = UserConsent(
            user_id=user.id, organization_id=org_id, status='suspended',
            acceptance_date=acceptance_date, agreement_url=uc.agreement_url,
            research_study_id=research_study_id)
        suspended.send_reminders = False
        suspended.include_in_reports = True
        suspended.staff_editable = (not current_app.config.get('GIL'))
        user.update_consents(
            consent_list=[suspended], acting_user=acting_user)

        # NB - we do NOT call QuestionnaireResponse.purge_qb_relationship()
        # in this case, as the user is withdrawing, not altering initial
        # consent dates.  Doing so does alter the QB_timeline from point of
        # withdrawal forward, so force QB_timeline renewal
        invalidate_users_QBT(
            user_id=user.id, research_study_id=research_study_id)

    except ValueError as e:
        abort(400, str(e))

    return jsonify(suspended.as_json())


@user_api.route('/user/<int:user_id>/consent', methods=('DELETE',))
@crossdomain()
@oauth.require_oauth()
def delete_user_consents(user_id):
    """Delete a consent agreement between the user and the named organization

    Used to delete consent agreements between a user and an organization.

    ---
    tags:
      - User
      - Consent
      - Organization
    operationId: delete_user_consent
    produces:
      - application/json
    parameters:
      - name: user_id
        in: path
        description: TrueNTH user ID
        required: true
        type: integer
        format: int64
      - in: body
        name: body
        schema:
          id: consent_agreement
          required:
            - organization_id
          properties:
            organization_id:
              type: integer
              format: int64
              description:
                Organization identifier defining with whom the consent
                agreement applies
            research_study_id:
              type: integer
              format: int64
              description:
                Research Study identifier defining which research study the
                consent agreement applies to.  Include to override the default
                value of 0 (zero).
    responses:
      200:
        description: successful operation
        schema:
          id: response_ok
          required:
            - message
          properties:
            message:
              type: string
              description: Result, typically "ok"
      400:
        description: if the request includes invalid data
      401:
        description:
          if missing valid OAuth token or if the authorized user lacks
          permission to edit requested user_id
      404:
        description: if user_id doesn't exist
    security:
      - ServiceToken: []

    """
    current_app.logger.debug('delete user consent called w/: {}'.format(
        request.json))
    user = get_user(user_id, 'edit')
    remove_uc = None
    research_study_id = request.json.get('research_study_id', 0)
    try:
        id_to_delete = int(request.json['organization_id'])
    except ValueError:
        abort(400, "requires integer value for `organization_id`")
    for uc in user.valid_consents:
        if (
                uc.organization.id == id_to_delete and
                uc.research_study_id == research_study_id):
            remove_uc = uc
            break
    if not remove_uc:
        abort(404, "matching user consent not found")

    audit_comment = 'Deleted consent agreement'
    if research_study_id == EMPRO_RS_ID:
        audit_comment = 'Deleted EMPRO consent agreement'
    remove_uc.deleted = Audit(
        user_id=current_user().id, subject_id=user_id,
        comment=audit_comment, context='consent')
    remove_uc.status = 'deleted'
    # The deleted consent may have altered the cached assessment
    # status, even the qb assignments - force re-eval by invalidating now
    cache.delete_memoized(trigger_date)
    QuestionnaireResponse.purge_qb_relationship(
        subject_id=user_id,
        research_study_id=research_study_id,
        acting_user_id=current_user().id)

    invalidate_users_QBT(user_id=user_id, research_study_id=research_study_id)
    db.session.commit()

    return jsonify(message="ok")


@user_api.route('/user/<int:user_id>/encounter', methods=('GET',))
@crossdomain()
@oauth.require_oauth()
def current_encounter(user_id):
    """Return current/latest encounter for logged in user

    NB: only expected use at this time is current user. raises
    RuntimeError if called on another, to avoid creating false,
    failsafe encounters.

    ---
    tags:
      - User
      - Encounter
    operationId: current_encounter
    parameters:
      - name: user_id
        in: path
        description: TrueNTH user ID
        required: true
        type: integer
        format: int64
    produces:
      - application/json
    responses:
      200:
        description:
          Returns the current encounter for the requested user.  NB only
          the ``current_user`` is supported at this time.
        schema:
          id: encounter
          required:
            - id
            - status
            - patient
            - auth_method
          properties:
            id:
              type: integer
              format: int64
              description:
                Current encounter identifier
            status:
              description:
                Plain text describing the encounter status,
                expect ``in-progress`` for "current" encounter.
              type: string
              enum:
                - planned
                - arrived
                - in-progress
                - onleave
                - finished
                - cancelled
            patient:
              description: Reference to patient owning the encounter
              $ref: "#/definitions/Reference"
            auth_method:
              description: Form of encounter authentication
              type: string
              enum:
                - password_authenticated
                - url_authenticated
                - staff_authenticated
                - staff_handed_to_patient
                - service_token_authenticated
                - url_authenticated_and_verified
                - failsafe
      400:
        description:
          Only supported for current user - any other will result in 400
      401:
        description:
          if missing valid OAuth token or if the authorized user lacks
          permission to view requested user_id

    """
    user = current_user()
    if user_id != user.id:
        abort(400, "Only current_user's encounter accessible")
    return jsonify(user.current_encounter().as_fhir())


@user_api.route('/user/<int:user_id>/groups')
@crossdomain()
@oauth.require_oauth()
def user_groups(user_id):
    """Returns simple JSON defining user's groups

    Returns the list of groups the requested user belongs to.
    ---
    tags:
      - User
      - Group
    operationId: user_groups
    parameters:
      - name: user_id
        in: path
        description: TrueNTH user ID
        required: true
        type: integer
        format: int64
    produces:
      - application/json
    responses:
      200:
        description:
          Returns the list of groups the requested user belongs to.
        schema:
          id: groups
          required:
            - name
            - description
          properties:
            name:
              type: string
              description:
                Group name, always a lower case string with no white space.
            description:
              type: string
              description: Plain text describing the group.
      401:
        description:
          if missing valid OAuth token or if the authorized user lacks
          permission to view requested user_id
    security:
      - ServiceToken: []

    """
    user = get_user(user_id, 'view')
    return jsonify(groups=[g.as_json() for g in user.groups])


@user_api.route('/user/<int:user_id>/groups', methods=('PUT',))
@crossdomain()
@oauth.require_oauth()
def set_user_groups(user_id):
    """Set groups for user, returns simple JSON defining user groups

    Used to set group assignments for a user.  Include all groups
    the user should be a member of.  If user previously belonged to
    groups not included, the missing groups will be deleted from the user.

    Only the 'name' field of the groups is referenced.  Must match
    current groups in the system.

    Returns a list of all groups user belongs to after change.
    ---
    tags:
      - User
      - Group
    operationId: set_user_groups
    produces:
      - application/json
    parameters:
      - name: user_id
        in: path
        description: TrueNTH user ID
        required: true
        type: integer
        format: int64
      - in: body
        name: body
        schema:
          id: nested_groups
          properties:
            groups:
              type: array
              items:
                type: object
                required:
                  - name
                properties:
                  name:
                    type: string
                    description:
                      The string defining the name of each group
                      the user should belong to.  Must exist as an
                      available group in the system.
    responses:
      200:
        description:
          Returns a list of all groups user belongs to after change.
        schema:
          id: user_groups
          required:
            - name
            - description
          properties:
            name:
              type: string
              description:
                Group name, always a lower case string with no white space.
            description:
              type: string
              description: Plain text describing the group.
      400:
        description: if the request includes an unknown group.
      401:
        description:
          if missing valid OAuth token or if the authorized user lacks
          permission to edit requested user_id
      404:
        description: if user_id doesn't exist
    security:
      - ServiceToken: []

    """
    user = get_user(user_id, 'edit')
    if not request.json or 'groups' not in request.json:
        abort(400, "Requires 'groups' list")

    remove_if_not_requested = {group.id: group for group in user.groups}
    requested_groups = [r['name'] for r in request.json['groups']]
    matching_groups = Group.query.filter(Group.name.in_(
                                         requested_groups)).all()
    if len(matching_groups) != len(requested_groups):
        abort(400, "One or more groups requested not available")
    # Add any requested not already set on user
    for requested_group in matching_groups:
        if requested_group not in user.groups:
            user.groups.append(requested_group)
            auditable_event("added {} to user {}".format(
                requested_group, user.id), user_id=current_user().id,
                subject_id=user.id, context='group')
        else:
            remove_if_not_requested.pop(requested_group.id)

    for stale_group in remove_if_not_requested.values():
        user.groups.remove(stale_group)
        auditable_event("deleted {} from user {}".format(
            stale_group, user.id), user_id=current_user().id,
            subject_id=user.id, context='group')

    if user not in db.session:
        db.session.add(user)
    db.session.commit()

    # Return user's updated group list
    return jsonify(groups=[g.as_json() for g in user.groups])


@user_api.route('/relationships')
@crossdomain()
@oauth.require_oauth()
def system_relationships():
    """Returns simple JSON defining all system relationships

    Returns a list of all known relationships.
    ---
    tags:
      - User
      - Relationship
    operationId: system_relationships
    produces:
      - application/json
    responses:
      200:
        description: Returns a list of all known relationships.
        schema:
          id: relationships
          required:
            - name
            - description
          properties:
            name:
              type: string
              description:
                relationship name, a lower case string with no white space.
            description:
              type: string
              description: Plain text describing the relationship.
      401:
        description:
          if missing valid OAuth token or if the authorized user lacks
          permission to view system relationships
    security:
      - ServiceToken: []

    """
    results = [{'name': r.name, 'description': r.description}
               for r in Relationship.query.all()]
    return jsonify(relationships=results)


@user_api.route('/user/<int:user_id>/relationships')
@crossdomain()
@oauth.require_oauth()
def relationships(user_id):
    """Returns simple JSON defining user relationships

    Relationships may exist between user accounts.  A user may have
    any number of relationships.  The relationship
    is a one-way definition defined to extend permissions to appropriate
    users, such as intimate partners or service account sponsors.

    The JSON returned includes all relationships for the given user both
    as subject and as part of the relationship predicate.
    ---
    tags:
      - User
      - Relationship
    operationId: getrelationships
    parameters:
      - name: user_id
        in: path
        description: TrueNTH user ID
        required: true
        type: integer
        format: int64
    produces:
      - application/json
    responses:
      200:
        description:
          Returns the list of relationships the requested user belongs to.
        schema:
          id: user_relationships
          required:
            - user
            - has the relationship
            - with
          properties:
            user:
              type: integer
              format: int64
              description: id of user acting as subject
            has the relationship:
              type: string
              description:
                The string defining the name of each relationship the user
                should belong to.  Must exist as an available relationship
                in the system.
            with:
              type: integer
              format: int64
              description: id of user acting as part of predicate
      401:
        description:
          if missing valid OAuth token or if the authorized user lacks
          permission to view requested user_id
    security:
      - ServiceToken: []

    """
    user = get_user(user_id, 'view')
    results = []
    for r in user.relationships:
        results.append({'user': r.user_id,
                        'has the relationship': r.relationship.name,
                        'with': r.other_user_id})
    # add in any relationships where the user is on the predicate side
    predicates = UserRelationship.query.filter_by(other_user_id=user.id)
    for r in predicates:
        results.append({'user': r.user_id,
                        'has the relationship': r.relationship.name,
                        'with': r.other_user_id})
    return jsonify(relationships=results)


@user_api.route('/user/register-now')
@crossdomain()
@oauth.require_oauth()
def register_now():
    """Target for triggering registration of account

    Some flows generate accounts that are not yet ``registered``,
    such as when given the ``access_on_verify`` role.

    When it's desirable to promote the user to a registered account
    (eg when they've completed a flow like MUSIC P3P, where stakeholders
    wanted to avoid the potential disruption of registration), redirect
    to this endpoint to trigger promotion to a registered account.

    Session variables capture the state, and redirect the user
    through the common registration mechanism.

    ---
    tags:
      - User
    operationId: registernow
    produces:
      - application/json
    responses:
      302:
        description:
          Redirects user-agent to user.registration after validation
          and state storage.
      401:
        description:
          if missing valid OAuth token or if the authorized user lacks
          permission to view requested user_id
      400:
        description:
          if user is already registered or not eligible for some reason
    security:
      - ServiceToken: []
      - OAuth2AuthzFlow: []

    """
    user = current_user()
    if user.is_registered():
        abort(400, "User already registered")

    ready, reason = user.email_ready()
    if not ready:
        abort(400, reason)

    # Need to logout current user, or the opportunity to register
    # isn't available.  This also clears the session, so do this
    # step first
    logout(
        prevent_redirect=True,
        reason='give un-registered chance to register new account')

    user.mask_email()
    db.session.commit()
    session['invited_verified_user_id'] = user.id

    return redirect(url_for('user.register', email=user.email))


@user_api.route('/user/<int:user_id>/relationships', methods=('PUT',))
@crossdomain()
@oauth.require_oauth()
def set_relationships(user_id):
    """Set relationships for user, returns JSON defining user relationships

    Used to set relationship assignments for a user, both in a subject
    and predicate role.  The provided list of relationships will be definitive,
    resulting in deletion of previously existing relationships omitted from
    the given list (again where user_id is acting as the relationship
    subject or part of predicate).

    Returns a list of all relationships user belongs to after change.
    ---
    tags:
      - User
      - Relationship
    operationId: setrelationships
    produces:
      - application/json
    parameters:
      - name: user_id
        in: path
        description: TrueNTH user ID
        required: true
        type: integer
        format: int64
      - in: body
        name: body
        schema:
          id: user_relationships
          required:
            - user
            - has the relationship
            - with
          properties:
            user:
              type: integer
              format: int64
              description: id of user acting as subject
            has the relationship:
              type: string
              description:
                The string defining the name of each relationship the user
                should belong to.  Must exist as an available relationship
                in the system.
            with:
              type: integer
              format: int64
              description: id of user acting as part of predicate
    responses:
      200:
        description:
          Returns a list of all relationships user belongs to after change.
        schema:
          id: user_relationships
          required:
            - user
            - has the relationship
            - with
          properties:
            user:
              type: integer
              format: int64
              description: id of user acting as subject
            has the relationship:
              type: string
              description:
                The string defining the name of each relationship the user
                should belong to.  Must exist as an available relationship
                in the system.
            with:
              type: integer
              format: int64
              description: id of user acting as part of predicate
      400:
        description: if the request includes an unknown relationship.
      401:
        description:
          if missing valid OAuth token or if the authorized user lacks
          permission to view requested user_id
    security:
      - ServiceToken: []

    """
    user = get_user(user_id, 'edit')
    if not request.json or 'relationships' not in request.json:
        abort(400, "Requires relationship list in JSON")
    # First confirm all the data is valid and the user has permission
    current_relationships = [r.name for r in Relationship.query]
    for r in request.json['relationships']:
        if r['has the relationship'] not in current_relationships:
            abort(404, "Unknown relationship '{}' can't be added".format(
                r['has the relationship']))
        if r['user'] == r['with']:
            abort(400, "Relationship must be between two different users")
        if user_id not in (r['user'], r['with']):
            abort(401, "Path user must be part of relationship")

    subjects = [ur for ur in user.relationships]
    predicates = [ur for ur in
                  UserRelationship.query.filter_by(other_user_id=user.id)]
    remove_if_not_requested = {ur.id: ur for ur in subjects + predicates}

    # Add any requested that don't exist, track what isn't mentioned for
    # deletion.
    audit_adds = []  # preserve till post commit
    audit_dels = []  # preserve till post commit
    for r in request.json['relationships']:
        rel_id = Relationship.query.with_entities(
            Relationship.id).filter_by(name=r['has the relationship']).first()
        kwargs = {'user_id': r['user'],
                  'relationship_id': rel_id[0],
                  'other_user_id': r['with']}
        existing = UserRelationship.query.filter_by(**kwargs).first()
        if not existing:
            user_relationship = UserRelationship(**kwargs)
            db.session.add(user_relationship)
            audit_adds.append(user_relationship)
        else:
            remove_if_not_requested.pop(existing.id)

    for ur in remove_if_not_requested.values():
        audit_dels.append(''.format(ur))
        db.session.delete(ur)

    db.session.commit()
    for ad in audit_adds:
        auditable_event("added {}".format(ad),
                        user_id=current_user().id, subject_id=user.id,
                        context='relationship')
    for ad in audit_dels:
        auditable_event("deleted {}".format(ad),
                        user_id=current_user().id, subject_id=user.id,
                        context='relationship')
    # Return user's updated relationship list
    return relationships(user.id)


@user_api.route('/user/<int:user_id>/email_ready')
@crossdomain()
@oauth.require_oauth()
def email_ready(user_id):
    """See if given user is 'email ready'

    A user is considered email ready, if the account has adequate data
    to 1.) send email (a valid email address) and 2.) attributes
    required to finish a reset password process if initiated.

    Returns JSON detailing if ready, and reason not if applicable.
    ---
    tags:
      - User
    operationId: email_ready
    produces:
      - application/json
    parameters:
      - name: user_id
        in: path
        description: TrueNTH user ID
        required: true
        type: integer
        format: int64
      - name: ignore_preference
        in: query
        description: Set for checks that should ignore a users preference
          to not receive email, such as a password reset action
        required: false
        type: string
    responses:
      200:
        description:
          Returns JSON describing {ready=True} or
           {ready=False; reason=description}
        schema:
          id: ready_result
          required:
            - ready
          properties:
            ready:
              type: boolean
              description: result of email ready check
            reason:
              type: string
              description:
                detailed description defined only if the user is NOT ready
                to receive email
      401:
        description: if missing valid OAuth token
    security:
      - ServiceToken: []

    """
    user = get_user(user_id, 'view')
    ignore_preference = request.args.get('ignore_preference', False)
    ready, reason = user.email_ready(ignore_preference)
    if ready:
        return jsonify(ready=ready)
    else:
        return jsonify(ready=ready, reason=reason)


@user_api.route('/unique_email')
@crossdomain()
def unique_email():
    """Confirm a given email is unique

    For upfront validation of email addresses, determine if the given
    email is unique - i.e. unknown to the system.  If it is known, but
    belongs to the authenticated user (or user_id if provided), it will
    still be considered unique.

    Returns json unique=True or unique=False
    ---
    tags:
      - User
    operationId: unique_email
    produces:
      - application/json
    parameters:
      - name: email
        in: query
        description:
          email to validate
        required: true
        type: string
      - name: user_id
        in: query
        description:
          optional user_id, defaults to current user, necessary for admins
          editing other users.
        required: false
        type: string
    responses:
      200:
        description:
          Returns JSON describing unique=True or unique=False
        schema:
          id: unique_result
          required:
            - unique
          properties:
            unique:
              type: boolean
              description: result of unique check
      400:
        description: if email param is poorly defined
      401:
        description: if missing valid OAuth token
    security:
      - ServiceToken: []

    """
    email = request.args.get('email')
    validate_email(email)
    # find matching account by email regardless of case
    match = User.query.filter(func.lower(User.email) == email.lower())
    if match.count() > 1:
        current_app.logger.error(
             'there are >1 emails that match {}'.format(email)
        )
        return jsonify(unique=False)
    if match.count() == 1:
        # If the user is the authenticated user or provided user_id,
        # it still counts as unique

        user_id = request.args.get('user_id')
        if not user_id:
            # Note the extra oauth verify step, so this method can also
            # be used by unauth'd users (say during registration).
            valid, req = oauth.verify_request(['email'])
            if valid:
                user_id = req.user.id
            else:
                user = current_user()
                user_id = user.id if user else None
        else:
            user_id = check_int(user_id)

        result = match.one()
        if user_id != result.id:
            return jsonify(unique=False)

    # Look out for "masked" emails, as they'll create collisions down the road
    masked = INVITE_PREFIX + email
    match = User.query.filter(func.lower(User.email) == masked.lower())
    if match.count():
        return jsonify(unique=False)
    return jsonify(unique=True)


@user_api.route('/user/<int:user_id>/user_documents')
@crossdomain()
@oauth.require_oauth()
def user_documents(user_id):
    """Returns simple JSON defining user documents

    Returns the list of the user's user documents.
    ---
    tags:
      - User
      - User Document
    operationId: get_user_documents
    parameters:
      - name: user_id
        in: path
        description: TrueNTH user ID
        required: true
        type: integer
        format: int64
      - name: document_type
        in: query
        description:
          optional document_type to filter results
        required: false
        type: string
    produces:
      - application/json
    responses:
      200:
        description:
          Returns the list of user documents for the requested user.
        schema:
          id: user_documents
          properties:
            user_documents:
              type: array
              items:
                type: object
                required:
                  - id
                  - user_id
                  - document_type
                  - uploaded_at
                  - filename
                  - filetype
                properties:
                  id:
                    type: integer
                    format: int64
                    description: identifier for the user document
                  user_id:
                    type: integer
                    format: int64
                    description:
                      User identifier defining to whom the document belongs
                  document_type:
                    type: string
                    description:
                      Type of document uploaded (e.g. patient report pdf,
                      user avatar image, etc)
                  uploaded_at:
                    type: string
                    format: date-time
                    description:
                      Original UTC date-time from the moment the document was
                      uploaded to the portal
                  filename:
                    type: string
                    description: Filename of the uploaded document file
                  filetype:
                    type: string
                    description: Filetype of the uploaded document file
      401:
        description:
          if missing valid OAuth token or if the authorized user lacks
          permission to view requested user_id
    security:
      - ServiceToken: []

    """
    user = get_user(user_id, 'view')
    doctype = request.args.get('document_type')
    if doctype:
        results = user.documents.filter_by(document_type=doctype)
    else:
        results = user.documents

    return jsonify(user_documents=[d.as_json() for d in
                                   results])


@user_api.route('/user/<int:user_id>/user_documents/<int:doc_id>')
@crossdomain()
@oauth.require_oauth()
def download_user_document(user_id, doc_id):
    """Download a user document belonging to a user

    Used to download the file contents of a user document.

    ---
    tags:
      - User
      - User Document
    operationId: download_user_document
    produces:
      - application/pdf
    parameters:
      - name: user_id
        in: path
        description: TrueNTH user ID
        required: true
        type: integer
        format: int64
      - name: doc_id
        in: path
        description: User Document ID
        required: true
        type: integer
        format: int64
    responses:
      200:
        description:
          Returns the file contents of the requested user document
      400:
        description: if the request includes invalid data or references
      401:
        description:
          if missing valid OAuth token or if the authorized user lacks
          permission to edit requested user_id
      404:
        description: if user_id or doc_id doesn't exist
    security:
      - ServiceToken: []

    """
    user = get_user(user_id, 'edit')
    download_ud = None
    for ud in user.documents:
        if ud.id == doc_id:
            download_ud = ud
            break
    if not download_ud:
        abort(404, "matching user document not found")

    file_contents = None
    try:
        file_contents = ud.get_file_contents()
    except ValueError as e:
        abort(400, str(e))

    response = make_response(file_contents)
    response.headers["Content-Type"] = 'application/{}'.format(ud.filetype)
    response.headers["Content-Disposition"] = 'attachment; filename={}'.format(
        ud.filename)

    return response


@user_api.route('/user/<int:user_id>/patient_report', methods=('POST',))
@crossdomain()
@oauth.require_oauth()
def upload_user_document(user_id):
    """Add a Patient Report for the user
    (e.g. from WiserCare, P3P, Symptom Tracker, etc)

    File must be included in the POST call, and must be a valid PDF file.
    File will be stored on server using uuid as filename; file metadata
    (including reference uuid) will be stored in the db.

    ---
    tags:
      - User
      - User Document
      - Patient Report
    operationId: post_patient_report
    produces:
      - application/json
    parameters:
      - name: user_id
        in: path
        description: TrueNTH user ID
        required: true
        type: integer
        format: int64
    properties:
      file:
        type: file
        description: File to upload
    responses:
      200:
        description: successful operation
        schema:
          id: response_ok
          required:
            - message
          properties:
            message:
              type: string
              description: Result, typically "ok"
      400:
        description: if the request includes invalid data
      401:
        description:
          if missing valid OAuth token or if the authorized user lacks
          permission to edit requested user_id
      404:
        description: if user_id doesn't exist
    security:
      - ServiceToken: []

    """
    user = get_user(user_id, 'edit')

    def posted_filename(req):
        """Return file regardless of POST convention

        Depending on POST convention, filename is either the key or
        the second part of the file tuple, not always available as 'file'.

        :return: the posted file
        """
        if not req.files or len(req.files) != 1:
            abort(
                400, "no file found - please POST a single file using "
                     "standard multipart/form-data parameters")
        key = next(iter(req.files.keys()))  # either 'file' or actual filename
        return req.files[key]

    filedata = posted_filename(request)

    contributor = None
    if 'Authorization' in request.headers:
        token = request.headers['Authorization'].split()[1]
        intervention = Intervention.query.join(Client).join(Token).filter(
            and_(Token.access_token == token,
                 Token.client_id == Client.client_id,
                 Client.client_id == Intervention.client_id)).first()
    else:
        intervention = Intervention.query.join(Client).join(Token).filter(
            and_(Token.user_id == current_user().id,
                 Token.client_id == Client.client_id,
                 Client.client_id == Intervention.client_id)).first()

    if intervention:
        contributor = intervention.description

    data = {'user_id': user_id, 'document_type': "PatientReport",
            'allowed_extensions': ['pdf'], 'contributor': contributor}
    try:
        doc = UserDocument.from_post(filedata, data)
    except ValueError as e:
        abort(400, str(e))
    except OSError as e:
        current_app.logger.error('patient_report post error - {}'.format(e))
        abort(500, str(e))

    db.session.add(doc)
    db.session.commit()
    auditable_event("patient report {} posted for user {}".format(
        doc.uuid, user_id), user_id=current_user().id, subject_id=user.id,
        context='assessment')

    # This is a notifiable event; trigger any applicable notifications
    data.update({"document_id": doc.id})
    del data['allowed_extensions']
    client_event_dispatch(event="user_document_upload", user=user, **data)

    return jsonify(message="ok")


@user_api.route('/user/<int:user_id>/password_reset', methods=('POST',))
@crossdomain()
@oauth.require_oauth()  # for service token access, oauth must come first
@roles_required(
    [ROLE.ADMIN.value, ROLE.STAFF_ADMIN.value, ROLE.STAFF.value,
     ROLE.INTERVENTION_STAFF.value])
def trigger_password_reset_email(user_id):
    """Trigger a password reset email for the specified user

    Allows admins, staff, etc to manually trigger password reset emails to
    patients, allowing them to easily change their passwords and login without
    knowing their current password or email.
    ---
    tags:
      - User
    operationId: send_password_reset
    produces:
      - application/json
    parameters:
      - name: user_id
        in: path
        description: TrueNTH user ID
        required: true
        type: integer
        format: int64
    responses:
      200:
        description: successful operation
        schema:
          id: response_ok
          required:
            - message
          properties:
            message:
              type: string
              description: Result, typically "ok"
      400:
        description: if the request includes invalid data
      401:
        description:
          if missing valid OAuth token or if the authorized user lacks
          permission to edit requested user_id
      404:
        description: if user_id doesn't exist
    security:
      - ServiceToken: []
      - OAuth2AuthzFlow: []

    """
    user = get_user(user_id, permission='edit')
    if '@' not in getattr(user, 'email', ''):
        abort(400, "invalid email address")

    try:
        with force_locale(user.locale_code):
            user_manager.send_reset_password_email(user.email)
    except ValueError as e:
        current_app.logger.debug('failed to send reset password email to %s', user.email)
        abort(400, str(e))

    auditable_event(
        "password reset email triggered for user {}".format(user_id),
        user_id=current_user().id,
        subject_id=user_id,
        context='login',
    )
    return jsonify(message="ok")


@user_api.route('/user/<int:user_id>/table_preferences/<string:table_name>')
@crossdomain()
@oauth.require_oauth()
def get_table_preferences(user_id, table_name):
    """Returns simple JSON defining user table preferences

    Returns the user's view preferences for the given table.
    ---
    tags:
      - User
    operationId: get_table_preferences
    parameters:
      - name: user_id
        in: path
        description: TrueNTH user ID
        required: true
        type: integer
        format: int64
      - name: table_name
        in: path
        description: Portal UI Table Name
        required: true
        type: string
        format: int64
    produces:
      - application/json
    responses:
      200:
        description:
          Returns JSON of the user's table view preferences.
        schema:
          id: table_preferences
          properties:
            user_id:
              type: integer
              format: int64
              description: TrueNTH user ID
            table_name:
              type: string
              description: Name of table in portal UI
            sort_field:
              type: string
              description: Field on which to sort the table
            sort_order:
              type: string
              description: Method to use for sorting (asc or desc)
            filters:
              type: object
              description: JSON describing filter fields and values
            updated_at:
              type: string
              format: date-time
              description: Last updated datetime
      401:
        description:
          if missing valid OAuth token or if the authorized user lacks
          permission to view requested user_id
      404:
        description:
          if no TablePreference found for given user_id and table_name
    security:
      - ServiceToken: []

    """
    user = get_user(user_id, 'view')
    pref = TablePreference.query.filter_by(
        table_name=table_name, user_id=user.id).first()
    # 404 case handled by get_user() above.  Return
    # empty list if no preferences yet exist.
    if not pref:
        return jsonify({})

    return jsonify(pref.as_json())


@user_api.route(
    '/user/<int:user_id>/table_preferences/<string:table_name>',
    methods=('PUT', 'POST'))
@crossdomain()
@oauth.require_oauth()
def set_table_preferences(user_id, table_name):
    """Add a consent agreement for the user with named organization

    Used to add a consent agreements between a user and an organization.
    Assumed to have just been agreed to.  Include 'expires' if
    necessary, defaults to now and five years from now (both in UTC).

    NB only one valid consent should be in place between a user and an
    organization.  Therefore, if this POST would create a second consent on the
    given user / organization, the existing consent will be marked deleted.

    ---
    tags:
      - User
    operationId: set_table_preferences
    produces:
      - application/json
    parameters:
      - name: user_id
        in: path
        description: TrueNTH user ID
        required: true
        type: integer
        format: int64
      - name: table_name
        in: path
        description: Portal UI Table Name
        required: true
        type: string
        format: int64
      - in: body
        name: body
        schema:
          id: set_preferences
          properties:
            sort_field:
              type: string
              description: Field on which to sort the table
            sort_order:
              type: string
              description: Method to use for sorting (asc or desc)
            filters:
              type: object
              description: JSON describing filter fields and values
    responses:
      200:
        description:
          Returns JSON of the user's table view preferences.
        schema:
          id: table_preferences
          properties:
            user_id:
              type: integer
              format: int64
              description: TrueNTH user ID
            table_name:
              type: string
              description: Name of table in portal UI
            sort_field:
              type: string
              description: Field on which to sort the table
            sort_order:
              type: string
              description: Method to use for sorting (asc or desc)
            filters:
              type: object
              description: JSON describing filter fields and values
            updated_at:
              type: string
              format: date-time
              description: Last updated datetime
      400:
        description: if the request includes invalid data
      401:
        description:
          if missing valid OAuth token or if the authorized user lacks
          permission to edit requested user_id
    security:
      - ServiceToken: []
      - OAuth2AuthzFlow: []

    """
    user = get_user(user_id, 'view')
    if not request.json:
        abort(400, "no table preference data provided")

    req = request.json
    req['user_id'] = user.id
    req['table_name'] = table_name

    pref = TablePreference.from_json(req)
    db.session.add(pref)
    db.session.commit()

    return jsonify(pref.as_json())


@user_api.route('/user/<int:user_id>/invite', methods=('POST',))
@crossdomain()
@oauth.require_oauth()  # for service token access, oauth must come first
@roles_required([ROLE.SERVICE.value])
def invite(user_id):
    """Send invite email message to given user

    It is expected that the named user has the expected roles and
    affiliations such as organization to determine the appropriate
    email context to send.

    Include query param `?preview=True`
    to have the email content generated but not sent.

    Only available via service token.
    ---
    tags:
      - User
    operationId: user_invite
    parameters:
      - name: user_id
        in: path
        description: TrueNTH user ID
        required: true
        type: integer
        format: int64
      - name: preview
        in: query
        description: Set to simply preview the message - don't send!
        required: false
        type: integer
        format: int64
    produces:
      - application/json
    responses:
      200:
        description:
          Returns success of call (i.e. {message="sent"}, or JSON of the
          generated message if `preview` is set.
        schema:
          id: user_invite
          properties:
            sender:
              type: string
              description: Email message sender
            recipients:
              type: string
              description: Email message recipients
            subject:
              type: string
              description: Email message subject
            body:
              type: string
              description: Email message body, includes footer
      400:
        description:
          if given user lacks a legitimate looking email address
      401:
        description:
          if missing valid OAuth token or if the authorized user lacks
          permission to view requested user_id
    security:
      - ServiceToken: []
      - OAuth2AuthzFlow: []
    """
    user = get_user(user_id, 'edit')
    validate_email(user.email)
    sender = current_app.config.get("MAIL_DEFAULT_SENDER")
    org = user.first_top_organization()
    org_name = org.name if org else None
    name_key = UserInviteEmail_ATMA.name_key(org=org_name)
    args = load_template_args(user=user)
    mail = MailResource(
        app_text(name_key), locale_code=user.locale_code, variables=args)
    email = EmailMessage(
        subject=mail.subject, body=mail.body, recipients=user.email,
        sender=sender, user_id=user.id)
    if request.args.get('preview'):
        message = email.as_json()
    else:
        email.send_message()
        db.session.add(email)
        db.session.commit()
        message = "okay"
    return jsonify(message=message)


@user_api.route('/user/<int:user_id>/messages')
@crossdomain()
@oauth.require_oauth()
@roles_required(
    [ROLE.ADMIN.value, ROLE.STAFF_ADMIN.value, ROLE.STAFF.value,
     ROLE.CLINICIAN.value, ROLE.INTERVENTION_STAFF.value])
def get_user_messages(user_id):
    """Returns simple JSON defining user email messages

    Returns JSON of all messages where the receipient_id matches the given
    user.
    ---
    tags:
      - User
    operationId: get_user_messages
    parameters:
      - name: user_id
        in: path
        description: TrueNTH user ID
        required: true
        type: integer
        format: int64
    produces:
      - application/json
    responses:
      200:
        description:
          Returns JSON of the user's email messages.
        schema:
          id: user_messages
          properties:
            sender:
              type: string
              description: Email message sender
            recipients:
              type: string
              description: Email message recipients
            subject:
              type: string
              description: Email message subject
            body:
              type: string
              description: Email message body
            sent_at:
              type: string
              format: date-time
              description: Datetime of when email message was sent
            user_id:
              type: integer
              format: int64
              description: TrueNTH user ID
      401:
        description:
          if missing valid OAuth token or if the authorized user lacks
          permission to view requested user_id
    security:
      - ServiceToken: []
      - OAuth2AuthzFlow: []

    """
    get_user(user_id, 'view')
    messages = []
    for em in EmailMessage.query.filter(
            EmailMessage.recipient_id == user_id):
        messages.append(em.as_json())

    return jsonify(messages=messages)


@user_api.route('/user/<int:user_id>/questionnaire_bank')
@crossdomain()
@oauth.require_oauth()
def get_current_user_qb(user_id):
    """Returns JSON defining user's current QuestionnaireBank

    Returns JSON of the user's current QuestionnaireBank. Date is
    assumed as UTCnow, unless specific as-of date provided.
    ---
    tags:
      - User
    operationId: get_current_user_qb
    parameters:
      - name: user_id
        in: path
        description: TrueNTH user ID
        required: true
        type: integer
        format: int64
      - name: research_study_id
        in: query
        description: research study id, defaults to 0
        required: false
        type: integer
      - name: as_of_date
        in: query
        description: Optional datetime for user-specific QB (otherwise, now)
        required: false
        type: string
        format: date-time
    produces:
      - application/json
    responses:
      200:
        description:
          Returns JSON of the user's current QB info
      400:
        description: invalid query parameters
      401:
        description:
          if missing valid OAuth token or if the authorized user lacks
          permission to view requested user_id
    security:
      - ServiceToken: []

    """
    from ..models.qb_status import QB_Status
    user = get_user(user_id, 'view')
    date = request.args.get('as_of_date')
    # allow date and time info to be available
    date = FHIR_datetime.parse(date) if date else datetime.utcnow()

    research_study_id = int(request.args.get('research_study_id', 0))
    qstats = QB_Status(
        user=user, research_study_id=research_study_id, as_of_date=date)
    qbd = qstats.current_qbd()

    if not qbd:
        qbd_json = {'questionnaire_bank': None}
    else:
        qbd_json = qbd.as_json()
        expiry = qstats.expired_date
        qbd_json['relative_expired'] = (
            FHIR_datetime.as_fhir(expiry) if expiry else None)

    return jsonify(qbd_json)