Documentation
API
Q&A
Read
AnnouncementsArticlesWebsite tips
Learn
Getting StartedManagerMaestroAnalyticsExchangeWorkspaces
Resources
VideosDownloadsExchange PackagesRelease Notes
Ideas
Contact
Platform
Manager
Maestro
Exchange
Workspaces
Analytics
Springboard

Migrate to a SCM Project

   MaestroThe UI design product.  |   Form BuilderPlatform Developer  |   17.10 This feature was updated in 17.10.

Journey Maestro allows you to create SCM projects so you can use your favorite version control tools to branch project's source code. If you have a Maestro Standard project, once you are ready use Continuous Integration (CI)Continuous Integration (CI) is a development practice that requires developers to integrate code into a shared repository several times a day. Each check-in is then verified by an automated build, allowing teams to detect problems early. practices on Maestro code base, which consists of templates, forms, components and libraries, you can convert it to the Maestro SCM Project type.

Note

It also works in the opposite direction - if you have a Maestro SCM project, you can migrate it to the Standard project type as the project type doesn't affect the content of forms.

Migration Challenges

The main problem here is that the SCM project doesn't support multiple versions of any asset types it contains. There must be only a single version number of each form, component, library, and template in the project. It's assumed that the GIT branch it was pulled from identifies what version of the asset this is (or will be deployed as).

Due to the above, we are hitting a big problem in the migration to SCM projects. Generally, there would always be multiple versions of any of the assets in the legacy maestro projects. That's just the way we used to do it. Since the SCM project can have only one version, we need to pick the initial one which will make it to GIT as the first one at the migration time. Picking the right version number of any of the assets is not as of an issue as making sure we pick and migrate only that one while removing (or skipping) all the other ones during the migration process.

Just imagine we are migrating a project with 10 forms where each of them has 30+ versions (same for templates, components, libraries). When creating the SCM project only the most updated version needs to be migrated.

The restriction of a single version only takes us to the next challenge: a new folder structure of the SCM projects. The folder structure of a legacy project downloaded via maestro UI or SCM is different to the folder structure of the scm project type. The version folders were removed decreasing the depth of the folder structure by 1.

Migration Strategies

There are several ways to migrate an existing Maestro standard project to a SCM one. Let's look at them in details.

Recreate the original project

As the heading suggest this approach recommends to create an empty SCM project where all necessary assets from the original one will be manually copied to. The coping is done via Maestro dashboard export and import of each asset one by one.

Pros
  • Great opportunity to clean up the project by skipping any litter
  • A good opportunity to review the project structure, dependencies between assets, such as forms, components, libraries, and refactor them if possible
Cons
  • Too lengthy - can time too much time
  • Error prone - easy to miss or copy wrong assets

Converting a legacy project to the SCM project type

If you chose to convert an existing legacy project to the SCM project type as it is a few steps must be executed manually. The steps are listed below:

  1. Pick asset's current versions:
    • remove or skip any outdated asset versions and pick only the current one you wish to push into the GIT master branch.
    • this would likely be the latest or highest version of your asset.
  2. Delete remaining asset versions. It must be done on forms, components, templates, libraries.
  3. Migrate asset's content. Copy all asset current version's content into the asset's root folder. For example, if you picked the version 1.0.0 as the current one: forms/cc-application/1.0.0/* to forms/cc-application/*.
  4. Update asset's lib-manifest.json. remove the delete version numbers from the designVersions node.
  5. Update the asset's form-manifest.json.
  6. Validate. Test library associations. Make sure the SCM project has the same libraries associated as the legacy (original) project. Note that the project version libraries will be on the version 1.0.0 though.

Next, learn how to use Maestro SCM to implement a Git Feature Branch workflow.