Aam Digital
en
Language
en English de German fr French

Documentation & Support for the Aam Digital case management platform

Search for the articles here or browse the categories below.

Popular topics: Administration General

Browse by topic

Find guides, tutorials, and answers organised by category.

📁

Administration

Setup and configuration related questions

Sebastian Browse
📁

General

User questions interacting with the case management system

Sebastian Browse

Popular articles

What other people are reading right now.

Administration

User Roles & Permissions

Aam Digital offers a configurable access control system to limit user permissions. Users can be assigned one or more roles that can limit permissions on various levels: - limit access to selected types of data (e.g. restricting sensitive health or learning details) - limit access to selected groups of records (e.g. allowing access only to beneficiaries at a specific location) - limit access to selected documents (e.g. users can only access individually assigned notes) - limit selected actions (e.g. allowing only coordinators to register new beneficiaries) User management is based upon the Keycloak system, which offers options for integration with other single-sign-on providers, 2-factor-authentication and advanced authentication options. also see: - Data Security one-pager - User Guide: Invite & Disable users User Roles A role defines a set of access rules that give users permissions regarding certain data records. One role usually defines several rules that logically depend on each other. This keeps user management simple, as you only have to assign one (or very few) roles to each user. (e.g. one role could give read-only access to all participant records and also permission to create and update notes). for details about the available access rules, see below Roles are assigned to individual user accounts. A user can also be assigned to multiple user permission roles. The permissions of each role are then combined to give that user access to the combination of all the roles’ access rights. (e.g. a user could be assigned roles of “health worker” and “teacher”, giving access to health and education details for that account) Access Rules An access rule defines a subset of data and an allowed action that this user role is allowed to take on the given subset of data Actions that can be granted/restricted are: - create: add new data records - read: access existing data records - update: edit existing data records - delete: completely remove existing data records Subsets of data can be defined by a combination of: - Entity type (e.g. Participants / Notes / Events / …) - Value of a field of the record (e.g. participants with “gender” = “male”; events with “status” = “approved”) - (!) it is not possible to use “indirect values” for permissions (e.g. participants whose linked school is located in region X) - Link to the current user (e.g. notes where the user is included in the “authors” field) - Link to a “project” entity that the current user is added to (e.g. the user’s profile is linked to several “project” entities, participant records are also linked to a project entity, the user receives access only to those participants that are linked to the same project that the user account is linked to) Example: Rules for approval workflow Roles: - manager - Access to all records - All actions (read / update / delete) - fieldworker - Access to records linked to own user account - Allowed to create and read these records - Allowed to edit records only if the record’s “status” field is “to be reviewed” Scenario / Workflow: (exact fields and status categories below can be freely customized for your specific system) 1. fieldworker registers new participant. 1. → creates new record in Aam Digital. 2. “registered by” field of the new record is automatically pre-filled with a link to the user account. This gives the team clarity who recorded this data and grants the fieldworker continued access to this new record 3. “status” field of the new record is automatically pre-filled to “to be reviewed”. This gives the manager an indication to check this record (and approve it) and allows the fieldworker to continue editing the record making corrections. 2. manager approves the new participant. 1. → edits the record created by the field worker and checks the details. 2. manager changes the “status” field to “approved”. This gives the team an indication that this record has been checked. The fieldworker can still see the record (he/she is still assigned in the “registered by” field) 3. … but the fieldworker now cannot edit the information anymore (because the status is not “to be reviewed”). This ensures there are no accidental changes that contradict the approval. 3. … the manager at any time can also change the status of a record back to “to be reviewed”, which allows the fieldworker to again edit the record and make corrections until the manager changes the status again.

General

Importing data from a spreadsheet (.csv or Excel file)

Aam Digital provides a visual user interface to help you import data from other formats using either CSV(.csv) or Excel (.xlsx, .xls) file formats. Any spreadsheet (Google Sheets, etc.) can be saved or exported in these formats and then imported to Aam Digital. The app then guides your through the process of mapping data into the correct fields. In this guide, we will demonstrate how to upload a file containing multiple beneficiaries. For advanced import options also see the sections below about linking imported records to some other entry or updating existing data through an import. You can also watch the following video guide: https://www.youtube.com/watch?v=IYyArbZCp6Y Importing data from spreadsheet 1. Click on "Import" from the main menu. You can also find the "Import from file" functionality in the three-dot-menu at the top right of any list in Aam Digital 2. Upload a CSV or Excel file. You can save any spreadsheet (MS Excel, Google Sheets, etc.) as a .csv, .xlsx or .xls file and import it to Aam Digital. (In this example, we are uploading a file with data of multiple children of a school) Then click on "Continue" (at the top right of the import screen). 3. Based on the uploaded file, you can choose the entity type to import. This tells the system where to create new records from your file (e.g., selecting “Child” means the data from your spreadsheet will be added to the “Children” list of Aam Digital.) You can import data for any of your record types. 4. The "Map Columns" step shows a list of all the columns from your imported file. Here you select into which field in Aam Digital each column from your file should get imported. In case you don’t select any field here for an entry, the system will ignore that column and the data for these fields will be blank in the record. 1. For certain types of Aam Digital fields, like dropdowns or dates, a button "Configure value mapping" appears after you select that field for a column. With this, you can configure for each unique value in the imported records how it should match to the corresponding data format in Aam Digital’s structure (e.g. so that a date's day and month are correctly detected). 5. Finally, continue to the last step "Review Data" You can preview the data with the mapping done in the previous step here. The table shown here is exactly how the records will be added to your system when you run the import. You can also navigate back to the previous steps to make changes. 6. Once it is mapped according to your configuration. You can "Start Import". 7. After importing, you can view the newly created records in the normal list of your system. Undoing an import Aam Digital provides an option to undo the upload of any files you have imported. On the first step of the Import page you see all your previous imports listed on the right side. By clicking the "Undo Import" button, you can remove the records that were created through that import from the Aam Digital system, along with any associated records and links created during the import process. This functionality is especially useful when you realize you have uploaded duplicate data or incorrect files. Instead of deleting each record and its multiple links one by one, the undo import feature allows you to delete all relevant records at once. Linking imported records with individual "parent" entities When you import a spreadsheet of survey responses or exam results, these often include the name of a person they relate to. In this sense your imported data rows include a column with a "reference" to an existing record (e.g. that person's profile) in Aam Digital. You can use the import's data mapping to link each item to its correct person. Please refer to the video guide here, showing how to configure such links during the import: https://www.youtube.com/watch?v=IYyArbZCp6Y To import a link to an existing record in any field of your imported records, take the following steps in while going through an import as described above: 1. Let's assume you want to import some notes and link them to children that are already in the database. You upload a csv spreadsheet with the following columns: note_title | note_text | child_name | child_phone 2. In the "Map Columns" step you can select one one or more of your columns to be mapped to a field with datatype "link to another record", which will create a link during import. In our example, map child_name and child_phone columns to the "Children" field of the Note record. (We want to make sure we can distinguish kids with the same name by mapping a second field, the phone number.) 3. The "Configure Value Mapping" button appears next to each of these columns. Here you define how the values in your imported columns are compared to existing records in the database. In our example, open it for both "configure value mapping" dialogs and respectively select "Name" (for the child_name column, so that the values are matched with the "Name" field of existing Child records in the system) and "Phone" (for the child_phone column) for the two mapped fields. 4. When you proceed to the preview step you see that as children of the notes there are actual links to existing records. Only if all mapped fields (in our example here both the "name" and "phone number" of the child) from the imported file match exactly with the values in an existing record, then the link is imported. If there are multiple records matching the value(s), the system links the first one it finds. Linking imported records to one fixed related entity Other than the scenario described above, you sometimes may need to link all the imported records to the same selected entity. For example, you may import a list of participants and want to create a participant record for each row of your import and then additionally select one "Activity" in your system to which all of the new records shall be linked also. The following steps show how you can do this: When files are imported into the Aam Digital system, the system also provides additional functionalities to the user. You can link these imported records to various pre-defined activities in the system or another entity. This linking process is optional; you can import files without associating activities with the records. This feature helps reduce your workload by simplifying the process of associating an event or activity with multiple beneficiaries. For example, if you are importing the data of multiple “Children” to the system, you can use this advanced functionality to link these children to an entity like a school and also link the children to a recurring activity like attendance tracking in the system. 1. While configuring an import as shown above, in the step "Select Import Type(s)", click on "Advanced Import Actions" to link a record with one or more entities. 2. You can link the imported records to any other entity in your Aam Digital system, if your data structures have some fields linking the two record types. For example, you could link Child records to a School or Activity. 3. After selecting what kind of link you need, select the particular existing record in the system. e.g. choose the specific activity or school in from the system. 4. Continue and complete the normal import process (see above). After creating new records from your imported file, the system will also automatically create links based on what you configured here. Update existing data through an import If you already have records in your Aam Digital system you can also update details of this existing data with an imported file. For example, you could update the phone numbers of your existing beneficiaries by importing a file with their names or IDs and the new phone numbers, if someone from your team has collected these separately. Instead of manually updating each record one by one, you can import a file that updates the existing records. Usually Aam Digital's import feature creates a new record for each row in your imported file. But you can configure it to compare the imported data with the existing records in the system instead. For this, you select some fields/columns as identifiers. During import the field value of the selected identifiers in the imported data has to match the value in the existing record, then the record will be updated instead of created as a new entry. Please note: The columns you select to match existing records need to be correctly mapped and configured in the "Column Mapping" step of the import process. As an example, we will here update a children records from an imported file, using the name and date of birth to match existing records: 1. After selecting a file, in the "Select Import Types" step of the import, expand the optional section "Check/Update existing instead of creating new records" 2. Select one or more fields that define which existing record matches a row in your imported data. In this example, we use "name" and "date of birth". This means if a row in the imported spreadsheet has the exact same name as a record already in the database AND the date of birth is also matching between that imported row and the existing record, then the system will update the existing entry. 3. Proceed through the other import steps as usual. Make sure you correctly "Map Columns". The matching will only succeed if the fields used to identify the existing records are also correctly mapped 4. Once your data is mapped, the system identifies records that will be updated. These are specially highlighted in the "Review & Edit Data" step. Importing multiple values from a single column (for a multi-select dropdown field) In some situations, you may need to capture multiple values for a single field in your form. For instance, if you want to record the different languages a participant speaks, you can now easily import multiple values for that single field. Prerequisite: - The record type for which you are importing data must have a dropdown field with the " allow multiple values (multi-select)" option enabled (see Adding/Editing a field if necessary) Example data: Name, languages spoken John, "English, German" Doe, "English, French, German" (Here, the second column "languages spoken" contains a comma-separated list of multiple languages) Steps to import: (1) In step 2 of the import process - "Select Import Type": Under Additional Settings > "Multi-value Separator" you can specify the character used to separate multiple values in your file. If the suggested separators (comma (,) and semicolon (;)) are not what you need, you can also type into the field and add a different separator. (2) In step 3 "Map columns": Select the relevant multi-select dropdown field for your column with multiple values. Then click on the "Configure value mappings" button next to it. Each unique value from your imported file will be mapped to a corresponding value in the system. The individual values are split and mapped separately.This ensures that every value is accurately linked to the appropriate field in the system, regardless of the combinations used. (3) In step 4, the preview, you will see that multiple values are imported for a single record:

Administration

Manage User Accounts

You can manage user accounts yourself within the Aam Digital application if your account has the required "account_manager" permission role. Below you can find instructions for the different user management tasks. Managing User Accounts To access the User Accounts overview, navigate to "Settings" from bottom left of the navigation menu. From there, click on "User Management". To edit an existing user profile, click on "User Accounts": Add User Account 1. Navigate to “Users” in the main menu on the left-hand side of the screen (please note that depending on your configuration, the navigation item may come under a different name). 2. Click the "Add New" button to add a new record (or open an existing record to edit that user) 3. Create the user profile record by capturing basic user information, such as their name and contact information. Click on “Save”. This makes that person available in the system to link records with, e.g., assign notes or tasks to this profile. 4. Create the account for platform login for this user by navigating to the "User Account" tab in the record. Enter the user’s email address and assign user roles. You can assign multiple roles to a given user. 5. Click on “Create account & send invitation”. This will send an invitation to that email address. 6. The system then sends an automatic message to that email address with a link to create an initial password, enabling that user to log in and access your Aam Digital system. also see User Roles & Access Permissions Deactivate User Account To deactivate an account and prevent that person from logging into your Aam Digital system, you need to edit that User record's details: 1. Navigate to the profile of that user - or open the User Accounts list from the "System Settings" (see above "Managing User Accounts") 2. Within the respective user profile, click on the “User Account” tab. 3. Click the “Deactivate user” button to ensure the user cannot log in with the previous credentials. 4. You can also re-activate that user account again by editing it. Delete User Record and Account 1. Navigate to “Users” in the main menu on the left-hand side of the screen. 2. In the user list, click on the user account you wish to delete. 3. Within the respective user profile, you can delete the user completely using the "Delete" option in the three-dot menu in the top-right corner of the record. The related user login (if any account exists for this record) is then deleted automatically as well. Please be aware that deleting a user record will permanently and completely remove any related data from your system. This includes any links to notes, tasks, or other activities that identified this user as an author or responsible person for these. If the user has been linked to any data, you most likely do not want to delete the user record and instead only archive or anonymize it. see Archiving and Anonymizing records

Administration

Adding a new field to a profile form

Aam Digital is extremely customizable and you can easily change the fields and data structures of your record types (e.g. add an additional phone number field to the "student" profile - or change anything else around this). You can even create as many new "record types" as you need to manage your specific project (e.g. adding "school", "village" or other lists of related records with their own profiles). In this guide, we explain how you can change the form of an existing record type. As an example here, we'll walk you through the process of adding a "mother's name" field to the "Children" record type. (You can follow along in our interactive demo system: demo.aam-digital.com) 1. Open the Admin UI for the record type: 1. navigate to the list of Children (or open a child's details) 2. click the three-dot menu in the top right 3. select "Edit Data Structure" 2. Navigate to the "Details View" section of the Admin UI: 1. Now you see a preview of your profile view for that record type. You can edit the fields and layout here by dragging and dropping elements. 3. Drag & drop the "Create New Field" block from the sidebar on the right into the place in your form where you want to see the new field 4. When you drop this somewhere in the form preview, a popup opens to configure the newly created field. 1. Add a "label" (the text that will be displayed to users) 2. Select a "type". For our example this will simply be "text". 3. The type defines what kind of data can be entered in this field. Apart from simple text you can also define dropdown fields, links to other records, file attachments or other special field types. 4. 5. Save the popup form. Your new field is now shown in the preview. 5. You can also display the new field in the list of all records. 1. These steps to display the field in the list are optional. You can also just add the field to the details profile and skip this. 2. Switch to "List View" on the left of the Admin UI to display the new field in your overall table of all children also 3. Click the "+" button at the bottom of the page below the preview of the currently displayed table columns 4. Activate the "toggle" by clicking on the name of your field to display it in that list view 6. Save the Admin View overall, using the "Save" button on the top right of the page 7. You can now use your new field whenever you create or edit a "Child" record.

Administration

Integration with TolaData

Aam Digital offers an API to integrate with other systems automatically by linking the servers. For example, we collaborate closely with TolaData, a digital platform for organisations to track, manage and visualize results. Integrating your Aam Digital case management system with TolaData allows you to get dashboards, indicators and visualizations of your logframe and targets in real-time, based on the participants and activities your team records in Aam Digital. Set up API integration Reach out to your Aam Digital tech support to receive an API key that allows the external system access to selected reports of your data. This initial activation of the API is something you cannot do yourself in the application at the moment. We are happy to support you with the setup overall. In your TolaData system, you can add integration with your Aam Digital system from the "Data tables" section through the "Import table" menu: - the Customer URL represents the base API endpoint (e.g. https://my-system.aam-digital.app) - the Keycloak URL represents the Authentication server, including your system's custom "realm" (e.g. https://keycloak.aam-digital.com/realms/***my-system***/protocol/openid-connect/token) - Client ID and Client secret are access credentials provided by your technical server administrator - Make sure the Client has required roles (reporting_read, reporting_write)

General

Adding dropdown options

Add a new dropdown option Dropdown options from which your team can select a pre-defined category can be easily edited. Just click on the small tool / wrench icon next to the dropdown field. This will show you all options and allows you to rename, delete, add or reorder. You can also just start typing and select the entry "Add option ...": Adding multiple dropdown options at once In addition to adding dropdown values individually, you can also add multiple values at once. You can import a list of values with one click. You can simply copy a list of options from a text file or spreadsheet and paste it into the field to "add new option". Each value, whether separated by commas or placed in separate cells/lines, will be added as a separate entry in the dropdown list. The system can identify and skip duplicate values, ensuring that each option in the dropdown is unique. Scenario: I want to add a list of cities to the dropdown options from a spreadsheet: 1. Copy the values from the spreadsheet and paste them in the dropdown field 2. Click the “+” icon to create each value as a dropdown option