Pular para o conteúdo principal
Versão: 2.2.1

Questões gerais

Questões gerais​

Integração de portais e/ou sistemas legados para inicialização de Workflow dentro do SoftExpert Suite.​

  • A integração pode ser feita utilizando os Web Services do SoftExpert Suite. Os Web Services do SoftExpert Suite estão detalhados no capítulo Integração via web services.
info
Observação

Demais ações dentro do componente Workflow também estão liberadas a partir da utilização do Web Service SOAP, como execução de atividades, preenchimento de atributos e campos de formulário, upload de anexos, etc. (Documentação on-line dos Web Services https://<domínio>/se/ws/wf_ws.php).

Uso de ferramentas de Dataviz para visualização de origem do SoftExpert Suite.​

  • Para isto recomendamos o uso da API do Conjunto de Dados que possibilita montar as consultas desejadas. O dicionário de dados do nosso produto está disponibilizado on-line no componente SE Configuração, por meio do menu SE Configuração -> Ferramenta -> Editor SQL -> Botão "Documentação".

Integração de sistemas externos de clientes, para cadastro e inclusão de dados diversos no SoftExpert Suite.​

  • Para este tipo de demanda temos disponível modelos de interfaces e os próprios Web Services ou APIs, ambos estão detalhados em Referência.

Ler dados de bancos de dados externos, para serem utilizados dentro do SoftExpert Suite.​

  • Para isto temos a opção do recurso de atributos externos dentro da aplicação. Os detalhes de como configurar os atributos externos estão no manual/help do componente SoftExpert Administração.
  • E, se tratando dos componentes baseados no SoftExpert Processo, temos a opção de configuração de aplicações externas onde pode-se testar uma informação externa, retornar algum tipo de dados, etc., seja via o conceito de Web Service, API ou mesmo uma aplicação personalizada (mediante customização).
info
Observação

O mesmo conceito pode ser utilizado para carregar dados de lista de campos de formulário. Nesse caso não há opção da conexão direta como o atributo externo, poderá ser utilizado o conjunto de dados.

A partir do SoftExpert Suite, gravar informações em sistemas externos.​

  • Para isto é possível Web Services ou APIs (se o sistema externo possuir), exportar para arquivos de dados (TXT, CSV), para importação pelo sistema externo ou senão realizar as gravações diretamente no banco de dados do sistema externo.
  • E, se tratando dos componentes baseados no SoftExpert Processo, temos a opção de configuração de aplicações externas onde pode-se configurar os clients de Web Service nativamente (salvo particularidades de autenticação e arquitetura que no caso teria que ser implementado o client específico).

Integração quando Hosting.​

  • A restrição fica por conta exclusivamente da infraestrutura disponibilizada para os ferramentais a serem utilizados. Por exemplo, se a conexão for direta entre os bancos de dados, estes devem possibilitar um DBLINK ou estarem numa mesma rede (VPN Dedicada). Se a necessidade for de transferência de arquivos, os fileservers devem estar disponíveis na nuvem, e assim por diante.
  • A orientação e arquitetura indicada nestes casos é o uso de APIs ou Web Services.

Integrações possíveis de serem feitas com ERP SAP.​

  • Pode ser efetivada por qualquer ferramental do SAP (ABAP, XI, RFC, etc.), sendo estas dependentes mais do contrato que o cliente possui. No entanto o direcionamento é que as implementações de rotinas diretamente no SAP são feitas geralmente pela equipe de TI do cliente ou de consultores SAP.
info

O mesmo entendimento pode ser aplicado a qualquer outro ERP, ou seja, a equipe SoftExpert precisa mapear qual o método de disponibilização de dados pelo ERP em questão. A partir disso é direcionado aos métodos supracitados.

Questões gerais sobre o uso de Integrações​

Qual tipo de licença é mais adequado para chamadas de API?​

O tipo da licença varia de acordo com a necessidade. Por exemplo, caso um usuário de uma licença STAFF seja utilizado como usuário de Web Service, ele não conseguirá cadastrar novos usuários pelo serviço adm_ws, já que esta é uma funcionalidade que exige uma licença mais permissiva.

Consigo consumir uma API utilizando um usuário que esteja logado?​

Sim, desde que a licença permita.

Qual a real diferença entre uma sessão de usuário "normal" e de uma API?​

A principal distinção entre uma sessão de usuário "normal" e uma de API reside na maneira como ambas consomem licenças e gerenciam suas respectivas sessões. Em ambos os casos, uma licença é consumida. Entretanto, quando um web service é chamado, este não registra sua sessão na tabela de sessões. Isto implica que um acesso por meio do /apigateway não entra em conflito com outras chamadas de web service ou API para o mesmo usuário, uma vez que nenhuma delas vai registrar uma sessão ativa.

No entanto, um cenário a ser considerado ocorre quando há apenas uma licença para usuário simultâneo e já existe um usuário logado no SoftExpert Suite visualizando um portal, por exemplo. Nessa situação, as chamadas de Web Service vão retornar um erro 403. Isso ocorre porque existe um usuário que já está consumindo a única sessão disponível de fato.

Portanto, enquanto as sessões de usuários "normais" e de API podem parecer semelhantes à primeira vista, elas têm características de gestão de licenças e sessões distintas, que devem ser levadas em conta ao projetar e implementar soluções que utilizam esses recursos.

Levando em conta estes cenários, o que é sugerido?

  1. Cadastrar um usuário específico para consumo das APIs e Web Services SOAP.
  2. Deixar apenas uma licença para este usuário. Isso é necessário, pois nos casos de chamadas externas (cuja licença não é informada), o SoftExpert Suite vai pegar a primeira que encontrar.
  3. Utilizar uma licença permissiva, de acordo com as necessidades (se deseja iniciar workflows via web service, o tipo da licença deve comportar tal funcionalidade)

Os logs das requisições enviadas para o SoftExpert Suite ficam armazenados no SoftExpert Suite?​

Os registros das requisições enviadas para o SoftExpert Suite são armazenados dentro do próprio sistema. Estes podem ser acessados por meio dos Widgets disponíveis nos elementos do componente SoftExpert Administração, os quais podem ser utilizados durante a criação de um portal. Alternativamente, esses registros também podem ser consultados através da importação de um portal personalizado do sistema.

Desta forma, tanto os administradores quanto os usuários têm a capacidade de monitorar e analisar as solicitações feitas para o SoftExpert Suite, facilitando o rastreamento de atividades e a solução de problemas potenciais.

O que preciso saber sobre as mensagens de erro da API?​

Salvo indicação em contrário, a maioria dos endpoints da SoftExpert Suite retorna uma resposta 200 OK para indicar uma operação bem-sucedida. Caso uma API ou Web Service retorne um código de status diferente, as informações específicas sobre a resposta serão detalhadas em sua respectiva documentação.

A SoftExpert Suite também possui várias respostas de erro padrão que são comuns a diversas APIs:

  • 401 Unauthorized: Esta resposta é retornada quando a autenticação fornecida é inválida. Para detalhes sobre como autenticar corretamente as solicitações de API, consulte nossa seção de autenticação e segurança.
  • 403 Forbidden: Este código é retornado quando a autenticação fornecida não detém as permissões necessárias para acessar a URL específica.
  • 429 Too Many Requests: Esta resposta é retornada quando a sua conta ou aplicativo excede os limites de taxa da API. Oferecemos sugestões sobre como operar dentro desses limites em nossa documentação.

Porque estou recebendo a mensagem Valid GatewayJWT not found in the request or user is blocked!?​

Essa mensagem geralmente é exibida quando ocorre um erro 401. Na maioria dos casos, isso indica que a API Key necessária para autenticar a solicitação não foi incluída no cabeçalho dela. É crucial garantir que a API Key esteja corretamente incorporada no cabeçalho de todas as solicitações que você envia para evitar esse erro.

Alternativamente, essa mensagem também pode surgir se o usuário usado para a integração estiver bloqueado. Nesse caso, seria necessário verificar o status do usuário e tomar as medidas necessárias para desbloqueá-lo, se for o caso.

Caso continue recebendo essa mensagem após verificar esses dois aspectos, sugerimos que você entre em contato com o suporte técnico para obter assistência adicional.

É possível usar Bearer Tokens em nossas definições de fonte de dados REST? Se sim, como podemos configurá-lo?​

Atualmente, a opção de autenticação Bearer Token não está disponível nos tipos de autenticação suportados pelo menu Fonte de dados REST (AD052). No entanto, é possível contornar essa limitação adicionando um cabeçalho personalizado para atender a esse requisito na tela de configuração dos parâmetros de entrada, selecionando o tipo de parâmetro como HEADER. Para realizar essa configuração, crie o cabeçalho da seguinte maneira:

Bearer <Sua chave de API>

Caso o token seja dinâmico, será preciso utilizar os recursos dos componentes de BPM para passar o token para esse parâmetro de maneira dinâmica. Para obter informações mais detalhadas, recomendamos que entre em contato com seu executivo de conta para uma consultoria personalizada.

Para saber como configurar uma Fonte de dados REST, consulte Configurar uma Fonte de dados REST

API do conjunto de dados​

Consigo utilizar a API do conjunto de dados no serviço online do Power BI?​

Sim, é possível utilizar a API do Conjunto de Dados do SoftExpert Suite como Fonte de Dados no Power BI Online. Porém, é importante lembrar que, para clientes que possuem ambientes On-Premises do SoftExpert Suite e que estão em redes privadas, é necessário garantir o acesso ao Serviço do Power BI Online para que o funcionamento seja adequado. Recomendamos nesses casos consultar sua equipe de Infraestrutura responsável pela sustentação do SoftExpert Suite ou a própria documentação do Power BI.

É possível realizar paginação na API do Conjunto de Dados?​

No momento, a API do Conjunto de Dados não suporta paginação. Isso significa que só é possível obter os primeiros 10.000 (dez mil) registros como objetos. Se o cliente precisar recuperar mais registros, ele precisará criar uma lógica em seu Script SQL para obter o número total de registros retornados na tela de consulta ou cadastro do Conjunto de Dados.

info
Observação:

Nem todas as APIs suportam a paginação. Quando isso acontece, pode ser necessário criar lógicas alternativas no lado do cliente para manipular grandes conjuntos de dados, como dividir a consulta em pedaços menores ou obter o número total de registros para permitir a exibição de resultados em etapas.

Interface de banco de dados​

Como posso solucionar o erro 404 “NoSuchKey” na descrição do erro na tela Configuração > Ferramenta > Importação: Acompanhamento (CM015)?​

Se você se deparou com o erro 404 "NoSuchKey" durante uma importação de dados, não se preocupe - há uma solução. Este erro indica que o objeto solicitado não foi encontrado no SFTP (bucket S3) durante o processo de importação.

O que isso significa? O erro "NoSuchKey" ocorre quando o sistema não consegue encontrar o objeto necessário para a importação de dados. Isso pode acontecer por diversos motivos, incluindo problemas de configuração ou arquivos ausentes.

Como resolver: Siga estas etapas para corrigir o problema:

  1. Verifique a presença do arquivo eletrônico: Certifique-se de que o arquivo eletrônico necessário foi criado e está disponível no SFTP fornecido pela SoftExpert.
  2. Confirme o SFTP correto: Verifique se os arquivos eletrônicos estão no SFTP correto para cada ambiente contratado. Cada ambiente possui seu próprio SFTP.
  3. Corrija a referência ao arquivo eletrônico: Certifique-se de que a referência ao arquivo eletrônico está correta na configuração da importação de dados do modelo que está sendo utilizado.

Se você precisar de mais orientações, recomendamos a leitura do nosso documento de diretrizes sobre o uso do Armazenamento de arquivos para integração (Amazon S3).

Precisa de ajuda adicional? Se o problema persistir ou se você tiver dúvidas, entre em contato com nosso suporte técnico para assistência adicional.

Descrição técnica do erro:

{
  "error": "Internal Server Error",
  "exception": "com.amazonaws.services.s3.model.AmazonS3Exception",
  "message": "The specified key does not exist. (Service: Amazon S3; Status Code: 404; Error Code: NoSuchKey; Request ID: <Request ID>; S3 Extended Request ID: <S3 Extended Request ID>)",
  "status": 500,
  "time": 1707745683813
}