Filter Object Definition

In the Finout Virtual Tags API documentation, the structure of the filters object can be explained by starting with simpler usage and then detailing more complex scenarios:

1. Simple Conditions Without Logical Operators:

   • Use direct condition keys for single-condition requirements.

     Example JSON:

     {
       "to": "Asaf",
       "filters": {
         "costCenter": "AWS",
         "key": "aws_account_name",
         "displayName": "Account Name",
         "operator": "oneOf",
         "value": [
           "004a533177",
           "0371d7d3bf"
         ]
       }

2. Complex Conditions with Nested Logical Operators:

   • AND and OR keys represent logical operators for grouping multiple conditions.

   • You can nest multiple layers of AND and OR for intricate conditional logic.

     Example JSON:

     {
       "filters": {
         "AND": [
           {
             "OR": [
               {
                 "costCenter": "AWS",
                 "key": "condition1",
                 "operator": "equals",
                 "value": "value1"
               },
               {
                 "costCenter": "AWS",
                 "key": "condition2",
                 "operator": "equals",
                 "value": "value2"
               }
             ]
           },
           {
             "costCenter": "AWS",
             "key": "condition3",
             "operator": "equals",
             "value": "value3"
           }
         ]
       }
     }

Filter operator object definition

Field	Type	Description	Example Value
costCenter	string	The cost center associated with the filter.	"AWS" , "GCP", "Kubernetes" , "Snowflake" , "Virtual Tags" , "Datadog" , "Azure" , "Custom Cost"
operator	string	The comparison operator to apply for the filter (e.g., "oneOf", "equal", "greaterThan").	"oneOf"
value	array	An array of values to use the operator against.	["Amazon Web Services EMEA KFIR"]
key	string	The key in Finout filters. For non-unique keys or specific keys (finrichment), a transform function is applied as follows: finrichment is returned as f_ plus the Kubernetes key and the node/pod label is returned as nl_<key>/pl_<key>	“1233442423423” “finrichment_usage_type” -> “f_usage_type” Use Finout’s Query Language API to get a list of the available keys.

Note: "displayName" is retrieved in the GET API call. This parameter should not be sent in the POST/PUT API calls.

Supported Operators

The following operators can be used in the rule definitions to specify filtering conditions:

• oneOf: Matches the resource value if it is equal to any of the specified values.

• notOneOf: Matches the resource value if it is not equal to any of the specified values.

• is: Matches the resource value if it is exactly equal to the specified value.

• isNot: Matches the resource value if it is not equal to the specified value.

• contains: Matches the resource value if it contains the specified substring.

• notContains: Matches the resource value if it does not contain the specified substring.

• exists: Matches the resource value if it exists (not null or empty).

• notExists: Matches the resource value if it does not exist (null or empty).

Example rule configuration

{
  "requestId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "accountId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "name": "Test",
  "rules": [
    {
      "to": "Finout",
      "filters": {
        "AND": [
          {
            "costCenter": "AWS",
            "key": "aws_account_name",
            "displayName": "Account Name",
            "operator": "oneOf",
            "value": ["Finout"]
          },
          {
            "costCenter": "AWS",
            "key": "f_operation",
            "displayName": "API Operation",
            "operator": "oneOf",
            "value": ["AAAA"]
          },
          {
            "costCenter": "Virtual Tags",
            "key": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
            "displayName": "Cost per Customer",
            "operator": "oneOf",
            "value": ["Abra"]
          }
        ]
      }
    },
    {
      "to": "Finout-Subaccount",
      "filters": {
        "costCenter": "AWS",
        "key": "aws_account_name",
        "displayName": "Account Name",
        "operator": "oneOf",
        "value": ["Finout-Subaccount"]
      }
    },
    {
      "to": "AWS",
      "filters": {
        "costCenter": "Global",
        "key": "cost_center_type",
        "displayName": "Cost Center",
        "operator": "oneOf",
        "value": ["AWS"]
      }
    }
  ],
  "category": "Project",
  "createdBy": "User",
  "updatedBy": "User",
  "createdAt": "Wed Mar 13 2024 15:40:46 GMT+0000 (Greenwich Mean Time)",
  "updatedAt": "Thu Mar 21 2024 10:49:17 GMT+0000 (Greenwich Mean Time)",
  "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "defaultValue": "Untagged"
}

In the example above, the rule engine is configured with two rules. The first rule filters resources with costCenter equal to "virtualTag" and type equal to "virtual_tag" using the oneOf operator, matching the values "Aged", "AllArid", "BidBare", "Calm", or "Coal". The matching resources are then directed to the "Application" destination.

The second rule filters resources with costCenter equal to "virtualTag" and type equal to "virtual_tag" using the contains operator, matching the value "Jet". The matching resources are directed to the "Backend" destination.

Example rules and filter conditions

{
  "requestId": "xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "accountId": "xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "name": "exampleName",
  "rules": [
    {
      "to": "Tag1",
      "filters": {
        "AND": [
          {
            "OR": [
              {
                "costCenter": "Center1",
                "key": "service_key",
                "displayName": "Service Name",
                "operator": "oneOf",
                "value": [
                  "ServiceA",
                  "ServiceB",
                  "ServiceC"
                ]
              },
              {
                "costCenter": "Center1",
                "key": "account_name_key",
                "displayName": "Account Name",
                "operator": "oneOf",
                "value": [
                  "AccountX",
                  "AccountY"
                ]
              }
            ]
          },
          {
            "costCenter": "Center1",
            "key": "service_key",
            "displayName": "Service Name",
            "operator": "oneOf",
            "value": [
              "ServiceA",
              "ServiceB"
            ]
          }
        ]
      }
    },
    {
      "to": "Tag2",
      "filters": {
        "costCenter": "Center2",
        "key": "account_name_key",
        "displayName": "Account Name",
        "operator": "oneOf",
        "value": [
          "AccountZ",
          "AccountW"
        ]
      }
    }
  ],
  "createdBy": "CreatorName",
  "updatedBy": "UpdaterName",
  "createdAt": "Date and Time",
  "updatedAt": "Date and Time",
  "id": "xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "defaultValue": "DefaultTag"
}

In the provided example, the third rule illustrates complex conditional logic using both "AND" and "OR" operators. This rule's filter conditions demonstrate the logic: "(condition 1 AND condition 2) OR (condition 1 AND condition 3)". This showcases how multiple conditions can be intricately grouped within "AND" or "OR" relationships, allowing for the creation of sophisticated filtering logic for virtual tags. This example serves to show the versatility and depth of the filtering system in handling diverse and complex tagging scenarios.