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. Conheça um pouco mais sobre ele, com este novo (3o)
artigo da série.
Ok. Estamos chegando lá e em breve seremos honesta e justamente habilitados no Connector Builder. Mas antes:
São passos muito importantes para o correto entendimento e aproveitamento do que será abordado a seguir. Abordaremos aqui a criação e codificação do módulo “Runtime” do nosso componente customizado.
Partindo do projeto MS.NET (StepRT.sln) que foi gerado pelo assistente, cfe. mostrado no artigo I, nós precisaremos definir e implementar 1 classe:
- runtime = classe (qualquer nome é válido, mas tem de respeitar o que foi definido nos metadados do componente), que precisa obrigatoriamente implementar a interface IStep.
Como precisamos implementar a interface IStep, a primeira ação é referenciar o assembly “XPI_SDK” disponibilizado pelo Magic xpi na pasta “Runtime\“:
Agora, vamos entender a implementação desta classe. Não iremos explicar o “código C#” usado no projeto, até porque você terá livre acesso a ele. Mas vamos explicar o funcionamento e propósito dela.
Classe runtime
Esta é a classe encarregada de executar as regras de negócio do conector. O Magic xpi Server vai instanciar esta classe e executar seu método invoke. Ao final desta execução, o Magic xpi Server entende que o trabalho, seja lá qual devesse ser, foi finalizado.
Caso o componente precise sinalizar que algo não ocorreu adequadamente, ele deve gerar uma exceção do dipo XPI_SDK.SDKException, com um código e uma descrição do ocorrido.
Os códigos utilizados devem estar dentro da lista definida nos metadados do componente (rever artigo I). Este código e mensagem preencherão as variáveis C.sys.ErrorCode e C.sys.ErrorDescription do fluxo de integração.
Método invoke
É o único método obrigatório da interface IStep. Ele recebe um único argumento, um objeto do tipo StepGeneralParams.
StepGeneralParams é um objeto que encapsula várias informações do ambiente de execução Magic xpi Server, bem como as configurações definidas no Magic xpi Studio para este componente.
Todas as proriedades de configuração não marcadas com o atributo [ExcludeFromRuntime], são disponibiliadas neste objeto como uma coleção de objetos UserProperty:
Um UserProperty disponibiliza informações como nome da propriedade, sua direção (input ou output), seu tipo de dados para o Magic xpi Server e seu valor:
Quando queremos ler o valor de uma propriedade da configuração, usamos o seu método: UserProperty.getValue().
Se a propriedado for do tipo output, podemos atualizá-la com métodos compatíveis com seu tipo interno de dados: UserProperty.setAlpha(), UserProperty.setNumeric() e assim por diante.
*Nota: o valor de uma propriedade (getValue()) pode ser "null", caso ela não esteja definida ou seu valor calculado no fluxo de integração seja de fato "NULL()"
Temos também acesso ao ResourceObject, um dicionario (coleção chave=valor), com informações do recurso associado ao nosso componente:
E ao EnvironmentSettings, outro dicionario com informações do ambiente e do contexto de execução do fluxo:
O StepGeneralParams também nos dá acesso ao PayloadObject. Recordando o artigo II, algumas das propriedades do componente podem ter sido configurada através de um DataMapper.
Neste caso, estas informações estarão todas disponíveis nesta propriedade (PayloadObject). O formato da informação vai depender de como definimos o “esquema” a usar neste DataMapper:
- Será uma coleção de linhas de texto, se o SchemaInfo foi “FlatFile“.
- Será um documento Xml, se o SchemaInfo foi “Xml“.
- Será um documento Json, se o SchemaInfo foi “JSon“.
Caso porém, tenha sido definido neste DataMapper que o resultado do mapeamento deveria ser armazenado em um “arquivo”, então estes valores não estarão no PayloadObject.
Estarão num arquivo em disco, cujo nome (completo) estará disponível na propriedade PayloadFile.
A partir daí, é campo livre para a criatividade. Dentro deste método devemos programar toda a lógica de negócio necessária.
No nosso caso, é uma sequência até simples de ações.
Primeiro extraímos as propriedades de configuração (são 15 no total) do componente:
Fazemos verificações básicas de informações que não podem estar faltando:
Chamamos uma outra rotina, incumbida de executar o programa/comando “curl“:
E por fim, atualizamos as propriedades output com as informações resultantes da operação:
Caso qualquer anormalidade ocorra nesta execução, convertemos isso em uma exceção XPI_SDK.SDKException:
E é isto! Está pronta nosso projeto “Runtime“, de regras de negócio para o nosso conector customizado.
Lembrando que o módulo compilado precisa ser colocado sempre na pasta “Runtime\addon_connectors\<componente>\runtime\dotnet\lib“:
E com a conclusão desta 3a. etapa, agora sim, nosso conector é totalmente “viável” e está pronto para ser usado.
Obtenha o código completo do componente. Baixe-o deste endereço.
O descanso do guerreiro
Criar um novo componente com o Connector Builder é sem dúvida uma jornada prazerosa para um desenvolvedor.
Mas tudo é sempre parte de um propósito maior. E estes componentes são desenvolvidos para empoderar os projetos de integração Magic xpi.
Então, vamos usá-lo!
Vamos exercitá-lo num fluxo simples:
Nós usaremos este conector para consumir um webService SOAP, de nome “UppercaseWordsWithToken” no endereço https://www.dataaccess.com/webservicesserver/TextCasing.wso.
É um webservice que recebe um texto de entrada e converte-o para maiúsculo:
Preparamos o envelope SOAP da forma que serviço espera (com o Flow Data) e configuramos o nosso conector “curl” para fazer este acesso:
E caso a chamada ocorra sem erros, gravamos no Magic xpi Monitor (com o Save Message) alguns detalhes do acesso e seus resultados.
Este é o resultado final desta execução:
Como nós configuramos a propriedade keepWorkingFiles como true, na pasta “temp” do Magic xpi ficaram disponíveis todas as informações trafegadas na comunicação:
E como configuramos a propriedade ComponentDebugOn como ‘Y‘, na pasta “logs” do Magic xpi ficou disponúvel um log da execução interna do conector:
Obtenha o código completo do projeto exemplo (Magic xpi 4.13). Baixe-o deste endereço.
Disponível também no GitHub ! Acesse: https://github.com/desenvmagicbr/Component-Store-Magicxpi-CUrl/tree/master
Mais adiante, iremos para a parte IV da série. Vamos abordar conectores de Triggers. Aguarde…
Para receber os artigos do Blog Magic Brasil em primeira mão no seu email, registre-se aqui