Interface InstanceMetadataInterface

The InstanceMetadataInterface tells about the information linked to a part instance, be it a node or a leaf.

The InstanceMetadataInterface is included in the PartInstanceInfoInterface or ChildrenPartInstanceInfoInterface, which is retrieved by an IdCardGetterInterface or ChildrenIdCardGetterInterface. In the case of PartInstanceInfoInterface, the retrieved data is actually an AncestryInstanceMetadataInterface that provides also the World Matrix of the part instance.

There is a unique instantiation chain of part instances, starting from the root part instance to a specific part instance (this is the definition of a part instance). The InstanceMetadataInterface is one element of such a chain.

The InstanceMetadataInterface shows the metadata documents and the properties of a part instance.

The InstanceMetadataInterface is organized by document types (part metadata documents, link metadata documents, part instance metadata documents).

Such metadata documents may be :

• part metadata documents : these documents are shared among all the instances of the same part (a bolt for example).
• link metadata documents : when defining a child of a part instance, a metadata document may be set to define the link between the two part instances. The child part instance includes the link metadata document (as such, the root part instance of the DMU cannot have a link metadata document and thus its link metadata document is empty).
• instance metadata documents : the given part instance may have specific information attached to it (not shared by all the instances of the same part, as a serial number for example).

All these documents follow the same pattern :

• A string document id, which is a unique string inside the DMU that identifies the document.
• A string type.
• The actual metadata object.

Please remember that the part instances that include specific metadata documents cannot be queried by their string id but by their integer ids (see Search).

NB : link metadata documents are used for computing the configurations (WorkingSetInterface, Main concepts) of the DMU. A configuration is a set of included or excluded effectivities. Any link that satisfies the requirements in term of effectivities is included in the configuration, meaning the child part instance of the link will be available in the given configuration. If not, the given child part instance will not be included. Here link metadata documents only expose their internal content and not the effectivities.

Warning : the documents content may change depending on the given configuration, as such, some fields may appear or not depending on the chosen configuration.

The InstanceMetadataInterface include the documents of the part instance hierarchy if included in a PartInstanceInfoInterface, if included in a ChildrenPartInstanceInfoInterface, then the documents are the one of the children of the requested part instance. The IdCardGetterInterface.retrieveIdCard and ChildrenIdCardGetterInterface.retrieveChildrenIdCard will return the same number of PartInstanceInfoInterface than the number of part instances that were queried.

A chain, or children are exposed as an array of InstanceMetadataInterface with the size of the chain of the part instances, or the number of children of a part instance. In the case of a chain, the first item in the chain is the root part instance, the last item is the part instance that was queried by IdCardGetterInterface.retrieveIdCard. In the case of a children list, the order is irrelevant.

The InstanceMetadataInterface also shows if the given part instance has any attached document (see DocumentContentGetterInterface and AttachedDocumentInfoInterface) attached to it, if it is displayable.

Here is an example of an InstanceMetadataInterface :

{
    "annotationsViews": [],
    "attachedDocuments": [],
    "classid": 5522,
    "depth": 0,
    "instanceDocuments": [],
    "instanceid": 1554,
    "isDisplayable": true,
    "isLeaf": false,
    "linkDocuments": [],
    "linkid": 2721,
    "linkid_string": "",
    "localXForm": [
        1,
        0,
        0,
        0,
        0,
        1,
        0,
        0,
        0,
        0,
        1,
        0,
        0,
        0,
        0,
        1
    ],
    "parentInstanceid": 0,
    "partid": 1697,
    "partid_string": "struct_Link&Go.CATProduct_0d73b92e93248dfac0154598c28935a3758829107ceac3695801e13242405006",
    "partDocuments": [
        {
            "documentid": "partmd_Link&Go_CATProduct",
            "docSecurityTags": [],
            "docContent": {
                "metadata": {
                    "psconverter:type": "assembly",
                    "AppliUUID": "78b0c783 00000ad4 50d060f2 0000003c",
                    "filename": "Link&Go.CATProduct",
                    "PartNumber": "Link&Go",
                    "Original filename": "Link&Go.CATProduct",
                    "configured_metadata": [
                        {
                            "conf_int": 1,
                            "conf_info": "version_A"
                        },
                        {
                            "conf_int": 2,
                            "conf_info": "version_B"
                        },
                        {
                            "conf_int": 3,
                            "conf_info": "No conf restriction"
                        },
                        {
                            "conf_int": 4,
                            "conf_info": "version_hybrid"
                        },
                        {
                            "conf_int": 5,
                            "conf_info": "version_C_with_test"
                        }
                    ],
                    "Input Format and Emitter": "CATIA V5R19 SP0 HF0",
                    "UUID": "78b0c78300000ad450d060f200000406",
                    "Name": "Link&Go"
                },
                "id": "partmd_Link&Go_CATProduct",
                "type": "partmetadata",
                "ts": 1678959046
            }
        },
        {
            "documentid": "restricted_md_doc",
            "docSecurityTags": [
                "L&G_restricted"
            ],
            "docContent": {
                "metadata": {
                    "restrictedinfo": "dummy doc put on each file root, with a restriction tag"
                },
                "id": "restricted_md_doc",
                "type": "partmetadata",
                "ts": 1682673398
            }
        }
    ],
    "securityTags": [],
    "statusFlag": 160,
    "subLeafMin": 1,
    "subLeafMax": 1553,
    "cumulatedXForm": [
        1,
        0,
        0,
        0,
        0,
        1,
        0,
        0,
        0,
        0,
        1,
        0,
        0,
        0,
        0,
        1
    ]
}
Copy

The InstanceMetadataInterface may be queried by the following code :

/** 
 * Sample to illustrate the use of an IdCardGetterInterface with the parsing of
 * PartInstanceInfoInterface to display some information about a part instance.
 */
import {
    WorkingSetInterface, IdCardGetterInterface, IdCardGetterInterfaceSignal,
    InfiniteEvent, PartInstanceInfoInterface, DataSessionInterface, AncestryInstanceMetadataInterface, DocumentContentInterface
} from 'generated_files/documentation/appinfiniteapi';

// the DataSessionInterface has been created previously and is connected
let lDataSession : DataSessionInterface;
// created previously
let lVisibilityContext : WorkingSetInterface;
// the `part instance id` to get
let lPartInstanceId : number;
// what to do when we have retrieved id card information ?
let onIdCardReady : (_pEvent: InfiniteEvent, _pCallbackData: Object | undefined) => void;

// create an idCardGetter
const lIdCardGetterInterface : IdCardGetterInterface = lDataSession.createIdCardGetter();
// what to do when result is ready ?
lIdCardGetterInterface.addEventListener(IdCardGetterInterfaceSignal.IdCardReady, onIdCardReady);

// onIdCardReady will be called when data is available
onIdCardReady = (_pEvent: InfiniteEvent, _pCallbackData: Object | undefined) : void =>
{
    if (lIdCardGetterInterface.getLastError() !== undefined) {
        // do nothing in case of error
        // perhaps some GUI code ?
    }
    const lPartInstanceInfos : Array<PartInstanceInfoInterface> | undefined = lIdCardGetterInterface.getPartInstanceInfos();
    if (!lPartInstanceInfos || lPartInstanceInfos.length !== 1)
    {
        // no data (isCancelled ?)
        return;
    }
    // we required only one `part instance`, as such, only one result should be retrieved
    // iterate over the instantiation chain, but take the first chain since one `part instance` retrieved
    const lCurrentChain : PartInstanceInfoInterface = lPartInstanceInfos[0];

    // iterate over the metadata infos
    const lAllInstanceMetadata : Array<AncestryInstanceMetadataInterface> = lCurrentChain.getAncestorInstanceInfos();

    // number of items 
    const lNbAncestors : number = lAllInstanceMetadata.length;
    const lOffsetToPartInstance : number = lNbAncestors - 1;
    // we get the `part` metadata of the given `part instance` (and not their parents - grand parents) => lNbAncestors-1
    const lCurrentInstanceInfos : AncestryInstanceMetadataInterface = lAllInstanceMetadata[lOffsetToPartInstance];
    const lPartMetadataDocuments : Array<DocumentContentInterface> = lCurrentInstanceInfos.getPartMetadataDocuments();
    if (lPartMetadataDocuments.length === 0)
    {
        console.log('this part instance has no part metadata documents');
        return;
    }
    // and we only care with the first document, but many documents may be attached
    const lPartMetadata : Object = lPartMetadataDocuments[0].getDocumentContent();
    // some fancy output
    console.log(JSON.stringify(lPartMetadata));

    // get the visibility info in order to get information about the `part instance`
    if (lCurrentInstanceInfos.isDisplayable())
    {
        console.log('this part instance is displayable');
    }
};

// trigger the retrieval
lIdCardGetterInterface.retrieveIdCard(lPartInstanceId, lVisibilityContext);

Copy

or :

/** 
 * Sample to illustrate the use of an ChildrenIdCardGetterInterface with the parsing of
 * PartInstanceInfoInterface to display some information about a part instance.
 */
import {
    ChildrenIdCardGetterInterface, ChildrenIdCardGetterInterfaceSignal,
    InfiniteEvent, ChildrenPartInstanceInfoInterface, DataSessionInterface,
    InstanceMetadataInterface, DocumentContentInterface, WorkingSetInterface
} from 'generated_files/documentation/appinfiniteapi';

// the DataSessionInterface has been created previously and is connected
let lDataSession : DataSessionInterface;
// created previously
let lWorkingSet : WorkingSetInterface;
// the `part instance id` to get
let lPartInstanceId : number;
// what to do when we have retrieved id card information ?
let onChildrenIdCardReady : (_pEvent: InfiniteEvent, _pCallbackData: Object | undefined) => void;

// create an ChildrenIdCardGetter
const lChildrenIdCardGetterInterface : ChildrenIdCardGetterInterface = lDataSession.createChildrenIdCardGetter();
// what to do when result is ready ?
lChildrenIdCardGetterInterface.addEventListener(ChildrenIdCardGetterInterfaceSignal.ChildrenIdCardReady, onChildrenIdCardReady);

// onChildrenIdCardReady will be called when data is available
onChildrenIdCardReady = (_pEvent: InfiniteEvent, _pCallbackData: Object | undefined) : void =>
{
    if (lChildrenIdCardGetterInterface.getLastError() !== undefined) {
        // do nothing in case of error
        // perhaps some GUI code ?
    }
    const lPartInstanceInfos : Array<ChildrenPartInstanceInfoInterface> | undefined = lChildrenIdCardGetterInterface.getPartInstanceInfos();
    if (!lPartInstanceInfos || lPartInstanceInfos.length !== 1)
    {
        // no data (isCancelled ?)
        return;
    }
    // we required only one `part instance`, as such, only one result should be retrieved
    // iterate over the instantiation chain, but take the first chain since one `part instance` retrieved
    const lCurrentChildren : ChildrenPartInstanceInfoInterface = lPartInstanceInfos[0];

    // iterate over the children metadata infos
    const lAllInstanceMetadata : Array<InstanceMetadataInterface> = lCurrentChildren.getChildrenInstanceInfos();

    // number of items 
    const lNbChildren : number = lAllInstanceMetadata.length;
    if (lNbChildren <= 0)
    {
        console.log('this part instance is a leaf');
        return;
    }
    // take the last child
    const lChildInstanceOffset : number = lNbChildren - 1;
    const lLastChildInstanceInfos : InstanceMetadataInterface = lAllInstanceMetadata[lChildInstanceOffset];
    // we get the `part` metadata of the last child of the `part instance`
    const lPartMetadataDocuments : Array<DocumentContentInterface> = lLastChildInstanceInfos.getPartMetadataDocuments();
    if (lPartMetadataDocuments.length === 0)
    {
        console.log('this part instance has no part metadata documents');
        return;
    }
    // and we only care with the first document, but many documents may be attached
    const lPartMetadata : Object = lPartMetadataDocuments[0].getDocumentContent();
    // some fancy output
    console.log(JSON.stringify(lPartMetadata));

    // get the visibility info in order to get information about the `part instance`
    if (lLastChildInstanceInfos.isDisplayable())
    {
        console.log('the last child of the part instance is displayable');
    }
};

// trigger the retrieval
lChildrenIdCardGetterInterface.retrieveChildrenIdCard(lPartInstanceId, lWorkingSet);

Copy

With async calls :

/** 
 * Sample to illustrate the asynchronous use of an IdCardGetterInterface with the parsing of
 * PartInstanceInfoInterface to display some information about a part instance.
 */
import {
    WorkingSetInterface, IdCardGetterInterface, AsyncPartInstanceInfoResult,
    AsyncResultReason, PartInstanceInfoInterface, DataSessionInterface, AncestryInstanceMetadataInterface, DocumentContentInterface
} from 'generated_files/documentation/appinfiniteapi';

// the DataSessionInterface has been created previously and is connected
let lDataSession : DataSessionInterface;
// created previously
let lVisibilityContext : WorkingSetInterface;
// the `part instance id` to get
let lPartInstanceId : number;
// what to do when we have retrieved id card information ?

// create an idCardGetter
const lIdCardGetterInterface : IdCardGetterInterface = lDataSession.createIdCardGetter();

const fetchIdCard = async () : Promise<void> =>
{
    // trigger the retrieval
    const lResult : AsyncPartInstanceInfoResult = await lIdCardGetterInterface.asyncRetrieveIdCard(lPartInstanceId, lVisibilityContext);
    if (lResult.reason !== AsyncResultReason.ARR_Success) {
        // do nothing in case of error
        // perhaps some GUI code ?
    }

    const lPartInstanceInfos : Array<PartInstanceInfoInterface> | undefined = lIdCardGetterInterface.getPartInstanceInfos();
    console.assert(lPartInstanceInfos === lResult.value);
    if (!lPartInstanceInfos || lPartInstanceInfos.length !== 1)
    {
        // no data (isCancelled ?)
        return;
    }
    // we required only one `part instance`, as such, only one result should be retrieved
    // iterate over the instantiation chain, but take the first chain since one `part instance` retrieved
    const lCurrentChain : PartInstanceInfoInterface = lPartInstanceInfos[0];

    // get all metadata hierarchy
    const lAllInstanceMetadata : Array<AncestryInstanceMetadataInterface> = lCurrentChain.getAncestorInstanceInfos();

    // number of items 
    const lNbAncestors : number = lAllInstanceMetadata.length;
    const lOffsetToPartInstance : number = lNbAncestors - 1;

    // we get the `part` metadata of the given `part instance` (and not their parents - grand parents) => lNbAncestors-1
    const lCurrentInstanceInfos : AncestryInstanceMetadataInterface = lAllInstanceMetadata[lOffsetToPartInstance];
    const lPartMetadataDocuments : Array<DocumentContentInterface> = lCurrentInstanceInfos.getPartMetadataDocuments();
    if (lPartMetadataDocuments.length === 0)
    {
        console.log('this part instance has no part metadata documents');
        return;
    }
    // and we only care with the first document, but many documents may be attached
    const lPartMetadata : Object = lPartMetadataDocuments[0].getDocumentContent();
    // some fancy output
    console.log(JSON.stringify(lPartMetadata));

    // get the visibility info in order to get information about the `part instance`
    if (lCurrentInstanceInfos.isDisplayable())
    {
        console.log('the last child of the part instance is displayable');
    }
};

fetchIdCard();

Copy

or :

/** 
 * Sample to illustrate the asynchronous use of an ChildrenIdCardGetterInterface with the parsing of
 * PartInstanceInfoInterface to display some information about a part instance.
 */
import {
    ChildrenIdCardGetterInterface, AsyncChildrenPartInstanceInfoResult,
    ChildrenPartInstanceInfoInterface, AsyncResultReason, DataSessionInterface,
    InstanceMetadataInterface, DocumentContentInterface, WorkingSetInterface
} from 'generated_files/documentation/appinfiniteapi';

// the DataSessionInterface has been created previously and is connected
let lDataSession : DataSessionInterface;
// created previously
let lWorkingSet : WorkingSetInterface;
// the `part instance id` to get
let lPartInstanceId : number;

// create an ChildrenIdCardGetter
const lChildrenIdCardGetterInterface : ChildrenIdCardGetterInterface = lDataSession.createChildrenIdCardGetter();

const retrieveIdCard = async () : Promise<void> =>
{
    // trigger the retrieval
    const lResult : AsyncChildrenPartInstanceInfoResult = await lChildrenIdCardGetterInterface.asyncRetrieveChildrenIdCard(lPartInstanceId, lWorkingSet);

    if (lResult.reason !== AsyncResultReason.ARR_Success || lResult.value === undefined)
    {
        // do nothing in case of error
        // perhaps some GUI code ?
        return;
    }
    const lPartInstanceInfos : Array<ChildrenPartInstanceInfoInterface> = lResult.value;
    // we required only one `part instance`, as such, only one result should be retrieved
    // iterate over the instantiation chain, but take the first chain since one `part instance` retrieved
    const lCurrentChildren : ChildrenPartInstanceInfoInterface = lPartInstanceInfos[0];

    // iterate over the children metadata infos
    const lAllInstanceMetadata : Array<InstanceMetadataInterface> = lCurrentChildren.getChildrenInstanceInfos();
    // number of items 
    const lNbChildren : number = lAllInstanceMetadata.length;
    if (lNbChildren <= 0)
    {
        console.log('this part instance is a leaf');
        return;
    }
    // take the last child
    const lChildInstanceOffset : number = lNbChildren - 1;
    const lLastChildInstanceInfos : InstanceMetadataInterface = lAllInstanceMetadata[lChildInstanceOffset];
    // we get the `part` metadata of the last child of the `part instance`
    const lPartMetadataDocuments : Array<DocumentContentInterface> = lLastChildInstanceInfos.getPartMetadataDocuments();

    if (lPartMetadataDocuments.length === 0)
    {
        console.log('this part instance has no part metadata documents');
        return;
    }
    // and we only care with the first document, but many documents may be attached
    const lPartMetadata : Object = lPartMetadataDocuments[0].getDocumentContent();
    // some fancy output
    console.log(JSON.stringify(lPartMetadata));

    // get the visibility info in order to get information about the `part instance`
    if (lLastChildInstanceInfos.isDisplayable())
    {
        console.log('the last child of the part instance is displayable');
    }
};

retrieveIdCard();

Copy

The InstanceMetadataInterface documents contains fields that are included in the AttributesDictionaryInterface. Just look for the given attribute in the AttributesDictionaryInterface.

Any field may have the given type, an array of the given type or null (depending on AttributeInfoInterface.getAttributeType). Any field may have not be included in the AttributesDictionaryInterface, in this case, such metadata cannot be filtered, since it cannot be indexed. Such data that cannot be indexed can be found in the DocumentContentInterface.getNonIndexedContent fields.

See

• PartInstanceInfoInterface
• ChildrenPartInstanceInfoInterface