Filter by metadata

To filter items by metadata, the target platform must support metadata.

  • Rest API | If the target platform does not support metadata, the filter or text definition for the given connection will be ignored
  • User-Interface | If the target platform does not support metadata, the "Metadata Content" custom filter will be disabled

Not Supported

  • Filtering metadata is not supported when using the Metadata Import function
  • Any metadata content filters configured with Metadata Import will be ignored

User-Interface - Configuration

To filter metadata content, both the Advanced - Filtering and Advanced - Scripting options need to be enabled

Advanced - Metadata Mapping option should not be enabled

This example will excluded the item that is associated with value "Doe1" for the property value LName metadata column on the Source platform.

Format: 

[Property]="Text"

[Property]=Numeric Value

Metadata Mapping - Identify the Columns to Filter on

  • Populate the property name value that corresponds with metadata content column 

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

{
"transfer" : {
"metadata_map": {
                "schemas": [
                    {
                        "mappings": [
                            {
                                "source": {
                                    "property": {
                                        "name": "LName",
                                        "type": "string"
                                    }
                                },
                                "destination": {
                                    "property": {
                                        "name": "LName",
                                        "type": "string"
                                    }
                                }
                            }
                        ]
                    }
                ]
            }
}
}

Rest API - Configuration

For metadata filtering, the type attribute can use filter_metadata or metadata. Both configurations work the same. 

In addition, metadata filtering rules (rules block) can be defined using either a filter block or text attribute. Filters (filter blocks) include name, op, and value attributes, name is the metadata field name, op is one of the operators defined in the table below, and value is the metadata value used for the comparison. All three attributes are required, even with the empty and not_empty operators. When empty and not_empty operators are used, ensure to configure the value to represent an empty state (e.g. "value": ""). 

Text (text) values must be in a string format with quotes around the value escaped and brackets around the field name (e.g. "[ProtectionLevel]=\"Sensitive\""). Numeric values do not need to be contained in quotes. 

Operator (filter:op)

Description

Equivalent Text Operators

Filter Example

Text Example

eq

equals

=
"filter": { 
  "name": "ProtectionLevel", 
"op": "eq",
  "value": "Sensitive"
}
"[ProtectionLevel]=\"Sensitive\""
ne

not equals

<> or !=
"filter": { 
  "name": "ProtectionLevel", 
"op": "ne",
  "value": "Sensitive"
}
"[ProtectionLevel]!=\"Sensitive\""
lt

less than

<
"filter": { 
  "name": "ProtectionLevel", 
"op": "lt",
  "value": 100
}
"[ProtectionLevel]<100"
le

less than or equal to

<=
"filter": {
  "name": "ProtectionLevel", 
  "op": "le",
  "value": 100
}
"[ProtectionLevel]<=100"
gt

greater than

>
"filter": {
  "name": "ProtectionLevel", 
  "op": "gt",
  "value": 100
}
"[ProtectionLevel]>100"
ge

greater than or equal to

>=
"filter": {
  "name": "ProtectionLevel", 
  "op": "ge",
  "value": 100
}
"[ProtectionLevel]>=100"
starts_with

starts with

= with * appended to the end of the value

"filter": {
  "name": "Author", 
  "op": "starts_with",
  "value": "John"
}
"text": "[Author]=\"John*\""
not_starts_with

does not start with

<> or !=

"filter": {
  "name": "Author", 
  "op": "not_starts_with",
  "value": "John"
}
"text": "[Author]!=\"John*\""
ends_with

ends with

= with * prepended to the beginning of the value

"filter": {
  "name": "Author", 
  "op": "ends_with",
  "value": "Anderson"
}
"text": "[Author]=\"*Anderson\""
not_ends_with

does not end with

<> or !=

"filter": {
  "name": "Author", 
  "op": "not_ends_with",
  "value": "Anderson"
}
"text": "[Author]!=\"*Anderson\""
contains

contains

=
"filter": {
  "name": "Author", 
  "op": "contains",
  "value": "John"
}
"text": "[Author]=\"*John*\""
not_contains

does not contain

<> or !=

"filter": {
  "name": "Author", 
  "op": "not_contains",
  "value": "John"
}
"text": "[Author]!=\"*John*\""
in

includes all the values

IN
"filter": {
  "name": "ProtectionLevel", 
  "op": "in",
  "value": ["Not Sensitive"]
}
"text": "[ProtectionLevel] IN (\"Not Sensitive\")"
not_in

does not include all the values

NOT IN
"filter": {
  "name": "ProtectionLevel", 
  "op": "not_in",
  "value": ["Sensitive", "Highly Sensitive"]
}
"text": "[ProtectionLevel] NOT IN (\"Sensitive\", \"Highly Sensitive\")"
empty

the value is empty

<>"*" or !="*"

"filter": {
  "name": "Author", 
  "op": "empty",
  "value": ""
}
"text": "[Author]!=\"*\""
not_empty

the value is not empty

="*" 
"filter": {
  "name": "Author", 
  "op": "not_empty",
  "value": ""
}
"text": "[Author]=\"*\""

Example 1

The following example will exclude any files on the source from being transferred to the destination that have a metadata field named "ProtectionLevel" with value "Sensitive".

{
  "name": "Metadata Content Filter Include Value Equal To [Value]",
  "kind": "transfer",
  "transfer": {
    "audit_level": "trace",
    "transfer_type": "copy",
    "source": {
        "connection": {"id": "{{source_cloud_connection}}"},
            "target": {
                "path": "/Source Folder"
        }
    },
    "destination": {
        "connection": {"id": "{{destination_cloud_connection}}"},
            "target": {
                "path": "/Destination Folder"
        }
  },
  "filter": {
    "source": [{
      "action": "include",
        "rules": [{
            "filter": {
                "name": "ProtectionLevel",
                "op": "eq",
                "value": "Sensitive"
            },
        "type": "filter_metadata"
        }],
        "type": "filter_rule"
        }
      ]
    }
  },
    "schedule": {
        "mode": "manual"
    },
    "stop_policy": {
        "on_success": 5,
        "on_failure": 5,
        "on_execute": 25
    },
    "category": {
      "name": "Report Name"
    }
}

Example 2

The following example results in the same filtering as Example 1. Here the filter block is replaced by the equivalent text attribute.

{
    ...
    "transfer": {
        ...
        "filter": {
            "source": [{
                    "action": "exclude",
                    "rules": [{
                        "text": "[ProtectionLevel]=\"Sensitive\"",
                        "type": "filter_metadata"                  
                    }],
                    "type": "filter_rule"
                }
            ]
        }
    }
    ...
}

Related Links