sascha benjamin cohen edited this page Sep 7, 2017 · 41 revisions

( this page will continue to be expanded as we collect common questions and answers, and as new items arise they will be shared via the ilios mailing lists as well )

Q: Can the Ilios UI be customized?

A: Yes!

Beginning with version 3.31.0, schools have the ability to customize headers, colors, and logos for Ilios. Information about how to implement these customizations is available at

Q: Does Ilios have a size limit on Learning Materials?

A: in 2.4? Yes! in 3.0? Not Really!

Ilios 2.4 enforces a hard file-upload-size-limit for learning materials of 105MB. In Ilios 3, the size limit will be controlled by your server PHP settings noted below. We still recommend not uploading files of a size greater than ~50MB.

For lectures and other similar media, where the likely method of delivery is streaming/viewing from the server, rather than downloading, they should be stored elsewhere, and the link to it should be the resource saved in Ilios.

For a typical user, the download of a 105MB file will take between 3-10 minutes on a fast broadband connection, longer on a slow connection; anything that size or larger is not ideal for a student trying to access info in a timely manner.

Keep in mind though, that the setting in Ilios are only one potential throttle on upload size limits: PHP configuration defaults are much less. You may have to bump the values for the following config options in your php.ini file accordingly:


For example, the following will set the upload limit to 105mb. (Please note that both settings must be adjusted)

   post_max_size = 105M
   upload_max_filesize = 105M

After making adjustments to your php.ini file, make sure to restart your web server.


Ilios User Guide, release version 2.2, pp. 27-29.

Q: Can I modify the description of a Learning material?

A: Learning Materials have a number of editable fields to allow for descriptive information, but they can (and should) be used in different ways, and have different applications.

The Description field is entered when a material is first loaded into the system; it is meant to describe the file or asset broadly -- a sort of abstract if you will -- and once entered, is not editable.

The Instructional Notes field is entered whenever a learning material is associated to a course or session in the curriculum. It is editable, and unique to that particular use of the learning material. In addition, it can be set to be shown or hidden from learners, depending on what information is desired in that space. It is editable at any time by users with appropriate permissions.

So: if the description of a file is absent or lacking content when you associate to the curriculum, you can always add the information you want displayed in the Instructional Notes field. When used in conjunction with one another, these two fields can provide robust detail regarding content and usage of learning materials.

Q: When you roll over a course in Ilios from one year to the next, will it keep all its associated data and relationships?

A: Yes -- Mostly.

A course will carry along with it all the basic course data: sessions and their objectives and attributes, including links to course objectives, the course definition and its attributes, all learning materials, assigned topics and MeSH terms, etc. A user has the option of replicating all the scheduled offerings from the original course, and placing them on the calendar for the new course. This is the default option; you may also choose to create the new course without scheduled offerings, retaining only the course and session curricular data.

But please note that if a course is rolled over into a new academic year (one other than that of the original course), links up to programs, their associated competencies, and program cohort relationships will not be maintained. Learner group relationships are never rolled over with course information from one academic year to another. This means that the relationships between course objectives and program objectives are reset on rollover, and the assigned program cohort(s) of the original course will not appear in the new rolled over course.

For courses cloned into the same academic year as the original course, programs, their associated competencies, and cohort relationships will be maintained and presented in the summary for review.

The reason for this is that programs and their associated objectives cohorts and competencies are associated to a course via the cohort of students traveling through a given program, and attached to the course. These issues fall outside the construct of the course as a stable entity year over year (your students will be different each term, guaranteed), and so a course must be re-hooked up to the programmatic level and its competencies each year.

While we have plans to create a more automated and streamlined workflow and method for capturing, cloning, and re-associating this higher level data, we don't yet have the resources to throw at the development of the feature set. If anyone in the community is wanting to take a stab at it, we'd love to hear from you. Until we can tackle this, rollover only rolls over courses and what they contain, and not their external relationships to groups, cohorts, and programs.


Ilios User Guide, release version 2.2, p. 38.

Q: Can I copy a single Session from one course to another?

A: Yes! Sessions can be copied from one course to any other target course, even into the same course where it currently exists. Just click on the copy icon in the upper right of the selected session, choose your target course, and save.

Q: Is it a good idea to cut and paste learning objectives from Microsoft Word or similar robust word processing applications into Ilios?

A: No!

Despite the ability to paste pretty much anything into the entry field for a learning objective in Ilios, it is never a good idea to cut and paste from MS Word into a web application without first cleaning up the entry via a simple text editor (like textpad, or notepad). The reason for this is two-fold:

  1. Word adds an immense amount of hidden code to everything you write, and when you cut and paste it into Ilios, you are also pasting all the hidden markup and xml that has been generated behind the scenes. To give you a sense of the scale, a simple 19 word objective such as

"Appraise and assimilate the scientific evidence from the literature and apply it to clinical decision making for individual patients"

when pasted from word is captured in the database as an item containing nearly 18,000 characters -- only 133 of which are visible or desired. Converting your objectives to plain text first -- or even better, entering them directly into Ilios, using the text editing tools provided -- is by far a better option.

  1. It is very easy (considering the issue above) for a cut-and-paste from Word to contain illegal characters, or improperly encoded characters. Once these are in the system, it is challenging to work with them. A common problem will be the inability to save a course or session object to which bad data has been attached. It is also very challenging to track down and correct these types of hidden, embedded errors so that the users are not confounded over and over again.

Best practice is to always enter objectives for programs, courses and sessions into Ilios as plain text--either directly or from a simple plain text editor such as notepad or textpad, and to use the built-in editing tools to provide any additional formatting needed.

BUT...With Ilios 3, we have provided for this with a new editor which will clean any illegal or hidden characters from a cut&paste entry. We also have provided a tool which can be run on installation which will apply the same cleaning action to existing objectives and description entries in your database.


see [Troubleshooting: Dealing with Character Encoding Issues] (

Q: Is the Ilios database available in db platforms other than MySQL?

A: No.

Ilios is strictly a MySQL data application. MSSQL, Oracle, and other platforms are not currently supported, and there is no current plan for porting to them. Because Ilios is an open source application, we do not expect to make the database available on any proprietary platforms.

Q: Can I get a diagram of the database?

A: Yes!

A snapshot is available here. The schematic is updated whenever major modifications are made to the data model. However, please note that with the release of version 3.0, the schema will be getting frequent (~monthly) modifications to allow rapid development and deployment of new features and enhancements. We urge all users to begin migrating their affiliated systems from database connections to using the Ilios API.

Q: Is there a data dictionary available?

A: Yes!

It is available here. This is still a work in progress, and we will be updating it as frequently as we are able. Comments and additions are welcome; please post them to the forums or email them to

Q: Can we modify the data model for our own deployment?

A: Of course you can.

But -- we don't recommend it. If you do, you will need to maintain any customizations independently of official upgrades and releases, and we cannot guarantee that your changes will conform with future development. If you fork the code here on GitHub, and keep your modifications here, it is really helpful to us and to others for seeing what is being done and what various schools feel they need that is not yet in the model.

Q: Is it safe to run large reports against the live database?

A: Safe? yes. Smart? Not so much.

As with any active data system, we strongly encourage the use with Ilios 2.4 of a separate slave or clone database for large reports, or the use of a Business Intelligence warehousing system such as Cognos, Pentaho, or similar products. This is because deep analytics can be very resource intensive for a system, and there is no way to balance that with the potential high level needs of a large user population. Our philosophy is that the users needs come first in resourcing --- and that means that reporting is best when done in a separate environment, a "walled garden" if you will.

With Ilios 3.0, as noted elsewhere, we discourage direct reporting from the database, and strongly encourage all users to leverage the API for their reporting needs.

Q: What is a “cohort” in Ilios, and how are cohorts created?

A: Cohorts are designated groups of learners who begin enter a program together, and so share the same basic matriculation date and demands regarding progress and graduation. You can think of an Ilios cohort as synonymous with a “graduating class of year XXXX”. Cohorts are created automatically each time a new year is added to a program. Program years can be added retroactively up to seven years prior to the current year, and seven years forward.


Ilios User Guide, release version 2.2, pp.12-13.

Q: What is an “Academic Year” in Ilios?

A: An academic year defines two things in ilios. First, Academic Year is synonymous with “Program Year” – a given calendar year during which an academic program is active, and associated with an incoming cohort of students, who in turn will be held to the requirements, objectives, and competencies defined for that specific year.

Second, Academic Year also defines the calendar time between two specific dates which correspond to a single annual cycle in the curriculum (eg, an LCME “year”). In the current version of Ilios this value is a “baked in” configuration, with the academic year beginning July 1 and ending June 30 of the following calendar year. In future releases, we expect the academic year to be configurable by each school. As more and more curricula develop models independent of the concept of “year” (focusing more on phase and level), we will still need to track and associate these phases to a given annual cycle (or “academic year”) in order to appropriately report out to accrediting groups, as well as to identify associations with students in regard to registration, matriculation, time to graduation, etc. We will continue to refine the Ilios model to stay ahead of this progress in the community, and to provide additional tools and methods to address the ever-changing innovations being introduced to health professions curricula.

Q: How do I change the color of a session type in the calendar?

A: Modify the Session Type Record in the School Administration tab.

Starting with Ilios 3.32.0, color display, along with other attributes, can be managed directly in the UI on the School Administration page. Simply select the Session Type you wish to modify, and choose your desired color, and save.

Please note that attributes of Session Type other than color can only be modified when the session type is not in use. Once linked to any activity, only session color can be modified for Session Types in use.

Q: Can you retroactively create courses in Ilios for previous years?

A: No.

Ilios by design does not allow the retroactive creation of new curriculum via the UI. If you think about it, you'll see why this could be a very problematic issue in terms of audit and accountability. The only time that it really is valid to be doing this is in an initial implementation, in order to input material as a baseline. You may create courses for the current academic year and future academic years, but not for previous academic years. While there is no way to override this from the UI of Ilios, in 2.4 you can still get this information in with a little coordination during implementation. Courses may be created and assigned into the current academic year, during initial data load for an implementation, and once created (but not yet populated), a database update can be run to shift them to the desired year. You must have already created the corresponding program years for these courses (program years can be created retroactively), and once you have reconciled this information, your Ilios instance will have a history of prior-year courses, which can be edited to meet your needs. In Ilios 3.0 you may post a retroacctive course via the API.

This should not be a regular action after implementation, as it will negatively impact the ability to accurately report out for accreditation and related auditable matters.

Q: Can I get my Ilios Calendar to synchronize to my phone automatically?

A: Yes!

Mobile sync has been one of the most sought after features by our student users; beginning with version 2.4, this feature is available to all users using the rss/sync icon above the calendar display.

Q: Can I add different Session Types for Ilios?

A: Yes!

Ilios by default provides the complete recommended list of instructional and assessment types developed by Medbiquitous and the AAMC. If you are NOT participating in the AAMC curriculum inventory project, then you may add or modify these values as you wish. Session types are school-specific, and are maintained in the data table session_type. In 2.4.x, Colors for new sessions may be assigned by following the instructions in the FAQ on custom css styles here: In 3.32.0 and above, colors are managed directly in the UI.

If you ARE participating in the AAMC curriculum inventory project, be aware that the default recommended instructional and assessment methods listed are the only values that will be accepted into the national upload at this time. Any non-standard entries will require a mapping to cross-reference them to those standards. So you can still add any other session types you wish into Ilios; but if you want them to be included in your curriculum inventory export, you will need to map them to one of the existing values already in the system. Similarly, while Ilios allows for the use of any competency framework model of up to two tiers of hierarchy, for purposes of the AAMC curriculum inventory your local competency framework must map to the values provided in the AAMC aggregate data. Ilios provides a table for managing and maintaining this mapping.



Q: Is it a good idea to store protected (HIPAA, FERPA; PHI, ePHI) information in Ilios?

A: No!

Whether as part of the curriculum structure, or within learning materials, it is never a good idea to store HIPAA or FERPA protected data within Ilios. Despite the security in place on the application, the nature of how the data is distributed to students and used allows for the misuse and/or abuse of protected information, regardless of any safety features that may be put in place. It is never a good idea to store protected information where it may be searched, downloaded, or distributed beyond the boundaries of a secure system.

Q: How often are new versions of Ilios released, and where can I get updates?

A: Frequently!

Ilios development follows a continuous quality improvement cycle, which means that we provide enhancements and improvements on an ongoing basis. Ilios is currently (2017) updated on a rolling weekly schedule; with our new frontend CDN deployment for Ilios 3.0, new UI enhancements are deployed on a weekly basis without the need for code downloads. With the core code, new releases are available from the code download site ( approximately every 2-4 weeks (sometimes a little sooner, sometimes a little later). The API will have major versions released on a rolling 18 month cycle.

If you want to be alerted to new releases, you can subscribe to our Public Release Notification mailing list here:

Q: How do I use Ilios to upload to the AAMC Curriculum Inventory?

A: Ilios provides all the tools you need to craft a high level model and report of your curriculum for export to the AAMC. Instructions are found in the latest User Guide pp.47-50 (v2.4.5 and above), and here on the wiki, covering report building, mapping to the PCRS, and all other areas.

Q: Can I copy a Curriculum Inventory Report from one year to the next?

A: Yes!

just click on the rollover icon at the top of your desired CI report page, as you would for a course, and the entire structure of the report will be copied over into your target year. You will still need to populate the courses associated with each sequence block, but the overall block structure of the report will be automatically created for you.

Q: Can I set the order in which learning materials are displayed to my students?

A: Yes!

Learning Materials (LMs) are by default shown in the order they are added to a course or session. But you can always set the order for their display by using the drag and drop ordering tool in the course or session LM section you are working with.

Q: Can I search in vocabulary terms using the MyReports tool?

A: Yes!

Terms from any vocabulary can be selected as part of a MyReports inquiry into the system.

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.