Cross-framework import support

[canstudios-nicolaw]

Fixes #2288

This is a PR for the cross framework import support feature, it matches the original proposal document which was laid out previously.

The user now gets guidance through the import process so that they can see which plugins they need to be update and which can be updated for them. There is no longer a blanket ban on importing courses that have an older framework version.

I have created a more detailed document to aid testing here: https://docs.google.com/document/d/1geSzp0OCPdCzJ4htRG4GsOxOkjE1pa103m-gQjBgXvM/edit?usp=sharing. This explains the routes that the code takes as well as some expected scenarios.

[tomgreenfield]

Once again, thanks for all the work that's gone into this!

I have some preliminary rewording suggestions now I've seen the tables in situ. Generally, I think it might make it clearer to approach the versioning from a "what's in my import?" versus "what's already installed in my tool?" perspective.

Current display

The following plugins are not supported in this authoring tool. You must remove or update these plugins before you can continue with the import.

Name	Current Version	New Version	Status
Custom Theme	2.0.4-alpha.18	N/A	Incompatible

The following plugins are not supported in this authoring tool. Compatible versions of these plugins have already been installed so your course will be updated to use the compatible versions.

Name	Current Version	New Version	Status
Accordion	2.1.2	4.0.0	Outdated
Box menu	3.0.0	4.0.1	Outdated
Close	1.0.5	1.0.3	Outdated
Graphic	2.0.5	3.0.0	Outdated
Graphical Multiple Choice Question	3.0.0	4.0.0	Outdated
Hotgrid	2.1.1-alpha.1	2.1.1	Outdated
Media	2.1.1	4.1.0	Outdated
Multiple Choice Question	2.2.1	3.0.0	Outdated
Narrative	2.1.0	5.0.1	Outdated
Page Level Progress	3.1.0	4.1.1	Outdated
Spoor	2.1.3	3.2.0	Outdated
Text	2.0.3	3.0.0	Outdated

The following plugins will be installed or updated in the authoring tool.

Name	Current Version	New Version	Status
Confidence Slider	2.2.0	2.2.0	Compatible
iOSScrollFix	0.1.3-alpha.1	0.1.3-alpha.1	Compatible

Suggested display

Name	Import Version	Installed Version	Action
Custom Theme	2.0.4-alpha.18	None	Action Needed
Accordion	2.1.2	4.0.0	Skip
Box menu	3.0.0	4.0.1	Skip
Close	1.0.5	1.0.3	Skip
Graphic	2.0.5	3.0.0	Skip
Graphical Multiple Choice Question	3.0.0	4.0.0	Skip
Hotgrid	2.1.1-alpha.1	2.1.1	Skip
Media	2.1.1	4.1.0	Skip
Multiple Choice Question	2.2.1	3.0.0	Skip
Narrative	2.1.0	5.0.1	Skip
Page Level Progress	3.1.0	4.1.1	Skip
Spoor	2.1.3	3.2.0	Skip
Text	2.0.3	3.0.0	Skip
Confidence Slider	2.2.0	2.1.2-alpha.1	Update
iOSScrollFix	0.1.3-alpha.1	None	Install

Notes

• The category descriptions would move to a key above the table with explanations.
• Each action in the fourth column would still be coloured according to its associated category.
• The third column would always display the version on the server i.e. if there's nothing installed, show None or if there's an older version, display that.
• Also toying with the idea of swapping columns two and three?

[canstudios-nicolaw]

Thanks for taking the time to review this! Much appreciated.

I will talk this through internally first thing tomorrow and get back to you.

[canstudios-nicolaw]

@tomgreenfield

Having discussed this internally we have a few more suggestions to the UI you have proposed.

• The text in the action column has an appropriate font colour but doesn't have the coloured background as it does now. We think that in the current design these labels look a bit button-y and having text like "Install" and "Update" could be more confusing if the button-y design was kept.

• Instead of 'Import Version' and 'Installed Version' headings, we suggest calling them 'Course Version' and 'Authoring Tool Version' which we hope will make the end result clearer

• We suggest that in each row (with the exception of red plugin rows) the 'winning' plugin version is made bold to indicate that this will be the end result. In yellow columns this would mean that the 3rd column would be bold, and in green columns the 2nd column would be bold

• Depending on how it looks, we wonder if it would be worth putting tooltips on actions to explain. Particularly "Skip" seems a little ambiguous (we couldn't think of a better alternative). I would complete the other parts first and we could decide on this later, just wanted to suggest it.

What do you think?

[tomgreenfield]

The text in the action column has an appropriate font colour but doesn't have the coloured background as it does now. We think that in the current design these labels look a bit button-y and having text like "Install" and "Update" could be more confusing if the button-y design was kept.

Completely agree, I originally tried to click the coloured boxes myself!

Instead of 'Import Version' and 'Installed Version' headings, we suggest calling them 'Course Version' and 'Authoring Tool Version' which we hope will make the end result clearer

We indeed discussed having 'authoring tool version' as a heading so that seems okay. I'm still keen to avoid calling it the 'course version' due to a bit of ambiguity over what the 'course' is, and the fact that the import ZIP is an entire source package rather than just the course content. Can't think of anything more clear than 'import version' or 'imported version' at this point in the day!

We suggest that in each row (with the exception of red plugin rows) the 'winning' plugin version is made bold to indicate that this will be the end result. In yellow columns this would mean that the 3rd column would be bold, and in green columns the 2nd column would be bold

Interesting idea, I like it.

Depending on how it looks, we wonder if it would be worth putting tooltips on actions to explain. Particularly "Skip" seems a little ambiguous (we couldn't think of a better alternative). I would complete the other parts first and we could decide on this later, just wanted to suggest it.

I pondered over tooltips while reviewing. Not to duplicate the text in the legend/key but rather to give more specific information, such as why the plugin is incompatible, e.g. if it isn't supported in the installed framework version or if there's a dodgy semver somewhere. 'Skip' could possibly become something like 'Use installed version'.

[canstudios-nicolaw]

👍 I'll get working on this and we can discuss further on Monday

[dancgray]

Thanks for all of the work that has gone into this. Works well so far.

On the second import page the import source button should have a state change after it is clicked. At the moment it is unclear if anything is happening until the import completes.

[canstudios-nicolaw]

Thanks for testing @dancgray :)

Thanks for the feedback - it will be good to implement that at the same time as the other UI changes :)

[canstudios-nicolaw]

@dancgray @tomgreenfield I've attached a screenshot with these changes, I've got a few things left to test before I commit. Any thoughts so far?

[canstudios-nicolaw]

I have also updated the testing document to reflect these latest changes to the table.

[canstudios-nicolaw]

I have added the invalid semver check - I believe all actions have been completed and this is ready for re-review.

[tomgreenfield]

Hi @canstudios-nicolaw, I hope you don't mind an iterative approach to reviewing while this PR is in draft mode. I'm keen to avoid discussing too much in one go and also there a quite a few test imports for me to go through!

[tomgreenfield]

Brilliant, now onto a code review 👓.

Please also ensure all files use two-space indentation.

[canstudios-nicolaw]

Indentation fixes are in progress

[canstudios-nicolaw]

As discussed in the call today I will be updating this so that 'backwards' imports are blocked (it will not be possible to import a FWv4 course into an AT that is running FWv2 for example)

[canstudios-nicolaw]

Added a simple import not allowed message for downgrade cases.

[canstudios-nicolaw]

Our QA team have now finished testing this and are satisfied that it is ready for release.

The only odd behaviour encountered was what happens if one user performs actions that affect a second users import while it is running. I think this is an acceptable edge case for now as there is similar behaviour if users edit the same course.

"user 1 removes a plugin that appears in the user's 2 course during user 2's cross framework import.
In the above scenario:

• User 2 hangs as the course import buttons, and a 502 proxy error eventually occurs.
• User 2 is still in the plugins list step of course import and can still click the Import source button.
• The course is imported, though without the missing plugin"

[tomgreenfield]

There is a misleading message saying that the framework version is identical when importing a course – do we want to tweak this?

[Rahulc24]

Hi,

I'm currently trying to make some textual updates to a Adapt course that was developed by someone else a few years ago. Unfortunately, I do not have access to the original Adapt authoring instance used to create it. All I have are a few ZIP files, which I believe are the source packages. I attempted to import these ZIP files into my current Adapt authoring tool instance but encountered the following error:
“This course can't be imported.”
(Screenshot attached)

After investigating, it seems that the original course may have been built using custom or local plugins that are no longer available in the public Adapt plugin library. I suspect this is causing compatibility issues, especially since the framework and plugins used at that time appear to be outdated compared to the current Adapt version.

I also searched the Adapt public plugin library for the missing plugins referenced in the course files but was unable to find them.

Could you please advise on:

1. Whether there’s a workaround to import such older courses?
2. Please suggest ways to solve this.

Please note that I’ve only recently started using the Adapt authoring tool- just a few days ago- so I’m still learning the platform. I would really appreciate your guidance on how best to proceed. I would really appreciate your guidance at the earliest, as I’m on a tight deadline to update and redeploy this course.

[ambivalent-axiom]

It is possible that you have a build. Either way I would attempt to make changes directly into the code instead of importing it to authoring tool.

…

On Tue, 22 Jul 2025 at 07:17, Rahulc24 ***@***.***> wrote: *Rahulc24* left a comment (adaptlearning/adapt_authoring#2389) <#2389 (comment)> Hi, I'm currently trying to make some textual updates to a Adapt course that was developed by someone else a few years ago. Unfortunately, I do not have access to the original Adapt authoring instance used to create it. All I have are a few ZIP files, which I believe are the source packages. I attempted to import these ZIP files into my current Adapt authoring tool instance but encountered the following error: “This course can't be imported.” (Screenshot attached) After investigating, it seems that the original course may have been built using custom or local plugins that are no longer available in the public Adapt plugin library. I suspect this is causing compatibility issues, especially since the framework and plugins used at that time appear to be outdated compared to the current Adapt version. I also searched the Adapt public plugin library for the missing plugins referenced in the course files but was unable to find them. Could you please advise on: 1. Whether there’s a workaround to import such older courses? 2. Please suggest ways to solve this. Please note that I’ve only recently started using the Adapt authoring tool- just a few days ago- so I’m still learning the platform. I would really appreciate your guidance on how best to proceed. I would really appreciate your guidance at the earliest, as I’m on a tight deadline to update and redeploy this course. Package.contents.Source.file.sample.1.png (view on web) <https://github.com/user-attachments/assets/84d5e925-ef26-4c25-9fce-f056fabc8b53> Screenshot.3466.1.png (view on web) <https://github.com/user-attachments/assets/23f88ce9-d7f8-401d-8104-02b91e36036b> — Reply to this email directly, view it on GitHub <#2389 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AQROW3JYXB776DALC7TFG533JW3NXAVCNFSM6AAAAACCBS4FMGVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZTCMBQHA2DENJTGM> . You are receiving this because you are subscribed to this thread.Message ID: ***@***.***>

[Rahulc24]

@ambivalent-axiom Thanks for the suggestion. I am not an expert in the method you mentioned, so are there any alternative approaches?. Also, could you explain the reason behind the issue and suggest possible solutions?

[ambivalent-axiom]

Just extract and open content directory in code editor, then look for places you need to edit by using search. No I can’t, to explain anything I need to see at least the file and its contents + adapt logs after unsuccessful import attempt.

…

On Tue, 22 Jul 2025 at 10:00, Rahulc24 ***@***.***> wrote: *Rahulc24* left a comment (adaptlearning/adapt_authoring#2389) <#2389 (comment)> @ambivalent-axiom <https://github.com/ambivalent-axiom> Thanks for the suggestion. I am not an expert in the method you mentioned, so are there any alternative approaches?. Also, could you explain the reason behind the issue and suggest possible solutions? — Reply to this email directly, view it on GitHub <#2389 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AQROW3MGJQH536LRW44WPAT3JXORJAVCNFSM6AAAAACCBS4FMGVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZTCMBRGM2DQNJRHA> . You are receiving this because you were mentioned.Message ID: ***@***.***>