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:

1SearchCriteria criteria = new SearchCriteria();
2
3SearchCondition condition = new SearchCondition();
4condition.SearchType = SearchType.DocumentName;
5condition.OperatorType = Operator.Contains;
6condition.Operands = new object[] { "sample phrase" };
7
8criteria.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:

 1SearchCriteria criteria = new SearchCriteria();
 2
 3SearchCondition fieldCondition = new SearchCondition();
 4fieldCondition.SearchType = APIDemo.DocumentFinderService.SearchType.SchemaWithField;
 5fieldCondition.OperatorType = APIDemo.DocumentFinderService.Operator.Equal;
 6fieldCondition.Operands = new object[] { documentSchemaId, metadataFieldId, "sample value" };
 7
 8SearchCondition folderCondition = new SearchCondition();
 9folderCondition.SearchType = APIDemo.DocumentFinderService.SearchType.FolderId;
10folderCondition.OperatorType = APIDemo.DocumentFinderService.Operator.Equal;
11folderCondition.Operands = new object[] { folderId };
12
13criteria.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// Order by document name
2ColumnSelector cc = new ColumnSelector();
3cc.IsSystem = true;
4cc.Id = (int)FileHold.Common.SystemFieldType.DocumentName;
5ColumnSelector[] sortOrder = new ColumnSelector[] { cc };
6
7Guid prevSnapshotId = Guid.Empty;
8Guid snapshotId = Guid.Empty;
9ColumnsWithValues 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.

1int metadataVersionId = columnsWithValues.DocumentValues[ 0 ].MetadataVersionId;
2Guid token = Guid.Empty;
3long fileSize = 0;
4string fileName = String.Empty;
5documentManager.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.

 1int transferedSize = 0;
 2string requestUrl = serverUrl + "DocumentRepository/DownloadHandler.ashx"
 3    + "?token=" + token + "&offset=" + transferedSize + "&size=" + chunkSize;
 4while ( transferedSize < fileSize )
 5{
 6    WebRequest request = WebRequest.Create( requestUrl );
 7    request.Method = "GET";
 8    request.Headers.Add( HttpRequestHeader.Cookie, "FHLSID=" + sessionId );
 9    HttpWebRequest httpRequest = request as HttpWebRequest;
10    if ( httpRequest != null )
11        httpRequest.AllowWriteStreamBuffering = false;
12    WebResponse response = request.GetResponse();
13    Stream responseStream = response.GetResponseStream();
14    byte[] buffer = new byte[ 65536 ];
15    while ( true )
16    {
17        int read = responseStream.Read( buffer, 0, buffer.Length );
18        if ( read <= 0 )
19            break;
20        stream.Write( buffer, 0, read );
21        transferedSize += read;
22    }
23    responseStream.Close();
24}

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

 1Selection selection = new Selection();
 2
 3SnapshotSelection snapshotSelection = new SnapshotSelection();
 4snapshotSelection.SnapshotId = snapshotId;
 5snapshotSelection.DocumentIdList = new int[] { columnsWithValues.DocumentValues[ 0 ].DocumentId };
 6snapshotSelection.MetadataVersionIdList = new int[] { columnsWithValues.DocumentValues[ 0 ].MetadataVersionId };
 7
 8selection.SnapshotSelection = new SnapshotSelection[ 1 ] { snapshotSelection };
 9
10Guid 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.

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

Note that in most cases a selection is automatically destroyed after a successful batch operation so it doesn't need to be destroyed manually.