Umas das grandes características da plataforma Magic xpi é a sua capacidade de moldar-se às necessidades e desafios propostos. 
Multiplique e adapte você mesmo os recursos de integração da plataforma, com o Connector Builder. Venha conhecer como.
O Connector Builder é um framework que vem junto com a plataforma Magic xpi desde a sua versão 4.5, mas pouco falado, acabando por passar despercebido algumas vezes:
Ele permite criarmos “novos componentes” para uso nos fluxos de integração dos projetos.
Qualquer tipo de componente. Para qualquer finalidade. Para qualquer API!
Um olhar mais atento na pasta “Runtime\addon_connectors” da instalação do Magic xpi, vai nos mostrar uma pequena lista de subpastas:
São “componentes” ( MQTT, OData, REST Client, SAP R/3 ERP, Web Services (SOAP) Client ) que vem sendo criados e adicionados à coleção de ferramentas, ao longo das versões lançadas, e que estão localizados nesta pasta justamente porque foram todos criados com o Connector Builder!
Isso mesmo: o próprio R&D da Magic Software utiliza o Connector Builder para desenhar e disponibilizar novos conectores.
Ou seja, quando nós formos criar componentes com este framework, teremos à nossa disposição todos os recursos necessários para ações em Steps, Triggers, Resources e o que mais for preciso.
Quer ver seu sistema figurando na biblioteca de componentes do Magic xpi? Connector Builder é o caminho!
Este trabalho não é complexo, mas requer dedicação e um pouco de tempo. Por isso, vamos dividir este tema em um série de posts, pois não dá para mostrar tudo de forma correta em uma única publicação.
Nesta primeira parte, faremos a introdução ao Connector Builder. Ao final da série, com 5 ou 6 posts talvez, você terá à disposição um novo componente para uso em seus projetos de integração.
O que vamos fazer?
Vamos criar um novo componente que realiza requisições web (via protocolo HTTP ou HTTP/s) a sites, assim como já faz o componente HTTP padrão do Magic xpi.
Mas faremos isso através do programa curl.
O curl é um utilitário de linha de comando (call url) muito conhecido no mundo Linux mas que também está disponível para o Windows (o que queremos aqui), e que permite acessar qualquer site através do protocolo HTTP(s), seja para requisições REST ou SOAP.
*Nota: este conector será compatível com Windows 64Bits somente.
O que vamos precisar?
Inicialmente, claro, do curl. O curl está nativamente disponível nas versões mais novas do Windows. Mas se não for o seu caso, pode baixá-lo deste site: https://curl.se/windows/ e após instalá-lo, adicione sua pasta “bin” no PATH do Windows. Para confirmar se está OK, abre o prompt do DOS e digite:
curl --help
Tem de aparecer um resultado semelhante a este:
*Nota: É esta a versão que, inclusive, usaremos aqui nesta série de postagens.
Outra coisa que iremos precisar é uma IDE para desenvolvimento MS.NET. Nos exemplos deste post, usaremos o Visual Studio, mas qualquer outra de sua preferência é válida.
Existem dois tipos de módulos que precisam ser desenvolvidos na criação de componentes Magic xpi: UI e Runtime.
UI é a interface (conjunto de telas) que o Magic xpi Studio utilizará para configurar a execução do componente, na área de Step ou Trigger, durante o desenho do projeto.
Este módulo, obrigatoriamente, tem de ser desenvolvido em MS.NET (FW). Daí esta necessidade.
Runtime é o módulo que será invocado pelo Magic xpi Server, durante a execução de alguma integração envolvendo este componente.
Para este módulo (runtime), já são três as opções de tecnologia de desenvolvimento disponíveis (aceitas pelo Magic xpi): MS.NET, Java ou Magic xpa.
Conforme for a sua escolha, muda a IDE necessária para este desenvolvimento. Por exemplo, usamos algumas vezes o Eclipse Kepler* para criação de módulos Java para o Magic xpi.
*Nota: A versão Java usada tem de ser compatível com a versão Java que o Magic xpi usará, na execução dos projetos (jvm7, jvm8...).
Nesta série de posts, nós manteremos uma tecnologia só: MS.NET para UI e Runtime. Para simplificação.
*Nota: Se o objetivo fosse ter um conector que também executasse na versão Linux do Magic xpi, o módulo "Runtime" dele teria de ser Java ou Magic xpa
Iniciando com o Connector Builder
Esta é a tela inicial do Connector Builder e à medida que formos adicionando novos componente ( com o botão [+] ), eles ficarão listados aqui.
Todo componente criado com este framework fica localizado na pasta “Runtime\addon_connectors“, na instalação do Magic xpi.
Um detalhe importante (curioso até), é que o Connector Builder extrai o local de instalação a partir do Registro do Windows, da chave:
HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\MSE\Magic xpi\InstallPath
Então é necessário que esta informação esteja apontando para a pasta correta (da sua instalação), especialmente se você possuir várias versões do Magic xpi na mesma máquina.
Adicionando o novo componente ( com o botão [+] ), vamos iniciar a sua definição na pasta “Geral Details“:
Name: O nome do nosso componente
Description: Uma descrição breve do que ele é, e seu propósito
Icon: Usando o botão assistente (do lado), vamos selecionar um imagem do tipo GIF, de tamanho 48×48 para ser o ícone deste componente no Magic xpi Studio.
Toolbox Group: Escolhemos em qual grupo da caixa de ferramentas do Magic xpi Studio este componente deve aparecer.
Include Step: Ligamos esta opção, se nosso componente pode ser usado na área de Steps dos fluxos de integração do projeto. No nosso caso, sim, vamos “ligar“.
Include Trigger: Ligamos esta opção, se nosso componente pode ser usado na área de Triggers dos fluxos de integração do projeto. No nosso caso, não, vamos deixar “desligado“.
Include Resource: Ligamos esta opção, se nosso componente precisa de algum Resource do projeto para o seu funcionamento. No nosso caso, sim, vamos “ligar“.
Completada esta primeira aba, podemos já clicar em “Save“. Isso vai gravar nossas alterações (ainda que sejam parciais) do componente.
*Nota: é normal alguns alertas neste momento, de que há pendências na definição do componente. Afinal, só completamos a 1a aba.
Com esta primeira gravação, já vai ocorrer o seguinte:
Uma pasta com o nome do componente (Curl) será criada dentro de “Runtime\addon_connectors“, com uma estrutura já pré-definida:
icons: para as imagens do componente
runtime\dotnet\lib para o módulo de execução (Magic xpi Server) usar, quando a tecnologia escolhida for “MS.NET“.
runtime\java\lib e runtime\java\classes, para o módulo de execução (Magic xpi Server) usar, quando a tecnologia escolhida for “Java“.
runtime\magic\lib para o módulo de execução (Magic xpi Server) usar, quando a tecnologia escolhida for “Magic xpa“.
ui\lib para o módulo de desenho (Magic xpi Studio) usar.
*Nota: estra estruturação é necessária ao Magic xpi, e estas pastas não devem ser removidas ou renomeadas.
Falando mais sobre “icons“, se além do GIF nós também disponibilizarmos uma imagem PNG de 48×48:
este PNG é usado dentro do Connector Builder junto ao nome do componente:
Ok, passemos agora para a próxima pasta (aba), a “Step“.
Esta pasta existe justamente porque ligamos a opção “Include Step”:
UI Type: Existem duas opções. A “Static“, é uma interface que será provida pelo Magic xpi Studio, e que não precisaremos codificar nada a respeito.
É a interface clássica “Method“, como quando estamos configurando o envio de um email por exemplo.
Nós vamos escolher aqui a “Dynamic“, e iremos criar do zero a interface de configuração. Mas para saber como seria a interface “Static” (a que não precisamos desenhar), segue um exemplo:
*Nota: a forma de definir o componente muda bastante, em função da sua UI ser "dynamic" ou "static". Não abordaremos a interface "static" nesta série.
UI Implementation Class: Por ter escolhido a UI “Dynamic“, temos de dizer o nome da classe MS.NET que iremos criar e disponibilizar ao Magic xpi Studio, para ele executar a interface de configuração durante o desenho dos fluxos de integração.
No botão assistente (do lado), clicamos e definimos uma pasta para a geração do “código fonte” desta classe:
*Nota: por praticidade e organização, manteremos os fontes deste projeto na pasta "Runtime\addon_connectors\CUrl\src\ui". Mas não é obrigatório.
O Connector Builder vai gerar o esqueleto de um projeto MS.NET, de onde deveremos partir e codificar a interface (UI) de configuração.
Runtime Tecnology: É aqui que diremos se o módulo de runtime (que será invocado pelo Magic xpi Server) será Java, Magic xpa ou MS.NET. Nós escolheremos o .NET.
No botão assistente (do lado), clicamos e definimos uma pasta para a geração do “código fonte” desta classe definida:
*Nota: por praticidade e organização, manteremos os fontes deste projeto na pasta "Runtime\addon_connectors\CUrl\src\runtime". Mas não é obrigatório.
O Connector Builder vai gerar o esqueleto de um projeto (Java, MS.NET ou Magic xpa), de onde deveremos partir e codificar a lógica de negócio deste componente.
Resources: Como definimos anteriormente que o componente necessitará de um Resource do projeto, deixamos estas opções ligadas.
Completada esta segunda aba, podemos clicar em “Save“. Isso vai gravar nossas alterações (ainda que sejam parciais) do componente.
Ok, passemos agora para a próxima pasta (aba), a “Resources“.
Esta pasta existe justamente porque ligamos a opção “Include Resource”:
Name: O nome do recurso que criaremos para uso pelo componente.
Description: Uma descrição breve do que ele é, e seu propósito
Propriedades do Recurso
Name: Nome da propriedade (ou campo).
Type: O tipo de dado Magic xpi (Alpha, Time, Numeric, etc…) que vai guardar esta informação. O nosso aqui será ALPHA.
Picure: A máscara de entrada e tamanho máximo deste dado. O nosso aqui será 1000.
Value Selection Type: Como será o tipo de entrada que o usuário fará. Se por uma lista fixa de opções (Combo), ou entrada livre (Expression). Vamos usar aqui o Expression.
Flags: Várias opções de features disponíveis. Vamos marcar “Mandatory” (exigir esta informação), e “Env Vars” (permite informar variáveis de ambiente). Existem outras opções, que podem ser interessantes em alguns casos. Se você já viu nos Resources do projeto, propriedades que somem ou aparecem conforme escolhas vão sendo feitas, isso é por conta do flag “Depends On”.
Botões do Recurso
Nós não vamos utilizar em nosso exemplo, mas é possível adicionarmos botões para o recurso.
Por exemplo, diversos recursos dos projetos Magic xpi possuem o botão “Validate“.
Quando definimos botões (um ou vários), no módulo UI devemos escrever também o código para responder a cada clique do usuário neles.
Completada esta terceira aba, podemos clicar em “Save“. Isso vai gravar nossas alterações (ainda que sejam parciais) do componente.
O que definimos nesta tela foi um recurso com uma propriedade chamada “Url“, que identificará o webSite que o componente deverá acessar quando executado.
Ok, passemos agora para a próxima pasta (aba), a “Errors“.
Todo componente do Magic xpi tem a missão de executar uma determinada operação (lógica de negócio). E por diversos motivos, essa operação pode não ser completada.
E os componentes tem por definição, que informar estas exceções ao Magic xpi Server através de um sistema de códigos, para que o Error Handling do fluxo de integração pode ser ativado.
Com os componentes customizados através do Connector Builder não é diferente.
Nesta tela, definimos uma sequência de códigos de erros representando situações que antecipadamente podemos prever que têm chance de falhar. A sinalização desta exceção estará a cargo do código que iremos escrever para o componente (módulo Runtime), e o Magic xpi Server irá identificar e compreender que o componente está avisando sobre uma falha (inconformidade), através das informações que retornarão nas variáveis C.sys.ErrorCode e C.sys.ErrorDescription.
Em nosso exemplo, definiremos uma única situação de anormalidade que será “programa CUrl falhou”, identificada pelo código 56000.
Completada esta quarta aba, podemos clicar em “Save“. Isso vai gravar nossas alterações (agora comletas) do componente.
Todas estas definições do novo componente vão sendo salvas na pasta deste componente, no arquivo “metadata.xml“:
e por causa disso, da existência deste arquivo nesta pasta, já conseguiremos ver o novo componente no Magic xpi Studio:
Mas lembre-se: só fizemos a definição do novo componente até aqui.
Não criamos o código da interface (módulo UI) dele, então ele não pode ainda ser configurado no Magic xpi Studio.
Tampouco criamos o código das regras de negócio (módulo Runtime) dele, então ele não pode ainda ser executado pelo Magic xpi Server.
E estas são as etapas que deixaremos para as próximas publicações 🙂
Aguarde a parte II!
Quer dar uma sneak peak no código do componente, com o que foi visto até aqui? Baixe-o deste endereço.
Mas não se esqueça: você já pode vê-lo, mas ainda não pode tocá-lo!
Para receber os artigos do Blog Magic Brasil em primeira mão no seu email, registre-se aqui