> 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
## Resumen
La implementación de runbooks de RealmJoin ofrece capacidades de personalización al autor de un runbook o al administrador de un entorno, para que puedan:
* Alojar parámetros y plantillas específicos del cliente/Tenant
* Ofrecer elementos de interfaz de usuario como selectores de usuarios o selecciones desplegables
* Presentar explicaciones legibles por humanos de los parámetros
* Ocultar elementos de interfaz de usuario innecesarios
Las personalizaciones pueden incluirse en el propio runbook y/o almacenarse en la instancia de RealmJoin Portal del cliente. De forma predeterminada, 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 Office 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), reemplazando el comportamiento predeterminado del runbook
* Bloque de JSON en la cabecera de un runbook
Además (con la menor prioridad)
* por parámetro en la cabecera 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 los mejores resultados.
## Bloque Param del Runbook
RealmJoin Portal analiza el bloque param de PowerShell de un runbook para determinar qué campos de entrada renderizar. Cuando es posible, también validará las entradas según el tipo .NET proporcionado para una variable.
Actualmente se entienden los siguientes tipos de datos:
* `[bool]`, `[boolean]` - mostrará un interruptor 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 y 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 exigir que estos parámetros se completen.
Cuando sea posible, RealmJoin Portal también leerá y mostrará los valores predeterminados dados en la interfaz de usuario.
Tenga en cuenta que los valores predeterminados del runbook pueden ser reemplazados 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 en su runbook el módulo PS auxiliar de Runbook de RealmJoin:
`#Requires -Modules @{ModuleName = "RealmJoin.RunbookHelper"; ModuleVersion = "0.6.0" }`
A continuación, puede incluir `[ValidateScript( { Use-RJInterface ... } )]` declaraciones 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 dispositivo a este usuario (opcional)" -Type Graph -Entity User } )]
[string] $AssignedUserId = ""
)
```
Analicemos esto paso a paso. `[ValidateScript...]` es un modificador para el 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 definido por completo por el tipo de variable.
`-DisplayName` le permite pasar una indicación / descripción legible por humanos para este parámetro a RealmJoin Portal.
#### Recursos de Graph
En el ejemplo anterior, la fuente de información es MS Graph, como se describe en `-Type Graph`. Para MS Graph, use `-Entity` para especificar qué tipo de recurso espera. Las entidades disponibles son `de usuarios`, `Grupo`, `Dispositivo`. Esto producirá un selector para usuarios, grupos o dispositivos en el Entra ID dado.
El selector incluye una búsqueda rápida para localizar fácilmente el recurso requerido.
Actualmente, no es posible la selección múltiple usando un selector.
De forma predeterminada, un selector de MS Graph devolverá el ID del objeto. Si necesita, por ejemplo, el nombre principal de usuario 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 comiencen con "LIC\_".
```powershell
param(
[Parameter(Mandatory = $true)]
[ValidateScript( { Use-RJInterface -Type Graph -Entity Group -Filter "startswith(DisplayName, 'LIC_')" -DisplayName "Grupo de licencia" } )]
[String] $GroupID_License
)
```
Puede preparar filtros y reutilizarlos en varios scripts usando el [almacén de datos central](#graph-filters). En este caso, solo haga referencia al filtro por nombre usando `-Filter "ref:LicenseGroup"`, donde `ref:` indica que se debe buscar un filtro almacenado.
```powershell
param(
[Parameter(Mandatory = $true)]
[ValidateScript( { Use-RJInterface -Type Graph -Entity Group -Filter "ref:LicenseGroup" } )]
[String] $GroupID_License
)
```
Este ejemplo específico `ref:LicenseGroup` está disponible de forma predeterminada sin necesidad de configuración adicional.
## Cabecera del Runbook
El Portal puede analizar la [ayuda basada en comentarios](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_comment_based_help?view=powershell-5.1) sección, si está presente.
Aquí hay un ejemplo:
```powershell
<#
.SYNOPSIS
(Des)asignar una licencia a un usuario mediante la pertenencia a un grupo.
.DESCRIPTION
(Des)asignar una licencia a un usuario mediante la pertenencia a un grupo. Descripción más detallada...
.PARAMETER DefaultGroups
Lista de grupos a asignar separada por comas. 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": {
"Asignar licencia al usuario": false,
"Quitar licencia al usuario": true
}
}
}
}
#>
```
`.SYNOPSIS` - Dé una descripción muy breve de la función de su runbook. Se mostrará en la lista de runbooks disponibles.
`.DESCRIPTION` - Dé una descripción de la función de su runbook. Puede contener un poco más de detalle, ya que se mostrará dentro del diálogo de ejecución / parámetros de los runbooks.
`.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 de runbook basado en JSON.
`.NOTES` - No se analiza ni se renderiza. Use este espacio para anotar qué permisos y requisitos existen para su runbook.
`.EXAMPLE` - No se analiza ni se renderiza. Puede contener un ejemplo de una personalización basada en JSON para usar en el RealmJoin Datastore de su Tenant. Pueden ser ejemplos de cómo crear plantillas, p. ej., para distintos flujos de trabajo o clases de usuarios.
## Personalización basada en JSON
### Datastore central
Cada Tenant de Azure puede alojar un datastore de "Runbook Customizations", disponible en .
El formato es JSON con comentarios, lo que permite comas finales. Actualmente, hay tres secciones relevantes, `bloque de configuración`, `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 mismo nombre que el actual Azure Automation Runbook, su contenido se utilizará para personalizar el frontend mostrado al usuario.
Supongamos el siguiente runbook sencillo de demostración, llamado `rjgit-device_demo-runbook-customizing`.
```powershell
<#
.SYNOPSIS
Demostrar personalización de runbooks
.DESCRIPTION
Demostrar personalización de runbooks, como desplegables/selección
#>
#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 complicado altamente opcional
if ($ExtraWorkflow) {
"## Ejecutando meditación..."
Start-Sleep -Seconds $ExtraWorkflowTime
}
```
Si no se personaliza, se presentará así en el frontend:
Ideas:
* 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é con qué dispositivo estoy trabajando.
* ¿Qué ocurre si habilito o deshabilito el "Extra Workflow"? ¿Tengo que pensar en el "Extra Workflow Time" si deshabilito el "Extra Workflow"?
Mejoremos eso. El siguiente JSON de ejemplo en el almacén de datos central modificará la interfaz de usuario 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 adicional",
"DisplayBefore": "ExtraWorkflowTime",
"Select": {
"Options": [
{
"Display": "Ejecutar meditación (opcional)",
"Customization": {
"Default": {
"ExtraWorkflow": true
}
}
},
{
"Display": "Omitir la atención plena del dispositivo",
"Customization": {
"Default": {
"ExtraWorkflow": false
},
"Hide": [
"ExtraWorkflowTime"
]
}
}
],
},
"Default": "Omitir la atención plena del dispositivo"
}
]
}
}
}
```
Puede usar la misma notación / funciones en su [cabecera 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, hay más información disponible para el usuario sobre las alternativas de "Extra Workflow". Además, ahora el usuario solo se preocupará por "Extra Workflow Time" si es relevante.
El cambio de visibilidad de ese campo se realizó usando un `"Customization"` bloque dentro de una de las `"Select"` opciones. Actualmente, solo puede haber como máximo un bloque de este tipo `"Customization"` activo a la vez.
Como puede ver, el parámetro `$DeviceId` está completamente oculto. Esto se hace estableciendo el `"Hide": true` para este parámetro.
Los parámetros pueden tener un `DisplayName`. Hemos ofrecido un `DisplayName` legible para humanos para reemplazar `$ExtraWorkflowTime` en la interfaz de usuario. Vea otros [modificadores](#modifiers) para más información.
Puede insertar parámetros "sin nombre" (faltando la `Nombre` declaración) como la sección "Execute Extra Workflow", si desea ofrecer elementos de interfaz de usuario sin devolver directamente un valor. Esto normalmente solo se usa junto con `Selecciona`.
#### Selecciona
Usamos `Selecciona`, para mostrar una lista de `Opciones` en un desplegable. Cada opción puede `Visualización` texto, o activar una `Personalización`, como establecer `Hide` o un `Predeterminado` valor en otros parámetros. En nuestro ejemplo, lo usamos para (des)ocultar `$ExtraWorkflowTime` y reemplazar `$ExtraWorkflow`el valor de '$ExtraWorkflow'.
`$ExtraWorkflowTime` por lo tanto, solo se muestra cuando es relevante y el interruptor binario `$ExtraWorkflow` ahora se reemplaza por alternativas significativas desde la perspectiva del usuario.
En el 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 `Selecciona` bloque 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 adicional",
"DisplayBefore": "ExtraWorkflowTime",
"Select": {
"Options": [
{
"Display": "Ejecutar meditación (opcional)",
"ParameterValue": true
},
{
"Display": "Omitir la atención plena del dispositivo",
"ParameterValue": false,
"Customization": {
"Hide": [
"ExtraWorkflowTime"
]
}
}
],
"ShowValue": false
}
}
```
El `Predeterminado` / `DefaultValue` declaración en el parámetro también especifica el estado inicial del desplegable. En el caso de un parámetro sin nombre, use el `DisplayName` de la opción deseada; de lo contrario, proporcione 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 necesita toda la potencia de un `Selecciona` y solo desea ofrecer una lista de posibles valores en un desplegable (sin aplicar personalización adicional), puede usar `SelectSimple`.
`SelectSimple` solo es utilizable 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 adicional",
"Default": false,
"SelectSimple": {
"Ejecutar meditación (opcional)": true,
"Omitir la atención plena del dispositivo": false
}
},
"ExtraWorkflowTime": {
"DisplayName": "¿Cuánto tiempo meditar?"
}
}
}
}
}
```
La mayor diferencia (aparte de ser mucho más corto) con nuestro ejemplo anterior es que `$ExtraWorkflowTime` siempre está visible.
#### Modificadores
Cada parámetro puede tener uno o más de los siguientes modificadores:
* `"DisplayName": "text"` - Mostrar "text" como nombre del parámetro en la interfaz de usuario
* `"Hide": true / false` - Ocultar este parámetro
* `"Mandatory": true / false` - Exigir que este parámetro se complete
* `"ReadOnly": true / false` - Proteger este parámetro para que no se cambie 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. (combínelo con plantillas)
### bloque de configuración
`bloque de configuración` 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 de un 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
)
```
El Portal intentará rellenar previamente cada parámetro con valores del almacén de datos central, si están presentes. Esto también funciona si el parámetro se ha ocultado en la interfaz de usuario.
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 elemento faltante `Container` simplemente no se rellenará previamente en la interfaz de usuario.
### Plantillas
`Plantillas` utilice referencias JSON para incorporar datos - por ejemplo, una larga lista de ubicaciones de Office - al usar una `Selecciona` declaración.
Esto permite mantener una personalización neutral/reutilizable/separada de los datos reales.
Tomemos el ejemplo de la incorporación de nuevos usuarios. Puede que tenga múltiples opciones dadas para departamentos o ubicaciones de Office, donde asignar una ubicación de Office también exige una determinada dirección postal, país, estado, etc.
El siguiente ejemplo de una personalización de runbook usa la `$ref` dentro del `Runbooks` sección para referenciar/importar un subárbol desde la `Plantillas` sección. Preste atención a los `$id`/`$values` palabras clave. Tenga en cuenta que `$id`/`$values` deben 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 el `$id` llamado `LocationOptions` e incluya sus `$values`, reemplazando la `$ref` declaración. Así, el portal renderizará un `Selecciona` como se describe en la `Runbooks` sección, pero incluya las opciones reales de `Plantillas`.
Una plantilla puede contener cualquier instrucción compatible con la ubicación de referencia. En este ejemplo, usamos una `Personalización` instrucción para modificar otros parámetros como `Dirección`.
Así, podemos tener una personalización específica de runbook en `Runbooks` reutilizable en múltiples entornos, mientras se mantienen los datos reales separados.
```json
{
"Templates": {
"Options": [
{
"$id": "LocationOptions",
"$values": [
{
"Display": "DE-OF",
"Customization": {
"Default": {
"StreetAddress": "Kaiserstraße 39",
"PostalCode": "63065",
"City": "Offenbach",
"Country": "Germany"
}
}
},
{
"Display": "DE-DEG",
"Customization": {
"Default": {
"StreetAddress": "Lateinschulgassse 24-26",
"PostalCode": "94469",
"City": "Deggendorf",
"Country": "Germany"
}
}
},
{
"Display": "DE-HH",
"Customization": {
"Default": {
"StreetAddress": "Hans-Henny-Jahnn-Weg 53",
"PostalCode": "22085",
"City": "Hamburg",
"Country": "Germany"
}
}
},
{
"Display": "FI-HS",
"Customization": {
"Default": {
"StreetAddress": "Somewhere 42",
"PostalCode": "12345",
"City": "Helsinki",
"Country": "Finland"
}
}
}
]
},
{
"$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. Almacénelos en una sección llamada `GraphFilters`.
El siguiente ejemplo filtra un determinado prefijo en el `DisplayName` 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
}
```
Ver [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:
```
GET https://docs.realmjoin.com/es/automatizacion/runbooks/runbook-customization.md?ask=
```
The question should be specific, self-contained, and written in natural language.
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.