Crear Asistente IA y conectarlo con z/OS a través de REST API de z/OSMF
Aprovechando que existe una prueba de 30 días (trial) de IBM watsonx Orchestrate , voy a crear un AI assistant y crear una skill/extesión conectada con mi z/OS. De esta manera, desde el chat del asistente podré ver la información del comando D IPLINFO.
El enlace a la versión trial de 30 días:
https://www.ibm.com/account/reg/es-es/signup?formid=urx-52753
Crear un asistente IA
Para registrarse, unicamente hay que seguir los pasos.
Una vez nos hayamos registrado, esperamos a que la versión de prueba esté preparada.
Al acceder, hacer clic en el icono de la esquina superior izquierda para ver el menú.
Desplegar el menú Build y clic en Assistant Builder
Rellenamos los datos para crear nuestro primer asistente.
Si no hacemos la ventana lo suficientemente grande, puede que no veamos algunos campos del formulario.
El asistente se puede integrar en: Web, SMS, Slack, Facebook, Whatsapp…
Para esta prueba, elegiré Web.
Podremos personalizar la interfaz de usuario.
Pulsamos en el botón Create y ya tendremos el asistente definido.
Crear acciones del asistente IA
Ahora vamos a crear la primera acción. Clic en Custom-built --> Add
La acción será para mostrar la información del último IPL.
Esto será lo que tendrá que escribir el usuario en el chat para mostrar la información.
En el campo Assistant says escribiremos lo que queremos que responda el asistente.
En el campo And then elegiremos la acción que hará a continuación.
Voy a elegir Use an extension porque es la manera de llamar a una skill/extensión que ejecute el comando D IPLINFO en z/OS.
Crear skill/extensión para el asistente
Como no tengo ninguna extensión creada, haré clic en integrations catalog
Se abrirá una nueva ventana. Abajo, en la sección Extensions, clic en el botón Build custom extension
En la versión trial, tenemos que importar el fichero de skill/extensión que queramos usar en formato JSON (basado en OpenAPI).
En esta documentación, vienen detallados los parámetros que se pueden usar.
https://www.ibm.com/docs/en/watsonx/watson-orchestrate/base?topic=flows-building-openapi-specifications-skills
En mi caso, lo que hace es conectarse a z/OS usando REST API de z/OSMF, concretamente, Console Services.
De esta manera, le enviaremos un comando al sistema y mostraremos la respuesta.
Puede ser cualquier comando, por ejemplo, D IPLINFO
En API Explorer de z/OSMF, encontramos todos los datos que necesitamos para los parámetros del fichero JSON.
https://server:port/zosmf/api/explorer
Si hacemos clic en Modelo, veremos más detalles del tipo de dato que es cada parámetro.
En la web de IBM, encontramos más información detallada:
https://www.ibm.com/docs/en/zos/3.1.0?topic=services-issue-command-from-system-console
Este es el fichero que usaré.
Es necesario actualizar el parámetro url y el nombre de la consola (dato: IBMUSECN)
Ejemplo Skill IA / Extensión - IPL INFO
{
"openapi": "3.0.3",
"servers": [
{
"url": "https://server:port"
}
],
"info": {
"description": "z/OS IPL info",
"version": "1.0.0",
"title": "z/OS IPL info",
"x-ibm-annotations": "1.0.0",
"x-ibm-application-name": "z/OS data",
"x-ibm-application-icon": "",
"x-ibm-application-id": "zos-data",
"x-ibm-skill-subtype": "public",
"x-ibm-skill-type": "imported",
"x-ibm-disable-default-server-url": "true"
},
"tags": [
{
"name": "zOS data"
}
],
"paths": {
"/zosmf/restconsoles/consoles/{consoleName}": {
"put": {
"summary": "z/OS IPL Information",
"description": "z/OS IPL Information",
"operationId": "zosIplInfo",
"parameters": [
{
"name": "consoleName",
"in": "path",
"required": true,
"schema": {
"type": "string",
"default": "IBMUSECN"
},
"description": "EMCS console on z/OS"
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"cmd-response-key": {
"type": "string"
},
"cmd-response-url": {
"type": "string"
},
"cmd-response-uri": {
"type": "string"
},
"cmd-response": {
"type": "string"
},
"sol-key-detected": {
"type": "boolean"
},
"sol-key-timeout": {
"type": "boolean"
}
}
}
}
},
"description": "D IPLINFO - OK response"
},
"400": {
"content": {
"application/json": {}
},
"description": "Bad Request"
},
"403": {
"content": {
"application/json": {}
},
"description": "Forbidden"
},
"404": {
"content": {
"application/json": {}
},
"description": "Not Found"
}
},
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": ["cmd", "sol-key"],
"properties": {
"cmd": {
"type": "string",
"default": "d iplinfo"
},
"sol-key": {
"type": "string",
"default": "JES"
}
}
}
}
},
"description": "{\n \"cmd\": \"d iplinfo\",\n \"sol-key\": \"JES\"\n}"
},
"x-ibm-nl-intent-examples": ["Display IPL info", "IPL info"],
"x-ibm-next-actions": [],
"x-ibm-nl-entities": {
"entities": []
},
"x-ibm-conversational-skill": true
}
}
},
"components": {
"securitySchemes": {
"basicAuth": {
"type": "http",
"scheme": "basic"
}
}
},
"security": [
{
"basicAuth": []
}
]
Ahora, importamos el fichero. Clic en Next.
Rellenar los datos.
Buscar el fichero JSON.
Revisamos los datos y, si todo está bien, clic en Finish.
Volvemos al menú Actions, para seguir editando el asistente. Entrar en IPL INFO.
Vamos al primer paso y rellenamos la información. En And then, elegir Use an extension
Volvemos a ir a integrations catalog.
Ahora es posible añadir la Skill/Extensión que hemos importado.
Como uso el tipo de autenticación basic, tengo que indicar el usuario que usaremos para conectar por z/OSMF.
Debe ser un usuario que exista en z/OS y que tenga permisos en z/OSMF.
Cada vez que editemos la skill, tenemos que volver a actualizar la información de la autenticación.
Editar skill/extensión
Si queremos editar una skill porque nos hemos equivocado y tenemos que subir un nuevo JSON, clic en Open.
En mi caso, en Environment selecciono Draft.
Clic en Replace para subir el nuevo fichero JSON.
Después debemos ir a la pestaña Authentication y volver a poner los datos del usuario de z/OS.
En el momento de estas pruebas, la web no funciona correctamente y no muestra los campos de usuario y password.
Debemos cambiar el campo Authentication type a No authentication y volver a cambiarlo a Basic auth para que muestre ambos campos.
Hay que volver a escribir la password.
Asignar skill/extensión al asistente
Volver a Actions y seguir editando IPL INFO.
En el campo And then, elegir Use an extension de nuevo.
Ahora si podremos elegir la extensión.
Ya hemos completado el primer paso que consiste en llamar a la extensión que lanza el comando contra el z/OS usando z/OSMF.
Ahora tenemos que hacer un segundo paso que muestre la información recibida.
Para ello, pulsar en New step.
En este paso podemos poner una condición de entrada, por ejemplo, que el paso anterior se haya ejecutado bien. No lo voy a hacer para no complicar demasiado el ejemplo.
Para mostrar el resultado del paso anterior, hay que elegir el botón fx.
En mi caso, selecciono step 1.
La variable que contiene el resultado del comando es cmd-response.
Hay que modificar lo siguiente para mostrar bien el resultado porque el editor escribe el código de una manera que no es válida para esta API de z/OSMF.
Para saber qué debemos poner, podemos buscar en Google JSON path finder.
Por ejemplo: https://jsonpathfinder.com/
Debemos poner el resultado que devuelve la API (podemos cogerlo del API Explorer de z/OSMF) dentro de una etiqueta body, como en la imagen.
A la derecha, al desplegar la etiqueta body y seleccionar cmd-response, nos dirá el path y cómo debemos ponerlo.
En este caso:
body['cmd-response']
Con el botón < / > cambiamos al modo editor de código.
Debemos modificar body.cmd-response por body['cmd-response'].
Guardamos los cambios y pulsamos en Preview.
Al poner ipl info en el chat, falla. En Inspect, podremos ver el error. En mi caso, es por usar certificados autofirmados en z/OS.
Permitir certificados autofirmados (SSL/TLS)
Para permitir conexiones con certificados autofirmados, salimos del editor (x arriba a la derecha) y vamos a Assistant Settings.
En el apartado Security certificates (SSL/TLS), hay varias opciones.
Como son certificados autofirmados, podríamos usar la primera o segunda opción y subir el certificado descargándolo de z/OS.
Haré una entrada específica de esto para no hacer muy extensa esta.
Yo ya tenía selecciona la tercera opción, pero cuando se hacen cambios en las skill, hay que volver a seleccionarla.
Al menos es lo que me ha pasado en las pruebas.
Como no funciona correctamente, seleccionaré la primera o segunda opción y volveré a seleccionar la tercera, porque así si guarda los cambios.
Probar Asistente IA
En el menú, vamos a Preview. Se abrirá el asistente y nos dará varias opciones predefinidas.
La que yo he configurado es IPL INFO, podemos hacer clic en el botón o escribirlo en el chat.
Alguna vez no responde en tiempo y hay que volver a probar.
Aparecerá el resultado del comando.
En z/OS, comprobamos que se ha ejecutado el comando.
