> For the complete documentation index, see [llms.txt](https://docs.realmjoin.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.realmjoin.com/pt/automatizacao/runbooks/runbook-customization.md).

# Personalização de runbooks

Adapte os runbooks genéricos do RealmJoin às necessidades dos seus ambientes.

## Visão geral

A implementação de runbooks do RealmJoin oferece capacidades de personalização ao autor de um runbook ou ao administrador de um ambiente, para que possam:

* Hospedar parâmetros e modelos específicos do cliente/Tenant
* Oferecer elementos de UI como seletores de utilizador ou listas suspensas
* Apresentar explicações legíveis por humanos dos parâmetros
* Ocultar elementos de UI desnecessários

<figure><img src="https://686519968-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MkrcM7cKOpXKri1kVrh%2Fuploads%2FmVmZrDFgG1ShkZlo1Fbe%2Fimage.png?alt=media&amp;token=39876732-3578-41d2-acf1-8571bb941e68" alt=""><figcaption></figcaption></figure>

As personalizações podem ser incluídas no próprio runbook e/ou armazenadas na instância do RealmJoin Portal do cliente. Por predefinição, tentaremos oferecer valores predefinidos sensatos nos runbooks oferecidos no [GitHub](https://github.com/realmjoin/realmjoin-runbooks).

Alguns runbooks virão com exemplos de como configurar modelos específicos do cliente, como especificar localizações do Office para a integração do utilizador.

### Formato

A personalização pode ser definida (por ordem decrescente de prioridade)

* Bloco de JSON em [definições do RealmJoin Portal](https://portal.realmjoin.com/settings/runbooks-customizations), substituindo o comportamento predefinido do runbook
* Bloco de JSON no cabeçalho de um runbook

Adicionalmente (com a menor prioridade)

* por parâmetro no cabeçalho do runbook
* por parâmetro no bloco param do runbook (usando o módulo RJRb Helper)

Algumas funcionalidades (como modelos) só estão disponíveis em formato JSON. Algumas funcionalidades (como criar um seletor de utilizador) só estão disponíveis ao especificar um tipo de dados no bloco param. Pode combinar vários tipos de personalização para obter melhores resultados.

## Bloco Param do Runbook

O RealmJoin Portal analisa o bloco param do PowerShell de um runbook para determinar quais campos de entrada renderizar. Quando possível, também validará as entradas de acordo com o tipo .NET indicado para uma variável.

Os seguintes tipos de dados são atualmente compreendidos:

* `[bool]`, `[boolean]` - apresentará um alternador binário
* `[string]` - apresentará uma caixa de texto para introduzir qualquer entrada alfanumérica
* `[int]` - apresentará uma caixa de texto, permitindo apenas entradas numéricas
* `[DateTime]`, `[DateTimeOffset]` - Apresentará um seletor de data/hora

Pode aplicar modificadores padrão do PowerShell aos parâmetros. O RealmJoin Portal, em particular, entenderá se especificar `[Parameter(Mandatory = $true)]` para indicar um parâmetro obrigatório e garantir que esses parâmetros sejam preenchidos.

Quando possível, o RealmJoin Portal também lerá e apresentará os valores predefinidos na UI.

Tenha em atenção que os valores predefinidos do runbook podem ser substituídos por personalizações. Além disso, os parâmetros podem ser completamente ocultados por personalizações.

### Personalizar parâmetros

Para poder personalizar parâmetros, certifique-se de incluir o módulo PS Runbook Helper do RealmJoin no seu runbook:

`#Requires -Modules @{ModuleName = "RealmJoin.RunbookHelper"; ModuleVersion = "0.6.0" }`

Pode então incluir `[ValidateScript( { Use-RJInterface ... } )]` instruções nas definições dos parâmetros. Por exemplo, o seguinte criará um seletor de utilizador, permitindo escolher um utilizador do Entra ID e passará o respetivo ID de objeto como string para o runbook.

```powershell
param(
    [ValidateScript( { Use-RJInterface -DisplayName "Assign device to this user (optional)" -Type Graph -Entity User } )]
    [string] $AssignedUserId = ""
)
```

Vamos analisar isto passo a passo. `[ValidateScript...]` é um modificador para o próximo parâmetro definido no bloco param. Neste caso, a variável `$AssignedUserId`.

`Use-RJInterface` faz parte do nosso [RealmJoin Runbook Helper](https://github.com/realmjoin/RealmJoin.RunbookHelper) módulo PowerShell. Permite especificar que tipo de entrada espera utilizando `-Type` e `-Entity`, se isso ainda não estiver totalmente definido pelo tipo da variável.

`-DisplayName` permite passar ao RealmJoin Portal um aviso / descrição legível por humanos para este parâmetro.

#### Recursos do Graph

No exemplo acima, a origem da informação é o MS Graph, conforme descrito por `-Type Graph`. Para o MS Graph, use `-Entity` para especificar que tipo de recurso está à espera. As entidades disponíveis são `Utilizador`, `Grupo`, `Dispositivo`. Isto produzirá um seletor para utilizadores, grupos ou dispositivos no Entra ID indicado.

O seletor inclui uma pesquisa rápida, para localizar facilmente o recurso necessário.

![Exemplo de seletor](https://686519968-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MkrcM7cKOpXKri1kVrh%2Fuploads%2Fgit-blob-0c393c4ea73a77b34da2c678b0712a6556ed3bc2%2Frunbook-customization-img2.png?alt=media)

Atualmente, não é possível selecionar várias opções usando um seletor.

Por predefinição, um seletor do MS Graph devolverá o ID do objeto. Se precisar, por exemplo, do nome principal do utilizador em vez disso, certifique-se de incluir "name" como sufixo no nome da sua variável. Assim, basicamente, para obter o ID de um utilizador, nomeie o parâmetro `$userid`. Se quiser um UPN, nomeie-o `$username`.

#### Filtragem do Graph

Se estiver a usar um seletor baseado no MS Graph, também pode especificar `-Filter` e usar um [filtro ODATA](https://docs.microsoft.com/en-us/graph/query-parameters?context=graph%2Fapi%2F1.0\&view=graph-rest-1.0#filter-parameter) para limitar os objetos oferecidos no seletor.

O exemplo seguinte listará apenas grupos do Entra ID que começam por "LIC\_".

```powershell
param(
    [Parameter(Mandatory = $true)]
    [ValidateScript( { Use-RJInterface -Type Graph -Entity Group -Filter "startswith(DisplayName, 'LIC_')" -DisplayName "License group" } )]
    [String] $GroupID_License
)
```

Pode preparar filtros e reutilizá-los em vários scripts usando o [armazenamento central](#graph-filters). Neste caso, basta referenciar o filtro pelo nome usando `-Filter "ref:LicenseGroup"`, onde `ref:` indica para procurar um filtro armazenado.

```powershell
param(
    [Parameter(Mandatory = $true)]
    [ValidateScript( { Use-RJInterface -Type Graph -Entity Group -Filter "ref:LicenseGroup" } )]
    [String] $GroupID_License
)
```

Este exemplo específico `ref:LicenseGroup` está disponível por predefinição sem qualquer configuração adicional.

![filtro ODATA](https://686519968-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MkrcM7cKOpXKri1kVrh%2Fuploads%2Fgit-blob-4913ddfbc3324fc7a3522de2bc6887e8d2745e35%2Frunbook-customization-img3.png?alt=media)

## Cabeçalho do Runbook

O Portal pode analisar a [ajuda baseada em comentários](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_comment_based_help?view=powershell-5.1) secção, se existir.

Eis um exemplo:

```powershell
<#
  .SYNOPSIS
  (Des)atribuir uma licença a um utilizador através da filiação em grupos.

  .DESCRIPTION
  (Des)atribuir uma licença a um utilizador através da filiação em grupos. Descrição mais detalhada...

  .PARAMETER DefaultGroups
  Lista de grupos separada por vírgulas para atribuir. p. ex. "DL Sales,LIC Internal Product"

  .NOTES
  Permissões:
  MS Graph (API):
  - User.Read.All
  - GroupMember.ReadWrite.All 
  - Group.ReadWrite.All

  .INPUTS
  RunbookCustomization: {
        "Parameters": {
            "UserName": {
                "Hide": true
            },
            "Remove": {
                "DisplayName": "Atribuir ou remover licença",
                "SelectSimple": {
                    "Atribuir licença ao utilizador": false,
                    "Remover licença do utilizador": true
                }
            }
        }
    }
#>
```

`.SYNOPSIS` - Dê uma descrição muito breve da função do seu runbook. Isto será apresentado na lista de runbooks disponíveis.

`.DESCRIPTION` - Dê uma descrição da função do seu runbook. Pode conter um pouco mais de detalhe, pois isto será apresentado na execução do runbook / diálogo de parâmetros.

`.PARAMETER` - Tem de ser seguido pelo nome de um parâmetro. Permite-lhe dar uma explicação detalhada da entrada esperada para o parâmetro em questão.

`.INPUTS` - Pode conter um bloco de personalização do runbook baseado em JSON.

`.NOTES` - Não é analisado / renderizado. Use este espaço para indicar quais permissões e requisitos existem para o seu runbook.

`.EXAMPLE` - Não é analisado / renderizado. Pode conter um exemplo de personalização baseada em JSON para usar no armazenamento de dados do RealmJoin no seu Tenant. Podem ser exemplos de como criar modelos, por exemplo, para diferentes fluxos de trabalho ou classes de utilizadores.

## Personalização baseada em JSON

### Armazenamento central

Cada Tenant Azure pode alojar um armazenamento de dados "Runbook Customizations", encontrado em <https://portal.realmjoin.com/settings/runbooks-customizations> .

O formato é JSON com comentários, permitindo vírgulas finais. Atualmente, existem três secções relevantes, `Definições`, `Modelos`, `Runbooks`.

```json
{
    "Settings": {
    },
    "Templates": {
    },
    "Runbooks": {
    }
}
```

### Secção Runbooks

`Runbooks` é analisada pelo portal ao iniciar um runbook. Se existir uma secção com o nome do atual Runbook de Azure Automation, o seu conteúdo será usado para personalizar a interface apresentada ao utilizador.

Assuma o seguinte runbook de demonstração simples, chamado `rjgit-device_demo-runbook-customizing`.

```powershell
<#
  .SYNOPSIS
  Demonstrar personalização de runbook

  .DESCRIPTION
  Demonstrar personalização de runbook, como lista suspensa/seletor
#>

#Requires -Modules @{ModuleName = "RealmJoin.RunbookHelper"; ModuleVersion = "0.6.0" }

param(
    [string] $DeviceId,
    [bool] $ExtraWorkflow = $true,
    [int] $ExtraWorkflowTime = 15
)

"## A fazer coisas ao dispositivo '$DeviceID'"

# Fluxo de trabalho complicado altamente opcional
if ($ExtraWorkflow) {
    "## A executar meditação..."
    Start-Sleep -Seconds $ExtraWorkflowTime
}
```

Se não for personalizado, será apresentado assim na interface:

![Demo - antes](https://686519968-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MkrcM7cKOpXKri1kVrh%2Fuploads%2Fgit-blob-931b958f4b949268736f6ff3f174913cf56adcf7%2Frunbook-customization-img4.png?alt=media)

Ideias:

* Como este runbook é iniciado a partir do contexto de um dispositivo no portal, o `$DeviceId` é informação redundante para um utilizador. Já sei em que dispositivo estou a trabalhar.
* O que acontece se ativar ou desativar o "Extra Workflow"? Preciso de pensar no "Extra Workflow Time" se desativar o "Extra Workflow"?

Vamos melhorar isso. O seguinte JSON de exemplo no armazenamento central modificará a UI do runbook.

```json
{
    "Runbooks": {
        "rjgit-device_demo-runbook-customizing": {
            "ParameterList": [
                {
                    "Name": "DeviceId",
                    "Hide": true
                }, 
                {
                    "Name": "ExtraWorkflow",
                    "Hide": true
                },
                {
                    "Name": "ExtraWorkflowTime",
                    "DisplayName": "Quanto tempo para meditar?",
                },
                {
                    "DisplayName": "Executar Extra Workflow",
                    "DisplayBefore": "ExtraWorkflowTime",
                    "Select": {
                        "Options": [
                            {
                                "Display": "Executar meditação (opcional)",
                                "Customization": {
                                    "Default": {
                                        "ExtraWorkflow": true
                                    }
                                }
                            },
                            {
                                "Display": "Ignorar a atenção plena do dispositivo",
                                "Customization": {
                                    "Default": {
                                        "ExtraWorkflow": false
                                    },
                                    "Hide": [
                                        "ExtraWorkflowTime"
                                    ]
                                }
                            }
                        ],
                        
                    },
                    "Default": "Ignorar a atenção plena do dispositivo"
                }
            ]
        }
    }
}
```

Pode usar a mesma notação / funcionalidades no seu [cabeçalho do runbook](#runbook-header).

#### ParameterList

Cada parâmetro tem a sua própria secção em `ParameterList`. [Modificadores](#modifiers) permitem alterar o comportamento desse parâmetro.

O resultado terá este aspeto:

![Demo - depois de oculto](https://686519968-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MkrcM7cKOpXKri1kVrh%2Fuploads%2Fgit-blob-4ae4e681371ad29f076063c5f1925a0cb8113872%2Frunbook-customization-img5.png?alt=media)

Escolher o fluxo de trabalho adicional apresentará (desocultará) mais parâmetros:

![Demo - depois de desoculto](https://686519968-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MkrcM7cKOpXKri1kVrh%2Fuploads%2Fgit-blob-7960cf8309d8bbdf12ab1539c073714211715411%2Frunbook-customization-img6.png?alt=media)

Isto mostra menos desordem em comparação com antes de aplicar a personalização. Ao mesmo tempo, mais informação sobre as alternativas de "Extra Workflow" fica disponível para o utilizador. Além disso, o utilizador só se preocupará agora com "Extra Workflow Time" se isso for relevante.

A alteração da visibilidade desse campo foi feita usando um `"Customization"` bloco dentro de uma das `"Select"` opções. Atualmente, pode ter no máximo um desses `"Customization"` blocos ativos de cada vez.

Como pode ver, o parâmetro `$DeviceId` está completamente oculto. Isto é feito definindo o `"Hide": true` para este parâmetro.

Os parâmetros podem ter um `DisplayName`Oferecemos um `DisplayName` legível por humanos para substituir `$ExtraWorkflowTime` na UI. Veja outros [modificadores](#modifiers) para mais detalhes.

Pode inserir parâmetros "sem nome" (sem o `Name` declaração) como a secção "Executar Extra Workflow", se quiser oferecer elementos de UI sem devolver diretamente um valor. Isto é normalmente usado apenas em conjunto com `Select`.

#### Select

Usámos `Select`, para apresentar uma lista de `Options` numa lista suspensa. Cada opção pode `Display` texto, ou acionar uma `Customization`, como definir `Hide` ou um `Default` valor noutros parâmetros. No nosso exemplo, usámo-lo para (des)ocultar `$ExtraWorkflowTime` e substituir `$ExtraWorkflow`o seu valor.

`$ExtraWorkflowTime` é, assim, mostrado apenas quando relevante e o alternador binário `$ExtraWorkflow` é agora substituído por alternativas com significado do ponto de vista do utilizador.

No caso de um `Select` para um parâmetro nomeado, cada opção deve ter um `"ParameterValue": "..."` para passar ao runbook. Pode colocar um `"ShowValue: false"` dentro do `Select` bloco para mostrar apenas a lista suspensa e não um campo para o valor resultante do parâmetro.

Exemplo de parâmetro nomeado:

```json
{
    "Name": "ExtraWorkflow",
    "DefaultValue": true,
    "DisplayName": "Executar Extra Workflow",
    "DisplayBefore": "ExtraWorkflowTime",
    "Select": {
        "Options": [
            {
                "Display": "Executar meditação (opcional)",
                "ParameterValue": true
            },
            {
                "Display": "Ignorar a atenção plena do dispositivo",
                "ParameterValue": false,
                "Customization": {
                    "Hide": [
                        "ExtraWorkflowTime"
                    ]
                }
            }
        ],
        "ShowValue": false
    }
}
```

Os `Default` / `DefaultValue` A instrução DefaultValue no parâmetro também especifica o estado inicial da lista suspensa. No caso de um parâmetro sem nome, use o `DisplayName` da opção pretendida; caso contrário, indique um valor de retorno predefinido, como "true" ou "false" ou alguma string.

#### Parâmetros

Se tiver apenas parâmetros nomeados, pode usar o formato ligeiramente mais curto `Parâmetros` em vez de `ParameterList`.

Para um exemplo, veja SelectSimple

#### SelectSimple

Se todo o poder de um `Select` não for necessário e quiser apenas oferecer uma lista de valores possíveis numa lista suspensa (sem aplicar personalização adicional), pode usar `SelectSimple`.

`SelectSimple` só pode ser usado para parâmetros nomeados.

Exemplo:

```json
{
    "Runbooks": {
        "rjgit-device_demo-runbook-customizing": {
            "Parameters": {
                "DeviceId": {
                    "Hide": true
                }, 
                "ExtraWorkflow": {
                    "Name": "ExtraWorkflow",
                    "DisplayName": "Executar Extra Workflow",
                    "Default": false,
                    "SelectSimple": {
                        "Executar meditação (opcional)": true,
                        "Ignorar a atenção plena do dispositivo": false
                    }
                },
                "ExtraWorkflowTime": {
                    "DisplayName": "Quanto tempo para meditar?"
                }
            }
        }
    }
}
```

A maior diferença (para além de ser muito mais curto) em relação ao nosso exemplo anterior é que `$ExtraWorkflowTime` está sempre visível.

#### Modificadores

Cada parâmetro pode ter um ou mais dos seguintes modificadores:

* `"DisplayName": "text"` - Apresentar "text" como nome do parâmetro na UI
* `"Hide": true / false` - Ocultar este parâmetro
* `"Mandatory": true / false` - Exigir que este parâmetro seja preenchido
* `"ReadOnly": true / false` - Impedir que este parâmetro seja alterado em relação ao seu valor predefinido
* `"DefaultValue": "..."` - Definir um valor predefinido para este parâmetro. (Também pode usar `Default` em vez disso.)
* `"GraphFilter": "startswith(DisplayName, 'LIC_')"` - ver [Filtragem do Graph](#graph-filtering)
* `"AllowEdit": true / false` - Impedir a edição manual deste parâmetro. (combine isto com modelos)

### Definições

`Definições` permite armazenar dados de configuração como nomes de Storage Account Azure num local central, mantendo-os separados dos seus runbooks.

Pode aceder a valores individuais a partir de um param-Block de um runbook usando `Use-RJInterface`.

Vamos analisar este exemplo de param-block de um runbook:

```powershell
param(
    [ValidateScript( { Use-RJInterface -Type Setting -Attribute "RJReport.StorageAccount.ResourceGroup" } )]
    [string] $ResourceGroupName,
    [ValidateScript( { Use-RJInterface -Type Setting -Attribute "RJReport.StorageAccount.StorageAccountName" } )]
    [string] $StorageAccountName,
    [ValidateScript( { Use-RJInterface -Type Setting -Attribute "RJReport.StorageAccount.LinkExpiryDays" } )]
    [int] $LinkExpiryDays = 6
)
```

O Portal tentará preencher previamente cada parâmetro com valores do armazenamento central, se existirem. Isto também funciona se o parâmetro tiver sido ocultado na UI.

Um possível JSON no armazenamento de dados para este runbook seria:

```json
{
    "Settings": {
        "RJReport": {
            "StorageAccount": {
                "ResourceGroup": "rj-runbooks-01",
                "StorageAccountName": "rjrbexports01"
            }
        }
    }
}
```

O elemento em falta `LinkExpiryDays` simplesmente não será preenchido previamente na UI, pelo que o parâmetro mantém o seu valor predefinido de `6`.

Um bloco runbook na `Runbooks` secção pode conter o seu próprio `Definições`. Para cada valor, o portal procura primeiro aí e só depois no global `Definições`, então runbooks individuais podem usar valores diferentes. Veja [Use uma Storage Account diferente para runbooks individuais](https://docs.realmjoin.com/pt/automatizacao/runbooks/runbook-report-settings.md#use-a-different-storage-account-for-individual-runbooks) para um exemplo.

### Modelos

`Modelos` use referências JSON para importar dados - por exemplo, uma longa lista de localizações de escritório - ao usar um `Select` declaração.

Isso permite manter uma personalização neutra/reutilizável/separada dos dados reais.

Vamos pegar o exemplo de integração de novos usuários. Você pode ter múltiplas opções disponíveis para departamentos ou localizações de escritório, em que atribuir uma localização de escritório também exige um determinado endereço, país, estado etc.

O exemplo a seguir de uma personalização de runbook usa a `$ref` dentro do `Runbooks` seção para referenciar/importar uma subárvore da `Modelos` seção. Atente para os `$id`/`$values` palavras-chave. Tenha em mente que `$id`/`$values` precisam ser definidos antes de serem referenciados usando `$ref`. É por isso que `Modelos` é definido antes de `Runbooks` neste exemplo.

Neste exemplo, dizemos ao portal para pegar a subárvore com o `$id` chamado `LocationOptions` e incluir seus `$values`, substituindo a `$ref` declaração. Assim, o portal exibirá um `Select` como descrito na `Runbooks` seção, mas incluirá as opções reais de `Modelos`.

Um modelo pode conter qualquer instrução suportada no local de referência. Neste exemplo, usamos uma `Customization` instrução para modificar outros parâmetros como `StreetAddress`.

Assim, podemos ter uma personalização específica do runbook em `Runbooks` reutilizável em vários ambientes, mantendo os dados reais separados.

```json
{
    "Templates": {
        "Options": [
            {
                "$id": "LocationOptions",
                "$values": [
                    {
                        "Display": "DE-OF",
                        "Customization": {
                            "Default": {
                                "StreetAddress": "Kaiserstraße 39",
                                "PostalCode": "63065",
                                "City": "Offenbach",
                                "Country": "Alemanha"
                            }
                        }
                    },
                    {
                        "Display": "DE-DEG",
                        "Customization": {
                            "Default": {
                                "StreetAddress": "Lateinschulgassse 24-26",
                                "PostalCode": "94469",
                                "City": "Deggendorf",
                                "Country": "Alemanha"
                            }
                        }
                    },
                    {
                        "Display": "DE-HH",
                        "Customization": {
                            "Default": {
                                "StreetAddress": "Hans-Henny-Jahnn-Weg 53",
                                "PostalCode": "22085",
                                "City": "Hamburg",
                                "Country": "Alemanha"
                            }
                        }
                    },
                    {
                        "Display": "FI-HS",
                        "Customization": {
                            "Default": {
                                "StreetAddress": "Em algum lugar 42",
                                "PostalCode": "12345",
                                "City": "Helsinki",
                                "Country": "Finlândia"
                            }
                        }
                    }
                ]
            },
            {
                "$id": "CompanyOptions",
                "$values": [
                    {
                        "Id": "gkg",
                        "Display": "glueckkanja",
                        "Value": "glueckkanja AG"
                    },
                    {
                        "Id": "pp",
                        "Display": "PRIMEPULSE",
                        "Value": "PRIMEPULSE SE"
                    }
                ]
            }
        ]
    },
    "Runbooks": {
        "rjgit-org_general_add-user": {
            "ParameterList": [
                {
                    "DisplayName": "Localização do Office",
                    "DisplayAfter": "CompanyName",
                    "Select": {
                        "Options": {
                            "$ref": "LocationOptions"
                        }
                    }
                },
                {
                    "Name": "CompanyName",
                    "Select": {
                        "Options": {
                            "$ref": "CompanyOptions"
                        },
                        "AllowEdit": false
                    }
                }
            ],
            "ReadOnly": [
                "StreetAddress",
                "PostalCode",
                "City",
                "Country"
            ]
        }
    }
}
```

Isso criará a seguinte interface:

![Demonstração - ref-location](https://686519968-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MkrcM7cKOpXKri1kVrh%2Fuploads%2Fgit-blob-93295541748dcc12dbc72208851138efd0808d51%2Frunbook-customization-img7.png?alt=media)

![Demonstração - ref-address](https://686519968-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MkrcM7cKOpXKri1kVrh%2Fuploads%2Fgit-blob-11e2812670e56cf10bb03fe7588059d232a8addf%2Frunbook-customization-img8.png?alt=media)

### Filtros de Grafo

Você pode preparar [Filtros de Grafo ODATA](https://docs.microsoft.com/en-us/graph/query-parameters?context=graph%2Fapi%2F1.0\&view=graph-rest-1.0#filter-parameter) para serem usados em vários runbooks. Armazene-os em uma seção chamada `GraphFilters`.

O exemplo a seguir filtra um determinado prefixo no `DisplayName` de um grupo, para mostrar apenas grupos relacionados a licenciamento em um seletor de grupos.

```json
"GraphFilters": {
    "LicenseGroup": "startswith(DisplayName, 'LIC_')" // também incluído no código RJ como padrão
  }
```

Veja [filtragem de grafo](#graph-filtering) sobre como usar isto a partir de um runbook.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.realmjoin.com/pt/automatizacao/runbooks/runbook-customization.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
