Importação e Exportação de Canais no Lumis Portal

Objetivos

• Compreender a funcionalidade de importação e exportação de canais no Lumis Portal.
• Apresentar diversas alternativas para a importação e exportação de canais no Lumis.
• Compreender cuidados que devem ser tomados na estruturação de um portal para permitir uso desta funcionalidade.
• Entender erros que podem ocorrer durante a importação de canais e como resolvê-los.

As anotações se encontram no final do artigo.

Pré-requisitos

• Ao menos um portal montado, permitindo exercitar os conceitos apresentados.

Conceitos

A funcionalidade de importação/exportação de canais do Lumis Portal tem por objetivo efetuar a extração de uma estrutura de canais de um Portal para um arquivo, ou de importar este arquivo para um Portal, criando-o ou alterando-o conforme o necessário.

O cenário mais comum de aplicação desta funcionalidade é o 'deployment' de alterações em um Portal, quando estas exigem mudanças de estrutura. Desta forma é possível automatizar a criação ou alteração da estrutura de um portal a partir de uma montagem efetuada e testada em outro ambiente; canais, páginas, grupos e controle de acesso, entre diversas outras características, podem ser facilmente ajustados.

A importação e exportação não se limita à estrutura do Portal. O uso desta funcionalidade permite, também, que dados cadastrados em um Portal possam ser importados para outro, juntamente com as eventuais alterações estruturais feitas. Esta abordagem evita a necessidade de inserir no portal destino, manualmente ou por meio de 'scripts', conteúdos importantes que tenham sido cadastrados no portal de origem.

Entretanto, a importação/exportação não deve ser vista como um mecanismo de sincronismo absoluto entre dois portais. Serviços novos que tenham sido desenvolvidos no portal origem devem ter seus arquivos copiados para o portal destino, e devidamente registrados; usuários e grupos globais também não são automaticamente criados no portal destino*¹; a exportação (e posterior importação) usualmente abrange apenas parte da estrutura do Portal, não garantindo portanto que ambas as estruturas sejam idênticas.

A funcionalidade de importação e exportação de canais deve ser vista, portanto, como uma ferramenta acessória à transferência (usualmente parcial) de estrutura e, opcionalmente, de conteúdo, de um portal origem para um portal destino.

Estruturas de canais

Em um portal desenvolvido em Lumis, canais funcionam de forma similar a diretórios em estruturas de arquivos. Cada um destes canais podem conter páginas, e um ou mais subcanais (que, por sua vez, possuem novos subcanais e páginas). Esta estrutura hierárquica é utilizada para organizar de forma lógica todo o portal, podendo ser também usada para estabelecer critérios de navegação. Esta estrutura pode conter também instâncias de serviço, grupos locais e controle de acesso, bem como parâmetros de configuração que definem cada canal. Estas instâncias de serviço podem conter conteúdos (informações) já cadastradas no Portal. Páginas também possuem parâmetros de configuração e instâncias de interfaces de serviço*².

Quando um canal é exportado, estas informações são armazenadas em um arquivo que descreve por completo toda a estrutura e (opcionalmente) os dados cadastrados em suas instâncias de serviço. Desta forma, a futura importação deste arquivo é capaz de replicar a estrutura original em um outro ambiente, desde que alguns cuidados (mencionados neste mesmo documento) sejam tomados.

Alguns cuidados a serem tomados no procedimento.

Ao planejar uma exportação é necessário levar em conta algumas características:

• A exportação/importação é suportada apenas entre ambientes que possuam a mesma versão do Lumis Portal, pois depende do tratamento de estruturas internas do produto que podem sofrer alterações a cada versão lançada.
• A exportação de conteúdo (opcional) ocorre tanto para serviços Lumis quanto para serviços customizados de gestão de conteúdo.
• Alguns serviços padronizados podem não ter seus dados exportados, como é o caso do serviço de comentários.
• Apenas conteúdos das instâncias de serviço que se encontrem na estrutura selecionada serão exportados, mesmo que estes conteúdos sejam referenciados por alguma instância de serviço que tenha seus dados exportados*³.
• Estilos pertencentes à definição do serviço não são exportados, são considerados parte do código-fonte e serão atualizados ao registrar a nova versão do serviço. Estilos adicionados pelo front-end e não definidos no serviço são considerados adições à solução, e são exportados e importados normalmente.

Atenção:

Ao exportar um canal, devemos levar em consideração todas suas dependências externas (aquelas que dependem de objetos que não estão no escopo de exportação). Durante a exportação de uma estrutura de canais, estas dependências serão verificadas, cabendo ao administrador optar por ser alertado em caso de conflitos que possam prejudicar a futura importação do arquivo.

Algumas dependências que devem ser levadas em conta:

• Templates de canais ou páginas criados fora do escopo do canal exportado e que estão aplicados em subcanais e páginas deste canal. Caso estes templates inexistam no portal destino, haverá um erro de importação pela inexistência da dependência externa ao escopo de importação.
• Instâncias de serviços que utilizam outras instâncias de serviços. Ex: instância do serviço de Notícias que pode utilizar instâncias dos serviços de Documentos e Imagens, que por sua vez estão instanciados fora do escopo da estrutura a ser exportada. Esta situação não incorrerá em erro de importação, mas causará um problema de visualização dos conteúdos no portal destino decorrente da ausência dos arquivos.
• Workflow customizado pertencente ou não ao escopo da exportação. Workflows devem ser registrados no portal destino, da mesma forma que serviços novos ou que tenham sido alterados. Em algumas situações alterações em serviços que não tenham sido replicadas no portal destino podem não apresentar problemas imediatos, o que usualmente traz inconsistências de difícil isolamento e investigação.
• Usuários e grupos globais do controle de acesso de um objeto pertencente ao escopo da exportação*⁴. A exportação não cria ou altera informações de usuários e grupos locais, sendo necessário ao administrador executar estes passos manualmente se necessário, em etapa anterior à importação do arquivo. É importante perceber, neste caso, que as referências se dão pelos IDs dos usuários e grupos; assim sendo, a criação de um grupo com mesmo nome (mas ID diferente) no portal destino pode não resolver ou evitar erros de importação.

Exportação de canais.

A funcionalidade é parte da área administrativa (F12) do Lumis Portal. Para exportar um canal basta clicar com o botão direito do mouse sobre o mesmo selecionar a opção “Exportar”.

Será então apresentada uma nova janela, contendo as opções para a exportação:

• Arquivo: nome do arquivo “lec” (Lumis Exported Channel) a ser criado com a estrutura de canais exportada. Recomenda-se nomear o arquivo com o nome do canal ou com algum nome que reflita seu caminho, facilitando uma futura importação.
• “Incluir sub-canais recursivamente”: permite escolher se os sub-canais da estrutura serão exportados ou não (default: exportação recursiva*⁵). Em alguns momentos onde é necessário exportar apenas as estruturas existentes em um canal (páginas, templates de página, grupos locais, instâncias de serviços, configurações do canal, etc.), sem exportar os sub-canais. Neste caso, a importação não altera os sub-canais que existam no portal destino.
• “Incluir conteúdo”: indica se o usuário deseja exportar o conteúdo das instâncias de serviço que estejam na estrutura exportada. A exportação do conteúdo é completa, incluindo versionamento, meta-dados de publicação e estágio atual do workflow.
• “Incluir referência a membros do tipo usuário”: permite incluir ou não na exportação a relação de "membro de" entre usuário e grupo.
• “Exibir alertas sobre dependências externas”: Se marcado, serão apresentados alertas na tela com as dependências externas encontradas ao longo da exportação. Sugere-se marcar sempre esta opção.

A segunda aba deste formulário permite especificar que grupos globais devem ser exportados. Para permitir a exportação de um grupo global do portal origem, é preciso informá-los neste formulário de exportação, não importando se eles fazem ou não parte do controle de acesso da estrutura exportada. Grupos explicitamente indicados neste formulário serão criados no portal destino, caso não existam.

Para mencionar explicitamente que grupos devem ser exportados, basta clicar em “Adicionar” e selecioná-los. Todos os grupos globais do portal serão exibidos, à exceção dos grupos padrão que, certamente, já existem em um portal destino ('Administradores do Portal', 'Publicadores', 'Desenvolvedores', 'Usuários Cadastrados' e 'Todos os Usuários').

Há, também, a opção de excluir algum grupo local da exportação, bastando utilizar o botão “Excluir”, ao lado de “Adicionar”.

Atenção:

A extensão do arquivo de exportação criado será sempre “*.lec”, não sendo portanto necessário colocar tal informação no nome do arquivo.

O arquivo é salvo por padrão no diretório “lumisdata/data/exporteddata”, não sendo também necessário informar o diretório de exportação.

Durante a exportação de canais podem ser apresentados alertas de dependência externa. A imagem a seguir mostra um exemplo desta situação, mencionada anteriormente.

Para cada objeto citado no alerta de dependências externas, é informado o seu ID e outras informações que podem ajudar na identificação do objeto, como nome e título. Além disso, as setas localizadas ao lado de todos os objetos listados no relatório remetem para sua localização no portal.

A melhor forma de resolução deste problema dependerá da situação, cabendo ao administrador do portal decidir o que deve ser feito. No caso apresentado, a dependência externa (um grupo local) pode ser facilmente exportado, solucionando o problema.

Uma situação bastante comum é a presença de instâncias de serviço fora da estrutura a ser exportada. Neste caso, ocorrerá erro se a instância de serviço não existir previamente no portal destino.

Uma forma de resolver este tipo de conflito é mover, temporariamente, a instância para a estrutura a ser exportada, voltando a recolocá-la no canal correto após a exportação (e após a importação, se for o caso). Porém esta solução é adequada apenas quando sabemos que a instância não existe no portal destino – a tentativa de importar uma nova instância com mesmo ID resultará em erro de importação*⁶.

Alguns objetos dependentes podem ser desnecessários, podendo neste caso ser removidos do portal origem em momento anterior à exportação.

É importante, apenas, que o administrador conheça a estrutura de ambas as soluções (portais) e seja capaz de identificar e solucionar problemas que possam ocorrer.

O processo de exportação pode mostrar as seguintes informações e alertas:

1. Informações sobre o andamento do processo da exportação e sobre o sucesso da exportação dos conteúdos da(s) instância(s) de serviço;
2. Avisos em geral, tais como restrições em relação às dependências externas;
3. Possíveis erros não esperados na exportação. Tais erros podem ocorrer, por exemplo, quando há insuficiência de memória, de espaço em disco, etc;
4. O Resultado da exportação com sucesso (ou com erro);
5. Aviso de exportação cancelada, a qualquer momento, antes do seu término, quando acionado o botão "Cancelar".

A importação de canais deve ser apenas uma das partes integrante de um roteiro bem definido do 'deployment'; se forem necessárias cópias de arquivos, registro de serviços, execução de scripts e outros passos manuais ou automatizados, estes precisam estar claramente listados. Como mencionado anteriormente, a importação/exportação de canais é uma ferramenta, não uma funcionalidade completa de sincronismo entre portais ou mecanismo complexo de deployment.

Importação de Canais

Esta opção permite que as estruturas de canais (e, opcionalmente, conteúdos) previamente exportadas sejam importadas. O arquivo de importação deve possuir a extensão '.lec' e residir no diretório “lumisdata/data/exporteddata” do servidor de aplicação. Caso o diretório não exista, deverá ser criado, e o arquivo para importação para ele copiado.

Alguns pontos devem ser mencionados:

• Portais de origem e destino devem estar na mesma versão do produto Lumis Portal;
• A estrutura importada será exibida no portal, após selecionar o botão "Fechar" do relatório de importação;
• Quaisquer dependências externas devem sempre ser importadas ou criadas anteriormente à importação das estruturas que delas dependam. Esta importação deve ser sempre feita preservando-se os IDs originais, uma vez que as relações se dão a partir desta informação.
• Serviços novos ou que tenham sofrido alterações, bem como arquivos de definição de workflows customizados devem ser anteriormente registrados no ambiente destino. Todos os passos necessários para o registro desses serviços devem ser seguidos adequadamente (cópia dos arquivos XML, XSL, classes, arquivos e ajustes de configuração, scripts de banco de dados, etc.).

Para, efetivamente, importar o arquivo desejado, basta clicar com o botão direito do mouse sobre o canal onde a estrutura deve ser importada e selecionar a opção “Importar”, como mostra a imagem a seguir.

A imagem a seguir apresenta as opções disponibilizadas para configuração da importação de canais. Adiante serão apresentados alguns detalhes sobre cada opção.

O formulário possui duas abas. Na primeira, ‘Geral’, as seguintes informações devem ser preenchidas:

• Arquivo: Nome do arquivo gerado na exportação, sem a extensão (“.lec”);
• Ação: O administrador pode escolher entre importar a estrutura diretamente abaixo do canal selecionado (canal ‘filho’) ou atualizar o canal atual.
• Preservar IDs: Permite migrar uma mesma estrutura entre, por exemplo, servidores de desenvolvimento e produção, mantendo-se a coerência entre os IDs de todos os objetos. Recomenda-se sempre utilizar esta opção. Quando não há preservação de IDs, todos os canais, serviços e páginas são cadastrados como novos elementos no portal. Quando a importação tem por objetivo atualizar um canal selecionado (na opção ‘ação’, anteriormente mencionada), a preservação de IDs é implicitamente assumida e não pode ser alterada.
• Simular apenas: Permite apenas simular a importação, visualizando, eventuais diferenças entre a estrutura de origem e a de destino. Com uso desta opção é possível verificar no relatório de importação a possível ocorrência de erros devido a dependências externas.
• CSS e XSL existentes: Permite escolher a ação a ser tomada em casos de conflito de arquivos CSS ou XSL. Um conflito ocorre quando o CSS/XSL que está sendo importado já existe no portal, mas há diferenças quanto ao registro e/ou conteúdo do arquivo referenciado. Quando ocorre um conflito, há risco de quebra de layout, tanto para layouts existentes no portal quanto para os presentes nos canais que estão sendo importados. As ações possíveis são:
• Abortar importação (sugerida por padrão): Em caso de conflito, a importação é abortada. Esta opção permite que os conflitos sejam manualmente analisados e resolvidos, para que a importação possa ser realizada novamente;

• Atualizar: Deve ser escolhida quando é preciso sobrescrever os arquivos e/ou registros de CSS ou XSL existentes no portal destino; o administrador assume, portanto, que os arquivos provenientes do portal origem devem ser importados.
• Manter: Deve ser escolhida quando não se deseja substituir os arquivos e/ou registros de CSS e XSL existentes no portal corrente; neste caso, o administrador assume serem corretos os existentes no portal destino. Neste caso, o portal manterá o arquivo CSS do ambiente corrente e seu registro, mesmo que as informações quanto ao nome, descrição e caminho sejam diferentes do registro do ambiente de origem (contanto, é claro, que os IDs sejam iguais).

O uso da opção ‘manter’ possui também as seguintes características:

• Se o registro de um arquivo (CSS/XSL) não existe mas há um arquivo CSS/XSL com o nome esperado, o registro é criado e o arquivo é mantido;
• Se um arquivo (CSS/XSL) não existe no ambiente destino mas há um registro, este é mantido; ou seja, o portal mantém o ambiente corrente em relação ao registro do CSS, embora não tome nenhuma ação em relação ao arquivo (este não é criado para não comprometer a solução).

A importação do CSS também ocorrerá com sucesso quando não existir o arquivo no ambiente corrente e quando os IDs dos registros forem diferentes. Neste caso, arquivo e registro serão criados.

A importação não ocorrerá com sucesso quando o arquivo e suas informações de registro sejam os mesmos do CSS previamente exportado, e seus IDs sejam diferentes. Neste caso, o mecanismo de importação/exportação preserva a coerência estrutural do portal.

• Incluir conteúdo: Permite determinar se os conteúdos das instâncias de serviço exportadas serão importados*⁷. A premissa para que haja importação de conteúdos é que os IDs da estrutura sejam preservados; isto é necessário para que as referências dos conteúdos aos objetos não sejam perdidas. Desta forma, ao selecionar esta opção de inclusão de conteúdo, a opção "Preservar IDs" é automaticamente selecionada e não pode ser desmarcada.

Os metadados que acompanham o conteúdo, também são importados (datas de publicação, expiração, workflow, entre outros). Durante o processo de importação, as instâncias de serviço importadas têm seus conteúdos reindexados.

A segunda aba deste formulário (‘membros’) é apresentada a seguir.

Grupos locais são sempre importados, embora existam regras de importação para o tratamento de seus membros (usuários e grupos locais e globais e controle de acesso). Tais regras podem ser configuradas, considerando que grupos ou ACLs podem existir ou não no ambiente corrente. Para novos grupos ou ACLs, pode-se optar por:

• Importar todos os membros: serão importadas as referências de grupos e usuários locais e globais, bem como seu controle de acesso;
• Importar todos os membros do tipo grupo: serão importadas somente as referências de grupos locais ou globais, bem como seu controle de acesso;
• Importar todos membros do tipo grupo ignorando os que não existem: serão importadas somente as referências de grupos locais ou globais, bem com seu controle de acesso, ignorando referências que não existam no ambiente corrente.
• No caso de haver referências a um ou mais grupos locais como "membros de" outros grupos locais, pode-se utilizar esta opção de importação de membros quando os grupos tiverem sido criados em outros canais não exportados e pertencerem ao controle de acesso do canal exportado. A mesma opção pode ser utilizada no caso de referências a grupos globais como "membro de" um grupo local, quando tais grupos globais não foram exportados junto com a estrutura e não existirem no ambiente corrente.
• Importar somente membros locais do tipo grupo: serão importadas somente as referências de grupos locais, bem como seus respectivos controles de acesso.

Para grupos ou ACLs existentes, pode-se optar por:

• Importar todos os membros: serão importadas as referências de grupos e usuários locais e globais, bem como seus respectivos controles de acesso. Neste caso, as relações dos membros e as suas referências preexistentes serão removidas do ambiente destino durante a importação;
• Importar todos os membros do tipo grupo: serão importadas somente as referências de grupos (locais ou globais), bem como controle de acesso. Neste caso, as relações existentes dos membros que tem grupos envolvidos e as suas referências serão também removidas do ambiente destino durante a importação;
• Importar todos os membros do tipo grupo ignorando os que não existem: serão importadas somente as referências de grupos locais ou globais, bem com seu controle de acesso, ignorando aquelas referências que não existam no ambiente corrente. Neste caso, as relações existentes dos membros que tem grupos envolvidos e as suas referências serão removidas do ambiente corrente durante a importação;
• Importar somente membros locais do tipo grupo: serão importadas somente as referências de grupos locais, bem como seu controle de acesso. Neste caso, as relações existentes dos membros que tem grupos locais envolvidos e as suas referências são removidas do ambiente corrente durante a importação.

Há dois tipos de alertas possíveis durante a importação:

1. Informações sobre o andamento do processo da importação, sucesso da importação do conteúdo da(s) instância(s) de serviço e da reindexação dos mesmos;
2. Alertas sobre atualizações e manutenções de arquivos CSS e XSL;
3. Erros na importação. A ocorrência de pelo menos um erro acarreta o cancelamento da importação;
4. Importação concluída sem sucesso, com erros que podem estar relacionados a dependências externas não tratadas, problemas com arquivos CSS ou XSL ou conflitos de IDs entre origem e destino.
5. Resultado da importação com sucesso.

Alguns detalhes do processo de importação:

• A importação pode ser cancelada a qualquer momento antes do seu término, selecionando o botão "Cancelar"; todas as alterações estruturais feitas até o momento serão desfeitas.
• Após a importação com sucesso as instâncias de serviços envolvidas são reindexadas.
• É necessário clicar em "Fechar", após conclusão da importação, para que efetivamente a nova estrutura seja exibida no navegador.
• Para informações completas sobre o processo de importação, pode-se verificar o log de serialização, no diretório de logs do produto.

Quiz

1. Qual o objetivo da Exportação e Importação de Canais no Lumis Portal? Em que cenários pode ser interessante o uso desta funcionalidade.
2. Na exportação de canais, em que diretório será salvo o arquivo que contém as configurações a serem exportadas? Qual a extensão de tal arquivo?
3. O que são consideradas dependências externas? Cite dois tipos de dependências externas e formas de tratá-las durante o processo de exportação de um canal.
4. A exportação com sucesso de uma estrutura garante a importação desta mesma estrutura em um outro portal? Cite três situações em que uma estrutura corretamente exportada não pode ser importada com sucesso.
5. Qual o papel da importação/exportação de estruturas de canais em um processo de deployment? Que passos e cuidados devem ser usualmente tomados antes da execução da importação de um canal?
6. Qual a importância de preservar os IDs dos objetos durante a importação de canais?
7. Que tipo de conflitos podem existir com arquivos CSS e XSL durante a importação de canais no Lumis Portal? Que tipos de tratamento são disponibilizados pela ferramenta para tratar estes casos?

Hands-on

Exercício 1:

1. Criar uma estrutura de canais, com a seguinte apresentação:

• Canal 1
  • Página 1
  • Página 2
• Canal 2

2. Exportar a estrutura do “Canal 1” e importar sobre o “Canal 2”, atualizando tal canal;
3. Verificar se a estrutura do “Canal 1” foi replicada no “Canal 2”;
4. Alterar os arquivos CSS e XSL das páginas do “Canal 1” e exportar novamente;
5. Importar novamente no “Canal 2”, utilizando a opção para manter os arquivos e verificar que as alterações não foram refletidas no canal destino.
6. Tentar importar novamente, utilizando a opção de ‘preservar IDs’ e observar o que acontece.

Exercício 2:

1. Criar uma nova instalação do produto, em ambiente similar ao apresentado no Exercício 1;
2. Exportar o “Canal 1” e importar em tal ambiente;
3. Criar um novo grupo de usuários no primeiro ambiente, exportar novamente a estrutura de canais (não acrescentando o novo grupo criado) e importar no segundo ambiente;
4. Verificar os problemas de importação, devido à dependência externa do grupo criado;
5. Exportar novamente, incluindo o novo grupo, e importar novamente no segundo ambiente.

Autor: Erich Angerman

Anotações:

1 - É possível mencionar explicitamente (manualmente) que grupos globais devem ser exportados no processo.

2 - Informações completas sobre as estruturas de montagem de uma solução em Lumis Portal podem ser encontradas no artigo que trata deste assunto: Conceitos de Montagem de um Portal em Lumis

3 - Considere por exemplo, um link no editor HTML que referencia um documento de uma instâncias de serviços ‘Documentos’ que não esteja no escopo da exportação; neste caso, será exportado somente o link com a referência. O documento não será exportado. Da mesma forma, conteúdos de instâncias externas à estruturas que tenham sido publicados para uma instância interna a ela (usando o recurso ‘publicar para’) não serão importados.

4 - Não se encontram nesta situação os usuários e grupos padrão do Lumis Portal, pois existem em ambos os portais (origem e destino), não podendo ser apagados. A única exceção a esta regra é o usuário ‘admin’, considerado uma referência externa (pode ser apagado, desde que outro seja criado e faça parte do grupo de ‘administradores do portal’).

5 - Elementos globais (CSS, por exemplo) são importados, independente desta opção.

6 - Em casos como este, a tentativa de resolver um conflito na exportação pode causar um erro de importação.

7 - Em outras palavras, pode-se exportar uma estrutura com conteúdos e optar por sua não-importação no ambiente de destino.

Autor: Erich Angerman