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.