Antes de começar

Um Carol App reúne o código e as configurações de uma aplicação na plataforma. Ele pode transformar dados, executar rotinas ou disponibilizar serviços. O ponto de partida depende do que você pretende construir.

Antes de criar o primeiro app, conheça os ambientes em que ele pode ser desenvolvido e utilizado. Depois, escolha o tutorial mais adequado ao seu objetivo.

Conheça os ambientes

Na Carol, cada ambiente é chamado de tenant. Ele possui seus próprios dados e configurações. Há três tipos principais:

Ambiente	Para que serve
Desenvolvimento (Development)	Criar, testar e ajustar a aplicação antes de disponibilizá-la para uso
Cliente (Customer)	Utilizar a solução com os dados de um cliente
Unificado (Unified)	Reunir dados de diferentes clientes para processamentos e análises conjuntos

Você não precisa configurar os três ambientes para começar. A necessidade depende da solução, e uma mesma aplicação pode envolver mais de um deles.

No tutorial Preparando os dados, por exemplo, o exercício é realizado apenas no ambiente de desenvolvimento. Já na distribuição de uma solução para clientes, o app é preparado nesse ambiente e sua versão é instalada primeiro no unificado, depois nos ambientes clientes.

Se ainda não possui o ambiente necessário, consulte o guia de provisionamento.

Entenda as camadas de dados

Uma aplicação pode precisar tanto de processar muitos dados quanto de responder rapidamente a consultas específicas. Na Carol, essas necessidades são atendidas por camadas com finalidades distintas:

Camada	Uso recomendado	Exemplo
BigQuery	Processar e analisar grandes volumes de dados com SQL	Calcular os valores dos pedidos, cruzar tabelas e produzir indicadores
Baixa latência	Disponibilizar dados para consultas rápidas e filtradas de aplicações e assistentes	Consultar um pedido específico durante um atendimento

As camadas podem ser utilizadas em conjunto. Uma solução pode tratar os dados no BigQuery e disponibilizar os resultados necessários em baixa latência para consulta pela aplicação. Os dados disponibilizados na camada de baixa latência também permanecem armazenados no BigQuery.

Por que essa configuração aparece ao criar um app?

Um Carol App pode reunir processamento de dados e serviços de consulta. Por isso, a tela de criação inclui o campo Low Latency Data Source for Servers (MCP/REST): ele define se os serviços de baixa latência consultarão os dados do ambiente cliente ou do unificado.

Se o app utiliza apenas BigQuery, selecione Customer Tenant e prossiga com a criação. O formulário exige essa seleção, mas você não precisa habilitar a baixa latência para processar dados com SQL.

Saiba mais: escolha a origem dos dados dos serviços

No campo Low Latency Data Source for Servers (MCP/REST), escolha a opção correspondente aos dados que os serviços devem consultar:

• Customer Tenant: dados do ambiente de cada cliente que utiliza a solução.
• Unified Tenant: dados reunidos no ambiente unificado. Nesse caso, informe também qual é esse ambiente no campo Unified tenant, vinculando-o ao app.

Para habilitar o recurso e escolher as tabelas que estarão disponíveis nessa camada, consulte a configuração de baixa latência.

Escolha por onde começar

Objetivo	Próximo passo
Receber dados e transformá-los com SQL	Preparando os dados
Executar uma rotina com início e fim, sob demanda ou agendada	Carol App batch
Disponibilizar um serviço que atenda requisições	Carol App online

Referências para implementação

Saiba mais: atualização das tabelas ao instalar um app

Fluxo de materialização de esquemas na instalação de Carol Apps nos clientes

A instalação de um aplicativo Carol considera um processo padrão de atualização da staging table nos clientes, ao invés de aplicar um novo esquema excluindo colunas existentes. As regras seguidas são:

1. Executa validação verificando a existência da staging table;
2. Se não existir, cria;
3. Se existir, verifica se o conector é restrito;
4. Se não for restrito, somente adiciona novas colunas que o aplicativo Carol definiu para a staging table do cliente;
5. Se for restrito, verifica o parâmetro forceMaterializeStagingSchemaFromConnectorProtheusCarol;
6. Se o parâmetro for verdadeiro, somente adiciona novas colunas que o aplicativo Carol definiu para a staging table do cliente;
7. Se o parâmetro for falso, pula a materialização da staging table e crosswalk;

OBS: Nos itens 4 e 6, vale ressaltar que a eliminação de colunas não são materializadas.

Importante

Se o tipo do campo definido na tenant do Carol App for diferente daquele previamente definido na tenant do cliente, um aviso será registrado no log da tarefa de instalação do Carol App, informando o nome do conector, da staging table e do campo. Para definir o seu connector como restrito, é necessário associar o mesmo a um Modelo de Connector (ConnectorModelId), para tal, contate um administrador da plataforma.

Saiba mais: desenvolvimento de aplicações web

Carol App FronEnd SDK

Este documento se apresenta como uma introdução teórica ao pacote de desenvolvimento carol-app-fe-sdk, que tem como objetivo auxiliar na criação e desenvolvimento de aplicações web para a plataforma Carol, usando o framework Angular.

A plataforma Carol permite a hospedagem de aplicações customizadas em seus ambientes como forma de prover serviços adicionais aos seus usuários. Entre as modalidades de aplicação disponíveis estão as aplicações web, as quais são o publico alvo deste pacote.

Dica

Todas as aplicações web hospedadas na plataforma Carol são recomendadas a utilizarem o framework javascript Angular. Este SDK foi desenvolvido levando em consideração o ecossistema desta ferramenta, e não prevê suporte a outras tecnologias.

Adicionalmente, recomenda-se também que as aplicações sejam desenvolvidas em conjunto com a biblioteca de componentes open source da TOTVS, o PO UI - embora o SDK seja agnóstico em relação a isso.

O SDK possui uma documentação técnica com um guia de integração, e descrição de todas as ferramentas embutidas que facilitam a interação com a plataforma.

Através das APIs disponibilizadas, os desenvolvedores conseguem com poucas linhas de código interagir com todos os aspectos relevantes do ambiente da aplicação.

Documentação de Referência

• Pacote SDK carol-app-fe-sdk no npmjs: https://www.npmjs.com/package/@totvslabs/carol-app-fe-sdk

• Biblioteca PO UI: https://po-ui.io