Documentation update for the `opslevel_filter` service

[vini-mw]

Provider documentation for the opslevel_filter resource does not cover how to create a filter targeting a custom property definition, use case which does not respect the documented use of the key_data input and not only that.

No guides or instructions are provided for using the resource in question where key = "properties", which, although it has similar in structure to the tags predicate object, it does not follow the same use.

To use a filter condition evaluating a custom property definition:

• the key_data input requires the UID of the property definition in question, instead of the name of the property definition
• the jq condition (type = "satisfies_jq_expression"), must contain a JSON-encoded value to perform the evaluation, where the expression will fail to evaluate otherwise

Note that the provider will throw the following error during the apply process if key_data points at the name of the property instead of the ID - with no real clues - where the terraform plan looks perfectly fine:

Took me quite a bit of debugging time to figure this out, would be great to add this use case in your list of code examples on the opslevel_filter page and document the use case further.

below is a terraform code example for clarification and visualisation purposes:

resource "opslevel_property_definition" "type" {
  name = "App Type"
  schema = jsonencode({
    type    = "string"
    pattern = "^[a-z0-9]+$"
  })
  allowed_in_config_files = false
  property_display_status = "visible"
}

resource "opslevel_filter" "workload" {
  name = "Service type Workload"

  predicate {
    key      = "properties"
    type     = "satisfies_jq_expression"
    key_data = opslevel_property_definition.type.id
    value    = ". == ${jsonencode("workload")}"
  }
}

[davidbloss]

Hi @vini-mw, what version of the provider are you using in this case? We just released v1.1.3 yesterday that might resolve this issue. Also, yes! This is an excellent use case to add to the opslevel_filter docs page! ❤️ Please let us know if this issue is fixed with v1.1.3 and if not, we'll dig into it

[vini-mw]

hi @davidbloss , im not saying this is an issue, im just saying the docs provided on the resource do not cover this use case example and its quite hard to figure out the input syntaxes when using custom propriety definitions thats all.

the error screen shot i posted (which was using the latest v1.1.3 provider v) is there only to show what happens if you try to feed in the key name of the property definition (eg: opslevel_property_definition.type.name) - as thats what one concludes should be done by following the docs and trying to replicate the instructions given for the tags use case. where the ID must be the one inputted instead.

if all inputs are set accordingly, as shown in my code example, for both the key_data input and the value in the case of a jq expression, everything works just fine. i am ultimately just asking for the docs to cover this, thats all 😇