Cross Segmentos - Linha Datasul - MLA - Criação da API para disponibilizar documentos para o APP

 Tempo aproximado para leitura: 00:11:20 min

Dúvida
Como realizar a criação da API para disponibilizar documentos para o Aplicativo - APP Minhas Pendências de Aprovação do MLA - Módulo Logístico de Aprovação?

Ambiente
Cross Segmentos - TOTVS Backoffice (Linha Datasul) - Aprovação Processo Logístico (MLA) - Versão 12

Solução
A nomenclatura da API a ser criada deve ser lap/mla-doc-<número doc>.p.
Por exemplo:

• Para o documento 13 seria lap/mla-doc-13.p.
• Para o documento 501 seria lap/mla-doc-501.p.

É importante entender que este programa será utilizado para configurar os campos que devem aparecer na listagem e detalhamento das pendências no APP, assim como para preencher os campos com os seus respectivos valores.
Para o cabeçalho segue exemplo, com explicações:

Para documentos específicos não é necessário a parte de versionamento, licenciamento e pontos de entrada.
A include lap/mlaapi021.i1 e lap/cria-tt-layout.i são liberadas para que se possa fazer a compilação dos programas. Na sequência, deve-se implementar as procedures pi-retorna-campos-lista e pi-retorna-campos-detalhe.

• pi-retorna-campos-lista: Utilizada para retorno dos campos que podem ser configurados para a listagem
• pi-retorna-campos-detalhe: Utilizada para retorno dos campos que podem ser configurados para o detalhe

As duas procedures possuem a mesma estrutura de parâmetros de entrada e saída.

Sobre a estrutura da temp-table tt-layout:

Para a criação dos campos na temp-table, sugere-se a utilização da include lap/cria-tt-layout.i, pois ela já faz o tratamento para técnica de tradução e também já faz o tratamento para criar na temp-table os campos para retorno conforme visibilidade. Por exemplo, se estiver marcado para retornar somente visíveis, criará apenas os campos visíveis para retorno. Se fizer a criação manualmente, precisará se preocupar com estes detalhes.
Exemplo de utilização abaixo, lembrando que deverá existir uma chamada para cada componente:

{lap/cria-tt-layout.i &cCodIdCampo="'doc-nr-requisicao'"
                               &iIdiCompon="1"
                               &cNomRotuCampo="'Requisição'"
                               &cDesCampo="'Número da Requisição'"
                               &lLogVisivel="TRUE"
                               &iCdnTam="100"}

Se utilizada esta include, a ordenação dos campos, seguirá a ordem em que forem criados.

Para as procedures de retorno de campos para lista e detalhe, caso se deseje retornar também os campos genéricos do MLA, pode-se chamar o programa que os retorna, dentro de cada uma das procedures. Por exemplo, para incluir os campos de informações genéricas do MLA na lista ou detalhe, pode-se utilizar o trecho a seguir.

Veja que neste exemplo, na chamada na include lap/cria-tt-layout.i, foi fixado para que todos os campos genéricos fiquem como não visíveis - &lLogVisivel=”false” e o tamanho como 100 - &iCdnTam="100", se desejasse que eles tivessem a mesma visibilidade e tamanho que o padrão para os documentos genéricos, poderia utilizar &lLogVisivel="tt-layout-modelo.log-visivel" e &iCdnTam="tt-layout-modelo.cdn-tam".

Para buscar os campos genéricos do MLA para o detalhe, deve-se utilizar a mesma estrutura acima, apenas alterando a procedure para pi-retorna-campos-detalhe.
Caso queira saber quais os campos genéricos do MLA para o APP, consultar o artigo Cross Segmentos - Linha Datasul - MLA - Campos genéricos do MLA no APP Minhas Pendências de Aprovação

Para o retorno da sigla do documento deve-se implementar a procedure pi-retorna-sigla. Com a seguinte estrutura de parâmetros a seguir:

Exemplo:

É necessário também criar as procedures que irão fazer o preenchimento dos valores para mostrar cada campo nas pendências. Para facilitar as explicações, vamos utilizar um exemplo, de que o programa a ser criado deve contemplar a apresentação do documento abaixo:

Deve-se então implementar as procedure pi-preenche-lista e pi-preenche-detalhe que são utilizadas para o preenchimento dos campos da listagem e do detalhamento de pendências, respectivamente, com seus valores de negócio. A estrutura de parâmetros destas procedures deve ser a seguinte:

Para a procedure pi-preenche-lista, temos o exemplo de implementação na sequência, com explicação dos códigos:

1. É necessário localizar as tabelas de negócio. Neste caso documento é uma temp-table, com somente um registro para demonstração, por isso o FIND FIRST. Na prática deve-se localizar a tabela de negócio conforme a chave do documento disponibilizada pela leitura da tabela mla-doc-pend-aprov.

Abaixo um exemplo para localização da tabela de negócio com base na chave do documento. Definir a include lap/mlaapi001.i99 no início do programa para ter disponível da temp-table tt-mla-chave, e as três variáveis abaixo:

Utilizar a include laphtml/mlacriachave.i para preencher a tt-mla-chave com os campos da chave do documento, neste caso são três. Após isso, utilizar cada posição para localizar o registro de negócio.

2. Preencher os registros da temp-table que vieram com IDs preenchidos com os respectivos valores. A informação deve ser sempre retornada como STRING e formatada como se deseja que apareça no APP.

3. Caso nas procedures de retorno de campos tenha definido para mostrar campos genéricos do MLA é necessário o preenchimento deles.

Na procedure pi-preenche-lista é importante não eliminar o handle das informações genéricas do MLA - h-mla-prog, pois ela será chamada várias vezes de forma persistente. Então deve-se criar a procedure pi-finaliza eliminando este handle.

Para a procedure pi-preenche-detalhe, a estrutura inicial é muito semelhante a procedure de lista. A diferença que temos é para os componentes de listas, com a necessidade de definição de 5 variáveis para cada lista, que serão explicadas a utilização mais para frente. O valor do extent deve ser o número de componentes que a lista possui.
Neste caso temos duas listas, de itens e de entregas, cada uma com dois campos, portanto os extents tem o valor 2. É necessário fazer a leitura das tabelas de negócio, assim como explicado na lista.

Para o preenchimento dos campos que não vão em listas, é igual na listagem.
Lembrando que para separadores e o componente de lista não há valor para retornar neles, são apenas para diferenciar o layout ou tratar a estrutura de filhos.

Já para o preenchimento de campos que vão dentro de listas sugere-se a seguinte estrutura. Preencher as variáveis para indicar:

• Que há campos na lista – l-existe-campo-xxx;
• Para criar o campo filho X – l-cria-filho-xxx;
• Nome do campo filho X – c-campo-filho-xxx;

Lembrando que estas duas variáveis são extent, então para cada campo, deve-se usar uma posição. Por fim, deve-se eliminar o registro da temp-table tt-campo-valor. Isso é necessário, pois teremos que criar um registro deste componente para cada linha filha existente.

O trecho de código a seguir, deve vir depois do FOR EACH da tt-campo-valor.
Neste momento, precisamos preencher os campos das listas, criando um registro para cada linha e componente existente no modelo definido.

1. Inicializar o contador da lista, que será incrementado a cada linha. Neste caso, a cada item encontrado do documento.
2. No caso de haver mais um nível de lista dentro desta, é necessário eliminar o registro o componente de lista, pois será necessário criar um por linha de item. Definir o buffer no início do programa: DEFINE BUFFER bf-tt-campo-valor FOR tt-campo-valor.
3. Realizar a leitura da tabela filha, com base no pai. Passar por todos os campos da lista. Neste caso são dois. Se o campo em questão deve ser retornado, criar um registro na tt-campo-valor, se atentando para o ID do campo, linha e o ID do pai. Preencher o valor do campo conforme regras de negócio.
4. Trecho será explicado na próxima imagem.

Sobre o preenchimento dos campos para a lista de entregas:

1. Se houverem campos a serem apresentados para a segunda lista, neste caso, de entregas, deve fazer basicamente o mesmo tratamento que a primeira lista para preencher os campos.
2. Diferença: Será necessário criar um componente de lista, para cada registro da lista anterior, neste caso, para cada item.
3. Diferença: Necessário preencher o campo de linha pai, com o número da linha pai. Neste caso, linha do item em questão.

Caso nas procedures de retorno de campos tenha definido para mostrar campos genéricos do MLA é necessário o preenchimento deles.

Verificando o resultado do programa no Configurador Visual – Lista:

Verificando o resultado do programa no Configurador Visual – Detalhe:

Verificando o resultado do programa no APP – Lista:

Verificando o resultado do programa no APP – Detalhe:

Saiba mais
Para os documentos padrões é importante que em cada procedure citada, seja incluso os pontos de EPC - External Program Call padronizados, para que seja possível customizar o documento. Para verificar quais pontos devem ser disponibilizados verificar a documentação Cross Segmentos - Linha Datasul - MLA - Customização de documento padrão disponibilizado no APP

Anexo
Para conferir um exemplo completo da API, veja o anexo abaixo.