When the user runs the WhereScape GIT Enablement Pack, this will start the process of connecting to GIT and building the WhereScape 3D and RED repositories.

This should be done at the following times: 

1. When connecting to a new GIT repository. 
2. When connecting to an existing GIT repository for the first time (on a Developer machine). 
3. When refreshing a Personal Access Token to an existing GIT repository. 
4. When rebuilding a corrupted Developer machine's GIT repository. 

When the process is launched, it will prompt the user for the following information:

• Select the repository types: Select the product(s) you want to utilize from the check buttons, choosing RED, 3D or both. 
• Environment Type: Developer Machine or Deployment Machine to be selected from the dropdown menu 
• Environment Tag: One letter can be entered here to provide a description for what the environment is used for, For example ‘d’ for development, or ‘t’ for testing. This will be included in the Repository name. 
• On Pull Action: Drop Schema or Drop Database to be selected from the dropdown menu. 
• GIT URL 
• GIT Organization: The organization name used within GIT. 
• GIT Repository: The GIT Repository name to connect to. 
• Username: The user's Username to be used on the build.  
• Personal Access Token: The user's Personal Access Token. 
• Local GIT Repository: The location of the GIT repository created locally on the machine/virtual machine will be displayed (read-only). 
• Is this an initial Build? Select if this process starts an Initial Build. 
• RED Repository Server and Port: Add the RED PostgreSQL Server and port. 
• RED Repository Database Name: The repository database name will be calculated based on the information provided – this is read-only. This can have a max character length of 63 characters. If you would like to change the way this is configured, please consult section 'Changing the Repository Database Name'. 
• RED Repository Username and Password: Add the RED Username and Password. 
• RED Generate Files: Use the check buttons to select whether you would like to generate DDL, DML and/or JSON files. 
• RED Repository Backup: If Initial Build is set to ‘Yes’ the user will have the opportunity to select a backup file to use as a copy for their repository. 
  

  Important

  The backup files will need to be in SQL, BAK or a Repository files format. 
  These files must be created using pg_dump, and the PostgreSQL version used for the backup must match the version of the target repository.

• 3D Repository Server: Add the 3D PostgreSQL Server and port.

• 3D Repository Database Name: The repository database name will be calculated based on the information provided – this is read-only. This can have a max character length of 63 characters. If you would like to change the way this is configured, please consult section 'Changing the Repository Database Name'.

• 3D Repository Username and Password: Add the 3D Username and Password.

• If Initial Build is set to ‘Yes’ the user will have the opportunity to select a backup file to use as a copy for your repository. 
  

  Important

  The backup files will need to be in SQL, BAK or a Repository files format.  
  These files must be created using pg_dump, and the PostgreSQL version used for the backup must match the version of the target repository.

  

• Once the form is created click on 'OK'. If there are any issues with connecting to the GIT repository, the user will receive an error message.

• The local GIT directory will now be created.

• The user credentials for WhereScape RED and 3D repositories are created:
  • These are stored locally at this location: `%USERPROFILE%\WhereScape\GIT`. 
  • This file stores the user's credentials and configuration details which are required for the workflows to run correctly. 
    

    Important

    Each GIT Repository will have its own profile file. If it is deleted or modified incorrectly, the workflows will stop working.

• The user will be prompted to select a branch from the remote GIT repository.
  
   

• This action refreshes the local GIT repository with updates from the specified remote branch.

• WhereScape 3D and/or RED is rebuilt using the files within the local GIT repository. 

If the user requires to connect to a new or different GIT repository, these steps should be repeated using the new settings.

Changing the Repository Database Name

When completing the WhereScape GIT Enablement Pack form, the RED and 3D Repository Database names are read-only and are created based on the user information provided elsewhere on the form. However, this can be changed via the config file if required. 

1. The config is held in a JSON file named 'config.json' at the following location: 
    %USERPROFILE%\WhereScape\GIT 
2. The repository database names are calculated within their resepective RED or 3D sections under the 'Repository Database name prefix and suffix' keys. These values can be amended to change the way that the repository database names are created when completing the WhereScape GIT Enablement Pack from. 
   
   

WhereScape 3D

By default, WhereScape 3D and RED store their metadata in separate PostgreSQL databases. To make sure both applications stay in sync, GIT is used as the master source for all metadata. 

When developers pull the latest metadata files from the remote GIT repository, their local WhereScape repositories are rebuilt using those files. This keeps everything aligned to the same version (called a commit ID) and ensures consistency across both tools. 

This process has been designed to ensure that both WhereScape repositories are always aligned. 

Using WhereScape 3D Workflows

The below lists all avaialable Workflow processes in the WhereScape GIT Enablement Pack. All existing WhereScape 3D workflow processes remain available.

To configure your workflows, please consult section ‘Configuring Workflows’.

Committing to GIT

To commit a new model or changes to an existing model to GIT, users click the workflow button, which executes the ed3d_commit_to_git template.

This workflow is used for the following reasons:

1. After making a change to a new data model.
2. After making a change to an existing data model.

This workflow will perform the following tasks:

1. Verifies connection to GIT Repository.
2. Brings in the latest changes from the remote repository so your local setup is up to date.
3. Saves the current version of your local repository.
4. The user will be prompted to add their own commit message:
   
   • If the user would like to link their commit to a backlog item or bug in GIT, they can use development tags in their commit message. Simply add a '#' followed by the backlog item ID. For example: '#123', will automatically associate the commit with the corresponding work item in your backlog.
5. Commits your changes to the remote GIT repository with your message.

Users can create/change the workflow configuration for any category, model, or model version; however, this function requires the user to select the model version to operate correctly.

Committing ALL Objects to GIT

To commit all changes made to a WhereScape 3D Repository, users click the workflow button, which executes the ed3d_commit_all_objects_to_git template.

This workflow is used for the following reasons:

1. After making changes to multiple new and/or existing data models.
2. After making changes to data models and configuration.

This workflow will perform the following tasks:

1. Verifies connection to GIT Repository.
2. Brings in the latest changes from the remote repository so your local setup is up to date.
3. Saves the current version of your local repository.
4. The user will be prompted to add their own commit message:
   
   • If the user would like to link their commit to a backlog item or bug in GIT, they can use development tags in their commit message. Simply add a '#' followed by the backlog item ID. For example: '#123', will automatically associate the commit with the corresponding work item in your backlog.
     
     
5. Commits all your changes to the remote GIT repository with your message.

Committing configuration changes to GIT

To commit any configuration changes to GIT, users will click the workflow button, which executes the ed3d_commit_config_to_git template.

This workflow is used for the following reasons:

1. After creating a new configuration setting.
2. After deleting an existing configuration setting.
3. After changing an existing configuration setting.

This workflow will perform the following tasks:

1. Verifies connection to GIT Repository.
2. Brings in the latest config changes from the remote repository so your local setup is up to date.
3. Refers to the GIT Audit Change log within the WhereScape 3D repository.
4. Extracts the configuration files & stores them within the local GIT repository folder.
5. The user will be prompted to add their own commit message:
   
   • If the user would like to link their commit to a backlog item or bug in GIT, they can use development tags in their commit message. Simply add a '#' followed by the backlog item ID. For example: '#123', will automatically associate the commit with the corresponding work item in your backlog.
6. Commits the config change to the remote GIT repository with your message.

Delete Model and Commit Changes

To delete a model from your repository and commit the changes, users will click the workflow button 'Delete Model and Commit', which executes the ed3d_delete_model_commit_to_git template.

This workflow is used for the following reasons:

1. When a model is no longer required and needs to be removed.

This workflow will perform the following tasks:

1. Deletes the currently selected model.
2. Verifies connection to GIT Repository.
3. Brings in the latest changes from the remote repository so your local setup is up to date.
4. Saves the current version of your local repository.
5. Commits the change to the remote GIT repository.

Create Branch

Users will click the workflow button to create a new branch, which executes the ed3d_create_feature_branch template.

This workflow is used for the following reasons:

1. Preparing a copy of an existing branch for a new purpose/development task/developer.

This workflow will perform the following tasks:

1. Verifies connection to GIT Repository.
2. Brings in the latest changes from the remote repository so your local setup is up to date.
3. The user will be prompted with a window and asked to provide the following information:
   1. The branch they wish to clone.
   2. The name the new branch.
   3. Click 'Create'
      
4. WhereScape 3D is closed.
5. The selected branch will be cloned on the remote GIT repository.
6. The new branch will be pulled onto the local\virtual machine.
7. WhereScape 3D is rebuilt using the files within the local GIT repository.
8. WhereScape RED (if using) is rebuilt using the files within the local GIT repository.
9. WhereScape 3D is reopened.

Close Branch 

Users will click the workflow button to close a branch, which executes the ed3d_close_branch template. 

This workflow is used for the following reasons: 

1. Close and discard the branch without merging changes into another branch. 
2. Merge the current branch into another branch (e.g. feature branch to be merged into development). 

This workflow will perform the following tasks:

1. Verifies connection to GIT Repository. 
2. The user is prompted to select the branch to close. The user can close a branch and discard all changes or close and merge the branch into another branch. The user will choose a branch to switch or merge to. 
   
3. If the user selects to close and merge, then a GIT merge action will take place between the selected branches. If there are any issues with this merge, the user will be prompted with the files creating issues. 
4. The local GIT repository is refreshed from the selected branch on the remote GIT repository. 
5. WhereScape 3D is rebuilt using the files within the local GIT repository. 
6. WhereScape RED (if using) is rebuilt using the files within the local GIT repository. 
7. WhereScape 3D is reopened. 

Switch Branch 

Users will click the workflow button to switch branch, which executes the ed3d_switch_branch template. 

This workflow is used for the following reasons:

1. To review the code/data model of the alternative branch.
2. Start development on a different branch.

This workflow will perform the following tasks:

1. Verifies connection to GIT Repository.
2. The user is prompted to select the branch to switch to.
   
3. Refreshes the local GIT repository from the remote GIT repository of the selected branch.
4. WhereScape 3D is rebuilt using the files within the local GIT repository.
5. WhereScape RED is rebuilt using the files within the local GIT repository.
6. WhereScape 3D is reopened.

Pull from GIT

Users will click the workflow button to fetch changes from the remote GIT repository to their current local branch, which executes the ed3d_pull template.

This workflow is used for the following reasons:

1. Refresh the Developer machines WhereScape repositories with the current (commit) metadata on the remote GIT repository.
2. Refresh and rebase the Developer machines WhereScape repositories, discarding any uncommitted changes.

This workflow will perform the following tasks:

1. Verifies connection to GIT Repository.
2. The “Branch” stored within the WhereScape Repository is the selected branch from which to pull.
3. Refresh the local GIT repository with updates from the corresponding remote GIT repository.
4. WhereScape 3D is rebuilt using the files within the local GIT repository.
5. WhereScape RED is rebuilt using the files within the local GIT repository.
6. WhereScape 3D is reopened.

Export to RED
To export a RED export model WhereScape RED, users will click the workflow button, which executes the ed3d_git_to_red templates.

This workflow is used for the following reasons:

1. Deploy a new Data Model into the WhereScape RED repository.
2. Deploy changes to an existing Data Model into the WhereScape RED repository.

This workflow will perform the following tasks:

1. Verifies connection to GIT Repository.
2. Brings in the latest changes from the remote repository so your local setup is up to date.
3. Saves the current version of your local repository.
4. Commits the change to the remote GIT repository.
5. You will be prompted to add a commit message:
6. You will be prompted to update connections:
   1. You are able to select the connection and then input the username and password. When you click on apply, the command line will write the credentials to the RED metadata repository.
   2. This step will only update the credentials within the RED metadata repository. Any credentials within the RED profile file, will override the credentials in the metadata repository.
      
7. Once you have updated the connections, click Next to continue the deployment.
8. Deployment of the model to RED completes.

Import Model

Users will click the workflow button to import a Data Model from a selected commit ID from a branch. This workflow button executes the ed3d_import_model_from_git template.

This workflow is used for the following reasons:

1. Import merge conflicts from a different branch.
2. Import a historical version of a data model into the existing branch.

This workflow will perform the following tasks:

1. Verifies connection to GIT Repository.
2. A window opens prompting the user for the following information:
   1. Select a branch
   2. Select a commit reference you wish to import from.
      Please note: These commits are filtered only to show commits that include the selected data model version.
   3. The user can review the commit changes they have selected in the text box.
   4. The user can overwrite the selected model version OR create a new version, using the commit ID as a prefix to the current model version name.
   5. Select 'OK'
      

3. The local GIT repository is synchronized to the selected commit.

4. A new model version is created, and the model is imported to your local repository.

5. The user must refresh the Repository Browser to see the imported data model.