Primeros Pasos (con Onesait Platform CloudLab)
Guía actualizada a la versión 7.0.0-Zelda
Introducción
El objetivo de este artículo es el de familiarizarse con Onesait Platform y su modelo de desarrollo low code.
Para seguir esta guía se va a usar Onesait Platform CloudLab, un entorno gratuito en la nube de la Plataforma, en donde desarrolladores y usuarios potenciales pueden realizar sus pruebas con una Plataforma completamente funcional.
Paso 1: registro y acceso a la Plataforma
Acceso al entorno de CloudLab y creación de un nuevo usuario
El primer paso será acceder al entorno de CloudLab. Para ello, desde un navegador web (se recomienda usar Google Chrome) se navegará a la URL de: https://lab.onesaitplatform.com
Para registrar un nuevo usuario, desde la pantalla de inicio de sesión se tendrá que pulsar en el botón de «Register»:
Se mostrará entonces una formulario en donde se tendrá que introducir los datos del usuario:
First name: para indicar el nombre del usuario
Last name: para los apellidos
Email: para indicar el correo electrónico de contacto. No se podrá reutilizar uno ya registrado.
Username: el nombre de usuario para identificarse. Deberá tener una longitud de, al menos, cuatro caracteres alfanuméricos, y no podrá tener espacios ni caracteres especiales más allá de «@», «.» o «_»
Password: deberá tener al menos diez caracteres, de los cuales al menos uno tendrá que ser una letra, otro un número y un caracter especial.
Para continuar con el registro se pulsará en el botón de «Register».
Si todo ha ido correctamente, se mostrará nuevamente la pantalla de inicio de sesión, con un mensaje en el que se indica que la información de la cuenta ha sido actualizada.
En el campo de username se mostrará el nombre de usuario previamente indicado. Introduciendo la contraseña escogida en el campo de password, se podrá iniciar la sesión pulsando en el botón de «Sign In».
Tras iniciar se sesión, se mostrará la pantalla principal de la Plataforma, el Control Panel.
Por defecto, los usuarios registrados tienen un rol de tipo «desarrollador». Para cambiar el rol del usuario, será necesario contactar con un administrador.
Se puede consultar la información sobre los roles de la Plataforma en el siguiente artículo:
Conociendo Control Panel
Control Panel es la consola web central para gestionar todos los conceptos de Onesait Platform.
Se encuentra construido con diversas capacidades que están prácticamente listas para usar, como accesibilidad, usabilidad, capacidades multilingües, etc., lo que facilita la gestión máxima de los usuarios de la Plataforma.
En el siguiente artículo se explica con detalle la funcionalidad de Control Panel:
Como resumen, en esta página se muestra la siguiente información:
Menú de acceso: localizado en el lateral izquierdo de la pantalla, el cual cuenta con todas las opciones disponibles para el usuario, así como un buscador integrado en la parte superior para localizar un módulo concreto. Cada menú se compone de submenús.
En el siguiente artículo se explica y desglosa el menú de acceso de la Plataforma y sus diferentes componentes:
Cabecera: desde donde se podrá acceder a dos menús:
Perfil de usuario: en donde se podrá cambiar el idioma, consultar los datos del usuario y sus prerefencias, así como cerrar la sesión.
Opciones: con acceso a los servicios de API REST de la Plataforma, los tokens de usuarios, así como el market de Assets y la solicitud de soporte.
Aplicaciones: localizado en el centro de la pantalla, se trata de un listado de las aplicaciones disponibles para el usuario. Un nuevo usuario no tendrá ninguna Aplicación a mostrar.
Pulsando en el interruptor de «Aplicaciones», situado en la parte superior derecha, se cambiará el modo de visualiación a «Mi universo».Mi universo: situado en el mismo lugar que las «Aplicaciones» en el centro de la pantalla, muestra todos los conceptos gestionados por la Plataforma.
Con un usuario recién registrado, sólo se tendrá una única Entidad, de nombre «Audit_
nombre de usuario», en la que la Plataforma registrará automáticamente todas las acciones del usuario:
Paso 2: crear una Entidad
Desde la versión 3.1.0-KickOff, en el Control Panel se ha pasado a denominar a las Ontologías como «Entidades». Esto no altera ninguna funcionalidad; simplemente se ha cambiado la nomenclatura para un mejor entendimiento del concepto.
Introducción
Para facilitar el proceso de creación de una Entidad, el Control Panel cuenta con un asistente de creación que simplifica y guía al usuario durante el proceso.
El proceso de creación de una Entidad se divide en cuatro pasos:
Rellenar la información general.
Definir el esquema.
Gestionar si los Formularios servirán como CRUD.
Configurar las opciones avanzadas.
La información proporcionada en los dos primeros pasos es obligatoria (es información genérica que define a la Entidad), siendo la tercera opcional.
Pasos
Crear la Entidad
Desde el Control Panel, se navegará al menú de Core > Entidades.
Esto llevará al listado de Entidades disponibles. Para crear la Entidad, se pulsará en el botón de «+» situado en la parte superior derecha de la pantalla.
De las distintas Entidades que se van a poder crear, se seleccionará la de «Creación paso a paso»:
Rellenar la información general
Esto abrirá el asistente de creación de Entidades, en donde se tendrá que introducir una información básica:
Identificación: el nombre único con el que identificar a la Entidad.
Meta-Información: etiquetas con las que caracterizar la Entidad, que servirán para su filtrado a la hora de hacer búsquedas.
Descripción: texto descriptivo extendido de la Entidad, como su uso, propiedades, características, etc.
Además, se cuenta con algunas opciones más de caracterización de la Entidad:
Entidad activa: para que la Entidad funcione o se encuentre bloqueada.
Entidad pública: si queremos que la Entidad sea pública, o si la queremos privada.
Permite campos cifrados: si interesa que algunos campos almacenen información sensible y estén cifrados (más información).
Habilita ContextData: si se quiere que la Entidad registre internamente los cambios de escritura y gestión (más información).
Soporta JSON-LD: si interesa que la Entidad pueda trabajar con contexto (más información).
Habilitar el preprocesamiento de clases de datos: opción que permite que la Entidad registre internamente los cambios de escritura y gestión.
Una vez definida la información general y las opciones de la Entidad, se pulsará en el botón de «Continuar» para acceder a la definición del esquema de la Entidad.
Definir el esquema de la Entidad
En este paso, se solicitará al usuario que seleccione una plantilla de esquema o que cree una desde cero.
En caso de que se quiera utilizar una plantilla predefinida, ésta se seleccionará del listado de plantillas categorizadas. En la parte derecha de la pantalla se mostrarán los diferentes campos que tendrá la Entidad, así como las propiedades de cada uno de ellos.
Esta plantilla se podrá modificar según se necesite, añadiendo, modificando o borrando campos, así como cambiando sus propiedades.
Para crear un esquema propio, se seleccionará la plantilla de «EMPTYBASE» localizada en la categoría de «General»:
Por defecto, las Entidades se crean con un nodo raíz, el cual corresponde con el nombre de la Entidad. Es posible crear Entidades sin dicho nodo, seleccionando la opción de «EMPTYBASE NO ROOT NODE».
En este caso, en la parte derecha de la pantalla aparecerá el gestor de campos de la Entidad vacío.
Para crear un nuevo campo en la Entidad, se pulsará en el botón de «+».
Aparecerá entonces en el listado un nuevo registro, en donde se tendrá que indicar las siguientes opciones:
Propiedad: el nombre del campo. Dicho nombre no podrá contar con espacios.
Tipo: en este selector se tendrá que escoger el tipo de dato que será el campo.
Se diferencian los siguientes:
string: para campos de texto.
object: para almacenar objetos de tipo JavaScript.
number: para guardar números en general (incluidos decimales).
integer: para usar números enteros.
geometry-{{type}}: los campos de tipo geometry se utilizan para almacenar datos con componente espacial (coordenadas). Cada tipo de campo correspondiente con una de las diferentes geometrías soportadas en la Plataforma (más información).
file: este tipo se utiliza para almacenar datos binarios en un campo (más información).
date: para almacenar fechas en formato ISO 8601 (yyyy-MM-dd).
timestamp-mongo: para guardar marcas temporales en formato de MongoDB.
timestamp: como el anterior, pero en formato ISO 8601 (yyyy-MM-dd HH:mm:ss).
array: para almacenar listas de datos.
boolean: si el campo será de tipo lógico.
email: para guardar campos de tipo correo electrónico.
Requerido: marcando esta opción hará que el campo tenga que introducirse obligatoriamente al añadir un dato en la Entidad.
Encriptado: si se ha habilitado la opción de permitir campos encriptados, hará que la información del campo se enmascare (encripte).
Clase de datos: si se han creado previamente, permiten asignar operaciones de tratamiento del dato, como convertir el contenido del campo de tipo texto a mayúsculas, convertir el valor según un dominio, etc. (más información).
Valor por defecto: se podrá indicar el valor por defecto que tendrá el campo en caso de que el usuario no indique ningún otro valor.
Valores enumerados: es posible introducir una serie de valores para que a la hora de rellenar este campo, se tenga un listado de opciones entre las que elegir (más información).
Descripción: texto descriptivo para poder caracterizar el campo.
Borrar: pulsando en el icono de la papelera se podrá eliminar la propiedad que se está creando.
Una vez escogida la plantilla de por defecto que se quiere utilizar, o creado los campos que se precisen, se pulsará en el botón de «Actualizar Esquema» para que los cambios se registren en el esquema de la entidad.
Nada más pulsar, se visualizará una pantalla de código con la estructura de la Entidad en formato JSON:
Una vez comprobada que la estructura es la correcta, se pulsará en el botón de «Generar Instancia» para ver un ejemplo de dato de la Entidad:
Hecho esto, se pulsará en el botón de «Continuar» para pasar al último paso de la creación de la Entidad.
Formularios de Entidad
En este tercer paso se tendrá que marcar, si se desea, la opción de «Crear CRUD a partir de formularios».
Esta opción, como indica el texto de ayuda, permite que se pueda crear un grupo de formulario que sirvan para realizar CRUD de datos.
Configurar las opciones avanzadas
En este último apartado se podrán configurar ciertas opciones avanzadas de la Entidad.
Entre las opciones disponibles, la primera corresponde con el borrado de datos:
Borrar de la base de datos: esta opción permite el borrado automático de los datos almacenados en la Entidad a partir de un tiempo definido.
Borrar Entidades creadas anteriores a: si se ha habilitado la opción anterior, en este selector se podrá escoger la cantidad de tiempo a partir del cual se irán borrando los datos de la Entidad.
Las siguientes opciones hacen referencia a tópicos de comunicación de las Entidades:
Permite crear un tópico Kafka de ingesta para la Entidad (más información).
Permite crear un tópico Kafka de notificaciones (más información).
Permite crear un tópuco MQTT de ingesta para la Entidad (más información).
Habilita notificaciones al BPM (más información).
Por último, se puede indicar el tipo de instancia de base de datos que utilizará la Entidad. Esta opción sólo se puede configurar ahora, durante la creación de la Entidad, por lo que una vez definido el tipo de instancia, no se podrá cambiar en el futuro.
Desde el selector, se podrá escoger el tipo de instancia que se necesite:
Configuradas estas opciones, se pulsará el botón de «Crear» para terminar con la creación de la Entidad.
Se mostrará entonces una ventana con las opciones disponibles a realizar con la Entidad creada.
Pulsando en el botón de «Close» se volverá al listado de Entidades, en donde aparecerá la Entidad recién creada.
Paso 3: API REST para acceder a una Entidad
Una vez creada la Entidad que representa la información que se quiere manejar en el sistema, es posible hacer diferentes procesamientos en Onesait Platform: se pueden crear visualizaciones con el Dashboard Engine, generar un cliente para acceder a esta Entidad a través del Broker de la Plataforma, o bien crear una API REST para acceder a estos datos de forma sencilla y estandarizada.
Crear una API REST
Para crear una API REST de una Entidad, se puede acceder al asistente de creación tanto desde la ventana que aparece tras crear la entidad, como desde el menú de Procesamiento > APIs.
Sin importar la forma por la que se acceda, se mostrará un listado con las APIs a las que tiene acceso el usuario, ya sean propias como compartidas por otros usuarios (las que se muestran como públicas).
Para crear la nueva API, se pulsará en el botón de «+» situado en la parte superior derecha de la pantalla.
Esto abrirá el asistente de creación de la API, en donde se tendrá que introducir una información básica:
Habrá que introducir la siguiente información:
Identificación: el nombre único con el que identificar a la API.
Versión: la versión actual de la API. Este valor es autogenerado.
Categoría: para definir la API y poder filtrarlo fácilmente a la hora de buscarlo.
Tipo de API REST: representa el tipo de API a crear. La Plataforma permite publicar una API REST a partir de una Entidad, o bien crear una API REST desde un descriptor Swagger para actuar de Proxy.
Entidad: este selector permitirá escoger una de las Entidades propias o autorizadas al usuario, sobre la que generar la API REST, si el tipo de API REST escogido es de tipo Entidad. En el desplegable se podrá filtrar por el nombre la Entidad de interés:
Meta-Información: etiquetas con las que caracterizar la Entidad, que servirán para su filtrado a la hora de hacer búsquedas.
EndPoint base: campo autogenerado con la URL de la API REST a crear.
EndPoint Swagger: la URL del Swagger de la API REST.
Descripción: texto descriptivo extendido de la API REST, como su uso, propiedades, características, etc.
Imagen: es posible cargar una imagen para caracterizar la API.
Pecitiones por segundo (QPS): es posible fijar el número de peticiones que acepta la API por segundo.
Tiempo de caché (minutos): el tiempo en minutos que mantendrá almacenada la información cacheada (más información).
Pública: si se quiere que la Entidad sea pública, o si se quiere privada.
Publicar a Gravitee: para publicar la API en el gestor de APIs de Gravitee.
Además, en la parte derecha de la pantalla se encuentra la sección de Operaciones, en donde se listan las operaciones a disponibilizar en la API:
La Plataforma permite crear automáticamente las operaciones CRUD de una API, así como hacer consultas personalizadas.
QUERY(ALL): petición GET, que recupera todos los datos de una Entidad.
QUERY(ID): petición GET, que recupera una instancia a partir del identificador único.
INSERT: petición POST, que permite inserta una nueva instancia.
UPDATE: petición PUT, que permite actualiza una instancia.
DELETE(ID): petición DELETE, que permite eliminar una instancia a partir de su identificador.
QUERY CUSTOM: petición GET, que permite crear una consulta personalizada.
Por defecto no hay ninguna disponible, por lo que habrá que pulsar en el botón de aquellas que interese habilitar. Por ejemplo, para permitir hacer una consulta a partir de un identificador, se habilitará la de «Query(ID)»:
En el campo «Descripción» se podrá introducir una pequeña descripción de la funcionalidad de la operación.
Una vez definidas las operaciones que interesan, se podrá terminar de crear la API REST pulsando en el botón de «Crear».
Tras pulsar el botón, el asistente de creación se cerrará y se volverá a la vista del listado de API REST, donde se podrá visualizar la nueva API creada, la cual aparecerá con el estado «Created».
Toda API tiene un ciclo de vida específico (más información). Esto afecta a la capacidad de otros usuarios de invorcar dicha API, por lo que debe de tener al menos el estado «Development» para ser accesible.
Para cambiar el estado de una API, en las opciones de la API se tendrá que desplegar el menú de opciones pulsando en el icono de «⋮», y seguidamente seleccionar la opción de «Desarrollo» (o «Publicar»).
Invocar la API REST
Para invocar las API de Plataforma es necesario utilizar un token de acceso. Existen dos tipos:
X-OP-APIKey: este es un token personalizado para cada usuario, el cual es más sencillo para invocar una API desde dentro de la Plataforma.
OAuth2: este token se genera automáticamente por la Plataforma dentro del ciclo de vida OAuth2. Este es el método recomendado cuando se invoca la API REST desde fuera de la Plataforma.
Para acceder al listado de tokens X-OP-APIKey de usuario, desde Control Panel se pulsará en el menú situado en la parte superior derecha de la pantalla y representado por el icono «⋮». De entre las distintas opciones, se seleccionará la de «User Tokens»:
Se mostrará entonces un listado con los tokens disponibles:
Si se quisiese generar un nuevo token, únicamente habría que pulsar en el botón de «Generar Token».
Se mostrará entonces un modal en el que introducer el identificador y descripción del token, algo útil para diferenciar para qué se usa cada token.
Para consultar el OAuth2, así como visualizar los tokens de X-OP-APIKey, desde el mismo menú de antes se seleccionará la opción de APIs:
Se mostrará entonces un modal con el token de OAuth2 y los tokens X-OP-APIKey disponibles para el usuario:
Una vez que se conoce dónde se encuentran los tokens, desde las opciones de la API REST se seleccionará la opción de «Swagger».
Las APIS de Onesait Platform se publican siguiendo el estándar Open API 3. Dentro del Control Panel se integra el UI de Swagger para poder invocar a estas APIs.
Se mostrará entonces una vista de Swagger con las operaciones disponibles para la API REST.
Lo primero que habrá que hacer es autorizar el Swagger. Para ello, se pulsará en el botón de «Authorize», lo que mostrará un modal en el que añadir el valor de X-OP-APIKey u OAuth2:
Tras introducir el tipo de token que se desee, se pulsará en el botón de «Authorize» para almacenar el token y autorizar las operaciones.
Hecho esto, únicamente habrá que escoger una de las operaciones, pulsar en el botón de «Try it out» y lanzar la operación con el botón de «Execute»:
En caso de una operación de POST/PUT, habrá que indicar un parámetro y/o un cuerpo en la operación.
Si la respuesta de la operación es correcta, se mostrará con un código 200 y un cuerpo con la información requerida:
Consultas personalizadas
Las consultas vistas hasta ahora son las genéricas. Sin embargo, es posible crear consultas personalizadas que permitan obtener información concreta.
Para ello, se editará la API desde el listado de APIs disponibles pulsando en el botón de «✎» (editar).
Para poder editar la API REST, ésta debe de estar en modo «Created» o «Development»; en caso contrario, no se podrá editar la API. En tal caso, habrá que modificar el estado a uno de los dos anteriores.
Una vez abierto el asistente de configuración, en la parte superior derecha se pulsará sobre el botón de «+ Query Custom»:
Se abrirá entonces un modal en el que preparar la consulta personalizada:
En dicha pantalla se tendrá que indicar la siguiente información:
Método: pudiendo escoger entre
PUT,POST,GETyDELETE.Nombre: el nombre del método con el que se invocará la consulta personalizada.
Consulta: la consulta para obtener la información de la Entidad.
Tipo de consulta: si la consulta se realiza en SQL o en nativo (MongoDB).
Descripción: texto descriptivo extendido del método, explicando lo que hace.
Activar procesado: activando este selector, se habilita una ventana en la que poder procesar la respuesta de la consulta usando JavaScript, en donde la variable «data» sería la respuesta de la consulta:
Parámetros en la consulta
A la hora de generar la consulta, es posible utilizar parámetros para hacer consultas dinámicas. Para ello, se introducirá el parámetro como: {$param}.
Por ejemplo, para la Entidad de «Restaurants», con la siguiente consulta se podrían obtener aquellos restaurantes cuya cocina sea de tipo americana:
SELECT c.Restaurant
FROM Restaurants AS c
WHERE c.Restaurant.cuisine = 'American'La consulta tendrá que estar definida como tipo GET.
Parametrizando el tipo de cocina, para poder indicar el tipo, la consulta quedaría así:
SELECT c.Restaurant
FROM Restaurants AS c
WHERE c.Restaurant.cuisine = {$cuisineType}Se actualizará entonces la sección de «Parámetros Query», mostrando el parámetro creado («cuisineType» en este caso) y puediendo configurar dos opciones:
Tipo: el tipo del parámetro; objeto, texto, número o fecha.
Localización: dónde se definirá el parámetro en la llamada; en el cuerpo, encabezado, parámetro de URL, etc.
Una vez incluido un parámetro, no se podrá ejecutar la consulta, por lo que para probar si todo funciona correctamente, habrá que introducir el valor de la consulta, y si funciona bien, ya cambiarlo a parámetro.
Una vez terminada de definir la consulta personalizada, se podrá guardar pulsando en el botón de «Guardar cambios».
Una vez guardados los cambios, la consulta personalizada aparecerá disponible en el listado de operaciones:
Si todo está conforme, se salvarán los cambios de la API REST pulsando en el botón de «Guardar cambios» situado en la parte superior derecha de la pantalla.
Regresando al Swagger, la nueva operación aparecerá listada:
Ejecutándola, e introduciendo como parámetro de entrada el tipo de cocina «Americana», se ejecuta correctamente la consulta:
Paso 4: Uso de la herramienta de consultas
La última herramienta que se va a ver en este tutorial es la herramienta de consultas, muy útil para conocer la información disponible en las Entidades.
Para acceder a ella hay que navegar al menú de Herramientas Dev > Herramientas de consultas.
Al acceder, se mostrará un vista en donde poder escoger qué se quiere analizar. Para ello, existen diferentes opciones:
Bases de datos: en el caso de los usuarios con roles de «analista» o «desarrollador», sólo estará disponible la Realtime DB, que es donde se almacenan las Entidades. En el caso de los usuarios con rol de tipo «administrador», además tendrán disponible la Config DB, donde se encuentran las tablas de datos de Onesait Platform.
Entidades/Tablas: en el caso de la base de datos Realtime DB, se podrá seleccionar la Entidad a la que consultar. Si se tiene acceso y se escoge la Config DB, permitirá consultar las tablas de configuración.
Mostrar sólo mis Entidades: para filtrar el listado de Entidades y mostrar únicamente las Entidades propietarias del usuario, lo que facilita la búsqueda.
Tras escoger una Entidad, se habilitarán nuevas opciones para realizar la consulta:
Tipo: lenguaje de la consulta. De partida está seleccionada la opción de
SQL, pero se puede escoger hacer las consultas en nativo (MongoDBpor defecto).Formato: el formato en el que se devolverá la respuesta. Está fijo en JSON.
Asistente para consultas: permite habilitar un asistente que ayude al usuario a generar la consulta.
En la parte inferior se muestra una ventana de código en donde se podrá introducir la consulta a realizar:
Por defecto, la consulta que sale siempre para cualquier Entidad es la la siguiente:
SELECT *
FROM nombre_entidad
LIMIT 3Esta consulta recupera datos de una Entidad. Se conforma de tres partes diferenciadas:
SELECT *: que selecciona todas las propiedades disponibles en la Entidad.FROM nombre_entidad: especifica la Entidad de donde se obtendrán los datos.LIMIT 3: restringe los resultados de la consulta a solo tres registros.
Como resultado, se recuperan las tres primeras filas completas de la Entidad especificada, mostrando todos los camposde cada registro.
Para ejecutarla, se pulsará en el botón de «Ejecutar Query»:
En la parte inferior de la pantalla, se mostrará una sección de código con la respuesta de la consulta: