JSBox

O JSBox foi criado com o intuito de permitir que engenheiros jurídicos façam operações em JavaScript dentro de seu template. Essa ferramenta, no entanto, funciona através de uma API -- o engenheiro envia as informações necessárias para um bot que executa as ações requisitadas e retorna os dados produzidos ou coletados.

Formato da API

Para facilitar a organização dos dados, sugerimos que, ao utilizar a API, o usuário crie duas estruturas: uma para o envio e outra para o recebimento dos dados. No entanto, é possível fazer uso da ferramenta com somente uma estrutura, se ela possuir todos os requisitos discutidos a seguir. O comando dentro de operations que irá pedir para o JSBOX executar o código é:

Copy
use *FUNC_LooplexGraph where (
    <subscription_key> = <key>,
    <method> = "jsbox",
    <payload> : <payload>,
    <response> : <response>
)

(Para mais informações verifique a documentação sobre o uso de APIs)

O exemplo acima faz uso das estruturas <req> para representar os dados que serão enviados ao JSBox como requisição e <res> para representar os dados que o sistema receberá de resposta. Entretanto, o engenheiro jurídico pode utilizar os nomes que preferir para essas estruturas.

Formato da estrutura de envio

O JSBox exige que na estrutura de envios exista uma String chamada operations. Sem ela o programa não terá código em JavaScript para executar. Ele tem também, como parâmetro opcional, uma Struct chamada declarations para que o engenheiro possa enviar dados ao JSBox. Segue um exemplo de como a estrutura de envio pode ser declarada no Lawtex:

Copy
declarations {
    +<req> : Struct {
        fields {
            +[declarations] : Struct {
                fields {
                    +[valores] String
                }
            },
            +[operations] : String
        }
    }
}

A Struct declarations pode ser utilizada pelo usuário para enviar dados ao JSBox que poderão ser utilizado dentro das operações (exemplo 2).

A String operations deve conter as instruções em JavaScript que devem ser executadas pelo JSBox.

Formato da estrutura de resposta

Como mencionado anteriormente, a estrutura de retorno pode ter o nome que o usuário preferir, no entanto, ela deve ter uma estrutura específica para o JSBox saber onde colocar os resultados. Para facilitar a verificação do sucesso da operação, o JSBox sempre retornará uma variável com o nome de [status] que terá o valor de "SUCCESS" ou "FAILURE". Se for "FAILURE", a estrutura message virá preenchida com as variáveis [name], [message] e [stack] que providenciarão mais detalhes a respeito do erro que impediu a execução do código.

Se a operação tiver um [status] de "SUCCESS" os campos dentro da estrutura message serão os que o usuário declarou no seu código em JS.

Copy
declarations {
    -<res> : Struct {
        fields {
            -[status]: String,
            -[message]: Struct {
                fields {
                    // Em caso de "FAILURE"
                    -[name] : String,
                    -[message]: String,
                    -[stack] : String
                    // Em caso de "SUCCESS"
                    //Aqui o usuário pode declarar as variáveis ou estruturas que quiser e, quando for programar o código em JS utilizar os mesmos nomes.
                }
            }
        }
    }
}

Código em JavaScript

O JSBox é capaz de executar o que o usuário pedir em JS inclusive fazer APIs, surfar a internet, lidar com estruturas de dados complexas, etc. Portanto, o que o usuário quiser fazer só será limitado pelo seu conhecimento de JS e sua habilidade de integrar o resultado com o ambiente da Looplex.

No entanto, vale lembrar que qualquer operação de print no documento deve ser feita em Lawtex pois o JSBox não é capaz de efetuar nenhuma operação de console.log na plataforma Looplex. Consequentemente, toda comunicação deve ser através de dados enviados entre as duas plataformas.

Receber variáveis

Quando for usar variáveis que foram enviadas na estrutura [declarations] em JS, basta substituir o nome da estrutura que foi enviada em Lawtex pelo termo data. Por exemplo, para utilizar uma variável chamada rg que foi colocada dentro de [declarations] em Lawtex, o engenheiro deve utilizar o termo data.declarations.rg em JS.

Devolver variáveis

Quando o engenheiro quiser pedir para o JSBox retornar uma valor específico para uma variável, estrutura, vetor, etc. ele deve sempre começar as atribuições criando variáveis dentro da estrutura [message] do retorno. Para isso, utilize o termo data.message seguido de um ponto e o nome da variável que quiser utilizar. Por exemplo:

Copy
data.message.oi = 'Oi';

retornará a string "Oi" em uma variável com o nome [oi] que deve estar declarada dentro de <res.message> no Lawtex.

Comportamentos especias do Lawtex

1. Envio de Vectors

Quando o Lawtex prepara uma Struct ou um Vector para o envio através de uma API ou para ser salva em formato JSON, ele não cria um array para Vectors. Ele cria estruturas indexadas por uma String que registra o número da aba do Vector. Segue um exemplo básico para ilustrar:

Copy
+|vectSTR| : Vector[String] {
    name = "Vector de String"
}

Os dados serão registrados no seguinte formato:

Copy
{
    "0":"StringA",
    "1":"StringB",
    "2":"StringC",
    "3":"StringD",
    "4":"StringE",
    "5":"StringF",
    "6":"StringG"
}

O mesmo se aplica a Vectors de Structs. Por isso, precisamos ficar atentos para lidar com os dados de forma correta dentro do JSBox.

2. Join de Strings

Quando o Lawtex envia uma String ele junta todo o texto mesmo se for escrito em mais de uma linha. Por causa disso, precisamos ser muito atenciosos ao enviar os [operations] ao JSBox.

Copy
<operations> = "
const oi = 'bom dia';
const saudacoes = `Olá, ${oi}`;
data.message.oi = saudacoes;
"

Os <operations> acima são enviados da seguinte maneira:

Copy
{
    "operations": "const oi = 'bom dia';const saudacoes = `Olá, ${oi}`;data.message.oi = saudacoes;"
}

Por essa razão, precisamos garantir que todas as instruções em JS tenham um ; para que o JSBox saiba separar as linhas e, se quisermos comentar o código, utilizar /**/ para não comentar a linha inteira que está sendo enviada.

3. Caracteres de escape

Quando a plataforma Looplex registra um caractere de escape como \n ou \t em uma String, ela acaba duplicando a barra. Portanto, não podemos usar \n nas nos operations enviados.

4. Variáveis vazias

Quando a plataforma Looplex envia estruturas ou variáveis através de uma API, ela somente envia a variável ou estrutura se há algum valor atribuído à mesma. Portanto, mesmo se o engenheiro somente quiser utilizar o [operations], é necessário preencher algo no [declarations] para garantir que a estrutura seja enviada. Isso fica demonstrado no primeiro exemplo abaixo em que a String <req.declarations.valores> é preenchida com um valor aleatório, "valor", para garantir que a estrutura inteira de [declarations] seja enviada na API -- esse valor é ignorado no código em JS e assim o código funciona como desejado.

Exemplos

1. Somente enviar operations:

Copy
metainfo {
    declarations {
        -<req> : Struct {
            fields {
                -[declarations] : Struct {
                    fields {
                        -[valores] : String
                    }
                },
                -[operations] : String
            }
        },
        -<res> : Struct {
            fields {
                -[status]: String,
                -[message]: Struct {
                    fields {
                        // Em caso de "FAILURE"
                        -[name] : String,
                        -[message]: String,
                        -[stack] : String,
                        // Em caso de "SUCCESS"
                        -[oi] : String
                    }
                }
            }
        }
    }
}
body {
    operations {
        <req.declarations.valores> = "valor",
        <req.operations> = "
        const oi = 'bom dia';
        const saudacoes = `Olá, ${oi}`;
        data.message.oi = saudacoes;
        ",
        use *FUNC_LooplexGraph where (
            <subscription_key> = <key>,
            <method> = "jsbox",
            <payload> : <payload>,
            <response> : <response>
        ),
        print <res.message.oi>
    }
}

Nesse caso, no documento na plataforma Looplex, será impresso o texto Olá, bom dia.

2. Uso de dados no declarations:

Copy
metainfo {
    declarations {
        -<req> : Struct {
            fields {
                -[declarations] : Struct {
                    fields {
                        -[x] : Integer,
                        -[y] : Integer
                    }
                },
                -[operations] : String
            }
        },
        -<res> : Struct {
            fields {
                -[status]: String,
                -[message]: Struct {
                    fields {
                        // Em caso de "FAILURE"
                        -[name] : String,
                        -[message]: String,
                        -[stack] : String,
                        // Em caso de "SUCCESS"
                        -[quociente] : String
                    }
                }
            }
        }
    }
}
body {
    operations {
        <req.declarations.x> = 11,
        <req.declarations.y> = 5,
        <req.operations> = "
        var quotient = Math.floor(data.declarations.x/data.declarations.y);
        data.message.quociente = JSON.stringify(quotient);
        ",
        use *FUNC_LooplexGraph where (
            <subscription_key> = <key>,
            <method> = "jsbox",
            <payload> : <payload>,
            <response> : <response>
        ),
        print <res.message.quociente>
    }
}

Nesse caso, no documento na plataforma Looplex, será impresso o texto 2, pois 2 é o resultado da divisão de 11 por 5 sem o resto.