Property Mappers#

Overview#

CtrlSync also provides property mapping within your M-Files vault application. Through the M-Files Admin UI, users can configure various PropertyMappers to automate the generation of M-Files object properties, based on basic information explicitly stored in the folder names, file names and Microsoft Graph data associated with any Microsoft Graph document.

PropertyMappers#

At the time of writing, CtrlSync supports the following PropertyMappers.

PathPropertyMapper#

The PathPropertyMapper allows mapping properties based on file paths. Users can configure this mapper through the M-Files Admin UI, specifying the property to be mapped, default values, aliases, the and mapping types (Any, First, Last, Exact, Regex). The file paths used are those found in Microsoft SharePoint or Microsoft Teams. For a Team, each Channel is given a folder in SharePoint, so it is e.g. possible to match the name of a Teams channel using the First type of PathPropertyMapper.

NameToPropertyMapper#

The NameToPropertyMapper enables mapping properties based on file names. Users can configure this mapper through the M-Files Admin UI, specifying the property to be mapped, default values, aliases, and the mapping types (Regex, StartsWith, EndsWith, Contains).

GraphPropertyMapper#

The GraphPropertyMapper facilitates property mapping based on Microsoft Graph properties. Users can configure this mapper through the M-Files Admin UI, specifying the Graph property to be mapped. Available Graph properties are:

  • Id, the unique ID property for the object in MS Graph

  • Name, the filename of the object in MS Graph

  • CreatedDateTime, the timestamp for when the object was created in MS Graph

  • LastModifiedDateTime, the timestamp for when the object was last modified in MS Graph

  • Size, the size in bytes of the object in MS Graph

  • WebUrl, the url to the object in MS Graph

E.g. the WebUrl can be used to provide a link to the document.

Source relation property#

It is possible for multiple objects in a vault to be matched by a property mapper. In order to restrict the amount of matches, you can specify a source relation property which will be checked on the matched object, ensuring that any matches must hold a lookup reference to the relevant graph source object.

Indirect Keys#

It is also possible to use an indirect key property for a property mapper. Rather than to look directly for a value list item’s name (for objects, this is their title property) or an alias, you can set the ‘Key Property’, which can be used to select properties available from the ‘Matching property’, based on the key property. An example key property could be an ID property that automatically increments. Then, a corresponding Name mapping could look for ID’s in the name of an incoming file.

Order of application#

CtrlSync will apply your property-mappings in the following order:

  1. Path mappings

  2. Name mappings

  3. Graph property mappings

The order within these categories are determined by the order of definition in the configuration.

This application order means that if a path mapping determines e.g. a document class to be ‘A’ and a name mapping determines it to be ‘B’, the name mapping is applied last and thus the resulting class for the document will be ‘B’ when checked into M-Files.

Configuring Property Mappers through M-Files Admin UI#

  1. Navigate to the Admin UI:

    • Log in to the M-Files Admin UI.

  2. Access Configuration Options:

    • Locate the configuration section related to the CtrlSync module.

  3. Create or Edit a Configuration:

    • Users can create a new configuration or edit an existing one.

  4. Choose a PropertyMapper:

    • Select the PropertyMapper you want to configure (PathPropertyMapper, NameToPropertyMapper, or GraphPropertyMapper).

  5. Configure Mapper Settings:

    • For each mapper, set the desired configuration options such as the property to map, default values, aliases, and mapping types.

  6. Save Configuration:

    • Save the configuration to apply the settings.

Mapping Process#

The PropertyMappers operates by interpreting the configuration set through the M-Files Admin UI. The chosen PropertyMapper implements the logic for deriving property values based on file paths, names, or Graph properties. They are applied whenever new files are received from Microsoft Graph.

For regex-based mappings, the PropertyMappers use a provided regex to extract values from the file path, and checks for matches based valid values for the M-Files property selected.

Additionally, the PropertyMappers consider user-defined aliases, allowing for static mappings of specific strings to predefined values. This is useful for defining short-hands that users of Microsoft Teams or SharePoint can incorporate into their file and folder names to ensure a particular mapping is performed.

Limitations#

  • Regular Expressions:

    • While the module supports regular expressions for path and name matching, complex or inefficient regex patterns may impact performance. Regular expressions are also unwieldy, make sure to test your regular expressions before using them (a good place to test could be regex101)!

  • Mapping Types:

    • The effectiveness of property mapping depends on the chosen mapping type and the structure of file paths or names. Choose the mapping type that best suits your use case.

  • Default Values:

    • Default values are applied only if the document does not already have a value for the mapped property.