# Widgets personalizados

Los widgets personalizados integran servicios externos dentro de ServiceDesk Plus para ampliar las capacidades de la aplicación. Le permiten acceder a aplicaciones de terceros y páginas web desde ServiceDesk Plus. Los widgets son componentes de interfaz de usuario integrables que puede crear mediante un paquete de widget personalizado.

> **Nota:** Los widgets personalizados están disponibles solo para la edición Enterprise de ServiceDesk Plus.
>
> **Límite actual:** Puede crear 10 widgets y 4 elementos de widget por cada widget.

Puede configurar widgets personalizados para que sean accesibles desde la siguiente ubicación:

- Paneles
- Pestaña web
- Detalles de la solicitud
- Detalles del cambio
- Detalles del activo
- Detalles de la versión
- Detalles del módulo personalizado

## Crear paquete de widget personalizado

Un paquete de widget personalizado es un conjunto de archivos de configuración y archivos de recursos como html, png, js o css, necesarios para crear un widget personalizado. Esto ayuda a integrar aplicaciones de terceros y ampliar la funcionalidad de ServiceDesk Plus.

Para crear un paquete de widget personalizado:

- Desarrolle un paquete de aplicación mediante archivos de recursos.
- Cree un archivo `plugin-manifest.json`.
- Comprima el paquete de la aplicación y el archivo `plugin-manifest.json` en un archivo zip.
- Cargue el archivo zip en la página de widgets personalizados.

El siguiente documento explica el procedimiento para crear un paquete de aplicación y un archivo `plugin-manifest.json`.

### Desarrollar paquete de aplicación

Cree un archivo de recursos para un widget en la carpeta de la aplicación. Genere una URL que dirija a la página de destino del elemento del widget. Ingrese esta URL al configurar la [URL de ruta](https://www.manageengine.com/latam/service-desk/help/adminguide/custom-widgets.html#path-url) en el archivo `plugin-manifest.json`.

Puede usar funciones Util para establecer la conexión entre ServiceDesk Plus y el widget personalizado. Con las funciones Util, puede agregar datos al servidor de la aplicación desde el widget personalizado o recuperar datos del widget, como URL o cualquier otro dato del widget personalizado.

### Crear archivo Plugin-Manifest.JSON

El archivo `plugin-manifest.json` contiene los detalles de configuración del widget personalizado. Algunas claves incluidas en este archivo son opcionales, mientras que otras son obligatorias.

Use las siguientes indicaciones para proporcionar valores a las claves:

- **Widgets***: Un arreglo JSON que contiene detalles de los elementos del widget personalizado. Debe agregar al menos un elemento de widget en un paquete de widget personalizado. Puede agregar un máximo de cuatro elementos de widget. Cada elemento de widget debe tener el siguiente conjunto de propiedades:
  - **name***: Nombre del elemento del widget (máximo de 100 caracteres).
  - **description**: Una breve explicación del elemento del widget.
  - **path url***: La ruta URL del elemento del widget. Formato de ejemplo: `("/app/index.html")`

- **PropertyJSON**: Contiene propiedades del elemento del widget personalizado.
  - **white_list**: Ingrese la ruta URL del dominio para realizar una llamada API. Formato de ejemplo: `("api.zoom.us")`
  - **visible_to**: Restringe la disponibilidad de los widgets personalizados a usuarios según los roles.
  - **icons**: Una clave opcional para proporcionar íconos para sus elementos de widget. De forma predeterminada, se genera un ícono según el nombre del elemento del widget. Puede cargar un ícono de hasta 30x30 píxeles ingresando la URL del ícono como valor para la clave `30X30` en el archivo del manifiesto del plugin. Los íconos se representan dinámicamente en modo oscuro o claro según el tema de la aplicación.
  - **Íconos temáticos**: Puede proporcionar diferentes íconos para distintos temas. La URL de los íconos temáticos debe incluir una versión "dark" o "light".  
    Formato de ejemplo:
    ```
    "icons": {
      "dark": "/app/[icon-name].png",
      "light": "/app/[icon-name].png"
    }
    ```

- **Locations***: Defina la ubicación en ServiceDesk Plus donde se pueden representar los widgets personalizados. Debe proporcionar al menos una ubicación para el elemento del widget.

Actualmente, puede configurar widgets personalizados en las siguientes ubicaciones:

| Ubicación | Formato de clave JSON | Descripción |
|---|---|---|
| Pestaña web | `"webtab"` | El widget personalizado se agrega como una pestaña web en el panel de navegación. |
| Inicio | `"dashboard"` (para técnicos y solicitantes) | Los widgets personalizados se incrustan en el panel. Los widgets del panel solo se pueden habilitar. Para agregar un widget, haga clic en Nuevo > Nuevo widget en el panel. Si está habilitado para solicitantes, puede incrustarse en la página de inicio del portal del solicitante. |
| Página de detalles de la solicitud | `"request.detail.tab"` | Se agrega como una pestaña en la página de detalles de la solicitud. |
| Página de detalles de la solicitud | `"request.detail.rightpanel"` | Se agrega al panel derecho en la página de detalles de la solicitud. |
| Página de detalles del cambio | `"change.detail.tab"` | Se agrega como una pestaña en la página de detalles del cambio. |
| Página de detalles del cambio | `"change.detail.rightpanel"` | Se agrega al panel derecho en la página de detalles del cambio. |
| Página de detalles de la versión | `"release.detail.tab"` | Se agrega como una pestaña en la página de detalles de la versión. |
| Página de detalles de la versión | `"release.detail.rightpanel"` | Se agrega al panel derecho en la página de detalles de la versión. |
| Página de detalles del recurso | `"asset.detail.tab"` | Se agrega como una pestaña en la página de detalles del recurso. |
| Página de detalles del recurso | `"asset.detail.rightpanel"` | Se agrega al panel derecho en la página de detalles del recurso. |
| Página de detalles del módulo personalizado | `"cm_{modulename}.detail.tab"` | Se agrega como una pestaña en la página de detalles del módulo personalizado. |
| Página de detalles del módulo personalizado | `"cm_{modulename}.detail.rightpanel"` | Se agrega al panel derecho en la página de detalles del módulo personalizado. |

### Configuraciones adicionales

Las configuraciones adicionales, como **Connections** o **Modules**, mejoran las capacidades de los widgets personalizados. El alcance de las configuraciones adicionales se limita al nivel del elemento del widget o se aplica globalmente a todos los elementos del widget.

#### Configurar Connections

Connections permite integrar widgets personalizados con API de terceros. Puede agregar hasta cuatro connections a un widget personalizado.

Para configurar connections en el archivo de manifiesto:

1. Vaya a **Admin > Developer Space > Connections**.
2. Copie el fragmento de código JSON desde la página de detalles de la connection.
3. Péguelo como una cadena JSON en el archivo `plugin-manifest.json`.

- Para permitir que los usuarios autoricen connections, establezca `"userAccess": true`.
- Para restringir la autorización solo al SDAdmin que instaló el widget personalizado, establezca `"userAccess": false`.

Ejemplo:

```json
"connections": [{
  "connectionLinkName": "twitter",
  "connectionName": "twitter",
  "serviceName": "twitter",
  "userAccess": false,
  "isUserDefinedService": false
}]
```

> **Alcance:** Esta configuración tiene alcance global.  
> Cuando se elimina un widget personalizado, las connections asociadas también se eliminan.

#### Configurar Modules

Modules permite recopilar y almacenar datos adicionales. Los datos se pueden completar y administrar en los widgets del módulo personalizado usando API de JS, API o desde la aplicación.

El nombre para mostrar, el nombre plural para mostrar y el nombre de la API del módulo personalizado deben ser únicos en la aplicación.

Ejemplo:

```json
"modules": [{
  "display_name": "zoom details1",
  "display_plural_name": "zoom_custom_widget",
  "api_plural_name": "zoom_custom_widget",
  "name": "zoom1_custom_widget",
  "permission": {
    "all": [{
      "field": "type",
      "values": ["user", "technician"],
      "condition": "es",
      "logical_operator": "y"
    }],
    "allowed_users": "Todos"
  },
  "fields": [{
    "additional_attributes": { "nullable": false },
    "display_name": "request_id",
    "name": "request_id",
    "field_type": "Línea única",
    "only_numeric": false
  }]
}]
```

> **Alcance:** Esta configuración es específica para cada elemento del widget.  
> Cuando se elimina un widget personalizado, los módulos personalizados asociados también se eliminarán.

## Archivo plugin-manifest.json de ejemplo

```json
{
  "name": "Aplicaciones de reuniones",
  "widgets": [{
    "name": "Aplicaciones de Zoom",
    "description": "Un widget que permite a los técnicos obtener acceso remoto a dispositivos en diferentes plataformas.",
    "locations": [{
      "name": "request.detail.rightpanel",
      "is_enabled": true
    }],
    "property_json": {
      "icons": {
        "dark": "/app/img/TV_icon.png"
      },
      "white_list": ["api.zoom.us"],
      "visible_to": ["SDAdmin"]
    },
    "url": "/app/zoom.html"
  }],
  "connections": [{
    "connectionLinkName": "adminzoom",
    "connectionName": "adminzoom",
    "serviceName": "zoom",
    "userAccess": false,
    "isUserDefinedService": true,
    "sharedBy": 5
  }]
}
```