Métodos Nativos

Funções específicas para ajudá-lo a automatizar.

Funções contextuais para seu Jestor

Há muito que você pode fazer programando no Jestor, mas também há algumas coisas que você não pode codificar através de PHP puro.

Por exemplo, você não terá acesso direto ao próprio banco de dados. No entanto, o Jestor tem métodos nativos que permitem buscar, criar e atualizar informações no banco de dados do seu Jestor. São funções projetadas especificamente para ajudá-lo a manipular os dados do seu Jestor como quiser.

📘

Entendendo as funções

Embora as funções abaixo sejam muito fáceis de entender, é útil ter um conhecimento de como as funções funcionam em geral. Aqui está um link se você quiser ler mais sobre isso.

Funções: https://www.php.net/manual/en/language.functions.php

Quais são os métodos nativos do Jestor?

  • Jestor.fetch
  • Jestor.count
  • Jestor.fetchUsers
  • Jestor.fetchTasks
  • Jestor.createUser
  • Jestor.create
  • Jestor.error
  • Jestor.update
  • Jestor.loadData
  • Jestor.remove
  • Jestor.downloadFile
  • Jestor.getContentFile
  • Jestor.loadXml
  • Jestor.curlCall
  • Jestor.files

O que é Jestor.fetch no Jestor?

Buscar registros de sua conta Jestor

Argumentos

  • objectType: nome da tabela para buscar os registros. Use o nome da API.
    filtros (opcional): filtros a aplicar. Use a mesma sintaxe de filtro usada na API Jestor.
    limite (opcional): contagem de registros para buscar. O máximo permitido é de 500 por operação. O padrão é 100
  • página (opcional): para paginação
  • sort (opcional): use para ordenar os resultados.
  • fieldsToSelect (opcional): array de campos a serem selecionados. Se você usar os campos mínimos necessários, o desempenho será aumentado.
  • fetchType (opcional): único ou aninhado. Quando aninhado for fornecido, retornará registros e registros aninhados na mesma solicitação. se single for fornecido, apenas os registros da guia solicitada.

Devoluções
Array com registros.

Limitações

  • As tabelas do sistema (tais usuários ou tarefas) não funcionarão com este método, use funções específicas para carregar esse tipo de registro
  • Apenas buscar registros da tabela que o usuário logado pode visualizar.
$filters = [
  ['field' => 'account_detail', 'value' => 'user seems a fraud', 'operator' => 'like']
];

$records = Jestor.fetch('tab_name', $filters);

foreach($records as $record) {
  // ...
}

O que é Jestor.count no Jestor?

Retornar contagem de registros para determinada tabela

Argumentos:

  • objectType: nome da tabela para buscar os registros. Use o nome da API.
    filtros (opcional)*: filtros a aplicar. Use a mesma sintaxe de filtro usada na API Jestor.

Devoluções
Um número inteiro que representa a contagem de tabela

Limitações
Para tabelas com mais de 100K, os registros retornarão apenas 100K, para evitar problemas de desempenho do banco de dados.

$total = Jestor.count('tab_name');

echo $total;

O que é Jestor.fetchUsers no Jestor?

Carregue usuários de sua conta Jestor.

Argumentos
filtros (opcional): filtros a aplicar. Use a mesma sintaxe de filtro usada na API Jestor.
limite (opcional): máximo de registros a serem buscados. O padrão é 100, o máximo permitido é 500

  • página (opcional): para paginação
  • sort (opcional): campo para ordenar

Devoluções
Array de usuários, sem dados confidenciais.

$filters = [
  ['field' => 'name', 'value' => 'a', 'operator' => 'startsWith']
];

$usersWithA = Jestor.fetchUsers($filters);

O que é Jestor.fetchTasks no Jestor?

Carregue tarefas da sua conta Jestor.

Argumentos
filtros (opcional): filtros a aplicar. Use a mesma sintaxe de filtro usada na API Jestor.
limite (opcional): máximo de registros a serem buscados. O padrão é 100, o máximo permitido é 500

  • página (opcional): para paginação

Devoluções
Array de tarefas

$filters = [
  ['field' => 'user', 'value' => 1]
];

$usersWithA = Jestor.fetchTasks($filters);

O que é Jestor.createUser no Jestor?

Cria um novo usuário em sua conta Jestor

Argumentos

  • email: email do usuário a ser criado
  • senha: senha bruta do novo usuário
  • profileId: id do perfil a ser atribuído a este usuário
  • nome (opcional): nome do usuário
  • bypassEmailValidation (opcional): Jestor realiza uma validação no endereço de e-mail. Você pode passar true para este sinalizador para ignorar isso. O valor padrão é falso

Devoluções
Array com novo usuário criado

Limitações

  • Se você tentar criar um usuário com um email existente será gerado um erro
  • Usuário com perfil de super administrador (10001) não pode ser criado via low-code
$newUser = Jestor.createUser('[email protected]', '%$%@Sax6yhA', 12001);

O que é Jestor.create no Jestor?

Esta função usa dois argumentos para criar um registro em uma tabela:

  • Uma string que reflete o nome da API/trigger da tabela na qual o registro será criado.
  • Um array emparelhando campos e valores do registro a ser criado.

O exemplo abaixo mostra a criação de um registro na tabela de ofertas.

$newdeal = array(
    "name" => "Deal #0001",
    "amount" => 500,
    "status" => "In Progress"
);
Jestor.create("deals",$newdeal);

Ao criar um registro, você também pode atribuir todas as informações do registro recém-criado a uma variável. Isso é útil quando você deseja criar um registro e ter seu id para outra parte da automação.

$newdeal = array(
    "name" => "Deal #0001",
    "amount" => 500,
    "status" => "In Progress"
);
$createddeal = Jestor.create("deals",$newdeal);

No caso acima, se eu quisesse o id do novo registro, ele estaria disponível em $createddeal["id_deals"];

O que é Jestor.error no Jestor?

Esta função interrompe a automação e reverte todos os registros afetados para o estado anterior à entrada do usuário, mostrando uma mensagem de erro. A mensagem a ser exibida deve ser uma string passada como argumento da função.

No exemplo abaixo, estamos verificando se o registro criado pelo usuário está vazio no campo "amount" e aplicando Jestor.error aos casos TRUE.

if(empty($objectNew["amount"])){
    Jestor.error("Insert an amount for the purchase!");
}

Para o usuário, será algo assim:

800

Erro ao criar compras sem Valor.

O que é Jestor.update no Jestor?

Esta função usa dois argumentos para atualizar um registro em uma tabela:

  • Uma string que reflete o nome da API/trigger da tabela que contém o registro a ser atualizado.
  • Um array emparelhando campos e valores do registro a ser atualizado.

🚧

Sobre o segundo argumento

O array deve conter um id => value pairing, pois a função precisa que o id do registro seja atualizado. Portanto, se eu quiser atualizar o número de telefone de Andrew e Andrew for o registro de id 3 na tabela Employees, o array deve conter o emparelhamento "id_employees" => 3 junto com os pares de campo/valor a serem atualizados.

Se eu tentasse atualizar o e-mail de um fornecedor, por exemplo, faria algo assim:

$vendorupdate = array(
  "id_vendors" => 1,
    "email" => "[email protected]",
);
Jestor.update("vendors",$vendorupdate);

O que é Jestor.loadData no Jestor? (função obsoleta)

Nota: esta função está obsoleta e não recebe atualizações de novas funcionalidades do Jestor. Use a função Jestor.fetch em seu lugar.

Esta função usa dois argumentos para buscar registros em uma tabela:

  • Uma string que reflete o nome da API/trigger da tabela onde a pesquisa será realizada.
  • Um array contendo os filtros e condições da pesquisa.

O array do segundo argumento pode ter parâmetros diferentes, como:

onde: uma matriz contendo as condições que um registro deve atender. Por exemplo, o Jestor.loadData abaixo buscará na tabela Planos por registros que tenham o valor do campo "status" como "Ativo".

$conditions = array(
  "status" => "Active",
);
$search = Jestor.loadData("plans",["where" => $conditions]);

Você pode passar mais de uma condição (que funcionará com uma lógica AND). Além disso, você não precisa trabalhar sempre com correspondências exatas. Você pode passar operadores junto com o campo (como !=, >, < e outros).

O exemplo abaixo buscará registros que tenham Status igual a Ativo E tenham Preço acima de 50.

$conditions = array(
  "status" => "Active",
  "price >" => 50
);
$search = Jestor.loadData("plans",["where" => $conditions]);

sort: a ordem em que os resultados da pesquisa serão apresentados. Por padrão, uma pesquisa trará os resultados por ordem crescente de criação, mas usando um parâmetro "sort" você pode trazer os resultados por ordem crescente (asc) ou decrescente (desc) de qualquer outro campo.

$search = Jestor.loadData("plans",["sort" => "price asc"]);

limit: uma quantidade máxima de resultados que a pesquisa retornará. Por exemplo, é possível limitar o número de resultados aos 10 primeiros resultados, o que pode tornar as pesquisas mais rápidas.

$search = Jestor.loadData("plans",["limit" => 10]);

offset: pula os primeiros n resultados de sua pesquisa, o que pode ser útil ao fazer pesquisas em lotes. No exemplo abaixo, pulamos os primeiros 50 resultados da pesquisa.

$search = Jestor.loadData("plans",["offset" => 50]);

Você pode, é claro, enviar uma mistura de where, sort, limit e offset.

$conditions = array(
  "status" => "Active",
  "price >" => 50
);
$search = Jestor.loadData("plans",["where" => $conditions,"sort" => "price asc", "limit" => 10, "offset" => 50]);

Uma coisa importante a notar é que um Jestor.loadData pode buscar mais de um registro. Por isso, a variável que recebe os resultados da pesquisa (no caso acima, $search) é na verdade um array em que cada posição é um registro inteiro. Assim, por exemplo, $search[0] é na verdade outro array contendo todas as informações do primeiro registro da busca, $search[1] é um array contendo as informações do segundo registro e assim por diante.

O que é Jestor.remove no Jestor?

Esta função usa dois argumentos para remover registros em uma tabela:

  • Uma string que reflete o nome da API/trigger da tabela onde a pesquisa será realizada.
  • O id do registro a ser excluído.

O exemplo abaixo exclui o registro da tabela Plans com id_plans = 3.

Jestor.remove('plans',3);

O que é Jestor.createNewFile no Jestor?

Esta função usa dois argumentos para criar um arquivo a partir de algum tipo de conteúdo:

  • Uma variável contendo o conteúdo.
  • A extensão do arquivo a ser criado.

O exemplo abaixo criará um arquivo .txt que contém o texto "Hello world!" e coloque-o em um campo de anexo.

$text = "Hello world!";
$file = Jestor.createNewFile($text,"txt");
$objectNew["attachment"] = $file;

O que é Jestor.downloadFile no Jestor?

Esta função baixa um arquivo de um determinado URL. O exemplo abaixo tentaria baixar o arquivo .jpg da URL falsa que passamos como argumento.

$downloadedFile = Jestor.downloadFile("https://example.com/file.jpg");

Observe que você não pode passar o conteúdo baixado diretamente para um anexo ou campo de imagem. Você teria que usar Jestor.createNewFile() para criar um arquivo primeiro e depois salvá-lo no campo, como no exemplo abaixo.

$downloadedFile = Jestor.downloadFile("https://example.com/file.jpg");
$file = Jestor.createNewFile($downloadedFile,"jpg");
$objectNew["picture"] = $file;

O que é Jestor.getContentFile no Jestor?

Esta função obtém o conteúdo de um arquivo dentro do próprio Jestor. O exemplo abaixo fará o download do arquivo .jpg do campo de imagem que passamos como argumento.

$contentFile = Jestor.getContentFile($objectNew["picture"]);

Assim como Jestor.downloadFile(), você não pode passar o conteúdo diretamente para um anexo ou campo de imagem. Você teria que usar Jestor.createNewFile() para criar um arquivo primeiro e depois salvá-lo no campo, como no exemplo abaixo.

$contentFile = Jestor.getContentFile($objectNew["picture"]);
$file = Jestor.createNewFile($contentFile,"jpg");
$objectNew["picture"] = $file;

Uma coisa importante sobre arquivos dentro do Jestor é que, se tudo que você está fazendo é passar um arquivo de um campo para outro, apenas copiá-lo funcionará sem a necessidade de usar Jestor.getContentFile(). Esta função geralmente é usada quando você precisa tratar o arquivo, como codificá-lo como base64 para mostrá-lo em uma página personalizada.

#this will work if all you're trying to do is copy a file to a different field

$search = Jestor.loadData("docs",["where" => ["id_docs" => 1]]);
$objectNew["attachment"] = $search[0]["file"];

#but you'll need to do this if you want to treat the file content somehow. In this case, encoding as base64

$contentFile = Jestor.getContentFile($objectNew["picture");
$file64 = base64_encode($contentFile);

O que é Jestor.loadXml no Jestor?

Esta função carrega o arquivo xml e retorna uma instância de SimpleXMLElement.

Argumentos:

  • $fileName ou $xmlContent: nome do arquivo a ser carregado, ou $xmlString
  • $options: flags a serem usados ao carregar xml. Consulte https://www.php.net/manual/pt_BR/libxml.constants.php para valores aceitos - este argumento não é obrigatório
  • $ns: prefixo de namespace - este argumento não é obrigatório
  • $isPrefix: true se $ns for um namespace, false se for um URI. O valor padrão é falso.
$file = $objectNew['uploaded_file'];

$xmlFromFile = Jestor.loadXml($file);


# or

$content = '<orders><order><product id="1">Sample product</product></order></orders>';

$xmlFromString = Jestor.loadXml($content);

O que é Jestor.curlCall no Jestor?

Esse método faz uma chamada cURL, que pode ser usada para buscar ou enviar informações para terminais de API ou webhooks. Esta função precisa de dois argumentos: uma URL e um array contendo os parâmetros de chamada (incluindo dados).

O código de exemplo abaixo cria um array com dados, codifica e envia para a URL especificada. A resposta é então armazenada na variável $response.

$url = "https://example-url.com";

$data = array(

"name" => "Example",
"amount" => 1000

);

$payload = json_encode($data);

$response  = Jestor.curlCall($url,array(

CURLOPT_HTTPHEADER => array(

'Content-Type: application/json'

),

CURLOPT_POST => true,

CURLOPT_POSTFIELDS,

CURLOPT_POSTFIELDS => $payload

));

Esse método pode até ser usado para enviar chamadas de API para seu próprio Jestor (embora geralmente seja melhor e mais fácil usar os métodos nativos do Jestor ao lidar com dados dentro de sua própria organização). O código de exemplo abaixo listará os dados de retorno de todas as Faturas em que o valor é igual a 500 ou 1.000.

$url = "https://yourorg.api.jestor.com/object/list";

$data = array(

"object_type" => "invoices",
"sort" =>  "amount asc",
"page": 1,
"size": "100",
"filters" => array(array(
    "field" => "amount",
  "operator" => "in",
  "value" => array(
        500,
    1000)))
  
);

$payload = json_encode($data);

$response  = Jestor.curlCall($url,array(

CURLOPT_HTTPHEADER => array(

'Content-Type: application/json',
'Authorization: Bearer your_token'

),

CURLOPT_POST => true,

CURLOPT_POSTFIELDS,

CURLOPT_POSTFIELDS => $payload

));

O que é Jestor.files no Jestor?

Como o campo de arquivos contém muitas informações, pode ser um pouco complicado operá-lo diretamente com os métodos padrão. Com isso em mente, Jestor tem um método específico para facilitar o trabalho com campos de arquivo.

Lembre-se: a manipulação de arquivos é sempre relativa às tabelas e registros onde serão armazenados.

  • Criando um objeto de arquivos vazio

Para criar um objeto de arquivos vazio para uma tabela, use Jestor.files() e use o nome da API da tabela como parâmetro.

$files = Jestor.files('table');
  • Buscando um objeto de arquivos existente

Para recuperar um objeto de arquivos existente em um registro, use Jestor.files() e use o nome da API da tabela, o id do registro e o nome da API do campo de arquivos como parâmetros.

$files = Jestor.files('table',1,'field');
  • Adicionando arquivos a um objeto de arquivos

Você pode adicionar arquivos a um objeto de arquivos de três maneiras: por URL, por conteúdo e por local se o arquivo já existir em algum lugar em sua conta Jestor).

Supondo que você tenha um objeto de arquivo em $files:

//adding by URL

$files.addFile([
    'name' => 'My file',
    'fileUrl' => 'https://example.file'
]);

//adding by content

$files.addFile([
    'name' => 'My file content',
    'content' => '<content string>'
    'contentType' => 'pdf'
]);

//adding by local

$files.addFile([
    'name' => 'My file local',
    'localFile' => 'table/filename.png'
]);
  • Atualizando um arquivo

Às vezes, você pode querer substituir um arquivo por outro (por exemplo, substituir o arquivo PDF de uma planilha de horas por uma versão mais recente).

Supondo que você tenha o objeto de arquivo correto em $files:

$files.updateFile($fileId, [
    'name' => 'My file content',
    'content' => '<content string>'
    'contentType' => 'pdf'
]);
  • Excluindo um arquivo

Da mesma forma, você pode querer simplesmente apagar um arquivo completamente.

Supondo que você tenha o objeto de arquivo correto em $files:

$files.deleteFile($fileId);
  • Pesquisando arquivos dentro de um objeto de arquivos

Você pode realizar pesquisas dentro de um objeto de arquivos para condições específicas. Por exemplo, você pode querer recuperar todos os arquivos do tipo PDF ou obter apenas o primeiro resultado após pesquisar um arquivo com um nome específico.

Supondo que você tenha o objeto de arquivo correto em $files:

//searching and getting all results
$fileList = $files.matchFiles([
    'ext' => 'pdf',
]);

//searching and getting only the first result
$file = $files.firstMatchFile([
    'name' => 'My file content',
]);
  • Salvando o novo objeto de arquivos

Após manipular o objeto de arquivos, você precisa salvá-lo em um registro em um campo de arquivos. Você pode fazer isso através de um simples Jestor.update().

Jestor.update('table', [
    'id_table' => $idRecord,
    'files_field' => $files // OR $files->toJsonFiles();
]);