User Help > Managing Your Personal Workspace in a Sandbox > Creating a Sandbox
Creating a Sandbox
si createsandbox
Once a Sandbox is created, you can add subprojects or members to that Sandbox. The project is then updated to reflect the addition of new project members.
To create a Sandbox in the GUI, select Sandbox > Create or File > New > Sandbox and follow the instructions in the Create Sandbox Wizard.
While it is possible to create more than one Sandbox in a single directory, it is not recommended.
Specifying the Project to Base the Sandbox On
You can type in or select the project to base the Sandbox on.
If you are creating a variant or build Sandbox in the GUI, initially only enter the path and name of the root project. You specify the subproject later in the procedure. When specifying the subproject, there are rules that control what project configuration you can jump to. If your selection breaks any of the rules, you cannot create the Sandbox.
Selecting a Sandbox Type
When creating a Sandbox you can create the following types:
As Of creates a Sandbox based on a project configuration as of a specified date (date-based project configuration). When the As Of option is selected, the Project Branch option becomes available to specify a Branch ID value. Specifying the branch ID is the only way to specify a date-based project configuration for a development path that was dropped. The branch ID is the ID of the branch that the development path was on. For example, if the last checkpoint on the development path was project revision, then the branch ID is 1.1.1.
For more information, see Working With Date-Based Project Configurations.
Current configuration creates a Sandbox based on the existing configuration of the selected project or subproject. The new Sandbox is configured according to the displayed configuration information.
Normal creates a Sandbox based on the working project on the mainline.
Variant creates a Sandbox based on a project on a specific development path.
The Variant option is unavailable if there are no available development paths.
Deactivated development paths are not shown in the Development Path Name list.
Build creates a Sandbox based on a specific checkpoint of the master project. You can specify the checkpoint through its checkpoint number or label.
If the project that the Sandbox is based on is specified in the Project Name field using a keyword-based string with a jump to a variant or build project, you cannot select the type of Sandbox to create. When you click Finish, a variant or build Sandbox is created for you based on the configuration of the specified project.
If you select Current configuration, then a sandbox that was created based on a subproject will follow any subproject reconfigurations performed after the sandbox was created.
If you select Normal, Variant, or Build; after choosing a subproject then the sandbox will not follow subproject reconfigurations performed after the sandbox was created down to that subproject. In that scenario, the sandbox will only follow subproject reconfigurations on additional subprojects selected using the Specify a subproject of the project panel.
Specifying the Sandbox Scope
For large projects with mixed content, such as source code, simulation files, calibration files, and documentation, creating complete Sandboxes from these projects can impact Windchill RV&S client performance and consume large amounts of network bandwidth. While you may need all components in the projects (subprojects), you may only need to work with certain subprojects, files, or file types.
Specifying a Sandbox scope allows you to define what subprojects and/or members are included in a Sandbox. A Sandbox scope determines which specific subprojects and/or members to transfer from the Windchill RV&S server to the Sandbox directory when the Sandbox is created or resynchronized. Specifying Sandbox scope can greatly improve the performance of the Create Sandbox operation, reduce network traffic, and make it easier to locate the relevant subprojects and/or members that you need to work with.
In the Sandbox Wizard, under Options > Sandbox Scope, click Change Scope.
To define Sandbox subproject scope, click the Members in Subprojects check box, and click the Select option to specify which subprojects you want in scope. You can select a parent node to select all child subprojects within that parent node automatically. When you select a subproject lower in the tree, higher parent nodes display a partial node selection icon Partial Subproject Scope Selection. Once you select a parent node and all of its children, you cannot deselect individual children of that selected parent node.
In the GUI, the path is displayed using explicit non-compact keyword string syntax. For example:
For more details on source configuration paths using keyword-based strings, see the options page of the CLI man pages.
When the Sandbox is created, the related folder structure on the file system includes only selected subprojects in scope.
To define Sandbox member scope, click a check box to include () or invert () one or more of the following options:
All Members
All project members. This is the default setting.
Members with Attribute
Project members with an attribute or attribute set to a value, for example, Beta or OS=Windows. This option is case-sensitive.
Members with Path
Project members that reside in a directory, relative to the top-level Sandbox, for example, watch/lib/*. The specified path does not differentiate between subdirectories and subproject names. This means that you cannot specify individual co-located subprojects.
For example, if you create a scoped Sandbox from the following top-level project:
with the following subprojects and members:
specifying sub1 matches p1/sub1/aa.txt and p1/sub1/dd.txt
or specifying *sub1 matches /p1/sub1/aa.txt, /p1/sub1/bb.txt, /p1/sub2/sub1/cc.txt, and /p1/sub1/dd.txt.
If the client OS is a case-sensitive file system and the database repository on the server is case-sensitive, this option is case-sensitive. Otherwise, this option is case-insensitive.
Members with Name
Project members with a name or file extension, for example, Readme.txt or *.java. A name is only valid for a file name, not a leading directory prefix.
If the client OS is a case-sensitive file system and the database repository on the server is case-sensitive, this option is case-sensitive. Otherwise, this option is case-insensitive.
Member with Label at Member Revision
Project members with a label at member revision, for example, TEST. This option is case-sensitive and accepts wildcards (* and ?).
Members with Label at Any Revision
Project members with a label at any revision, for example, PROD. This option is case-sensitive and accepts wildcards (* and ?).
Members with Archive Type
Project members that are a Binary or Text archive type.
Combine Selections Using
Logical AND
Logical OR
Combines multiple Sandbox scope options using a logical AND or OR operator. For example, to include project members with member attribute Beta AND name *.java, set With Attribute to Beta, Members with Name to *.java, and enable Logical AND.
Using the si createsandbox command, you can create and edit more complex Sandbox scope definitions using a combination of logical AND or OR operators; however, these definitions may not always be editable from the GUI. If you attempt to edit a complex scope definition from the GUI, Windchill RV&S truncates the definition to what the GUI is capable of displaying. If you attempt to edit a complex scope definition using the si configuresandbox -g/gui command, Windchill RV&S displays a warning message that choosing to edit the scope definition removes the options the GUI is not capable of displaying.
After the Sandbox is created, the title bar in the Sandbox view displays Scoped Sandboxpath and project.
You can view and change the scope definition when creating Sandboxes using the Create Sandbox Wizard, from the Sandbox Information dialog box, or using the si configureandbox command.
Changes to the scope definition are automatically reflected in the Sandbox view. Out of scope subprojects are automatically hidden from the view unless the corresponding folders exist on disk. Members with working files in the Sandbox that no longer match the scope definition display deltas, but remain in the Sandbox. Selecting one of the members indicates that a working file exists and the member does not match the Sandbox scope. Perform a Resynchronize operation to remove the out of scope members and subprojects from the Sandbox.
Note the following:
When you define both subproject scope and member scope for a Sandbox, the member scope definition is combined with the subproject scope definition using a logical AND operation. Only the members in scope within the subprojects in scope are included in the Sandbox view.
The scope of a Sandbox is saved with the Sandbox and persists when the Sandbox or Windchill RV&S client are closed and restarted. It is possible to have two Sandboxes of the same project with each one having a different Sandbox scope.
For future Create Sandbox operations, you can set the Sandbox member scope in the preferences for the Create Sandbox command.
New subprojects and members are affected by the Sandbox scope.
For example, if the Sandbox scope includes project members with attribute name and value OS=Windows, and you add a project member with that attribute name and value in a non-scoped Sandbox, the member displays in the scoped Sandbox as a new member. Resynchronizing the member adds the working file to the Sandbox. If you add a project member without an attribute name and value in non-scoped Sandbox, the member does not display in the scoped Sandbox.
If you add a new subproject using the Windchill RV&S client in a non-scoped Sandbox, that subproject is not visible in the scoped Sandbox because the folder is not created on disk. However, if you add a new subproject using the CLI, the corresponding folder is created on disk and visible in the Sandbox view.
You can perform other operations that can result in subprojects or members in the Sandbox that do not match the current Sandbox scope. For example, you can resynchronize change packages using --resyncIfOutOfScope to resynchronize both in scope and out of scope subprojects and members. You can also modify a member so that it no longer matches the Sandbox scope, add a new member that doesn't match the Sandbox scope, or you can update the Sandbox scope definition.
Defining Sandbox scope is different from filtering members using the view filters using the si viewsandbox command. Sandbox scope determines what subprojects and members are initially included in the Sandbox and are transferred to the file system when you resynchronize. View filters allow you to further filter which members are displayed in the Sandbox view. For example, if you create a scoped Sandbox that includes members with attribute name/value OS=Windows, your Sandbox only includes members that match that scope. You can then apply the Locked Members filter to your Sandbox to display only members that match the Sandbox scope and have a lock. Members of the project that have a lock but do not match your scope are not visible in the view.
The scope and sparse options are independent of one another, for example, you can create a scoped sparse Sandbox.
You can manage out of scope subprojects and/or members by using the Sandbox view Filter list and the View > Select command. To display only members that have working files in the Sandbox that do not match the current Sandbox scope definition, select Out of Scope Members from the Sandbox view Filter list. To select only members that have working files in the Sandbox that do not match the current Sandbox scope definition, select View > Select and enable the Out of Scope Members option.