Owl

1. Introduccion

Owl provee las clases con los tipos de datos comunes, pero a su vez unas interfaces para que se puedan implementar procesamiento de datos personalizados definiendo un formato Xml al cual se deben ajustar para poder integrase a la herramienta.

Owl utiliza como base el lenguaje Xml y lo extiende a través de su propio lenguaje llamado XOML (eXtensible Owl Markup Language), este lenguaje se utiliza para configurar los Owl Output Config permitiendo realizar configuraciones más robustas y con más opciones.

Es importante mencionar que Owl es sensible a mayúsculas y minúsculas.

2. Estructura del Owl

Para poder trabajar con Owl se requiere lo siguiente:

Owl Output Config: En este archivo se define la estructura de salida, con sus validaciones y mapeo del documento, este archivo se configura con la sintaxis XOML.
OwlSettings: Clase que nos define las configuraciones de la transformación
- Ruta u objeto del Owl Output Config.
- Ruta u objeto del Owl Output Config base.
- Objeto de references cruzadas.
- Separador de decimales.
- Configuración de instancia.
IFormatInput: Define el tipo de entrada para el proceso de datos.
IFormatOutput: Define el tipo de salida para la generación de datos.
OwlHandler: Clase que se encarga de controlar todo el proceso de transformación de datos, para este proceso se crea un objeto del tipo de la clase inyectandole el objeto OwlSettings y se invocan sus métodos LoadConfigMap, LoadInput y WriteOutput.

2.1 Owl Output Config.

En este archivo es donde se define la estructura del archivo a generar con el mapeo y validaciones requeridas, el siguiente ejemplo muestra un archivo de configuración:

<?xml version="1.0" encoding="utf-8" ?>
<owl>
 <structure>
    <section name="header" separator=",">
        <element name="id" default="H" />
        <element name="field_1" />
        <element name="field_2" />
    </section>
    <section name="detail" itera="details">
        <element name="id" default="D" />
        <element name="field_1" />
        <element name="field_2" />
    </section>
 </structure>
</owl>

2.2 OwlSettings

Esta estructura se utiliza para realizar la configuración de mapeo de Owl, en esta estructura se define el archivo Owl Output Config, y si aplica en Owl Output Config base, el DataSet de references, el separador de decimales que se usa a la entrada y a la salida, también podemos configurar si se requiere una instancia.

OwlSettings settings = new OwlSettings
{
 References = new DataSet(),
 PathConfig = @"D:\ruta\config_5.0.xml",
 PathConfigBase = @"D:\ruta\configbase.xml"
};

2.3 IFormatInput.

Interfaz para las estructuras de entrada, define métodos para la carga y obtención de datos. Owl provee soporte para entradas basadas en XML mediante la clase XmlInput.

2.4 IFormatOutput.

Interfaz para las estructuras de salida, define métodos para la generación de datos. Owl provee soporte para salidas de tipo Archivo Plano, EDI, ANSI, XML, Json y SQL mediante las clases FlatFileOutput, EDIOutput, ANSIOutput, XmlOutput, JsonOutput y SQLOutput respectivamente, pero cada desarrollador puede crear sus tipos de salidas personalizados.

2.5 OwlHandler.

Clase que se encarga de controlar todo el proceso de transformación de datos, para este proceso se crea un objeto del tipo de la clase inyectandole una instancia de OwlSettings y se invocan sus métodos LoadConfigMap, LoadInput y WriteOutput para iniciar el proceso de transformación:

Owl = new OwlHandler(settings);
Owl.LoadConfigMap();
Owl.LoadInput(new XmlInput(@"D:\ruta\file.xml"));
foreach (GenericOutputValue value in Owl.WriteOutput(new FlatFileOutput())) { Process }

Adicional si se requiere generar una instancia de la configuración se puede realizar asignando la propiedad Instance igual a true en el objeto OwlSettings, al asignar dicho valor indicamos que solo se va a generar un archivo de muestra, por lo tanto Owl no realiza validaciones, no genera eventos y solo se van a tomar en cuenta las Owl Keywords default, variable y key para los valores de los elementos; los demás valores van a ser el Nombre que se configure al elemento.

Generar una instancia sirve para ver una muestra del documento que genera la configuración sin necesidad de tener un documento de entrada

3. XOML

El XOML (eXtensible Owl Markup Language / Lenguaje Extensible de Marcado para Owl) es un lenguaje de Owl para configurar los Owl Output Config permitiendo realizar configuraciones más robustas y con más opciones, se basa en XML.

La sintaxis de XOML se utiliza para configurar las propiedades de un determinado objeto y se puede realizar de la siguiente forma:

TIPO	EJEMPLO
Atributo: Se coloca la propiedad como atributo Xml y se asigna directamente el valor de la propiedad	<element length=”12” />
Atributo con Inline XOML: Se coloca la propiedad como atributo Xml y el valor de la propiedad con una Owl Keyword seguida de dos puntos y luego el valor, las Owl Keywords soportadas son:<br/>default, variable, key y xpath	<element length=”variable:lengthConfig” /><br /><element Descripcion=”xpath:val/@val” />
Etiqueta: Se coloca una subetiqueta con el nombre del objeto, punto “.” y el nombre de la propiedad, para asignar el valor se utiliza una Owl Keyword	<element> <element.length> <Owl Keyword> </element.length> </element>
Listas: Cuando una propiedad del objeto sea una lista, se puede configurar como atributo enviando los valores separados por coma “,” o se puede configurar como etiqueta creando por cada valor una etiqueta nueva con la estructura (nombre objeto, punto “.”, propiedad, punto “.”, value (texto fijo)). Cuando se envíe como atributo con los valores separados por coma, cada valor se puede configurar con Inline XOML	Atributo: <reference CamposObtener="Campo1,Campo2" Atributo con Inline XOML: <reference CamposObtener="xpath:val/@val,Campo2" Etiqueta: <reference> <reference.CamposObtener> <reference.CamposObtener.Valor> <Owl Keyword> </reference.CamposObtener.Valor> <reference.CamposObtener.Valor> <Owl Keyword> </reference.CamposObtener.Valor> </reference.CamposObtener> </reference>

Dentro de la configuración es posible combinar diferentes propiedades como atributo y como etiqueta, en caso de que la misma propiedad se configure como atributo y etiqueta solo se tendrá en cuenta el atributo.

Nota: Algunos objetos tienen restricciones en la configuración XOML y solo permiten configurar algunas propiedades como atributo o solo como etiqueta.

4. Owl Keywords

Para poder definir el valor que se mapea en un determinado elemento se debe hacer por medio de Owl Keywords, que son las que nos permiten obtener un valor, existen dos tipos de Owl Keywords, las de valores y las de funciones.

Owl Keywords - Valores: Son las que nos permiten mapear un valor directamente.

NOMBRE	DESCRIPCION
default	Valor por defecto
variable	Valor de una variable que se configura en la clase OwlHandler o con las opciones new-variable y counter
key	Valor que se obtiene a partir de una valor reservado en la estructura de salida
xpath	Valor que se busca en la estructura de entrada
reference	Valor que se obtiene del DataSet de references configurado en OwlSettings

Owl Keywords - Funciones: Son las que nos permiten realizar alguna función previa a los valores para retornar los datos

NOMBRE	DESCRIPCION
concatenate	Función para concatenar múltiples valores
substring	Función para obtener una subcadena
length	Función para obtener la longitud de un valor
is-number	Función para validar si el valor representa un número
index-of	Función para obtener la posición donde se encuentra una subcadena dentro del valor
is-empty	Función para validar si el valor está vacío
trim	Función para quitar los espacios en blanco al valor
if	Función para hacer un validación entre dos valores

Las Owl Keywords se colocan en el Owl Output Config con la sintaxis XOML, sin embargo, las Owl Keywords default, variable, key y xpath se pueden colocar como atributos:

Atributo: Owl busca el atributo que corresponda a una Owl Keyword permitida como atributo y obtiene el valor, en caso de que se coloquen varios atributos que correspondan a Owl Keywords solo se toma una (para definir cual se toma, Owl tiene en cuenta el orden dado en la tabla anterior).

4.1 default

Valor por defecto, la sintaxis es:

Atributo: default=”VALUE”
XOML: Las siguientes dos opciones:

<default value="" />

<default>
 <default.value></default.value>
</default>

4.2 variable

Valor de una Variable que se configura en la clase OwlHandler o con las opciones new-variable y counter.

Para agregar variables por código se realiza de la siguiente forma:

Owl["variable-name"] = "value";

La sintaxis es:

Atributo: variable=”variable-name”
XOML: Las siguientes dos opciones:

<variable value="" />

<variable>
 <variable.value></variable.value>
</variable>

Si se trata de acceder a una variable que no existe se genera una excepción de tipo OwlException.

4.3 key

Valor que se obtiene a partir de una palabra reservada en la estructura de salida, la sintaxis es:

Atributo: key=”value”
XOML: Las siguientes dos opciones:

<key value="" />

<key>
 <key.value></key.value>
</key>

Las salidas de Owl incluyen las siguientes palabras keys:

CONSECUTIVE_ITERA: Entrega el consecutivo de la iteración actual.
CONSECUTIVE_ITERA_PARENT: Entrega el consecutivo de la iteración actual de la sección padre.
DATETIME:FORMAT: Fecha y hora del sistema. El formato es opcional, si no se coloca formato, por defecto es “yyyyMMdd”, los formatos soportados son los mismos de .Net, ejemplos:
- Si la fecha es 2020/12/24 el Owl devolverá lo siguiente:
- FECHAHORA_SISTEMA => 20201224
- FECHAHORA_SISTEMA:yyyyMMddHHmm => Devuelve 202012240935
TOTAL_SECTIONS: Contador de secciones.
CONSECUTIVE_STRUCTURE: Entrega el consecutivo de la iteración de la estructura actual.

En caso de colocar un valor no soportado se genera una excepción de tipo OwlException.

4.4 xpath

Valor que se busca en la estructura de entrada, la sintaxis es:

Atributo: xpath=”xpath”
XOML: Las siguientes dos opciones:

<xpath value="" />

<xpath>
 <xpath.value></xpath.value>
</xpath>

En caso de haber un error con el xpath se genera una excepción de tipo OwlSectionException.

4.5 reference

Valor que se obtiene del DataSet configurado en la propiedad References de OwlSettings, la sintaxis es: