Módulo principal do plugin em Python

O plugin deve ter um módulo principal onde são implementadas as funções abaixo.

* Definições obrigatórias no plugin

PLUGIN_GLOBAL

PLUGIN_GLOBAL = 1

Define se o plugin é Global.

Um plugin global é ativado/desativado para todas as estações do sistema.

Se o valor for 0 (zero) ou a variável não for criada o plugin é considerado não global.

PLUGIN_NAME

PLUGIN_NAME = 'NomeDoPlugin'

Define o nome do plugin.

Este nome é usado para identificar o plugin internamente.

Limite: 30 caracteres.

Esta declaração sempre deve existir no plugin.

PLUGIN_VERSION

PLUGIN_VERSION = '1.0.0.0'

Define a versão do plugin.

A versão deve ser no formato N.N.N.N.

Esta declaração sempre deve existir no plugin.

ativar

def ativar(maquina):
	pass

Informa que o plugin foi ativado para uma máquina.

Parametro	Descrição
maquina	ID da máquina ativada.

Nenhum

atualizar

Esta função tornou-se obsoleta e não é mais executada.

Para atualizar um plugin deve-se utilizar os scripts no pacote de distribuição cmpkg.

def atualizar():
	return ''

Avisa o plugin para se atualizar.

Esta função é automaticamente chamada quando um dos três primeiros dígitos* do PLUGIN_VERSION, for incrementado.

* 'N.N.N.N"

Nenhum

Um texto vazio ou um JSON com uma mensagem de erro, caso ocorra alguma falha:

{
  "erro" : "Mensagem de erro"
}

configurar

def configurar(maquinas):
	pass

Abre o diálogo de configuração do plugin.

Parametro	Descrição
maquinas	Texto com dicionário JSON contendo a lista de máquinas em que o plugin está ativo {'maquina_atual': 1, 'maquinas': {1: 'SALAO', 1: 'BAR'}} maquina_atual - ID da máquina que está rodando a configuração maquinas - dicionário contendo o ID e o NOME das maquinas em que o plugin está ativado

Nenhum

configurar_db

def configurar_db(servidor, banco, usuario, senha, provedor):
	pass

Fornece os parâmetros da base de dados do Colibri.

Esta função é chamada apenas uma vez, na inicialização do plugin.

Parametro	Descrição
servidor	Nome ou endereço do servidor de banco de dados
banco	Nome do banco de dados
usuario	Usuário para acesso
senha	Senha para acesso
provedor	Provedor de banco de dados

Nenhum

desativar

def desativar(maquina):
	pass

Informa que o plugin foi desativado para uma máquina.

Parametro	Descrição
maquina	ID da máquina desativada.

Nenhum

notificar

def notificar(evento, contexto):
	return ''

Notifica o plugin de um dos eventos assinados.

Para saber mais consulte Eventos disponíveis.

Parametro

Descrição

evento

Identificação do evento assinado.

contexto

Texto json com o contexto(informações) do evento

Para saber mais consulte Eventos disponíveis

Um texto vazio ou um JSON com um ou mais campos a seguir:

{
  "erro": "Mensagem de erro",
  "acao": "tipo da acao",
  "modificadores": {
    "chave1" : "valor",
    "chave2" : "valor"
  }
}

Chave

Descrição

Obrigatório

erro

Em caso de erro, indica uma mensagem de erro a ser exibida pelo Colibri.

acao

Uma ação a ser executada pelo Colibri:

abort - Suspende a execução da ação em curso.

modificadores

Valores alterados das chaves modificadoras.

As chaves modificadoras são enviadas no contexto do evento e podem ser alteradas pelo plugin

obter_dados_fabricante

def obter_dados_fabricante():
	return ''

Obtém os dados do fabricante com informações de licenciamento e dados de suporte.

Esta função sempre deve existir no plugin.

Nenhum

Um JSON com os dados do fabricante e de suporte.

{
  "fabricante":{
    "empresa":"Fornecedora",
    "desenvolvedor":"Equipe",
    "termos_da_licenca":"",
    "direitos_de_copia":"",
    "marcas_registradas":""
  },
  "suporte":{
    "email":"suporte@empresa.com",
    "url":"",
    "telefone":"(XX)9999-9999"
  }
}

Chave fabricante

Estes dados são opcionais e podem ser exibidos ao cliente.

empresa	Texto	Nome da empresa do plugin
desenvolvedor	Texto	Equipe ou desenvolvedor
termos_da_licenca	Texto	Texto livre com a licença do plugin
direitos_de_copia	Texto	Texto livre com informações de copyright do plugin
marcas_registradas	Texto	Texto livre com informações sobre marcas registradas

Chave suporte

Deve ser especificada ao menos uma forma de contato com suporte.

Essa informação pode ser exibida ao cliente.

email	Texto	E-mail de contato para suporte
url	Texto	Url para obter suporte
telefone	Texto	Telefone de suporte, com código de área

obter_dados_licenca

def obter_dados_licenca(info):
	return ''

Obtém os dados de licenciamento.

Parametro	Descrição
info	Reservado para Informações adicionais

Um JSON com os dados da licença.

{
  "chave_extensao":"6cb6f508-91d3-4e49-8444-c4a6a2230cf2"
}

Chaves

chave_extensao

Texto

GUID da extensão. É gerada automaticamente no Market Place quando uma extensão é registrada.

obter_dados_REST

def obter_dados_REST():
	return ''

Esta função é chamada nos plugins tipo server para obter os dados de configuração dos serviços REST fornecidos pelo plugin.

Assim, é possível definir os caminhos redirecionados para a função TratarREST / tratar_REST do plugin.

Se esta função não existir no plugin, haverá um único caminho implementado com o nome do plugin:

http://servidor-cis:porta-cis/NomeDoPlugin/qualquer_recurso/

Nenhum

Um JSON com os dados de configuração dos serviços REST:

{
  "caminhos":[
     "MeuCaminhoRest1",
     "MeuCaminhoRest2"
   ]
}

Onde:

Variável Tipo Descrição

caminhos

Lista

Lista de caminhos que serão redirecionados para a função TratarREST do plugin. Em caso de omissão haverá um único caminho com o NomeDoPlugin.

Exemplo:

http://servidor-cis:porta-cis/Caminho/qualquer_recurso/

Importante!

Os nomes dos caminhos devem ser escolhidos com cuidado para evitar conflito com caminhos definidos por outros plugins. Evite nomes genéricos ou não relacionados ao produto/empresa (por exemplo, 'cadastro', 'api', 'servico' não são boas escolhas). Contudo, os caminhos internos são de uso livre pois estão sob domínio do plugin, ex: /ACME/cadastro

obter_macro

def obter_macro(uma_macro):
	return ''

Obtem o valor de uma macro do plugin.

Para saber mais sobre macros acesse Injetando elementos visuais :: Macros.

Parametro	Descrição
uma_macro	Macro a substituir.

Um JSON com o valor da macro:

{
  "valor": "Valor da macro"
}

Se a macro não for localizada o campo valor deve ser omitido ou o retorno deve ser vazio.

obter_verificacoes

def obter_verificacoes():
	return ''

Objetivo

Obtém a lista de verificações disponíveis para o checklist desse plugin no Launcher.

Parâmetros

Nenhum

Retorno

Uma lista de verificações e seus respectivos IDs.

Em Python a codificação deve ser cp1252.
Em DLL este valor de retorno deve nulo ou um buffer criado por AlocarBuffer

{
  "verificacoes":[
    {
      "id":1,
      "descricao":"Falta configurar a gaveta em algum terminal?"
    },
    {
       "id":2,
       "descricao":"Este terminal está se comunicando com a gaveta?"
    }
  ]
}

registrar_assinaturas

def registrar_assinaturas():
	pass

Solicita ao plugin que assine os eventos do Colibri.

O plugin deve chamar colibri.assinar_evento para os eventos que deseja assinar.

Para saber mais consulte Eventos disponíveis

Nenhum

Nenhuma

registrar_assinaturas_server

def registrar_assinaturas_server():
	pass

Solicita ao plugin que assine os eventos do Servidor Colibri.

O plugin deve chamar colibri.assinar_evento para os eventos que deseja assinar.

Essa função faz parte dos requisitos para que um plugin funcione no CIS.

Para saber mais consulte Eventos disponíveis

Nenhum

Nenhuma

registrar_permissoes

def registrar_permissoes():
	return ''

Obtém as permissões do plugin a serem disponibilizadas no sistema de permissões do Colibri.

Nenhum

Um JSON com as permissões.

{
   "descricao_plugin":"Plugin X",
   "id":"0a0a0a0a-0a0a-0a0a-0a0a-0a0a0a0a0a0a",
   "permissoes":[
      {
         "descricao":"Descrição da Permissão",
         "id":"0a0a0a0a-0a0a-0a0a-0a0a-0a0a0a0a0a0a",
         "grupos_liberados":[
            -1,
            -2,
            -3
         ],
         "modo_venda":0
      },
      {
         "descricao":"Nível superior",
         "id":"0a0a0a0a-0a0a-0a0a-0a0a-0a0a0a0a0a0b",
         "grupos_liberados":[
            -1,
            -2,
            -3
         ],
         "modo_venda":0,
         "permissoes":[
            {
               "descricao":"Permissão aninhada",
               "id":"0a0a0a0a-0a0a-0a0a-0a0a-0a0a0a0a0a0c",
               "grupos_liberados":[
                  -1,
                  -2,
                  -3
               ],
               "modo_venda":0
            }
         ]
      }
   ]
}

Onde:

Variável	Tipo de dado	Descrição
descricao_plugin	Texto	Descrição do plugin na tela de configuração
descricao	Texto	Descrição da permissão
id	Texto	Id único (GUID) da permissão
grupos_liberados	Lista	Lista de ids de grupos de usuários liberados por padrão para essa permissão
modo_venda	Inteiro	Modo de venda aplicável ou;
modos_venda	Lista	Lista de modos de venda aplicáveis
permissoes	Lista	Lista de sub-permissões, usados quando for uma permissão de primeiro nível

tratar_REST

def tratar_REST(uma_requisicao):
	return ''

Esta função é chamada como resultado de um redirecionamento de requisição REST. Se esta função existir no plugin, ao acionar um recurso com a URL:

http://servidor-cis:porta-cis/Caminho/qualquer_recurso/

a requisição será repassada ao plugin correspondente através da chamada desta função.

Para especificar o Caminho, é necessário implementar a função ObterDadosREST / obter_dados_REST.

Caso contrário, por padrão o caminho será o NomeDoPlugin.

Parametro	Descrição
uma_requisicao	Dados da requisição.

Sendo uma_requisicao um JSON Onde:

Variável	Descrição
Host	Host da requisição
Password	Senha da requisição
Username	Usuário da requisição
URI	URI da requisição
Command	Tipo do comando REST
ContentType	Tipo de conteúdo da requisição
UserAgent	User agent da requisição
AuthPassword	Senha de autenticação
AuthUsername	Usuário de autenticação
CustomHeaders	Outros headers da requisição
PostStream	Buffer postado com a requisição

Um JSON com a requisição tratada:

{
  "StatusCode": 200,
  "Content": "{}"
}

Onde:

Variável	Tipo	Descrição
StatusCode	Inteiro	Código http de retorno da resposta
Content	Texto	Conteúdo de retorno da resposta
ContentType	Texto	Tipo de conteúdo retornado. Se omitido será assumido application/json

Se a URI ou método não for implementado pelo plugin, deve-se retornar vazio.

verificar_problemas

def verificar_problemas(id):
	return ''

Executa uma verificação do check list desse plugin no Launcher.

Parâmetros

id	ID da verificação a executar

Retorno

O plugin deve retornar um JSON com resultado da verificação ou mensagem de erro.

Atributo	Significado
mensagem	Mensagem em caso de sucesso ou erro.
status	OK - verificação passou Falha - verificação falhou

Exemplo de retorno

{
   "mensagem": "Porta verificada com sucesso",
   "status": "OK"
}

Em Python a codificação deve ser cp1252.
Em DLL este valor de retorno deve nulo ou um buffer criado pela rotina AlocarBuffer().

verificar_versao

def verificar_versao(informacao):
	return ''

Verifica se o plugin é compatível com a versão do Colibri.

Em caso de incompatibilidade ou inconformidade permite interromper a carga do plugin.

Saiba mais em Versão do gerenciador de plugins

O parãmetro informação é um JSON com informações sobre o ambiente de carga do plugin:

chave

descrição

versao

Versão do gerenciador de plugins

maquina

ID da máquina

(somente a partir da versão 1001 do GP)

ativando

True, se o plugin estiver sendo carregado para ser ativado no Colibri

False, se o plugin estiver sendo carregado para ser configurado.

(somente a partir da versão 1001 do GP)

Um texto vazio ou um JSON com uma mensagem de erro:

{
  "erro": "Este plugin não é compatível com a versão x do Colibri"
}

Caso seja retornada uma mensagem, esta será exibida ao cliente e a carga do plugin não continuará.

Observação

Em Python: codificação deve ser cp1252

Em DLL: Este valor de retorno deve nulo ou um buffer criado por AlocarBuffer

Content

Ferramentas de Espaço

Breadcrumbs

Módulo principal do plugin em Python

PLUGIN_GLOBAL

PLUGIN_NAME

PLUGIN_VERSION

ativar

atualizar

configurar

configurar_db

desativar

notificar

obter_dados_fabricante

obter_dados_licenca

obter_dados_REST

obter_macro

obter_verificacoes

Objetivo

Parâmetros

Retorno

registrar_assinaturas

registrar_assinaturas_server

registrar_permissoes

tratar_REST

verificar_problemas

Parâmetros

Retorno

verificar_versao