.. _user-details-functions:

User details functions
--------------------------------

.. index:: Macro function;fn.request_user_name
.. index:: Macro function;fn.request_user_role
.. index:: Macro function;fn.request_user_email
.. index:: Macro function;fn.request_user_pkid
.. index:: Macro function;fn.request_user_type
.. index:: Macro function;fn.list_end_user_names
.. index:: Macro function;fn.user_type_from_context_details
.. index:: Macro function;fn.user_vendor_status


.. tabularcolumns:: |p{4.5cm}|p{5cm}|p{5.5cm}|

+-----------------------------------+----------------------------------------------------------+---------------------------------------+
| Function                          | Description                                              | Example                               |
+===================================+==========================================================+=======================================+
|                                   |                                                          | ::                                    |
|                                   |                                                          |                                       |
| fn.request_user_name              | Return the logged in username.                           |    {{fn.request_user_name}}           |
+-----------------------------------+----------------------------------------------------------+---------------------------------------+
|                                   |                                                          | ::                                    |
|                                   |                                                          |                                       |
| fn.request_user_role              | Return the logged in user role.                          |    {{fn.request_user_role}}           |
+-----------------------------------+----------------------------------------------------------+---------------------------------------+
|                                   |                                                          | ::                                    |
|                                   |                                                          |                                       |
| fn.request_user_email             | Return the logged in user email address.                 |    {{fn.request_user_email}}          |
+-----------------------------------+----------------------------------------------------------+---------------------------------------+
|                                   |                                                          | ::                                    |
|                                   |                                                          |                                       |
| fn.request_user_pkid              | Return the logged in user pkid.                          |    {{fn.request_user_pkid}}           |
+-----------------------------------+----------------------------------------------------------+---------------------------------------+
| fn.request_user_type              |  Return the logged in user's user type,                  | ::                                    |
|                                   |  such as "Admin", "End User" and "End User + Admin".     |                                       |
|                                   |                                                          |    {{fn.request_user_type}}           |
+-----------------------------------+----------------------------------------------------------+---------------------------------------+


.. tabularcolumns:: |p{4.5cm}|p{5cm}|p{5.5cm}|

+-----------------------------------+-----------------------------------------------------------+----------------------------------------+
| Function                          | Description                                               | Example                                |
+===================================+===========================================================+========================================+
|                                   | Given a lookup direction and specified target             | ::                                     |
|                                   | hierarchy type as input parameters,                       |                                        |
| fn.list_end_user_names            | return a list of *end users* (data.User.username)         |   {{# fn.list_end_user_names           |
|                                   | from the current hierarchy scope to the specified level.  |   up Customer #}}                      |
|                                   | The user type should contain "End User". The direction    |                                        |
|                                   | can be "up", "down", "above", "below", or "local".        |                                        |
|                                   | Target hierarchy type can be "System", "Hcs",             |                                        |
|                                   | "Provider", "Reseller", "Customer", "IntermediateNode",   |                                        |
|                                   | "Site", "LinkedSite". To exclude target hierarchy type    |                                        |
|                                   | or direction from the resulting filter, pass fn.null.     |                                        |
+-----------------------------------+-----------------------------------------------------------+----------------------------------------+
|                                   | Given a provided context with user details, typically     | ::                                     |
| fn.user_type_from_context_details | "input" or "pwf", returns the *user type* for the user    |                                        |
|                                   | based on the role and authorized admin hierarchy          |   {{fn.user_type_from_context_details  |
|                                   | association.                                              |   input }}                             |
|                                   |                                                           |                                        |
|                                   | * User type is "End User + Admin" if role is selfservice  |                                        |
|                                   |   and there is an associated authorized admin hierarchy   |                                        |
|                                   | * User type is "End User"  when role is selfservice       |                                        |
|                                   |   without authorized admin hierarchy                      |                                        |
|                                   | * User type is "Admin" when role is administration        |                                        |
|                                   | * Otherwise, user type is Invalid                         |                                        |
|                                   |                                                           |                                        |
+-----------------------------------+-----------------------------------------------------------+----------------------------------------+
| fn.user_vendor_status             | Given a username as input parameter, return the vendor(s) | ::                                     |
|                                   | of the services that the user has, as follows:            |                                        |
|                                   |                                                           |   {{fn.user_vendor_status abby.black}} |
|                                   | * ``cisco`` for Cisco services                            |                                        |
|                                   | * ``microsoft`` for Microsoft services                    |                                        |
|                                   | * ``webex`` for Webex services                            | Output                                 |
|                                   | * ``hybrid_cisco_ms`` for Cisco and Microsoft services    |                                        |
|                                   | * ``hybrid_cisco_webex`` for Cisco and Webex services     | ::                                     |
|                                   | * ``hybrid_ms_webex`` for Microsoft and Webex services    |                                        |
|                                   | * ``None`` otherwise                                      |     cisco                              |
|                                   |                                                           |                                        |
+-----------------------------------+-----------------------------------------------------------+----------------------------------------+