Vincular arquivos a cadastros

A vinculação de arquivos a cadastros é útil para associar arquivos do sistema de arquivos virtual (VFS) ou da LobStorage a determinados cadastros do sistema, como imagens associadas aos produtos ou usuários.

Arquivos armazenados no sistema de arquivos virtual sempre estão disponíveis de forma pública na Internet. Eles devem ser utilizados exclusivamente para documentos ou imagens que não contenham dados privados ou sensíveis que necessitem controle de acesso. O acesso a esses arquivos é otimizado, pois eles estão totalmente ou parcialmente armazenados no cache local. Por outro lado, o uso excessivo de arquivos na VFS aumenta o tempo de inicialização e o tamanho do cache local de todos os Engines.

Arquivos da LobStorage são gravados exclusivamente na base de dados e são privados por padrão. O acesso aos arquivos exige autorização do usuário, permitindo o controle de acesso com base no modelo de permissão do sistema. Por não serem gravados no cache local, o acesso aos arquivos da LobStorage é mais lento que o observado no sistema de arquivos virtual. Essa característica torna necessária uma estratégia adequada de cache no cliente onde os documentos e imagens são apresentados para o usuário.

Configurando o ambiente para a importação

Para realizar a configuração do ambiente de forma a possibilitar a importação, é necessário seguir os seguintes passos:

Deve ser criado o diretório de vínculo. Este diretório será utilizado para receber o arquivo x-model onde serão definidas algumas propriedades relativas à importação e é também onde será definido o campo de chave estrangeira que será a base do relacionamento com o cadastro. Este diretório deverá ficar em /Dados/Sistema/Relações/Relações entre Cadastros/Relações entre Cadastros e Arquivos. Caso os arquivos sejam de imagem, o diretório deverá ficar em /Dados/Sistema/Relações/Relações entre Cadastros/Relações entre Cadastros e Arquivos/Relações entre cadastros e imagens.

Agora que criamos o diretório de vínculo, devemos criar o arquivo do tipo x-model. Este arquivo precisa ter, necessariamente, as propriedades a seguir:

• this.linkedTableName: deve conter o nome da tabela de cadastro que ficará vinculada aos arquivos importados. Exemplo:

  this.linkedTableName = 'iGroupUser';
  

• this.linkFieldName: o nome do campo, na tabela de vínculo, que será utilizado como chave estrangeira para a tabela de cadastro. Este é o campo base do relacionamento entre cada registro de vínculo e o respectivo registro associado na tabela de cadastro. Exemplo:

  this.linkFieldName = 'iGroupUser';
  

• this.formatFileName: uma lista com os nomes dos campos-chaves de pesquisa. Cada arquivo importado deverá conter, em seu nome, chaves de pesquisa que serão utilizadas na busca e vinculação do arquivo importado. A importação ocorrerá para cada arquivo que tiver, em seu nome, uma chave de pesquisa correspondente a um registro da tabela de cadastro. Assim, por exemplo, para um this.formatFileName.push('iName'), os arquivos importados serão aqueles que contiverem em seu nome um valor correspondente na coluna iName da tabela de cadastro. Veja o manual Importação de documentos ou imagens para mais detalhes do seu uso.

• this.storageKind: indica o tipo de armazenamento de arquivos. Para arquivos públicos deve ser informado “vfs” e para arquivos privados deve ser informado “lob”. Exemplo:

  this.storageKind = 'vfs';
  

• this.storageClassKey: para arquivos públicos deve ser informada a chave do diretório onde ficarão armazenados os arquivos no sistema de arquivos virtuais, ou seja, na tabela iVfs. Para a importação de imagens, é recomendado que o diretório seja filho de /Dados/Arquivos/Imagens. Já para arquivos privados deve ser informado a chave de uma classe filha de /Dados/Sistema/Large Objects. Exemplo:

  this.storageClassKey = -1898139457; // Imagens de Usuários
  

• this.accept (opcional): indica o tipo dos arquivos aceitos na operação de upload. Mais detalhes em 'UploadOptions.prototype.accept'. Exemplo:

  this.accept = 'image/*'; // Somente imagens serão importadas
  

• this.maxFiles (opcional): define a quantidade máxima de arquivos que podem ser recebidos. Por padrão, será imposto o limite de 50 arquivos vinculados ao cadastro. Exemplo:

  this.maxFiles = 50;
  

• this.maxFileSize (opcional): define o tamanho máximo do arquivo a ser importado em bytes. Por padrão, será imposto o limite de 10Mb. Exemplo:

  this.maxFileSize = 10 * Math.pow(1024, 2); // 10MB
  

• this.maxTotalSize (opcional): define o tamanho máximo em bytes disponível para armazenamento de todos os arquivos vinculados ao cadastro. Por padrão, será imposto o limite de 100Mb. Exemplo:

  this.maxTotalSize = 100 * Math.pow(1024, 2); // 10MB
  

• this.cacheControl (opcional): diretiva HTTP de cache que deve ser aplicada aos arquivos gerenciados pela classe de relacionamento de arquivos. Por padrão, é utilizado o valor “private, max-age=86400”, indicando que o navegador ou outro cliente HTTP deve realizar o cache do arquivo por 24 horas. Mais detalhes sobre valores aceitos por essa diretiva podem ser observados em https://developer.mozilla.org/pt-BR/docs/Web/HTTP/Headers/Cache-Control#diretivas_de_cache_de_respostas. Exemplo:

  this.cacheControl = 'private, max-age=604800'; // 1 semana
  

  Importante: a configuração “cacheControl” é permitida apenas para os arquivos armazenados na LobStorage. Arquivos armazenados na VFS seguem a configuração padrão do tratamento de arquivos estáticos do servidor Engine, que atualmente solicita para o cliente HTTP o cache privado por até 24 horas.

Ainda neste arquivo do tipo x-model, outra necessidade é a própria definição do campo citado em linkFieldName. Exemplo da definição do campo iGroupUser na tabela iDataRel, campo este utilizado para a vinculação de imagens ao cadastro de usuários do Sistema:

var fld = this.field('iGroupUser', 'int64');
fld.label = 'Usuário';
fld.required = true;
fld.classKey = -1898187809 /* Usuários */;
fld.lookupType = LookupType.RECORD;
fld.help = 'Campo que armazena a chave do usuário associado à imagem.';

Configurando atributos para o arquivo

No arquivo x-model da vinculação de arquivos a cadastros poderão ser criados campos dinâmicos, que representam os atributos do arquivo. Esses atributos serão gravados como atributos extras do arquivo, podendo ser recuperado através do método 'FileStorage.prototype.getExtraFileAttributes'. Exemplo:

var fld = this.fileAttribute('size', 'int64');
fld.label = 'Tamanho';
fld.classKey = -1898141855; /* Tamanho */
fld.required = true;
fld.help = 'Atributo tamanho da imagem.';

Atenção: eventos não podem ser definidos para esses campos.

Configurando o controle de acesso dos arquivos da LobStorage

Os arquivos da LobStorage por padrão podem ser acessados apenas pelos usuários que têm permissão de visão à classe da relação de arquivos (Imagens de usuários, Imagens de recursos, etc), à classe do registro vinculado (Usuários, Recursos, etc) e à classe onde os arquivos são gravados, filha de Large Objects. Essa regra é determinada pela função userHasViewPermission da definição da classe de relacionamento, que por padrão tem a seguinte implementação:

this.userHasViewPermission = function (userKey, fileKey, linkedRecordKey) {    
  return security.getPermission(this.key, 'iView', userKey) &&
    security.getPermission(this.storageClassKey, 'iView', userKey) &&
    security.getPermission(dbCache.getClass(linkedRecordKey), 'iView', userKey);
};

Essa função pode ser modificada nas classes de relacionamentos de arquivos para implementar um controle de acesso mais adequado ao uso dos documentos e imagens armazenados. Por exemplo, as imagens de perfil de usuário são visíveis para todos os usuários logados, independentemente das permissões de visão dos usuários às classes de dados de relacionamento e da Lob Storage.