Migrate Companion for Delivery version from 4.2.1 to 5.0.0

When upgrading to version 5.0.0, three modifications resulted in breaking changes:

  • The change of the groupId and artifactId to be consistent with the other products of the Companion suite
  • The modification of the Companion for Delivery packages to be consistent with the new groupId
  • The addition of the second level of the XSD in CSV / Excel files, previously implicit to allow support for attributes in these tags

Pom configuration

The first step is to update the pom configuration of your Companion for Delivery project

Update plugin companion-maven-plugin

In your pom.xml at the root of the project you should find somewhere the following tags:

<build>
    <plugins>
        <plugin>
            <groupId>fr.cantor.companion</groupId>
            <artifactId>companion-maven-plugin</artifactId>
            <version>4.2.1</version> <!-- This should be a variable in your project -->
            <extensions>true</extensions>
            ...
        </plugin>
    </plugins>
</build>



 
 
 





Modify the following information:

  • groupId: fr.cantor.companion -> fr.cantor.c4d
  • artifactId: companion-maven-plugin -> c4d-maven-plugin
  • version: 4.2.1 -> 5.0.0

Delete old documentation configuration

In your pom.xml at the root of the project you should find somewhere the following tags:

<build>
    <plugins>
        <plugin>
            <groupId>fr.cantor.c4d</groupId>
            <artifactId>c4d-maven-plugin</artifactId>
            <version>5.0.0</version> <!-- This should be a variable in your project -->
            <extensions>true</extensions>
            <configuration>
                <companion>
                    <documentation>
                        <url>${documentation.url}</url>
                        <password>${documentation.password}</password>
                        <username>${documentation.username}</username>
                        <settingsPath>documentation.properties</settingsPath>
                    </documentation>
                </companion>
            </configuration>
        </plugin>
    </plugins>
</build>









 
 
 
 
 
 





Remove the <documentation> tag and its contents

Update Companion for Delivery dependencies

If you use the following dependencies somewhere in your project, please update them as below.
Dependencies can appear in several places in your pom.xml files.

Note that fr.cantor.companion.ext has not been renamed, so no changes are required

companion-xml-processor

Old :

<dependency>
    <groupId>fr.cantor.companion</groupId>
    <artifactId>companion-xml-processor</artifactId>
    <version>4.2.1</version> <!-- This should be a variable in your project -->
</dependency>

New :

<dependency>
    <groupId>fr.cantor.c4d</groupId>
    <artifactId>c4d-xml-processor</artifactId>
    <version>5.0.0</version> <!-- This should be a variable in your project -->
</dependency>

companion-tests

Old :

<dependency>
    <groupId>fr.cantor.companion</groupId>
    <artifactId>companion-tests</artifactId>
    <version>4.2.1</version> <!-- This should be a variable in your project -->
    <scope>test</scope>
</dependency>

New :

<dependency>
    <groupId>fr.cantor.c4d</groupId>
    <artifactId>c4d-tests</artifactId>
    <version>5.0.0</version> <!-- This should be a variable in your project -->
    <scope>test</scope>
</dependency>

twirl-templates

Old :

<dependency>
    <groupId>fr.cantor.companion.templates</groupId>
    <artifactId>twirl-templates</artifactId>
    <version>1.1.2</version> <!-- Could be a variable in your project -->
</dependency>

New :

<dependency>
    <groupId>fr.cantor.c4d.templates</groupId>
    <artifactId>twirl-templates</artifactId>
    <version>2.0.0</version> <!-- Could be a variable in your project -->
</dependency>

Launch migration command

Your project must now be correctly configured to use Companion for Delivery version 5.0.0 and Companion Twirl Template version 2.0.0 if you use it

Companion for Delivery now offers a migration goal: c4d:migrate

You can run it, and you will find the result of the migration of each module in a migrations directory

WARNING

Be careful, if you run the migration tool several times you may get an inconsistent result !

Details of the automatic migration

Two actions are performed on your source files during migration

  • .companion.csv and .companion.xlsx files: Adding level 2 of the XSD -> may require a manual action
  • .companion.xml, .companion.template.xml and .java files: Modification of fr.cantor.companion imports to fr.cantor.c4d

Analysis of migration results

At the top of the migration file, the first line shows the number of files processed and the percentage of success.

If the percentage of success is not 100%, then look for the files for which the program encountered an error. For example :

Processed files: 2 (50,0% success)
<ABSOLUTE_PATH>\step-contexts\src\main\step\ContextList\Context.companion.csv:
 - [FAILURE] Sheet 'MAIN': Ambiguous relation between element: Context and candidates: ContextList, CrossContexts
<ABSOLUTE_PATH>\step-contexts\src\main\step\DimensionList\Dimension.companion.csv:
 - [SUCCESS] Sheet 'MAIN': Dimension -> DimensionList

Ambiguous relation

If you encounter this error it is because the program is not able to determine from the XSD which level 2 to add to your file.
Indeed, in some cases the same level 3 tag can be present under several level 2 tags.

To correct this problem, you need to manually edit your file with the correct level 2 element from the proposals.

No candidate found

If you encounter this error, it means that the program is not able to provide a level 2 element for your highest tag.

Either your file is malformed or it has already been migrated

Last Updated: