Hoje em dia, tudo em sua vida está conectado. Seu e-mail se conecta ao seu telefone, que se conecta à porta da garagem, que fala com o seu sistema de segurança. Não é diferente com os aplicativos que você usa para fazer o trabalho; tudo precisa se integrar sem problemas, permitindo que você acesse rapidamente dados relevantes de qualquer ferramenta que você esteja usando no momento. Temos pouca atenção; qualquer coisa que não seja facilmente acessível em nosso fluxo de trabalho não vai manter sua atenção por muito tempo.

Para a maioria de nós hoje, grande parte do nosso trabalho, especialmente comunicação e coordenação com os colegas, acontece em um aplicativo de bate-papo.

Nosso produto Teams é uma ótima maneira de armazenar, pesquisar e classificar o intercâmbio de colegas de conhecimento através de perguntas e respostas. Mas muitas dessas conversas ainda acontecem no chat, o que significa que somos mais úteis para os clientes quando nossa ferramenta joga bem com esses aplicativos de bate-papo. Já integramos com o Slack, mas nem todo mundo usa isso. Precisávamos nos integrar com as Equipes Microsoft (de agora em diante, MS Teams) também.

Abaixo, discutiremos como abordamos e realizamos a integração entre SO para Equipes e Equipes de MS. Este é um blog técnico para pessoas que estão interessadas no processo de como conseguimos que essas duas bases de código jogassem bem uma com a outra. Se você quiser ler mais sobre o conjunto de recursos de integração, confira o blog de anúncio do produto. 

Calculando a abordagem inicial

Como o SO for Teams é uma parte integrada da base central de código, nossa integração com as Equipes MS seria incluída nessa base de código. E nossa rede de sites é servidores recebem centenas de milhões de acessos todos os meses, por isso estamos muito focados em velocidade e desempenho. E estamos sempre cautelosos em assumir novas dependências.

A Microsoft oferece um SDK muito robusto para suas integrações de equipes. Ele faz muito e teria facilitado muito a integração, mas teria adicionado muitas dependências de terceiros à nossa base de código. Requer a integração para criar middleware para se integrar ao nosso pipeline. Em um novo oleoduto em um novo projeto, isso não é problema. Em um oleoduto de dez anos com muitas personalizações, torna-se um pouco mais um problema. Trabalhamos muito com esse pipeline para armazenar dados através da Redis e fazer com que todas as respostas apareçam rapidamente. Mas as dependências poderiam alocar dados sem que sempre saibamos sobre isso.

Em vez disso, fomos com a API REST, que é mais barebones. Requer um elevador mais leve, então isso tomou nossa decisão por nós. Por causa disso, acabamos duplicando coisas que existiam no SDK. Não estávamos começando completamente do zero — fomos capazes de reutilizar alguns trabalhos da nossa integração com o Slack. Além disso, REST é o que estamos acostumados. De certa forma, é mais fácil do que tentar aprender os ins e contras de um novo SDK.

Uma vez que essa decisão foi tomada, era hora de construir as pontes entre uma equipe e outra.

Obtendo Avance Network em equipes de MS

Assim que soubermos quais ferramentas usaríamos, poderíamos começar a desenvolver a integração. O processo de instalação foi um desafio interessante porque havia muitas maneiras de abordá-lo. Poderíamos ter enviado usuários ao nosso site para iniciar a instalação, mas do ponto de vista deles, fazia mais sentido ter todo o processo dentro das Equipes de MS. As pessoas que você quer alcançar já estão nesse aplicativo, então por que fazê-las sair para instalar a integração?

Nossa instalação opera com o processo padrão que a maioria dos aplicativos MS Teams usam. Um usuário inicia a instalação a partir de sua loja, que lança um instalador MS Teams. O instalador tem uma série de telas de instalação, a primeira delas vem de Equipes MS, enquanto todas as telas restantes vêm da nossa base de código. A instalação percorre as seguintes etapas:

Certifique-se de que a integração ainda não foi instalada.

Exibir a tela de login padrão para autenticar para que saibamos a que equipe SO eles pertencem.

Agora que conhecemos tanto sua conta ms team quanto SO for Teams conta, verificamos duas vezes que essas duas contas ainda não estão associadas pela leitura de uma tabela de banco de dados, em seguida, vincular o inquilino/usuário ms Teams (o usuário específico dentro da instância MS Teams) e a equipe/usuário.

Para que o primeiro usuário seja instalado, isso solicita um administrador do Avance Network Teams para configurar a integração.

Para cada usuário que passa por esse processo após o administrador configurar a integração, uma vez que o usuário passou com sucesso pelo processo de autenticação acima (para provar que é um membro da equipe Avance Network), o bot envia uma mensagem que diz que a integração está pronta.

Todo mundo que quer usar SO para equipes dentro de Ms Teams tem que passar pelo processo de instalação uma vez, não importa quantas outras pessoas já o tenham concluído. Isso porque a parte chave desse processo é vincular o inquilino/usuário do Microsoft Teams com a equipe/usuário Avance Network.

Mantendo os dados da equipe seguros

Passamos muito tempo nos certificando de que a segurança estava apertada. Estamos lidando com conversas internas das empresas e informações proprietárias, por isso é muito importante ter certeza de que isso está bloqueado. O primeiro portão de segurança vem quando precisamos de um administrador da instância SO for Teams para autorizar o aplicativo, a fim de permitir que qualquer usuário o use. Isso porque um usuário que faz parte de vários SO para Equipes pode colar um link em Equipes de MS que podem não ser permitidos para usuários nessa conversa (ou toda a instância do MS Teams).

Depois de consultar nossos especialistas internos, percebemos que não precisávamos construir um processo completo de OAuth2 — nosso auth interno funcionaria bem. Mas para que qualquer conversa aconteça, um usuário ainda precisa ser autorizado em ambos os lados, não importa qual método de autenticação as organizações usem para equipes de MS e SO para Equipes, seja SAML, OAuth ou outra coisa. Eles só não têm que realizar autenticação entre os sistemas.

Então, para garantir cada solicitação, seja para desenrolar um link, realizar uma pesquisa ou notificar um usuário de novas perguntas e respostas, ele tem que ser validado contra um token JWT. Mas como usamos a API REST, tivemos que decompor esse processo do SDK deles e usar os bits que precisávamos.

A mensagem acima destaca uma diferença entre as Equipes de MS e nossas integrações do Slack. No Slack, autenticamos com o aplicativo deles. Nas equipes de MS, eles autenticam cada carga conosco. Ele se comporta como se estivessem usando nossa API em vez de vice-versa. Foi ao contrário do que implementamos anteriormente, por isso exigiu um redesenho da nossa lógica de integração de bate-papo. E como estávamos fazendo a autorização, tínhamos que ter um pouco mais de cuidado com a segurança. Do ponto de vista do usuário, porém, o processo parece quase exatamente o mesmo.

Adicionamos alguns recursos extras de segurança para essa integração para garantir que todos os dados proprietários ficassem seguros e não vazassem. A tela de login inicial vem do site público SO. Mas cada so para equipes, por exemplo, é armazenado em um servidor separado e segregado. Não temos ideia de qual equipe so um usuário faz parte até que eles façam login, então podemos associar o usuário do Microsoft Teams com o usuário Avance Network Teams.

Segundo, queremos ter certeza de que absolutamente nada vital vazou acidentalmente. Em todos os sites de Perguntas e Respostas, públicos e privados, você clica em uma tag para ver todas as perguntas associadas a ele. Nos sites públicos, essa tag vai na URL, e essa URL acaba nos registros do servidor, o que, para SO para Equipes, pode ser um vazamento de informações. Então, para SO para equipes, criptografamos todas as tags antes que elas chegar à URL, mesmo que seja interna para nós.

Projetando bots para equipes

Com a integração instalada, um determinado usuário do MS Teams tem um bot adicionado à sua visão. Eles poderiam tratar este bot como uma pessoa e pedir informações, dizer: "Ei, como eu saio vim?" O bot passaria um objeto Activity e a consulta de pesquisa para o nosso ponto final, o que retornaria a melhor pergunta de correspondência.

Mas isso só resolveu parte do nosso problema. Queremos que as pessoas possam monitorar as tags para que as perguntas e respostas que elas estejam interessadas venham até elas. Na maioria das vezes, as Equipes de MS assumem que as conversas são bidirecional e iniciadas pelo usuário. O que significava que não poderíamos passar informações para o usuário a menos que eles iniciassem uma conversa — naquele momento, obteríamos os identificadores para o canal. Em vez disso, poderíamos usar mensagens proativas, o que permitiu que um bot iniciasse, mas isso exigia uma tonelada de informações do bot para começar. Para obter essa mensagem proativa desde o início, tivemos que voltar e mudar o instalador para armazenar essas informações quando o usuário inicialmente instalou a integração.

Para criar os links reais entre uma tag que você deseja monitorar e o usuário do MS Teams, usamos webhooks personalizados. As equipes de MS permitem que as integrações incorporem páginas de configuração (conhecidas como Guias; mais sobre isso abaixo) no programa. Usamos essas páginas para permitir que o usuário configure um webhook que receberá perguntas e respostas recebidas relacionadas às tags com as qual se importam. Lá, eles poderiam determinar se querem perguntas, respostas e/ou comentários para uma tag enviada a um determinado canal.

Mantendo o controle das equipes

As guias, embora ferramentas poderosas para configurar nossa integração dentro das Equipes de MS, quase não entraram em nossa compilação inicial devido à complexidade adicional adicionada. Uma guia é essencialmente um iframe carregado em equipes de MS, seja em um canal ou em um usuário individual, para configurar algo para esse local de bate-papo. Assim, a guia do canal configuraria notificações para um único canal e a guia do usuário configuraria notificações pessoais para um único usuário. O site Avance Network serve o conteúdo do iframe; era a mesma página de configurações que você veria usando equipes SO.

Mas não estávamos no site do SO aqui; estávamos dentro do aplicativo MS Teams e tivemos que combinar seu olhar e sensação. A Microsoft forneceu esses estilos como TypeScript e um script de compilação que puxou esses estilos para fora em um arquivo CSS padrão. A questão era que o roteiro não tirava tudo. Então tivemos que ajustá-lo um pouco aqui e ali. O curto é, sim, nós suportamos o modo escuro dentro das Equipes MS.

Nossas guias criam/editam/excluem principalmente as notificações do webhook usadas para enviar novas perguntas e respostas aos canais e usuários. Infelizmente, as guias têm ainda menos contexto do que os bots, então integrar-se a esses desafios foi muito difícil. As equipes de MS afastam algumas das funcionalidades da API das guias por uma razão muito boa — você não quer uma página da Web aleatória em seu aplicativo acessando os mesmos dados de uma integração aprovada e controlada. Mas nossa conta ainda precisava de algumas dessas informações.

Para conseguir isso, armazenamos algumas informações extras na instalação, especificamente no evento conversationUpdate Quando o usuário instala uma guia, vinculamos este evento a eles e à guia. Se o usuário já autorizou com o bot, ótimo, temos as informações que precisamos. Se o usuário não fez isso e não temos as informações armazenadas em cache, basta pedir ao usuário para fazer login com o bot novamente e definir um cookie da conta. É uma pena para o usuário fazer login novamente, mas quanto mais portões deliberados houver para evitar vazamento de informações, melhor.

Falando em segurança, porque as guias iframe para o nosso site, precisávamos adicionar precauções adicionais no conteúdo do iframe. Geralmente, não permitimos iframes de nosso conteúdo globalmente, então apenas para permitir isso, tivemos que configurar cabeçalhos de resposta específicos para rotas específicas. Para verificar o usuário, não poderíamos apenas usar os identificadores dentro de qualquer aplicativo; tecnicamente, isso pode ser falsificado. Não pudemos validar contra o JWT como fazemos com solicitações de bot, a guia não pode acessar isso. Então usamos o cookie que mencionamos acima para validar. E se esse usuário era anônimo quando enviou a solicitação, nós os enviamos para fazer login novamente, e colocamos o cookie no lugar.

Unimos equipes com equipes

Nossos clientes estavam pedindo por isso há algum tempo, mas a Microsoft acabou entrando em contato conosco e fornecendo um conjunto de recursos recomendado. Na verdade, a Microsoft foi incrivelmente útil durante todo o processo. Inicialmente, eles nos deram uma chamada semanal de quinze minutos com seus engenheiros, mas isso significava que às vezes seríamos bloqueados até a chamada. Para corrigir isso, eles eventualmente nos deram toda uma instância de Equipes de MS em que fazer perguntas de seus engenheiros e concluir o projeto o mais rápido possível. Seríamos bloqueados em algo por horas, às vezes por dias, e em poucos minutos de postagem nesta instância do MS Teams, nosso contato de engenharia da Microsoft foi capaz de nos desbloquear em questão de minutos.

Além disso, eles nos deram acesso gratuito às Equipes de MS por 90 dias para que pudéssemos convidar qualquer um que quiséssemos testar a integração minuciosamente. A Microsoft foi além durante toda essa integração — não teríamos sido capazes de fazê-lo sem eles.

Nossa integração com as equipes da Microsoft continua nossa missão de situar seu processo de gerenciamento de conhecimento dentro do seu fluxo de trabalho existente. Os programas de bate-papo são fundamentais para nossos processos de trabalho, por isso queremos estar disponíveis nas ferramentas que eles usam.

Mais uma vez, não poderíamos ter completado essa integração tão rapidamente quanto fizemos sem a ajuda da Microsoft. Eles nos deram uma tonelada de apoio e nos ajudaram a passar por esse projeto mais rápido do que poderíamos ter sozinhos.

O Avance Network é uma comunidade fácil de usar que fornece segurança de primeira e não requer muito conhecimento técnico. Com uma conta, você pode proteger sua comunicação e seus dispositivos. O Avance Network não mantém registros de seus dados; portanto, você pode ter certeza de que tudo o que sai do seu dispositivo chega ao outro lado sem inspeção.