-
Notifications
You must be signed in to change notification settings - Fork 96
Siga WF Documentação Técnica
Siga → Siga-Wf → Documentação Técnica
Esta página dá detalhes técnicos a respeito do Siga-Wf. Caso queira visualizar a documentação para o usuário, acesse esta página.
- JPDL: linguagem baseada em XML usada para definir os processos (documentação jPDL)
- Node: Caixa com uma atividade a ser executada por um sistema, seja manual ou automático. Um node poderia também iniciar um outro proceso, embora esse recurso não seja usado no Siga-Wf
- Task Node: Caixa a ser executada por um ser humano. Existem também outros tipos de node, como mail-node, action-node, entre outros. Pode-se também criar tipos personalizados de nodo, plugando-se funcionalidades.
- Task: é uma tarefa, produzida por um task node (embora possa ser produzida por outros meios). Sempre é executada por humanos. Um task node pode possuir mais de uma task. Nesse caso, o fluxo prossegue, saindo da task node, quando essas várias tasks componentes são executadas.
- Decision node: representa uma decisão tomada pelo sistema. Não por uma pessoa pois, nesse caso, seria uma task node com duas saídas.
- Start state: ponto inicial do processo. É um node, que pode conter uma task. No Siga-Wf, essa task contém a informação de quem iniciou o processo do workflow, ou seja, quem assinou o processo do Siga-Doc.
- Pooled Actors: tabela associada à task instance que indica os possíveis executores de uma tarefa.
- Token: representa a execução do processo. Um token transita pelo fluxo e pode conter variáveis (assim como as variáveis do processo). O gestor define as variáveis do processo ao montar o gráfico usando a JPDL e também faz referência a elas em outros pontos do arquivo XML. Essa operação é, naturalmente, sujeita a erros. Um token pode se dividir, nos forks, embora não usemos esse recurso no Siga-WF.
- Swimlane: é um agrupamento de nodes. Quando uma das tarefas é alocada a uma pessoa (ou seja, é definido o actorID), o workflow memoriza a pessoa alocada, de modo que, caindo novamente o token cair numa outra task do mesmo swimlane, o actorID é o mesmo.
- Event: Dentro de uma task pode haver um event (node-live, por exemplo, representando o momento da saída do nodo). Um event pode executar um script. Ver processDefinition.xml. É possível também inserir uma tag , dentro da definição de uma transição.
O Siga-Wf consiste num conjunto de classes que encapsulam a ferramenta JBPM3 e em tabelas geradas para uso por essa ferramenta. Além das tabelas do JBPM3, foram criadas também as tabelas WF_CONFIGURACAO e WF_CONHECIMENTO.
No diretório siga-wf/tools está o pacote com todos os artefatos do JBPM3 baixados (manual, bibliotecas não importadas pelo Siga, código fonte do JBPM3, arquivos-modelo de configuração e também, na pasta db, o código SQL usado como base para o script acima.
A classe UploadServlet recebe, pelo método handleRequest, o pacote com os dados do processo a ser incluso no sistema. Esses dados consistem num arquivo .zip contendo a definição do processo (process-definition.xml). Usando esse zip como parâmetro, é feita então uma chamada para JBPM, que gera o process definition (jbpmContext.deployProcessDefinition()). Com base em mapeamentos do Hibernate feitos pelo JBPM, as entradas são criadas nas tabelas, especialmente JBPM_PROCESSDEFINITION.
O controle de versão das definições de processo é feito com base no nome do processo, definido no arquivo XML com a definição enviado para o servlet, e num número de versão sequencial.
A opção Ferramentas -> Editar Procedimento, que possibilita editar a definição do processo pela interface ou diretamente pela edição do arquivo XML, usa a classe EdicaoController e a página form.jsp.
A associação das tarefas à definição do processo, feita por meio da tela Ferramentas -> Designar Tarefas e gravada pelo método gravar(), da classe DesignacaoController, é armazenada como WfConfiguracao, ligando cada processo/tarefa à pessoa, lotação ou expressão definida como atendente.
Se uma pessoa for definida como atendente designada de uma tarefa, ela será automaticamente atribuída como actorId (não só inclusa nos pooled actors) das task instances geradas para a tarefa.
Chamada por JSP
Um exemplo de disparo do processo do Siga-Wf pelo Siga-Doc está no modelo sec.jsp (Solicitação Eletrônica de Contratação), que cria um workflow após a assinatura através da chamada da tag mod:assinatura
Chamada por Freemarker
Os modelos em freemarker podem chamar o siga-wf definindo a macro pre_assinatura no modelo geral, que é processada em ExMovimentacaoController.java
[#macro pre_assinatura]
[#if gerar_pre_assinatura!false]
[#nested]
[/#if]
[/#macro]
O trecho de código delimitado pela tag assinatura (ou pela macro pre_assinatura, no caso do Freemarker) pode incluir uma chamada à função criarWorkflow, da classe FuncoesEL, ainda no Siga-Doc, que possui uma chamada para o método criaWorkflow, da classe ExBL, o qual, por sua vez, faz a chamada efetiva ao módulo Siga-Wf para iniciar o processo (método do Siga-Wf criarInstanciaDeProcesso()).
Criação do processo do Siga-Wf
A criação de processos no Siga-Wf dá origem ao registro correspondente nas tabela JBPM_PROCESSINSTANCE.
No momento da criação da instância do processo WfBL.createProcessInstance() são definidas as variáveis wf_cadastrante, wf_lota_cadastrante, wf_titular e wf_lota_titular, que armazenam a informação sobre o cadastrante e o titular do processo. As variáveis definidas não ficam visíveis ao usuário; são apenas internas. Seus valores, acessados e/ou alterados pelas tasks, são obtidos invocando-se o execution context (ctx.getContextInstance().getVariable()).
Localização de processos iniciados
Para se encontrar um processo a partir de um documento do Siga-Doc, a tabela SIGAWF.JBPM_PROCESSINSTANCE deve ser consultada. Para isso, primeiro, é preciso recuperar o id do processo do Siga-Doc na tabela JBPM_VARIABLEINSTANCE. Caso não haja resultados, o workflow não foi iniciado para o processo do Siga-Doc. O campo processinstance_ recupera o identificador do procedimento. Os campos start_ e end_ da tabela JBPM_PROCESSINSTANCE indicam a data de início e fim do procedimento. Para listar todas as tarefas do procedimento e suas respectivas datas de início e fim, a tabela SIGAWF.JBPM_TASKINSTANCE deve ser consultada. O campo actorid indica quem executou a tarefa. Exemplo de consulta para o processo JFRJ-2014-EOF/00339:
`select *`
`from SIGAWF.JBPM_VARIABLEINSTANCE `
`where STRINGVALUE_ like ‘<código do processo do Siga-Doc>’; `
`select * from SIGAWF.JBPM_PROCESSINSTANCE `
`where id_ = NNNNN;`
`select * `
`from SIGAWF.JBPM_TASKINSTANCE `
`where procinst_ = NNNNN;`
Caso o procedimento tenha sido encerrado, o campo end_ da tabela JBPM_PROCESSINSTANCE estará preenchido. A data da última tarefa do procedimento contante na tabela JBPM_TASKINSTANCE será igual à data de encerramento do procedimento. Além disso, o campo actorid conterá a matrícula do usuário que encerrou o procedimento (workflow).
- Obs: Se os milisegundos da data estão todos zerados, provavelmente o encerramento foi feito manualmente a pedido do usuário.
Criação e alocação da tarefa
O Siga-Wf, através da classe WfAssignmentHandler.java, associa as tarefas às pessoas e lotações. Essa classe, que estende um handler do JBPM, é chamada pelo próprio JBPM quando uma tarefa é criada. Nessa classe, o actorID é associado a um usuário do Corporativo. No arquivo jbpm.cfg.xml fica a definição de que essa é a classe a ser usada como Handle.
O método dessa classe invocado pelo JBPM é o assign(). Essa rotina obtém, para a task que está se iniciando, a WfConfiguracao representando a designação de uma pessoa, lotação ou expressão para a tarefa e insere essa informação na task em formato String.
Quando cada tarefa é instanciada, o pooled actors é preenchido. Quando uma task instance é criada, o pooled actors é definido com a informação de todas as pessoas da lotação designada, ou seja todos os possíveis atendentes da tarefa. Quando um deles clica no botão Prosseguir (ou Pegar), o actorId da task instance é preenchido, referenciando a pessoa que clicou.
Tarefas da lotação
Não existe o conceito de lotação no JBPM3, para a qual tarefas possam ser alocadas. O método [getTaskList] (https://github.com/projeto-siga/siga/blob/master/siga-wf/src/main/java/br/gov/jfrj/siga/wf/bl/WfBL.java), chamado ao se acessar a inbox - método inbox, da classe AppController - passa os actorIDs e obtém as tarefas alocadas pra essas pessoas. Wf não tem o conceito de lotação. É necessário passar a lista de actorIDs.
Geração dos campos da tela de exibição da tarefa
Cada um dos task nodes dá origem a uma tela (/sigawf/app/task, baseada em [task.jsp] (https://github.com/projeto-siga/siga/blob/master/sigawf/src/main/webapp/WEB-INF/page/app/task.jsp)). Para cada saída possível do node, há um botão de confirmação. Quando há uma variável na tarefa que pede o número de um documento, é exibido um campo Seleção na tela. Essa tela possui também parte contendo campos para definição da pessoa responsável (actorId) e da lotação (pooled actors) e uma área que permite referenciar um conhecimento contendo orientações ao usuário sobre como executar a tarefa.
Comentários
Os comentários feitos durante a execução da task (e que ficam associados à tarefa) são armazenados na tabela JBPM_COMMENT. Ver o método commentTask, da classe AppController.
A seção que lista os comentários já realizados traz informações baseadas nos comentários das task instances anteriores.
Término da tarefa
Conforme mencionado acima, os botões exibidos para término da task (e passagem à task seguinte) são gerados conforme as saídas predefinidas para o nodo. Quando o botão é pressionado, o Siga-Wf obtém a transição associada ao botão (o que já causou erros de encoding, visto que o teste é feito pelo nome). Ver o método executeTask, da classe AppController.
Ainda nesse método, os valores parâmetros vindos do formulário são armazenados em variáveis (taskInstance.getToken().getProcessInstance().getContextInstance().setVariable()).
Conforme mencionado no início, neste ponto, o actorId da taskInstance é definido para referenciar a pessoa que clicou em Prosseguir (ou no botão relativo a uma das saídas possíveis do node).
Chamada aos outros módulos do Siga a partir do Siga-Wf
Durante a transição, é verificado, via webservice, se o documento correspondente no Siga-Doc pode ser transferido. A não ser que haja predefinição na task de que a transição não implicará transferência automática do documento. Ver o método assertPodeTransferirDocumentosVinculados, da classe WfUtil. É possível também arquivar um documento do Siga-Doc automaticamente.
Em adição à chamada ao Siga-Doc por webservice no código Java que realiza a transição de nodos, pode haver, na própria definição do nodo, no arquivo xml, uma chamada ao Siga-Doc por webservice. Chamadas desse tipo são feitas inserindo-se um elemento evento em um Task Node <script name="Arquivar"> br.gov.jfrj.siga.Service.getExService().arquivarCorrente(doc_a, null, null); </script> Nesse ponto do código, poderia ser feita também uma chamada para uma função do WfFunctionMapper.java (definido no arquivo jbpm.cfg.xml ).
Retorno à mesma tarefa
Caso a mesma tarefa torne a ser executada (em razão de o fluxo levar o token novamente à mesma tarefa num momento futuro da tramitação), outro task instance será criado, e o actorId não estará definido conforme a task instance anterior da mesma tarefa. Uma exceção a essa regra está relacionada ao uso de swimlanes. Caso a tarefa faça parte de uma swimlane, as variáveis pooled actors e actorId serão definidas na swimlane, não na task instance. Haveria a possibilidade de a definição ser feita na task instance, caso em que as variáveis da swimlane seriam desconsideradas. Mas o Siga-Wf não faz uso desse recurso.
Tarefas do processo ainda não executadas
É possível identificar as tarefas que ainda não foram executadas no Siga-Wf, por meio do código abaixo:
-
select *from SIGAWF.JBPM_TASKINSTANCEwhere actorid_ is null;
Mudança da sigla de uma lotação durante a execução de um processo
Quando o processo é instanciado, o Siga-Wf já acessa as configurações e verifica se alguma das lotações definidas como atendentes do processo deixou de existir no Corporativo. Mas quando uma lotação tem a sigla alterada no meio da execução do processo, ocorre erro ao exibir a tarja do workflow dentro de um documento. Nesse caso, além de atualizar a definição dos atendentes por meio da tela Designar Tarefas, é necessário executar queries para atualizar as tarefas dos processos já iniciados, conforme a seção abaixo.
O WfJobExecutorServlet (que estende JobExecutor, do JBPM3) é um servlet que executa automaticamente quando a aplicação é instalada no servidor. Essa classe abre threads que verificam, periodicamente, a existência de tasks cujo conteúdo inclui envio de e-mail após ter-se passado determinado período.
No arquivo jbpm.cfg.xml, fica definida a classe WfMail como responsável por essas notificações. Para cálculo do tempo decorrido, existem properties no formato do JBPM (https://github.com/projeto-siga/siga/blob/master/siga-wf/src/main/resources/jbpm.business.calendar.properties), que definem os feriados e horários de expediente.
O Siga-Wf resolve os e-mails das pessoas e lotações por meio da classe WfAddressResolver.java