No BPA é possível adicionar um número ilimitado de plugins. Os plugins adicionados podem ser utilizados para adicionar novas funcionalidades na criação de processos ou também para executar regras específicas do seu fluxo, como por exemplo, realizar requisições em uma API externa.
Plugin é um programa de computador geralmente utilizado como extensão de outros programas para adicionar funções e regras de negócios específicas. Saiba mais.
Saiba como utilizar os plugins nos fluxos de processos, clicando aqui.
Navegue para a página de gerenciamento dos plugins utilizando a opção do menu lateral "Gerenciar plugins". Nesta página está localizado a listagem de todos os plugins e as funcionalidades como: adicionar, atualizar, desativar e excluir.
Caso o menu não apareça para você, é provável que seu usuário não tenha permissão de acesso. Saiba mais.
Caso clique sobre um plugin, será aberta a tela de detalhes deste plugin. Nesta tela é exibida todas as informações e atributos (entrada e saída) que o plugin possui.
O Beew4y disponibiliza alguns plugins prontos e para diferenciar dos outros, possuem a marcação "Plugin Oficial". Além disso, esses plugins não podem ser atualizados e excluídos, apenas desativados.
¶ Novo Plugin
Os plugins desenvolvidos para a plataforma Beew4y devem ser escritos em linguagem C# (.Net Core 3.1) e também devem seguir os padrões que serão explicados em detalhes ainda nesta documentação.
O .NET Framework é uma iniciativa da empresa Microsoft, que visa uma plataforma única para desenvolvimento e execução de sistemas e aplicações. Uma das linguagens suportadas pelo .Net é a C#, uma linguagem de programação poderosa, multiparadigma, de tipagem forte. Saiba mais.
Com o intuito de facilitar o desenvolvimento de um novo plugin, é disponibilizado em tela o botão "Dowload Modelo", clique neste botão para fazer dowload de um modelo de exemplo.
¶ Criando um novo Plugin
Todos os plugins criados para executar no BPA, devem seguir a estrutura do modelo baixado na tela de plugin.
Essa estrutura utiliza uma biblioteca (dll) nativa do Beew4y chamada "beew4y.BPA.Essential" que contém classes e interfaces que permitem a criação de Assemblies em .Net Core. Dessa forma, permitindo o usuário criar classes totalmente customizáveis com suas regras de negócio e serviços. Para personalizar a classe e propriedades do seu plugin, utilize os atributos disponíveis da nossa biblioteca.
Na classe do plugin utilize o namespace beew4y.BPA.Task
¶ Atributos para a Classe
- StepDefine
Para organização, no BPA os plugins são separados em quatros tipos:
- Regra de Negócio
- Recebimento de Mensagem
- Envio de Mensagem
- Tarefa Autônoma
O "StepDefine" define qual é o tipo do plugin. Adicione esse atributo na classe de seu plugin, passando como parâmetro o enum "StepType" que representa o tipo do plugin. Por exemplo:
namespace beew4y.BPA.Task
{
[StepDefine(StepType.BusinessRule)]
public class PluginTreinamento : IStepTask
{
...
}
}
Os valores do enum "StepType" são:
public enum StepType
{
BusinessRule = 0, //Regra de Negócio
ReceiveMessageTask = 1, //Recebimento de Mensagem
SendMessageTask = 2, //Envio de Mensagem
ServiceTask = 3 //Tarefa Autônoma
}
- Version
O atributo "Version" define qual é a versão do plugin. Adicione esse atributo na classe de seu plugin, passando como parâmetro uma string. Por exemplo:
namespace beew4y.BPA.Task
{
[Essential.Version("1.0")]
public class PluginTreinamento : IStepTask
{
...
}
}
- Translate
O atributo "Translate" define qual é o nome do plugin para os três idiomas disponíveis no Beew4y. Adicione esse atributo na classe de seu plugin, passando como parâmetro o enum "Idiom" que indica o idioma e também uma string. Por exemplo:
namespace beew4y.BPA.Task
{
[Translate(Idiom.Portuguese, "Plugin de Treinamento")]
[Translate(Idiom.English, "Training plugin")]
[Translate(Idiom.Spanish, "Plugin de formación")]
public class PluginTreinamento : IStepTask
{
...
}
}
- Description
O atributo "Description" define uma descrição do plugin para os três idiomas disponíveis no Beew4y. Adicione esse atributo na classe de seu plugin, passando como parâmetro o enum "Idiom" que indica o idioma e também uma string. Por exemplo:
namespace beew4y.BPA.Task
{
[Description(Idiom.Portuguese, "Este é um plugin para treinamento.")]
[Description(Idiom.English, "This is a training plugin.")]
[Description(Idiom.Spanish, "Este es un plugin de formación.")]
public class PluginTreinamento : IStepTask
{
...
}
}
- Image
O atributo "Image" define que o plugin possui uma imagem. Caso seu plugin tenha uma imagem, adicione esse atributo na classe, passando como parâmetro uma string (caminho da imagem). Por exemplo:
namespace beew4y.BPA.Task
{
[Image("Images\\beew4y.png")]
public class PluginTreinamento : IStepTask
{
...
}
}
O caminho indicado na string deve existir em sua solução.
É importante que através do Visual Studio seja configurado para a imagem ser sempre copiada no diretório de saída. Por exemplo:
¶ Atributos para as Propriedades
Utilize os atributos da nossa biblioteca também nas propriedades da classe do seu plugin, esses atributos são:
- Input
O atributo "Input" define que a propriedade é um parâmetro de entrada do plugin. Com isso, ao utilizar o plugin nos fluxos do processo, as propriedades que possuem esse atributo se tornaram um campo de entrada onde o usuário poderá inserir valores ou expressões.
Adicione esse atributo nas propriedades da sua classe, passando como parâmetro o enum "PropertyType" que indica o tipo do campo de entrada e também uma string parar definir o nome do campo. Por exemplo:
public class PluginTreinamento : IStepTask
{
[Input(PropertyType.String, "InputExemplo")]
public String InputExemplo { get; set; }
...
}
Os valores disponíveis no enum "PropertyType" são:
public enum PropertyType
{
Boolean = 0,
Char = 1,
DateTime = 2,
Decimal = 3,
Double = 4,
Float = 5,
Int32 = 6,
Int64 = 7,
Long = 8,
Object = 9,
String = 10
}
O tipo indicado através do enum PropertyType deve ser igual ao tipo da propriedade.
O nome indicado no atributo deve ser o mesmo nome da propriedade.
- Output
O atributo "Output" define que a propriedade é um parâmetro de saída do plugin, com isso ao utilizar o plugin nos fluxos de processo, as propriedades que possuem esse atributo se tornaram as propriedades do objeto "Result", dessa forma permitindo a utilização dos valores de saída em outras passos do fluxo.
Saiba mais sobre o objeto Result clicando aqui.
Adicione esse atributo nas propriedades da sua classe, passando como parâmetro o enum "PropertyType" que indica o tipo do campo de saída e também uma string parar definir o nome do campo. Por exemplo:
public class PluginTreinamento : IStepTask
{
[Output(PropertyType.String, "OutputExemplo")]
public String OutputExemplo { get; set; }
...
}
Os valores disponíveis no enum "PropertyType" são:
public enum PropertyType
{
Boolean = 0,
Char = 1,
DateTime = 2,
Decimal = 3,
Double = 4,
Float = 5,
Int32 = 6,
Int64 = 7,
Long = 8,
Object = 9,
String = 10
}
O tipo indicado através do enum PropertyType deve ser igual ao tipo da propriedade.
O nome indicado no atributo deve ser o mesmo nome da propriedade.
As propriedades que utilizam o atributo Output devem sempre retornar um valor.
- DefaultValue
O atributo "DefaultValue" define um valor padrão para as propriedades de entrada do plugin. Adicione esse atributo nas propriedades entrada da sua classe, passando como parâmetro um valor coerente com o tipo da propriedade. Por exemplo:
public class PluginTreinamento : IStepTask
{
[DefaultValue("Aqui é o valor padrão")]
[Input(PropertyType.String, "InputExemplo")]
public String InputExemplo { get; set; }
...
}
- Translate
O atributo "Translate" já explicado anteriormente também serve para definir um nome para as propriedades do plugin. Por exemplo:
public class PluginTreinamento : IStepTask
{
[Translate(Idiom.Portuguese, "Campo de exemplo")]
[Translate(Idiom.English, "Example field")]
[Translate(Idiom.Spanish, "Campo de ejemplo")]
[Input(PropertyType.String, "InputExemplo")]
public String InputExemplo { get; set; }
...
}
Caso a propriedade não tenha o atributo Translate, será utilizado como nome do campo o nome da propriedade.
- Required
O atributo "Required" define como obrigatório a inserção de valores nas propriedades de entrada do plugin. Este atributo não possui parâmetros, basta apenas adicionar nas propriedades entrada da sua classe. Por exemplo:
public class PluginTreinamento : IStepTask
{
[Required]
[Input(PropertyType.String, "InputExemplo")]
public String InputExemplo { get; set; }
...
}
- Options
O atributo "Options" define que a propriedade de entrada no fluxo de processo será uma lista de opções(combobox). Adicione esse atributo nas propriedades de entrada da sua classe, passando como parâmetro a descrição da opção e valor. Por exemplo:
public class PluginTreinamento : IStepTask
{
[Options("Primeira Opção", 1)]
[Options("Segunda Opção", 2)]
[Options("Terceira Opção", 3)]
[Input(PropertyType.Int, "InputExemplo")]
public Int InputExemplo { get; set; }
...
}
Caso a descrição das opções tenha que ser exibida nos três idiomas disponíveis no Beew4y, passe como parâmetro as três descrições necessárias e por último o valor. Por exemplo:
- //PT
[Options("Primeira Opção", 1)]
- //PT //EN
[Options("Primeira Opção", "First option", 1)]
- //PT //EN //ES
[Options("Primeira Opção", "First option", "Primera Opción", 1)]
No parâmetro que define o valor da opção, deve ser informado um valor coerente com o tipo da propriedade.
- Order
O atributo "Order" define a ordem que as propriedades de entrada serão exibidas para o usuário ao utilizar o plugin em fluxos de processo. Adicione esse atributo nas propriedades entrada da sua classe, passando como parâmetro a posição da propriedade. Por exemplo:
public class PluginTreinamento : IStepTask
{
[Order(1)]
[Input(PropertyType.String, "InputExemplo")]
public String InputExemplo { get; set; }
[Order(2)]
[Input(PropertyType.String, "InputExemplo2")]
public String InputExemplo2 { get; set; }
...
}
- List
O atributo "List" define que a propriedade de entrada é uma lista, com isso ao utilizar o plugin nos fluxos de processo, o usuário poderá inserir um ou vários valores para a mesma propriedade. Este atributo não possui parâmetros, basta apenas adicionar nas propriedades entrada da sua classe. Por exemplo:
public class PluginTreinamento : IStepTask
{
[List]
[Input(PropertyType.String, "InputExemplo")]
public List<String> InputExemplo { get; set; }
...
}
É permitido utilizar o atributo List apenas em propriedades que são listas.
- Password
O atributo "Password" define que o valor da propriedade deve ser criptografado. Este atributo não possui parâmetros, basta apenas adicionar nas propriedades entrada da sua classe. Por exemplo:
public class PluginTreinamento : IStepTask
{
[Password]
[Input(PropertyType.String, "InputExemplo")]
public String InputExemplo { get; set; }
...
}
¶ Interface IStepTask
A classe de seu plugin deve utilizar a interface da nossa biblioteca chamada "IStepTask". As classes que utilizam essa interface obrigatóriamente deve possuir o método chamado "Execute" que possui um objeto dinâmico como parâmetro. Por exemplo:
namespace beew4y.BPA.Task
{
public class PluginTreinamento : IStepTask
{
public void Execute(dynamic bo)
{
}
}
}
O parâmetro do método "Execute" é na realidade o "BO (Business Object)", sendo assim, é possível dentro do método trabalhar com o "BO" que percorre por todos os passos do fluxo durante uma instância. Implemente as regras de negócio e serviços do seu plugin, dentro do metódo "Execute", utilizando as propriedades de entrada e saída e também o "BO" de acordo com sua necessidade.
No exemplo a seguir, dentro do metódo "Execute" são utilizados as propriedades de entrada e saída do plugin e também o "BO" que está percorrendo na instância do fluxo que executou o plugin.
public class PluginTreinamento : IStepTask
{
[Input(PropertyType.Int32, "Valor")]
public Int32 Valor { get; set; }
[Output(PropertyType.Int32, "Resultado")]
public Int32 Resultado { get; set; }
public void Execute(dynamic bo)
{
if (!bo.Calculado)
{
Resultado = Valor * 100;
bo.Calculado = true;
}
}
}
O BO (Business Object) pode receber apenas objetos do tipo dinâmico.
Saiba mais sobre o BO (Business Object) clicando aqui.
¶ Arquivo Config
O plugin deve contér um arquivo JSON chamado "Config", neste JSON adicione as propriedades "mainDll" e "Author". Por exemplo:
{
"mainDll": "PluginTreinamento.dll",
"Author": "Joao Sereno"
}
Na propriedade "mainDll" informe o nome da DLL principal do seu projeto (classe do seu plugin). O nome da DLL deve ser o mesmo que o da classe.
Na propriedade "Author" informe o nome do desenvolvedor do plugin.
Além disso, é importante que através do Visual Studio o arquivo seja configurado para sempre ser copiado no diretório de saída. Por exemplo:
¶ Compilando e Compactando
Após terminar o desenvolvimento do plugin, para finalizar compile sua solução. Com a compilação concluída, acesse a pasta indicada no caminho que é exibido na conclusão da compilação e copie esses arquivos em uma pasta separada. Nesta pasta separada também coloque o arquivo config.json e a pasta com a imagem do plugin.
Após isso compacte todos esses arquivos juntos em um arquivo .ZIP e adicione esse arquivo na plataforma Beew4y.
¶ Adicionando o Plugin
Com o plugin criado e compactado no formato .ZIP, acesse a tela de gerenciamento de plugins através do menu lateral e em seguida clique no botão "Novo Plugin".
Ao clicar será exibido em tela um modal de upload, neste modal clique no botão "Selec. Arquivo" e insira o plugin.
Após o carregamento clique no botão "Enviar" e com isso o plugin será adicionado no BPA e disponibilizado para utilização em qualquer fluxo de processo.
O Beew4y internamente valida se o plugin adicionado está seguindo os padrões da plataforma, caso tenha alguma inconsistência o plugin não será adicionado e será exibido a descrição do problema em tela. Por exemplo:
Neste tipo de caso, ajuste o problema informado, repita o processo de compilação e compactação do plugin e tente adicioná-lo novamente.
¶ Atualizar Plugin
Para atualizar um plugin, acesse a tela de gerenciamento de plugins e localize o plugin que será atualizado. Após localizar clique no botão "Atualizar".
Ao clicar será exibido em tela um modal de upload, neste modal clique no botão "Selec. Arquivo" e insira o plugin atualizado.
Após o carregamento clique no botão "Enviar" e em seguida para finalizar confirme a atualização do plugin clicando no botão "Substitutir".
O Beew4y internamente valida se o plugin atualizado está seguindo os padrões da plataforma, caso tenha alguma inconsistência a atualização do plugin não será concluída e será exibido a descrição do problema em tela. Por exemplo:
Neste tipo de caso, ajuste o problema informado, repita o processo de compilação e compactação do plugin e tente atualizar novamente.
¶ Desativar e Ativar Plugin
Todos os plugins possuem os status, os dois possíveis status são:
Ativado: Com o status ativado, o plugin pode ser utilizado normalmente na criação de fluxos de processos.
Desativado: Com o status desativado, o plugin se manterá no Beew4y, porém não será permitido utilizar ele na criação de fluxos de processos.
Para desativar ou ativar um plugin, acesse a tela de gerenciamento de plugins e localize o plugin. Após localizar clique no botão "Ativado" ou "Desativado" como no exemplo a seguir:
Não é permitido desativar plugins que estão vinculados a fluxos de processo. Caso tente desativar será apresentado em tela uma mensagem de erro e nesta mensagem será informado os processos que o plugin possui vínculo, neste tipo de caso, primeiro remova o plugin do processo e em seguida tente desativar novamente.
¶ Excluir Plugin
Para excluir um plugin, acesse a tela de gerenciamento de plugins e localize o plugin que será excluído. Após localizar clique no botão "Excluir".
Após clicar será necessário confirmar a exclusão.
Após a confirmação será apresentada a mensagem de sucesso.
Não é permitido excluir plugins que estão vinculados a fluxos de processo. Caso tente excluir será apresentado em tela uma mensagem de erro e nesta mensagem será informado os processos que o plugin possui vínculo, neste tipo de caso, primeiro remova o plugin do processo e em seguida tente excluir novamente.