SmartLink Adapter

TOTVS iPaaS + SmartLink 

A estratégia Behavior Sharing utilizada pelo SmartLink é uma tecnologia de comunicação entre os produtos TOTVS Apps e os produtos On-Premises, ou Clouds privadas. Os componentes SmartLink no TOTVS iPaaS surgem da necessidade de facilitar as integrações que carecem iniciar a partir de um gatilho nos

produtos On-Premises, ou até mesmo, enviá-los informações acerca da integração sem a necessidade de mais liberações além das requisitadas pelo SmartLink. Neste guia explicaremos os pré-requisitos para sua utilização e algumas configurações para o uso. 

Pré-requisitos

Para a utilização do SmartLink são necessários alguns pré-requisitos listados abaixo:

• RAC configurado: para validar se o TOTVS RAC da empresa está configurado, execute a requisição correspondente no Apêndice A. Caso o valor retornado no campo tenantId tenha retornado uma chave UUID, seu Tenant está configurado no TOTVS RAC, caso contrário, contate o responsável TOTVS pela sua conta.
  
  
• Setup SmartLink: para o envio de informações como componente TOTVS iPaaS SmartLink Sender é necessário que a fila do seu Tenant já esteja configurada no SmartLink. A falta desta não gerará erros no iPaaS, contudo, a mensagem enviada se perderá. A configuração pode ser validada em: https://smartlink.totvs.app/queues ou ambientes staging ou dev. Em casos onde hajam filas semelhante a imagem abaixo, seu ambiente está configurado. 

Utilização no TOTVS iPaaS

Como mencionado anteriormente, existem dois componentes SmartLink no TOTVS iPaaS, sendo eles:

• SmartLink Hook
• SmartLink Sender

SmartLink Hook

O SmartLink Hook é um componente de início do TOTVS iPaaS, ou seja, a partir dele as integrações podem ser iniciadas. Este componente será ativado para toda mensagem recebida no tenant via SmartLink e que corresponda aos filtros de cabeçalho informados em sua configuração, sendo o filtro por tenant

já é colocado por padrão, não sendo necessário informá-lo.

Adicionando o componente no builder

Siga os passos abaixo para adicionar o componente no builder:

01. Com o builder aberto, clique no ícone  e clique no componente SmartLink Hook;

02. Clique em Selecionar para incluir o componente do builder;

03. Passe o mouse sobre o componente e clique no ícone ;

04. Realize a configuração que mais adequada seguindo as opções abaixo.

Configuração

Todos os campos para a configuração do componente SmartLink Hook são opcionais, porém torna-se recomendável a informação de pelo menos um deles. Sendo uma das opções abaixo:

• Tipo: parâmetro que é passado com a chave type no cabeçalho, geralmente o equivalente à subscrição;
• Audiência: parâmetro que é passado com a chave audience no cabeçalho;
• Demais filtros de cabeçalho: possível adicionar outros filtros conforme a necessidade, tendo como parâmetro o cabeçalho a ser filtrado (chave) e seu respectivo valor recebido.

Simular recebimento no serviço On-Premises

Para simular o envio de uma aplicação On-Premises para o SmartLink é possível utilizar os endpoints indicados no Apêndice D e Apêndice E.

Utilização dos dados de entrada

Ao receber uma mensagem de gatilho para o diagrama, é possível resgatar o conteúdo tanto do corpo da mensagem quanto do cabeçalho. Ambos, são equivalentes respectivamente ao payload e headers/properties do message broker.

SmartLink Sender

O SmartLink Sender é um componente do TOTVS iPaaS onde é possível utilizá-lo como um dos processos do seu diagrama. Este componente serve para enviar mensagens ao message broker da plataforma TOTVS Apps, consequentemente, ao elemento Behavior Sharing do SmartLink, que possibilitará o

recebimento nos serviços On-Premises.

Este componente é assíncrono, portanto, depois de enviada a mensagem para a plataforma, não há nenhuma saída para o mesmo.

Configuração

A configuração do componente SmartLink Sender possui os seguintes campos baseados em sua maioria na documentação Opens in new window or tab:

• Nome: nome do componente que será exibido na rastreabilidade do TOTVS iPaaS;
• Tipo da subscrição (opcional): cabeçalho type da documentação acima mencionada, pode ser consultada na aba subscrições da fila que deverá receber a mensagem conforme imagem abaixo:

• Formato do evento: formato conforme a RFC da documentação acima mencionada, podendo ser CloudEvents ou TOTVS Message por convenção;
• Corpo: texto livre que irá trafegar no corpo da mensagem. Deve-se atentar ao formato de evento escolhido para que o corpo da mensagem trafegue conforme a documentação orienta (JSON, XML, plain text, etc).

As configurações são diferentes dependendo da escolha do formato do evento, porém, todas são opcionais e estão documentadas na RFC000011 (Opens in new window or tab).

Simular envio ao serviço On-Premises

Para simular o envio do TOTVS iPaaS para uma aplicação On-Premises, após executar um diagrama com o componente SmartLink Sender, é possível utilizar o endpoint correspondente no Apêndice F para recuperar o conteúdo da primeira mensagem na fila que está indo para aplicação On-Premises, e na

sequência, utilizar o endpoint correspondente no Apêndice G para removê-la da fila (ack).

É possível também através do monitor SmartLink verificar quantas mensagens chegaram para a fila do seu Tenant.

Apêndices

Apêndice A - Validar RAC no Tenant:

Utilize o token de usuário do Accounts onde lê-se {USER_TOKEN}.

curl --location 'https://rac.dev.totvs.app/totvs.rac/api/v1/fluigIdentity/authorization/roles' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {USER_TOKEN}' \
--data '[]

curl --location 'https://rac.staging.totvs.app/totvs.rac/api/v1/fluigIdentity/authorization/roles' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {USER_TOKEN}' \
--data '[]

curl --location 'https://rac.totvs.app/totvs.rac/api/v1/fluigIdentity/authorization/roles' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {USER_TOKEN}' \
--data '[]

Apêndice B - Gerar Token RAC

As variáveis CLIENT_ID e CLIENT_SECRET são enviadas ao email administrador do Tenant no momento de sua criação.

curl --location 'https://totvs.rac.dev.totvs.app/totvs.rac/connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id={CLIENT_ID}' \
--data-urlencode 'client_secret={CLIENT_SECRET}' \
--data-urlencode 'scope=authorization_api'

curl --location 'https://totvs.rac.staging.totvs.app/totvs.rac/connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id={CLIENT_ID}' \
--data-urlencode 'client_secret={CLIENT_SECRET}' \
--data-urlencode 'scope=authorization_api'

curl --location 'https://totvs.rac.totvs.app/totvs.rac/connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id={CLIENT_ID}' \
--data-urlencode 'client_secret={CLIENT_SECRET}' \
--data-urlencode 'scope=authorization_api'

Apêndice C - Configurar Fila para o Tenant SmartLink

As variáveis a serem substituídas são:

• TOKEN_RAC = Token RAC obtido conforme Apêndice B;
• SUBSCRIPTION_TYPE = Texto de tamanho livre sem caracteres especiais representando o tipo de subscrição, utilizado muitas vezes para filtros;
• RAC_TENANT_ID = Tenant do RAC obtido no Apêndice A;
• PRODUCT_NAME = Texto de tamanho livre contendo o nome do produto responsável pela mensagem (pode ser tanto iPaaS quanto o produto on-premises);
• REQUEUE_COUNT = Quantidade máxima de reinfileiramento da mensagem antes de ir para a deadletter.

curl --location 'https://api-smartlink.dev.totvs.app/api/v1/link/setup' \
--header 'accept: application/json' \
--header 'Authorization: Bearer {TOKEN_RAC}' \
--header 'Content-Type: application/json' \
--data '{
  "subscriptions": ["{SUBSCRIPTION_TYPE}"],
  "tenants": ["{RAC_TENANT_ID}"],
  "productName": "{PRODUCT_NAME}",
  "requeueCountMax": {REQUEUE_COUNT}
}'

curl --location 'https://api-smartlink.staging.totvs.app/api/v1/link/setup' \
--header 'accept: application/json' \
--header 'Authorization: Bearer {TOKEN_RAC}' \
--header 'Content-Type: application/json' \
--data '{
  "subscriptions": ["{SUBSCRIPTION_TYPE}"],
  "tenants": ["{RAC_TENANT_ID}"],
  "productName": "{PRODUCT_NAME}",
  "requeueCountMax": {REQUEUE_COUNT}
}'

curl --location 'https://api-smartlink.totvs.app/api/v1/link/setup' \
--header 'accept: application/json' \
--header 'Authorization: Bearer {TOKEN_RAC}' \
--header 'Content-Type: application/json' \
--data '{
  "subscriptions": ["{SUBSCRIPTION_TYPE}"],
  "tenants": ["{RAC_TENANT_ID}"],
  "productName": "{PRODUCT_NAME}",
  "requeueCountMax": {REQUEUE_COUNT}
}'

Apêndice D - Enviando para o iPaaS sem Audiência

As variáveis a serem substituídas são:

• TOKEN_RAC: Token RAC obtido conforme Apêndice B;
• TYPE: Tipo da mensagem, equivalente a subscrição (algo que identifique a natureza da mensagem), este campo deve equivaler ao informado no campo "Tipo" filtrado pelo iPaaS caso seja informado;
• É também possível informar o conteúdo da mensagem dentro do json do campo "data".

curl --location 'https://api-smartlink.dev.totvs.app/api/v1/link/send/{TYPE}' \
--header 'accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {TOKEN_RAC}' \
--data '{}'

curl --location 'https://api-smartlink.staging.totvs.app/api/v1/link/send/{TYPE}' \
--header 'accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {TOKEN_RAC}' \
--data '{}'

curl --location 'https://api-smartlink.totvs.app/api/v1/link/send/{TYPE}' \
--header 'accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {TOKEN_RAC}' \
--data '{}'

Apêndice E - Enviando para o iPaaS com Audiência

As variáveis a serem substituídas são:

• TOKEN_RAC: Token RAC obtido conforme Apêndice B;
• TYPE: Tipo da mensagem, equivalente a subscrição (algo que identifique a natureza da mensagem), este campo deve equivaler ao informado no campo "Tipo" filtrado pelo iPaaS caso seja informado;
• AUDIENCE: Audiência da mensagem, este campo deve equivaler ao informado no campo "Audiência" filtrado pelo iPaaS caso seja informado;
• É também possível informar o conteúdo da mensagem dentro do json do campo "data".

curl --location 'https://api-smartlink.dev.totvs.app/api/v1/link/send/{TYPE}/{AUDIENCE}' \
--header 'accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {TOKEN_RAC}' \
--data '{}'

curl --location 'https://api-smartlink.staging.totvs.app/api/v1/link/send/{TYPE}/{AUDIENCE}' \
--header 'accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {TOKEN_RAC}' \
--data '{}'

curl --location 'https://api-smartlink.totvs.app/api/v1/link/send/{TYPE}/{AUDIENCE}' \
--header 'accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {TOKEN_RAC}' \
--data '{}'

Apêndice G - Buscar Conteúdo da Primeira Mensagem da Fila

As variáveis a serem substituídas são:

• TOKEN_RAC: Token RAC obtido conforme Apêndice B;

curl --location 'https://api-smartlink.dev.totvs.app/api/v1/link/get' \
--header 'accept: application/json' \
--header 'Authorization: Bearer {TOKEN_RAC}'

curl --location 'https://api-smartlink.staging.totvs.app/api/v1/link/get' \
--header 'accept: application/json' \
--header 'Authorization: Bearer {TOKEN_RAC}'

curl --location 'https://api-smartlink.totvs.app/api/v1/link/get' \
--header 'accept: application/json' \
--header 'Authorization: Bearer {TOKEN_RAC}'

Apêndice H - ACK na Primeira Mensagem da Fila

As variáveis a serem substituídas são:

• TOKEN_RAC: Token RAC obtido conforme Apêndice B;

curl --location --request POST 'https://api-smartlink.dev.totvs.app/api/v1/link/ack' \
--header 'accept: application/json' \
--header 'Authorization: Bearer {TOKEN_RAC}'

curl --location --request POST 'https://api-smartlink.staging.totvs.app/api/v1/link/ack' \
--header 'accept: application/json' \
--header 'Authorization: Bearer {TOKEN_RAC}'

curl --location --request POST 'https://api-smartlink.totvs.app/api/v1/link/ack' \
--header 'accept: application/json' \
--header 'Authorization: Bearer {TOKEN_RAC}'

Editando o componente

Para diagramas extensos ou que possuem muitas ligações entre componente e aplicativos, existe a possibilidade de editar o componente em casos onde é necessário alterar o componente de início escolhido sem precisar romper as ligações já estabelecidas.

01. Passe o mouse sobre o componente de início SamrtLink Hook;

02. Clique no ícone  para alterar o componente;

03. A lista com os componentes de início será apresentada, escolha o componente que deseja e clique em Salvar;

04. Uma mensagem de confirmação será apresentada, clique em Prosseguir para salvar as alterações.