Developing Templates in the Cloud, 2024.12

Documentation

Template development guide

For distributed development of FirstSpirit projects Git and FS-CLI can be used. A Git-based workflow enables efficient collaboration with topic branches, synchronization and automated Bamboo plans. For more control during synchronization, FS CLI can be used to execute commands locally.

Distributed development of FirstSpirit projects

Example: distributed development of a FirstSpirit demo project using Git and FS-CLI.

Concept

The Git-based development process associates a FirstSpirit project with a Git repository, which contains all the project design elements, e.g. templates and technical media (JavaScript libraries, CSS files, etc.).

The Git repository tracks changes to features that make it easier to identify and resolve issues that may later arise.

Git topic branches enable multiple individual team members to work on different features or bug fixes simultaneously and in isolation from the main project or other developers. Each Git branch corresponds to a separate FirstSpirit branch project in which the development and testing processes run. When work is complete, the branch project merges with the main project without any interferences.

ExternalSync allows a synchronization between Git branches and FirstSpirit projects; ContentTransport enables you to fill new branch projects with sample content. This ensures a better development experience as well as the possibility to transport content between environments.

Overall, this process improves the efficiency and collaboration within the team as well as the codebase quality.

Distributed Template Development

The following Bamboo plans support the template development and synchronization:

Sync › FirstSpirit Project → Git
Export of a FirstSpirit project into a Git branch. A new commit is created in the branch.
Sync › Git → FirstSpirit Project
Content import from a Git branch into a FirstSpirit branch project using ExternalSync.
Auto Create FirstSpirit Branch Project
When a new topic branch is pushed to Git repository, a new branch project automatically creates.
Auto Cleanup FirstSpirit Branch Projects
Deactivation and deletion of FirstSpirit projects that are no longer associated with any Git branch because the branch was deleted and the project is no longer needed. Automatic execution with an option for manual triggering. A project is deactivated if no Git branch is associated with it and subsequently deleted after 30 days of inactivity.

Information on the FirstSpirit project in Template Development for ContentCreator:

most recent Git commit
last synchonization with Git
hyperlinks to applied Bamboo plans

Git setup

Step	Additional information
Installing Git	Use of version control systems (VCS)
Git configuration	Configuring external components

Setting up a project using a Bamboo plan

Initial transfer to an empty Git repository

The following steps are optional:

Open the main project in SiteArchitect and create ContentTransport features for the example content. The example content is automatically installs in topic branch projects by the "Auto Create FirstSpirit Branch Project" Bamboo plan.
Documentation: Creating features
Make sure you are in the main development Git branch.
Edit the fs-project.yaml file in the repository root to edit the repository's project configuration.

version: 1
mainProject:
  name: "Name of your FirstSpirit project which needs to be exported"
  gitBranchName: "main"
externalSync:
  exportElements: "projectproperty:ALL templatestore"
features:
  defaultInstallationOptions:
    onFailure: FAIL
    force: false
  testContent:
    - name: Example Content
      options:
        useLatestRevision: true
        useRelease: true
        onFailure: WARN
        force: true
    - name: More example content for dev
      options:
        useLatestRevision: true
    - name: Picture Gallery for Dev
    - name: Videos for Dev
    - name: Extras for Dev

Explanation

Elements in the Git repository

The exportElements property references the content that is exported by FS-CLI into the Git repository.

The FS-CLI documentation is part of the FS-CLI downloads. It can be found in the "/docs/" directory. Alternatively, execute FS-CLI with the heip command to view the documentation:
fs-cli help export

All of the project's design related elements should be contained in exportElements. This can include templates, (technical) media, and data sources with technical content. The actual content depends on the project's composition and can differ for each project. In some cases global settings need to be exported as well.

In the project's structure, design elemts and content should be clearly differentiated. This makes it easier to define the number of elements to be exported and to keep them synchronized with the ContentTransport features.

Project settings (users, groups, etc.) also need to be exported. To do this, add projectproperty:ALL to the parameters. This command is used to export all project settings into the Git repository. If you need more fine-grained control over the project settings that shall be exported, you can define them one by one:

projectproperty:USERS projectproperty:GROUPS etc.

Refer to the FS-CLI documentation for a list of all project settings that can be exported. However, in most cases, we recommend to export all settings.

Full example of the exportElements property:

projectproperty:ALL templatestore contentstore entities:translation entities:translationstudio_list entities:translationstudio_requests globalstore mediafolder:layout mediafolder:files mediafolder:logos

ContentTransport features

"Example Content", "More example content for dev", "Picture Gallery for Dev", "Videos for Dev", "Extras for Dev" are names of feature packages in the main FirstSpirit project that should be installed in any topic branch project.

If you don't wish to install any features in your branch projects, then you don't have to define the "features" property.

Commit and push the changes:

git add fs-project.yaml
git commit -m "exporting FS project to git"
git push -u origin main

Start the Sync › FirstSpirit Project → Git Bamboo plan for the "main"-Git branch. After it has run successfully, you should be able to see a new Git commit pushed onto the "main"-branch. Don't forget to pull those changes using the git pull command.

Ensure that the newly exported project contains everything you would need and expect. The easiest way to do this is to create an additional Git topic branch from the freshly pushed changes:

git checkout -b feat-check-export-is-ok
git push -u origin feat-check-export-is-ok

After that the Auto Create FirstSpirit Branch Project Bamboo plan should start automatically for the newly pushed Git branch feat-check-export-is-ok.

The plan may take several minutes to run through. When the plan finishes, a new project should be found on the FirstSpirit server. If your main project is called "My FS Project", then the new project for the feat-check-export-is-ok Git branch should be called "My FS Project (feat-check-export-is-ok)".

Open the newly created project in ContentCreator or in SiteArchitect and ensure that it is complete, e.g. necessary CSS styles are applied and the expected content is existent, such as icons and feature content.

In case of missing content:

Switch back to the "main"-branch in Git.
Adjust the exportElements property in the fs-project.yaml file accordingly.
Commit and push the changes .
Trigger the Sync › FirstSpirit Project → Git Bamboo plan for the "main"-branch again and wait until finished.
Pull the changes again via git pull.
Switch back to the feat-check-export-is-ok-branch and update it via git merge --ff-only main. Since only the "main"-branch has been changed, the merging should be finished quickly.
Push the updated feat-check-export-is-ok-branch.
Start the corresponding Sync › Git → FirstSpirit Project Bamboo plan and wait until finished.
Check the update project "My FS Project (feat-check-export-is-ok)".

If the project including the Git exported content is correctly created, you may delete the feat-check-export-is-ok branch:

git checkout main
git push --delete origin feat-check-export-is-ok
git branch -D feat-check-export-is-ok

The corresponding topic branch FirstSpirit project will be deactivated automatically by the Auto Cleanup FirstSpirit Branch Projects Bamboo plan and will be deleted after 30 days of inactivity by the same plan.

Use-case: Implementing a requirement (#42)

Requirements

The "main"-branch in Git is active.
Your project is already exported to the "main"-branch.

Implementation

Create a new Git topic branch, e.g. feat42, and push it using git checkout -b feat42 && git push -u origin feat42
→ The Auto Create FirstSpirit Branch Project Bamboo plan for the pushed branch automatically creates a new FirstSpirit project branch with the postfix "(feat42)".
Start the Sync › FirstSpirit Project → Git Bamboo plan for the pushed branch.
→ Changes potentially introduced by the FS-CLI external sync command, i.e. changes in groups and workflows, are exported.
Pull the changes via git pull --ff-only.
Open the branch project in ContentCreator or in SiteArchitect and implement the requirements. Then start the Sync › FirstSpirit Project → Git Bamboo plan again
The implemented requirements are exported to Git branch feat42.
Pull the changes.

Repeat the above steps to add further requirements.

After development, create a pull request from your topic branch feat42 to the "main"-branch.
Your colleague may review the created pull request and the corresponding branch FirstSpirit project.
After successful review, merge the pull request into the "main"-branch.
Run the Sync › Git → FirstSpirit Project Bamboo plan for the "main"-branch after the merge.
→ The main FirstSpirit project is updated.
After the requirement has been implemented and the changes have been integrated into the "main"-branch and into the main project, the topic branch feat42 may be deleted:
git branch -d feat42
git push --delete origin feat42
The branch FirstSpirit project is automatically cleaned up by the Auto Cleanup FirstSpirit Branch Projects Bamboo plan.

Use-case: Dealing with conflicts (#23)

Requirements

The topic-branch "main" is active in Git.
The project has already been exported into the topic-branch "main".

Implementation

Create a new Git topic branch, e.g. feat23, and push it:
git checkout -b feat23 && git push -u origin feat23
Create the topic branch feat42 in Git:
git checkout -b feat42 && git push -u origin feat42
In this topic-branch changes will be made that are in conflict with topic-branch feat23.
Implement the steps described in the previous part.
Make some changes to e.g. some template.
Merge the changes made into the "main"-branch.
You can now delete the topic branch feat42.
Switch back to the feat23 branch via git checkout feat23. The Auto Create FirstSpirit Branch Project Bamboo plan automatically creates a new FirstSpirit projet branch for the topic-branch feat23.
Start the Sync › FirstSpirit Project → Git Bamboo plan for feat23 as well. Because the changes to the template were made in a separate branch feat42, they are not implemented in the currently active branch feat23.
In topic-branch feat23, make changes that are in conflict with the changes made in feat42. For example, change the same line in the same template.
Export the changes using the Sync › FirstSpirit Project → Git Bamboo plan into the branch feat23
Don't forget to pull them via git pull --ff-only.
Create a pull request from your topic branch feat23 into "main". The conflict will be displayed.
Resolve the Git conflict when merging "main" into your topic branch feat23 e.g. using your favorite merge and compare tool:
git fetch origin
git merge origin/main
All conflicts are now resolved.
Push the updated feat23 branch: git push origin feat23.
Execute the Sync › Git → FirstSpirit Project Bamboo plan for feat23 again in order to update the topic-branch project feat23.
Check to ensure that the updated project is correct (no missing CSS styles, all icons are in place, no invalid templates etc.).
Compare your now conflict-free pull request and the corresponding topic branch project.
Integrate the pull request into the topic-branch feat23.
Delete the topic branch feat23 :
git branch -d feat23
git push --delete origin feat23
Execute the Sync › Git → FirstSpirit Project Bamboo plan for the topic-branch "main" to update the main project.
The FirstSpirit projects for feat42 and feat23 will be automatically cleaned up by the Auto Cleanup FirstSpirit Branch Projects Bamboo plan.

Transport design between Dev, QA, and Prod environments

If there are changes to the website design or new features implemented in the Dev environment, these changes are first transferred to the QA and then to the Prod environment. The ContentTransport functionality is used for this purpose.

The process is supported by three Bamboo plans:

Transport › Dev → QA
Website design transport between the Dev and QA environment.
Transport › QA → Prod
Website design transport between the QA and Prod environment.
Transport › Prod → Prod
Website design transport between different projects in the Prod environment.
Use case: Several sub-projects for different countries with a centrally controlled website design

Preparation

Create a new ContentTransport-Feature in SiteArchitect.
Name the feature, e.g. "Website Design".
Add all the design elements of the project to the feature.

In practice, the contents of this feature should exactly match the elements listed in the exportElements parameter in the fs-project.yaml file. The feature must include all required dependencies. An exception to this are the project settings: users and groups usually already exist in the target instance and don't need to be transported separately. Missing optional dependencies, like preview pages for templates, are unproblematic.

If new store elements are added to or removed from the set of website design elements, make sure to adjust the ContentTransport package accordingly. The ContentTransport package and the exportElements parameter in the fs-project.yaml must always be kept in sync.

Save the feature.
Define the design packages in the fs-project.yaml.

Example definition:

version: 1
mainProject:
  name: "Name of your FirstSpirit project"
  gitBranchName: main
externalSync:
  exportElements: projectproperty:ALL templatestore
features:
  defaultInstallationOptions:
    onFailure: FAIL
    force: false
  testContent:
    - name: Example Content
  designForQa:
    - source:
        features:
        - name: Website Design
  designForProd:
    - source:
        features:
          - name: Website Design
  designForSubprojects:
    - source:
        features:
          - name: Website Design
      target:
        projects:
          - "Name of your FirstSpirit EN country project"
          - "Name of your FirstSpirit DE country project"
          - etc...

Use the name of the feature created in SiteArchitect,
In the above example: "Website Design".

The keys "designForQa", "designForProd" and "designForSubprojects" are used in the Bamboo plans mentioned above:
The names are used to determine which content is transferred to the next environment.
If features don't need to be transferred to a specific environment, the corresponding YAML key can be omitted.

The Bamboo plans use the following properties:

Bamboo Plan	Key in fs-project.yaml
Transport › Dev → QA	designForQa
Transport › QA → Prod	designForProd
Transport › Prod → Prod	designForSubprojects

It is not possible to skip environments.

ContentTransport

Before synchronizing content, check the associated ContentTransport package in SiteArchitect in the Dev environment to ensure that the content is up-to-date.
Adjust the package if elements or dependencies have changed.
Select the revision you want to transport and save the feature.
Execute one of the plans:
Transport › Dev → QA
Transport › QA → Prod
Transport › Prod → Prod
The transport is now started. This process can take several minutes.
After completing the transport to the target project, check whether the transfer was successful.

Standard names for QA- and Prod- projects

If only the name of the Dev-project is defined in the YAML file, the same name is used for both the QA- and the Prod-project during feature transport.

Example

version: 1
mainProject:
  name: www.my-project.com [DEV]
  gitBranchName: main
features:
  designForQa:
    - source:
        features:
          - name: from DEV to QA with defaults

    - source:
        features:
          - name: from DEV to QA with override for source project
        project: www.my-previous-project-with-useful-features-in-it.com [DEV]

    - source:
        features:
          - name: from DEV to QA with override for target projects
      target:
        projects:
          - www.my-other-project-1.com [QA]
          - www.my-other-project-2.com [QA]
          - www.my-other-project-3.com [QA]

Explanation

Transfer of from DEV to QA with defaults
from Dev environment
www.my-project.com [DEV]
to QA environment
www.my-project.com [DEV]

The default source or target project can be overwritten for individual features in the YAML file:

Transfer from DEV to QA with override for source project
from Dev environment
www.my-previous-project-with-useful-features-in-it.com [DEV]
to QA environment
www.my-project.com [DEV]
Transfer from DEV to QA with override for target projects
from Dev environment
www.my-project.com [DEV]
to QA environment
www.my-other-project-1.com [QA]
www.my-other-project-2.com [QA]
www.my-other-project-3.com [QA]

Often, however, the project names in Dev, QA, and Prod are different.
If the project names for QA and Prod are defined in the YAML file, they are used for both the target and the source project.

Example

version: 1

mainProject:
  name: www.my-project.com [DEV]
  gitBranchName: main
  qa: www.my-project.com [QA]
  prod: www.my-project.com [PROD]

features:
  designForQa:
    - source:
        features:
          - name: from DEV to QA with defaults

  designForProd:
    - source:
        features:
          - name: from QA to PROD with defaults

  designForSubprojects:
    - source:
        features:
          - name: from PROD to PROD with defaults
      target:
        projects:
          - www.my-other-project-1.com [PROD]
          - www.my-other-project-2.com [PROD]
          - www.my-other-project-3.com [PROD]

Explanation

Use of www.my-project.com [QA]
as default target project in designForQa
and
as default source project in designForProd
Use of www.my-project.com [PROD]
as default target project in designForProd
and
as default source project in designForSubprojects
Transfer of from DEV to QA with defaults
from Dev environment
www.my-project.com [DEV]
to QA environment
www.my-project.com [QA]
Transfer of from QA to PROD with defaults
from QA environment
www.my-project.com [QA]
to Prod environment
www.my-project.com [PROD]
Transfer of from PROD to PROD with defaults
from Prod environment
www.my-project.com [PROD]
to Prod environment
www.my-other-project-1.com [PROD]
www.my-other-project-2.com [PROD]
www.my-other-project-3.com [PROD]

Distributed development of FirstSpirit project: local usage of FS-CLI

FS-CLI can be used for local execution of commands, e.g. for better control over the synchronization steps.

FS-CLI setup

Step	Documentation
Install FS-CLI	The "FSDevTools" command line tool
Define environment variables for FS-CLI	See example values below
Add the executable directory of the FS-CLI (fs-cli/bin) to your system’s PATH variable so that you can run the FS-CLI from the project directory
Test the FS-CLI connection to the FirstSpirit server	Execute `fs-cli test` command

Example values for environment variables for FS-CLI

Variable	Example value	Description
fshost	ecs-dev-caas-eu-central-1-1.e-spirit.hosting	FS server host
fsport	443	FS server port
fsmode	HTTPS	connection mode
fsuser	username@my-company.com	username
fspwd	Passw0rd!	password

Synchronization: project with Git

The FS-CLI external sync export command is used by Bamboo plans for syncing an existing FirstSpirit project into a filesystem. The project is versioned by Git and can be saved in Git.

Consult the FirstSpirit documentation for more information on the export command.

Example:

fs-cli -e --syncDir fs-project --project "My FS Project" export --permissionMode ALL -- projectproperty:ALL templatestore

Synchronization: Git with project

The FS-CLI external sync import command is used by Bamboo plans for syncing content versioned by Git into a FirstSpirit project on the server. If the project does not yet exist, it will be created by the command.

In the example below the --layerMapping parameter which takes the value "*:FirstSpiritDBA" which is specific to the Cloud installation of FirstSpirit.

For more information on the import command and associated parameters consult the FirstSpirit documentation.

Example:

fs-cli -e --syncDir fs-project --project "Mein FS-Projekt (my-feat-branch)" import --updateExistingPermissions --layerMapping "*:FirstSpiritDBA"

Install features using FS-CLI

Obtain the feature ZIP file from the main project using the following command:

fs-cli -e --project "My FS Project" feature download --name "My Feature" --file feature.zip --useLatestRevision --useRelease false

Install the downloaded feature in a FirstSpirit project branch:

fs-cli -e --project "My FS Project (my-feat-branch)" feature install --file feature.zip --layerMapping "*:FirstSpiritDBA"

Further information on the FSDevTools can be found in the FirstSpirit documentation.

Template development guide

Distributed development of FirstSpirit projects

Concept

Git setup

Setting up a project using a Bamboo plan

Initial transfer to an empty Git repository

Explanation

Elements in the Git repository

ContentTransport features

Use-case: Implementing a requirement (#42)

Requirements

Implementation

Use-case: Dealing with conflicts (#23)

Requirements

Implementation

Transport design between Dev, QA, and Prod environments

Preparation

ContentTransport

Standard names for QA- and Prod- projects

Example

Explanation

Example

Explanation

Distributed development of FirstSpirit project: local usage of FS-CLI

FS-CLI setup

Synchronization: project with Git

Synchronization: Git with project

Install features using FS-CLI

Table of Contents