Atauliza nova forma de exportação de documentos do zope

Migração-sapl-2.5-para-3.1.md

@@ -47,8 +47,8 @@ DATABASE_URL_FONTE = mysql://sapl:sapl@localhost:3306/interlegis
 Posteriormente rodar a seguinte sequencia de comandos estando no ambiente virtual::
 ```
 ./manage.py shell --settings=sapl.legacy_migration_settings
-%run sapl/legacy/migration.py
-migrate()
+In [1]: from sapl.legacy.migracao import migrar_dados
+In [2]: migrar_dados()
 ```
 ## Migração de documentos do sapl 2.5
 No sapl 2.5 todos os documentos ficavam armazenados no ZODB (o banco do Zope).
@@ -60,40 +60,42 @@ No sapl 3.1 eles ficam no sistema de arquivos convencional e portanto precisam:
 
 ### Exportar os documentos para o sistema de arquivos
 
+Exite um subprojeto no repositório do sapl na pasta Instale o projeto versionado em `sapl/legacy/scripts/exporta_zope`. Ele deve ser instalado em virtualenv separado com python 2.7
 Siga os seguintes passos:
 
-1. Instale o `Products.FSDump` no sapl 2.5.
-
-   Para isso basta colocar a pasta `Products/FSDump` do projeto https://github.com/zopefoundation/Products.FSDump na pasta `Products` da instalação do sapl 2.5 e reiniciar o Zope.
-
-   A pasta a ser instalada é a seguinte:
-   https://github.com/zopefoundation/Products.FSDump/tree/master/Products/FSDump
-
-2. Na ZMI, na pasta `sapl_documentos`, adicione um objeto do tipo `Dumper`:
-
-   - Em `Filesystem path` escolha uma pasta do sistema de arquivos local para onde os arquivos serão copiados
-   - Desmarque a opção `Use .metadata file`
-   - Clique no botão `Add`
-
-3. Use o objeto `Dumper` criado para exportar os arquivos:
-
-   - Clique no objeto `Dumper` criado para ver suas opções
-   - Confira seus parametros e clique em `Change and Dump`
-   - Aguarde a exportação dos arquivos e verifique que foram copiados para a pasta indicada
-
+1. Crie um _virtualenv_ com python 2.7
+2. Instale nesse _virtualenv_ as dependências em `sapl/legacy/scripts/exporta_zope/requirements.txt`
+3. Coloque uma cópia do arquivo Data.fs (o arquivo de dados do zope) em uma pasta local. Não realize esse procedimento contra o arquivo em produção. Uma forma de obter uma cópia desse arquivo é fazer um pack no zope e copiar o arquivo Data.fs.old criado.
+4. Limpe a pasta `media` de sua instalação do sapl. Se necessário faça um backup de seu conteúdo. A forma padrão deste procedimento extrai os arquivos do Data.fs nesta pasta.
+5. Com o _virtualenv_ ativado e na pasta `sapl/legacy/scripts/exporta_zope` rode a exportação usando a função `exporta_zope.dump_sapl` com o caminho do `Data.fs` como parâmetro. A forma mais simples de fazer isso é rodar o script `exporta_zope` com o caminho do `Data.fs` como argumento. Por exemplo:
+```
+    > ./exporta_zope.py caminho/para/Data.fs.old
+```
+   Isso criará, na pasta `media` de sua instalação:
+   * um arquivo `usuarios.yaml` com todos os usuários do zope, seus perfis e hashes de suas senhas;
+   * uma pasta `sapl_documentos` com todo conteúdo extraído dessa pasta do zope;
+   * uma pasta `XSLT` com todo conteúdo extraído dessa pasta do zope;
 
 ### Vincular os documentos ao novo banco do sapl 3.1
 
 1. Primeiramente migre o banco do sapl 2.5 para o sapl 3.1
-
-2. Copie a pasta exportada `sapl_documentos` dentro da pasta `media` da instalação do sapl 3.1
-
+2. Conserve o conteúdo da pasta `media` criado pela extração anterior
 3. De forma semelhante ao realizado na migração do banco, dentro no mesmo ambiente virtual, rode os seguintes comandos::
 ```
 ./manage.py shell --settings=sapl.legacy_migration_settings
-%run sapl/legacy/migracao_documentos.py
-migrar_documentos()
+In [1]: from sapl.legacy.migracao import migrar_documentos, migrar_usuarios
+In [2]: migrar_usuarios()                                              
+   ...: migrar_documentos()
 ```
+  Isto irá fazer as seguintes atualizações no banco do sapl 3.1:
+ 
+  * criará os usuários presentes no arquivo `media/usuarios.yaml` (ou atualizar os existentes) com seus perfis e senhas e apagará o arquivo;
+  * vinculará os documentos presentes na pasta `media/sapl_documentos` a seus registros (migrados anteriormente do sapl 2.5) e os moverá para os locais corretos dentro de `media/sapl`. Como os arquivos são movidos (e não copiados) este procedimento só pode ser realizado uma vez. Guarde um backup da pasta `media/sapl_documentos` extraída ou repita a extração do zope, se precisar repetir esse passo.
+  
+  Após esse procedimento restarão na pasta `media/sapl_documentos` os documentos sem registro correspondente e, portanto, não migrados. Eles pertenciam a registros que foram excluídos no sapl 2.5. Guarde o conteúdo restante da pasta `media/sapl_documentos` **fora de sua instalação** para efeito histórico ou descarte se preferir reter apenas o Data.fs.
+  
+  Sugerimos que sempre retenha seus dados originais (Data.fs, dump do mysql).
+
 ### Para indexar os arquivos para pesquisa textual
 ```
 workon sapl