====== medAL-data Administrator Guide ======

This page gathers all the informations needed to use the medAL-//data// web application as an administrator.





===== Reset a user's password =====

Follow these steps to reset a user's password:
  - From the home page, go to ''Admin Corner'' > ''Users Management''.
  - Look for the desired user, and click ''Reset Password''.
  - A popup will appear: click on ''Reset''.
  - An email should be sent to the user to reset its password.




===== Two-Factor authentication =====

==== Generate secrets for all users ====

It may happen that some users do not have two-factor authentication enabled on their account (mainly due to accounts created before the medAL-//data// update adding this implementation).To generate secrets for users that do not yet have two-factor authentication enabled, run:
<code>
sudo dokku enter <app_name> web php artisan 2fa:authenticate_all --send_email
</code>
, and confirm by typing ''yes''. Press //Enter//.

Users should receive their code via email.


==== Generate user's new secret ====

To refresh a new two-factor authentication secret for a given user, follow these steps:
  - Run the command: \\ <code>
sudo dokku enter <app_name> web php artisan 2fa:reauthenticate --send_email
</code>
  - Enter the user's email address and press //Enter//.
  - Confirm by typing ''yes''. Press //Enter//.

The new code should be printed, and the user should receive their new code via email.



===== Roles and permissions =====

==== Assign a role to a user ====

To assign a role to a user, follow these steps:

  - From the home page, go to ''Admin Corner'' > ''Users Management''.
  - Look for the desired user, and click on ''Edit''.
  - Under ''Roles'' choose the role to add to the user.
  - Click on ''Update''.

==== Repair the database permission ====

If you are missing permissions or if some permissions are not assigned to the right role. Or if some items are missing in the left menu. Run the command:
<code>
sudo dokku enter <app_name> web php artisan permission:fix
</code>

==== Update of the algorithm  ====
If for some reason you find that the algorithm used by the tablets is not up to date.  Run the command:
<code>
sudo dokku enter <app_name> web php artisan HealthFacilitiesAlgo:update
sudo dokku enter <app_name> web php artisan update:versions
</code>


==== production.ERROR: Missing key 'createdAt' on data for 'patient' error  ====

If you spot this error in the log file, then you should run the command :
<code>
sudo dokku enter <app_name> web php artisan json:fix_created
</code>
and then reload the failed json and confirm that it is now imported with :
<code>
sudo dokku enter <app_name> web php artisan cases:reload
</code>

==== The export date is not the current date  ====

First we need to know why the export didn't work. For that open the log file at 03:20AM and communicate the error. 
To launch manually the export, run this command :
<code>
sudo dokku enter <app_name> web php artisan export:start
</code>


==== JSON Failure Folder Not Empty ====
If you have some JSON inside the Failed Folder table, then please retrieve the error in the log file. You can search with the JSON file name. Share with us the  error.
When we have corrected the issue, then you can reload the failed folder with this command:
<code>
sudo dokku enter <app_name> web php artisan cases:reload
</code>

==== Some Examples ==== 

=== Count the number of medical cases which are not yet synchronize with REDCap inside the PostgreSQL database ===
<code bash>
dokku postgres:enter <postgres_container_name> psql -U postgres <postgres_database_name> -c "SELECT count(*) FROM public.medical_cases where redcap=false"
</code>

=== Retrieve environment variable ===
[[https://doc.medal-suite.org/doku.php?id=medal-data:variables|More information about medAL-data environment variable]]
<code bash>
# Example to retrieve all environment variable
sudo dokku config:show <app_name>
# Example to retrieve CREATOR_ALGORITHM_URL environment variable
sudo dokku <app_name> config:get CREATOR_ALGORITHM_URL
</code>

=== Set a environment variable ===
<code bash>
sudo dokku config:set <app_name> MAIL_USERNAME="exemple@mail.com"
# You can also add the --no-restart flag to set STUDY_ID environment variable without restarting the app
sudo dokku config:set <app_name> STUDY_ID="Dynamic Tanzania" --no-restart
</code>