Skip to content

Workspace mgmt app

Introduction🔗

Modelon Impact Workspace Management allows users to collaborate with other users via version controlled repositories on Subversion (SVN) and Git. This app enables use of version controlled Modelica libraries in Modelon Impact workspaces, and changes and new contributions to these libraries are tracked and can be shared with others through version control operations built into the app. Updates by other users can also be fetched, enabling coordinated work among Modelon Impact users collaboratively developing models or Modelica libraries.

Modelon Impact Workspace Management is available with Modelon Impact On-Premise.

Modelon Impact Workspace Management includes three key components:

Each component can be accessed both from the Modelon Impact landing page and from a workspace in Modelon Impact through the Apps menu in the upper right corner of the browser window:

For information on the advanced tools shown in the Apps menu, see JupyterHub Advanced Tools. For more information on version control, see Use version control.

Credentials🔗

The Credentials page shows an overview of your saved version control service credentials (e.g. for https://github.com). The version control credentials are needed to be able to interact with version controlled libraries, e.g. fetch remote updates or contribute with your changes to make them accessible for other users.

Select Master Password🔗

To enable saving of credentials, you need to select a master password which will be used to protect the credentials to your version control services. You will be guided to do this at the Credentials page and at the Repository Management page if a master password is not set already. Select a master password and keep it safe.

Add Credentials🔗

Once the master password is set, credentials are automatically saved when entering credentials to check out version controlled content from the Repository Management page. Credentials can also be added on the Credentials page if this is preferred, through "New Credential":

Tip

It is recommended to enter the url to the Git/SVN service (e.g. https://github.com) when adding credentials, and not to the repository (e.g. https://github.com/my-organization/my-repo). This is done automatically when adding credentials at checkout through the Repository Management page (recommended).

Note

Note that for Git services, the credentials should be a user name and a Git token, and not the password to the Git service (e.g. password to github). Git tokens are generated from the git service web page. For github, they can be generated at the personal access tokens page, and for gitlab from the personal access tokens page.

Note

Due to git design, git credentials are removed from the saved credentials when the token is invalid (e.g. has expired). If this happens, the credentials for the git service needs to be re-entered, through the credentials page or at the repository management page at checkout.

Update/Delete Credentials🔗

When the saved credentials are unlocked using the master password, version control service credentials can be updated from the expanded entry in the Credentials page.

Forgot Your Password?🔗

If you forgot your master password, you can reset it using "Forgot your credentials password?" to the bottom right of the page. The option is visible only when the saved credentials are locked. Note that the master password is never saved due to security reasons, so if you have lost it you need to add the needed version control service credentials again. After doing this, a new master password can be selected and version control service credentials can be entered as before.

Repository Management🔗

On the repository management page, an overview of the existing repositories for which working copies have been checked out is visible. Each bubble represents a repository and each grey box represents a working copy from this repository. The screenshot below shows an example where several working copies from a number of different repositories have already been checked out.

Pre-requisite

  • SVN or Git account and repository url to check out are needed to complete these steps
  • SVN urls are often similar to https://svn.server-name.com/my-repository/trunk/my-subfolder
  • Git urls are often similar to https://github.com/my-organization/my-repo or https://gitlab.com/my-organization/my-subgroup/my-repo.git.

For more information about repositories, working copies, SVN and Git, see Use version control.

Checkout/Clone Content from SVN/Git🔗

To add a working copy from a new remote location, click on the '+' button and enter the required information. The repository url can be any SVN or Git url. If credentials are already available in the saved credentials, this will be shown. If not, credentials need to be entered, and will be saved if checkout is successful.

The custom display name can be used to set a specific display name for all content from this repository (shown for the repository component). If not set, the shortest unique name for the repository will be selected based on the existing repositories where content is already checked out. If at least one working copy from this repository has already been checked out, the display name will be read-only and can not be edited. The new working copy will be grouped together with the existing working copies from the same remote location.

The branch/tag field (for Git only) can be used to check out a specific branch or tag. If left blank, the default branch is checked out. For SVN, the branch/tag is specified through the url. The revision field (for SVN only) can be used to check out a specific revision of the repository. If the field is left blank, the latest revision is checked out.

When clicking 'Add', a working copy of the repository is checked out/cloned to your user disk. This can take a while if the repository is large. A spinner is shown with the possibility to cancel the operation if desired. After checkout, the new repository is shown, with all its working copies visible as grey boxes.

Tip

For git, it is strongly recommended to work on your own branch to avoid conflicts with remote changes in everyday work. Any conflicts with remote changes are then handled only when changes are merged to another branch (e.g. main/master).

Check Status of Working Copies🔗

The revision number (for SVN) or branch (for Git) and the size of the working copy on disk are shown for each working copy. It is also possible to open the working copy in Visual Studio Code (VS Code) through the context menu when clicking the three dots in the grey box.

An icon next to the three dots indicates the current status of the working copy:

  • An orange lock icon indicates that the status can not be fetched since credentials are locked ("locked"). Click on the lock icon on the top right corner to enter the master password and fetch the status.
  • A red, strikethrough lock icon indicates that there are no credentials for this repository in the saved credentials ("no credentials"). Go to the credentials page to enter credentials for this repository to be able to show the status.
  • A green check with arrows means that the working copy is up to date with the remote repository ("up to date"). No update is needed and there are no local modifications in the working copy.
  • A pen and text icon indicates that there are local modifications in the working copy ("has local modifications"), e.g. from editing, adding, or deleting models in any library inside this working copy in Modelon Impact. These changes can be uploaded to the remote repository ("Push changes" for Git, "Commit changes" for SVN), or reverted through the context menu. To view the changes file by file, open the working copy in VS Code through the context menu. Hints on how to view differences in Visual Studio Code are available in the section Version Control in Visual Studio Code.
  • A dark cycle arrow indicates that there are remote updates to this working copy ("has remote updates"), i.e. the working copy is not up to date with the remote repository. Updating to the latest revision is enabled through the context menu.
  • A red exclamation mark with arrows indicates a conflict between the local modifications (my changes) and the remote updates to the repository (incoming changes) ("has conflicts"). The conflict can be resolved through the context menu using "Keep my changes" or "Keep incoming changes", or the conflicts can be edited and resolved manually using VS Code. Hints on how to edit conflicts in Visual Studio Code are available in the section Version Control in Visual Studio Code. There is also an option to revert all local modifications to the working copy.

Fetch Remote Updates🔗

When the status is "has remote updates", the context menu has an option "Update" that can be used to fetch the remote changes to the working copy. Note that there may also be local modifications to the working copy, and any conflicts with incoming changes will be shown only after updating. To inspect the working copy file by file before updating, open the working copy in VS Code through the context menu, see hints in the section Version Control in Visual Studio Code.

After clicking update, the status will be either "up to date", "has local modifications", or "has conflicts". If there are conflicts, these can be resolved through the options in the context menu, or by opening VS Code to edit and resolve the conflicts manually.

Upload Changes to the Repository🔗

When having worked with a version controlled model/library in Modelon Impact (added/modified/deleted models and/or packages), the working copy where the library is located will contain local modifications. These can be uploaded (committed/pushed) to the remote repository through the repository management page. The most convenient way of working is to open the Workspace configuration page from the Apps menu inside the workspace in Modelon Impact. This will show all version controlled libraries inside the workspace and their status. For the working copy for which to upload the changes, click the context menu (three dots) and select "Open in Repo Management". This will open the Repository Management page with the relevant repository and working copy selected.

To upload the changes, first, verify that the status is "has local modifications" (pen and text icon). If the status is a lock icon, credentials need to be unlocked or added first. If the status is "has remote updates", the remote updates need to be fetched first. If the status is "has conflicts", the conflict needs to be resolved first.

To inspect the changes, open the working copy in VS Code through the context menu. See hints on how to view the changes in the section Version Control in Visual Studio Code.

To upload the changes so that everyone with access to the repository gets access to them, click "Commit changes" (for SVN) or "Push changes" (for Git) in the context menu. A field will appear where a commit message can be entered. The changes are committed/pushed to the current branch.

Note

Common practice is to set the commit message to a short description of the changes which are committed, and a development ticket number if relevant.

After uploading the changes, the status of the working copy should be "up to date", and the revision (SVN only) be updated to the latest.

Revert Changes in the Working Copy🔗

If wanting to discard all local modifications in a working copy, this can be done using "Revert changes" in the context menu for the working copy. This will revert any changes done to models that are already version controlled, but no local files will be removed from disk. The option is available when the status is "has local modifications" (pen and text icon) or "has conflicts" (red exclamation mark icon). Checking which files are modified can be done by opening the working copy in VS Code, see hints on how to do this in the section Version Control in Visual Studio Code.

After reverting the changes, the status of the working copy should be "up to date" or "has remote updates".

Solve Merge Conflicts🔗

If two or more users work on the same branch and make changes in the same files, merge conflicts may appear when updating the working copy, due to conflicting changes in the local working copy with incoming changes. This will set the working copy in a conflicted state, which is indicated by the "has conflicts" status icon for the working copy.

The conflict can be resolved using the options "Keep my changes" or "Keep incoming changes" in the context menu. "Keep my changes" will resolve the conflict by keeping your own full file for each file where there are conflicts with remote changes. This will result in the status "has local modifications", and your changes can then be uploaded to the repository if desired. "Keep incoming changes" will keep the full file from the remote repository for each file where there are conflicts.

To edit the conflicts manually, open the working copy in VS Code. In VS Code, open each conflicted file in the "Source control" view, select "Accept current" or "Accept incoming" for each conflict and then accept the conflicts as resolved when prompted. See more hints related to this in the section Version Control in Visual Studio Code.

Note

SVN tree conflicts (e.g. two users adding a model with the same name) can currently not be resolved by the "Resolve" actions in the context menu. These conflicts have to be resolved in another tool (e.g. Visual studio code or a terminal).

Workspace Configuration🔗

The workspace configuration page can be used to configure existing or new workspaces with version controlled libraries and/or Modelon Impact libraries. The page also shows an overview of all content in the workspace and the status of the working copies in which the version controlled libraries are located. The workspace configuration page can be opened from the Apps menu in an open workspace in Modelon Impact to configure or view the content of the workspace, or from the Apps menu on the Modelon Impact landing page to create and configure a new workspace.

Configure Workspace🔗

When the workspace configuration page is opened from the workspace in Modelon Impact, the content of the workspace is shown, as well as the status of the working copies in which the version controlled libraries are located. There are three types of content which can be in the workspace:

  • Version controlled libraries show as "LibraryName (branch)", where 'branch' is the branch the library is located on in the SVN or Git repository. Each grey box represents a working copy, which can be further inspected at the repository management page through the option "Open in Repo Management" in the context menu (three dots). The status of each working copy is displayed next to the three dots, see more info in Check Status of Working Copies. One working copy can contain one ore more Modelica libraries.
  • Libraries not under version control are displayed as only the library name. These are libraries located only on your user disk, and could be top level packages or models created in Modelon Impact. By default, each new workspace will contain a package "Workspace", which is not under version control. All libraries which are not under version control are grouped together in a grey box.
  • Modelon Impact libraries show as a library name and a version number, separated by a space. These libraries are distributed together with Modelon Impact, and can not be edited. All Modelon Impact libraries are grouped together in a grey box.

To add/remove/delete libraries in the workspace, click the "Edit" button. Available version controlled libraries and Modelon Impact libraries are now shown to the right, and can be dragged into the workspace as editable or read-only (dependencies). To remove a library from the workspace, click the 'x' button, and it will again appear under "Available libraries". For libraries which are not version controlled (only located on your user disk), there is a trash can icon which enables you to delete the library.

If you are missing any version controlled libraries, click the link "Clone/checkout new library") to go to the repository management page to checkout/clone them to your disk, and then go back to the configure page to continue (refresh page may be needed).

Changes are applied as soon as they are performed, but to get a cleaner page view, edit mode can be exited after configuration is finished by clicking "Done". When configuration is complete, you can go back to the workspace in Modelon Impact (a reload will be requested if the content was changed), or you can use the link at the bottom of the page to open the workspace in Modelon Impact.

Note

Modelon Impact does not allow more than one library with the same name in a workspace, which is why this is restricted when configuring a workspace.

Note

The libraries distributed with Modelon Impact are read-only, which is why they can not be added as editable in a workspace.

Open Workspace in Visual Studio Code🔗

The link at the bottom of the page to open the workspace in Visual Studio (VS) Code may be convenient for checking the status of all version controlled libraries in the workspace simultaneously. Clicking the link will open a VS Code workspace which has all working copies open for which there are libraries included in the current Modelon Impact workspace. Going to the "Source Control" view (icon in the left sidebar) will show the local modifications in each of the working copies. See more information in the section Version Control in Visual Studio Code.

Create New Workspace🔗

When the workspace configuration page is opened from the Modelon Impact landing page, a page for creating and configuring the workspace is shown. Specify a name of the new workspace and drag and drop version controlled and/or Modelon Impact libraries as needed to "Editable libraries" and/or "Dependencies", see Configure Workspace.

After clicking "Create workspace", the workspace is created and the page switches to configure mode, where you can continue configuring the workspace or opening it in Modelon Impact or VS Code.