Linked Project Spaces Walkthrough
With Linked Project Spaces, an “upstream” project space is identified where all original development work takes place, including the source application and data models. By linking project spaces, you can push this to downstream project spaces where users access this released content.
Getting Started
The first step in using linked project spaces is establishing relationships between an upstream project space and one or many downstream project spaces. Please see below for understanding what these terms mean.
Terminology
An upstream project space is the development environment where the master applications and data models are created. These upstream project spaces are linked to downstream project spaces. When the development work in the upstream project space is complete, the content is transferred or pushed to downstream project spaces for release.
A downstream project space is where the final or released versions of master applications and data models are deployed, such as in testing or production environments. The downstream project space is linked to the upstream project space. This allows users to sync updates from the upstream project space as needed.
The content refers to everything that is pushed or synced from project spaces. The content that is pushed from the upstream project space to the downstream project spaces is linked, and is referred to as linked configurations. In the context of Linked Configurations, a Match refers to a situation where there are unlinked content items in both the upstream and downstream project spaces that share the same name, ID, or Label. Read more about matches at https://dimagi.atlassian.net/wiki/x/X5XKfw.
Data models refer to Individual components that make up the content. e.g., lookup tables, web user roles, etc. Read more at https://dimagi.atlassian.net/wiki/x/GjHKfw and https://dimagi.atlassian.net/wiki/x/JDHKfw.
Linking between different cloud environments or an on-premise environment?
If you are linking between different cloud environments or from a cloud to an on-premise environment, you must email support@dimagi.com with the details. Our Support Team must perform steps 1 and 2 (below) with you.
To link Project Spaces with MRM, the user needs the Multi-Environment Release Management permission added to their role.
Initial Setup
Upstream Project Space
If you link project spaces for the first time, you can do that from the Linked Projects page under Project Settings. Since this will be your first link, you should start from within the project space you intend to set as upstream, meaning the project space you want the content to originate from.
Navigate to Linked Projects Spaces from Project Settings.
Select Link Downstream Project Spaces. Next, choose a project space from the drop-down menu. This will be the project space that you want to push content to.
The linked project space will display on the page.
You can link multiple downstream project spaces to a single upstream project space.
With MRM, you can only push linked configurations to one downstream project at a time, even if your upstream project space is linked to multiple downstream project spaces.
With ERM, you can push linked configurations to multiple downstream project spaces simultaneously.
Unlinking project spaces can only be done from the upstream project space; click Remove Link next to the name of the downstream project space.
Downstream Project Space
You will see this page when you navigate to the Linked Project Spaces page in the downstream project space you created.
Here you have the option to
1. Navigate to the linked upstream project space.
2. Link downstream project spaces from the current project space (thus making it an upstream project space).
You need to link applications individually from an upstream project space to a downstream project space before you can push any content.
Considerations
Here are some considerations to know before creating project links.
The project link must always be created from the upstream project space.
You must have the MRM/ERM permission added to your role.
With ERM, only projects under the same enterprise account can be linked together.
Push content from the upstream project space
1. In the Upstream Project Space, navigate to Linked Project Spaces on the Project Settings page.
The MRM Menu UI on the Project Settings page:
The ERM Menu UI on the Project Settings page:
2. Click on the Push Content tab
3. Select the applications and other content you want to push to downstream project spaces. You also have the option to search for content and projects spaces.
4. Select the downstream project space to which you want to push the content.
MRM will only allow you to select one project space.
ERM will allow you to select multiple project spaces.
5. When pushing an application, by default, the latest released version of the selected application will be pushed to the selected downstream project spaces without releasing the application. This pushed application can then be manually released from the downstream project space.
If you want to release the pushed application in the downstream project space automatically, check the Create and release new build for the apps box. This is useful if you want to control the end-to-end process of application building, pushing, and releasing from one upstream project space.
6. Click Push Content.
7. A banner will show that the application push is in process.
8. You will receive an email confirming that the process was successful.
Content Matches
Matches may arise when pushing content from the upstream project space to the downstream project space in CommCare due to identical data model names, IDs, or labels. The data models are not linked configurations yet. Users have two options when pushing content:
a. Push or
b. Push & Overwrite Matches.
If the Push option is chosen, the system checks for matches and prompts the user to resolve them manually by either renaming or removing the downstream content. If the Push & Overwrite Matches option is chosen, all content in the downstream project space with matching data model names, IDs, or labels will be overwritten without notification. They are then considered linked configurations.
Push Content
If you attempt to push content from an upstream project space to a downstream project space and there is a match, you will receive an email notification that an error occurred. See the use case below.
In this use case, we have lookup tables in the upstream project space and the downstream project space with the same ID, but they are not linked configurations.
A lookup table with the Table ID LPS exists in the downstream project space.
A lookup table with the same Table ID exists in the upstream project space. You attempt to push the lookup table from the upstream project space to the downstream project space.
You receive an email notification informing you of the match and suggesting that you remove the lookup table before you attempt to push content again.
Push & Overwrite Matches
Instead of clicking Push, you select Push & Overwrite Matches.
A warning message informs you that you are about to overwrite content in the downstream project space.
You proceed. You receive an email notification that the release is successful.
The lookup table is changed into a linked configuration. The icon below indicates that data models are linked configurations. Read more at .
Supported Content Matches
Data Model | Sync type |
|---|---|
Applications | Sync individually |
Web User Roles | Sync as a group |
Custom User Data Fields | Sync as a group |
Global Lookup Tables | Sync individually |
Auto Case Update Rules | Sync individually |
Custom Location Data Fields | Sync as a group |
Key Words | Sync as a group |
Reports | Sync individually |
Enabled Feature Previews | Sync individually |
Content Match Troubleshooting
Matches can occur when pushing content from an upstream project space to a downstream project space if there is content with the same name, ID, or label in both spaces (see the table below to elaborate). In this case, syncing between project spaces won't be successful. When you try to push from the upstream project space, you will receive an email informing you of the match, and when you try to sync content from the upstream project space, you will receive a warning message in the downstream project space. To resolve these matches, you have four options:
Rename the data model in either the upstream project space or the downstream project space.
Remove the existing data model in the downstream project space.
Select the Push & Overwrite Matches option when you push content from the upstream project space.
Select the Sync & Overwrite Matches option when you sync content from the downstream project space.
Content type | Match between upstream and downstream content: |
|---|---|
Default Web User Role (e.g., App Builder) | When the two roles have the same Role Name but do not have the same permissions settings. |
Custom Web User Role | When the two roles have the same name, the Role Name label. |
Lookup Tables | When the two roles have the same Table ID. |
Custom User Data | When the two have the same User Property label. |
Case Update Rules | The two rules have the same Name. |
Custom Location Data | When the two have the same Location Property label. |
Keywords | When the two have the same Keyword label |
Sync content from downstream project spaces
Updates can be "synced" by the downstream project space from the upstream project space.
Navigate to a downstream project space from the Manage Downstream Project Spaces page in the upstream project space.
OR, navigate to Project Settings in the downstream project space. Click on Linked Project Spaces in the sidebar.
You will be directed to a dashboard that shows all linked applications and the additional content available to be pulled. You also have the option to search for content and applications.
Content Matches
When syncing content from the downstream project space of the upstream project space in CommCare, matches may arise due to identical data model names, IDs, or labels. The data models are not linked configurations yet. Users have two options when pushing content:
a. Sync or
b. Sync & Overwrite Matches.
If the Sync option is chosen, the system checks for matches and prompts the user to resolve them manually by either renaming or removing the downstream content. If the Sync & Overwrite Matches option is chosen, all content in the downstream project space with matching names, IDs, or labels will be overwritten without notification.
Sync
1). Select the content to pull and click Sync & Overwrite.
2). You will receive an error if there is matching content,i.e., unliked data models with the same names, IDs, or labels. You must manually remove or rename the data model to resolve the match.
Sync & Overwrite Matches
1. Select the content to sync and click Sync & Overwrite Matches.
2. A warning message will display. Click Sync & Overwrite if you want to overwrite the data model. After overwriting data, the data models will be linked configurations.
3. You are notified that the content sync is successful.
You can sync the latest version of an application in the upstream project space from the linked application in the downstream project space.
4. Under Manage Linked Project Space, click Go to update page.
5. You will be directed to the application settings page in the downstream project space. Click on Update. (Note: you can only sync down app versions marked as released in the upstream space.)
6. You will see the successful message.
7. You can check the box if you want an email notification. This is recommended for larger application.
Managing Linked Project Spaces
Link an Application to a Project Space
In the upstream project space, navigate to the applications page.
Navigate to the application settings.
Select the Actions tab.
Select the downstream project space you want to link the application to.
Check the Copy as Linked Application box. This will create an application that can be updated when content is pushed or pulled with the Linked Project Spaces feature.
6. When you navigate to the downstream project space, you will see the linked application.
7. You will see the application in the Linked Content section of the Linked Project Spaces page in the downstream project space.
Linked Project Space History gives a historical report for each time content is synced. It is accessible from both the upstream and downstream project space.
Navigate to Project Settings, and click Linked Project Space History in the sidebar menu.
Select the content to see the history.
Click Apply.
4. We have selected All in the content field, but you can customize your report by selecting any content in the dropdown menu.
5. Your report will display.
6. You can hide the Report Filters section at the top of the report by clicking Hide Filter Options.
7. You can save your report.
8. Name the report and give a description.
9. The saved report will appear in Favorites.
Unlinking project spaces
Unlinking project spaces can only be done from the upstream project space; click Remove Link next to the name of the downstream project space.
When you unlink project spaces, you remove the link between two project spaces. Currently, clicking the "remove link" button only marks the link entry as deleted in the project space link table without taking further action. This is because some data models in the system do not have a "upstream_id" field to track linked data. However, unlinking project spaces does not affect data models that have upstream ids.
To address the issue of preserving linked data for built-in roles, an exception will be made to unlink roles. This is because preserving linked data for built-in roles can cause conflicts when a second upstream project space tries to overwrite them. This approach balances the need to preserve linked data while addressing the specific pain point with built-in roles. Overall, the current behavior of preserving linked data will be maintained, as it is most acceptable and allows for rollbacks in case of mistakenly unlinking a project space.