diff --git a/staff-user-documentation/README.md b/staff-user-documentation/README.md new file mode 100644 index 000000000..9f48aa453 --- /dev/null +++ b/staff-user-documentation/README.md @@ -0,0 +1,403 @@ +# Compact Connect: Staff Onboarding Guide + +This guide provides step-by-step instructions for Compact and State administrative staff to onboard into the Compact Connect Production and Beta environments. + +## Table of Contents +- [Initial Setup and Login](#initial-setup-and-login) +- [User Management](#user-management) +- [System Configuration](#system-configuration) +- [General User Functions](#general-user-functions) +- [Data Upload](#data-upload) +- [Automated License Data Upload for IT Departments](#automated-license-data-upload-for-it-departments) +- [Privilege and License Management](#privilege-and-license-management) + +--- + +## Initial Setup and Login + +### First-Time Access +The Compact Connect team will configure the initial Compact Staff user account. You will receive an invitation email at the address provided to the team containing: +- Your username +- A temporary password +- Login instructions + +### Logging In +1. Navigate to the main Compact Connect dashboard +2. Select **"Login as Compact or State Staff"** +3. Enter your login credentials using the temporary password provided +4. You will be prompted to create a permanent password upon first login + + +![Login Page](images/staff_login.png) + +![Change Password Page](images/reset_password.png) + +--- + +## User Management + +Once logged in, administrators can manage staff users through the user management interface. + +### Accessing User Management +Navigate to **"Manage Users"** in the left navigation panel to access user management functions. + +![Dashboard Navigation](images/manage_users_tab.png) + +![User Management Page](images/user_management_page.png) + +### Inviting New Staff Users + +#### Steps to Invite Users +1. Click the **"Invite"** button in the top-right corner of the User Management page +2. Complete the invitation form with the following information: + - User's email address + - First and last name + - Compact or State affiliation + - Required permissions (see [Permissions](#permissions) section below) +3. Click **"Send Invite"** to dispatch the email invitation + +![User Invitation Form](images/invite_user_form.png) + +### Permissions + +The Compact Connect system uses role-based permissions that can be granted at either the compact or state level: + +#### Available Permissions + +##### Read Private +- Access to non-public practitioner information (e.g., date of birth) +- Should only be granted when necessary for job responsibilities + +##### Read SSN +- Access to full Social Security Numbers of practitioners +> ⚠️ **Critical**: Grant this permission only when necessary for job responsibilities + +##### Admin +- Manage other users within their respective Compact or State scope +- Define privilege fee rates +- Configure system notification recipients +- **Compact Admins**: Can deactivate privileges +- **State Admins**: Can set encumbrances on licenses and privileges +- Includes both Read Private and Read SSN permissions + +##### Write (State-level only) +- Upload licensure data for a specific state + +### Managing Existing Users + +#### Resending Invitations +If a user hasn't logged in within seven days or didn't receive their initial invitation: + +1. Locate the user in the User Management list +2. Click the three-dot menu (⋮) next to their name +3. Select **"Resend Invite"** + +#### Editing User Permissions +To modify a user's permissions: + +1. Click the three-dot menu (⋮) next to the user's name +2. Select **"Edit Permissions"** +3. Adjust the permission settings as needed +4. Click **"Save Changes"** + +>⚠️ **Important**: Users currently logged into the system must log out and log back in for permission changes to take effect. + +#### Deactivating Users +When a staff member leaves their position: + +1. Click the three-dot menu (⋮) next to their name +2. Select **"Deactivate"** +3. Confirm the deactivation + +--- + +## System Configuration + +### Accessing Settings +Administrators can configure system settings by clicking the **gear icon** on the left navigation panel. The available settings will depend on your role and permissions. + +![Settings Page](images/settings_tab.png) + +--- + +### State/Jurisdiction Administrator Settings + +State administrators have access to jurisdiction-specific configuration options that control how their state operates within the Compact Connect system. + +#### Jurisdiction Fees for Compact Privileges + +State administrators must configure the fees that their jurisdiction charges for compact privileges. These fees are set per license type offered by the compact. + +**Configuration Steps** +1. Navigate to the Jurisdiction Settings section +2. Locate the "Privilege Fees" section +3. Set the standard fee amount for each license type +4. Optionally configure military rates (see below) + +##### Military Rate Configuration +Jurisdictions may offer reduced rates for active military-affiliated licensees: + +1. Enable the "Military Rate" option +2. Set the reduced fee amount for military members +3. This creates a special fixed price for qualifying military personnel + +#### Contact Details for System Notifications + +State administrators must provide email addresses for three types of system notifications: + +**1. Operations Notification Recipients** +- Email addresses added to this list will receive notifications related to technical support (such as issues with license uploads) + +**2. Encumbrance Notification Recipients** +- Email addresses added to this list will receive notifications related to license and privilege encumbrances. + +**3. Summary Report Notification Recipients** +- Email addresses added to this list will receive periodic summary reports generated by the system +- These reports provide insights into privilege purchasing within your respective jurisdiction. + +> **💡 Recommendation**: Use distribution lists that users can subscribe to or unsubscribe from without requiring configuration changes in the system. + +#### Jurisprudence Requirements + +Configure whether your jurisdiction has jurisprudence requirements for licensees (assessment of knowledge of laws and rules governing practice): + +1. Toggle the "Jurisprudence Requirements" setting +2. Optionally provide a website link where requirements are defined +3. This information helps licensees understand your jurisdiction's specific requirements + + +#### Enabling Licensee Registration + +State administrators can enable licensee registration for their jurisdiction. This allows licensees within your state to register, and allows licensees from other states to purchase privileges within your state. + +> ⚠️ **Important**: Once enabled, this setting cannot be disabled + +--- + +### Compact Administrator Settings + +Compact administrators have access to compact-wide configuration options that affect all participating jurisdictions. + +#### Card Code Verification (CCV) Setup in Authorize.net Account + +> ⚠️ **Important**: Before configuring payment processing credentials, you must first set up the Card Code Verification (CCV) security feature in your Authorize.net account to ensure secure payment processing, described in this section. + +**Setup Steps** +1. Log into your Authorize.net merchant account +2. Navigate to Account Settings by clicking the **Settings** button in the main navigation + +![Authorize.net Settings Button](images/authorize_net_home_settings.png) + +3. From the Settings page, locate and click **"Enhanced Card Code Verification"** + +![Enhanced Card Code Verification Option](images/authorize_net_settings_eccv.png) + +4. Configure your CCV settings to match the recommended security configuration shown below and select the save button: + +![CCV Configuration Settings](images/eccv_filter_settings.png) + +> **🔒 Security Note**: Proper CCV configuration is essential for payment security and fraud prevention. These settings help protect both your organization and licensees during payment processing. + +--- + + +> ⚠️ **Important**: After completing the CVV configuration setup in the Authorize.net account, return to the Compact Connect settings page to complete the following configuration settings. +> +#### Compact Administration Fee + + + +The Compact Administration Fee is a standardized fee collected for every privilege purchase that supports compact operations: + +**Configuration Steps** +1. Navigate to the Compact Settings section +2. Locate the "Commission Administration Fee" section +3. Set the flat rate amount (e.g., $50) +4. This fee is added to jurisdiction-specific fees for every privilege purchase + +> **Important Notes:** +> - This fee is the same regardless of which jurisdiction the provider is purchasing a privilege for +> - It's applied to all privilege purchases across all participating states + +#### Transaction Fee Configuration + +Compact administrators can configure whether licensees are charged fees to cover payment processor costs + +**Licensee Transaction Charges** +1. Enable/disable transaction fee charging +2. Set the fee amount to help cover transaction costs +3. This fee is applied once per privilege purchased + +> ⚠️ **Important**: if the compact will not charge transaction fees, leave this section blank. + +#### Contact Details for System Notifications + +Similar to state administrators, compact administrators must configure notification contacts: + +**1. Operations Notification Recipients** +- Email addresses added to this list will receive notifications related to technical support at the compact level. + +**2. Encumbrance Notification Recipients** +- Email addresses added to this list will receive notifications related to license and privilege encumbrances. + +**3. Summary Report Notification Recipients** +- Email addresses added to this list will receive periodic summary reports generated by the system +- These reports provide insights into privilege purchasing for all jurisdictions within the compact. + +#### Licensee Registration Settings + +Compact administrators can enable licensee registration at the compact level. This is the first step to allowing licensee registration. State admins must then also select to enable licensee registration within their individual jurisdictions: + +> ⚠️ **Important**: Once enabled, this setting cannot be disabled + +--- + +#### Payment Processing Configuration + +Compact administrators can configure Authorize.net payment processing credentials (this must be done after setting up the compact related fees): + +**Setup Steps** +1. Generate API credentials in your Authorize.net account ([view documentation](https://support.authorize.net/knowledgebase/Knowledgearticle/?code=000001271)) +2. Navigate to the "Authorize.net Credentials" section in Compact Settings +3. Enter your credentials: + - **API Login ID** + - **Transaction Key** +4. Click **"Submit"** to enable payment processing + + +> **🔒 Security Considerations:** +- If credentials are ever compromised, generate new ones immediately in your Authorize.net account +- Update the credentials in Compact Connect immediately after generating new ones +- Never share these credentials with others, and do not store them on your device. + +### Settings Validation and Confirmation + +After making any configuration changes: + +1. Review all entered information for accuracy +2. Click **"Save Changes"** or **"Submit"** as appropriate +3. Look for confirmation messages indicating successful updates +4. Some changes may require system processing time before taking effect + +⚠️ **Important Notes:** +- Configuration changes may affect billing and fee collection immediately +- It is recommended to test any configuration changes in the Beta environment before making changes in the Production environment. + +## General User Functions + +### Searching License Data + +#### Accessing the Search Function +Select **"Search Licensing Data"** from the left navigation panel. + +![Search Interface](images/license_search_tab.png) + +#### Search Criteria +You can search using the following parameters: +- **State/Jurisdiction**: Select from dropdown menu. This will filter the results to only display practitioners that have a license or privilege in the specified jurisdiction. +- **Practitioner Name**: Enter full first and last name +- **Combined Search**: Use both state and name criteria + +⚠️ **Note**: Partial name searches are not currently supported. You must enter the complete first and last name. + +#### Performing a Search +1. Enter your search criteria +2. Click **"Search"** +3. Review results on the License Listing page +4. Click any row to view detailed practitioner information + +![Search Results](images/license_list_view.png) + +### Practitioner Details Page + +The practitioner details page displays comprehensive license and privilege information for individual practitioners. + +![Practitioner Details](images/practitioner_details_page.png) + +#### Available Information: +- Licenses and their current status +- Privileges and their current statis +- Privilege history and timeline + +#### Viewing Privilege History +Click **"View Details"** on any privilege card to access: +- Complete privilege timeline, including status changes such as deactivation and encumbrance. +- Status change history + +![Privilege Timeline](images/privilege_summary.png) + +--- + +## Data Upload + +### License Information Upload +**This feature is available to staff users with write permissions only.** + +#### Uploading License Data +1. Select **"Upload Data"** from the left navigation panel +![Data Upload](images/license_upload.png) +2. Click **"Select File"** to select your CSV document +3. Ensure your license data in the CSV file includes all required license data fields as specified in the [License Data Schema Documentation](../backend/compact-connect/docs/README.md). +4. Click **"Submit"** to process the upload + +#### Upload Validation +The system will validate your data and provide weekly email feedback on: +- Successful imports +- Data formatting errors +- Missing required fields + +These email notifications will be sent to whichever email addresses have been set by the state admin for your respective state's Operations notification recipients. + +--- + +## Automated License Data Upload for IT Departments + +### Overview +State IT departments can set up automated license data uploads to CompactConnect through the API, eliminating the need for manual CSV uploads and ensuring timely data synchronization between state licensing systems and CompactConnect. For more information about this setup, see the following document: + +**[Automated License Data Upload Onboarding Instructions](../backend/compact-connect/app_clients/it_staff_onboarding_instructions/README.md)** + +--- + +## Privilege and License Management + +### Deactivating Privileges +**This feature is available to Compact Administrators only.** + +Privileges may be deactivated by Compact Administrators. This may be needed in cases where the practitioner does not want to have an active privilege in a particular jurisdiction for whatever reason (for example, they accidentally purchased a privilege they didn't intend to). + +#### Steps to Deactivate a Privilege +1. Navigate to the practitioner's detail page (see [Practitioner Details](#practitioner-details-page)) +2. Locate the privilege requiring deactivation +3. Click the three-dot menu (⋮) in the top-right corner of the privilege card +![Privilege Actions](images/privilege_action_menu.png) +4. Select **"Deactivate"** +5. Complete the notes section explaining the reason for deactivation +6. Click the **"Deactivate Privilege"** button. + +⚠️ **Important**: Deactivating privileges is different from encumbering them due to adverse actions. Encumbrance procedures are described below. + + +### Encumbering Privileges and Licenses +**This feature is available to State Administrators only.** + +#### Steps to Add an Encumbrance +1. Navigate to the practitioner's detail page(see [Practitioner Details](#practitioner-details-page)) +2. Locate the privilege or license requiring encumbrance +3. Click the three-dot menu (⋮) in the top-right corner of the card +![Privilege Actions](images/privilege_action_menu.png) +4. Select **"Encumber"** +5. Complete the encumbrance form with required information +6. Click the **"Encumber Privilege"** or **"Encumber License"** button + +#### Removing Encumbrances +To remove an existing encumbrance: +1. Navigate to the practitioner's detail page +2. Locate the encumbered privilege or license +3. Click the three-dot menu (⋮) in the top-right corner of the card +4. Select **"Remove Encumbrance"** +5. Complete the removal form +6. Click the **"Confirm Removal"** button. + + +--- diff --git a/staff-user-documentation/images/authorize_net_home_settings.png b/staff-user-documentation/images/authorize_net_home_settings.png new file mode 100644 index 000000000..2b8c77489 Binary files /dev/null and b/staff-user-documentation/images/authorize_net_home_settings.png differ diff --git a/staff-user-documentation/images/authorize_net_settings_eccv.png b/staff-user-documentation/images/authorize_net_settings_eccv.png new file mode 100644 index 000000000..57917c1f7 Binary files /dev/null and b/staff-user-documentation/images/authorize_net_settings_eccv.png differ diff --git a/staff-user-documentation/images/eccv_filter_settings.png b/staff-user-documentation/images/eccv_filter_settings.png new file mode 100644 index 000000000..60fb20df9 Binary files /dev/null and b/staff-user-documentation/images/eccv_filter_settings.png differ diff --git a/staff-user-documentation/images/invite_user_form.png b/staff-user-documentation/images/invite_user_form.png new file mode 100644 index 000000000..92336c4f1 Binary files /dev/null and b/staff-user-documentation/images/invite_user_form.png differ diff --git a/staff-user-documentation/images/license_list_view.png b/staff-user-documentation/images/license_list_view.png new file mode 100644 index 000000000..94d595430 Binary files /dev/null and b/staff-user-documentation/images/license_list_view.png differ diff --git a/staff-user-documentation/images/license_search_tab.png b/staff-user-documentation/images/license_search_tab.png new file mode 100644 index 000000000..a5d63e3f9 Binary files /dev/null and b/staff-user-documentation/images/license_search_tab.png differ diff --git a/staff-user-documentation/images/license_upload.png b/staff-user-documentation/images/license_upload.png new file mode 100644 index 000000000..5538f3c2b Binary files /dev/null and b/staff-user-documentation/images/license_upload.png differ diff --git a/staff-user-documentation/images/manage_users_tab.png b/staff-user-documentation/images/manage_users_tab.png new file mode 100644 index 000000000..7a337729b Binary files /dev/null and b/staff-user-documentation/images/manage_users_tab.png differ diff --git a/staff-user-documentation/images/practitioner_details_page.png b/staff-user-documentation/images/practitioner_details_page.png new file mode 100644 index 000000000..b95727d35 Binary files /dev/null and b/staff-user-documentation/images/practitioner_details_page.png differ diff --git a/staff-user-documentation/images/privilege_action_menu.png b/staff-user-documentation/images/privilege_action_menu.png new file mode 100644 index 000000000..1ec595e88 Binary files /dev/null and b/staff-user-documentation/images/privilege_action_menu.png differ diff --git a/staff-user-documentation/images/privilege_summary.png b/staff-user-documentation/images/privilege_summary.png new file mode 100644 index 000000000..1a6b5f8dd Binary files /dev/null and b/staff-user-documentation/images/privilege_summary.png differ diff --git a/staff-user-documentation/images/reset_password.png b/staff-user-documentation/images/reset_password.png new file mode 100644 index 000000000..e671c99ef Binary files /dev/null and b/staff-user-documentation/images/reset_password.png differ diff --git a/staff-user-documentation/images/settings_tab.png b/staff-user-documentation/images/settings_tab.png new file mode 100644 index 000000000..624182ab4 Binary files /dev/null and b/staff-user-documentation/images/settings_tab.png differ diff --git a/staff-user-documentation/images/staff_login.png b/staff-user-documentation/images/staff_login.png new file mode 100644 index 000000000..bbbeb9060 Binary files /dev/null and b/staff-user-documentation/images/staff_login.png differ diff --git a/staff-user-documentation/images/user_management_page.png b/staff-user-documentation/images/user_management_page.png new file mode 100644 index 000000000..47ed4c4a8 Binary files /dev/null and b/staff-user-documentation/images/user_management_page.png differ