Searching Documents

• Search criteria are initialized and a snapshot containing search results is retrieved.
• Metadata of each document found are printed.
• The first document found is downloaded into selected folder.

The Document Finder is the service responsible for searching for document matching given criteria and retrieving information including both system fields (properties) and user defined metadata fields.

The search criteria is a collection of conditions which consist of a search type, search operator and zero or more operands (whose type and meaning depend on both search type and operator). The following criteria can be used to find all documents containing some phrase in their name:

1
2
3
4
5
6
7
8

SearchCriteria criteria = new SearchCriteria();

SearchCondition condition = new SearchCondition();
condition.SearchType = SearchType.DocumentName;
condition.OperatorType = Operator.Contains;
condition.Operands = new object[] { "sample phrase" };

criteria.SearchConditions = new SearchCondition[] { condition };

Multiple search criteria can be combined using AND operator. The following criteria can be used to find documents with a specified schema and metadata field AND located in a specified folder:

1
2
3
4
5
6
7
8
9
10
11
12
13

SearchCriteria criteria = new SearchCriteria();

SearchCondition fieldCondition = new SearchCondition();
fieldCondition.SearchType = APIDemo.DocumentFinderService.SearchType.SchemaWithField;
fieldCondition.OperatorType = APIDemo.DocumentFinderService.Operator.Equal;
fieldCondition.Operands = new object[] { documentSchemaId, metadataFieldId, "sample value" };

SearchCondition folderCondition = new SearchCondition();
folderCondition.SearchType = APIDemo.DocumentFinderService.SearchType.FolderId;
folderCondition.OperatorType = APIDemo.DocumentFinderService.Operator.Equal;
folderCondition.Operands = new object[] { folderId };

criteria.SearchConditions = new SearchCondition[] { fieldCondition, folderCondition };

The GetDocumentsBySnapshot method creates a snapshot, which is basically a sorted list of documents which is stored in the database at the time of performing the search and identified using a GUID. The same method also retrieves information about a single page of documents from the snapshot and information about columns displayed in the specified view, so it provides all necessary information to populate a grid.

1
2
3
4
5
6
7
8
9

// Order by document name
ColumnSelector cc = new ColumnSelector();
cc.IsSystem = true;
cc.Id = (int)FileHold.Common.SystemFieldType.DocumentName;
ColumnSelector[] sortOrder = new ColumnSelector[] { cc };

Guid prevSnapshotId = Guid.Empty;
Guid snapshotId = Guid.Empty;
ColumnsWithValues columnsWithValues = finder.GetDocumentsBySnapshot( prevSnapshotId, ref snapshotId, "FLD", criteria, sortOrder, 0, 3 );

The viewContainerType parameter of the GetDocumentsBySnapshot method can be one of the following strings:

• "FLD" - folder list
• "SRT" - search results
• "VRT" - virtual folder
• "LNK" - linked document list
• "DTR" - document tray
• "FAV" - my favorites
• "CHO" - checked out documents
• "ALR" - document alerts
• "RMD" - document reminders
• "RAC" - recently accessed
• "RAD" - recently added
• "WRK" - workflow documents

There are three identifiers associated with each document returned in the ColumnsWithValues structures:

• DocumentId - identifies a single document in the library. It is shared by all versions of the document.
• DocumentVersionId - identifies a single version of a particular document. Usually it is associated with a single file in the repository (except for offline documents).
• MetadataVersionId - identifies a single metadata record of a particular version of a document. It is associated with a name, document schema and metadata values. Whenever the metadata of a document is modified, a new metadata version is created.

Usually when performing an operation on a single document, the MetadataVersionId is passed to the API, but some operations require a DocumentId or DocumentVersionId.

In order to download a document from the Document Repository a download token must be first obtained from the Library Manager. The download token is a randomly generated GUID which allows securely passing information between the two services.

1
2
3
4
5

int metadataVersionId = columnsWithValues.DocumentValues[ 0 ].MetadataVersionId;
Guid token = Guid.Empty;
long fileSize = 0;
string fileName = String.Empty;
documentManager.PrepareSingleDocumentToDownload( metadataVersionId, ref token, ref fileSize, ref fileName, ActionType.Downloaded );

The file size (in bytes) and name (with extension) are also retrieved. File can be downloaded entirely using one request, but for larger files it is recommended to download the file by smaller chunks. Also for better performance it is recommended to use the new DownloadFileDataChunk method rather than GetFileDataChunk.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

int transferedSize = 0;
string requestUrl = serverUrl + "DocumentRepository/DownloadHandler.ashx"
    + "?token=" + token + "&offset=" + transferedSize + "&size=" + chunkSize;
while ( transferedSize < fileSize )
{
    WebRequest request = WebRequest.Create( requestUrl );
    request.Method = "GET";
    request.Headers.Add( HttpRequestHeader.Cookie, "FHLSID=" + sessionId );
    HttpWebRequest httpRequest = request as HttpWebRequest;
    if ( httpRequest != null )
        httpRequest.AllowWriteStreamBuffering = false;
    WebResponse response = request.GetResponse();
    Stream responseStream = response.GetResponseStream();
    byte[] buffer = new byte[ 65536 ];
    while ( true )
    {
        int read = responseStream.Read( buffer, 0, buffer.Length );
        if ( read <= 0 )
            break;
        stream.Write( buffer, 0, read );
        transferedSize += read;
    }
    responseStream.Close();
}

Some operations can be performed on multiple documents at once; such operations are called batch operations. For example, several documents can be downloaded as a single zip file. To perform a batch operation, a selection must first be created. A selection is simply a subset of one or more search snapshots (for example search results, linked documents and document tray).

1
2
3
4
5
6
7
8
9
10

Selection selection = new Selection();

SnapshotSelection snapshotSelection = new SnapshotSelection();
snapshotSelection.SnapshotId = snapshotId;
snapshotSelection.DocumentIdList = new int[] { columnsWithValues.DocumentValues[ 0 ].DocumentId };
snapshotSelection.MetadataVersionIdList = new int[] { columnsWithValues.DocumentValues[ 0 ].MetadataVersionId };

selection.SnapshotSelection = new SnapshotSelection[ 1 ] { snapshotSelection };

Guid selectionId = documentManager.CreateSelection( selection );

A batch of documents can be downloaded in the same way as a single document, using a download token generated using the following method.

1
2
3
4

Guid token = Guid.Empty;
long fileSize = 0;
string fileName = String.Empty;
documentManager.PrepareDocumentsToDownload( selectionId, false, false, ref token, ref fileSize, ref fileName );