> 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 Runbook
Adapta los runbooks genéricos de RealmJoin a las necesidades de tus entornos.
## Resumen
La implementación del runbook de RealmJoin ofrece capacidades de personalización para el autor de un runbook o el administrador de un entorno, de modo que pueden:
* Alojar parámetros y plantillas específicos del cliente/inquilino
* Ofrecer elementos de interfaz como selectores de usuarios o selecciones desplegables
* Presentar explicaciones legibles por humanos de los parámetros
* Ocultar elementos de interfaz innecesarios
Las personalizaciones pueden incluirse en el propio runbook y/o almacenarse en la instancia del Portal de RealmJoin 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 oficina para la incorporación de usuarios.
### Formato
La personalización puede definirse (en orden descendente de prioridad)
* Bloque de JSON en [configuración del Portal de RealmJoin](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 de los runbooks (usando el módulo auxiliar RJRb)
Algunas funciones (como las plantillas) solo están disponibles en formato JSON. Algunas funciones (como crear un selector de usuario) solo están disponibles especificando un tipo de datos en el bloque param. Puede combinar varios tipos de personalización para obtener mejores resultados.
## Bloque Param del Runbook
El Portal de RealmJoin analiza el bloque param de PowerShell de un runbook para determinar qué campos de entrada mostrar. Cuando sea posible, también validará las entradas según el tipo .NET dado para una variable.
Los siguientes tipos de datos se entienden actualmente:
* `[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. El Portal de RealmJoin, en particular, entenderá si especifica `[Parameter(Mandatory = $true)]` para indicar un parámetro obligatorio y hacer cumplir que estos parámetros se rellenen.
Cuando sea posible, el Portal de RealmJoin también leerá y mostrará los valores predeterminados dados en la interfaz.
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 auxiliar de Runbook de RealmJoin en su runbook:
`#Requires -Modules @{ModuleName = "RealmJoin.RunbookHelper"; ModuleVersion = "0.6.0" }`
Entonces 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 pasará 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 = ""
)
```
Vamos a desglosarlo 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 completamente definido por el tipo de variable.
`-DisplayName` le permite pasar un mensaje/descripción legible por humanos para este parámetro al Portal de RealmJoin.
#### Recursos de Graph
En el ejemplo anterior, la fuente de información es MS Graph, como se describe con `-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 multiselección usando un selector.
De forma predeterminada, 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 desea 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 listará 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 licencias" } )]
[String] $GroupID_License
)
```
Puede preparar filtros y reutilizarlos en múltiples scripts usando el [almacén central de datos](#graph-filters). En este caso, simplemente 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 específico `ref:LicenseGroup` está disponible de forma predeterminada sin configuración adicional.
## Encabezado del Runbook
El Portal puede analizar la sección de [ayuda basada en comentarios](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_comment_based_help?view=powershell-5.1) , si está presente.
Aquí tiene un ejemplo:
```powershell
<#
.SYNOPSIS
(Des)asignar una licencia a un usuario mediante la pertenencia a grupos.
.DESCRIPTION
(Des)asignar una licencia a un usuario mediante la pertenencia a grupos. Descripción más detallada...
.PARAMETER DefaultGroups
Lista de grupos separada por comas para 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` - 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 del runbook basado en JSON.
`.NOTES` - No se analiza / no se muestra. Utilice este espacio para anotar qué permisos y requisitos existen para su runbook.
`.EXAMPLE` - No se analiza / no se muestra. 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, p. ej., para diferentes flujos de trabajo o clases de usuarios.
## Personalización basada en JSON
### Almacén central de datos
Cada Tenant de Azure puede alojar un almacén de datos de "Runbook Customizations", que se encuentra 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 mismo nombre que el Azure Automation Runbook actual, su contenido se utilizará para personalizar la interfaz mostrada al usuario.
Suponga el siguiente runbook de demostración simple, llamado `rjgit-device_demo-runbook-customizing`.
```powershell
<#
.SYNOPSIS
Demostrar personalización de runbook
.DESCRIPTION
Demostrar personalización de runbook, como listas desplegables/selecciones
#>
#Requires -Modules @{ModuleName = "RealmJoin.RunbookHelper"; ModuleVersion = "0.6.0" }
param(
[string] $DeviceId,
[bool] $ExtraWorkflow = $true,
[int] $ExtraWorkflowTime = 15
)
"## Realizando cosas en el dispositivo '$DeviceID'"
# Flujo de trabajo complicado altamente opcional
if ($ExtraWorkflow) {
"## Ejecutando meditación..."
Start-Sleep -Seconds $ExtraWorkflowTime
}
```
Si no se personaliza, se mostrará 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é pasa si habilito o deshabilito el "Flujo de trabajo adicional"? ¿Necesito pensar en "Tiempo de flujo de trabajo adicional" si deshabilito "Flujo de trabajo adicional"?
Mejorémoslo. El siguiente JSON de ejemplo en el almacén central de datos modificará la interfaz 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": "Saltar la atención plena del dispositivo",
"Customization": {
"Default": {
"ExtraWorkflow": false
},
"Hide": [
"ExtraWorkflowTime"
]
}
}
],
},
"Default": "Saltar la atención plena del dispositivo"
}
]
}
}
}
```
Puede utilizar la misma notación / características en su [encabezado del runbook](#runbook-header).
#### ParameterList
Cada parámetro tiene su propia sección en `ParameterList`. [Los 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, el usuario dispone de más información sobre las alternativas de "Flujo de trabajo adicional". Además, un usuario solo se preocupará ahora por "Tiempo de flujo de trabajo adicional" si es relevante.
Cambiar la visibilidad de ese campo se hizo usando un `"Customization"` bloque dentro de una de las `"Select"` opciones. 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
. Ofrecimos un `DisplayName`amigable para el usuario `DisplayName` para reemplazar `$ExtraWorkflowTime` en la interfaz. Vea otros [modificadores](#modifiers) para más información.
Puede insertar parámetros "sin nombre" (que carecen de la declaración) como la sección "Ejecutar flujo de trabajo adicional", si desea ofrecer elementos de interfaz sin devolver directamente un valor. Esto normalmente solo se usa junto con `Nombre` Usamos `Seleccione`.
#### Seleccione
, para mostrar una lista de `Seleccione`Opciones `en un menú desplegable. Cada opción puede` texto, o activar un `Mostrar` , como establecer el `Personalización`valor en otros parámetros. En nuestro ejemplo, lo usamos para (des)ocultar `Hide` o un `Predeterminado` y sobrescribir `$ExtraWorkflowTime` $ExtraWorkflow `y su valor.`solo se muestra, por tanto, cuando es relevante y el interruptor binario
`$ExtraWorkflowTime` es ahora reemplazado con alternativas significativas desde la perspectiva del usuario. `y su valor.` En caso de un
para un parámetro con nombre, cada opción debe tener un `Seleccione` "ParameterValue": "..." `que pasar al runbook. Puede colocar un` "ShowValue: false" `dentro del bloque` para mostrar solo el menú desplegable y no un campo para el valor resultante del parámetro. `Seleccione` Ejemplo de parámetro con nombre:
"DefaultValue": true,
```json
{
"Name": "ExtraWorkflow",
"ParameterValue": true
"DisplayName": "Ejecutar flujo de trabajo adicional",
"DisplayBefore": "ExtraWorkflowTime",
"Select": {
"Options": [
{
"Display": "Ejecutar meditación (opcional)",
"ParameterValue": false,
},
{
"Display": "Saltar la atención plena del dispositivo",
"ShowValue": false
"Customization": {
"Hide": [
"ExtraWorkflowTime"
]
}
}
],
DefaultValue
}
}
```
El `Predeterminado` / `la instrucción en el parámetro también especifica el estado inicial del menú desplegable. En el caso de un parámetro sin nombre, use el` de la opción deseada, de lo contrario proporcione un valor de retorno predeterminado, como "true" o "false" o alguna cadena. `DisplayName` Si solo tiene parámetros con nombre, puede usar el formato un poco más corto
#### Parámetros
en lugar de `Parámetros` Para ver un ejemplo, consulte SelectSimple `ParameterList`.
SelectSimple
#### Si no se necesita todo el poder de un
y solo quiere ofrecer una lista de valores posibles en un menú desplegable (sin aplicar personalización adicional), puede usar `Seleccione` solo es utilizable para parámetros con nombre. `Si no se necesita todo el poder de un`.
`Si no se necesita todo el poder de un` "DeviceId": {
Ejemplo:
```json
{
"Runbooks": {
"rjgit-device_demo-runbook-customizing": {
"Parameters": {
"ExtraWorkflow": {
"Hide": true
},
"Default": false,
"Name": "ExtraWorkflow",
"DisplayName": "Ejecutar flujo de trabajo adicional",
"Ejecutar meditación (opcional)": true,
"SelectSimple": {
"Saltar 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
}
}
}
}
}
```
siempre es visible. `$ExtraWorkflowTime` Cada parámetro puede tener uno o más de los siguientes modificadores:
#### Los modificadores
"DisplayName": "texto"
* `- Mostrar "texto" como nombre del parámetro en la interfaz` "Hide": true / false
* `- Ocultar este parámetro` "Mandatory": true / false
* `- Exigir que este parámetro se rellene` "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` en su lugar.) `Predeterminado` para ello
* `"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` 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 del 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 central de datos, si existen. Esto también funciona si el parámetro se ha ocultado en la interfaz.
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 `Container` que falta simplemente no se rellenará previamente en la interfaz.
### Plantillas
`Plantillas` usar referencias JSON para incorporar datos - por ejemplo, una larga lista de ubicaciones de oficina - al usar una `Seleccione` 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 múltiples 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` para mostrar solo el menú desplegable y no un campo para el valor resultante del parámetro. `Runbooks` para referenciar/importar un subárbol desde la sección `Plantillas` . Busque las palabras clave `$id`/`$values` . Tenga en cuenta que `$id`/`$values` tienen que definirse antes de referenciarlos 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 instrucción `$ref` . Así, el portal renderizará un `Seleccione` como se describe en la sección `Runbooks` pero incluirá las opciones reales de `Plantillas`.
Una plantilla puede contener cualquier instrucción que sea compatible en la ubicación de referencia. En este ejemplo, usamos una instrucción `Personalización` para modificar otros parámetros como `Dirección`.
Así, podemos tener una personalización específica del 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": "Hamburgo",
"Country": "Alemania"
}
}
},
{
"Display": "FI-HS",
"Customization": {
"Default": {
"StreetAddress": "Algún lugar 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 grafo
Puede 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 usarse en varios runbooks. Guárdelos en una sección llamada `GraphFilters`.
Los siguientes filtros de ejemplo para 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 grafo](#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 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/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 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.
