(Obrigatório)

Informações Gerais

   Legenda: 1 – Inovação 2 – Manutenção (Os demais campos devem ser preenchidos para ambos os processos). 

(Obrigatório)

Objetivo

Realizar a integração do aplicativo PIMS Multicultivos com o TOTVS|License Server. O TOTVS|License Server é um recurso computacional da TOTVS que têm como objetivo realizar o controle das licenças de uso dos softwares e aplicações TOTVS. Através deste recurso é possível prover de forma eficiente e segura as licenças e liberações de utilização de módulos e/ou funcionalidades das aplicações TOTVS em conformidade com o contrato firmado entre o cliente e a TOTVS. Cada instancia do TOTVS|License Server identifica uma instalação física vinculada ao contrato de licenciamento do cliente. Para maximizar o uso do licenciamento TOTVS, recomenda-se a utilização de uma única instancia do TOTVS|License Server, independentemente do ambiente de operação (Produção, Homologação e Teste).  Caso opte-se por mais de uma instalação física do TOTVS|License Server, será necessário o registro da divisão das licenças do contrato entre as instalações físicas.

(Obrigatório)

Definição da Regra de Negócio

Esta especificação trata do desenvolvimento da integração do PIMS Multicultivo ao TOTVS | License Server, que deverá ser realizada em duas etapas, sendo que este documento contempla a especificação da primeira fase.

A necessidade de realizarmos este desenvolvimento em duas etapas é que, num primeiro momento, ainda não dispomos de todas as definições de regras que serão aplicadas ao licenciamento do PIMS Multicultivo. Desta forma, a integração na primeira etapa contemplará um controle mais simplificado de licenças, realizado apenas no momento do login. A segunda etapa atenderá a cenários mais complexos de licenciamento, como o licenciamento por módulos.

Antes de detalharmos os aspectos técnicos de implementação, específicos do PIMS Multicultivo, vale a pena apresentar alguns conceitos e definições importantes sobre o licenciamento TOTVS. As seções a seguir apresentarão estas definições.

Tipos de Licença

 O TOTVS|License Server controla diversos tipos de licenciamento TOTVS, entre estes tipos:

• Licença TOTVS Full
• Licença TOTVS Light
• Licença TOTVS Light OnDemand
• Licença TOTVS I
• Licença TOTVS T
• Licença TOTVS V
• Licença Core
• Licença Processor
• Corporativo

Os tipos de licença são divididos em conformidade com sua natureza de controle, entre elas:

• Licenças Concorrentes
• Licenças de capacidade de demanda/OnDemand
• Licenças de capacidade de processamento
• Licenças de Habilitação

As licenças de natureza Concorrentes são aquelas cujo controle do TOTVS|License Server é realizado através da contagem dos usuários simultâneos do sistema em um determinado Agrupador de Negócio TOTVS. Para cada Agrupador de Negócio adicional que um usuário determinado utilizar, será considerado um novo consumo de licença. Não será considerado como um novo consumo de licença se o usuário utilizar, simultaneamente, mais de uma funcionalidade de um mesmo Agrupador de Negócio.

As licenças de natureza OnDemand são aquelas cujo controle é realizado pela contagem do volume de itens ativos de uma determinada métrica, por exemplo: volume de funcionários ativos. Esta natureza de licença não realiza a contagem do número de usuários simultâneos nos sistemas, mas faz o bloqueio da métrica definida, impedindo a operação do sistema quando a mesma é atingida e permite um número infinito de usuários.

As licenças baseadas na capacidade de processamento (CPUs) são aquelas cujo controle é realizado no startup do sistema, onde as licenças são consumidas conforme o volume de processadores ou núcleos do hardware hospedeiro da linha de produto. Caso o hardware seja virtualizado, a contagem é feita na Virtual Machine. A utilização desta natureza de licenciamento só é permitida para as linhas de produto que possuem a estrutura de um servidor de aplicação.

As licenças de natureza Habilitação são aquelas que habilitam determinada funcionalidade no software e geralmente estão atreladas as rotinas de menu que possuem integração com software de terceiros.

Com exceção da licença de natureza Habilitação, todas as demais naturezas são exclusivas, um mesmo componente da linha de software não pode utilizar duas naturezas concomitantemente.

Os Agrupadores de Negócio TOTVS, agrupam um conjunto de funcionalidades de regras de negócio independentemente da linha de software. Por exemplo, tomemos como base o Agrupador de Negócio Comércio Exterior. Segundo nosso Guia de Software, este agrupador reúne as funcionalidades de negócio:

• Cambio
• Importação
• Exportação
• Drawback

Assim os itens de menu de todas as linhas de software que possuem estas funcionalidades são agrupados no Agrupador de Negócio Comercio Exterior. Resumidamente podemos afirmar que o Agrupador de Negócio é o contexto da de solução sistêmica, definida pela TOTVS, para um processo (módulo/agrupador) licenciado.

TOTVS Full 

A licença TOTVS Full permite o acesso de um usuário a uma lista de Agrupadores de Negócio TOTVS. A natureza de controle desta licença é concorrente e sua contagem leva em consideração o usuário concorrente e o agrupador de negócio utilizado.

A principal diferença desta licença para a TOTVS Light está no Agrupador de Negócio. Enquanto a licença light disponibiliza um Agrupador de Negócio, esta licença disponibiliza uma lista de agrupadores, podendo assim ser utilizada como uma licença coringa.

Quando o TOTVS|License Server detecta que não há licenças TOTVS Light disponível, automaticamente ele faz a escala para uma licença TOTVS Full. Mais adiante falaremos sobre as regras de escala.

TOTVS Light

A licença TOTVS Light permite o acesso de um usuário ao Agrupador de Negócio definido na aquisição do Light TOTVS, desta forma existe uma licença Light para cada Agrupador de Negócio. A natureza de controle desta licença é concorrente e um mesmo usuário pode acessar, simultaneamente, mais de uma funcionalidade do mesmo Agrupador de Negócio.

TOTVS Light OnDemand

A licença TOTVS Light OnDemand permite o acesso de um usuário ao agrupador de negócio definido na aquisição do TOTVS Light OnDemand, sem que haja restrição do número de usuários. A natureza de controle desta licença é OnDemand.

TOTVS I – Internet

A licença TOTVS I é um tipo de licença utilizado para licenciar o Pool de conexões de Web Services, que atendem customizações e/ou funcionalidades do produto como Portais. A natureza de controle desta licença é concorrente.

Pool de Conexões, ou connection pooling, é uma técnica utilizada para otimizar o uso dos recursos associados a um Servidor de Aplicação. Nesta técnica, o servidor de aplicações gerencia uma coleção de conexões para servir os diversos usuários de um sistema.  O uso do pool de conexões tem dois objetivos principais. O primeiro é escalabilidade, uma vez que permite o compartilhamento de um número menor de conexões físicas para atender às requisições de conexões de uma aplicação. Esse compartilhamento é possível com o uso do tempo ocioso de uma conexão para atender outras requisições da aplicação.  Desta forma, temos um relacionamento 1:N, onde uma conexão física pode atender N conexões lógicas de usuários. O segundo objetivo é performance, já que minimiza o elevado custo para se estabelecer conexões.  Esse elevado custo é referente à necessidade de alocação memória, criação de um processo servidor e uma série de recursos necessários para o estabelecimento de uma conexão.  O pool de conexões minimiza esse custo ao manter, sempre, conexões pré-estabelecidas, sem que seja necessário abrir e fechar, repetidamente, as conexões físicas.

Note que o TOTVS I é um Agrupador de Negócio e mesmo que o Servidor de aplicação utilize a técnica do Pool de conexões é necessário verificar se a licença consumida é a TOTVS I ou uma TOTVS Light.

TOTVS T – Terminal

A licença TOTVS T é um tipo de licença utilizado para licenciar terminais coletores de dados e/ou dispositivos móveis. A natureza de controle desta licença é OnDemand, cuja métrica é o número de dispositivos.

TOTVS V – Viewer

A licença TOTVS Viewer permite o acesso de um usuário ao Agrupador de Negócio definido na aquisição. A natureza de controle desta licença é concorrente e um mesmo usuário pode acessar, simultaneamente, mais de uma funcionalidade do mesmo agrupador de negócio.

A diferença deste tipo de licença para uma Light está no fato que as funcionalidades deste agrupador não permite a manutenção de dados, ficando restrito o acesso da leitura dos dados.

TOTVS Core

A licença TOTVS Core permite o acesso ilimitado de usuários à um Agrupador de Negócio definido na aquisição. A natureza de controle desta licença é Capacidade de Processamento e seu controle baseia-se na contagem do número total dos núcleos dos processadores disponíveis no hardware instalado.

Equipamentos mais modernos, possuem 3 unidades de contagem de processadores:

• Processadores/Processor
• Núcleos/Core
• Threads

O dimensionamento da quantidade de licenças deve ser feito pela seguinte formula: Quantidade de processadores * Quantidade de núcleos por processador. Note que o número de Threads não é considerado na equação, apesar de poder ser visualizado no Medidor de CPU do Sistema Operacional utilizado. Em caso de dúvida, verifique a documentação do processador utilizado no equipamento.

Em caso de virtualização de hardware, será considerado a equação para Virtual Machine disponibilizada e não o hardware real.

TOTVS Processor

A licença TOTVS Processor permite o acesso ilimitado de usuários à um agrupador de negócio definido na aquisição. A natureza de controle desta licença é Capacidade de processamento e seu controle baseia-se na contagem do número total de processadores disponíveis no hardware instalado.

Componentes Acessórios

Este tipo de licença permite o acesso a uma funcionalidade acessória do produto. A natureza de controle desta licença é por Habilitação. A disponibilização desta funcionalidade não exclui o consumo do Agrupador de Negócio (TOTVS Light). Assim, cada componente acessório deve estar vinculado a um agrupador de negócio TOTVS, para o correto consumo do licenciamento.

Corporativo

A modalidade de licenciamento Corporativo permite acesso ilimitado a um conjunto de Agrupadores de Negócio definidos nas licenças TOTVS Full, TOTVS I, TOTVS T e TOTVS V; aceleradores de implantação e nas séries de produto 1,3 e T.

Estão excluídos do licenciamento Corporativo os componentes acessórios; software de parceiros e licenças de tecnologia. Apesar de alguns softwares de parceiros possuírem a mesma métrica do licenciamento corporativo TOTVS, sua precificação e controle é separado do Corporativo TOTVS, sendo chamado de Corporativo de Parceiro.

Para efeito de controle, o licenciamento Corporativo fornece 9000 acessos simultâneos em cada uma das licenças TOTVS Full, TOTVS I, TOTVS T e TOTVS V; além de realizar o controle adicional de CNPJ/Federal Id. Assim, o acesso ilimitado está condicionado a identificação das empresas que estão cadastradas na linha de produto, com o contrato.

Quando o licenciamento não é corporativo, dizemos que ele é tradicional e foi justamente desta modalidade de licenciamento que abordamos nos tópicos anteriores.

A figura abaixo demonstra a relação entre a modalidade Corporativo e Tradicional, bem como o escopo do licenciamento corporativo.

Padrão de identificação do produto

Visão Geral

Em 2009 a TOTVS decidiu padronizar suas linhas de Software e unificar a nomenclatura como elas são chamadas, documentadas e expedidas. Assim, deixa-se de existir a identificação anterior do software e passa a existir a identificação TOTVS. O software deve adotar o Guia de Estilos TOTVS em seu layout e a nova nomenclatura de identificação.

Os softwares de propriedade da TOTVS são identificados pelo Segmento TOTVS, Série de produto, Linha de produto e módulo/Slot.

A identificação do produto torna-se relevante no processo de comercialização, atendimento e suporte, uma vez que visualmente os softwares das TOTVS são cada vez mais parecidos e na visão do cliente ele adquire um produto TOTVS para o seu segmento de negócio. Exemplo: TOTVS Varejo.

Este ponto é extremamente relevante, pois toda comunicação de software (inclusive contrato) feita para um cliente, leva em consideração o seu segmento, independentemente da linha de produto que ele realmente utiliza. 

Segmento TOTVS 

A TOTVS distribui os seus clientes em Segmentos, conforme o seu código de atividade econômica (CNAE), bem como os seus softwares verticais. Assim, quando um cliente TOTVS adquire um software, ele adquire uma oferta vocacionada ao seu segmento de negócio.

A figura abaixo mostra os segmentos TOTVS e seu relacionamento com à série de produto.

Série de Produto

O conceito de série de produto foi criado para diferenciar o porte dos clientes que são atendidos pelo software TOTVS.

A TOTVS definiu 4 séries de produtos a saber:

• Série 1 – São os softwares popularmente conhecidos como softwares de prateleira e destina-se a microempresas, empresas individuais ou profissionais liberais.
• Série 3 – São os softwares possuem uma abrangência funcional restrita e baixa complexidade de processos de negócios. Assim, conseguem atender micro e pequenas ou outros portes de empresas de mesmo escopo funcional.
• Série T – São softwares que possuem uma abrangência funcional ampla, média e alta complexidade de processos de negócios. Assim, atendem uma ampla gama de empresas.
• Série C – São os softwares de consumerização e/ou embarcados em dispositivos, tais como os softwares destinados a TV Digital.

Linha de Produto

A nomenclatura antiga dos softwares TOTVS deve ser evitada, porém, em algumas situações ela é necessária, seja para o aculturamento dos clientes da base, seja para simplificar nossa documentação dos componentes de software que estão disponíveis para mais de um segmento de negócio.

Assim, a nomenclatura antiga dos softwares TOTVS passam a ser nomeadas como linhas de produtos e temporariamente fazem parte da nomenclatura do produto.

Para cada linha de produto TOTVS, será criado uma identificação numérica de dois dígitos.

Slot do Módulo

O Slot do módulo é um ID de 4 dígitos numéricos e sua função é identificar um conjunto de componentes de software que atendem uma ou mais funcionalidades de negócio.

O Slot do módulo é único e controlado pelo time de evangelizadores TOTVS. Toda vez que um novo Slot de módulo é criado, ele deve ser vinculado a um ou mais Agrupadores de Negócio.

Para ser distribuído e comercializado um software TOTVS, faz-se necessário o vínculo do Slot do módulo ao Agrupador de Negócio e este ao PartNumber (código de comercialização ou do contrato). As seguintes possibilidades são admitidas no relacionamento destas três entidades:

• Um PartNumber admite apenas um Agrupador de Negócio;
• Um Agrupador de Negócio admite mais de um PartNumber;
• Um Slot do módulo pode admitir mais de um Agrupador de Negócio, entretanto recomenta-se apenas 1.

O registro das informações acima deve ser feito no sistema de controle de licenciamento TOTVS. Caso o Slot do módulo seja distribuído sem a atividade acima, o mesmo não poderá ser utilizado pelo cliente.

Nomenclatura de Identificação

A TOTVS adota como padrão de nomenclatura de produto o seguinte layout:

                TOTVS + Segmento + (Linha de produto) + Id LP.Série.Slot

Onde:

                Segmento: É a descrição do segmento do cliente

                Linha de Produto: É a descrição temporária da linha de produto (marca)

                Id LP: É a identificação numérica da linha de produto

                Série: É o código numérico da série de produto TOTVS.

                Slot: É o Slot do Módulo de identificação da linha de produto

Exemplo:

• TOTVS Manufatura (Logix) 01.9.5023
• TOTVS Educacional (RM) 03.9.0520
• TOTVS Serviços (Protheus) 02.9.0005
• TOTVS Manufatura (Datasul) 06.9.5631

O código gerado pela concatenação das informações Id LP, Série e Slot, será conhecido como código de acesso do produto. Exemplo:

• 01.9.5023
• 03.9.0520
• 02.9.0005
• 06.9.5631

A identificação do produto deve estar visível a todo instante no produto, devendo estar preferencialmente visível na barra de título janela do produto.

Caso não seja possível identificar todas informações na abertura do software (Slot do Módulo), deve-se incluí-la/atualizá-la nas janelas seguintes, assim que possível. O contato com esta identificação irá ajudar os clientes a se localizarem mais rapidamente dentro na URA da TOTVS.

Auxilio ao Suporte Técnico

Todos os produtos TOTVS integrados ao TOTVS|License Server deverá fornecer suporte a tecla rápida (HotKey) [SHIFT+F6]. Esta tecla de atalho deverá fornecer informações as seguintes informações:

• Texto padronizado e internacionalizado de como obter suporte técnico ao componente de software contextualizado (Linha de produto e/ou Slot do Módulo). Neste texto deverá ser preenchida a área destinada ao código gerado pela concatenação das informações Id LP, Série e Slot (atalho de atendimento).
• Dados técnicos para suporte, tais como: Sistema operacional, Processador, Memória Instalada, da estação de trabalho e do Servidor de aplicação, entre outros dados específicos da linha, como versão, release, pacote instalados ou identificação do código-fonte no sistema de controle de versionamento utilizado.
• Extrato de versão. Entende-se por extrato de versão um arquivo com todos os dados técnicos de auxílio ao suporte para identificação de não-conformidades no sistema. Trata-se de um arquivo texto que é vinculado ao chamado de atendimento.

O Auxílio ao Suporte Técnico deverá estar disponível em qualquer local do produto, mesmo que a autenticação do usuário não tiver ocorrido.

APIs de Integração

A integração da linha de Software TOTVS com o License Server ocorre através de um Socket API. Entende-se por Socket API uma interface de programação de aplicações (API) que permite que os programas de aplicação utilizem interfaces de rede para troca de pacote de dados de informação, utilizando a combinação de um endereço de IP e o número da porta de rede.

Para acelerar o desenvolvimento da integração, a TOTVS fornece uma biblioteca de vínculo dinâmico - DLL (license_client.dll) desenvolvida em C/C++ (padrão CDECL) que realiza todo o controle de Socket API, deixando a cargo do desenvolvedor apenas o código de acoplamento e conversão de tipos entre a DLL e a linguagem nativa utilizada pelo Software.

Como o PIMS Multicultivo pode ser instalado também em ambientes Linux, a estratégia de utilização de DLLs não atenderá a todos os cenários. Desta forma a integração com o License Server terá de ser desenvolvida diretamente com as APIs de socket da plataforma Java.

Embora a estratégia de integração do PIMS Multicultivo não leve em consideração a utilização desta dll, vale a pena documentar suas rotinas, que são apresentadas a seguir de maneira básica:

Documentação dos métodos da DLL - license_client.dll

SLC_init

Método de inicialização da comunicação com o TOTVS|License Server. Este método deve ser executado para cada uma das threads de processamento da linha de software.

Parâmetros de entrada:

• ServerIp: Endereço IP do TOTVS|License Server
• ServerPort: Porta de comunicação do TOTVS|License Server
• ClientIP: Endereço IP da estação de trabalho da linha de produto TOTVS ou similar. Este parâmetro é utilizado para identificar o uso concorrente do licenciamento.

Retorno:

• Retorna um valor inteiro positivo com o Handle da conexão com o TOTVS|License Server. Este retorno será utilizado como parâmetros nos outros métodos da DLL. Caso o retorno seja negativo, um erro ocorreu durante a comunicação. 

SLC_setThreadID

Método utilizado para identificar a thread ou contexto onde será realizado o consumo de licença, esta informação é utilizada na regra de abono de licença.

SLC_setClientPort

Método utilizado para identificar a porta da aplicação a qual fará conexão com o servidor de licenças, esta informação é utilizada na regra de abono de licença.

SLC_CLEANUP

Método de encerramento da comunicação com o TOTVS|License Server. Este método deve ser executado para cada uma das threads de processamento da linha de software. Recomendamos a chamada deste método em um destrutor de Classe para evitar que a conexão fique presa se houver uma queda da aplicação por não-conformidade.

Parâmetros de entrada:

• SLC_HANDLE: Handle da conexão com o TOTVS|License Server gerado pela função SLC_INIT.

Retorno:

• Não há retorno.

SLC_GETID

Método de recuperação do número serial do TOTVS|License Server do ThreadId da conexão com o TOTVS|License Server. Quando não há um hardlock presente na instalação este método retorna a versão do TOTVS|License Server. Este método deve ser utilizado para verificar se trata da versão 2014 do TOTVS|License Server, neste caso o retorno será 2014.

Parâmetros de entrada:

• SLC_HANDLE: Handle da conexão com o TOTVS|License Server gerado pela função SLC_INIT.

Retorno:

• Retorna o número serial do hardlock ou a versão do TOTVS|License Server quando não há hardlock instalado, as versões possíveis são: 2002,2010,2011,2014.

SLC_CALLINTERNAL

Método de parametrização do ThreadId da conexão com o TOTVS|License Server. O ThreadId é utilizado na identificação das conexões com o TOTVS|License Server e é obrigatório ser informado.

Parâmetros de entrada:

• SLC_HANDLE: Handle da conexão com o TOTVS|License Server gerado pela função SLC_INIT.
• code: Código de identificação do tipo de mensagem que será enviada
• par1: mensagem que será transmitid

Retorno:

• Retorna uma string com a mensagem de retorno no formato Json, conforme documentação.

APIs que deverão ser implementadas

As seguintes rotinas terão de ser implementadas pelo Multicultivo, realizando a conexão direta com os sockets do license Server. A sintaxe abaixo foi tirada da documentação do License Server e não está em sintaxe Java, mas serve de ponto de partida.

LSIsOnLine

Implementar uma API para analisar se o TOTVS|License Server está configurado e aguardando uma mensagem.

Procedimentos:

1. Realizar a conexão com o TOTVS|License Server (SLC_INIT) conforme parâmetros de conexão configurados. Caso os parâmetros não estejam preenchidos, retorne ‘-1’.
2. Caso o TOTVS|License Server retorne um erro, somar -1000 ao erro e retornar o valor.
3. Armazenar o Handle da conexão em uma variável de escopo Privado para reutilização futura, caso não tenha sido feito anteriormente e retornar 1.

Parâmetros:

• Não há

Retorno:

• Retorna 1 em caso de sucesso ou um valor negativo em caso de erro.

LsIs2014

Implementar uma API para analisar se a versão do TOTVS|License Server configurada é igual ou superior a 2014.

Procedimentos:

1. Verificar se o retorno da API LSIsOnLine é positivo, caso contrário retornar 0 (zero).
2. Utilizar o método LS_GETID e verificar se o retorno é maior ou igual 2014 e menor que 9999. Em caso positivo retornar 1.
3. Qualquer outra condição, retornar 0 (zero).

Parâmetros:

• Não há

Retorno:

• Retorna 1 em caso de sucesso ou 0 (zero) em caso de insucesso.

LSgetLicense

Implementar uma API para o consumo do licenciamento TOTVS. O consumo de licenciamento TOTVS está preparado para realizar a identificação do tipo de licença solicitada e a natureza do controle, bem como identificar se a solicitação de licenciamento se refere ao licenciamento tradicional ou corporativo. A única preocupação do desenvolvedor é transmitir corretamente os dados solicitados na mensagem e realizar o tratamento correto do retorno da mensagem.

Procedimentos:

1. Verificar se o retorno da API LSIsOnLine é positivo, caso contrário retornar vazio.
2. Verificar se a versão do TOTVS|License Server é igual ou superior a 2014, caso contrário retornar uma exceção.
3. Montar o pacote JSon
4. Concatenar ao pacote Json a seguinte expressão: Json = “TOTVSLICENSESERVER_GETLICENSE|”+Json
5. Invocar o método SLC_callinternal passando no parâmetro code o valor 10003 e o novo valor do Json no parâmetro par1.
6. Em caso de sucesso será retornado um Json com os procedimentos que devem ser desenvolvidos.

Parâmetros:

• String Json montada conforme documentação.

Retorno:

• String Json conforme documentação.

Quanto a estrutura das mensagens Json, utilizadas no envio e retorno da API:

1) O Json de solicitação de licenciamento TOTVS deve ter a estrutura mencionada abaixo:

Exemplo:

{"method":"getLicense", 

"version":"1.0",

"federalId":"53113791000122",

"userId":"ivanpc",

"moduleId":"0005",

"routine":"mata030",

"ownerThread":1768,

"ownerClientIP":"172.0.10.1",

"ownerClientPort":9000,

"ownerServerIP": "172.0.0.1",

"fullDeterminado":false}

2) O Json retornado pela API possui uma das seguintes estruturas possíveis.

1. 1. Estrutura de retorno em caso de aviso de necessidade de renovação manual do LS. Esta mensagem será retornada quando ocorrer algum problema na atualização do TOTVS|License Server que necessite uma intervenção manual do Administrador do sistema. Recomendamos que seja utilizado a mensagem padrão fornecida pelo TOTVS|License Server. Esta mensagem deverá ser transmitida para todos os usuários do sistema (opção default ) ou somente aos usuários administradores ( opção configurada ), a cada solicitação de licenciamento. A mensagem contém o prazo de expiração da autorização de uso.
      
   2. Estrutura de retorno em caso de necessidade de atualização (sincronização) dos dados do usuário. Esta mensagem é gerada mensalmente para sincronização com os dados do usuário que aparece no monitor de licenciamento. Mais abaixo descrevemos uma API que deverá ser invocada para atualização destes dados.
      
   3. Estrutura de retorno em caso de necessidade de atualização (sincronização) dos dados da empresa. Esta mensagem é gerada mensalmente para sincronização com dos dados da empresa que aparece no monitor de licenciamento. Mais abaixo descrevemos uma API que deverá ser invocada para atualização dos dados.
      
   4. Estrutura de retorno em caso de necessidade de atualização dos dados de suporte técnico. Esta mensagem é gerada mensalmente para sincronização com dos dados que aparece no monitor de licenciamento. Mais abaixo descrevemos uma API que deverá ser invocada para atualização dos dados.
      
   5. Estrutura de retorno em caso de sucesso ou erro na operação. Note que no Objeto pendent, os dados acima são retornados.
      
      

LSgetInfo

Implementar uma API para verificar algumas informações do servidor, tais como Série e Segmento. Estas informações poder ser utilizadas para a montagem da nomenclatura de identificação da linha de produto.

Procedimentos:

1. Verificar se o retorno da API LSIsOnLine é positivo, caso contrário retornar vazio.
2. Verificar se a versão do TOTVS|License Server é igual ou superior a 2014, caso contrário retornar uma exceção.
3. Montar o pacote JSon conforme o parâmetro informado
4. Concatenar ao pacote Json a seguinte expressão: Json = “TOTVSLICENSESERVER_GETINFO|”+Json
5. Invocar o método SLC_callinternal passando no parâmetro code o valor 10003 e o novo valor do Json no parâmetro par1.
6. Analisar o Json retornada para identificar o correto retorno da API.

Parâmetros:

• String com o tipo de informação que se deseja recuperar do TOTVS|License Server

Retorno:

• String com a informação solicitada.

Json de envio da API:

Json de retorno da API:

LSgetOnDemand

Implementar uma API para verificar a necessidade de bloqueio no licenciamento de natureza OnDemand. Esta API irá retornar o limite contrato do licenciamento, cabendo ao desenvolvedor implementar as travas necessárias para que o cliente não utilize o produto por um tempo superior a dois meses após a utilização o atingimento da capacidade.

Procedimentos:

1. Verificar se o retorno da API LSIsOnLine é positivo, caso contrário retornar vazio.
2. Verificar se a versão do TOTVS|License Server é igual ou superior a 2014, caso contrário retornar uma exceção.
3. Montar o pacote JSon
4. Concatenar ao pacote Json a seguinte expressão: Json = “TOTVSLICENSESERVER_GETONDEMAND|”+Json
5. Invocar o metodo SLC_callinternal passando no parâmetro code o valor 10003 e o novo valor do Json no parâmetro par1.
6. Analisar o Json retornada para identificar o correto retorno da API.

Parâmetros:

• Id do Slot do licenciamento OnDemand TOTVS.

Retorno:

• Um valor inteiro positivo com o limite do licenciamento OnDemand ou 0 (zero) caso o licenciamento não seja OnDemand.

Json de envio da API:

Json de retorno da API:

LSCanUseCA

Implementar uma API para verificar se determinado componente acessório do produto pode ser habilitado na linha de produto – Licenciamento de natureza Habilitação.

Procedimentos:

1. Verificar se o retorno da API LSIsOnLine é positivo, caso contrário retornar vazio.
2. Verificar se a versão do TOTVS|License Server é igual ou superior a 2014, caso contrário retornar uma exceção.
3. Montar o pacote JSon
4. Concatenar ao pacote Json a seguinte expressão: Json = “TOTVSLICENSESERVER_DEFAULT|”+Json
5. Invocar o metodo SLC_callinternal passando no parâmetro code o valor 10003 e o novo valor do Json no parâmetro par1.
6. Analisar o Json retornada para identificar o correto retorno da API.

Parâmetros:

• Id do Slot do componente acessório TOTVS.

Retorno:

• Informe 1 (um) em caso de sucesso e 0 (zero) em caso de falha.

Json de envio da API:

Json de retorno da API:

LSsetInfo

Implementar uma API para enviar informações adicionais do servidor.

Procedimentos:

1. Verificar se o retorno da API LSIsOnLine é positivo, caso contrário retornar vazio.
2. Verificar se a versão do TOTVS|License Server é igual ou superior a 2014, caso contrário retornar uma exceção.
3. Montar o pacote JSon conforme o parâmetro informado
4. Concatenar ao pacote Json a seguinte expressão: Json = “TOTVSLICENSESERVER_DEFAULT|”+Json
5. Invocar o metodo SLC_callinternal passando no parâmetro code o valor 10003 e o novo valor do Json no parâmetro par1.

Parâmetros:

• String com o tipo de informação que deseja-se recuperar do TOTVS|License Server

Retorno:

• String com a informação solicitada.

Json de envio da API:

a) O Json abaixo deve ser enviado quando houver uma solicitação de complemento de informação LS001.

b) O Json abaixo deve ser enviado quando houver uma solicitação de complemento de informação LS002.

c) O Json abaixo deve ser enviado quando houver uma solicitação de complemento de informação LS003.

Json de retorno da API:

• Sempre retorna vazio.

LSgetValidate

Implementar uma API para certificar-se que a requisição que chega ao Pool de Threads do Application Server possui uma licença válida consumida. Esta API deve ser utilizada, em softwares com arquitetura SOA, onde as requisições são processadas por WebServices e o consumo do licenciamento foi realizado pela camada Client. Assim, caso haja a tentativa de utilizar o pool de serviço para uma customização, será automaticamente consumida uma licença TOTVS I, conforme abordado anteriormente.

Procedimentos:

1. Verificar se o retorno da API LSIsOnLine é positivo, caso contrário retornar 0 (zero).
2. Verificar se a versão do TOTVS|License Server é igual ou superior a 2014, caso contrário retornar uma exceção.
3. Montar o pacote JSon conforme o parâmetro informado
4. Concatenar ao pacote Json a seguinte expressão: Json = “TOTVSLICENSESERVER_DEFAULT|”+Json
5. Invocar o metodo SLC_callinternal passando no parâmetro code o valor 10003 e o novo valor do Json no parâmetro par1.
6. Verificar o Json de retorno e retornar 1 se válido e 0 (zero) se inválido
7. Na sequência, forçar o consumo de uma licença TOTVS I.

Parâmetros:

• String com o uniqueId. O uniqueId é retornado no Json da API LsgetLicense

Retorno:

• Retorna 1 em caso de sucesso ou 0 (zero) em caso de insucesso.

Json de envio da API:

Json de retorno da API:

Critérios de Aceitação 

Considera-se um software TOTVS integrado ao TOTVS|License Server, quando os seguintes componentes de software forem desenvolvidos e entregues pela linha de produto:

• Desenvolvimento Client - APIs de integração
• Padrão de Identificação do Produto
• Auxilio ao Suporte
• Treinamento de instalação da linha de produto com o TOTVS|License Server

Todos estes itens estarão contemplados no produto PIMS Multicultivo após as duas fases de implementação. 

Primeira Fase de Implementação 

Agrupadores de Negócio e Consumo de Licença

A questão principal do licenciamento TOTVS é onde ele deve ser chamado. A recomendação é que o licenciamento seja chamado logo após a seleção do item de menu da linha de produto, assim tem-se a certeza de qual Agrupador de Negócio deve ser utilizado.

Embora a recomendação seja a chamada do licenciamento a cada menu, nesta primeira etapa de integração o licenciamento será verificado apenas no momento do login, isto porque não temos uma clara definição de todos os agrupadores de negócio que irão compor o PIMS Multicultivo até o presente momento.

Na primeira etapa, será considerado apenas um número de slot para consumo de licenças. Este slot, de número 4100, é relativo ao Agrupamento de Negócios de Gestão Agrícola:

Uma vez que o licenciamento for obtido com sucesso no momento do login, o usuário poderá acessar qualquer menu da aplicação sem a necessidade de consumo de outra licença.

As seguintes regras devem ser observadas: 

• A licença recuperada no login deverá ser armazenada na sessão do usuário
• Quando um usuário já tiver feito o login no sistema poderá acessar qualquer menu do sistema.
• Caso o usuário abra a aplicação em outro navegador, criando assim uma nova sessão, uma nova licença deverá ser consumida.
• Ao ser finalizada a sessão do usuário, a licença consumida deve ser devolvida (liberada) no servidor de licenças.  

Desenvolvimento de APIs 

Nesta etapa serão desenvolvidas as APIs necessárias para suportar esta forma de integração com o servidor de licenças. Estas APIs foram descritas anteriormente neste documento, e os exemplos levam em consideração uma DLL, que terá suas rotinas descritas, mas não utilizadas, devido à necessidade de execução do PIMS Multicultivo em ambientes que não suportam a mesma. 

Seleção de Empresa no Sistema 

Ao obter uma licença, uma das possíveis solicitações feitas pelo servidor de licenças é o envio dos dados da empresa em questão. Como no PIMS Multicultivo há a possibilidade de muitas empresas cadastradas, a definição da empresa cujos dados serão enviados será feita através de um novo parâmetro, visível ao usuário, chamado LS_EMPRESA, de um novo grupo de parâmetros chamado LicenseSer (TOTVS License Server). Este parâmetro deverá conter o id da empresa cadastrada que será usada para envio dos dados ao servidor de licenças. 

-    Incluir novo parâmetro no cadastro Grupo de Parâmetros (tabela PRXGPPARAMETER): 

INSERT INTO PRXGPPARAMETER (ID_PRXGPPARAMETER, CD_PRXGPPARAMETER, DA_PRXGPPARAMETER, DE_PRXGPPARAMETER, ID_TERMO, ROWVERSION, LAST_UPDATE, CHANGED_BY) VALUES (30, 30, 'LicenseSer', 'TOTVS License Server', <ID_TERMO>, 1, SYSDATE, 'PRX'); 

Onde: <ID_TERMO> Identificador do Termo para o descritivo 'TOTVS License Server' (criar registro na tabela TERMO)

-    Incluir novo parâmetro no cadastro de parâmetros de configuração/controle da aplicação (tabela PRXPARAMETER): 

INSERT INTO PRXPARAMETER (ID_PRXPARAMETER, CONTEXT_APL, NAME_PARAMETER, DESCRIPTION, ID_PRXGPPARAMETER, FG_VISIVEL, ID_PRXTABELA, ID_TERMO, ROWVERSION, LAST_UPDATE, CHANGED_BY, FG_UNIDADEADM) VALUES (3000, 'PIMSGRAOS.TOTVS_LICENSE_SERVICE', 'LS_EMPRESA', 'Empresa para envio de dados ao servidor de licenças', 30, 'S', 16, <ID_TERMO>, 1, SYSDATE, 'PRX', 'N'); 

INSERT TABLE PRX_TAB_REFFRACA (ID_PRX_TAB_REFFRACA,ID_TAB_REFERENCIA,ID_TAB_DADOS,DE_CAMPO,ID_TERMO,DE_COMANDO,ROWVERSION,LAST_UPDATE,CHANGED_BY,FG_DELETE_CASCADE) VALUES(107,16,62,'ID_VALOR',9238,'SELECT COUNT(PP.ID_VALOR) NUMERO FROM PRXPARAMETER PP JOIN PRXTABELA PT ON (PT.ID_PRXTABELA = PP.ID_PRXTABELA) WHERE PT.CD_PRXTABELA = 'EMPRESA' AND PP.ID_VALOR = ?',1,'SYSDATE','PRX','N'); 

Onde: <ID_TERMO> Identificador do Termo para o descritivo 'Empresa para envio de dados ao servidor de licenças' (criar registro na tabela TERMO) 

Habilitação do Licenciamento no PIMS Multicultivo 

Hoje a habilitação do licenciamento no PIMS Multicultivo é determinada por um parâmetro em um arquivo de propriedades que fica no cliente. O arquivo em questão é o login.properties. O trecho deste arquivo que habilita o licenciamento está destacado na imagem abaixo:

A habilitação do licenciamento feita desta forma permitiria que o usuário pudesse alterar o parâmetro a qualquer momento, deixando assim de consumir licenças.

Uma opção seria exigir o licenciamento sempre, independentemente de parâmetros, mas para atender a clientes que já estão em produção sem a instalação do servidor de licenças, e até mesmo para que a implantação da versão licenciada seja progressiva, é importante manter esta habilitação parametrizada. Desta forma deve-se criar um novo parâmetro, invisível ao usuário, chamado LS_HABILITADO, cujo valor poderá ser true ou false. Este parâmetro deverá ser alterado apenas por consultores, durante a instalação ou atualização do produto, mediante scritps. 

-    Incluir novo parâmetro no cadastro de parâmetros de configuração/controle da aplicação (tabela PRXPARAMETER): 

INSERT INTO PRXPARAMETER (ID_PRXPARAMETER, CONTEXT_APL, NAME_PARAMETER, DESCRIPTION, VALOR, VALOR_PADRAO, ID_PRXGPPARAMETER, FG_VISIVEL, ID_PRXPARAM_GRP_DOMINIO, ID_TERMO, ROWVERSION, LAST_UPDATE, CHANGED_BY, FG_UNIDADEADM) VALUES (3001, 'PIMSGRAOS.TOTVS_LICENSE_SERVICE', 'LS_HABILITADO', 'Habilita o licenciamento da aplicação PIMS MC', 'false', 'false', 30, 'N', 2, <ID_TERMO>, 1, SYSDATE, 'PRX', 'N');

 Onde: <ID_TERMO> Identificador do Termo para o descritivo 'Habilita o licenciamento da aplicação PIMS MC' (criar registro na tabela TERMO) 

Considerações sobre Main Thread e Thread ID

Dentre as informações que são enviadas ao servidor de licenças no momento da recuperação de uma licença, constam duas que merecem especial atenção: Main Thread e Thread ID.

A Main Thread é um inteiro que identifica de forma única a sessão do usuário na aplicação. Já o Thread ID é um inteiro que identifica o "programa" em execução pelo usuário. Isto significa que, em uma mesma sessão, ou seja, mesmo Main Thread, podem ser executados vários programas, e se algum deles for executado mais de uma vez, na primeira vez haverá o consumo de uma licença e a partir da segunda vez o consumo será abonado. 

Como o PIMS Multicultivo é uma aplicação monolítica, em que não há mais de um aplicativo em execução, a identificação do "programa" terá de ser feita através da identificação do módulo relativo ao menu aberto pelo usuário.

Na primeira etapa de implementação, o Thread ID enviado será o Thread de execução do usuário. Na segunda etapa de implementação, ao recuperar o módulo relativo a um menu, o identificador do mesmo será enviado.

Considerações sobre Liberação da Licença

 A liberação da licença só acontecerá no momento em que o usuário realizar o logout da aplicação, ou no momento da expiração da sessão, caso o usuário feche o navegador sem fazer o logout.  

Considerações sobre Integrações

Integrações com serviços HTTP Simples

As integrações do PIMS Multicultivo com sistemas externos se dão, em algumas situações, através de chamadas HTTP simples aos serviços utilizados pelas telas. Este é o caso, por exemplo, das integrações com a Mobilidade.

Para realizar estas integrações, os aplicativos móveis realizam o login no PIMS Multicultivo através de credenciais fixas, e consomem os dados através de requisições aos serviços HTTP disponibilizados.

Por ser o mesmo processo de login utilizado pelas telas, as requisições de login realizadas pelas aplicações móveis passarão pelo mesmo processo de aquisição de licença. Uma vez consumida a licença, para que ela seja liberada será necessário armazenar a sessão da conexão HTTP e realizar o logout no final da operação, caso contrário a sessão criada no servidor irá reter uma licença a cada chamada.