<style>
    img {
        /* max-width: 1200px; */
        /* max-height: 800px; */
        max-width: 100%;
    }
    pre {
        background-color: #F5F5F5;
        padding: .5rem;
    }
</style>

# webshell

<!-- En un organismo existe la necesidad de mantener en constante comunicación a los miembros que lo conforman, esto para agilizar los procesos internos. Para hacer esto posible se ha creado un archivo que ofrece funciones para administrar las bitácoras (donde se requiera) de los distintos paquetes que conforman el sistema V12. -->

Archivos de inclusión requerido

- `functions.dkh`
- `serialize.dkh`
- `dbr.dkh`
- `dbr.vars.dkl`
- `magick.dkh`
- `webshell.dkh`

## Administración de bitácoras

### Variables globales

#### @DB

Referencia a una conexión de bases de datos.

Tipo: `object`, Predeterminado: `null`

**Nota:**
Si se hace uso de la biblioteca fuera del contexto de web es requerido asignar una conexión de base de datos abierta a la variable, por defecto se toma al que se encuentre establecido dentro de `@http_context`.

#### @webshell.delete_max_rows

Máximo de filas eliminadas a devolver por el método [webshell.detlog.delete.getall](#webshell.detlog.delete.getall).

Tipo: `integer`, Predeterminado: `5`

#### @webshell.max_rows

Máximo de filas a devolver por los métodos [webshell.detlog.getall](#webshell.detlog.getall), [webshell.detlog.file.getall](#webshell.detlog.file.getall).

Tipo: `integer`, Predeterminado: `200`

### Métodos

#### webshell.detlog.register

Registra las bitácoras para los [tipos de elementos de datos (DET)](/es/productos/v12/devops/dte.dkl) proporcionados.

```dkl
webshell.detlog.register(ldetlog)
```

**Parámetros**

- `array` **ldetlog** Lista de objetos con la información de las bitacóras a registrar

**Devoluciones**

`void`

**Excepciones**

Excepciones de bases de datos.

**Ejemplo**

En el siguiente ejemplo se registra la bitácora para los documentos de ventas.

```dkl
#include "dkli.dkh"
#!
program ""
{
    #include "functions.dkh"
    #include "serialize.dkh"
    #include "dbr.dkh"
    #include "dbr.vars.dkl"
    #include "magick.dkh"
    #include "webshell.dkh"

    ref @DB = dbr.open("miconexion@grupoapps")

    // "det": (string) Identificador del tipo de elemento proporcionado
    // "rpriv": (string) Itentificador del privilegio de lectura para la bitácora
    // "wpriv": (string) Itentificador del privilegio de escritura para la bitácora
    // "var_files": (string) Nombre de la variable de configuración que contiene la ruta física de guardado de los archivos, si es null, se usará la variable `ws_file_store`.
    ref lista = from.json('[
        {
            "det": "DET01C",
            "rpriv": "VD40",
            "wpriv": "VD41",
            "var_files": ""
        }
    ]')

    do webshell.detlog.register(lista)
}
```

#### webshell.wsdet.get

Obtiene la información de la bitátora registrada por medio del tipo de elemento de dato.

```dkl
webshell.wsdet.get(detid)
```

**Parámetros**

- `string` **detid** Identificador del tipo de elemento de dato

**Devoluciones**

`array` | `null`

Retorna el array con la información del registro de la bitácora especificada o nulo si el id proporcionado no existe.

**Excepciones**

Excepciones de bases de datos.

**Ejemplo**

En el siguiente ejemplo se obtiene el registro de la bitácora para los documentos de venta.

```dkl
#include "dkli.dkh"
#!
program ""
{
    #include "functions.dkh"
    #include "serialize.dkh"
    #include "dbr.dkh"
    #include "dbr.vars.dkl"
    #include "magick.dkh"
    #include "webshell.dkh"

    ref @DB = dbr.open("miconexion@grupoapps")

    ref wsdet = webshell.wsdet.get("DET01C")
    
    do print(to.json(wsdet))
    /**
    Salida esperada:
    {
        "sys_pk": (integer) Clave primaria del registro
        "sys_guid": (string) Identificador único de 32 caracteres de alcance global
        "det": (string) Identificador del tipo de elemento proporcionado
        "rpriv": (integer) Clave primaria del privilegio de lectura para la bitácora
        "wpriv": (integer) Clave primaria del privilegio de escritura para la bitácora
        "var_files": (string) Nombre de la variable de configuración que contiene la ruta física de guardado de los archivos
    }
    */
}
```

#### webshell.detlog.add

Agrega un mensaje a la bitácora de elemento proporcionado para el tema de conversación específicado.

```dkl
webshell.detlog.add(detid,guid,userid,text,filepath,idarchivo)
```

**Parámetros**

- `string` **detid** Identificador del tipo de elemento de dato.
- `string` **guid** Cadena de hasta 32 caracteres que identifica a un tema de conversación.
- `string` **userid** Identificador del usuario que escribe el mensaje.
- `string` **text** Cadena con el mensaje escrito por el usuario.
- `string` **filepath** Ruta donde se aloja el archivo adjunto. **Opcional**, pero requerido si el registro se trata de un archivo adjunto.
- `string` **idarchivo** Cadena de hasta 32 caracteres que identifica al archivo adjunto. **Opcional**, pero requerido si el registro se trata de un archivo adjunto.

**Devoluciones**

`array`

Devuelve un array de los datos proporcionados.

**Excepciones**

Excepciones de base de datos.

**Ejemplo**

En el siguiente ejemplo se agrega un mensaje a la bitácora de los documentos de ventas por el usuario "bob".

```dkl
#include "dkli.dkh"
#!
program ""
{
    #include "functions.dkh"
    #include "serialize.dkh"
    #include "dbr.dkh"
    #include "dbr.vars.dkl"
    #include "magick.dkh"
    #include "webshell.dkh"

    ref @DB = dbr.open("miconexion@grupoapps")
    
    ref msg = webshell.detlog.add("DET01C","da3d65ad317643feb53dde5518fc4e8c","bob","Hello World!!","","")

    do print(to.json(msg))
    /**
    Salida esperada:
    {
        "sys_guid": (string) Identificador único de 32 caracteres de alcance global
        "sys_dtcreated": (object) Referencia a un objeto que representa la fecha y hora en la que se creo el mensaje
        "sys_timestamp": (object) Referencia a un objeto que representa la fecha y hora en la que se actualizo el mensaje
        "origen": "DET01C"
        "guid": "da3d65ad317643feb53dde5518fc4e8c"
        "nota": "Hello World!!"
        "archivo": ""
        "idarchivo": ""
        "usuario": "bob"
    }
    */
}
```

#### webshell.detlog.get

Obtiene la información del registro de un mensaje.

```dkl
webshell.detlog.get(msgid)
```

**Parámetros**

- `string|integer` **msgid** Identificador del registro del mensaje a consultar

**Devoluciones**

`array`

Devuelve un array con la información del mensaje proporcionado.

**Excepciones**

Excepciones de base de datos.

**Ejemplo**

```dkl
#include "dkli.dkh"
#!
program ""
{
    #include "functions.dkh"
    #include "serialize.dkh"
    #include "dbr.dkh"
    #include "dbr.vars.dkl"
    #include "magick.dkh"
    #include "webshell.dkh"

    ref @DB = dbr.open("miconexion@grupoapps")

    ref msg = webshell.detlog.get(1)
    
    do print(to.json(msg))
    /**
    Salida esperada:
    {
        "sys_pk": (integer) Clave primaria del registro del mensaje.
        "sys_guid": (string) Identificador único de 32 caracteres de alcance global.
        "pk_det_log": (integer) Clave primaria del registro de la bitácora al que pertenece el mensaje.
        "fecha": (string) Fecha de creación del mensaje.
        "hora": (string) Hora de creación del mensaje.
        "guid": (string) Cadena de hasta 32 caracteres que identifica a un tema de conversación.
        "nota": (string) Mensaje escrito por el usuario.
        "archivo": (string) Ruta donde se aloja el archivo adjunto.
        "idarchivo": (string) Cadena de hasta 32 caracteres que identifica al archivo adjunto.
        "usuario": (string) Identificador del usuario.
        "det": (string) Identificador del tipo de elemento proporcionado
        "rpriv": (integer) Clave primaria del privilegio de lectura para la bitácora
        "wpriv": (integer) Clave primaria del privilegio de escritura para la bitácora
        "var_files": (string) Nombre de la variable de configuración que contiene la ruta física de guardado de los archivos
    }
    */
}
```

#### webshell.detlog.getall

Obtiene la información de los mensajes del tipo de elemento proporcionado para el tema de conversación indicado.

```dkl
webshell.detlog.getall(detid,guid,from,to)
```

**Parámetros**

- `string` **detid** Identificador del tipo de elemento de dato.
- `string` **guid** Cadena de hasta 32 caracteres que identifica a un tema de conversación.
- `integer` **from** Rango de registros, clave primaria del primer mensaje a tomar en cuenta. **opcional**
- `integer` **to** Rango de registros, clave primaria del último mensaje a tomar en cuenta. **Opcional**

**Devoluciones**

`array`

Devuelve una lista de objetos con la información de los mensajes del tipo de elemento proporcionado.

**Excepciones**

Excepciones de base de datos.

**Ejemplo**

En el siguiente ejemplo se consultan los mensajes de un documentos de venta.

```dkl
#include "dkli.dkh"
#!
program ""
{
    #include "functions.dkh"
    #include "serialize.dkh"
    #include "dbr.dkh"
    #include "dbr.vars.dkl"
    #include "magick.dkh"
    #include "webshell.dkh"

    ref @DB = dbr.open("miconexion@grupoapps")

    /**
    * Si `from` o `to` son cero, se asume lo mismo que se indica en el endpoint.
    * Las propiedades de los objetos de la lista de resultados devuelta corresponden a los que se definen en `webshell.detlog.get()`
    */
    ref mensajes = webshell.detlog.getall("DET01C","da3d65ad317643feb53dde5518fc4e8c",0,0)
}
```

#### webshell.detlog.delete

Elimina de forma lógica el registro del mensaje proporcionado.

```dkl
webshell.detlog.delete(msgid,userid)
```

**Parámetros**

- `integer` **msgid** Clave primaria del mensaje a eliminar
- `string` **userid** Identificador del usuario al que pertenece el mensaje a eliminar

**Devoluciones**

`void`

**Excepciones**

Excepciones de bases de datos.

**Ejemplo**

En el siguiente ejemplo se elimina el mensaje con clave primaria 1 del usuario "bob".

```dkl
#include "dkli.dkh"
#!
program ""
{
    #include "functions.dkh"
    #include "serialize.dkh"
    #include "dbr.dkh"
    #include "dbr.vars.dkl"
    #include "magick.dkh"
    #include "webshell.dkh"

    ref @DB = dbr.open("miconexion@grupoapps")
    do detlog.delete(1,"bob")
}
```

#### webshell.detlog.delete.getall

Obtiene la información de los mensajes eliminados en un tema de conversación.

```dkl
webshell.detlog.delete.getall(detid,guid)
```

**Parámetros**

- `string` **detid** Identificador del tipo de elemenento de dato.
- `string` **guid** Cadena de hasta 32 caracteres que identifica a un tema de conversación.

**Devoluciones**

`array`

Devuelve una lista de objetos con la información de los mensajes del tipo de elemento y tema proporcionado.

**Excepciones**

Excepciones de base de datos

**Ejemplo**

En el siguiente ejemplo de consultan los mensajes eliminados de un documento de venta.

```dkl
#include "dkli.dkh"
#!
program ""
{
    #include "functions.dkh"
    #include "serialize.dkh"
    #include "dbr.dkh"
    #include "dbr.vars.dkl"
    #include "magick.dkh"
    #include "webshell.dkh"

    ref @DB = dbr.open("miconexion@grupoapps")
    
    ref eliminados = webshell.detlog.delete.getall("DET01C","da3d65ad317643feb53dde5518fc4e8c")

    do print(to.json(eliminados))
    /**
    Salida esperada:
    {
        "pkmsg": (integer) Clave primaria del mensaje.
        "idmsg": (string) Identificador único de 32 caracteres de alcance global del mensaje.
        "fecha": (string) Fecha de creación del mensaje.
        "pkfile": (integer) Clave primaria del archivo adjunto.
        "guidfile": (string) Identificador único de 32 caracteres de alcance global del archivo adjunto.
        "idfile": (string) Cadena de hasta 32 caracteres que identifica al archivo adjunto.
        "nombre": (string) Nombre que identifica al archivo adjunto.
    }
    */
}
```

#### webshell.detlog.file.add

Registra los datos de un archivo adjunto.

```dkl
webshell.detlog.file.add(id,nombre)
```

**Parámetros**

- `string` **id** Identificador del archivo adjunto
- `string` **nombre** Nombre del archivo adjunto

**Devoluciones**

`void`

**Excepciones**

Excepciones de base de datos.

**Ejemplo**

```dkl
#include "dkli.dkh"
#!
program ""
{
    #include "functions.dkh"
    #include "serialize.dkh"
    #include "dbr.dkh"
    #include "dbr.vars.dkl"
    #include "magick.dkh"
    #include "webshell.dkh"

    ref @DB = dbr.open("miconexion@grupoapps")
    
    do webshell.detlog.file.add("d179cc6b10c641e0ac6001bf95319d73","F000001.zip")
}
```

#### webshell.detlog.files.save

Guarda en una ruta física y registra en la base de datos los archivos proporcionados. **Solo en contexto web**

```dkl
webshell.detlog.files.save(detid,guid)
```

**Parámetros**

- `string` **detid** Identificador del tipo de elemento de dato.
- `string` **guid** Cadena de hasta 32 caracteres que identifica a un tema de conversación.

**Devoluciones**

`void`

**Excepciones**

500 | No hay una ruta fisica para guardar los adjuntos.

Excepciones de base de datos.

**Ejemplo**

En el siguiente ejemplo se guardan y registran archivos adjuntos para un "Gasto".

```dkl
#include "dkli.dkh"
#!
program ""
{
    #include "functions.dkh"
    #include "serialize.dkh"
    #include "dbr.dkh"
    #include "dbr.vars.dkl"
    #include "magick.dkh"
    #include "webshell.dkh"
    
    do webshell.detlog.files.save("DET024","b1929b3ab29847bd9155e870bfc600d7")
}
```

#### webshell.detlog.file.get

Obtiene la información de registro de un archivo adjunto.

```dkl
webshell.detlog.file.get(id)
```

**Parámetros**

- `string` **id** Identificador del archivo adjunto

**Devoluciones**

`array`

Devuelve un objeto con los datos del archivo adjunto indicado.

**Excepciones**

Excepciones de base de datos.

**Ejemplo**

```dkl
#include "dkli.dkh"
#!
program ""
{
    #include "functions.dkh"
    #include "serialize.dkh"
    #include "dbr.dkh"
    #include "dbr.vars.dkl"
    #include "magick.dkh"
    #include "webshell.dkh"

    ref @DB = dbr.open("miconexion@grupoapps")
    
    ref file = webshell.detlog.file.get("d179cc6b10c641e0ac6001bf95319d73")

    do print(to.json(file))
    /**
    Salida esperada:
    {
        "sys_pk": (integer) Clave primaria del registro del mensaje.
        "sys_guid": (string) Identificador único de 32 caracteres de alcance global.
        "id": (string) Identificador del adjunto.
        "nombre": (string) Nombre del archivo.
        "usuario": (string) Identificador del usuario.
        "guid": (string) Cadena de hasta 32 caracteres que identifica a un tema de conversación.
    }
    */
}
```

#### webshell.detlog.file.getall

Obtiene la información de los adjuntos del tipo de elemento proporcionado para el tema de conversación indicado.

```dkl
webshell.detlog.file.getall(detid,guid,from,to)
```

**Parámetros**

- `string` **detid** Identificador del tipo de elemento de dato.
- `string` **guid** Cadena de hasta 32 caracteres que identifica a un tema de conversación.
- `integer` **from** Rango de registros, clave primaria del primer adjunto a tomar en cuenta. **opcional**
- `integer` **to** Rango de registros, clave primaria del último adjunto a tomar en cuenta. **Opcional**

**Devoluciones**

`array`

Devuelve una lista de objetos con la información de los adjuntos del tipo de elemento proporcionado.

**Excepciones**

Excepciones de base de datos.

**Ejemplo**

En el siguiente ejemplo se consultan los adjuntos de un documentos de venta.

```dkl
#include "dkli.dkh"
#!
program ""
{
    #include "functions.dkh"
    #include "serialize.dkh"
    #include "dbr.dkh"
    #include "dbr.vars.dkl"
    #include "magick.dkh"
    #include "webshell.dkh"

    ref @DB = dbr.open("miconexion@grupoapps")

    // Las propiedades de los objetos de la lista de resultados devuelta corresponden a los que se definen en `webshell.detlog.file.get()`
    ref mensajes = webshell.detlog.file.getall("DET01C","da3d65ad317643feb53dde5518fc4e8c",0,0)
}
```

#### webshell.detlog.unregiste

Elimina el registro de la bitácora por DET previamente registrada, se intenta la eliminación física y en caso de no ser posible se procede a eliminar de forma lógica.

```dkl
webshell.detlog.unregiste(det)
```

**Parámetros**

- `string` **det** Identificador del tipo de elemento de dato

**Devoluciones**

`integer`

Retorna el número de filas afectadas.

**Excepciones**

Excepciones de bases de datos.

**Ejemplo**

El siguiente ejemplo se cancela el registro de la bitácora de los documentos de venta.

```dkl
#include "dkli.dkh"
#!
program ""
{
    #include "functions.dkh"
    #include "serialize.dkh"
    #include "dbr.dkh"
    #include "dbr.vars.dkl"
    #include "magick.dkh"
    #include "webshell.dkh"

    ref @DB = dbr.open("miconexion@grupoapps")
    do webshell.detlog.unregiste("DET01C")
}
```

## Manipular imagenes

### Variables globales

#### @webShell.tamanio_img

Define el tamaño de las imagenes a usar como miniaturas.

Tipo: `integer`, Predeterminado: `300`

### Métodos

#### webshell.magick.generar.img

Redimensiona la imagen proporcionada.

```dkl
webshell.magick.generar.img(path,fileName)
```

**Parámetros**

- `string` **path** Ruta física donde se alojara la imagen.
- `string` **fileName** Nombre de la imagen a generar.

**Devoluciones**

`void`

**Excepciones**

**Ejemplo**

```dkl
#include "dkli.dkh"
#!
program ""
{
    #include "functions.dkh"
    #include "serialize.dkh"
    #include "dbr.dkh"
    #include "dbr.vars.dkl"
    #include "magick.dkh"
    #include "webshell.dkh"

    do webshell.magick.generar.img("data/@qname/@detid/@guid/","imagen.mini.jpg")
}
```

#### webshell.magick.img.eliminar

Elimina la imagen previamente redimensionada.

```dkl
webshell.magick.img.eliminar(path,fileName)
```

**Parámetros**

- `string` **path** Ruta física donde se aloja la imagen.
- `string` **fileName** Nombre de la imagen a eliminar.

**Devoluciones**

`void`

**Excepciones**

**Ejemplo**

```dkl
#include "dkli.dkh"
#!
program ""
{
    #include "functions.dkh"
    #include "serialize.dkh"
    #include "dbr.dkh"
    #include "dbr.vars.dkl"
    #include "magick.dkh"
    #include "webshell.dkh"

    do webshell.magick.img.eliminar("data/@qname/@detid/@guid/","imagen.mini.jpg")
}
```

## Almacén temporal de archivos

Solo contexto web.

#### webshell.temp.store

Guarda un archivo a una ruta temporal (data/@name/temp/@guid/).

```dkl
webshell.temp.store(guid,file)
```

**Parámetros**

- `string` **guid** Cadena que identifica a la carpeta que contendrá el archivo.
- `object` **file** Referencia a un objeto que representa el archivo a copiar.

**Devoluciones**

`string`

Devuelve la ruta y nombre del archivo copiado.

**Excepciones**

1 | Variable global '@http_context' no definida.

**Ejemplo**

```dkl
#include "dkli.dkh"
#!
program ""
{
    #include "functions.dkh"
    #include "serialize.dkh"
    #include "dbr.dkh"
    #include "dbr.vars.dkl"
    #include "magick.dkh"
    #include "webshell.dkh"

    function GuardarTemporales()
    {
        ref FILES = ifnull(@@(@http_context,"&request/files"),list.create())
        ref stored = list.create()
        guid = uuid()

        for i = 0; i < list.count(FILES)
        {
            ref file = list.obj(FILES,i)
            
            if file.exists(@@(file,"$temp_file")) && @@(file,"$filename")!="" && @@(file,"#size")>0 {
                filepath = webshell.temp.store(guid,file)
                do list.add(stored,filepath)
            }
        }

        return stored
        
        exception{ do pop_exception() }
    }

    do GuardarTemporales()
}
```

#### webshell.temp.list

Obtiene los archivos temporales del ID específicado.

```dkl
webshell.temp.list(guid)
```

**Parámetros**

- `string` **guid** Cadena que identifica a la carpeta que contiene los archivos.

**Devoluciones**

`array`

Devuelve una lista de objetos con las propiedades de cada archivo.

**Excepciones**

1 | Variable global '@http_context' no definida.

**Ejemplo**

```dkl
#include "dkli.dkh"
#!
program ""
{
    #include "functions.dkh"
    #include "serialize.dkh"
    #include "dbr.dkh"
    #include "dbr.vars.dkl"
    #include "magick.dkh"
    #include "webshell.dkh"

    ref temporales = webshell.temp.list("8d94627476b44fe8a595f879dd2f29af")
    // Salida esperada: {"guid":"","path":"","files":["","",...]}
}
```