Operaciones avanzadas

Introducción

A continuación se resumen una serie de operaciones avanzadas que se pueden realizar mediante API Administrativa. Para relizar estas acciones se necesita un token de un usuario que tenga asignado un rol que contenga el permiso de administración en la API (API_ADMIN). Para más detalles de cualquier endpoint, consultar Swagger

Operaciones de creacion o modificación de objetos

Obtención del cuerpo de objetos

Los siguientes endpoints permiten la creación o modificación de metadato de los objetos en Anjana.

Todos los body que hay que usar para la creación/edición de objetos se pueden conseguir llamando al endpoint

GET https://{{host}}/gateway/api/admin/kerno/body-create-update/{objectSubType}/{idObject}

Esta llamada devolverá el body del objeto correspondiente al idObject, que se puede usar para modificaciones sobre este. Para obtener el body necesario para crear un nuevo objeto no se debe mandar el idObject.

Para más información sobre qué se debe incluir como valor según el tipo de campo que es el metadato, consultar la Guía de usuario para ver ejemplos.

La información sobre la composición de las ARIs para campos que utilicen ARIs (aquellos relacionados con ficheros o entidades) se encuentra en el documento de ARIs.

Creación y edición de entidades nativas

Estos endpoints permiten crear y editar entidades nativas (DATASET, DSA, INSTANCE, SOLUTION y PROCESS) con todo lo que conllevan (relaciones internas, entidades extra en el caso del dataset, etc.).

A diferencia de la API estándar, aquí cada tipo de entidad tiene su propio endpoint y la operación finaliza directamente en el estado que se incluya en la petición. El cuerpo de la petición se obtiene según lo indicado en el apartado anterior.

En todos los casos, al igual que desde el portal, los datos enviados se validan y la operación solo se completa si se superan todas las validaciones; en caso contrario se informará de los errores.

Creación de entidades nativas

Paso 1. Preparar el cuerpo de la petición.

Obtén el cuerpo según lo indicado en el apartado anterior . En ningún caso se permite modificar las PK o claves primarias.

Paso 2. Llamar al endpoint correspondiente al tipo de entidad.

Edición de entidades nativas

Paso 3. Preparar el cuerpo de la petición e informar el idObject.
Obtén el cuerpo según el apartado API Interacciones básicas e informa la variable idObject en la URL.

Paso 4. Llamar al endpoint de edición correspondiente.

Manejo de listas de sub-entidades (dataset-fields, entidades contenidas, instancias, dataset input/output):

• Enviar la lista a null → no se edita esa relación.

• Enviar una lista vacía → se interpreta como eliminar / dejar sin elementos (en dataset, elimina todos los dataset-field).

Comportamiento de la edición

• Versionado: si la configuración indica que los cambios versionan el objeto, se genera una nueva versión con los cambios y se deprecia la entidad que se mandó editar.

• Campos no editables: se pueden editar enviando el parámetro disableNonEditValidations (desactivado por defecto).

• Invocación a Tot: en dataset gobernado con estado APPROVED y en DSA con estado APPROVED (enviando la información de la edición realizada).

Creación y actualización genérica de entidades

Además de los endpoints específicos por tipo, existe un endpoint genérico que permite crear o editar cualquier entidad —nativa o no nativa— finalizando directamente en el estado que se quiera, sin necesidad de workflow (por ejemplo, crear una entidad ya en estado APPROVED, o editar de APPROVED a DRAFT).

Este endpoint aplica controles similares a la creación desde el portal: no se permite crear objetos duplicados ni incluir valores incorrectos en los campos.

Para entidades DATASET, SOLUTION, INSTANCE o DSA se recomienda usar las APIs específicas por tipo, donde se amplía la información sobre entidades nativas completas.

Creación de una entidad

Paso 1. Preparar el cuerpo de la petición.
El idObject debe ser siempre null al tratarse de una creación. Dentro de la propiedad entityAttributes se incluyen todos los atributos del subtipo; el resto de propiedades dependen del subtipo que se quiera crear (ver tabla más abajo).

Paso 2. Llamar al endpoint genérico.

POST https://{{host}}/gateway/api/admin/kerno/create-update/entity/{objectSubType}

Propiedades específicas según el subtipo:

Actualización de una entidad

Paso 3. Preparar el cuerpo de la petición e informar el idObject.
Se usa el mismo endpoint que en la creación, pero indicando el idObject tanto en la URL como en el body.

Paso 4. Llamar al endpoint genérico de edición.

POST https://{{host}}/gateway/api/admin/kerno/create-update/entity/{objectSubType}/{idObject}

Restricción: no se puede editar una entidad en estado PENDING que ya tenga un workflow en proceso; hay que finalizar el workflow antes de editarla.

Consideraciones de la edición:

• Campos no editables: se pueden editar enviando el parámetro disableNonEditValidations (desactivado por defecto).

• Entidades nativas completas: puede ser necesario crear las relaciones internas, o usar exclusivamente las relaciones internas si solo se quieren editar los objetos internamente relacionados. Ver la sección de Edición de entidades nativas.

• Idioma de los atributos: debe incluirse el idioma en los atributos internacionales. Para atributos booleanos, de usuario, lista de valores, etc., no se incluye idioma y el valor debe indicarse según lo definido en attribute_definition_value.

Borrado de una entidad

Permite borrar una entidad. Consiste en la siguiente llamada:

DELETE https://{{host}}/gateway/api/admin/kerno/delete/entity/{idObject}.

Este endpoint borra toda la información de la entidad y aquella relacionada que aplique:

• Borrado de relaciones asociadas a la entidad (con sus atributos)

• Borrado de información de workflows asociados a la entidad (tanto en kerno como el workflow en activiti, que será borrado, junto con todas sus notificaciones)

• Borrado de las posibles combinaciones existentes si el borrado es un DATASET o DSA

• Borrado de la información guardada en el carrito relativa a la entidad a borrar

• Borrado de la propia entidad (con sus atributos)

• Borrado de la información indexada de la entidad (incluyendo snapshots)

• Borrado de la información indexada de las relaciones con la entidad (incluyendo snapshots)

No se podrán borrar procesos ni soluciones que dejen instancias huérfanas.

No se podrán borrar entidades que tengan ningún tipo de relación asociada, se enviará un aviso a los propietarios de los objetos de los extremos de la relación para avisar de que es necesario eliminar primero las relaciones para poder borrar sus objetos relacionados.

Creación y actualización de relaciones no nativas

Este endpoint permite crear o editar una relación no nativa finalizando directamente en el estado que se quiera, sin necesidad de workflow (por ejemplo, crear de cero directamente en APPROVED, o editar de APPROVED a DRAFT).

Aplica controles similares a la creación desde el portal: no se permite crear objetos duplicados ni incluir valores incorrectos en los campos.

Creación de una relación

Paso 1. Preparar el cuerpo de la petición.
El idObject debe ser siempre null al tratarse de una creación. Dentro de la propiedad relationshipAttributes se incluyen todos los atributos de la relación. Los atributos source y destination son obligatorios.

Paso 2. Llamar al endpoint.

POST https://{{host}}/gateway/api/admin/kerno/create-update/relationships/{objectSubType}

Actualización de una relación

Paso 3. Preparar el cuerpo de la petición e informar el idObject.
Se usa el mismo endpoint que en la creación, pero indicando el idObject tanto en la URL como en el body.

Paso 4. Llamar al endpoint de edición.

POST https://{{host}}/gateway/api/admin/kerno/create-update/relationships/{objectSubType}/{idObject}

Restricción: no se puede editar una entidad en estado PENDING que ya tenga un workflow en proceso; hay que finalizar el workflow antes de editarla.

Consideraciones de la edición:

• Campos no editables: se pueden editar enviando en el body el parámetro disableNonEditValidations (desactivado por defecto).

• Idioma de los atributos: debe incluirse el idioma en los atributos internacionales. Para atributos booleanos, de usuario, lista de valores, etc., no se incluye idioma y el valor debe indicarse según lo definido en attribute_definition_value.

Borrado de una relación

Permite borrar una relación. Consiste en la siguiente llamada:

DELETE https://{{host}}/gateway/api/admin/kerno/delete/relationship/{idObject}

Este endpoint borra toda la información de la relación y aquella relacionada que aplique:

• Borrado de información de workflows asociados a la relación(tanto en kerno como el workflow en Activiti, que será borrado, junto con todas sus notificaciones)

• Borrado de la propia relación (con sus atributos)

• Borrado de la información indexada de la relación (incluyendo snapshots)

Otras operaciones

Obtener metadato de una entidad

Este endpoint permite obtener los datos de un metadato definido de una entidad, dichos datos serán devueltos de la misma manera que reciben en el portal, es decir con la estructura de menús y secciones (incluyendo el menú y secciones ficticias para los campos customs).

Consiste en la llamada:

GET https://{{host}}/gateway/api/admin/kerno/entity/{objectSubType}/{idObject}

Cambiar Unidad Organizativa de una entidad

Te permite cambiar la unidad organizativa de una entidad sin pasar por la validación de workflow que normalmente se aplica.

Consiste en la llamada

POST https://{{host}}/gateway/api/admin/kerno/change-organizational-unit/{{idObject}}

Las validaciones que aplica son las mismas que desde el portal, no se puede cambiar la ou de una entidad que no existe o de aquellas que no tengan ou por sí mismas como INSTANCE.

Cambiar el estado de una entidad

Permite cambiar el estado de una entidad a cualquier estado, sin aplicar la lógica que suele tener dicho estado (ex: cambiarlo a expired cambiaría solo la entidad, no sus relaciones, no involucraría a tot si es necesario, etc).

Consiste en la llamada:

PUT https://{{host}}/gateway/api/admin/kerno/entity/change-state/{idObject}/{state}

En caso de cambiar el estado de DATASET, se actualizarán sus DATASET FIELD con el mismo estado.

Cambiar el estado de una relación

Permite cambiar el estado de una relación a cualquier estado permitido para éstas, sin aplicar la lógica que tiene la actualización de una relación entera. No se permitirá el cambio de estado de una relación nativa.

Consisten en la llamada:

PUT https://{{host}}/gateway/api/admin/kerno/relationship/change-state/{idObject}/{state}

donde idObject es el id de la relación a modificar y state el estado al que se desea cambiar.

Cambiar el nombre de una entidad o relación

Realiza un cambio de nombre en la entidad o relación especificada en el cuerpo de la petición.

Antes de cambiar el nombre se aplicarán las validaciones de PKs correspondientes al subtipo de la entidad o relación que se esté intentando modificar. Por tanto, si se introduce un nombre que ya existe para otra (o la misma) entidad, el usuario recibirá una excepción en la respuesta de la petición.

El renombrado afectará a todas las persistencias del nombre del objeto y de la ARI del objeto.

• Base de datos

  • entidad o relación

  • auditoría

  • notificaciones

  • workflows

• Indexación

Observaciones a tener en cuenta:

• El nombre no puede superar los 255 caracteres.

• No se permite renombrar objetos que tengan un workflow en proceso.

• Para modificación del nombre de un DSA aprobado que contenga entidades gobernadas conviene revisar la documentación del plugin correspondiente.

• No se permite sobreescribir el nombre de objetos en estado PENDING, ni en objetos que tengan otra versión.

Obtener atributos que dependen de otros atributos

Indica, para el valor de un atributo dado, qué valores de atributos dependen del indicado. Se puede aplicar para todos los subtipos o la relación que aplique a uno solo.

Consiste en la llamada:

POST https://{{host}}/gateway/api/admin/kerno/relationship

Descripción de las variables, todas son obligatorias:

• nameAttributeSource Nombre del atributo origen

• nameAttributeDest Nombre del attributo destino

• valueAttributeSource Lista de valores de origen de los cuáles queremos saber sus relacionados

• objectSubType Subtipo de la plantilla en la cual están definidos los atributos

Edición masiva de objetos

Permite editar los mismos atributos con los mismos valores a una lista de objetos..

Consiste en la llamada:

PUT https://{host}/gateway/api/admin/kerno/attribute/update/{objectType}/{objectSubType}

Como opción se incluye otro parámetro en la llamada: validateType. Este parámetro indica si se quiere validar el tipo de los parámetros (que los números son números o que el valor sea válido en aquellos campos con valores limitados, por ejemplo), por defecto está a true y solo se debe incluir si se quiere deshabilitar esas validaciones.

Como resultado se recibirá un OK (200) si todo ha ido bien o un PARTIAL CONTENT (206) si algún objeto no pudo ser editado, indicando el error que sucedió (será una lista con tantos elementos como objetos fallaron al editar).

Desadherencia de un DSA

Permite ejecutar la desadherencia de un DSA para el usuario indicado en la petición.

Consiste en la llamada:

POST https://{{host}}/gateway/api/admin/kerno/disadhere/{idObject}

Los únicos usuarios que no se permite desadherir son los owners de la unidad organizativa del DSA.

Indexado de todas las entidades

Permite actualizar completamente la colección de SolR de los objetos de Anjana (solo la de kerno, no los snapshots), eliminando todos los objetos presentes y reindexando.

Consiste en la llamada:

PUT https://{{host}}/gateway/api/admin/kerno/index/all-entities

Este endpoint lanza en segundo plano el procesado de todos los objetos y su indexado. Dependiendo del tamaño de los mismos y las configuraciones del servidor, se puede demorar el proceso.

Internamente se realiza por bloques configurables. Si el proceso no indexa correctamente todos los elementos, revisar y ajustar la configuración de los bloques para que se adapte a lo que el sistema soporte.