Interface DocumentIdConverterInterface

The DocumentIdConverterInterface interface is used to get the part instance ids and geometric instance ids that are linked to a given document (referenced by its metadata document id).

The metadata document id is retrieved from a SearchDocumentResultInterface after a successful call to a search request (see Search).

The DocumentIdConverterInterface interfaces are created through the createDocumentIdConverter method.

The list of signals the DocumentIdConverterInterface may trigger is available in the DocumentIdConverterInterfaceSignal enumeration.

The conversion mechanism is triggered through the convert method. The result is not available right away, but the event DocumentIdConverterReady is triggered when the result of the DocumentIdConverterInterface is available. The result is available through the getConversionResult function.

Warning : there may be cases when the getConversionResult is not available such as when the DocumentIdConverterInterface is fetching data, i.e. when isRunning returns true, or when the DocumentIdConverterInterface has been cancelled, i.e. when isCancelled returns true.

A DocumentIdConverterInterface may be interrupted (cancelled) when the DocumentIdConverterInterface is fetching data and cancel is called. In such cases, the DocumentIdConverterCancelled signal is fired, and shortly after, DocumentIdConverterReady signal is fired, but getConversionResult will return undefined. Just call convert with another (or the same) metadata document id to trigger a new retrieval.

If you call multiple times convert before receiving the DocumentIdConverterReady, only one DocumentIdConverterReady will be sent with the content of the last call to convert.

/** 
 * Sample to explain how to make search requests.
 */
import {
    InfiniteEvent, SearchInterface, DocumentIdConverterInterface,
    VisibilityContextInterface, SearchDocumentResultInterface, DocumentIdResultInterface, DocumentIdConverterResultInterface,
    SearchInterfaceSignal, DocumentIdConverterInterfaceSignal, DataSessionInterface
} from 'generated/documentation/appinfiniteapi';

// the DataSessionInterface has been created previously and is connected
let lDataSession : DataSessionInterface;
// the filtering context for the whole DMU as been set previously
let lCurrentDMUVisibilityCtx : VisibilityContextInterface;

// the filtering context for the search has been set previously (can be lCurrentDMUVisibilityCtx)
let lSearchVisibilityCtx : VisibilityContextInterface;
// the string to search in documents
let lQueryString : string;
// the max number of results
const lMaxDocsToRetrieve : number = 50;

// create a search requester
const lSearch : SearchInterface = lDataSession.createSearch();

// to get actual results from a search request :
// the search requester gets result in the form of documents,
// in a second step, the user may enquire the server to know the 
// relevant `part instance ids`
// the DocumentIdConverterInterface is there to make the conversion between 
// a document id and the actual `part instances`
const lDocumentIdConverter : DocumentIdConverterInterface = lDataSession.createDocumentIdConverter();

// When the search is ready, we check for errors
// we may find all the `geometric instance ids` in the search result
// we get the first found document
// and find the relevant `part instance ids` and `geometric instance ids`
const onSearchReady = (pEvent: InfiniteEvent) : void =>
{
    const lSearchInterface: SearchInterface = <SearchInterface>(pEvent.emitter);
    // make sure the search in no more running
    if (lSearchInterface.isRunning()) {
        console.assert(false, 'this should not happen');
        return;
    }
    // and make sure no error
    if (lSearchInterface.getLastError().length > 0) {
        return;
    }

    // get all the `geometric instance ids` of the search request
    const lGeometricInstanceIds: Uint32Array | undefined = lSearchInterface.getGeometricInstanceIds();
    if (lGeometricInstanceIds !== undefined)
    {
        console.log('all the geometric instances concerned by the search:' + lGeometricInstanceIds.length);
    }

    // and get the documents (content is filtered by the last parameter of SearchInterface.search)
    const lSearchResult: Array<SearchDocumentResultInterface> | undefined = lSearchInterface.getSearchDocuments();
    if (lSearchResult) {
        console.log('Search finished: ' + lSearchResult.length + ' result(s)');
        // do we have all documents, or are there more that were not included due to the search results capped to lMaxDocsToRetrieve ?
        if (lSearchInterface.hasOtherResults())
        {
            // some GUI code there perhaps ?
            console.log('Search was capped to ' + lMaxDocsToRetrieve);
        }
        if (lSearchResult.length > 0) {
            // get the `part instance ids` of the first document
            const lDocumentId: number = lSearchResult[0].getDocumentId();
            const lIsInVisibility : boolean = lSearchResult[0].isInVisibilityCtx();
            let lVisibilityCtxToUse : VisibilityContextInterface;
            if (lIsInVisibility)
            {
                console.log('retrieve document in visibility : ' + lDocumentId);
                // we will try here to find instances only in the search filtering context
                // but depending on your needs, you may use lCurrentDMUVisibilityCtx to extend the 
                // result to the `part instances` of the whole DMU, it is up to you
                // or make 2 requests, one in the search ctx, the other outside, or ....
                lVisibilityCtxToUse = lSearchVisibilityCtx;
            }
            else {
                // this case cannot happen if the third parameter to search is true
                console.log('retrieve document outside visibility : ' + lDocumentId);
                // in order to get results, we will make the conversion in the whole DMU filtering context
                // since this concerns `part instances` outside the search filtering context
                lVisibilityCtxToUse = lCurrentDMUVisibilityCtx;
            }
            // find the `part instance ids` and `geometric instance ids` of this document
            lDocumentIdConverter.convert(lDocumentId, lVisibilityCtxToUse);
        }
    }
};

// When the document `part instances` are found
// we get the relevant `part instance ids` and `geometric instance ids` of the requested document
const onDocumentIdConverterReady = (pEvent: InfiniteEvent) : void =>
{
    const lEventDocumentIdConverter: DocumentIdConverterInterface = <DocumentIdConverterInterface>(pEvent.emitter);
    // make sure the search in no more running
    if (lEventDocumentIdConverter.isRunning()) {
        console.assert(false, 'this should not happen');
        return;
    }
    if (lEventDocumentIdConverter.getLastError().length > 0) {
        return;
    }
    const lResult: DocumentIdConverterResultInterface | undefined = lEventDocumentIdConverter.getConversionResult();
    if (lResult)
    {
        const lDocumentIdConverterInstances: Array<DocumentIdResultInterface> = lResult.getConvertedInstances();
        const lPartInstanceIds: Uint32Array = new Uint32Array(lDocumentIdConverterInstances.length);

        for (let i = 0; i < lDocumentIdConverterInstances.length; ++i) {
            lPartInstanceIds[i] = lDocumentIdConverterInstances[i].getPartInstanceId();
        }
        console.log('documents converted :');
        console.log('Convert part instances to geometric instance ids: ' + JSON.stringify(lPartInstanceIds));
    }
};

// what to do when we get the results ?
lDocumentIdConverter.addEventListener(DocumentIdConverterInterfaceSignal.DocumentIdConverterReady, onDocumentIdConverterReady);
lSearch.addEventListener(SearchInterfaceSignal.SearchReady, onSearchReady);

// make a search request, and only retrieve the "PartNumber" metadata of the result documents
// we will get all the documents of the DMU (third parameter : false), but will get a hint of the 
// documents inside lSearchVisibilityCtx
// imit the results to lMaxDocsToRetrieve documents maximum
lSearch.search(lQueryString, lSearchVisibilityCtx, false, lMaxDocsToRetrieve, ['PartNumber']);

/** 
 * Sample to explain how to make asynchronous search requests.
 */
import {
    SearchInterface, DocumentIdConverterInterface,
    VisibilityContextInterface, SearchDocumentResultInterface, DocumentIdResultInterface,
    AsyncSearchResult, AsyncResultReason, AsyncSearchResultContent, AsyncDocumentIdConverterResultInterfaceResult,
    DataSessionInterface,
} from 'generated/documentation/appinfiniteapi';

// the DataSessionInterface has been created previously and is connected
let lDataSession : DataSessionInterface;
// the filtering context for the whole DMU as been set previously
let lCurrentDMUVisibilityCtx : VisibilityContextInterface;

// the filtering context for the search has been set previously (can be lCurrentDMUVisibilityCtx)
let lSearchVisibilityCtx : VisibilityContextInterface;
// the string to search in documents
let lQueryString : string;
// the max number of results
const lMaxDocsToRetrieve : number = 50;

// create a search requester
const lSearch : SearchInterface = lDataSession.createSearch();

// to get actual results from a search request :
// the search requester gets result in the form of documents,
// in a second step, the user may enquire the server to know the 
// relevant `part instance ids`
// the DocumentIdConverterInterface is there to make the conversion between 
// a document id and the actual `part instances`
const lDocumentIdConverter : DocumentIdConverterInterface = lDataSession.createDocumentIdConverter();

const triggerSearchRequest = async () : Promise<any> =>
{
    // make a search request, and only retrieve the "PartNumber" metadata of the result documents
    // we will get all the documents of the DMU (third parameter : false), but will get a hint of the 
    // documents inside lSearchVisibilityCtx
    // limit the results to lMaxDocsToRetrieve documents maximum
    const lResult : AsyncSearchResult = await lSearch.asyncSearch(lQueryString, lSearchVisibilityCtx, false, lMaxDocsToRetrieve, ['PartNumber']);

    if (lResult.reason !== AsyncResultReason.ARR_Success || lResult.value === undefined)
    {
        console.assert(false, 'this should not happen');
        return;
    }
    // When the search is ready, we check for errors
    // we may find all the `geometric instance ids` in the search result
    // we get the first found document
    // and find the relevant `part instance ids` and `geometric instance ids`

    const lSearchContent : AsyncSearchResultContent = lResult.value;
    // get all the `geometric instance ids` of the search request
    const lGeometricInstanceIds: Uint32Array | undefined = lSearchContent.geometricInstanceIds;
    if (lGeometricInstanceIds !== undefined)
    {
        console.log('all the geometric instances concerned by the search:' + lGeometricInstanceIds.length);
    }

    // and get the documents (content is filtered by the last parameter of SearchInterface.search)
    const lSearchResult: Array<SearchDocumentResultInterface> | undefined = lSearchContent.searchDocuments;
    if (!lSearchResult) {
        console.assert(false, 'this should not happen');
        return;
    }
    console.log('Search finished: ' + lSearchResult.length + ' result(s)');
    // do we have all documents, or are there more that were not included due to the search results capped to lMaxDocsToRetrieve ?
    if (lSearchContent.hasOtherResults)
    {
        // some GUI code there perhaps ?
        console.log('Search was capped to ' + lMaxDocsToRetrieve);
    }
    if (lSearchResult.length <= 0) {
        console.log('no document found');
        return;
    }
    // get the `part instance ids` of the first document
    const lDocumentId: number = lSearchResult[0].getDocumentId();
    const lIsInVisibility : boolean = lSearchResult[0].isInVisibilityCtx();
    let lVisibilityCtxToUse : VisibilityContextInterface;
    if (lIsInVisibility)
    {
        console.log('retrieve document in visibility : ' + lDocumentId);
        // we will try here to find instances only in the search filtering context
        // but depending on your needs, you may use lCurrentDMUVisibilityCtx to extend the 
        // result to the `part instances` of the whole DMU, it is up to you
        // or make 2 requests, one in the search ctx, the other outside, or ....
        lVisibilityCtxToUse = lSearchVisibilityCtx;
    }
    else {
        // this case cannot happen if the third parameter to search is true
        console.log('retrieve document outside visibility : ' + lDocumentId);
        // in order to get results, we will make the conversion in the whole DMU filtering context
        // since this concerns `part instances` outside the search filtering context
        lVisibilityCtxToUse = lCurrentDMUVisibilityCtx;
    }
    // find the `part instance ids` and `geometric instance ids` of this document
    const lConversion : AsyncDocumentIdConverterResultInterfaceResult = await lDocumentIdConverter.asyncConvert(lDocumentId, lVisibilityCtxToUse);

    // When the document `part instances` are found
    // we get the relevant `part instance ids` and `geometric instance ids` of the requested document
    if (lConversion.reason !== AsyncResultReason.ARR_Success || lConversion.value === undefined)
    {
        console.assert(false, 'this should not happen');
        return;
    }
    const lDocumentIdConverterInstances: Array<DocumentIdResultInterface> = lConversion.value.getConvertedInstances();
    const lPartInstanceIds: Uint32Array = new Uint32Array(lDocumentIdConverterInstances.length);

    for (let i = 0; i < lDocumentIdConverterInstances.length; ++i) {
        lPartInstanceIds[i] = lDocumentIdConverterInstances[i].getPartInstanceId();
    }
    console.log('documents converted :');
    console.log('Convert part instances to geometric instance ids: ' + JSON.stringify(lPartInstanceIds));
}

triggerSearchRequest();

See

• DocumentIdConverterInterfaceSignal
• DocumentIdConverterResultInterface
• DocumentIdResultInterface