10 Working with Folders

There are several types of Agile PLM folders with which you can work. Each user's selection of folders may vary. However, every user has a Home folder. From each user's Home folder, you can construct various subfolders and browse public and private queries.Folders are subject to the same transactional model as other Agile API objects. If you do not set a transaction boundary for a folder, it is automatically updated as soon as you add anything to, or remove anything from the folder.You can work with Folder Web services to deal with the hierarchical structure of a folder by adding and removing children, getting children, and getting the parent folder.

Private - Folders that are accessible only to the user that created them. Users can create or delete their own Private folders.
Public - Folders that are accessible to all Agile PLM users. Only users with the GlobalSearches privilege can create, delete, and modify Public folders.
System - Predefined folders that ship with the Agile PLM system. Most users cannot modify or delete system folders.
My Bookmarks (or Favorites) - A predefined folder containing each user's bookmarks to Agile PLM objects. You cannot delete the My Bookmarks folder.
Home - The predefined Agile PLM home folder. You cannot delete the Home folder.
Personal Searches - The predefined parent folder for each user's personal searches. You cannot delete the Personal Searches folder.
Recently Visited - A predefined folder containing links to recently visited objects. The web service does not populate this folder. It is only populated by client applications. If required, you specify this in your application.

Note:

The recently visited folder is only flushed to the database periodically. Therefore, secondary connections like process extensions with portals, or stand-alone web service based applications will not see the same information that the user's GUI displays.

Report - A folder containing reports. Although you cannot use the Agile API to create, modify, or delete report folders, you can create, modify, or delete them in Agile PLM clients.

10.1 Loading a Folder

There are two ways to load a folder:

Use the getFolder operation to specify the full path of a folder.
Use the getChildNode operation to specify the relative path of a subfolder.

Folder and query names are not case-sensitive. Therefore, you can specify a folder path using upper or lowercase. For example, to load the Personal Searches folder, you can specify /Personal Searches or /PERSONAL SEARCHES.

The following example shows how to load a folder by specifying the full path to the folder.

Example: Loading a folder using the getFolder operation

GetFolderRequestType getFolderRequestType =
new GetFolderRequestType();
AgileGetFolderRequestType[] agileGetFolderRequestTypeArray =
    new AgileGetFolderRequestType[1];
agileGetFolderRequestTypeArray[0] =
        new AgileGetFolderRequestType();
FolderIdentifierType identifier = new FolderIdentifierType();
identifier.setBaseFolder(3); // Home folder constant is 3. Please refer to the documentation
                             // for other base folder constants
identifier.setName("Personal Searches"); //relative name of the folder
agileGetFolderRequestTypeArray[0].setFolderIdentifier(identifier);
agileGetFolderRequestTypeArray[0].setRecursive(false); //set to true to load all child folders recursively
getFolderRequestType.setRequests(agileGetFolderRequestTypeArray);
GetFolderResponseType getFolderResponseType = agileFolderStub.getFolder(getFolderRequestType);

The following example shows how to load a folder by specifying its path relative to another folder, in this case the user's Home Folder.

Example: Loading a folder using getChildNode operation

GetChildNodeRequestType getChildNodeRequestType =
new GetChildNodeRequestType();
AgileGetChildNodeRequestType[] agileGetChildNodeRequestTypeArray =
    new AgileGetChildNodeRequestType[1];
agileGetChildNodeRequestTypeArray[0] =
        new AgileGetChildNodeRequestType();
FolderIdentifierType identifier = new FolderIdentifierType();
identifier.setBaseFolder(3); // Home folder constant is 3.
identifier.setName("Personal Searches/Folder A"); //relative name of the folder A
agileGetChildNodeRequestTypeArray[0].setFolderIdentifier(identifier);
String[] children = new String[2];
children[0] = "Folder 1";
children[1] = "Query 1";
agileGetChildNodeRequestTypeArray[0].setChildren(children);
getChildNodeRequestType.setRequests(agileGetChildNodeRequestTypeArray);
GetChildNodeResponseType getChildNodeResponseType = agileFolderStub.getChildNode(getChildNodeRequestType);

10.2 Creating a Folder

To create a folder, use the createFolder operation. When you create a folder, you must specify the folder's name and its parent folder. The following example shows how to create a folder named "MyTemporaryQueries" in the Personal Searches folder.

Example: Creating a new folder

CreateFolderRequestType createFolderRequestType =
new CreateFolderRequestType();
AgileCreateFolderRequestType[] agileCreateFolderRequestTypeArray =
    new AgileCreateFolderRequestType[1];
agileCreateFolderRequestTypeArray[0] =
        new AgileCreateFolderRequestType();
FolderIdentifierType identifier = new FolderIdentifierType();
identifier.setBaseFolder(3); // Home folder constant is 3.
identifier.setName("Personal Searches/Folder A"); //relative name of the folder A
agileCreateFolderRequestTypeArray[0].setFolderIdentifier(identifier);
createFolderRequestType.setRequests(agileCreateFolderRequestTypeArray);

10.3 Working with Folder Elements

An Agile PLM folder contains file folder objects (subfolders), query objects, and any kind of data object, such as item, manufacturer and so on.

10.3.1 Adding Folder Elements

You can use the "addChildNode"to add objects to a folder.

Using the operation, you can add childNodes to a folder identified by its folder identifier. The list of childNodes to be added to a folder is passed as input to the request. The child nodes can be a query object, an AgileObject or a subfolder itself.

Example: Adding child nodes to a folder.

AddChildNodeRequestType addChildNodeRequestType =
new AddChildNodeRequestType();
AgileAddChildNodeRequestType[] agileAddChildNodeRequestTypeArray =
    new AgileAddChildNodeRequestType[1];
agileAddChildNodeRequestTypeArray[0] =
        new AgileAddChildNodeRequestType();
FolderIdentifierType identifier = new FolderIdentifierType();
identifier.setBaseFolder(3); // Home folder constant is 3
identifier.setName("Personal Searches/Folder A"); //relative name of the folder A
agileAddChildNodeRequestTypeArray[0].setFolderIdentifier(identifier);
FolderIdentifierType[] childFolders = new FolderIdentifierType[2];
for(int i=0; i<childFolders.length; i++) {
    childFolders[i] = new FolderIdentifierType();
    childFolders[i].setBaseFolder(3);
    childFolders[i].setName("Personal Searches/Folder "+i);
}
agileAddChildNodeRequestTypeArray[0].setFolders(childFolders);
addChildNodeRequestType.setRequests(agileAddChildNodeRequestTypeArray);

10.3.2 Removing Folder Elements

To remove a single folder element, use the operation "removeChildNode".

Example: Removing child nodes from a folder

RemoveChildNodeRequestType removeChildNodeRequestType =
new RemoveChildNodeRequestType();
AgileRemoveChildNodeRequestType[] agileRemoveChildNodeRequestTypeArray =
    new AgileRemoveChildNodeRequestType[1];
agileRemoveChildNodeRequestTypeArray[0] =
        new AgileRemoveChildNodeRequestType();
FolderIdentifierType identifier = new FolderIdentifierType();
identifier.setBaseFolder(3); // Home folder constant is 3.
identifier.setName("Personal Searches/Folder A"); //relative name of the folder A
agileRemoveChildNodeRequestTypeArray[0].setFolderIdentifier(identifier);
String[] children = new String[2];
children[0] = "Folder 1";
children[1] = "Query 1";
agileRemoveChildNodeRequestTypeArray[0].setChildren(children);
removeChildNodeRequestType.setRequests(agileRemoveChildNodeRequestTypeArray);

10.3.3 Getting Folder Elements

All objects contained in a folder, including subfolders, can be loaded by name. To retrieve an object from a folder, use the operation "getChildNode". Remember, the object type for folder elements can vary. Depending on the object, you could get a subfolder, a query, or a dataobject, such as an Item.

Example: Getting a folder element

GetChildNodeRequestType getChildNodeRequestType =
new GetChildNodeRequestType();
AgileGetChildNodeRequestType[] agileGetChildNodeRequestTypeArray =
    new AgileGetChildNodeRequestType[1];
agileGetChildNodeRequestTypeArray[0] =
        new AgileGetChildNodeRequestType();
FolderIdentifierType identifier = new FolderIdentifierType();
identifier.setBaseFolder(3); // Home folder constant is 3.
identifier.setName("Personal Searches/Folder A"); //relative name of the folder A
agileGetChildNodeRequestTypeArray[0].setFolderIdentifier(identifier);
String[] children = new String[2];
children[0] = "Folder 1";
children[1] = "Query 1";
agileGetChildNodeRequestTypeArray[0].setChildren(children);
getChildNodeRequestType.setRequests(agileGetChildNodeRequestTypeArray);

10.4 Deleting a Folder

To delete a folder, use the operation "deleteFolder". You can delete folders that are empty and that are not predefined Agile PLM system folders (such as the Global Searches and My Inbox folders).

Note Unlike other data objects, folders are not "soft-deleted" the first time you delete them. When you delete a folder, it is permanently removed from the system.

Example: Deleting a folder

DeleteFolderRequestType deleteFolderRequestType =
new DeleteFolderRequestType();
AgileDeleteFolderRequestType[] agileDeleteFolderRequestTypeArray =
    new AgileDeleteFolderRequestType[1];
agileDeleteFolderRequestTypeArray[0] =
        new AgileDeleteFolderRequestType();
FolderIdentifierType identifier = new FolderIdentifierType();
identifier.setBaseFolder(3); // Home folder constant is 3.
identifier.setName("Personal Searches/Folder A"); //relative name of the folder A
agileDeleteFolderRequestTypeArray[0].setFolderIdentifier(identifier);
deleteFolderRequestType.setRequests(agileDeleteFolderRequestTypeArray);

10.5 Renaming a Folder

To rename a folder, use the operation "renameFolder".

Example: Renaming a folder

FolderRequestType renameFolderRequestType =
new RenameFolderRequestType();
AgileRenameFolderRequestType[] agileRenameFolderRequestTypeArray =
    new AgileRenameFolderRequestType[1];
agileRenameFolderRequestTypeArray[0] =
        new AgileRenameFolderRequestType();
FolderIdentifierType identifier = new FolderIdentifierType();
identifier.setBaseFolder(3); // Home folder constant is 3.
identifier.setName("Personal Searches/Folder A"); //relative name of the folder A
agileRenameFolderRequestTypeArray[0].setFolderIdentifier(identifier);
agileRenameFolderRequestTypeArray[0].setNewName("Folder B");
renameFolderRequestType.setRequests(agileRenameFolderRequestTypeArray);