@seniorsistemas/workflow-cockpit/README.md

Senior BPM Workflow Cockpit

# Workflow Cockpit

O cockpit do Workflow é capaz de apresentar dentro de um iframe formulários ECM e interfaces customizadas hospedadas em outros domínios. A comunicação entre as duas partes é realizada por [Window.postMessage()](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage) e abstraída por este componente, que deve ser incluído na página e configurado pelo desenvolvedor.

Para o correto funcionamento da interface customizada dentro do cockpit, o desenvolvedor deve definir como a página salva os dados do processo e como reage a erros ocorridos na criação do processo e tratamento da pendência.

## Passos para integração

Adicionar na página um componente que auxilia o cockpit a exibir o _iframe_ no tamanho correto:

`<script src="https://cdnjs.cloudflare.com/ajax/libs/iframe-resizer/3.5.14/iframeResizer.contentWindow.min.js"></script>`

Caso você não tiver babel-polyfill instalado como dependência de seu projeto é necessário adicionar o seguinte arquivo:

`<script src="https://cdnjs.cloudflare.com/ajax/libs/babel-polyfill/6.26.0/polyfill.js"></script>`

Referenciar também o componente Javascript do Workflow:

`<script type="text/javascript" src="https://cdn.senior.com.br/platform/1.7.1/js/workflow-cockpit.min.js"></script>`

Invocar a função `workflowCockpit` na inicialização da página. Caso seja utilizado o modo _Abrir Formulário na Plataforma G7_, poderá ser difinido o handler _'init'_, que será acionado quando a função é executada e irá prover informações como a instância do processo.:
```javascript
this.workflowCockpit = workflowCockpit({
  init: _loadData
});
```

Caso seja utilizado o modo de exibição _Abrir Formulário no Cockpit do Workflow_, é preciso definir as funções que tratarão cada evento originado pelo cockpit. Exemplo:
```javascript
this.workflowCockpit = workflowCockpit({
  init: _loadData,
  onSubmit: _saveData,
  onError: _rollback
});
```

## Funções da instância retornada

O objeto retornado pela função `workflowCockpit` é capaz de obter o identificador da instância do processo que está sendo executada, verificar se o usuário está criando ou respondendo a uma solicitação e obter informações sobre o usuário logado e sobre a plataforma.

**isRequestNew**: Indica se a tela foi aberta porque o usuário está criando uma solicitação. Se for _false_, indica que o usuário está respondendo a uma solicitação.

**getUserData**: Obtém um objeto contendo informações sobre o usuário logado no Workflow. É retornada uma promise.
```javascript
this.workflowCockpit.getUserData().then(function(data) {
  /*{
    description: ...,
    email: ...,
    fullname: ...,
    id: ...,
    locale: ...,
    subject: ...,
    tenantName: ...,
    username: ...
  }*/
});
```

**getPlatformData**: Obtém um objeto contendo dados para acessar recursos da plataforma G7. É retornada uma promise.
```javascript
this.workflowCockpit.getPlatformData().then(function(data) {
  /*{
    serviceUrl: ...,
    odataUrl: ...,
    token: {
      token_type: ...,
      access_token: ...
    }
  }*/
});
```

## Handlers de eventos

O Desenvolvedor pode configurar determinadas funções que responderão mensagens do Workflow. As funções retornadas por WorkflowCockpit estão disponíveis em um segundo parâmetro 'info':

```javascript
/*info: ({
       isRequestNew: function
       getUserData: function
       getPlatformData: function
   })*/
```

*  *init(data, info)*  
   
```javascript
 /*data: ({
       processInstanceId: int? (ocasional)
   })*/
```

Esta função é executada quando ocorre a criação do WorkflowCockpit, ou seja, não é executada por mensagem. Quando for uma nova requisição não existe um `processInstanceId` pelo simples fato do fluxo ainda não ter sido criado.
Exemplo:
```javascript
function _load(data, info) {
   info.getPlatformData().then(function(platformData) {
       this.tokenG7 = platformData.token;
       this.serviceUrl = platformData.serviceUrl;
       this.odataUrl = platformData.odataUrl;

       if (info.isRequestNew()) {
           this.fields = this.loadData(data.processInstanceId);
       }
   });
}
```

*  *onSubmit(data, info)*   

```javascript
/*data: ({
       processInstanceId: int
   })*/
```

Esta função é executada no momento que o usuário finaliza sua interação com a tela e tenta prosseguir ou iniciar um processo pelo Cockpit. Neste momento, a tela pode realizar a persistência dos dados do formulário e retornar os valores que deseja adicionar às variáveis do fluxo. Pode ser retornada uma Promise ou o próprio objeto contendo os dados.
Toda exceção lançada por essa função não permitirá a continuação do processo por parte do Workflow. Exemplo:

```javascript
function _saveData(data, info) {
  if (!isValid()) {
      throw Error('Os dados informados são inválidos.');
  }
  return persistData(data.processInstanceId, info.isRequestNew()).then(function(result) {
    return {
        formData: this.data // objeto contendo os dados dos campos
    };
  });
}
```
Importante lembrar que, como a execução dessa função não está associada a um contexto de renderização do Angular, é preciso invocar `$scope.$apply()` caso a função `isValid()` modifique alguma variável que afeta a apresentação.

*  *onError(data, info)*  

```javascript
/*data: ({
       error: obj
       processInstanceId: int
   })*/
```

Esta função é chamada quando o ocorre algum erro ao iniciar ou responder o fluxo. Após a execução do `save`, se ocorrer algum erro quando o Workflow tentar prosseguir com o processo, este é o momento onde pode ser realizado algum tipo de consistência com o erro ocorrido, por exemplo:

```javascript
function _rollback(data, info) {
  console.log(data.error);
  if (info.isRequestNew()) {
     return removeData(data.processInstanceId);
  }
  return rollbackData(data.processInstanceId);
}
```