Folder Manager service

The Folder Manager service available in the REST API supports multiple operations for manipulating folder structures in the Relativity UI framework. You can use it to create, update, or move a folder, query for folders, retrieve the root or children in a folder tree, and delete empty folders. It also indicates the progress for the deletion operation on folders.

You can also use the Relativity Services API to create, update, delete, and query for folders. For more information, see Folder Manager API.

This page contains the following information:

• Client code sample
• Create a folder
• Update a folder
• Delete unused folders
• Query for folders
• Helper methods
• Move folders

Client code sample

To interact with the Folder Manager service, you send HTTP(S) requests that use the POST method and specify query conditions in the body of the request. See the base URL for this service:

/relativity.rest/api/Relativity.Services.Folder.IFolderModule/Folder%20Manager/

You can use the following .NET code as the REST client for performing any of the operations available on the Folder Manager service. The code currently illustrates how to create a new folder, but you can modify it as follows to perform other operations:

• Set the url variable to the URL for the operation that you want to perform.
• Set the string represented by payload variable to the JSON input required for your operation.

public async Task FolderCreate()
{
    using (HttpClient httpClient = new HttpClient())
    {

        httpClient.BaseAddress = new Uri("http://localhost/relativity.rest/api/Relativity.Services.Folder.IFolderModule/Folder%20Manager/");

        //Set the required headers.
        httpClient.DefaultRequestHeaders.Add("/relativity.rest/api/Relativity.Services.Folder.IFolderModule/Folder%20Manager/QueryAsync", string.Empty);
        httpClient.DefaultRequestHeaders.Add("Authorization", "Basic c2FtcGxlYWRtaW5AcmVsYXRpdml0eS5yZXN0OlMwbTNwQHNzdzByZA==");

        string url = "CreateSingleAsync";

        var workspaceArtifactId = 0;

        var payload = @"{
                    workspaceArtifactID:0,
                    model: {
                        name: 'New folder name',
                        parentFolder: {
                            artifactId: 151561
                        }
                    }";

        var result = await httpClient.PostAsJsonAsync(url, payload);
        
    }
}

HTTP headers and status codes

The Folder Manager Service uses the same HTTP(S) headers and status codes as other services in the Relativity REST API. For more information, see the following:

• HTTP headers
• HTTP status codes

Create a folder

To create a folder, send a request to this URL for the Folder Manager service:

/relativity.rest/api/Relativity.Services.Folder.IFolderModule/Folder%20Manager/CreateSingleAsync

The request includes the following fields:

• workspaceArtifactID – the Artifact ID of the workspace where you want to create the folder.
• name – the model name, which is the name of the Folder DTO that you want to create.
• parentFolder – this field contains the parent folder where you want to add the new subfolder. If you want to create a folder at the root of a workspace, omit the parentFolder property.

The following request results in the creation of a child folder called MyFolder, which is added under an existing parent folder in a workspace.

{
    "workspaceArtifactID": 1015024,
    "model": {
        "name": "MyFolder",
        "parentFolder": {
            "artifactId": "1003697"
        }
    }
}

The response returns the Artifact ID of the folder that was created.

Update a folder

To rename or move a folder, send a request to this URL for the Folder Manager service:

/relativity.rest/api/Relativity.Services.Folder.IFolderModule/Folder%20Manager/UpdateSingleAsync

The request must contain the following fields:

• workspaceArtifactID – the unique identifier for the workspace where the folder resides.
• model.artifactID – the unique identifier for the Folder DTO.
• model.name – the text for the new folder name.

If the requests contains an Artifact ID that differs from ID for the original parent folder, the folder is moved to the parent folder specified in the request. If a parent folder isn't specified, the folder is moved to the root folder of the workspace.

The following request updates the name of folder to My new folder name. This folder has a parent folder in the workspace.

{
    "workspaceArtifactID": 1015024,
    "model": {
        "artifactID": "1039180",
        "parentFolder": {
            "artifactId": 1003697
        },
        "name": "My new folder name"
    }
}

The response returns the Artifact ID of the folder that was updated.

Delete unused folders

To delete all empty folders in a workspace, send a request to this URL for the Folder Manager service:

http://localhost/relativity.rest/api/Relativity.Services.Folder.IFolderModule/Folder%20Manager/DeleteUnusedFoldersAsync

Note: The DeleteUnusedFoldersAsync() method removes all unused folders from the workspace.

The request must include the Artifact ID of the workspace, where you want to deleted the unused folders:

{
    "workspaceArtifactID": 1015024,
}

The response returns a folder result set that lists the deleted folders.

{
    "QueryToken": "",
    "TotalCount": 3,
    "Success": true,
    "Message": "",
    "Results": [{
        "Success": true,
        "Artifact": {
            "ArtifactID": 1039163
        },
        "Message": "",
        "WarningMessages": []
    }, {
        "Success": true,
        "Artifact": {
            "ArtifactID": 1039179
        },
        "Message": "",
        "WarningMessages": []
    }, {
        "Success": true,
        "Artifact": {
            "ArtifactID": 1039180
        },
        "Message": "",
        "WarningMessages": []
    }]
}

Query for folders

To get an unstructured list of folders, send a request to the following Folder Manager Service URL:

/relativity.rest/api/Relativity.Services.Folder.IFolderModule/Folder%20Manager/QueryAsync

The request includes the following fields:

• workspaceArtifactId – the Artifact ID of the workspace that you want to query.
• query – may include query conditions or may be an empty query as illustrated in the following sample.
• length – indicates the number of returned results. The default value is 0 for length, and the number of returned results defaults to the Instance setting table value of PDVDefaultQueryCacheSize of 10000. For more information about query conditions and query tokens, see Search Relativity.

{
    "workspaceArtifactId": 1015024,
    "query": {},
    "length": 2
}

The response returns a list of all folders in the workspace that are available to requesting user.

If the response contains a token value that isn't null, it indicates that more results are available than initially specified in the length property, or that result count exceeds the default query limit. You can retrieve the additional folders by using the QuerySubsetAsync() method as illustrated in the following URL:

/relativity.rest/api/Relativity.Services.Folder.IFolderModule/Folder%20Manager/QuerySubsetAsync

The request for this method must include the workspaceArtifactID, queryToken, start, and length as in the following sample query:

{
    "workspaceArtifactID": 1015024,
    "queryToken": "f61f0c4a-a794-4cd0-9407-f8c4b927bdc3",
    "start": 5,
    "length": 4
}

The response to this query returns a subset with four elements from the previous query that starts at the fifth element.

Helper methods

The Folder Manager service provides helper methods that simplify retrieving folders or traversing the folder tree.

Retrieve workspace root Folder

To retrieve the root folder in a workspace, send a request to this URL for the Folder Manager service:

/relativity.rest/api/Relativity.Services.Folder.IFolderModule/Folder%20Manager/GetWorkspaceRootAsync

The request must include the workspaceArtifactID, which is the Artifact ID of the workspace that you want to query.

{
    "workspaceArtifactID": 1015024,
}

The response returns root folder in the workspace.

{
    "ParentFolder": {
        "ArtifactID": 0
    },
    "AccessControlListIsInherited": true,
    "SystemCreatedOn": "2010-08-08T16:59:49.1",
    "SystemLastModifiedOn": "2010-08-08T16:59:49.1",
    "Permissions": {
        "add": true,
        "delete": true,
        "edit": true,
        "secure": true
    },
    "Selected": false,
    "HasChildren": false,
    "ArtifactID": 1003697,
    "Name": "Test Template"
}

Retrieve subfolders

To retrieve a list of subfolders, send a request to this URL for the Folder Manager service:

/relativity.rest/api/Relativity.Services.Folder.IFolderModule/Folder%20Manager/GetChildrenAsync

The request must include the workspaceArtifactID, which is the Artifact ID of the workspace that you want to query.

{
    "workspaceArtifactID": 1015024,
    "parentId": 1003697
}

The response returns an array containing only direct descendants of the specified parent folder.

Retrieve expanded Folder nodes

You can retrieve a folder structure that contains expanded nodes, or you can retrieve a folder structure that contains expanded nodes, and Artifact ID of the folder currently selected by a user.

To retrieve information about expanded folder nodes, send a request to this URL for the Folder Manager service:

/relativity.rest/api/Relativity.Services.Folder.IFolderModule/Folder%20Manager/GetFolderTreeAsync

The request includes the following fields:

• workspaceArtifactId – the Artifact ID of the workspace that you want to query.
• expandedNodes – a list of Artifact IDs of specified folders. You want to retrieve information about these specified folders.
• selectedFolderId – an optional field used to mark a specific folder as selected.

For example, you might want to retrieve information about the children of the expanded root folder called Relativity Starter Template illustrated in the following screen shot:

You would query on Relativity Starter Template, Folder 3, and Folder 3.2 by sending the following request:

Note: For more information about the starter template, see Starter template on the Relativity Server2021 Documentation site.

{
    "workspaceArtifactId": 1015024,
    "expandedNodes": [1003697, 1039001, 1039006],
    "selectedFolderId": "1039008"
}

The response returns a list of children for all expanded folders.

Get folder access status

The GetAccessStatusAsync endpoint returns an object that contains information the user‘s ability to access the folder. Like the other endpoints in this API, use a POST request when making this call.

To return the access status, use this Folder Manager Service URL:

<host>/Relativity.Rest/API/Relativity.Services.Folder.IFolderModule/Folder%20Manager/GetAccessStatusAsync

The request must contain the following fields:

• workspaceArtifactID – the Artifact ID for the workspace where the folder resides.
• artifactID – the Artifact ID for the folder.

{
    "workspaceArtifactID": 1015024,
    "artifactID": 1038050
}

The response returns the following fields:

• Exists - indicates whether the folder exists.
• CanView - indicates whether the user has access to the folder.

{
    "Exists": true,
    "CanView": true
}

Move folders

You can move a folder and its children, including subfolders and documents. Send a request to this URL for the Folder Manager service:

/relativity.rest/api/Relativity.Services.Folder.IFolderModule/Folder%20Manager/MoveFolderAsync

The request must contain the following fields:

• workspaceArtifactID – the Artifact ID for the workspace where the folder resides.
• artifactID – the Artifact ID for the folder that you want to move.
• destinationFolderID - the Artifact ID for the target folder, where you want to move the current folder.

{
   "workspaceArtifactID":1015024,
   "artifactID":1039180,
   "destinationFolderID":1039178
}

The response returns the following fields:

• ProcessState - a message that indicates the current operation executing on the folder being moved. The process state messages include:
  • Creating destination folder hierarchy.
  • Creating document batches.
  • Creating folder reference update batches.
  • Moving documents.
  • Updating folder references.
  • Cleaning up.
• TotalOperations - equals the sum of the number of documents to be moved and the number of folder references to be updated.
• OperationsCompleted - indicates the number of operations that have been executed.

{
   "ProcessState":"Moving documents.",
   "TotalOperations":15,
   "OperationsCompleted":2
}