Manipulação das informações dos anexos

Produto:	Datasul
Ocorrência:	Documentação de API
Nome físico:	hubapi/apiDocuments.p

Objetivo

Manipular e retornar informações sobre os documentos anexados nos processos. Os processos neste caso, podem ser configurados conforme necessidade da área, para compras, por exemplo: ordens de compra, pedidos, cotações, entre outros.

A api de documentos permite a inclusão de anexo, consulta, download, upload e exclusão individual e em lote.

Funcionamento

A API fornece uma série de métodos que podem ser executados individualmente para apresentação dos anexos na tela do documento.

Segue a sintaxe para a chamada da API, que deve ser de forma persistente:

RUN hubapi/apiDocuments.p PERSISTENT SET h-handle.

A variável denominada h-handle irá receber o “handle” do programa, permitindo o acesso aos “métodos” internos da API.

Método Negócio

Quando a API for executada em modo persistente, os seguintes métodos estarão disponíveis para execução:

pi-metada-v1

Requisito

Nenhum.

Descrição

Retorna o metadados com os campos e ações ativos referentes a tela de Listagem (list), Consulta (view) ou Edição (edit), dependendo de qual tipo foi enviado pela requisição, para a montagem dinâmica da tela com as informações vindas do backend.

Parâmetros

Tipo

Input/Output

Descrição

oInput

JsonObject

INPUT

Parâmetros para a busca de metadados:

pathParams: Informar: metadata.

queryParams → type: Utilizando este atributo com uma das opções abaixo permite retornar as informações de:

list: Metadados da tela de listagem.
edit: Metadados da tela de inclusão do arquivo.

Exemplo

{
    "queryParams": {
    "type": "list"
  },
    "pathParams": [
       "metadata"
    ],
}

cEvent Character INPUT Identifica qual o tipo de evento vindo do queryParams para a busca do metadado correto.

cVersion Character INPUT Identifica a versão da API.

oOutput

JsonObject

OUTPUT

Retorno contendo o metadados com os campos e ações conforme parâmetros recebidos:

Metadados List:

List

{ "literals": {}, "validateFields": [], "title": "Anexos de documentos", "fields": [ { "visible": false, "property": "documentId", "label": "Código", "type": "number", "key": true, "order": 1 }, { "visible": false, "property": "processType", "options": [ { "label": "Ordem de Compra", "value": 1 }, { "label": "Cotação de Materiais", "value": 2 } ], "label": "Tipo Processo", "type": "label", "order": 2, "labels": [ { "label": "Ordem de Compra", "value": 1 }, { "label": "Cotação de Materiais", "value": 2 } ] }, { "visible": false, "property": "processKey", "label": "Chave Processo", "type": "string", "order": 3 }, { "property": "documentName", "width": "20%", "label": "Documento", "type": "string", "order": 4 }, { "property": "documentSize", "width": "10%", "label": "Tamanho", "type": "string", "order": 5 }, { "property": "documentDescription", "width": "30%", "label": "Descrição", "type": "string", "order": 6 }, { "visible": false, "allowColumnsManager": true, "property": "creationUser", "width": "5%", "label": "Criador", "type": "string", "order": 7 }, { "visible": false, "allowColumnsManager": true, "property": "creationUserName", "width": "15%", "label": "Nome Criador", "type": "string", "order": 8 }, { "visible": false, "allowColumnsManager": true, "property": "creationDatetime", "width": "20%", "label": "Data", "type": "dateTime", "order": 9 } ], "tableCustomActions": [], "actions": { "new": "/new", "removeAll": true, "remove": true }, "pageCustomActions": [] }

Descrição dos campos:

literals: Objeto com as literais usadas.
validateFields: Lista que define os campos que irão disparar o validate do form.
title: Título da página.
fields: São os campos a serem apresentados na tabela, sendo eles:
- property: Nome de referência do campo.
- label: Rótulo do campo exibido.
- type: Tipo do valor campo.
- key: Valor lógico que indica se o campo é chave.
- order: Informa a ordem de exibição do campo.
- visible: Indica se o campo será visível.
- width: Tamanho do campo.
- allowColumnsManager: Campo estará disponível no gerenciador de colunas.
tableCustomActions: Lista de ações customizadas da tabela que serão incorporadas às ações informadas através da propriedade actions.
actions: Ações que o usuário poderá executar na página através de botões:
- new: Rota ou função para criar um novo recurso, caso seja preenchida habilita a ação de "Novo" na tela de listagem para criação de um novo anexo.
- remove: Habilita a ação de exclusão na tabela.
- removeAll: Habilita a ação de exclusão em lote na página.
pageCustomActions: Lista de ações customizadas da página que serão incorporadas às ações informadas através da propriedade actions. Essas ações ficam localizadas na parte superior da página em botões com ações. Ex: "Novo", "Excluir".

Metadados Edit:

Edit

{
    "defaultFields": [
        {
            "gridColumns": 4,
            "divider": "Processo",
            "label": "Tipo Processo",
            "property": "processType",
            "disabled": true,
            "options": [
                {
                    "value": 1,
                    "label": "Ordem de Compra"
                }
            ]
        },
        {
            "gridColumns": 4,
            "label": "Chave",
            "property": "processKey",
            "disabled": true
        },
        {
            "autoUpload": true,
            "gridColumns": 4,
            "divider": "Anexar Documento",
            "label": "Selecione o documento",
            "property": "documentUpload",
            "required": true,
            "type": "upload"
        },
        {
            "maxLength": 200,
            "gridColumns": 8,
            "label": "Descrição",
            "property": "documentDescription",
            "rows": 4
        }
    ],
    "title": "Novo anexo",
    "breadcrumb": {
        "items": [
            {
                "link": "/",
                "label": "Anexos de documentos"
            },
            {
                "link": "/new",
                "label": "Novo anexo"
            }
        ]
    }
}

Descrição dos campos:

defaultFields: Armazena as informações dos campos padrões do formulários:
- gridColumns: Tamanho de exibição do campo em telas.
- divider: Exibirá um divisor acima, utilizando o seu conteúdo como título.
- label: Rótulo do campo exibido.
- property: Nome de referência do campo.
- disabled: Função que deve retornar um booleano para habilitar ou desabilitar a ação para o registro selecionado.
- options: Lista de opções que serão exibidas em um componente, podendo selecionar uma opção.
  - value: Valor que será usado como referência para exibição do conteúdo na coluna, representa o tipo de processo.
  - label: Rótulo do campo exibido, referenciando o nome do tipo de processo.
autoUpload: Define se o envio do arquivo será automático ao selecionar o mesmo.
required: Indica que o campo será obrigatório.
type: Tipo do valor do campo.
maxLength: Tamanho máximo de caracteres.
rows: Quantidade de linhas exibidas no campo "Descrição".
title: Título da página.
breadcrumb: Objeto com propriedades do breadcrumb, componente que gera uma estrutura de navegação que apresenta ao usuário a localização da URL atual, exibindo as antecessoras conforme é realizado a navegação na aplicação:
- items: Lista de itens do breadcrumb:
  - link: Url do item.
  - label: Rótulo do item.

Metadados View:

View

{
    "keepfilters": false,
    "literals": {},
    "validateFields": [],
    "title": "Consulta de Anexos de Documentos",
    "fields": [
        {
            "visible": false,
            "property": "documentId",
            "label": "Código",
            "type": "number",
            "key": true,
            "order": 1
        },
        {
            "property": "processTypeDescription",
            "width": "15%",
            "label": "Tipo Processo",
            "type": "string",
            "order": 2
        },
        {
            "property": "processKey",
            "width": "15%",
            "label": "Chave Processo",
            "type": "string",
            "order": 3
        },
        {
            "property": "documentName",
            "width": "20%",
            "label": "Documento",
            "type": "string",
            "order": 4
        },
        {
            "property": "documentSize",
            "width": "10%",
            "label": "Tamanho",
            "type": "string",
            "order": 5
        },
        {
            "property": "documentDescription",
            "width": "35%",
            "label": "Descrição",
            "type": "string",
            "order": 6
        },
        {
            "visible": false,
            "allowColumnsManager": true,
            "property": "creationUser",
            "width": "5%",
            "label": "Criador",
            "type": "string",
            "order": 7
        },
        {
            "visible": false,
            "property": "creationUserName",
            "width": "20%",
            "label": "Nome Criador",
            "type": "string",
            "order": 8
        },
        {
            "visible": false,
            "allowColumnsManager": true,
            "property": "creationDatetime",
            "width": "15%",
            "label": "Data",
            "type": "dateTime",
            "order": 9
        }
    ],
    "tableCustomActions": [],
    "pageCustomActions": []
}

Possui os mesmos campos de retorno do metadados "List", sendo que a diferença é que se trata de uma tela de Consulta apenas, então, neste caso, não estão disponíveis as ações ("actions" no json), ou seja, os botões "Novo" e "Excluir" não são carregados na tela.

A requisição é igual ao do metadados List (passando no queryparams o type = list) da api supplyDocuments, apenas alterando a api de origem que é a supplyDocumentsView. No método pi-metadata da supplyDocumentsView é feito o tratamento onde, ao receber o tipo "list" ele envia o tipo "view" para a apiDocuments fazer o tratamento e omitir os campos referente as ações da tela. No caso da apiDocuments, recebe o evento = "view" da apiSupplyDocuments.

Os eventos "list" e "view" também direcionam para qual título será apresentado na página. Se for "view", na página de consulta será mostrado o título "Consulta de Anexo de Documentos" e se for "list", na página de manutenção da ordem de compra será mostrado "Anexo de Documentos".

RowErrors Temp-table OUTPUT Informações sobre os erros ocorridos durante o processo de busca do metadados.

Retorno

Retorna informações do metadados ou erros ocorridos durante a busca.

pi-query-v1

Requisito

Nenhum.

Descrição

Executa a consulta dos anexos no banco de dados conforme o tipo de processo e a chave do documento enviada, e retorna a lista de anexos relacionados a um documento.

Parâmetros

Tipo

Input/Output

Descrição

oInput

JsonObject

INPUT

Parâmetros para a busca de anexos:

queryParams:

processType: tipo do processo vinculado ao documento. Os tipos devem ser cadastrados na include de view-as uninc\i01un403.i (HUB).
processKey: Código da chave do processo, identifica o processo ao qual o anexo pertence. A chave pode ou não ser composta. Caso seja, será separada por pipe "|" e deve ser enviada no formato encode. No exemplo abaixo, a chave "1234%7CABC" está no formato encode e corresponde a chave composta: "1234|ABC".

Exemplo

{
   "queryParams": {
       "processType": "1",
       "processKey": "1234%7CABC"
  }
}

Outros parâmetros que podem ser usados em conjunto com os queryParams de consulta dos anexos:

search: pesquisa por campos. Os parâmetros são os mesmos utilizados na queryParams de busca, sendo apenas adicionando o "search" na requisição juntamente com o critério de filtro que pode ser: nome do anexo, descrição do anexo ou usuário criador. No exemplo abaixo está sendo solicitada uma consulta utilizando um filtro para mostrar apenas os documentos anexados pelo usuário "super".

Exemplo

{
   "queryParams": {
       "processType": "1",
       "processKey": "1234%7CABC",
       "search":"super"
  }
}

order: Ordenação dos campos, podendo ser ascendente ou descendente ("-" sinal negativo).
- Exemplo:
  - ordem por data ascendente: order=-createDatetime.
  - ordem por data descendente: order=-createDatetime.

pageSize: Tamanho da página (número de registros retornados). Se não informado será considerado: 10.

aResult

JsonArray

OUTPUT

Retorno do processo, contendo os itens da listagem de anexos conforme parâmetros enviados.

Exemplo

{
    "total": 3,
    "totalHits": 3,
    "hasNext": false,
    "items": [
        {
            "creationUserName": "Super",
            "documentDir":"c:\\tmp\\ERP\\1\\123\\5\\c3e349d230b2d176eefb7d58f2eb35e1.txt",
            "creationUser": "super",
            "documentDescription": "arquivo 123",
            "processKey": "123|5",
            "documentId": 392,
            "processType": 1,
            "documentName": "arquivo123.txt",
            "documentSize": "74 Bytes",
            "processTypeDescription": "Ordem de Compra",
            "creationDatetime": "2022-02-07T09:12:43.000"
        },
        {
            "creationUserName": "Super",
            "documentDir":"c:\\tmp\\ERP\\1\\123\\5\\e13190f35f57fcb02bcf91c799ed3191.txt",
            "creationUser": "SUPER",
            "documentDescription": "teste download",
            "processKey": "123|5",
            "documentId": 393,
            "processType": 1,
            "documentName": "testando.txt",
            "documentSize": "1GB",
            "processTypeDescription": "Ordem de Compra",
            "creationDatetime": "2022-02-07T18:01:17.000"
        },
        {
            "creationUserName": "Super",
            "documentDir":"c:\\tmp\\ERP\\2\\1234\\5\\2ca28ec306fb5e55c24448f2bdb1baa3",
            "creationUser": "SUPER",
            "documentDescription": "teste download",
            "processKey": "123|5",
            "documentId": 396,
            "processType": 1,
            "documentName": "testando.txt",
            "documentSize": "1GB",
            "processTypeDescription": "Ordem de Compra",
            "creationDatetime": "2022-02-07T18:08:29.000"
        }
    ]
}

Para verificar o que significa cada campo, conferir no final desta documentação a descrição dos campos da temp-table: ttDocumentFile.

lHasNext Logical OUTPUT Indica que existem mais registros a serem mostrados.

iTotalHits Integer OUTPUT Contagem do total de registros encontrados.

RowErrors Temp-table OUTPUT Informações sobre os erros ocorridos durante o processo.

Retorno

Retorna a lista de arquivos relacionados a um documento ou erros ocorridos durante a busca.

pi-upload-v1

Requisito

Nenhum.

Descrição

Faz o upload do arquivo na criação de um novo anexo, retornando as informações do arquivo que está sendo feito o upload.

Parâmetros

Tipo

Input/Output

Descrição

oInput

JsonObject

INPUT

Parâmetros para o upload:

pathParams: Informar: upload.

queryParams → files=: Arquivo a ser efetuado o upload, sendo enviado também como parâmetro.

Exemplo abaixo do formato de requisição com arquivo enviado como parâmetro:

Exemplo

{
  "content-type": "multipart/form-data",
   "multipart": [
       {
    "headers": {
    "Content-Disposition": "form-data; name=\"file\"; filename=\"Adobe Sign Form Field.pdf\""
       },
    "body": {
    "content-type": "application/pdf",
    "content": "@{base64(body('Get_file_content_Signed_PDF'))}"
    }
      }
   ]
}

oOutput

JsonObject

OUTPUT

Informações do arquivo:

Exemplo

{
"fileName": "Evidencia_DMANSUPIMPA2-419.docx",
"content": "UEsDBBQABgAIAAAAIQCJi8MJ4gEAAF4KAAATAAgCW0NvbnRlbnRfVHlwZXN..."
}

Descrição dos campos:

fileName: Nome do arquivo que está sendo efetuado upload, seguido pela extensão.
content: Conteúdo presente no arquivo, convertido para base64.

RowErrors Temp-table OUTPUT Informações sobre os erros ocorridos durante o processo de upload.

Retorno

Retorna informações do nome do arquivo e seu conteúdo em base64 ou erros ocorridos durante o processo.

pi-download-v1

Requisito

Nenhum.

Descrição

Faz o download do arquivo, retornando as informações do nome e conteúdo do anexo.

Parâmetros

Tipo

Input/Output

Descrição

oInput

JsonObject

INPUT

Parâmetros para download do anexo:

pathParams: Informar: download e o documentId do documento.

Exemplo

{
    "pathParams": [
    "download",
    "402"
  ],
}

oOutput

JsonObject

OUTPUT

Retorno das informações do arquivo que está sendo realizado o download:

Exemplo

{
    "headers": {
        "Content-Type": "application/octet-stream"
    },
    "payload": {
        "file": {
            "FN_File": "Evidencia_COD_DMANSUPIMPA2-605.docx",
            "DN_File": "UEsDBBQABgAIAAAAIQBkdsOlw57DhwEAAMOKCQAAEwAIAltD..."
        }
    }
}

Descrição dos campos:

File : contém as informações do anexo
- FN_File: Nome do arquivo com extensão, vindo da tabela arquivo_docto.
- DN_File: Conteúdo do arquivo em base64.

RowErrors Temp-table OUTPUT Informações sobre os erros ocorridos durante o processo de download.

Retorno

Retorna informações de nome e conteúdo do anexo que está sendo feito download ou erros ocorridos durante o processo.

pi-delete-v1

Requisito

Nenhum.

Descrição

Efetua a exclusão de um único anexo ou de vários anexos dependendo do tipo de requisição recebida. Neste método os arquivos de anexos são excluídos do banco de dados e também da pasta física no servidor de arquivos onde estão gravados.

Parâmetros

Tipo

Input/Output

Descrição

oInput

JsonObject

INPUT

Parâmetros para eliminação de anexo individual:

pathParams: Informar: o documentId do anexo.

Exemplo

{
    "pathParams": [
       "1234"
    ],
}

Parâmetros para eliminação de anexo em lote:

Payload: Informar a relação dos documentId's a serem eliminados:

Exemplo

[
   {"documentId": 552,
   {"documentId": 553},
   {"documentId": 554}
]

oOutput

JsonObject

OUTPUT

Informações da exclusão:

Não há retorno direto via Output nesse método. Em caso de sucesso na exclusão individual ou lote, será retornado vazio.

RowErrors Temp-table OUTPUT Relação dos erros ocorridos durante o processo de exclusão individual ou em lote.

ListaIdsExcluidos Character OUTPUT Relação dos documentIds que foram eliminados com sucesso.

Retorno Erros ocorridos durante a exclusão individual ou em lote e relação dos documentIds que foram excluídos com sucesso.

pi-create-v1

Requisito

Nenhum.

Descrição

Efetua a inclusão de um registro com as informações de anexo no banco de dados e também grava no servidor o arquivo físico enviado.

Retorna informações sobre o anexo criado.

Parâmetros

Tipo

Input/Output

Descrição

oInput

JsonObject

INPUT

Parâmetros para criação:

Payload:

Exemplo

{
         "processType":1,
         "processKey":"12345|10",
         "documentName":"testeArquivo.txt",
         "documentDescription":"teste de arquivo",
         "documentFile": "JC9CVVNJTkVTU0hVQi9Gb250ZXNfRG9jL1N1c3RlbnRhY2FvL1YxMS9WMTEv..."
}

Descrição dos campos do payload:

processType: Tipo do processo ao qual o documento está vinculado.
processKey: Código da chave do processo podendo ser composta (separado por pipes).
documentName : Nome do arquivo.
documentDescription: Descrição do Documento.
documentFile: Conteúdo do arquivo, convertido para base64.

oOutput

JsonObject

OUTPUT

Informações do anexo criado:

Exemplo

{
    "items": [
        {
            "creationUserName": "Super",
            "documentDir": "\\\\moitas\\tmp\\ERP\\1\\12345\\10\\3c3bbcd88a4f01fb34fb63ae7f845f6c.txt",
            "creationUser": "super",
            "documentDescription": "teste de arquivo",
            "processKey": "12345|10",
            "documentId": 725,
            "processType": 1,
            "documentName": "testeArquivo.txt",
            "documentSize": "74 Bytes",
            "processTypeDescription": "Ordem de Compra",
            "creationDatetime": "2022-03-29T10:59:46.376"
        }
    ]
}

Para verificar o que significa cada campo conferir no final desta documentação o detalhamento dos campos da temp-table : ttDocumentFile .

RowErrors Temp-table OUTPUT Informações sobre os erros ocorridos durante a criação de arquivo.

Retorno

Informações do anexo criado ou erros ocorridos durante o processo.

pi-busca-lista-tipos-processos
Requisito	Nenhum.
Descrição	Busca os tipos de processos cadastrados na include uninc/i01un403.i.
	Parâmetros	Tipo	Input/Output	Descrição
	pListaProcessos	Character	INPUT	Lista dos processos existentes na include.
Retorno	Listagem dos tipos de processos existentes.

Tabelas

Arquivo_docto
Informações dos Arquivos
Atributo	Tipo	Formato	Descrição	Obrigatório
num_id_docto	INTEGER	999999999	Número sequencial de identificação do documento	Sim
cdn_tipo_proces	INTEGER	>>9	Tipo do processo ao qual o documento está vinculado	Sim
cod_chave_proces	CHARACTER	X(40)	Código da chave do processo	Sim
cod_usuar_docto	CHARACTER	X(12)	Código do usuário do documento	Sim
dtm_criac_docto	DATETIME	99/99/9999 HH:MM:SS.SSS	Data e hora da criação do documento	Sim
nom_arq_docto	CHARACTER	X(100)	Nome do arquivo	Sim
nom_dir_docto	CHARACTER	X(250)	Diretório onde está armazenado o documento	Sim
ind_tam_docto	CHARACTER	X(10)	Tamanho do arquivo	Não
des_docto	CHARACTER	X(200)	Descrição do Documento	Não

Sequencia

seq_arq_docto

Incrementa o ID do campo num_id_docto

Tabelas Temporárias

RowErrors					Entrada/Saída
Erros ocorridos durante a execução do programa.					Saída
Atributo	Tipo	Formato	Descrição	Obrigatório	Evolução
ErrorSequence	INTEGER		Sequência	Sim
ErrorNumber	INTEGER		Número	Sim
ErrorDescription	CHARACTER		Descrição	Não
ErrorParameters	CHARACTER		Parãmetros	Não
ErrorType	CHARACTER		Tipo de erro	Não
ErrorHelp	CHARACTER		Texto de ajuda	Não
ErrorSubType	CHARACTER		Sub-tipo do erro	Não

RowErrorsAux					Entrada/Saída
Erros ocorridos durante a execução da exclusão em lote, filtra os erros ocorridos na execução da BO , retirando os do tipo INTERNAL que não devem ser passados à RowErrors.
Atributo	Tipo	Formato	Descrição	Obrigatório	Evolução
ErrorSequence	INTEGER		Sequência	Sim
ErrorNumber	INTEGER		Número	Sim
ErrorDescription	CHARACTER		Descrição	Não
ErrorParameters	CHARACTER		Parãmetros	Não
ErrorType	CHARACTER		Tipo de erro	Não
ErrorHelp	CHARACTER		Texto de ajuda	Não
ErrorSubType	CHARACTER		Sub-tipo do erro	Não

ttDocumentFile					Entrada/Saída
Temp-table com os campos a serem retornados na busca dos documentos do processo.					Saída
Atributo	Nome no Objeto	Tipo	Descrição	Obrigatório	Evolução
num_id_docto	documentId	INTEGER	Número do ID do documento	Sim
cdn_tipo_processo	processType	INTEGER	Número do tipo do processo	Sim
desc_tipo_proces	processTypeDescription	CHARACTER	Descrição do tipo do processo	Sim
cod_chave_proces	processKey	CHARACTER	Código da chave do processo	Sim
cod_usuar_docto	creationUser	CHARACTER	Código do usuário criador	Sim
nom_usuar_docto	creationUserName	CHARACTER	Nome do usuário criador	Sim
dtm_criac_docto	creationDatetime	DATETIME	Data e hora da criação	Sim
nom_arq_docto	documentName	CHARACTER	Nome do documento	Sim
nom_dir_docto	documentDir	CHARACTER	Caminho do diretório do documento	Sim
ind_tam_docto	documentSize	CHARACTER	Tamanho do documento	Não
des_docto	documentDescription	CHARACTER	Descrição do documento	Não

ttArquivoDocto
Informações dos Arquivos
Atributo	Tipo	Formato	Descrição	Obrigatório
num_id_docto	INTEGER	999999999	Número sequencial de identificação do documento	Sim
cdn_tipo_proces	INTEGER	>>9	Tipo do processo ao qual o documento está vinculado	Sim
cod_chave_proces	CHARACTER	X(40)	Código da chave do processo	Sim
cod_usuar_docto	CHARACTER	X(12)	Código do usuário do documento	Sim
dtm_criac_docto	DATETIME	99/99/9999 HH:MM:SS.SSS	Data e hora da criação do documento	Sim
nom_arq_docto	CHARACTER	X(100)	Nome do arquivo	Sim
nom_dir_docto	CHARACTER	X(250)	Diretório onde está armazenado o documento	Sim
ind_tam_docto	CHARACTER	X(10)	Tamanho do arquivo	Não
des_docto	CHARACTER	X(200)	Descrição do Documento	Não
r-rowid	ROWID		Rowid do registro	Não

Árvore de páginas

APIDocuments - Informação dos Documentos (Anexos)

Manipulação das informações dos anexos

Método Negócio

Tabelas

Tabelas Temporárias