Technical migration 4.1 to 4.3

Before migrating Ametys ODF , you need to migrate Ametys CMS 4 .2.x to 4.3.x

This guide covers technical migration from Ametys ODF 4.1.x to 4.3.0.
See also the data migration guide and the graphics migration guide.   

  1. Data model
    1. Renaming the "main" metadata set in editing mode
    2. Merging contacts
    3. Add a "role" field to the testimonial repeater
    4. Add an "avatar" field (illustration) for contacts
    5. Add fields for Apogée export
    6. Course label management
    7. Skills-based approach
    8. Teaching potential
    9. Enumeration of supporting stages
  2. Workflow
    1. Reference table
    2. Global validation action
    3. Automatic invalidation of parent elements
    4. Republishing action
    5. Importing archives
  3. Other migrations
    1. Changing the name of the Apogée feature
    2. Apogée synchronization
      1. Apogée SCC settings
      2. Apogée synchronization operators
      3. Apogee conversion files
      4. SCC overload
      5. Mapping file and SCC query
    3. Adding a right to mutualize an ELP
    4. Popup on the ELPs of the training sheet

Data model

This chapter deals with changes to the data model that require migration.
To see all the changes made to the model, go to Modifying the data model.

Renaming the "main" metadata set in editing mode

For all ODF content (excluding reference tables), the "main" editing view has been renamed "default-edition".

In your content overrides ODF (WEB-INF/param/content-types/_override/org.ametys.plugins.odf.Content.*.xml), look for all occurrences of:

<cms:metadata-set name="main" type="edition">                             

and replace with

<cms:metadata-set name="default-edition" type="edition">                           

Merging contacts

For training courses, pathways and ELPs, contacts (managers + administrative contacts) have been merged into a single contact repeater.

If you have overloaded the views (metadata-set) of the courses and/or ELP, the reference to the "personInCharge" and "contact" metadata must be replaced by:

<cms:metadata-ref name="contacts">                             
    <cms:metadata-ref name="role"/>                             
    <cms:metadata-ref name="persons"/>                        
</cms:metadata-ref>          

If you are using a customized version of a CDMfr or ROF import or another import XML, the XSL transformation CDMfr -> Ametys and ROF -> Ametys have been modified.

  • The XSL templates named "program-personInCharge" and "program-contact" have been replaced by a single "program-contacts" template.
  • The templates XSL named "course-personInCharge" and "course-contact" have been replaced by "course-contacts".

Look for all occurrences of "program-personInCharge", "program-contact", "course-personInCharge" and "course-contact" in your overloads.

S'il s'agit de "xsl:call-template" (ex: <xsl:call-template name="program-personInCharge"/>), remplacez-les simplement par leur équivalent (ex: <xsl:call-template name="program-contacts"/>).

S'il s'agit de "xsl:template" (ex: <xsl:template name="program-personInCharge">), renommez-le par son équivalent (ex: <xsl:template name="program-contacts">) et référez-vous au template Ametys correspondant pour ré-adapter votre surcharge.

Add a "role" field to the testimonial repeater

If you have overloaded the views (metadata-set) of the training courses and/or itineraries, the "testimonies" repeater becomes :

<cms:metadata-ref name="testimonies">        
    <cms:metadata-ref name="title" />                             
    <cms:metadata-ref name="role" />                             
    <cms:metadata-ref name="image" />                             
    <cms:metadata-ref name="text" />                        
</cms:metadata-ref>        

Add an "avatar" field (illustration) for contacts

If you've overloaded the people views (metadata-set), add the reference to the new "avatar".

<cms:metadata-ref name="avatar"/>          

Add fields for Apogée export

New fields have been added for Apogee export. If the "default-edition" view has been overloaded, these fields must be added to the Apogee tab for all the following contents:

New fields have been added for Apogee export. If the "default-edition" view has been overloaded, these fields must be added to the Apogee tab for all the following contents:

  • Program

<cms:fieldset>                  
    <cms:label i18n="true">PLUGINS_ODF_PROGRAM_APOGEE_FIELDSET</cms:label>                  
    <cms:metadata-ref name="codeApogee" />                  
    <cms:metadata-ref name="cycleApogee" />                  
    <cms:metadata-ref name="start-date-validation" />                  
    <cms:metadata-ref name="end-date-validation" />                  
    <cms:metadata-ref name="start-date-recruitment" />                  
    <cms:metadata-ref name="end-date-recruitment" />                  
</cms:fieldset>                  
  • Course
<cms:fieldset>                  
    <cms:label i18n="true">PLUGINS_ODF_PROGRAM_APOGEE_FIELDSET</cms:label>                  
    <cms:metadata-ref name="codeApogee" />                  
    <cms:metadata-ref name="cycleApogee" />                  
    <cms:metadata-ref name="inscription-types" />                  
    <cms:metadata-ref name="cips" />                  
    <cms:metadata-ref name="duration-apogee" />                  
    <cms:metadata-ref name="start-date-validation" />                  
    <cms:metadata-ref name="end-date-validation" />                  
    <cms:metadata-ref name="start-date-recruitment" />                  
    <cms:metadata-ref name="end-date-recruitment" />                  
</cms:fieldset>                  
  • Container
<cms:fieldset>                  
    <cms:label i18n="true">PLUGINS_ODF_PROGRAM_APOGEE_FIELDSET</cms:label>                  
    <cms:metadata-ref name="codeApogee" />                  
    <cms:metadata-ref name="cycleApogee" />                  
    <cms:metadata-ref name="inscription-types" />                  
    <cms:metadata-ref name="cips" />                  
    <cms:metadata-ref name="duration-apogee" />                  
    <cms:metadata-ref name="siseCode" />                  
    <cms:metadata-ref name="orgUnit" />                  
</cms:fieldset>                  
  • ELP list
<cms:fieldset>                  
    <cms:label i18n="true">PLUGINS_ODF_PROGRAM_APOGEE_FIELDSET</cms:label>                  
    <cms:metadata-ref name="codeApogee" />                  
</cms:fieldset>                  
  • ELP
<cms:fieldset>                  
    <cms:label i18n="true">PLUGINS_ODF_PROGRAM_APOGEE_FIELDSET</cms:label>                  
    <cms:metadata-ref name="codeApogee" />                  
    <cms:metadata-ref name="cips" />                  
</cms:fieldset>                  
  • [Reference table] Nature (Container)
<cms:metadata-ref name="codeApogee" />                  
  • [Reference table] Nature (ELP)
<cms:metadata-ref name="codeApogee" />                  
  • [Reference table] Type of diploma
<cms:metadata-ref name="codeApogee" />                  
  • [Reference table] Diploma
<cms:metadata-ref name="codeApogee" />            

Course label management

Recently, state-controlled training courses have been required to bear a label.
The list of existing labels is imposed by the Ministry of Education: https://www.enseignementsup-recherche.gouv.fr/cid141235/labels-des-formations-controlees-par-l-etat. html

To this end, the diploma reference table contains a new "Labellisation" column (certificationLabel) which allows you to choose from a drop-down list the label associated with a type of diploma (e.g.: Diplôme national de licence - state-controlled).

In addition, a new boolean field "State-controlled training" (certified) has been added to training and courses.

If you have overloaded the "main" views of your courses, add this field to your views.

This new field is used to designate state-approved training courses, so that they can be identified by the corresponding diploma type label.
This is covered in the graphic charter (see graphic migration manual).       

Skills-based approach

The data model has been modified for the competency-based approach.

About training courses :

  • the "requiredSkillSets" field (multiple value of Skill Blocks) becomes requiredSkills (multiple value of Skills) of the same label. 
  • the "acquiredSkillSets" field has been removed

In your content type overloads (abstractProgram, program and/or subprogram), search for occurrences of "requiredSkillSets" and replace with "requiredSkills", then delete all occurrences of "acquiredSkillSets".

About ELPs:

  • the field "requiredSkillSets" (multiple value of SkillSets) has been replaced by "requiredSkills" (multiple value of Skills) with the same wording
  • the "acquiredSkillSets" field (multiple value of SkillSets) has been replaced by the following "acquiredSkills" repeater:
    • Compétence acquises (acquiredSkills) - repeater
      • SkillSet - Reference table - Simple
      • Compéténces (skills) - repeater
        • Compétence (skill) - Reference table - Simple
        • Acquisition level (acquisitionLevel) - Reference table - Simple

Dans vos surcharges du type de contenu ELP (course) recherchez les occurrences de "requiredSkillSets" et remplacez par "requiredSkills", puis recherchez les occurrences de "<cms:metadata-ref name="acquiredSkillSets" />" et remplacez par :

<cms:metadata-ref name="acquiredSkills">           
    <cms:metadata-ref name="skillSet"/>           
    <cms:metadata-ref name="skills">           
        <cms:metadata-ref name="skill"/>           
        <cms:metadata-ref name="acquisitionLevel"/>           
    </cms:metadata-ref>           
</cms:metadata-ref>         

Teaching potential

This migration only concerns Ametys ODF applications using plugin ODF -Pilotage.

A teaching discipline repeater (potentialsTeacher) has been added to the Component content type.
If you have overloaded the "default-edition" view of this content type, you must add the reference to this new repeater in the "Steering" tab:

<cms:fieldset role="tab">    
    <cms:label i18n="true">PLUGINS_ODF_PILOTAGE_FIELDSET</cms:label>    
    <cms:metadata-ref name="codCipApogee" />    
    <cms:metadata-ref name="codCmp" />    
    <cms:metadata-ref name="potentielsEnseignant">    
        <cms:metadata-ref name="discipline" />    
        <cms:metadata-ref name="potentiel" />    
    </cms:metadata-ref>    
</cms:fieldset>    

The Teaching Discipline field (TeachingDiscipline) has also been added to the ELPs "Piloting" tab.
If you have overloaded the ELPs "default-edition" view (race), you need to add the reference to this new field:

<cms:fieldset role="tab">    
    <cms:label i18n="true">PLUGINS_ODF_PILOTAGE_FIELDSET</cms:label>    
    <cms:metadata-ref name="disciplineEnseignement"/>    
    <cms:metadata-ref name="elpCode" />    
    <cms:metadata-ref name="etapePorteuse" />    
    ...    
</cms:fieldset>    

Enumeration of supporting stages

The etapePorteuse attribute of the ELP content type is no longer linked to a search model, but has its own enumerator.

In your overloads of the ELP content type, check whether the "etapePorteuse" attribute has been overloaded.
If so, replace:

<widget-params>      
    <param name="modelId">search-ui.XXXXX</param>      
</widget-params>      

by:

<enumeration>       
    <custom-enumerator class="org.ametys.plugins.odfpilotage.enumerators.StepHolderEnumerator"/>       
</enumeration>   

Please note that some data model modifications also involve data migration and graphics migration. Please refer to the relevant manuals.

Workflow

Reference table

In the reference table workflow file(reference-table.xml), add action 22 (modify action without EditContentFunction execution) to workflow state 3:

<step id="3" name="plugin.default-workflow:WORKFLOW_STATE_VALIDATED">                                  
    <actions>                                  
        <common-action id="2" />                                  
        <common-action id="22" />                                  
        <common-action id="220" />                                  
        <common-action id="222" />                                  
    </actions>                                  
</step>         

Global validation action

The global validation action is no longer a workflow action.
It is now available for all elements of the training model, whatever their status.
It can therefore be executed at any time. Only the lifecycle of non-validated elements will be modified.

In the workflow files for training courses (program.xml), courses (subprogram.xml), containers (container.xml), lists (courselist.xml) and ELP (course.xml), delete the declaration and references to action 900 (global validation).
These files are located in WEB-INF/param/workflows.

Dans le fichier plugins/default-odf-workflow/plugin.xml, supprimez toutes les occurrences de:
<menu-900-action>Ametys.plugins.odf.program.ProgramActions.globalValidate</menu-900-action>

Automatic invalidation of parent elements

When an element of the course model (course, container, list, ELP) is modified, the parent course is no longer invalidated (it no longer goes into draft).

When adding an element to the training model (new or by copy), only the direct parent element is automatically invalidated.

In the workflow files container.xml, subprogram.xml, courselist.xml and course.xml :

  • Delete all occurrences of the post-function org.ametys.odf.workflow.ChangeProgramStateFunction

Republishing action

The republish action (9001) is used to republish a course on a portal. Until now, it was only available if the course was in "Validated" status.

Since global validation is no longer a workflow action, the "republish" workflow action must be available from any state, provided the course has been validated at least once.

It is the validated version of the model elements that will be republished.

Dans le fichier de workflow WEB-INF/param/workflows/program.xml, recherchez l'action "9001".
Si elle existe, déplacez-là dans la section "<common-actions>" et ajoutez la condition de workflow suivante :

<condition type="avalon">              <arg name="role">org.ametys.odf.workflow.ODFContentPublishedCondition</arg>                 
</condition>         

Then for each state (step), refer to action 9001. Example:

<step id="1" name="plugin.default-odf-workflow:WORKFLOW_STATE_DRAFT">                      
    <actions>                          
        <!-- Edit Action -->                          
        <common-action id="2" />                          
        <common-action id="22" />                          
        ....                          
        <!-- Republish Action -->                          
        <common-action id="9001" />                      
    </actions>                 
</step>               

Importing archives

Pour que l'import des contenus d'une archive fonctionne, le workflow des contenus doit contenir l'action avec id=0.
Vérifiez que les fichiers de workflow se trouvant dans le répertoire WEB-INF/param/workflows contiennent bien cette action et si non, ajoutez-là dans la section <initial-actions> comme dans l'exemple ci-dessous :

<action id="0" name="plugin.default-odf-workflow:WORKFLOW_ACTION_CREATE">         
    <results>         
        <unconditional-result old-status=" " status=" " step="1" />         
    </results>         
</action>         

This action should be missing for files such as reference-table.xml, orgunit.xml and person.xml

If in doubt, compare your files with those of the ODF or ODFWeb template to apply the necessary modifications.
- ODF Web: https: //code.ametys.org/projects/ODF /repos/template-odfweb/browse/webapp/cms/WEB-INF/param/workflows
- ODF : https: //code.ametys.org/projects/ODF /repos/template-odf/browse/webapp/WEB-INF/param/workflows
Also compare your plugin "default-odf-workflow" with that of the template.

Other migrations

Changing the name of the Apogée feature

In the file WEB-INF/param/runtime.xml, replace

<feature>odf-sync/configuration.apogee</feature>                                       

by

<feature>odf-sync/odfsync.apogee</feature>                                       

Vous trouverez normalement cette ligne dans la section <exclude> si vous n'utilisez pas de synchro Apogée.

Apogée synchronization

The migrations in this chapter only concern ODF applications with Apogee synchro.

Apogée SCC settings

The Apogée source and administrative year, which were configuration parameters, become Apogée collection parameters.

In the configuration file $AMETYS_HOME/config/config .xml, you can delete the following lines:

<odf.apogee.jdbc.datasource>XXX</odf.apogee.jdbc.datasource>                                         
<odf.apogee.administrative.year>XXX</odf.apogee.administrative.year>                                         

Deleting these lines is not mandatory, but will avoid warnings in the application logs.

You must then reconfigure the 6 Apogee syncs to define these 2 old configuration parameters in each of them.

You can do it:

- or via the administration tool, by modifying Apogee synchros from the "Content synchronization" tool,

- or manually by modifying the file $AMETYS _HOME/config/synchronizable-collections .xml.

In this file, search for Apogee collections, i.e. collections linked to a model with the identifier prefix "org.ametys.plugins.odfsync.apogee.scc" and add the "datasourceId" and "year" parameters corresponding respectively to the old configuration parameters "odf.apogee.jdbc.datasource" and "odf.apogee.administrative.year".

For example:

<collection id="formations-apogee">                                        
  <label>Formations Apogée</label>                                        
  <!-- // autre -->                                        
  <model id="org.ametys.plugins.odfsync.apogee.scc.program">                                        
  <param name="datasourceId">SQL-jvnsnpln</param>                                        
  <param name="year">2019</param>                                        
  </model>                                        
</collection>           

Apogée synchronization operators

Apogee synchronization operators have been standardized, and operators specific to ELPs and containers have been removed.

Via the administration interface and from the "Content synchronization" tool, modify existing Apogee synchronizations for ELPs and containers, and choose the synchronization operator Conversion of Apogee data to Ametys.

If your application contains an overload of the JAVA org.ametys.plugins.odfsync.apogee.scc.operator.ApogeeSynchronizingContentOperatorHelper component, this overload may no longer be required or may need to be retrofitted.

Look for the component with "org.ametys.plugins.odfsync.apogee.scc.operator.ApogeeSynchronizingContentOperatorHelper" in the plugin.xml of your application :

  • if the class associated with this component is a Ametys class, you can remove this overload.
  • if the class associated with this component is not a Ametys class but a class specific to your application, it is necessary to adapt this class to identify what it brings and update the helper configuration by deleting the conversions

Apogee conversion files

If your application contains an overload of Apogee to Ametys conversion files, they must be renamed.
Their name must correspond to the exact name of the target reference table, in lower case and truncated with odf-enumeration. followed by _conversion.xml.

For example:

  • degrees_conversion.xml becomes degree_conversion. xml
  • educationTypes_conversion.xml becomes programtype_conversion. xml

These files are located in your application's WEB-INF/param/odf/apogee/code directory.

SCC overload

This chapter concerns only Apogée synchronization overloads, from version 4.3.11 onwards.

If you have overloaded the JAVA Apogée synchronization classes (classes inheriting from org.ametys.plugins.contentio.synchronize.SynchronizableContentsCollection), including the _search, make the following change:

Replace

if (!searchParams.containsKey("__count") && (searchParams.containsKey("apogeeSyncCode") || searchParams.containsKey("parentCode")))

by

if (!searchParams.containsKey("__count") && (searchParams.containsKey("apogeeSyncCode") || searchParams.containsKey("parentCode") || searchParams.containsKey("isGlobalSync")))

Mapping file and SCC query

This chapter concerns only Apogée synchronization overloads, from version 4.3.11 onwards.

If you have overloaded the Apogee query files in the WEB-INF/params/odf folder in your application :

Apogee-mapping file.xml

Replace all LIB_MEV occurrences with COD_MEV.

Make sure that the following line appears at the end:

{"metadata-ref":"mention","attribute":"COD_MEV","synchro":true}

apogee-requests file.xml

Replace all occurrences of LIB_MEV in the mention table with COD_MEV in the vdi table.

So the following join can normally be deleted too:

LEFT OUTER JOIN mention_vdi mention ON vdi.COD_MEV = mention.COD_MEV

Adding a right to mutualize an ELP

The actions for creating an ELP or adding an existing ELP have been separated into 2 separate buttons:

  • New ELP
  • Pooling an existing ELP

The "Mutualize an ELP" button is protected by its own "Mutualize an ELP" right (ODF_Rights_Course_Share)
You need to adapt your rights contexts to add this new right.

Popup on the ELPs of the training sheet

This migration only concerns applications using the ODF kernel charter.

On a training sheet, by default, in the "Program" table, clicking on an ELP opens a popup with some of the ELP's fields.
The fields available and displayed in this popup are those of the "structure" view (metadata-set).

For a correct display, in your WEB-INF/param/content-types/_override/org.ametys.plugins.odf.Content.course.xml, add an overload of the "structure" view as follows:

<cms:metadata-set name="structure" type="view" internal="true">   
    <cms:fieldset role="fieldset" name="benefits">   
    <cms:label i18n="false">benefits</cms:label>   
        <cms:metadata-ref name="level" />   
        <cms:metadata-ref name="ects"/>   
        <cms:metadata-ref name="orgUnit"/>   
        <cms:metadata-ref name="nbHours" />   
        <cms:metadata-ref name="teachingTerm" />   
    </cms:fieldset>   
    <cms:metadata-ref name="description" />   
</cms:metadata-set>   

You can choose other information to be displayed in the "benefits" area. Be careful, however, to limit this to a maximum of 5 items.

If you don't want to display popups on these links, but still want to access the ELP page directly from the table, a graphic overload is required (see graphic migration).

Back to top