Modelação de Entidades

Entidade Simples

1. Abrir o Modelo de Entidades (EntitiesModel.ed3)

2. Aceder à toolbox, selecionar a Entity e arrastar para o modelo

3. Aceder às propriedades da nova entidade (F4) e alterar-lhe o Name (o nome deve ser singular)

4. Adicionar novos campos à entidade clicando com o botão direito do rato em Attributes e selecionando “Add New Normal Attribute”

5. Aceder às propriedades do campo criado (F4), alterar o Name e associar ao Type pretendido

6. Ter em atenção que a entidade tem que possuir pelo menos uma Natural Key (nas propriedades do campo pretendido para Natural Key, colocar esta a True)

Associar uma Value List à Entidade

1. Aceder à toolbox, selecionar a Value List e arrastar para o modelo

2. Aceder às propriedades da nova value list (F4) e alterar-lhe o Name (o nome deve ser singular)

3. Adicionar novos campos à value list clicando com o botão direito do rato em Attributes e selecionando “Add New Value List Item” (os itens devem conter apenas uma palavra)

4. Aceder à toolbox, selecionar Association e fazer a associação desde a entidade até à value list.

5. Garantir que o modelo se encontra válido (botão direito do rato no modelo e selecionar a opção Validate) e guardar o modelo.  

Entidade Master Detail

1. Criar as entidades master e detail da mesma forma que se cria uma entidade simples (com a exceção que a entidade detail não terá uma Natural Key associada)

2. Aceder à toolbox, selecionar Association e fazer a associação desde a entidade master até à entidade detail

3. Clicar na linha que faz a associação, aceder às suas propriedades (F4) e colocar Composition a True.

External Entities

External entities são entidades de outros módulos que são acessíveis no módulo em questão. Por exemplo, no módulo CorePatterns encontra-se uma entidade que é utilizada em praticamente todos os módulos: Currency.

Assim, caso se queira referenciar esta entidade noutro módulo, é necessário seguir os seguintes passos:

1. Clicar com o botão direito do rato na Module Reference do módulo em questão

2. Selecionar Modules > Import Entities

3. Selecionar a entidade que se pretende importar

4. Aceder à toolbox, selecionar Association e fazer a associação desde a entidade até à external entity.

Extensões de Entidades Base

1. A extensão de uma entidade é feita através da ligação com uma Extension (acessível através da Toolbox como está representado na imagem) da entidade que se pretende fazer a extensão até uma outra entidade.

1. Para simplificar, utilizar-se-á um exemplo de implementação dos CompanySets no módulo BusinessCore. A entidade Company pertence ao módulo CorePatterns, contudo a entidade CompanySet pertence ao módulo BusinessCore e é uma extensão das Companies. A extensão permite que a entidade CompanySet herde todas as propriedades da entidade Company, acrescentando-lhe ainda as propriedades da própria extensão.

1. No modelo de menu da solução do produto (MenuModel.md3), pode ser representada tanto a lista das Companies como a lista dos CompanySets, sendo que ambas incluem a extensão na view.

   a. Se for inserida no modelo de menu a lista das Companies, a view permitirá apagar a extensão dos CompanySets, mesmo em modo de visualização.

   b. Contudo, se for inserida no modelo de menu a lista dos CompanySets, a extensão não poderá ser apagada em modo de visualização, o que se traduz numa vantagem uma vez que esta extensão tem campos que são obrigatórios para a definição da empresa.

Modelação de Serviços

1. Abrir o Modelo de Serviços (ServicesModel.sd3), selecionar a Module Reference do módulo em questão e clicar com o botão direito do rato na mesma selecionando Services > Generate Services

2. Selecionar os serviços que se pretende gerar (correspondentes às entidades criadas previamente)

3. Para adicionar colunas nas List Operations, clicar com o botão direito do rato na List Operation e selecionar List Operations > Select Attributes

4. Em cada uma das colunas é possível definir para cada uma se é para excluir da lista (Exclude From List) ou incluir na pesquisa (Include on Search).

Modelação de Views

1. Abrir o Modelo de Apresentação (PresentationModel.prd3)

2. Clicar com o botão direito do rato no modelo e selecionar Services > Generate Operations

3. Selecionar as operações que se pretende gerar

4. Clicar com o botão direito do rato na Editor View gerada, selecionar Views (Editor) e, por último, selecionar Edit Layout.

5. É aberta uma janela Edit View Layout que permite configurar o layout da view, selecionando colunas e linhas do bootstrap e a respetiva largura das mesmas (para phone, desktop e large desktop)

6. Depois de todas as configurações necessárias, validar o modelo com o botão direito do rato no fundo do mesmo e selecionando Validate, ou simplesmente guardando o modelo, que já faz a sua validação

Publish do Módulo

1. Abrir as soluções do módulo e do produto

2. Depois da solução do módulo devidamente transformada e compilada, utilizar o script Powershell “Update_Module.ps1” para copiar vários ficheiros do modelo para o produto: ficheiros javascript, views e json gerados dos modelos. Como alternativa, podem ser copiados os ficheiros da pasta do módulo para a pasta do produto (em que o ponto i do módulo é copiado para o ponto i do produto, e assim sucessivamente):

a. Módulo i. NomeDoMódulo \ Client \ Host \ Views \ nomeDoMódulo (apenas os ficheiros .cshtml) ii. NomeDoMódulo \ Client \ Host \ app \ modules \ nomeDoMódulo (apenas os ficheiros .js) iii. NomeDoMódulo \ Models \ Database \ GeneratedCode \ Organization (apenas os ficheiros .sql)

b. Produto i. NomeDoProduto \ Host \ Host \ Views \ nomeDoMódulo ii. NomeDoProduto \ Host \ Host \ app \ modules \ nomeDoMódulo iii. NomeDoProduto \ Database \ Database \ Database \ Organization \ NomeDoMódulo

Nota: no caso de novos ficheiros ou pastas, não esquecer de incluir na solução do produto.

Para passar os ficheiros .json atualizados para a solução do produto:

I. Módulo NomeDoMódulo \ Models \ Models \ GeneratedCode

II. Produto NomeDoProduto \ Models \ Models \ ExternalModels \ nomeDoMódulo

Nota: Este ponto 2 apenas é necessário se não existirem builds para o módulo em questão, uma vez que o processo das builds trata destes passos automaticamente.

1. Adicionar o módulo ao modelo do produto: na solução do produto, em Models, aceder ao ProductModel.pd3 a. Clicar com o botão direito do rato no fundo do modelo, selecionar Modules > Add Modules b. Selecionar o módulo que se pretende adicionar ao produto c. Guardar o modelo (a gravação gera o ficheiro .json correspondente) d. Transformar a solução do produto

2. Para configurar a conexão à base de dados: a. Aceder ao projeto Deployment na solução do produto b. Em Settings > Provisioning > Provisioning.json é possível configurar os dados necessários para a criação da base de dados.

Restrições de Lookup

1. Abrir o Modelo de Serviços (ServicesModel.sd3) e criar uma List Operation (arrastar de Toolbox > List Operation)

2. Estabelecer a ligação entre a List Operation e o seu respetivo serviço (Toolbox > Link)

3. Acedendo às propriedades da List Operation (F4), verifica-se que o Resource já se encontra preenchido de acordo com a ligação feita ao serviço.

4. Nas propriedades, alterar o List Type para “Lookup”

5. Inserir o Lookup Attribute selecionando o campo pretendido para a restrição de lookup

6. Inserir o código SQL no campo FIlter, com as restrições pretendidas para a lookup

   i. Caso seja necessário, adicionar os atributos (colunas) na List Operation (botão direito na List Operation > List Operations > Select Attributes > selecionar os atributos pretendidos da lista)

   ii. Adicionar os parâmetros necessários para a query (botão direito em Parameters > add new List Operation Parameter > escrever o nome do parâmetro e associar ao seu tipo). Estes parâmetros deverão ser preenchidos no Service Manager que será criado para o efeito (se não existir).

1. Transformar a solução para que seja gerado o sql respetivo das lookups e para poder adicionar a restrição de lookup ao Service Manager

2. Se não existir, criar a classe para o respetivo serviço (ServiceNameServiceManager.Lookups.cs) em Server > Custom Code

3. Fazer override ao método AddLookupConditionsFor(…) e, dentro do mesmo, preencher os parâmetros passados à List Operation no ponto 6ii

Side Effects

1. Abrir o Modelo de Entidades (EntitiesModel.ed3) e aceder às propriedades do campo ao qual se quer associar o Side Effect. Colocar a propriedade Has Side Effects a True

1. Transformar a solução para gerar os métodos necessários para desenvolver a funcionalidade do Side Effect

2. Se não existir, criar a classe Service Manager para o serviço da entidade à qual se adicionou o Side Effect (ServiceNameServiceManager.SideEffects.cs)

Nota: no caso de criar uma classe nova, o namespace desta classe deve ser alterado para conter apenas até Primavera.NomeMódulo.Domain

1. Fazer override ao método que foi gerado após a transformação da solução: o método é o que contém o nome do campo ao qual se associou o Side Effect. Como a lógica do Side Effect é uma lógica de negócio, deve ser inserida no Manager. Assim, é necessário adicionar ao método “contexto.Handled = false”, para ser direcionado para o Manager, onde será feito mais uma vez override ao método

1. Se não existir, criar a classe Manager para o serviço da entidade à qual se adicionou o Side Effect (ServiceNameManager.SideEffects.cs)

Nota: mais uma vez, no caso de criar uma classe nova, o namespace desta classe deve ser alterado para conter apenas até Primavera.NomeMódulo.Domain

1. Fazer override ao método e inserir a lógica de negócio subjacente ao Side Effect:

Inline Validations

1. Abrir o Modelo de Entidades (EntitiesModel.ed3) e aceder às propriedades do campo ao qual se quer adicionar uma Inline Validation. Em Validation Rules, clicar em “…”. De seguida, selecionar clicar com o botão direito do rato em “Rules for ‘NomeCampo’” e clicar em Add. Selecionar a “CustomValidation”

1. Transformar a solução para gerar os métodos necessários para desenvolver a funcionalidade da Inline Validation

2. Se não existir, criar a classe Validator Service para a entidade à qual se adicionou a Inline Validation (EntityNameValidatorService.cs)

Nota: no caso de criar uma classe nova, o namespace desta classe deve ser alterado para conter apenas até Primavera.NomeMódulo.Domain

1. Fazer override ao método que foi gerado após a transformação da solução: o método é o que contém o nome do campo ao qual se associou a Inline Validation

1. A lógica envolvida na Inline Validation deve constar no Service Manager. Assim, caso não exista, é necessário criar a classe Service Manager para o serviço da entidade à qual se adicionou a Inline Validation (ServiceNameServiceManager.cs)

2. Criar um método do tipo ValidationResult, que é chamado no ValidatorService para tratar a lógica da Inline Validation:

UI Rules

1. Na solução do módulo em questão, criar um novo ficheiro para a UI Rule em /Models/Rules (NomeADesignarRules.json)

2. Configurar a UI Rule de acordo com a regra que se pretende implementar, indicando os seguintes campos: i. Entity: resource sobre a qual se quer aplicar a regra ii. Field: campo que vai determinar se a regra é aplicada iii. Returns actions action type: ação que se quer aplicar no target iv. Return actions target: campo que será sujeito à ação v. Return actions value: condição para que a regra se aplique

1. Abrir o Modelo de Apresentação (PresentationModel.prd3) e aceder às propriedades do Editor Operation ao qual se quer adicionar uma UI Rule. Em UI Rules Definition, clicar em “…” e selecionar o ficheiro criado com as regras

UI Rules definidas ao nível do Presentation Model

Atualmente, as regras de UI podem ser definidas tanto no ficheiro de regras como ao nível do Presentation Model. No entanto, se existir uma regra definida na modelação as regras definidas no ficheiro de regras serão ignoradas.

• Regras de UI para visibilidade de campos

Para definir regras de UI para a visibilidade de campos no Presentation Model basta aceder ao modelo, abrir o editor view layout e associar a expressão que será utilizada para a regra ao campo, coluna, linha, expander ou grelha pretendida.

Exemplo de aplicação de regra de UI para a visibilidade de coluna:

Neste caso, o que acontece, é que na view de sequências, a coluna entidade (e, por sua vez, o campo que esta coluna contém), apenas será visível caso o campo "Tipo de Segmento" tenha o valor 1 (Entidade).

Para mais informação acerca das UI Rules consultar o documento Regras UI.

Custom Reports

Neste capítulo vamos demonstrar a modulação de um report.

Pré-requisitos

Como pré-requisito é obrigatório ter os packages Primavera.Reporting.Api e Primavera.Reporting.Engine instalado nos seguintes projetos:

• Data
• Domain
• Domain.Entities
• Models

Para instalar um package deverá executar o comando:

Install-Package [package_name] -Project [ProjectName]

Na figura seguinte demonstramos a instalação do package Primavera.Reporting.Api no projeto Models.

Modelo de Entidades

No modelo de entidades deverá associar a interface IReportableDocument a entidade que pretende efetuar a impressão. A implementação da interface vai obrigar a criação do atributo IsPrinted. Na figura seguinte demonstramos a associação da interface na entidade Journal Entry.

Modelo de Apresentação

No modelo de apresentação vamos adicionar um Report View e associar a um Operation (Editor).

No Operation (Editor) de criar um Journal Entry vamos adicionar uma ação com o nome SaveAndPrint e que tem como Service Action a opção Insert.

Para editar o layout do report, escolhemos a opção Edit Layout do menu de contexto referente ao clique do rato sobre o Report View. Neste editor existe dois tipos de reporting type, o Document e Standard. A diferença entre os dois tipos é a sua estrutura.

Template de base de dados

Para finalizar, é obrigatório adicionar uma scipt ao projeto database para associar o template do cliente ao report.

IF not exists (select top 1 id from Reporting.TemplateEntitygroups where Id ='B1ADCF50-2798-46FB-ACD5-80AB0E436455')
BEGIN
    Insert Into Reporting.TemplateEntitygroups (Id, Name, Description, ReportTypeId, NaturalKey, IsDraft) 
        Values ('B1ADCF50-2798-46FB-ACD5-80AB0E436455', 'S04', 'Accounting', 'E97C8BA9-A731-42ED-8537-E4813263426E', 'S04', 0)

    Insert Into Reporting.GroupTemplates (Id, TemplateId, IsDefaultForGroupEntities, TemplateEntityGroupId, [Index])
        Values ('8883F1BD-C69A-487A-98D8-BC72E64FE5B0', (Select top 1 [id] from Reporting.Templates where TemplateKey = 'Document'), 1, 'B1ADCF50-2798-46FB-ACD5-80AB0E436455', 0)

    Insert into Reporting.GroupSchemaEntities (Id, SchemaEntityId, TemplateEntityGroupId, [Index])
        Values ('66B9FF4F-3716-4221-9119-818DB0723C71', (Select Top 1 [Id] from CorePatterns.SchemaEntities WITH(NOLOCK) where [Key] = 'JournalEntries' And ModuleName = 'Accounting'), 'B1ADCF50-2798-46FB-ACD5-80AB0E436455', 0)

END

Criação de novas rotas

Quando forem criadas novas rotas, ou seja:

1 - Novas entidades

2 - Novas Views

3 - Mudar nome de operações,

4 - etc.

Devem ser seguidos os seguintes passos para validar:

1. Executar o ficheiro app.routes.tt

1. Validar que a rota está nas diferenças

1. Correr o comando "npm run build" numa linha de comandos/VS Code/etc.

Alteração da definição de uma view

Os passos para a alteração da definição de uma view são os seguintes:

1. Copiar o PresentationModel.json para a pasta ExternalModels do Produto

1. Transformar o TT "ProductViewDefinitions.tt" (Na solução do Produto, Projecto Deployment)

1. Correr o UnitTest ((ProcessRoseViewDefinitionsDevAsync)

NOTAS:

1. Isto altera a definição das Views para toda a gente que está a desenvolver e a usar o ambiente de DEV

2. Se continuar a ser usada a mesma janela, não haverá diferenças, uma vez que estas ficam na Session Storage. Para validar as alterações, abrir um novo tab.

3. Se ao Executar o Teste der o erro: "The table configuration service is invalid", verificar se o pisco no menu: "Test > Test Settings > ...Automation.testsettings" está DESATIVADO.

Modelação de Menu de Contexto com Opções Custom

1. Abrir o Modelo de Entidades e criar uma nova entidade que representará a informação contida no menu de contexto (Ex.: DetailAccountBalance) e liga-la à entidade que representa as linhas às quais se quer adicionar o menu de contexto (FinancialYearProcessLogLine).

1. No Modelo de Serviços, a entidade Master Detail (FinancialYearProcessLog) deve ter uma Main Resource associada. Caso não tenha, deve ser criada (StandardProcessYearLog).

1. Criar uma resource para o menu de contexto, que deve ser ligado ao serviço do Master Detail (FinancialYearProcessLogs).

1. No Modelo de Apresentação, criar uma Editor View que corresponderá à view que será apresentada quando selecionado o menu de contexto (neste exemplo corresponde a ProcessLogLinePartialAccountBalanceView).

2. Ligar a view acabada de criar à view que diz respeito à entidade Master Detail (StandardProcessYearLogView).

1. Selecionar a view criada, clicar com o botão direito do rato na mesma e selecionar Views (Editor) > Edit Layout.
2. Inserir colunas/linhas conforme o layout pretendido e adicionar os campos que se pretende mostrar.
3. Selecionar a view do Master Detail (StandardProcessYearLogView), clicar com o botão direito do rato na mesma e selecionar Views (Editor) > Edit Layout.

4. Inserir um novo campo nas linhas (Details) – AccountBalancesLink – que deve ser configurado da seguinte forma:

   i. Field Type: Link ii. Action Type: ShowModal iii. Referenced View: ProcessLogLinePartialAccountBalanceView (a view criada anteriormente) iv. Display: RowActions

Modelação Custom DrillDown

1. Abrir o Modelo de Serviços (ServicesModel.sd3) e criar uma Service Action (exemplo no módulo FinancialCore: DrillDownToAccountDoc)

NOTA: a service action tem nas suas propriedades (F4) um Detail Target, o qual deve ser selecionado caso se pretenda implementar o custom drilldown num campo que esteja contido num detalhe.

1. Ligar a Service Action ao serviço ao qual se quer associar o Custom DrillDown (exemplo: FinancialYearProcessLogs)

2. Abrir o Modelo de Apresentação (PresentationModel.pd3) e editar a view que contém o campo ao qual se pretende implementar o custom drilldown

3. Selecionar o campo e atribuir-lhe as seguintes propriedades:

   • Action Type: Custom

   • Service Action: “DrillDownToAccountDoc”

1. Validar os modelos e transformar a solução

2. Verificar se no módulo em questão já existe no projeto Services.Controllers, na secção do Custom Code, uma classe denominada de NavigationHelper.cs, que contém o código necessário ao funcionamento do Custom DrillDown. Se não existir, deve ser criada em “\Services.Controllers\CustomCode\DrillDown\ NavigationHelper.cs” (ver exemplos noutros módulos).

3. Depois de transformada a solução, foi gerado o método “OnDrillDownToAccountDocAsync”, que deve ser overriden. Para tal, criar uma nova classe no projeto Services.Controllers e fazer override ao método anterior.

Botões de Ação nas Views de Create e Edit

A criação dos botões de ação, como o exemplo do “Save and Reverse” e do “Reverse” das imagens abaixo, são criados através de modelação de serviços e apresentação.

Para criar as duas ações devem ser seguidos os seguintes passos:

1. Abrir o modelo de serviços (ServicesModel.sd3) do módulo em questão e, através da Toolbox, criar duas Service Action. Atribuir o nome às Service Action e ligar ao respetivo serviço.

1. Abrir o modelo de apresentação (PresentationModel.pd3) e criar a ação primária “Save and Reverse” no Create:

1. Criar a ação secundária “Reverse” no Edit:

1. Validar os modelos e transformar toda a solução

2. É gerado código para ambas as ações no projeto Services.Controllers. Se não existir, deve ser criada uma classe no CustomCode deste projeto (neste exemplo, é a “AccountingJournalEntriesController”)

3. Para a implementação das ações, deve ser feito override aos métodos gerados: