Skip to main content

Carol App integrado ao Git

Esta seção descreve as etapas para você criar seu primeiro aplicativo integrado a um repositório Git e implantá-lo na Carol.

Importante
  1. Recomenda-se que o usuário utilizado para integração com o Git (Github, GitBucket, Azure DevOps, etc.) seja um usuário de sistema com a função exclusiva de integrar a Carol com o repositório Git.

  2. Este usuário deve ter apenas acessos de leitura ao projeto específico, evitando usuários com privilégios elevados no repositório Git.

  3. Atentar-se a casos onde o usuário dono do token entre em período de férias ou seja desligado da empresa, pois ambas as situações farão com que o token seja inativado, afetando a conexão entre Git e Carol.

  1. Acesse a Tenant de desenvolvimento, vá até a página Carol Apps no menu lateral e crie um novo Carol App informando a Tenant unificada recém criada para ser vinculada ao seu novo App e em seguida escolha a estratégia de processamento adequada e clique no botão Create App.

  1. Na página do novo Carol App recém criado clique no botão representado pelo três pontos ... e selecione a opção App Config.

Carol App Github Step 1

  1. Na janela App Config clique na opção Git connection para selecionar um repositório Git, dentre as opções disponíveis, e siga os passos de acordo com a opção de repositório escolhida.

GitHub

  1. Em Git connection selecione a opção GitHub e em seguida clique no botão Next para estabelecer conexão utilizando o recurso de Single Sign On (SSO) para buscar o arquivo de manifesto da pipeline.

Carol App Github Step 1

  1. Então clique no botão Connect to Github para iniciar o processo de single sign on (SSO) que irá utilizar das suas credenciais para autenticação.

Carol App Github Step 2

  1. Ao clicar, o usuário será redirecionado para a tela de login do github, onde irá informar as suas credenciais e irá confirmar clicando no botão Sign In.

Carol App Github Step 3

  1. Durante a autenticação, o usuário será redirecionado para uma página na plataforma Carol informando do sucesso ou falha no processo de autenticação. Esta página poderá ser fechada.

Carol App Github Step 4

  1. Retornando a página do Carol App, o usuário visualizará que a conexão do Github com a Carol foi estabelecida, carregando consigo as listas de repositórios, branches e documentos disponíveis para dentro da plataforma.

Carol App Github Step 5

  1. Observe que uma vez realizada a integração, não é necessário preencher manualmente os demais campos, basta selecionar para cada campo um valor dentre os disponíveis na lista.

Carol App Github Step 6 Carol App Github Step 62 Carol App Github Step 61

  1. Após salvar a configuração você verá as informações do projeto e branch na tela de criação do Carol App.

Carol App Github Step 7

  1. Sempre que necessário, o token pode ser revogado clicando no botão Revoke token.

Carol App Github Step 8

  1. Para confirmar a revogação, basta escrever o nome informado na tela e clicar no botão Confirm.

Carol App Github Step 9

NOTA

Após essa etapa realizada, caso deseje efetuar uma nova conexão com autenticação no Github retorne ao passo 4.

Bitbucket

  1. Em Git connection selecione a opção Bitbucket e em seguida clique no botão Next para estabelecer a conexão e buscar o arquivo de manifesto da pipeline.

Carol App Bitbucket Step 1

  1. Na tela seguinte, preencha o User Name e App Password.

Carol App Bitbucket Step 2

  1. O usuário é o username do perfil do BitBucket. Em caso de dúvidas, o mesmo pode ser visualizado dentro de Account Settings.

Carol App Bitbucket Step 3

  1. O App Password é gerado dentro do Personal Settings do BitBucket Account.

Carol App Bitbucket Step 4

  1. Após os dados preenchidos, Clicar no botão Connect.

Carol App Bitbucket Step 5

  1. Após isto, as pipelines estarão integradas para seleção na tela do App. Então escolha o link do projeto, a branch e o link do manifesto, e em seguida clique no botão Save.

Carol App Bitbucket Step 6

  1. Após salvar a configuração você verá as informações do projeto e branch na tela de criação do Carol App.

Carol App Bitbucket Step 7

Nota

A Carol também permite a revogação do token para o Bitbucket.

Azure DevOps

  1. Em Git connection selecione a opção Azure e em seguida clique no botão Next para estabelecer a conexão e buscar o arquivo de manifesto da pipeline.

Carol App Azure Step 1

  1. Na tela seguinte, preencha o User Name e Personal Access Token.

Carol App Azure Step 2

  1. O usuário é o username do perfil do Azure DevOps (o mesmo fica marcado na URL da própria web page Azure DevOps)

Carol App Azure Step 3

  1. O Personal Access Token é gerado dentro do Azure DevOps, acessando pelo menu à esquerda a opção que leva o mesmo nome.

Carol App Azure Step 4

Importante

No campo organização é obrigatório que seja definido o valor como All acessible organizations para que a conexão entre Carol App e repositório GIT funcionem.

Caro App Azure Step 4 warning

  1. Após os dados preenchidos, clique no botão Connect.

Carol App Azure Step 5

  1. Após isto, as pipelines estarão integradas para seleção na tela do App. Então escolha o link do projeto, a branch e o link do manifesto, e em seguida clique no botão Save.

Carol App Azure Step 6

  1. Após salvar a configuração você verá as informações do projeto e branch na tela de criação do Carol App.
Nota

A Carol também permite a revogação do token para o Azure devops.

Carol App Azure Step 7

Submetendo o Carol App para aprovação

Com a staging e datamodel criados, selecione o App e execute o lançamento clicando no botão Release, submetendo o Carol App para aprovação (status = submitted for review).

Carol App Submission Step 1 Carol App Submission Step 2 Carol App Submission Step 3

Instalando o Carol App nas tenants

  1. Após o Carol App aprovado (status = deployed) na Tenant de desenvolvimento, acesse a página Carol Apps, na aba Installed Apps e clique no botão Available Apps.

Carol App Installation Step 1

  1. Selecione o Carol App clicando no botão Install e siga os passos indicados e clique no botão Finish.

Carol App Installation Step 2 Carol App Installation Step 3

  1. Aguarde pelo término total da instalação que será indicado pela mudança do status de Subscribed para Published.

Carol App Installation Step 4

  1. Agora vá para a Tenant unificada e repita os passos acima. Somente após feito isto, repita o mesmo procedimento para a Tenant do cliente.
Importante

Somente após ter o status Published será possível visualizar as stagings e data models criados.

Atualizando um Carol App por meio de endpoints

Esta documentação descreve como atualizar um Carol App por meio de endpoints. Abrange o fluxo para assinar a versão mais recente disponível e executar o fluxo de instalação.

Para esta missão, vamos executar as seguintes etapas:

  • Para um determinada Tenant, obteremos todos os aplicativos instalados.
  • Para a aplicação desejada iremos comparar se é a mais nova.
Nota

Para esta documentação, assumiremos Clock-In: carolclockinweb verificando se tem uma nova versão disponível para esta Tenant.

  • Considerando que tem uma nova versão, iremos subscrever a versão mais recente.
  • Publicaremos a configuração.
  • Faremos a instalação para disponibilizar todos os recursos necessários para esta versão do aplicativo.

Um pré-requisito para todas essas etapas é o fluxo de autenticação; Veja mais informações em Auntenticação e Login.

Obter todos os aplicativos instalados

O principal objetivo desta etapa é garantir que esta tenant tenha instalado, ou não, o aplicativo que desejamos instalar/atualizar. Esta etapa não é necessária se você não precisar verificar o status atual. Você pode pular para a próxima etapa.

O endpoint a seguir retorna todos os aplicativos instalados na Tenant atual:

Obter todos os aplicativos instalados
curl -X 'GET' \
'https://api.carol.ai/api/v3/tenantApps?offset=0&pageSize=-1&sortOrder=ASC&checkAllSpaces=false' \
-H 'accept: application/json' \
-H 'Authorization: TOKEN'

Onde:

  • Token: token que você gerou no fluxo de autenticação.
  • pageSize: o número de documentos retornados por este endpoint. O valor máximo é 5.000.

Resposta do endpoint para todos os Carol Apps disponíveis:

Resposta com todos os resultados de Carol Apps instalados
{
"aggs": {},
"count": 1,
"empty": false,
"hits": [
{
"mdmAppDeveloperIds": null,
"mdmAppIconUrl": "icon.png",
"mdmAppPictureUrl": [],
"mdmAppPoweredBy": {
"en-US": "Carol"
},
"mdmAppSubscriptionUrl": "/apps/carolclockinweb/3.33.5/index.html",
"mdmAppVersion": "3.33.5",
"mdmCreated": "2021-06-11T03:56:44.783Z",
"mdmCreatedUser": "furtado.bruno@totvs.com",
"mdmDescription": {
"en-US": "TOTVS RH Clock-In Web é a aplicação Web do Clock-In que permite que funcionários façam a marcação através do reconhecimento facial em um browser."
},
"mdmEntityType": "mdmCarolApp",
"mdmId": "ee4fc957ed5049bf9674e07a362a39ab",
"mdmIsLatestVersion": false,
"mdmIsSubscribable": true,
"mdmLabel": {
"en-US": "TOTVS RH Clock In Web"
},
"mdmLastUpdated": "2021-07-23T17:39:01.784Z",
"mdmName": "carolclockinweb",
"mdmProgress": null,
"mdmState": "NOT_CHANGED",
"mdmTenantId": "4c2c9090e7c611e893bf0e900682978b",
"mdmUpdatedUser": "furtado.bruno@totvs.com",
"score": null
}
],
"scrollId": null,
"took": 0,
"totalHits": 0
}

Na resposta acima, podemos ver que esta tenant tem o aplicativo carolclockinweb disponível na versão 3.33.5, esta versão está disponível porque é superior à versão atualmente instalada (3.31.2).

Obter todos os aplicativos disponíveis (incluindo novas instalações e atualizações)

Nesta etapa, obteremos todos os novos aplicativos e atualizações da Carol disponíveis (caso o aplicativo já esteja instalado). Para esta etapa, a seguinte linha mostra o endpoint que deve ser chamado:

Solicitação para obter todos os Carol Apps disponíveis
curl -X 'GET' \
'https://api.carol.ai/api/v3/tenantApps/subscribableCarolApps' \
-H 'accept: application/json' \
-H 'Authorization: TOKEN'

Onde:

  • TOKEN: token que você gerou no fluxo de autenticação.

A resposta para este endpoint segue:

Resposta para todos os Carol Apps disponíveis
{
"aggs": {},
"count": 1,
"empty": false,
"hits": [
{
"mdmAppDeveloperIds": null,
"mdmAppIconUrl": "icon.png",
"mdmAppPictureUrl": [],
"mdmAppPoweredBy": {
"en-US": "Carol"
},
"mdmAppSubscriptionUrl": "/apps/carolclockinweb/3.33.5/index.html",
"mdmAppVersion": "3.33.5",
"mdmCreated": "2021-06-11T03:56:44.783Z",
"mdmCreatedUser": "furtado.bruno@totvs.com",
"mdmDescription": {
"en-US": "TOTVS RH Clock-In Web é a aplicação Web do Clock-In que permite que funcionários façam a marcação através do reconhecimento facial em um browser."
},
"mdmEntityType": "mdmCarolApp",
"mdmId": "ee4fc957ed5049bf9674e07a362a39ab",
"mdmIsLatestVersion": false,
"mdmIsSubscribable": true,
"mdmLabel": {
"en-US": "TOTVS RH Clock In Web"
},
"mdmLastUpdated": "2021-07-23T17:39:01.784Z",
"mdmName": "carolclockinweb",
"mdmProgress": null,
"mdmState": "NOT_CHANGED",
"mdmTenantId": "4c2c9090e7c611e893bf0e900682978b",
"mdmUpdatedUser": "furtado.bruno@totvs.com",
"score": null
}
],
"scrollId": null,
"took": 0,
"totalHits": 0
}

Na resposta acima, podemos ver que esta tenant tem o aplicativo carolclockinweb disponível na versão 3.33.5, esta versão está disponível porque é superior à versão atualmente instalada (3.31.2).

Fluxo de assinatura para um novo aplicativo ou uma atualização

Após saber que o aplicativo está disponível para instalação ou uma nova versão disponível, precisamos cadastrar a Tenant no Carol App e a versão. O seguinte endpoint faz isso:

Carol App Subscription para um aplicativo e versão
curl -X 'POST' \
'https://api.carol.ai/api/v3/tenantApps/subscribe/carolApps/{carolAppID}' \
-H 'accept: application/json' \
-H 'Authorization: TOKEN' \
-d ''

Onde:

  • TOKEN: token que você gerou no fluxo de autenticação.
  • carolAppID: ID do aplicativo que podemos obter da resposta para todos os aplicativos disponíveis, linha 21 (ee4fc957ed5049bf9674e07a362a39ab).

A resposta para este endpoint segue:

Resposta da assinatura do aplicativo Carol
{
"mdmAppIconUrl": "icon.png",
"mdmAppPictureUrl": [],
"mdmAppPoweredBy": {
"en-US": "Carol"
},
"mdmAppSubscriptionUrl": "/apps/carolclockinweb/3.33.5/index.html",
"mdmAppVersion": "3.33.5",
"mdmCarolAppId": "ee4fc957ed5049bf9674e07a362a39ab",
"mdmConnectorGroupSelected": {
"mdmConnectorNames": [
"clockinweb"
],
"mdmLabel": {
"en-US": "Default"
},
"mdmName": "default"
},
"mdmCreated": "2021-02-23T02:56:35.169Z",
"mdmCreatedUser": "robson.poffo@totvs.com",
"mdmDescription": {
"en-US": "TOTVS RH Clock-In Web é a aplicação Web do Clock-In que permite que funcionários façam a marcação através do reconhecimento facial em um browser."
},
"mdmEntityType": "mdmTenantAppWorking",
"mdmId": "6ebaa847a4fb4b7bb22a03a3734f9c5c",
"mdmInstallationTaskId": "52bd33d5a8c247df810630f82ad23a34",
"mdmInstallationTaskStatus": "COMPLETED",
"mdmLabel": {
"en-US": "TOTVS RH Clock In Web"
},
"mdmLastUpdated": "2021-10-12T03:37:06.353Z",
"mdmName": "carolclockinweb",
"mdmStatus": "ACTIVE",
"mdmTenantId": "b57a7e74a1764003aa987288a610456e",
"mdmUpdatedUser": "robson.poffo@totvs.com"
}

Podemos ver que a assinatura aconteceu para o aplicativo Carol e a versão que esperávamos na resposta acima.

Publicar a configuração do aplicativo Carol

Esta etapa publicará a configuração do aplicativo usando o seguinte endpoint:

Solicitação para publicar um Carol App Setting (nova versão do app)
curl -X 'POST' \
'https://api.carol.ai/api/v3/tenantApps/{tenantCarolAppID}/publish' \
-H 'accept: application/json' \
-H 'Authorization: TOKEN' \
-d ''

Onde:

  • TOKEN: token que você gerou no fluxo de autenticação.
  • tenantCarolAppID: ID do aplicativo nesta tenant, obtemos essa informação da resposta da assinatura, linha 25 (6ebaa847a4fb4b7bb22a03a3734f9c5c).

A resposta para este endpoint segue:

Resposta da publicação do Carol App Setting
{
"mdmAppIconUrl": "icon.png",
"mdmAppPictureUrl": [],
"mdmAppPoweredBy": {
"en-US": "Carol"
},
"mdmAppSubscriptionUrl": "/apps/carolclockinweb/3.33.5/index.html",
"mdmAppVersion": "3.33.5",
"mdmCarolAppId": "ee4fc957ed5049bf9674e07a362a39ab",
"mdmConnectorGroupSelected": {
"mdmConnectorNames": [
"clockinweb"
],
"mdmLabel": {
"en-US": "Default"
},
"mdmName": "default"
},
"mdmCreated": "2021-02-23T02:56:35.169Z",
"mdmCreatedUser": "robson.poffo@totvs.com",
"mdmDescription": {
"en-US": "TOTVS RH Clock-In Web é a aplicação Web do Clock-In que permite que funcionários façam a marcação através do reconhecimento facial em um browser."
},
"mdmEntityType": "mdmTenantApp",
"mdmId": "6ebaa847a4fb4b7bb22a03a3734f9c5c",
"mdmInstallationTaskId": "52bd33d5a8c247df810630f82ad23a34",
"mdmInstallationTaskStatus": "COMPLETED",
"mdmLabel": {
"en-US": "TOTVS RH Clock In Web"
},
"mdmLastUpdated": "2021-10-12T03:42:26.190Z",
"mdmName": "carolclockinweb",
"mdmStatus": "ACTIVE",
"mdmTenantId": "b57a7e74a1764003aa987288a610456e",
"mdmUpdatedUser": "robson.poffo@totvs.com"
}

Na resposta acima, podemos ver que a ação de publicação Carol App Setting funcionou conforme o esperado.

Instalar o novo aplicativo ou a versão mais recente

Assim que soubermos que o Carol App ID está nesta tenant, podemos chamar o seguinte endpoint para iniciar a instalação do Carol App:

Solicitação para instalar uma versão específica do aplicativo Carol
curl -X 'POST' \
'https://api.carol.ai/api/v3/tenantApps/{tenantCarolAppID}/install?connectorGroup={connectorGroup}&publish=true' \
-H 'accept: application/json' \
-H 'Authorization: TOKEN' \
-d ''

Onde:

  • TOKEN: token que você gerou no fluxo de autenticação.
  • tenantCarolAppID: ID do aplicativo nesta tenant, obtemos essa informação da resposta da assinatura, linha 25 (6ebaa847a4fb4b7bb22a03a3734f9c5c).
  • conectorGroup: este parâmetro é opcional; se o aplicativo tiver um grupo de conectores especificado, você deverá especificar o nome do grupo de conectores. Para o aplicativo Web Clock-In, é padrão.
  • publish: deve ser true para que Carol publique o Carol App Setting (igual ao passo anterior).

A resposta para este endpoint segue:

Resposta da Instalação do Carol App
{
"mdmConnectorId": "0a0829172fc2433c9aa26460c31b78f0",
"mdmCreated": "2021-10-12T03:49:29.579Z",
"mdmCreatedUser": "robson.poffo@totvs.com",
"mdmData": {
"connectorGroup": "default",
"carolAppCopyToArea": "prod",
"carolAppName": "carolclockinweb",
"publish": true,
"carolAppId": "ee4fc957ed5049bf9674e07a362a39ab",
"carolAppCopyFromArea": "dev",
"tenantAppId": "6ebaa847a4fb4b7bb22a03a3734f9c5c",
"carolAppVersion": "3.33.5"
},
"mdmDistributionValue": 76,
"mdmEntityType": "mdmTask",
"mdmHasDebugLog": false,
"mdmHasErrorLog": false,
"mdmHasInfoLog": false,
"mdmHasLog": false,
"mdmHasTraceLog": false,
"mdmHasWarnLog": false,
"mdmId": "04a78e6397f94438a8043213f1ce8838",
"mdmLastUpdated": "2021-10-12T03:49:29.579Z",
"mdmNumIncompleteTries": 0,
"mdmNumTries": 0,
"mdmNumberOfSteps": 0,
"mdmNumberOfStepsExecuted": 0,
"mdmParentTaskId": "",
"mdmProcessAfter": "2021-10-12T03:49:29.526Z",
"mdmTaskFromSchedule": false,
"mdmTaskGroup": "6ebaa847a4fb4b7bb22a03a3734f9c5c",
"mdmTaskLevel": "mdmTenant",
"mdmTaskPreference": 100,
"mdmTaskProcessing": false,
"mdmTaskProgress": 0,
"mdmTaskReady": true,
"mdmTaskStatus": "READY",
"mdmTaskType": "INSTALL_CAROL_APP",
"mdmTenantId": "b57a7e74a1764003aa987288a610456e",
"mdmUpdatedUser": "robson.poffo@totvs.com",
"mdmUserId": "5bb29087db07443581804561fb41d1ee"
}

Na resposta acima, podemos ver que a instalação do Carol App foi iniciada. Podemos acompanhar o progresso da instalação através do seguinte endpoint:

Solicitação de status da tarefa
curl -X 'GET' \
'https://api.carol.ai/api/v1/tasks/{taskID}' \
-H 'accept: application/json' \
-H 'Authorization: TOKEN'

Onde:

  • TOKEN: token que você gerou no fluxo de autenticação.
  • taskID: este é o taskID retornado do terminal de instalação, linha 23 (04a78e6397f94438a8043213f1ce8838).

A resposta para este endpoint segue:

Resposta do status da tarefa
{
"mdmConnectorId": "0a0829172fc2433c9aa26460c31b78f0",
"mdmCreated": "2021-10-12T03:49:29.579Z",
"mdmCreatedUser": "robson.poffo@totvs.com",
"mdmData": {
"STAGING_SCHEMA_DONE": true,
"connectorGroup": "default",
"DATA_MODEL_DONE": true,
"carolAppCopyToArea": "prod",
"carolAppName": "carolclockinweb",
"publish": true,
"carolAppId": "ee4fc957ed5049bf9674e07a362a39ab",
"carolAppCopyFromArea": "dev",
"tenantAppId": "6ebaa847a4fb4b7bb22a03a3734f9c5c",
"carolAppVersion": "3.33.5",
"CONNECTORS_DONE": true
},
"mdmDistributionValue": 76,
"mdmEntityType": "mdmTask",
"mdmHasDebugLog": false,
"mdmHasErrorLog": false,
"mdmHasInfoLog": true,
"mdmHasLog": true,
"mdmHasTraceLog": false,
"mdmHasWarnLog": false,
"mdmId": "04a78e6397f94438a8043213f1ce8838",
"mdmLastUpdated": "2021-10-12T03:49:29.579Z",
"mdmNumIncompleteTries": 0,
"mdmNumTries": 1,
"mdmNumberOfSteps": 12,
"mdmNumberOfStepsExecuted": 3,
"mdmParentTaskId": "",
"mdmProcessAfter": "2021-10-12T03:49:29.526Z",
"mdmStartDate": "2021-10-12T03:49:29.861Z",
"mdmTaskFromSchedule": false,
"mdmTaskGroup": "6ebaa847a4fb4b7bb22a03a3734f9c5c",
"mdmTaskLevel": "mdmTenant",
"mdmTaskOwner": "worker-6659874597-pcf48",
"mdmTaskPreference": 100,
"mdmTaskProcessing": true,
"mdmTaskProgress": 25,
"mdmTaskReady": true,
"mdmTaskStatus": "RUNNING",
"mdmTaskType": "INSTALL_CAROL_APP",
"mdmTenantId": "b57a7e74a1764003aa987288a610456e",
"mdmUpdatedUser": "robson.poffo@totvs.com",
"mdmUserId": "5bb29087db07443581804561fb41d1ee"
}

Na resposta acima, podemos ver esse documento de tarefa. O campo mdmTaskStatus possui o seguinte status:

  • READY: quando a tarefa está esperando para ser executada.
  • RUNNING: quando a tarefa está sendo executada.
  • CANCELED: quando a tarefa foi cancelada. Geralmente por solicitação do usuário.
  • COMPLETED: quando a tarefa é concluída com sucesso.
  • FAILED: quando a tarefa obteve um erro interno e falhou.

Conclusão

As etapas acima permitem obter aplicativos Carol disponíveis ou atualizações disponíveis e executar um processo para atualizar um aplicativo Carol em TenantS.