Skip Headers

Agile Product Lifecycle Management Web Services Guide Release 9.3.3 E39310-01 |
| Contents

Previous | Next |

# 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 standalone 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.

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.

## 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 lower case. 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 if you want 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 can contain file folder objects (subfolders), query objects, and any kind of data object, such as item, manufacturer, etc. Use the addChildNode operation to add objects to a folder.

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

### 10.3.1 Adding Folder Elements

The following example shows how to add a child node to a folder.

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 removeChildNode operation.

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 getChildNode operation. Remember, the object type for folder elements can vary. Depending on the object, you could be getting 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 deleteFolder operation. 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 renameFolder operation.

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);