PHC GO Help Center

Manuais

Como funciona a regra - Ao instalar dataset de add-on

Por vezes, pode existir a necessidade de conseguir intercetar o momento de cópia de registos de um Add-on para a base de dados do cliente final, conhecidos no PHC GO como DataSets. Estes registos são geralmente registos de algum tipo de configuração necessária para que o Add-on possa funcionar corretamente (exemplo: séries de faturação específicas, templates de e-mail para servirem de base para o cliente final, entre outros).

Contudo, o Add-on poderá já estar instalado no cliente final, e tratando-se da instalação de uma nova versão desse mesmo Add-on, nesta situação, o registo de configuração que vem dentro do DataSet, também ele já existe na base de dados do cliente final, e até podem ter ocorridos alterações de alguns valores desse registos pelos utilizadores do cliente final.

É neste cenário que aparece a necessidade de aplicação de uma regra do tipo Ao instalar dataset de Add-on para que o programador de add-ons possa decidir se copia o registo de configuração que vem na nova versão do add-on, esmagando assim as alterações feitas anteriormente pelos utilizadores do cliente final, ou se deseja outro tipo de ação, como ignorar uma operação de cópia, preservando assim os dados que já existe na base de dados, ou outro tipo de operação mista como seja a atualização com dados anteriores e dados novos da nova versão do Add-on.

Nota

Além desta alteração simples e direta sobre um registo do dataset que está prestes a ser criado ou atualizado na base de dados da instalação do cliente final, o programador de Add-ons poderá utilizar qualquer outro código disponível no SDK dos Add-ons, para conseguir realizar outras operações necessárias nessa altura, como seja, verificar outro tipo de dados na base de dados; criar tarefas; criar outros registos adicionais; etc..

Assim, a regra do tipo Ao instalar dataset de Add-on constitui um evento que irá correr no momento da instalação ou upgrade do Add-on, quando este possui peças do tipo Dataset, sendo que esse evento irá correr tantas vezes quanto o número de registos contidos dentro do Dataset.

A assinatura deste evento recebe dois objetos, que serão dois registos da entidade que está selecionada no campo Entidade do registo do evento (ecrã Regras de negócio). O primeiro objeto bdItemVO representa um possível registo que possa já existir na base de dados, mas que poderá ter o valor Nothing indicando que o registo ainda não existe. O segundo objeto addOnItemVO representa o registo que está dentro do add-on e que a aplicação se prepara para copiar para a base de dados do cliente final.

O controlo de como a aplicação irá tratar esta operação de cópia, será através da manipulação do valor do campo Operation de cada um dos VOs, ou simplesmente retornar uma mensagem de erro, que informa a aplicação para cancelar esta cópia em concreto, mas continuar com as seguintes caso exista.

Informação

Os valores que este campo pode conter são os seguintes:

Public Enum OperationEnum As Integer

End Enum

Para melhor entendimento sobre este tipo de evento, vamos mostrar alguns exemplos práticos aplicados em 2 tipos de cenários:

CENÁRIO 1 - É a primeira vez que se está a instalar o add-on XPTO que contém um registo no dataset da entidade Artigos e Serviços (a referência FRETE que internamente tem o STSTAMP com o valor 1234), e na base de dados do cliente final, não existe nenhuma referência cujo STSTAMP seja 1234, então nesse caso o comportamento expectável seria o registo ser copiado do add-on para a instalação do cliente final, isto porque ainda não existe na BD do cliente.

Atendendo que neste cenário será a 1ª vez que o cliente instala o add-on, a aplicação copiará o registo de Artigos e Serviços do Dataset tal e qual como foi criado. Trata-se do comportamento default quando se instala pela 1ª vez o add-on. O valor do objeto bdItemVO é Nothing e o objeto addOnItemVO contém o registo que será criado na BD do cliente.

Podemos no entanto, interceptar o momento deste evento e efectuar algumas validações. Por exemplo, se o cliente já possui um artigo com referência FRETE, a aplicação por defeito não permite que seja criado um segundo artigo com a mesma referência e convém neste caso tratar esta situação.

Assim, podemos optar por não copiar o registo do dataset ou alterar o nome do artigo para FRETE_ADDON_XPTO para que assim seja criado na BD do cliente.

Exemplos:

( 1 ) Validar se já existe um artigo com a referência igual à referência do artigo que queremos introduzir na base de dados. Em caso afirmativo, não criar o registo.

Nome: Cópia de artigos para a BD do cliente
Entidade: Artigos e Serviços
Tipo de código: Ao instalar dataset de Add-on

Código:

If bdItemVO is Nothing  
     If SDK.Query.ExistRecord(ST.getTableName,New FilterItem(ST.ref, Comparison.Equal, addOnItemVO.ref)) 
     addOnItemVO.Operation = OperationEnum.None 
     End if 
End if

If bdItemVO is Nothing 
   If SDK.Query.ExistRecord(ST.getTableName,New FilterItem(ST.ref, Comparison.Equal, addOnItemVO.ref)) 
   addOnItemVO.ref = addOnItemVO.ref  + "_ADDON_XPTO" 
   End if 
End if

Na linha 1, primeiro validamos se o artigo já existe na base de dados. Se não existir, verificamos na linha 2 se na base de dados do cliente já existe algum outro artigo com referência igual ao que tentaremos instalar.

No caso afirmativo, a linha 3 é executada, atribuindo um novo valor de referência para o artigo que será criado na BD do cliente, de forma a não criar conflitos.

CENÁRIO 2 - Está a ser instalada a versão 2 do mesmo add-on XPTO que continua a trazer no seu dataset o mesmo registo do artigo FRETE, e na base de dados do cliente final também existe o registo que tinha sido copiado anteriormente, que mantém o valor 1234 no campo STSTAMP, mas que entretanto o cliente já tinha mudado algum campo da ficha do artigo (exemplo: preencheu o Preço de Venda 1 com o preço que lhe era mais conveniente).

Por defeito, neste caso o registo do dataset do Add-on não será criado (uma vez que já existe na base de dados), e o registo existente na BD do cliente manter-se-á tal qual como está.

No entanto, podemos optar atualizar um campo específico, ou até mesmo forçar a criação do registo do dataset, ou seja, esmagar as alterações que o cliente efectuou.

Exemplos:

( 1 ) Validar se o registo do dataset já foi instalado na BD do cliente. No caso afirmativo, atualizar apenas um campo específico.

Nome: Cópia de artigos para a BD do cliente
Entidade: Artigos e Serviços
Tipo de código: Ao instalar dataset de Add-on

Código:

If bdItemVO isNot Nothing andAlso bdItemVO.ststamp = '1234' 
    bdItemVO.obs = addOnItemVO.obs 
    bdItemVO.Operation = OperationEnum.Updated 
End if

Na linha 1, primeiro validamos se o artigo cujo stamp 1234 já existe na base de dados. Se existir, na linha 2 vamos atualizar o seu campo st.obs e na linha 3 indicamos que o registo existente será atualizado.
De salientar, tal como o código está, a atualização do campo st.obs apenas ocorrerá no registo cujo stamp é 1234 deste dataset. Outros registos existentes neste dataset não sofrerão esta alteração.

( 2 ) Validar se o registo do dataset já foi instalado na BD do cliente. No caso afirmativo, esmagar os dados, ou seja, substituir o registo do cliente pelo registo do dataset.

Nome: Cópia de artigos para a BD do cliente
Entidade: Artigos e Serviços
Tipo de código: Ao instalar dataset de Add-on

Código:

If bdItemVO isNot Nothing andAlso bdItemVO.ststamp = '1234' 
    bdItemVO.Operation = OperationEnum.Deleted 
    addOnItemVO.Operation = OperationEnum.Inserted 
End if

Na linha 1, primeiro validamos se o artigo cujo stamp 1234 já existe na base de dados. Se existir, na linha 2 eliminamos o registo existente e na linha 3 indicamos que o registo do dataset tem de ser instalado.

Veja aqui outro exemplo de aplicação deste tipo de regra.