Integration and HTTP

Learn how to call external services, validate XML against XSD schemas, transform XML, send emails with Ninox scripts.

Integration functions connect your app to services and communication tools outside Ninox. You can call APIs, validate XML against schemas, transform XML, and send emails.

In this chapter, you will learn how to:

• Call external services with HTTP.
• Transform XML.

Function (A-Z)	Task
email()	Return or reuse an email value
formatXML()	Convert JSON data to XML text
http()	Send an HTTP request
parseXML()	Convert XML text to a JSON object

Call external services

Use these functions to call any REST API, to pull data from another service or push data between Ninox databases.

Call an API with http()

Use http() to send a request to an external service.

Use it when you want to:

• Fetch data from, or send updates to another system.
• Connect Ninox to REST APIs and other Ninox databases.

Don't place http() inside do as transaction...end

Transactions use a single-threaded write queue. An HTTP call inside a transaction blocks all other writes until the request finishes. The app does not hang forever, but every pending write waits for the full duration of the call. That can make the app feel slow.

http(method, url) http(method, url, body) http(method, url, header, body) http(method, url, header, body, files)

• method text value of the HTTP method , for example, "GET" or "POST"
• url text value of the endpoint URL
• header optional headers as a JSON object, for example, { Authorization: token }
• body optional request body as a JSON object
• files optional files to upload as [file] when the current execution context supports file uploads (server context)

A body is required when accessing Ninox data

If you use http() to access data in Ninox, a body must be passed. If no information needs to be passed in the body, it simply remains empty. An example of this would be:

http("GET", "https://api.ninox.com/v1/[...]", {Authorization: "Bearer xxxx-xxxx-xxxx", "content-type": "application/json"}, {})

Let’s take a look at some examples:

http("GET", "https://api.example.com/status")

Calls the external service and returns a JSON response object or an error object.

let url := "https://api.ninoxdb.de/v1/teams/" + teamId() +
           "/databases/" + databaseId() + "/tables/";
let apiKey := "Bearer abcd1234-0000-xxxx-zzzz-1a1aa1aaa1a111";

let response := http("GET", url, {
    Authorization: apiKey
});
response

Lists tables from the current database through the Ninox API or an error object.

do as server
   let url := "https://api.ninoxdb.de/v1/teams/" + teamId() +
             "/databases/" + databaseId() + "/query";
   let apiKey := "Bearer abcd1234-0000-xxxx-zzzz-1a1aa1aaa1a111";
   
   let response := http("POST", url, {
             Authorization: apiKey, 
             "content-type": "application/json"
   }, {
    query: "select customers where status = 4"
   });
   response
end

Sends a POST request and returns matching records or an error object.

let response := do as server
    http("POST",
        "https://example.com/upload",
        { "content-type": "multipart/form-data" },
        null,
        [myFile])
end

Uploads a file to an external service when file uploads are supported in the current execution context.

Tips:

• http() returns a JSON object, not plain text.
• If you access another Ninox database, you need an API key.
• Some endpoints expect a body even for GET requests. Use {} when the target endpoint requires one and you do not need to send fields.
• File uploads depend on the execution context.
• Test integration scripts against the real service response, not sample output only.

Transform XML

Use these functions when another system sends or expects XML, especially when the XML must match a defined schema.

Convert XML text to data with parseXML()

Use parseXML() to turn XML text into a JSON object you can inspect in Ninox. This is especially useful when you connect Ninox to external services by API and need to process XML responses. XML is a common exchange format alongside JSON.

Use it when you want to:

• Read values from an XML response.
• Extract fields from imported XML.
• Convert XML into structured data for later logic.

parseXML(string)

• string the XML text you want to convert to a JSON object

Let’s take a look at some examples:

let xml := "<?xml version=""1.0"" encoding=""UTF-8""?>
<note>
    <to>Jane Doe</to>
    <from>Ninox</from>
    <heading>Save the world!</heading>
    <body>Please save the world!</body>
</note>";
parseXML(xml)

Returns a JSON object built from the XML text, for example:

{
  "note": {
    "to": {
      "@": "Jane Doe"
    },
    "from": {
      "@": "Ninox"
    },
    "heading": {
      "@": "Save the world!"
    },
    "body": {
      "@": "Please save the world!"
    }
  }
}

Tip:

• If you have an XSD schema, validate external XML before you parse it.

Create XML text with formatXML()

Use formatXML() to convert JSON data into XML text.

Use it when you want to:

• Prepare XML for another service.
• Reformat parsed data into readable XML.

formatXML(JSON) formatXML(JSON, boolean)

• JSON the structured data you want to convert to XML
• boolean whether the output should be visually structured for reading

Let’s take a look at some examples:

let x := parseXML("<root><item>1</item></root>");
formatXML(x, true)

Formats the parsed object back into readable XML text.

formatXML({
    contact: {
        @type: "Person",
        firstName: {
            @: "Max"
        },
        lastName: {
            @: "Mustermann"
        },
        phone: [{
            @type: "Mobile",
            @: "(+1) (202) 123 45 67"
        }, {
            @type: "Phone",
            @: "+1.151.11 ++66 14 66"
        }]
    }
}, true)

Converts the JSON object into structured XML text. Keys like @type become XML attributes. @ becomes the node text value.

Tips:

• Use the pretty option when humans need to read the result.
• Use compact output when the target system only needs the payload.
• This function is especially useful for API integrations that expect XML instead of JSON.

Send email messages

Use this function to open an email message from Ninox.

Work with an email value using email()

Use email() to convert text into an email value.

Use it when you want to:

• Open your device's email app from an email value.
• Display a formula field as an email field.
• Extract an email address from text and use it with one click.

email(string)

• string the text value to use as an email address. Include an @ and a valid domain.

Click in a field or button. Ninox opens your device's default email app.

Let’s take a look at some examples:

email(myEmail)

Converts the value in myEmail into an email value.

email("[e-mail]")

Displays the address as an email value with a clickable mail action.

Tips:

• Keep email addresses correctly formatted. Otherwise, the mail action can return an error.
• A correctly formatted address opens your device's default email app.

Integration behavior can depend on your environment, client, and connected services. Confirm HTTP and email workflows in the same setup your users run in production.