Entity Filtering

1. Overview

The TECHNIA Exchange Hub Connector supports advanced entity filtering capabilities that allow you to exclude specific entities and relationships from being transferred between 3DEXPERIENCE and TECHNIA Exchange based on configurable filter expressions.

This filtering system provides a powerful script-like language for defining exclusion rules based on entity types, attributes, and relationship contexts.

2. Key Features

  • Directional Filtering: Configure different filters for 3DX→TX and TX→3DX transfers

  • Entity & File Filtering: Filter both entities and their associated files

  • Relationship Context: Filter entities based on their relationships to other entities

  • File Name Patterns: Filter files based on name patterns, extensions, and content matching

  • Wildcard Support: Use * and ? wildcards in attribute value matching

  • Multiple Operators: Support for equality, contains, starts/ends with operations

  • Flexible Grammar: Simple yet powerful expression syntax

3. Filter Expression Syntax

3.1. Basic Grammar

EXPRESSION := SELECTOR OPERATOR VALUE
SELECTOR := (relationship[REL_TYPE].)?entity[ENTITY_TYPE].attribute[ATTR_NAME] |
           (relationship[REL_TYPE].)?entity[ENTITY_TYPE].file.name |
           file.name
OPERATOR := == | != | contains | !contains | startsWith | endsWith
VALUE := "string" | number | boolean
REL_TYPE := * | relationship name

3.2. Components

3.2.1. Selectors

  • entity: Refers to the entity being evaluated (main entity or relationship target)

  • relationship[TYPE]: Specifies relationship context

    • relationship[*]: Any relationship type

    • relationship[Related Document]: Specific relationship type

3.2.2. Entity Type Filtering

For 3DEXPERIENCE → TX transfers: * entity[VPMReference]: Parts and Assemblies * entity[Document]: Documents * entity[Drawing]: Technical Drawings

For TX → 3DEXPERIENCE transfers: * entity[Item]: Parts and Assemblies * entity[Document]: Documents

3.2.3. Attribute Access

  • .attribute[AttributeName]: Access entity attributes

    • .attribute[Title]: Document/entity title

    • .attribute[Name]: Entity name

    • .attribute[State]: Entity state

    • .attribute[Description]: Entity description

3.2.4. Operators

Operator Description Example

==

Equals (with wildcard support)

"DOC-*"

!=

Not equals (with wildcard support)

"TEMP-*"

contains

Contains text (case insensitive)

"draft"

!contains

Does not contain text

"obsolete"

startsWith

Starts with text

"DOC"

endsWith

Ends with text

".pdf"

3.2.5. Wildcards

  • *: Matches any sequence of characters

  • ?: Matches any single character

4. Configuration

4.1. Enabling Filtering

To enable entity filtering:

  1. Navigate to your extension configuration in TIF Cloud Administration

  2. Go to Include in Structure > Entity Filtering

  3. Check the Enable Entity Filtering option

4.2. Directional Filters

4.2.1. 3DEXPERIENCE to TECHNIA Exchange

Configure filters for entities being transferred from 3DX to TX using the 3DX → TX Filters field.

Use 3DEXPERIENCE terminology: * Entity types: VPMReference, Document, Drawing * Relationship types: Related Document, Reference Document, SpecificationDocument

Example:

relationship[Related Document].entity[Document].attribute[Title] startsWith "DOC-"

4.2.2. TECHNIA Exchange to 3DEXPERIENCE

Configure filters for entities being transferred from TX to 3DX using the TX → 3DX Filters field.

Use TECHNIA Exchange terminology: * Entity types: Item, Document * Relationship types: EBOM, MBOM, Part Specification

Example:

entity[Item].attribute[Name] startsWith "TEMP-"

4.3. Multiple Filters

Multiple filter expressions can be combined using semicolons (;). If any filter matches, the entity will be excluded.

5. Filter Examples

5.1. Exclude Documents by Title Pattern

Exclude all documents with titles starting with "DOC-":

relationship[*].entity[Document].attribute[Title] != "DOC-*"

5.2. Exclude Temporary Parts

Exclude VPM References with names starting with "TEMP-":

entity[VPMReference].attribute[Name] != "TEMP-*"

5.3. Exclude Released Documents

Exclude documents in "Released" state:

relationship[*].entity[Document].attribute[State] != "Released"

5.4. Exclude Draft Documents

Exclude documents containing "draft" in their description:

relationship[*].entity[Document].attribute[Description] contains "draft"

5.5. File Filtering Examples

Exclude files containing "Specification" in the filename:

file.name contains "Specification"

Exclude XML files from documents:

relationship[*].entity[Document].file.name endsWith ".xml"

Exclude temporary files from parts:

relationship[*].entity[VPMReference].file.name startsWith "temp_"

Exclude backup files (multiple patterns):

file.name endsWith ".bak"; file.name endsWith ".tmp"

5.6. Complex Multi-Filter Example

Exclude documents starting with "DOC-" AND temporary parts AND specification files:

tx.filter.3dx-to-tx=relationship[*].entity[Document].attribute[Title] != "DOC-*";entity[VPMReference].attribute[Name] != "TEMP-*";file.name contains "Specification"

6. Use Cases

6.1. Document Management

6.1.1. Exclude Test Documents

relationship[*].entity[Document].attribute[Title] != "TEST-*"

6.1.2. Exclude Specific File Types

relationship[*].entity[Document].attribute[Title] endsWith ".tmp"

6.1.3. Exclude Documents by State

relationship[Related Document].entity[Document].attribute[State] != "Obsolete"

6.2. Part Management

6.2.1. Exclude Prototype Parts

entity[VPMReference].attribute[Name] != "PROTO-*"

6.2.2. Exclude Parts by Description

entity[VPMReference].attribute[Description] contains "for testing only"

6.3. Relationship-Specific Filtering

6.3.1. Exclude Specification Documents Only

relationship[SpecificationDocument].entity[Document].attribute[Title] != "SPEC-*"

6.3.2. Exclude Reference Documents by Pattern

relationship[Reference Document].entity[Document].attribute[Name] != "REF-OBSOLETE-*"

7. Configuration in TIF Cloud

  1. Navigate to the extension configuration in TIF Cloud Administration

  2. Go to Include in Structure > Entity Filtering

  3. Check Enable Entity Filtering

  4. Configure directional filters:

    • Use 3DX → TX Filters field for 3DEXPERIENCE to TECHNIA Exchange transfers

    • Use TX → 3DX Filters field for TECHNIA Exchange to 3DEXPERIENCE transfers

  5. Enter filter expressions using the syntax described above

  6. Multiple expressions can be separated by semicolons

Use the correct entity and relationship terminology for each direction (see Directional Filters section above).

8. Testing and Validation

The filtering system includes built-in validation and logging:

  • Invalid filter expressions are logged as errors

  • Filter evaluation results are logged at debug level

  • Use the tx.api.debug=true setting to enable detailed filtering logs

8.1. Testing Filter Expressions

Before deploying filters in production, test them with sample data:

// Example test in JavaScript console
const testResult = FilterHelper.getInstance().testFilterExpression(
    'relationship[*].entity[Document].attribute[Title] != "DOC-*"',
    sampleEntity,
    sampleRelationship
);
console.log(testResult.message);

9. Troubleshooting

9.1. Common Issues

9.1.1. Filter Not Applied

  • Verify Enable Entity Filtering is checked in the configuration

  • Check filter expression syntax

  • Ensure you’re using the correct entity types for the transfer direction

  • Review logs for parsing errors

9.1.2. Unexpected Filtering Behavior

  • Enable Debug setting in the Endpoints configuration to see evaluation details

  • Verify entity attribute names match exactly (case sensitive)

  • Check entity types are correct for the transfer direction

  • Confirm you’re using the right system’s terminology (3DX vs TX)

9.1.3. Performance Considerations

  • Filters are evaluated for each entity and relationship

  • Complex filters with many expressions may impact performance

  • Filter initialization is optimized to occur only when filtering is enabled and first used

  • Test filter performance with representative data volumes

9.2. Debug Logging

Enable debug logging to troubleshoot filtering issues:

  1. Navigate to your extension configuration

  2. Go to Endpoints

  3. Check the Debug setting

This will provide detailed logs showing: * Filter expression parsing results * Entity evaluation details * Exclusion decisions and reasons

10. Best Practices

  1. Start Simple: Begin with simple single-attribute filters

  2. Test Thoroughly: Validate filters with sample data before production use

  3. Use Specific Types: Always specify entity types when possible

  4. Document Filters: Maintain documentation of active filters and their purpose

  5. Monitor Performance: Watch for performance impact with complex filter sets

  6. Use Descriptive Patterns: Make wildcard patterns as specific as possible

11. Migration Notes

When upgrading from earlier versions without filtering support:

  1. Filtering is disabled by default (Enable Entity Filtering is unchecked)

  2. No existing functionality is affected when filtering is disabled

  3. Enable filtering gradually and test with non-critical data first

  4. Existing configuration settings remain unchanged