Funções

Flexbundle permite a criação de funções javascript possibilitando a programação de lógicas de negócio personalizadas. Esta funcionalidade permite reduzir a necessidade de instalação e configuração de infraestrutura própria (servidores) visto que, a plataforma Flexbundle é responsável pelo gestão e execução destas funções.

Pode utilizar as funções para:

• Criar acções no flexbundle;

• Comunicar com clientes sobre o estado de um processo;

• Integrar com outros sistemas;

• Entre outras lógicas de negócio.

Para criar uma função seleccione a opção Configurações (1) > Funções (2) > Criar função (3).

Seguidamente, é apresentada uma página de configuração da função.

1 - Url (link) da função. Só é valido quando a função for criada.

2 - Campo para especificar o nome da função. Só deve conter caracteres alfanuméricos.

3 - Campo para especificar a descrição da função.

4 - Campo para especificar se a função é pública ou privada. Para mais informações consulte a documentação sobre a segurança das funções.

5 - Campo para especificar o método HTTP da função. Pode ser POST ou GET.

6 - Campo para especificação de variáveis de ambiente da função. Para mais informações consulte a documentação sobre as variáveis de ambiente.

7 - Campo para especificação do código da função.

O código de sua função recebe 3 parâmetros:

• context - o contexto para tratamento do pedido efetuado à função;

• resolve - função para terminar a função com sucesso;

• reject - função para terminar a função quando ocorrem erros;

Flexbundle disponibiliza recursos auxiliares para a concepção da função na variável $f:

• api - permite a interacção com os objectos do Flexbundle via API;

• email - permite o envio de notificações via email;

• helpers - fornece um conjunto de bibliotecas auxiliares para a programação de uma função;

Exemplo de uma função "Hello World" no Flexbundle:

function(context, resolve, reject) {
	const workspace = $f.api.asUser().workspace("<HELLO WORLD>"); 
	const payload = context.payload || {};
	const userInfo = context.userInfo || {};
	if(payload.sayHello) {
		workspace.create({col1: "Hello World from " + context.userInfo.name })
			.then(resolve)
			.catch(reject);
	} else {
		reject({error: "Not allowed to say hello to our world!"});
	}
}

Contexto de execução da função

Todos os pedidos efetuados à uma função possuem um contexto. Este contexto representa um objecto javascript composto por:

• userInfo - Objecto javascript contendo a informação do utilizador Flexbundle que accionou a função. Possui propriedades como id, nome e email.

• config - Objecto javascript contendo as variáveis de ambiente configuradas para a função.

• payload - JSON contento os dados fornecido pelo utilizador para o pedido.

Variáveis de ambiente

É possível definir um conjunto de variáveis de ambiente aquando da sua definição. Estas variáveis são exclusivas à função e são disponibilizadas no formato key/value aquando da execução da função.

Variáveis de ambiente são úteis para o armazenamento de configurações sensíveis como API Keys.

Exemplo de como aceder a uma variável de ambiente:

const apiKey = context.config.API_KEY;

Interagindo com Flexbundle

Para interagir com a plataforma Flexbundle, é necessário aceder ao api do Flexbundle.

const api = $f.api.asUser();

Por razões de segurança, Flexbundle obriga que o programador defina qual o escopo que pretende utilizar a api:

• asUser() - escopo que define que todas as interacções com Flexbundle sejam efetuadas em nome do utilizador que accionou a função;

• asAdmin() - escopo que define que todas as interacções com Flexbundle sejam efetuadas em nome do criador da função;

Quando o escopo asAdmin é utilizado, a função assume que o criador da função é o utilizador que fez a última alteração à função.

Após definição do escopo, o programador pode utilizar a API para interagir com Flexbundle. Esta api possuí a mesma interface de programação que o SDK do Flexbundle. Para mais informações, consulte a documentação do SDK.

Segurança

A execução de funções em Flexbundle possuí vários níveis de segurança.

Visibilidade da função

Uma função pode ser pública ou privada. Normalmente, uma função é privada, ou seja, somente os utilizadores autenticados de uma organização pode ter acesso a uma determinada função. No entanto, existem situações em que pode ser necessário uma função pública para que terceiros (utilizadores não autenticados) possam accionar uma determinada operação.

Utilize funções públicas para colectar informações dos seus clientes ou parceiros.

Escopo da API

Como já referido, o programador pode aceder uma determinada api utilizando o escopo do utilizador autenticado ou o escopo de administrador.

Normalmente deve-se utilizar, por defeito o escopo do utilizador, no entanto, existem situações em que é necessário efetuar uma operação em que o utilizador autenticado não possuí permissões para tal. Quando assim o é, o programador deve utilizar o escopo de administrador

Tokens temporários

Na maioria dos casos, o escopo da api servirá para garantir a segurança no acesso ao Flexbundle. No entanto, existem situações em que se pretende prevenir ao máximo o acesso acidental a workspaces e objectos não partilhados. Nestas situações, Flexbundle permite gerar tokens temporários com acessos temporários que podem ser definidos pelo programador.

const restrictedApi = $f.api.withCustomToken(
    $f.api.createCustomToken(
        {
            "<RESTRICTED_WORKSPACE_1>": "c",
            "<RESTRICTED_WORKSPACE_2>": "c,r,u,d"
        }
    )
);

Para cada workspace deve ser fornecido o nível de acesso permitido na função. Podem ser fornecidas várias permissões (separadas por vírgula) para um workspace.

Permissão	Descrição
c	Pode criar objectos do workspace
r	Pode buscar/pesquisar objectos do workspace
u	Pode editar objectos do workspace
d	Pode apagar objectos do workspace

Após executar as operações necessárias com o token temporário, deve-se invalidar o token utilizando para o efeito a instrução $f.api.denyCustomToken(<TOKEN>).

Envio de emails

É possível enviar notificações por email utilizando funções.

$f.email().fromName("Flexbundle Team")
				.to("[e-mail]")
				.replyTo("[e-mail]")
				.subject("Message from the future")
				.text("Tell Thor to aim for the head")
				.html("<b>Tell Thor to aim for the head</b>")
				.send().then(() => resolve())
				.catch(err => reject({error: "Error reaching the past!"}));

Métodos

Método	Descrição
fromName	Nome do remetente da mensagem
replyTo	O endereço para onde deve ser enviar as respostas à este email
subject	Assunto do email
text	Texto do corpo do email
html	Código html à enviar no corpo do email
send	Enviar email

Helpers

Flexbundle fornece um conjunto de bibliotecas auxiliares que pode ser utilizada na codificação de uma função.

const _ = $f.helpers.lodash; //lodash
const moment = $f.helpers.moment; //moment
const fetch = $f.helpers.fetch; //fetch
const xml2json = $f.helpers.xml2json; //xml2json

Bibliotecas

Biblioteca	Descrição
Lodash	https://lodash.com/docs
Moment	https://momentjs.com/docs/
Fetch	https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API
xml2json	Pequeno utilitário que permite a conversão simples de xml para json.