> 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/es/automatizacion/runbooks/runbook-customization.md).
# Personalización de runbooks
## Descripción general
La implementación del runbook de RealmJoin ofrece capacidades de personalización para el autor de un runbook o para el administrador de un entorno, de modo que puedan:
* Alojar parámetros y plantillas específicos del cliente/Tenant
* Ofrecer elementos de UI como selectores de usuarios o selecciones desplegables
* Presentar explicaciones legibles para humanos de los parámetros
* Ocultar elementos de UI innecesarios
Las personalizaciones pueden incluirse en el propio runbook y/o almacenarse en la instancia de RealmJoin Portal del cliente. Por defecto, intentaremos ofrecer valores predeterminados sensatos en los runbooks ofrecidos en [GitHub](https://github.com/realmjoin/realmjoin-runbooks).
Algunos runbooks incluirán ejemplos de cómo configurar plantillas específicas del cliente, como especificar ubicaciones de oficina para la incorporación de usuarios.
### Formatear
La personalización puede definirse (en orden descendente de prioridad)
* Bloque de JSON en [configuración de RealmJoin Portal](https://portal.realmjoin.com/settings/runbooks-customizations), sobrescribiendo el comportamiento predeterminado del runbook
* Bloque de JSON en el encabezado de un runbook
Además (con la menor prioridad)
* por parámetro en el encabezado del runbook
* por parámetro en el bloque param del runbook (usando el módulo auxiliar RJRb)
Algunas funcionalidades (como las plantillas) solo están disponibles en formato JSON. Algunas funcionalidades (como crear un selector de usuario) solo están disponibles especificando un tipo de dato en el bloque param. Puede combinar varios tipos de personalización para obtener mejores resultados.
## Bloque Param del runbook
RealmJoin Portal analiza el bloque param de PowerShell de un runbook para determinar qué campos de entrada mostrar. Cuando es posible, también validará las entradas según el tipo .NET dado para una variable.
Actualmente se entienden los siguientes tipos de datos:
* `[bool]`, `[boolean]` - mostrará un conmutador binario
* `[string]` - mostrará un cuadro de texto para escribir cualquier entrada alfanumérica
* `[int]` - mostrará un cuadro de texto, permitiendo solo entradas numéricas
* `[DateTime]`, `[DateTimeOffset]` - mostrará un selector de fecha/hora
Puede aplicar modificadores estándar de PowerShell a los parámetros. RealmJoin Portal, en particular, entenderá si especifica `[Parameter(Mandatory = $true)]` para indicar un parámetro obligatorio y forzar que estos parámetros se rellenen.
Cuando es posible, RealmJoin Portal también leerá y mostrará los valores predeterminados dados en la UI.
Tenga en cuenta que los valores predeterminados del runbook pueden ser sobrescritos por personalizaciones. Además, los parámetros pueden ocultarse por completo mediante personalizaciones.
### Personalización de parámetros
Para poder personalizar parámetros, asegúrese de incluir el módulo PS Runbook Helper de RealmJoin en su runbook:
`#Requires -Modules @{ModuleName = "RealmJoin.RunbookHelper"; ModuleVersion = "0.6.0" }`
Entonces puede incluir `[ValidateScript( { Use-RJInterface ... } )]` instrucciones en las definiciones de parámetros. Por ejemplo, lo siguiente creará un selector de usuario, permitiendo elegir un usuario de Entra ID y pasando su id de objeto como cadena al runbook.
```powershell
param(
[ValidateScript( { Use-RJInterface -DisplayName "Asignar este dispositivo a este usuario (opcional)" -Type Graph -Entity User } )]
[string] $AssignedUserId = ""
)
```
Desglosemos esto pieza por pieza. `[ValidateScript...]` es un modificador del siguiente parámetro definido en el bloque param. En este caso, la variable `$AssignedUserId`.
`Use-RJInterface` forma parte de nuestro [RealmJoin Runbook Helper](https://github.com/realmjoin/RealmJoin.RunbookHelper) módulo de PowerShell. Le permite especificar qué tipo de entrada espera usando `-Type` y `-Entity`, si eso no está ya completamente definido por el tipo de variable.
`-DisplayName` le permite pasar a RealmJoin Portal un mensaje / descripción legible para humanos para este parámetro.
#### Recursos de Graph
En el ejemplo anterior, la fuente de información es MS Graph, como se describe mediante `-Type Graph`. Para MS Graph, use `-Entity` para especificar qué tipo de recurso espera. Las entidades disponibles son `usuarios`, `Group`, `Device`. Esto producirá un selector para usuarios, grupos o dispositivos en el Entra ID dado.
El selector incluye una búsqueda rápida, para identificar fácilmente el recurso requerido.
Actualmente, no es posible seleccionar múltiples elementos usando un selector.
Por defecto, un selector de MS Graph devolverá el id del objeto. Si necesita, por ejemplo, el user principal name en su lugar, asegúrese de incluir "name" como sufijo en el nombre de su variable. Así que, básicamente, para obtener el id de un usuario, nombre el parámetro `$userid`. Si quiere un UPN, nómbrelo `$username`.
#### Filtrado de Graph
Si está usando un selector basado en MS Graph, también puede especificar `-Filter` y usar un [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 los objetos ofrecidos en el selector.
El siguiente ejemplo mostrará solo grupos de Entra ID que empiecen por "LIC\_".
```powershell
param(
[Parameter(Mandatory = $true)]
[ValidateScript( { Use-RJInterface -Type Graph -Entity Group -Filter "startswith(DisplayName, 'LIC_')" -DisplayName "Grupo de licencias" } )]
[String] $GroupID_License
)
```
Puede preparar filtros y reutilizarlos en varios scripts usando el [almacén central de datos](#graph-filters). En este caso, solo haga referencia al filtro por nombre usando `-Filter "ref:LicenseGroup"`, donde `ref:` indica buscar un filtro almacenado.
```powershell
param(
[Parameter(Mandatory = $true)]
[ValidateScript( { Use-RJInterface -Type Graph -Entity Group -Filter "ref:LicenseGroup" } )]
[String] $GroupID_License
)
```
Este ejemplo concreto `ref:LicenseGroup` está disponible por defecto sin configuración adicional.
## Encabezado del runbook
El portal puede analizar la sección [comentario basado en ayuda](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_comment_based_help?view=powershell-5.1) de un runbook, si está presente.
Aquí hay un ejemplo:
```powershell
<#
.SYNOPSIS
(Des-)asignar una licencia a un usuario mediante pertenencia a un grupo.
.DESCRIPTION
(Des-)asignar una licencia a un usuario mediante pertenencia a un grupo. Descripción más detallada...
.PARAMETER DefaultGroups
Lista separada por comas de grupos a asignar. p. ej. "DL Sales,LIC Internal Product"
.NOTES
Permisos:
MS Graph (API):
- User.Read.All
- GroupMember.ReadWrite.All
- Group.ReadWrite.All
.INPUTS
RunbookCustomization: {
"Parameters": {
"UserName": {
"Hide": true
},
"Remove": {
"DisplayName": "Asignar o quitar licencia",
"SelectSimple": {
"Assign License to User": false,
"Remove License from User": true
}
}
}
}
#>
```
`.SYNOPSIS` - Proporcione una descripción muy breve de la función de su runbook. Se mostrará en la lista de runbooks disponibles.
`.DESCRIPTION` - Proporcione una descripción de la función de su runbook. Puede contener un poco más de detalle, ya que se mostrará dentro del cuadro de ejecución / diálogo de parámetros del runbook.
`.PARAMETER` - Debe ir seguido del nombre de un parámetro. Le permite dar una explicación detallada de la entrada esperada para el parámetro en cuestión.
`.INPUTS` - Puede contener un bloque de personalización del runbook basado en JSON.
`.NOTES` - No se analiza / renderiza. Use este espacio para anotar qué permisos y requisitos existen para su runbook.
`.EXAMPLE` - No se analiza / renderiza. Puede contener un ejemplo de una personalización basada en JSON para usar en el almacén de datos de RealmJoin en su Tenant. Estos pueden ser ejemplos de cómo crear plantillas, por ejemplo, para distintos flujos de trabajo o clases de usuario.
## Personalización basada en JSON
### Almacén central de datos
Cada Tenant de Azure puede alojar un almacén de datos de "Runbook Customizations", ubicado en .
El formato es JSON con comentarios, permitiendo comas finales. Actualmente, hay tres secciones relevantes, `Settings`, `Plantillas`, `Runbooks`.
```json
{
"Settings": {
},
"Templates": {
},
"Runbooks": {
}
}
```
### sección de runbooks
`Runbooks` es analizada por el portal al iniciar un runbook. Si existe una sección con el nombre del actual Azure Automation Runbook, su contenido se usará para personalizar la interfaz mostrada al usuario.
Suponga el siguiente runbook simple de demostración, llamado `rjgit-device_demo-runbook-customizing`.
```powershell
<#
.SYNOPSIS
Demostrar personalización de runbooks
.DESCRIPTION
Demostrar personalización de runbooks, como dropdown/select
#>
#Requires -Modules @{ModuleName = "RealmJoin.RunbookHelper"; ModuleVersion = "0.6.0" }
param(
[string] $DeviceId,
[bool] $ExtraWorkflow = $true,
[int] $ExtraWorkflowTime = 15
)
"## Haciendo cosas al dispositivo '$DeviceID'"
# Flujo de trabajo muy opcional y complicado
if ($ExtraWorkflow) {
"## Ejecutando meditación..."
Start-Sleep -Seconds $ExtraWorkflowTime
}
```
Si no se personaliza, se presentará así en la interfaz:
Pensamientos:
* Como este runbook se inicia desde el contexto de un dispositivo en el portal, el `$DeviceId` es información redundante para un usuario. Ya sé en qué dispositivo estoy trabajando.
* ¿Qué sucede si activo o desactivo el "Extra Workflow"? ¿Tengo que pensar en "Extra Workflow Time" si desactivo "Extra Workflow"?
Mejorémoslo. El siguiente JSON de ejemplo en el almacén central de datos modificará la UI del runbook.
```json
{
"Runbooks": {
"rjgit-device_demo-runbook-customizing": {
"ParameterList": [
{
"Name": "DeviceId",
"Hide": true
},
{
"Name": "ExtraWorkflow",
"Hide": true
},
{
"Name": "ExtraWorkflowTime",
"DisplayName": "¿Cuánto tiempo meditar?",
},
{
"DisplayName": "Ejecutar flujo de trabajo extra",
"DisplayBefore": "ExtraWorkflowTime",
"Select": {
"Options": [
{
"Display": "Ejecutar meditación (opcional)",
"Customization": {
"Default": {
"ExtraWorkflow": true
}
}
},
{
"Display": "Omitir mindfulness del dispositivo",
"Customization": {
"Default": {
"ExtraWorkflow": false
},
"Hide": [
"ExtraWorkflowTime"
]
}
}
],
},
"Default": "Omitir mindfulness del dispositivo"
}
]
}
}
}
```
Puede usar la misma notación / funciones en su [encabezado del runbook](#runbook-header).
#### ParameterList
Cada parámetro tiene su propia sección en `ParameterList`. [Modificadores](#modifiers) permiten cambiar el comportamiento de ese parámetro.
El resultado se verá así:
Elegir el flujo de trabajo adicional mostrará (desocultará) más parámetros:
Esto muestra menos desorden en comparación con antes de aplicar la personalización. Al mismo tiempo, la persona usuaria dispone de más información sobre las alternativas de "Extra Workflow". Además, ahora un usuario solo se preocupará por "Extra Workflow Time" si es relevante.
Cambiar la visibilidad de ese campo se hizo usando un `"Customization"` bloque dentro de una de las opciones de `"Select"` Actualmente puede tener como máximo un bloque de este tipo activo a la vez. `"Customization"` Como puede ver, el parámetro
está completamente oculto. Esto se hace estableciendo el `$DeviceId` para este parámetro. `"Hide": true` Los parámetros pueden tener un
DisplayName `. Ofrecimos un`amigable para humanos `. Ofrecimos un` para reemplazar `$ExtraWorkflowTime` en la UI. Vea otros [modificadores](#modifiers) para más información.
Puede insertar parámetros "sin nombre" (faltando la instrucción `Nombre` como la sección "Execute Extra Workflow", si desea ofrecer elementos de UI sin devolver directamente un valor. Normalmente esto solo se usa junto con `Selecciona`.
#### Selecciona
Usamos `Selecciona`, para mostrar una lista de `Opciones` en un desplegable. Cada opción puede `Mostrar` texto, o activar un `Personalización`, como establecer `Hide` o un `Predeterminado` valor en otros parámetros. En nuestro ejemplo, lo usamos para (des)ocultar `$ExtraWorkflowTime` y sobrescribir `$ExtraWorkflow`valor.
`$ExtraWorkflowTime` por lo tanto solo se muestra cuando es relevante y el conmutador binario `$ExtraWorkflow` ahora se reemplaza por alternativas significativas desde la perspectiva del usuario.
En caso de un `Selecciona` para un parámetro con nombre, cada opción debe tener un `"ParameterValue": "..."` para pasar al runbook. Puede colocar un `"ShowValue: false"` dentro del bloque `Selecciona` para mostrar solo el desplegable y no un campo para el valor resultante del parámetro.
Ejemplo de parámetro con nombre:
```json
{
"Name": "ExtraWorkflow",
"DefaultValue": true,
"DisplayName": "Ejecutar flujo de trabajo extra",
"DisplayBefore": "ExtraWorkflowTime",
"Select": {
"Options": [
{
"Display": "Ejecutar meditación (opcional)",
"ParameterValue": true
},
{
"Display": "Omitir mindfulness del dispositivo",
"ParameterValue": false,
"Customization": {
"Hide": [
"ExtraWorkflowTime"
]
}
}
],
"ShowValue": false
}
}
```
El `Predeterminado` / `DefaultValue` instrucción en el parámetro también especifica el estado inicial del desplegable. En caso de un parámetro sin nombre, use el `. Ofrecimos un` de la opción deseada; de lo contrario, indique un valor de retorno predeterminado, como "true" o "false" o alguna cadena.
#### Parámetros
Si solo tiene parámetros con nombre, puede usar el formato ligeramente más corto `Parámetros` en lugar de `ParameterList`.
Para un ejemplo, vea SelectSimple
#### SelectSimple
Si no se necesita toda la potencia de un `Selecciona` y solo quiere ofrecer una lista de valores posibles en un desplegable (sin aplicar personalización adicional), puede usar `SelectSimple`.
`SelectSimple` solo se puede usar para parámetros con nombre.
Ejemplo:
```json
{
"Runbooks": {
"rjgit-device_demo-runbook-customizing": {
"Parameters": {
"DeviceId": {
"Hide": true
},
"ExtraWorkflow": {
"Name": "ExtraWorkflow",
"DisplayName": "Ejecutar flujo de trabajo extra",
"Default": false,
"SelectSimple": {
"Ejecutar meditación (opcional)": true,
"Omitir mindfulness del dispositivo": false
}
},
"ExtraWorkflowTime": {
"DisplayName": "¿Cuánto tiempo meditar?"
}
}
}
}
}
```
La diferencia más grande (aparte de ser mucho más corto) con nuestro ejemplo anterior es que `$ExtraWorkflowTime` siempre es visible.
#### Modificadores
Cada parámetro puede tener uno o más de los siguientes modificadores:
* `"DisplayName": "texto"` - Mostrar "texto" como nombre del parámetro en la UI
* `"Hide": true / false` - Ocultar este parámetro
* `"Mandatory": true / false` - Exigir que este parámetro se rellene
* `"ReadOnly": true / false` - Proteger este parámetro de ser cambiado respecto a su valor predeterminado
* `"DefaultValue": "..."` - Establecer un valor predeterminado para este parámetro. (También puede usar `Predeterminado` en su lugar.)
* `"GraphFilter": "startswith(DisplayName, 'LIC_')"` - vea [Filtrado de Graph](#graph-filtering)
* `"AllowEdit": true / false` - Proteger este parámetro de la edición manual. (combine esto con plantillas)
### Settings
`Settings` le permite almacenar datos de configuración como nombres de Azure Storage Account en un lugar central, manteniéndolos al mismo tiempo separados de sus runbooks.
Puede acceder a valores individuales desde el bloque param de un runbook usando `Use-RJInterface`.
Tomemos este ejemplo de bloque param de un runbook:
```powershell
param(
[ValidateScript( { Use-RJInterface -Type Setting -Attribute "CaPoliciesExport.Container" } )]
[string] $ContainerName,
[ValidateScript( { Use-RJInterface -Type Setting -Attribute "CaPoliciesExport.ResourceGroup" } )]
[string] $ResourceGroupName,
[ValidateScript( { Use-RJInterface -Type Setting -Attribute "CaPoliciesExport.StorageAccount.Name" } )]
[string] $StorageAccountName,
[ValidateScript( { Use-RJInterface -Type Setting -Attribute "CaPoliciesExport.StorageAccount.Location" } )]
[string] $StorageAccountLocation,
[ValidateScript( { Use-RJInterface -Type Setting -Attribute "CaPoliciesExport.StorageAccount.Sku" } )]
[string] $StorageAccountSku
)
```
Portal intentará completar previamente cada parámetro con valores del almacén central de datos, si están presentes. Esto también funciona si el parámetro se ha ocultado en la UI.
Un posible JSON en el almacén de datos para este runbook sería:
```json
{
"Settings": {
"CaPoliciesExport": {
"ResourceGroup": "rj-runbooks-01",
"StorageAccount": {
"Name": "rjrbexports01",
"Location": "West Europe",
"Sku": "Standard_LRS"
}
}
}
}
```
El `Container` elemento simplemente no se completará previamente en la UI.
### Plantillas
`Plantillas` usar referencias JSON para incorporar datos - por ejemplo, una larga lista de ubicaciones de oficina - al usar una `Selecciona` instrucción.
Esto permite mantener una personalización neutral/reutilizable/separada de los datos reales.
Tomemos el ejemplo de la incorporación de nuevos usuarios. Podría tener varias opciones dadas para departamentos o ubicaciones de oficina, donde asignar una ubicación de oficina también exige una determinada dirección, país, estado, etc.
El siguiente ejemplo de una personalización de runbook usa la sección `$ref` dentro del bloque `Runbooks` para referenciar/importar un subárbol desde la sección `Plantillas` sección. Preste atención a las palabras clave `$id`/`$values` Tenga en cuenta que `$id`/`$values` tienen que definirse antes de hacer referencia a ellas usando `$ref`. Por eso `Plantillas` se define antes que `Runbooks` en este ejemplo.
En este ejemplo le indicamos al portal que tome el subárbol con la `$id` llamado `LocationOptions` e incluya su `$values`, reemplazando la `$ref` instrucción. Así, el portal renderizará una `Selecciona` como se describe en la `Runbooks` sección, pero incluya las opciones reales de `Plantillas`.
Una plantilla puede contener cualquier instrucción admitida en la ubicación de referencia. En este ejemplo, usamos una `Personalización` instrucción para modificar otros parámetros como `StreetAddress`.
Así, podemos tener una personalización específica de runbook en `Runbooks` reutilizable en múltiples entornos, manteniendo los datos reales separados.
```json
{
"Templates": {
"Options": [
{
"$id": "LocationOptions",
"$values": [
{
"Display": "DE-OF",
"Customization": {
"Default": {
"StreetAddress": "Kaiserstraße 39",
"PostalCode": "63065",
"City": "Offenbach",
"Country": "Alemania"
}
}
},
{
"Display": "DE-DEG",
"Customization": {
"Default": {
"StreetAddress": "Lateinschulgassse 24-26",
"PostalCode": "94469",
"City": "Deggendorf",
"Country": "Alemania"
}
}
},
{
"Display": "DE-HH",
"Customization": {
"Default": {
"StreetAddress": "Hans-Henny-Jahnn-Weg 53",
"PostalCode": "22085",
"City": "Hamburg",
"Country": "Alemania"
}
}
},
{
"Display": "FI-HS",
"Customization": {
"Default": {
"StreetAddress": "Somewhere 42",
"PostalCode": "12345",
"City": "Helsinki",
"Country": "Finlandia"
}
}
}
]
},
{
"$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": "Ubicación de Office",
"DisplayAfter": "CompanyName",
"Select": {
"Options": {
"$ref": "LocationOptions"
}
}
},
{
"Name": "CompanyName",
"Select": {
"Options": {
"$ref": "CompanyOptions"
},
"AllowEdit": false
}
}
],
"ReadOnly": [
"StreetAddress",
"PostalCode",
"City",
"Country"
]
}
}
}
```
Esto creará la siguiente interfaz de usuario:
### Filtros de Graph
Puede preparar [Filtros de Graph ODATA](https://docs.microsoft.com/en-us/graph/query-parameters?context=graph%2Fapi%2F1.0\&view=graph-rest-1.0#filter-parameter) para usarlos en varios runbooks. Guárdelos en una sección llamada `GraphFilters`.
El siguiente ejemplo filtra un prefijo determinado en el `. Ofrecimos un` de un grupo, para mostrar solo los grupos relacionados con licencias en un selector de grupos.
```json
"GraphFilters": {
"LicenseGroup": "startswith(DisplayName, 'LIC_')" // también incluido en el código RJ como valor predeterminado
}
```
Vea [Filtrado de Graph](#graph-filtering) sobre cómo usar esto desde un 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 dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.realmjoin.com/es/automatizacion/runbooks/runbook-customization.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
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.