ER_PCREQ-6062_Suporte_a_Tecnica_Pulling_de_Sincronizacao_com_Fluig_Identity

Informações Gerais

Objetivo

Fornecer uma alternativa de sincronização das alterações realizadas no Identity com o Logix quando estes estiverem integrados.

Atualmente, após ativar a integração entre Identity e Logix, as operações de provisionamento como habilitar um usuário para utilizar o Logix, inclui-lo em um grupo de usuários ou atribuir um item de menu ao mesmo são executadas exclusivamente no Identity, sendo necessário replicar estas alterações no Logix para manter a consistência dos dados.

Esta replicação se dá com o Identity "empurrando" as alterações para o Logix através de requisições HTTP usando o padrão REST (o que denominaremos como "modo push"). Como o Identity localiza-se na "nuvem", torna-se imprescindível que o Logix esteja acessível a partir da internet, o que obriga aos clientes exporem o servidor de aplicação do Logix.

Obviamente, esta exposição exige um cuidado maior com segurança de acesso (ajustes das políticas de acesso com liberação de portas especificas no firewall, por exemplo), o que nem sempre é possível ou aceitável pelos clientes. Neste cenário, a alternativa proposta é fazer com que o Logix consulte o Identity, "puxando" as alterações realizadas e efetivando-as do seu lado (modo pull).

Definição da Regra de Negócio

Atualmente a sincronização dos dados entre o Fluig Identity e o ERP é realizada através de serviços REST e ocorrem de duas formas:

1. Sincronização inicial (fluxo ERP → Identity): sincroniza os dados do ERP enviando-os para o aplicativo do Fluig Identity configurado. Esta é a primeira sincronização que deve ser realizada na integração e, geralmente, executada uma única vez apenas para a carga inicial dos dados.
   
   
2. Sincronização parcial e contínua (fluxo Identity → ERP): após a configuração da integração e sincronização inicial dos dados, a manutenção das informações básicas (usuários, grupos e permissões) serão bloqueadas no ERP, permitindo apenas a manutenção destas através do Fluig Identity. Com isto, é necessário que o ERP disponibilize serviços REST para que o Fluig Identity consiga enviar os dados mantidos no aplicativo.
   

Devido ao fato do Fluig Identity ser uma ferramenta na nuvem, os serviços REST existentes no ERP devem ser expostos para acesso externo para que a a integração seja concluída e para que seja possível a comunicação do Fluig Identity com o ERP. Todavia, a exposição destes serviços acaba causando desconforto e insegurança nos clientes, além de exigir apoio de equipes de infraestrutura, tendo em vista estes empecilhos que foi criado o método de sincronização no modelo "Pull".

1. Modelo "Pull" de sincronização

Com o modelo "Pull" ligado no aplicativo do Fluig Identity, toda e qualquer alteração efetuada é armazenada em filas com as informações da operação realizada. Estas informações são posteriormente requisitadas, lidas e executadas pelo ERP efetivando as operações no produto, mantendo assim os dados sincronizados. Atualmente existem duas filas para armazenamento das operações (diagrama #1):

1. Fila de operações do aplicativo:
   Possuem informações das operações realizadas no aplicativo como: manutenção das informações dos recursos¹ e suas permissões.²
   
   
2. Fila de operações dos usuários do aplicativo:
   Possuem informações das operações realizadas em um determinado usuário como: manutenção das informações do usuário, suas permissões e associações com recursos.

¹ O Fluig Identity considera como recurso informações do ERP como empresas, grupos de usuários, itens de menu e consultas rápidas.

² A manutenção de recursos, bem como a manutenção das suas permissões, está atualmente disponível apenas para recursos do tipo Role (grupos de usuários).

Para recuperar as informações destas filas, o Fluig Identity disponibiliza os serviços REST abaixo:

• Pending App Operations
  GET /rest/v2/companies/{companyId}/users/{userId}/applications/{appId}/pending-app-operations

• Clear App Operations
  POST /rest/v2/companies/{companyId}/apps/{appId}/clear-app-operations

• Pending App Users
  GET /rest/v2/companies/{companyId}/users/{userId}/applications/{appId}/pending-app-users

• Pending User Operations
  GET /rest/v2/companies/{companyId}/users/{userId}/applications/{appId}/pending-user-operations

• Clear User Operations
  POST /rest/v2/companies/{companyId}/users/{userId}/applications/{appId}/clear-user-app-operations

1.2. Pending App Operations

Este serviço retorna as informações das operações realizadas no aplicativo como a manutenção de recursos e suas permissões. As informações de retorno virão no formato JSON com a estrutura abaixo:

[
    {
        "operationName": "DELETE_RESOURCE",
        "operationId": "7eac46ac-bef5-4634-8e01-2bcfed1295d8",
        "dataType": "RESOURCES_LIST",
        "data": [...],
        "companyId": "oaq3ssk03fl6sxvi1410390042739"
    }
]

Na estrutura acima existem três importantes atributos: operationName, operationId e data. O atributo operationName define o nome da operação realizada, sendo:

• CREATE_RESOURCE
  Indica que trata-se de uma criação de recurso.
• UPDATE_RESOURCE
  Indica que trata-se de uma alteração de recurso.
• DELETE_RESOURCE
  Indica que trata-se de uma exclusão de recurso.
• LINK_RESOURCES
  Indica que trata-se de um link entre um recurso e outro (atribuição de permissão).
• UNLINK_RESOURCES
  Indica que trata-se de um unlink de um recurso com outro (remoção de permissão).

O atributo operationId é o código da operação que será utilizado em conjunto com o serviço Clear App Operations e no atributo data virá as informações do recurso alterado.

1.3. Clear App Operations

Exclui da fila de operações do aplicativo, a operação pendente conforme o código informado.

1.4. Pending App Users

Este serviço retorna uma lista com os códigos de usuários que sofreram alterações. As informações de retorno virão no formato JSON com a estrutura abaixo:

[
    "tvusbzfo6k3dlzkn1410390388116",
    "tqjsi3pr44yfiop91410393173742"
]

Os códigos retornados serão utilizados em conjunto com o serviço Pending User Operations.

1.5. Pending User Operations

Este serviço retorna as informações das operações realizadas para um determinado usuário (conforme o código informado), estas operações contemplam: provisionamento no aplicativo, bloqueio, manutenção de suas permissões e associação com outros recursos. As operações e as informações de retorno virão no formato JSON com a estrutura abaixo:

[
    {
        "operationName": "PROVISIONING",
        "operationId": "7eac46ac-bef5-4634-8e01-2bcfed1295d8",
        "dataType": "RESOURCES_LIST",
        "data": [...],
        "companyId": "oaq3ssk03fl6sxvi1410390042739"
    }
]

Na estrutura acima existem três importantes atributos: operationName, operationId e data. O atributo operationName define o nome da operação realizada, sendo:

• PROVISIONING
  Indica que o usuário foi provisionado no aplicativo (criação do usuário no ERP).
• DEPROVISIONING
  Indica que o usuário foi removido do aplicativo (bloqueio do usuário no ERP).
• ADD_ENTITLEMENTS
  Indica que trata-se de uma atribuição de permissão.
• REMOVE_ENTITLEMENTS
  Indica que trata-se de uma remoção de permissão.

O atributo operationId é o código da operação que será utilizado em conjunto com o serviço Clear User Operations e no atributo data virá as informações do recurso alterado.

1.6. Clear User Operations

Exclui da fila de operações de usuários, a operação pendente conforme o código do usuário e operação informados.

2. Suporte ao modelo "Pull" no Logix

A sincronização através do modelo "Pull" no Logix deve ocorrer de duas formas:

1. A partir do SSO via Fluig Identity
   Ao acessar o aplicativo do ERP, além das informações do SSO, virão dois novos parâmetros booleanos na autenticação do usuário: o lEntitlementsChanged e o lAppsChanged. O primeiro parâmetro indica se há alterações para um ou mais usuários e o segundo parâmetro indica se há alterações no aplicativo. Dependendo dos valores destes parâmetros, será realizada a sincronização das alterações do aplicativo e do usuário informado de forma síncrona, ou seja, o usuário terá que esperar finalizar a atualização para poder utilizar o produto.
2. Através de um serviço JOB
   O serviço será criado para recuperar as informações pendentes de usuários e aplicativos a cada 30s, mantendo o ERP sempre sincronizado com o Fluig Identity.

Para efetuar a sincronização nos pontos acima, será desenvolvida uma função ou classe que execute os serviços REST do Fluig Identity (documentado no item 1 deste documento) para recuperar as operações pendentes e atualizá-las no ERP. Alguns pontos importantes devem ser considerados na criação desta função:

• Será executada a sincronização apenas se a integração com o Fluig Identity estiver habilitada (utilizando a função IDENTITY_isEnabled).
• A função deverá ter 3 parâmetros opcionais: o primeiro para indicar se atualiza ou não as operações do aplicativo, o segundo para indicar se atualiza ou não as operações dos usuários e o terceiro o código do Fluig Identity do usuário.
• Se o terceiro parâmetro (código do Fluig Identity do usuário) for informado, será sincronizado apenas as operações pendentes do usuário informado.

Esta função será a mesma executada no SSO via Fluig Identity e via serviço JOB e terá a estrutura semelhante do exemplo abaixo:

Alguns itens importantes devem ser considerados no desenvolvimento:

• A lógica de leitura do JSON do Fluig Identity para sincronização dos dados no ERP já estão desenvolvidas nos serviços REST do Logix (LSCIMUsers, LSCIMResources e LSCIMEntitlements).
• Para facilitar o processo de atualização, poderá ser utilizado como base a classe FWSCIM do produto Protheus.
• Os serviços REST do Logix devem continuar existindo para o modelo "Push"
• Separar a lógica de sincronização existente do Logix em métodos, permitindo que o mesmo método seja executado tanto no modelo "Pull" quanto no modelo "Push".

Durante a sincronização dos dados, caso a chave FWTRACELOG do ambiente em uso esteja ligada no arquivo de configuração do servidor TOTVSAPPSERVER.INI, mensagens serão exibidas no arquivo de LOG do servidor com as chaves PULLAPP ou PULLENTITLEMENT. Será enviado também um e-mail para o usuário administrador cadastrado no aplicativo, conforme o exemplo abaixo:

2.1. JOB de sincronização

O JOB de sincronização deve ser criado de forma automática e ativado apenas se o modelo "Pull" está ligado no aplicativo. Para isso, deve-se alterar o Configurador do Fluig Identity do Logix (LConfiguratorIdentity) para alterar o arquivo de configuração do servidor de aplicação (TOTVSAPPSERVER.INI) e incluir o JOB conforme exemplo abaixo:

[ONSTART]
JOBS=HTTPJOB,SCIMSCHEDLGX
REFRESHRATE=30

[HTTPJOB] -- JOB padrão do serviço REST do TOTVS Tec
MAIN=HTTP_START
ENVIRONMENT=[ambiente]

[SCIMSCHEDLGX] -- JOB de sincronização dos dados
MAIN=SCIMSchedule
ENVIRONMENT=[ambiente]

É válido lembrar que, mesmo com o modelo "Pull" ligado no aplicativo, ainda é necessário ter o serviço REST do Logix ativo, para as requisições de consultas rápidas do Fluig.

Fluxo do Processo

Diagrama #1 - Caso de Uso das operações pendentes

Veja também

• ER_PCREQ-6063_Suporte_Tecnica_Pulling_Para_Sincronismo_Com_Identity.