Functions

The Jigx function contains the URL of the REST service, details of the required parameters, and the ability to map your Jigx parameters to complex JSON for either input or output purposes. In the sections below, we will explain each part of the function definition and how you can define any REST service and use it within your Jigx application.

Functions structure

Structure	Description
Continuation	Use when REST services limit the number of items to be returned. Jigx function calls can automatically repeat calls by specifying a continuation block. This overwrites the parameters in the original function call.
Conversions	Handles file format conversions between local-uris and base64, data-uri, or buffer when sending to or receiving from a REST datasource.
disableTokenRefresh	Disables the auto-handling of 401 errors that refresh tokens twice.
error	Customize REST endpoint error messages to suppress or customize default error messages, log error details for more effective debugging, configure retries, and track errors through error logging.
format	Specifies the format of the data returned from the REST server. Supported formats include json, text, pdf, and xml. This setting determines how the response is processed by the function.
forRowsInRange	This function's results are for a specific range in the data - all rows matching the specified column name and parameter value ranges (inclusive) will be removed and replaced with the results from the function. If not specified, the whole table is replaced with the function results, unless either for RowsWithValues is specified.
forRowsWithMatchingIds	This function's results are for specific rows with matching IDs, and other rows are not changed or removed. If not specified, the whole table is replaced with the function results, unless either forRowsWithValues and/or forRowsInRange is specified.
forRowsWithValues	This function's results are for specific rows in the data - all rows matching the specified column name and parameter value pairs will be removed and replaced with the results from the function. If not specified, the whole table is replaced with the function results, unless forRowsInRange is specified.
functionId	Used to override the name of the function. Expected value is a string that respects the following rules: The first character has to start with a letter. The name can contain alphanumeric or symbols '-' and '_'. The name cannot contain spaces. The name cannot end with special characters. The length must be between 2-50 characters.
guard	Guard functions allow you to control what happens after a query runs by conditionally executing additional logic. These functions are called after a query completes and can invoke any other function.
inputTransform	When the function format is JSON, the request body is generated using the inputTransform, a JSONata expression that can reference parameters defined in the function.
keepTempIds	If set to true, temporary Ids in local data will not be deleted on sync. This does not apply when forRowsWithMatchingIds is set to true.
method	Jigx supports the following methods when making REST calls: DELETE GET HEAD PUT PATCH POST
operations	A function can specify zero or multiple table operations to perform on the solution's local SQLite database.
output	The function’s output is returned to calling actions or functions. If an outputTransform is defined, its result is returned; otherwise, the full response from the REST provider is used by default.
outputTransform	The outputTransform is a JSONata expression that converts the REST response into JSON for local SQLite insertion.
parameters	Function parameters are used to pass data into the function definition from the jig that uses the function. It can be used in body, query, path, and also as input parameters for procedures and views.
provider	DATA_PROVIDER_REST for making REST service calls.
queries	Queries in functions provide Just-In-Time (JIT) access to the latest local data, evaluated during function execution. The results can be used in function expressions.
url	The URL of the service that must be called. Jigx supports path and query parameters in the URL. Path parameters are tagged with curly brackets {}. Jigx will replace the path parameters with the values of the parameters defined in the parameter section of the function definition. Query parameters specified in the URL will be removed by Jigx and replaced by parameters defined in the parameters section of the function definition with a location property of type query.
when	Specify a condition for when to execute a function (default) and when to skip and not execute a function based on the local state of the database. The when expression is evaluated after the parameters and queries are evaluated. The when expression is evaluated before token credentials are checked and inputTransforms are evaluated. The when expression is re-evaluated on each continuation.

Creating Function Definitions

Function definitions are stored in the functions folder in a Jigx project with a .jigx file extension. The Jigx Builder IntelliSense code completion provides all the available code completion options relevant to REST functions.

Jigx functions

To add a new function, create a file in the functions folder. The .jigx extension is added automatically. Function file names must be lowercase and cannot contain special characters. Using a clear naming convention is recommended to help identify the purpose of each function, e.g. rest-get-customer or rest-update-customer.

Once functions are published in a Jigx solution you can preview the function in Jigx Management under the solution's REST functions option. See REST Functions for more information.

provider: DATA_PROVIDER_REST
method: POST
url: "https://api.sendgrid.com/v3/mail/send"

parameters:
  Authorization:
    location: header
    type: string
    value: Bearer XXXXXX
    required: true
  emailfrom:
    location: body
    type: string
    required: true
  emailto:
    location: body
    type: string
    required: true
  name:
    location: body
    type: string
    required: true
  subject:
    location: body
    type: string
    required: true
  content:
    location: body
    type: string
    required: true
    
inputTransform: |
  $.{
    "personalizations": [{
      "to": [ { "email": emailto, "name": name }]}],
      "from": {"email": emailfrom, "name": name}, 
      "reply to": {"email": emailfrom, "name": name },
      "subject": subject, 
      "content": [{ "type": "text/html", "value": content}
      ]}          

Referencing a function in a jig

Functions can be used in a jig to access and manage data in your app. You can either query the local SQLite database, populated from REST using configured functions, or use actions to trigger functions that update both the local and remote (REST) data.

local-datasource

datasources:
  customers: 
    type: datasource.sqlite
    options:
      provider: DATA_PROVIDER_LOCAL
      entities:
        - entity: customers
      query: |
        SELECT 
          cus.id AS id, 
          json_extract(cus.data, '$.firstName') AS firstName, 
          json_extract(cus.data, '$.lastName') AS lastName,
          json_extract(cus.data, '$.companyName') AS companyName,
          json_extract(cus.data, '$.address') AS address,
          json_extract(cus.data, '$.city') AS city,
          json_extract(cus.data, '$.state') AS state,
          json_extract(cus.data, '$.zip') AS zip,
          json_extract(cus.data, '$.phone1') AS phone
        FROM 
          [customers] AS cus
        -- ORDER BY 
        --  json_extract(cus.data, '$.companyName')

action

Supporting JSON

REST services typically have simple or complex JSON structures which enable you to provide them with suitable input data as well as return complex data structures. Jigx has built-in capabilities to deal with these structures. These are achieved using:

• InputTransform

• OutputTransform

Authentication Support

All REST functions support header, path, query, and body parameters. In addition, including calling services with no authentication, Jigx supports OAuth, API Key, and Basic Auth or Secrets for authentication. See Authentication for configuration steps.

Functions code completion options

The code completion will display the available template options when adding a new function. Creating a new function using one of these code options adds the skeleton code to the function definition, making it easier to configure functions for specific providers with their authentication configuration. These options are:

• REST: A REST service call with no authentication that returns JSON by default.

• REST (API Key): A REST service call that includes x-API-key in the header for authentication.

• REST (Basic Auth): A REST service call that includes basicAuth in the header populated with the credential's information.

• REST (OAuth): A REST service call that includes accessToken (Authorization) in the header populated with the OAuth Token returned during the OAuth loop.

• REST (Secret): A REST service call that includes a secret that can be added to the header or query string parameters for authentication.

Function execution order

Function properties are evaluated and executed in the following order:

• Check if function exists.

• Check and execute the parameters.

• Then execute queries, dependencies first.

• Then execute the when in the main function.

• Then the guard function is executed.

• Then the when in the guard function is executed.

• Then execute operations.

• Execute inputTransform.

• Then execute conversions.

• Return the output of the function.

Examples and code snippets

The following examples with code snippets are provided:

Example
Hello REST	In this section, a REST API is used to create a customers Jigx app, allowing you to add new customers and update and view customer details, location, and images.
MS Graph	The MS Graph examples use the User, Calendar, Mail, Insights, and To-do tasks to create a powerful Jigx apps with everything you need in one app.