Resource File (.NET)

The Resource File API allows clients to manage resource files for the Relativity applications in the environment. It includes the following features:

  • Supports create, read, update, delete and download resource files.
  • Update/upload file content and metadata.
  • Secondary methods allows the client to read all eligible applications.

You can also interact with the Resource File API through the REST API. See Resource File service.

Guidelines for the Resource File API

Review the following guidelines for working with the Resource File API.

Admin-level context

The value for the workspaceID parameter in the path should always be -1. Any other value will return an error.

Sample use cases

The Resource File API can be used by R1 Operations or ISVs to manage third-party applications in their Relativity instances.

Endpoints

The Resource File API includes the following endpoints. To set up a proxy to interact with the IResourceFile API, call the CreateProxy() method on the object returned by the GetServiceManager() method.

Copy 
Client.SamplesLibrary.Helper.IHelper helper;
  
// Create a proxy
using (IResourceFileManager ResourceFileManager= helper.GetServicesManager().CreateProxy<IResourceFileManager>(ExecutionIdentity.User))
{
    // Add your custom code ...
}

CreateAsync

The following code samples illustrate how to use this endpoint to add/create new resource files in the environment.

Permissions

The following permissions are required to call this endpoint:

  • Instance - Object - Resource File - Create
  • Instance - Object - Library Application - View
  • Instance - Admin Operations - View Admin Repository
Copy 
public async Task CreateAsync(ResourceFileRequest resourceFileRequest, string fileContent)
{
    byte[] contents = Encoding.UTF8.GetBytes(fileContent);
    MemoryStream memoryStream = new MemoryStream(contents)
    {
        Position = 0
    };
    KeplerStream keplerStream = new KeplerStream(memoryStream);
     
    try
    {
        ResourceFileResponse response = await ResourceFileManager.CreateAsync(resourceFileRequest, keplerStream);
    }
    catch (Exception ex)
    {
        string exception = $"An error occurred: {ex.Message}";
        Console.WriteLine(exception);
    }
}
Copy 
public async Task CreateAsync(string fileName, string fileContent)
{
    ContentsResponse uploadContentsResponse = null;
    ResourceFileRequest request = new ResourceFileRequest
    {
        Application = TestAppIdentifier,
        FileName = fileName,
        Keywords = string.Empty,
        Notes = string.Empty
    };
             
    MemoryStream memoryStream = new MemoryStream(Encoding.UTF8.GetBytes(fileContent))
    {
        Position = 0
    };
 
    using (KeplerStream keplerStream = new KeplerStream(memoryStream))
    {
        //Upload Contents
        uploadContentsResponse = await ResourceFileManager.UploadContentsAsync(keplerStream, fileName);
    }
 
    //Create ResourceFile with uploaded contents
    try
    {
        ResourceFileResponse createResponse = await ResourceFileManager.CreateAsync(request, uploadContentsResponse.ContentsKey);
    }
    catch (Exception ex)
    {
        string exception = $"An error occurred: {ex.Message}";
        Console.WriteLine(exception);
    }
}

ReadAsync

The following code sample illustrate how to use this endpoint to retrieve advanced metadata for a resource file, including its name, application, and other properties.

  • IncludeMetadata - A Boolean value indicating whether to return extended resource file metadata in the response.
  • IncludeActions - A Boolean value indicating whether to return a list of operations eligible to the current user of this resource file.

Permissions

The following permissions are required to call this endpoint:

  • Instance - Object - Resource File - View
  • Instance - Admin Operations - View Admin Repository

Additional permissions are required to view the application name and consume the Edit and Delete actions:

  • Instance - Object - Resource File - Delete
  • Instance - Object - Resource File - Edit
  • Instance - Object - Library Application - View
Copy 
public async Task ReadAsync(int resourceFileID, bool includeMetadata, bool includeActions )
{
    try
    {
        ResourceFileResponse response =
            await ResourceFileManager.ReadAsync(resourceFileID, includeMetadata, includeActions);
    }
    catch (Exception ex)
    {
        string exception = $"An error occurred: {ex.Message}";
        Console.WriteLine(exception);
    }
}

UpdateAsync

The following code samples illustrate how to use this endpoint to allow the client to update/modify resource file metadata and file content.

Permissions

The following permissions are required to call this endpoint:

  • Instance - Object - Resource File - View
  • Instance - Object - Resource File - Edit
  • Instance - Admin Operations - View Admin Repository
Copy 
public async Task UpdateMetadataAsync(int resourceFileID, string keywords, string notes)
{
    ResourceFileResponse readResponse =
        await ResourceFileManager.ReadAsync(resourceFileID);
    readResponse.Keywords = keywords;
    readResponse.Notes = notes;
 
    try
    {
        ResourceFileResponse response =
            await ResourceFileManager.UpdateAsync(resourceFileID, readResponse);
    }
    catch (Exception ex)
    {
        string exception = $"An error occurred: {ex.Message}";
        Console.WriteLine(exception);
    }
}
Copy 
public async Task UpdateContentsAsync(int resourceFileID, string  fileContent)
{
    byte[] contents = Encoding.UTF8.GetBytes(fileContent);
    MemoryStream memoryStream = new MemoryStream(contents)
    {
        Position = 0
    };
 
    KeplerStream keplerStream = new KeplerStream(memoryStream);
 
    try
    {
        ResourceFileResponse response =
            await ResourceFileManager.UpdateAsync(resourceFileID, keplerStream);
    }
    catch (Exception ex)
    {
        string exception = $"An error occurred: {ex.Message}";
        Console.WriteLine(exception);
    }
}
Copy 
public async Task UpdateMetadataAndContentsAsync(string fileName, string fileContent, string keywords, string notes)
{
    ResourceFileRequest request = new ResourceFileRequest
    {
        Application = TestAppIdentifier,
        FileName = fileName,
        Keywords = string.Empty,
        Notes = string.Empty
    };
    request.Keywords = keywords;
    request.Notes = notes;
             
    MemoryStream memoryStream = new MemoryStream(Encoding.UTF8.GetBytes(fileContent))
    {
        Position = 0
    };
    KeplerStream stream = new KeplerStream(memoryStream);
 
    try
    {
        ResourceFileResponse response =
            await ResourceFileManager.UpdateAsync(TestAppIdentifier.ArtifactID, request, stream);
    }
    catch (Exception ex)
    {
        string exception = $"An error occurred: {ex.Message}";
        Console.WriteLine(exception);
    }  
}
Copy 
public async Task UpdateContentsWithKeyAsync(int resourceFileID, string fileContent, DateTime lastModifiedOn)
{
    ContentsResponse uploadContentsResponse = null;
 
    ResourceFileResponse readResponse =
        await ResourceFileManager.ReadAsync(resourceFileID);
 
    MemoryStream memoryStream = new MemoryStream(Encoding.ASCII.GetBytes(fileContent))
    {
        Position = 0
    };
 
    using (KeplerStream keplerStream = new KeplerStream(memoryStream))
    {
        //Upload Contents
        uploadContentsResponse = await ResourceFileManager.UploadContentsAsync(keplerStream, readResponse.FileName);
    }
 
    try
    {
        ResourceFileResponse response =
            await ResourceFileManager.UpdateAsync(resourceFileID, readResponse, uploadContentsResponse.ContentsKey, lastModifiedOn);
    }
    catch (Exception ex)
    {
        string exception = $"An error occurred: {ex.Message}";
        Console.WriteLine(exception);
    }
}

The following code samples illustrate how to use this endpoint to modify properties of a resource file using a previously uploaded contents. The contents must have been previously uploaded using the UploadContentsAsync endpoint.

Copy 
public async Task UpdateMetadataAndContentsWithKeyAsync(string fileName, string fileContent, string keywords, string notes)
{
    ContentsResponse uploadContentsResponse = null;
 
    ResourceFileRequest request = new ResourceFileRequest
    {
        Application = TestAppIdentifier,
        FileName = fileName,
        Keywords = string.Empty,
        Notes = string.Empty
    };
 
    request.Keywords = keywords;
    request.Notes = notes;
 
    MemoryStream memoryStream = new MemoryStream(Encoding.ASCII.GetBytes(fileContent))
    {
        Position = 0
    };
 
    using (KeplerStream keplerStream = new KeplerStream(memoryStream))
    {
        //Upload Contents
        uploadContentsResponse = await ResourceFileManager.UploadContentsAsync(keplerStream, fileName);
    }
 
    try
    {
        ResourceFileResponse response =
            await ResourceFileManager.UpdateAsync(TestAppIdentifier.ArtifactID, request, uploadContentsResponse.ContentsKey);
    }
    catch (Exception ex)
    {
        string exception = $"An error occurred: {ex.Message}";
        Console.WriteLine(exception);
    }
}
Copy 
public async Task UpdateMetadataWithKeyAsync(int resourceFileID, string keywords, string notes, Guid contentsKey, DateTime lastModifiedOn)
{
    ResourceFileResponse readResponse =
        await ResourceFileManager.ReadAsync(resourceFileID);
 
    readResponse.Keywords = keywords;
    readResponse.Notes = notes;
 
    try
    {
        ResourceFileResponse response =
            await ResourceFileManager.UpdateAsync(resourceFileID, readResponse, contentsKey, lastModifiedOn);
    }
    catch (Exception ex)
    {
        string exception = $"An error occurred: {ex.Message}";
        Console.WriteLine(exception);
    }
}

DeleteAsync

The following code samples illustrate how to use this endpoint to delete the Resource File.

Permissions

The following permissions are required to call this endpoint:

  • Instance - Object - Resource File - View
  • Instance - Object - Resource File - Delete
  • Instance - Admin Operations - View Admin Repository
Copy 
public async Task DeleteAsync(int resourceFileID)
{
    try
    {
        await ResourceFileManager.DeleteAsync(_resourceFile.ObjectIdentifier.ArtifactID);
    }
    catch (Exception ex)
    {
        string exception = $"An error occurred: {ex.Message}";
        Console.WriteLine(exception);
    }
}

DownloadContentsAsync

The following code samples illustrate how to use this endpoint to download the contents associated with a resource file.

Permissions

The following permissions are required to call this endpoint:

  • Instance - Object - Resource File - View
  • Instance - Admin Operations - View Admin Repository
Copy 
public async Task DownloadContentsAsync(int resourceFileID)
{
    try
    {
        using (IKeplerStream stream =
            await ResourceFileManager.DownloadContentsAsync(_resourceFile.ObjectIdentifier.ArtifactID)) ;
    }
    catch (Exception ex)
    {
        string exception = $"An error occurred: {ex.Message}";
        Console.WriteLine(exception);
    }
}

UploadContentsAsync

The following code sample illustrate how to use this endpoint to upload the file contents. This endpoint is used in conjunction with CreateAsync and UpdateAsync to implement workflows where the file contents are uploaded before creating the resource file. The resource file is NOT created or updated until a subsequent call to CreateAsync or UpdateAsync.

Permissions

The following permissions are required to call this endpoint:

  • Instance - Object - Resource File - View
  • Instance - Admin Operations - View Admin Repository
Copy 
public async Task UploadContentsAsync(IKeplerStream contents, string fileName)
{
    try
    {
        ContentsResponse response = await ResourceFileManager.UploadContentsAsync(contents, fileName);
    }
    catch (Exception ex)
    {
        string exception = $"An error occurred: {ex.Message}";
        Console.WriteLine(exception);
    }
}

UpsertAsync

The following code samples illustrate how to use this endpoint to create a resource file if it doesn't exist or update properties of an existing resource file. The uniqueness of a resource file is determined by the combination of Application GUID and File Name.

Permissions

The following permissions are required to call this endpoint:

  • Instance - Object - Resource File - Create
  • Instance - Object - Resource File - View
  • Instance - Object - Resource File - Edit
  • Instance - Object - Resource File - Delete
  • Instance - Object - Library Application - View
  • Instance - Admin Operations - View Admin Repository
Copy 
public async Task UpsertAsync_keplerStream(ObjectIdentifier applicationIdentifier, string fileName)
{
    string FileContents = "File content goes here ..";
             
    Stream stream = new MemoryStream(Encoding.ASCII.GetBytes(FileContents));
    KeplerStream keplerStream = new KeplerStream(stream);
                 
    try
    {
        ResourceFileResponse response =
            await ResourceFileManager.UpsertAsync(applicationIdentifier, fileName, keplerStream);
    }
    catch (Exception ex)
    {
        string exception = $"An error occurred: {ex.Message}";
        Console.WriteLine(exception);
    }
}
Copy 
public async Task UpsertAsync_ContentsKey(ObjectIdentifier applicationIdentifier, string fileName)
{
    string FileContents = "File content goes here ..";
 
    Guid ContentsKey = await UploadContentsAsync(FileContents);
 
    async Task<Guid> UploadContentsAsync(string fileContents)
    {
        using (Stream stream = new MemoryStream(Encoding.ASCII.GetBytes(fileContents)))
        using (KeplerStream keplerStream = new KeplerStream(stream))
        {
            ContentsResponse response = await ResourceFileManager.UploadContentsAsync(keplerStream, fileName);
            return response.ContentsKey;
        }
    }
 
    try
    {
        ResourceFileResponse response =
            await ResourceFileManager.UpsertAsync(applicationIdentifier, fileName, ContentsKey);
    }
    catch (Exception ex)
    {
        string exception = $"An error occurred: {ex.Message}";
        Console.WriteLine(exception);
    }
}

GetEligibleApplicationsAsync

The following code sample illustrate how to use this endpoint to retrieve a list of applications that can be associated to a resource file. It is used in the Relativity UI to populate a list for the user to choose from. The values returned in the list are subject to item-level security.

Permissions

The following permissions are required to call this endpoint:

  • Instance - Object - Library Application - View
  • Instance - Admin Operations - View Admin Repository
Copy 
public async Task GetEligibleApplicationsAsync()
{
    try
    {
        SecurableList<EligibleApplication> eligibleApps =
            await ResourceFileManager.GetEligibleApplicationsAsync();
    }
    catch (Exception ex)
    {
        string exception = $"An error occurred: {ex.Message}";
        Console.WriteLine(exception);
    }
}

PushResourceFiles

The Push Resource File method allows callers to upload one or more resource files using local file paths.

Copy 
public async Task  PushResourceFilesAsync()
{
    string[] resourceFileNames =
    {
        "PushResourceFiles.txt",
        "PushResourceFiles.xml",
        "PushResourceFiles.dll"
    };
 
    List<string> resourceFilePaths = resourceFileNames
        .Select(x => TestContext.CurrentContext.TestDirectory + @"\Environment\V1\ResourceFile\PushResourceFiles\" + x)
        .ToList();
 
    // The underlying implementation uses Upsert.  The following should create 3 new files.
    List<ResourceFileResponse> createResponses = await ResourceFileManager.PushResourceFilesAsync(TestAppIdentifier, resourceFilePaths);
}