RESTful API

Hint

RESTful API is available only with Professional and Enterprise licienses.

To enable integration between NodeActa and third-party software, we provided a REST interface. This interface supports essential functions such as data querying, document retrieval, and archiving. It is crucial to distinguish the functionality provided by JavaScript applications executed in Application Center from the functionality provided by NodeActa Server. The Server handles operations like querying, archiving, and retrieving data or documents, while the logic implemented in JavaScript applications is not accessible via REST interface.

We will not document every possible request, but if you need details about specific requests and responses, you can create a sample app in the Application Center to perform the required functionality. Before running the code, activate Communication Monitor via Main Menu Development→Communication Monitor. In the monitor, you’ll find all the request and response parameters. Remember that response's data parameter will be base64 encoded in Communication Monitor, while in reality your HTTP request will return JSON. If you are using transactions, you must include the transactionId parameter with each request you want to be part of that transaction.
Here is an example of a request body for querying document class CONTRACT, filtering only contracts with value in the range between 1000-5000:

Request

{ 
    "storage": "SYSTEM", // can be omitted as "SYSTEM" storage is default
    "select": {
        "fields": [      // omit "fields" parameter if you want all fields retrieved
            {
                "table": "CONTRACT",
                "name": "SUBJECT"
            },
            {
                "table": "CONTRACT",
                "name": "TYP"
            },
            {
                "table": "CONTRACT",
                "name": "VAL"
            },
        ],
        "from": [
            {
                "table": "SYS$DATA"
            },
            {
                "table": "CONTRACT",
                "joinType": "inner join",
                "joinOn": [
                    {
                        "left": "SYS$DATA.ID",
                        "right": "CONTRACT.ID"
                    }
                ]
            }
        ],
        "where": [
            {
                "table": "CONTRACT",
                "field": "VAL",
                "condition": "greater than or equal",
                "value": 1000.00
            },
            {
                "bind": "and",
                "table": "CONTRACT",
                "field": "VAL",
                "condition": "less than",
                "value": 5000.00
            }
        ]
    }
}

JavaScript Examples

Query Documents

RequestResponse

$.ajax( {
    type: 'POST',
    url: "/record/query/select", 
    contentType: 'application/json',
    dataType: 'json',
    data: JSON.stringify( { 
        select: {
            fields: [
                {
                    table: "CONTRACT",
                    name: "SUBJECT"
                },
                {
                    table: "CONTRACT",
                    name: "TYP"
                },
                {
                    table: "CONTRACT",
                    name: "VAL"
                },
            ],
            from: [
                {
                    table: "SYS$DATA"
                },
                {
                    table: "CONTRACT",
                    joinType: "inner join",
                    joinOn: [
                        {
                            left: "SYS$DATA.ID",
                            right: "CONTRACT.ID"
                        }
                    ]
                }
            ],
            where: [
                {
                    table: "CONTRACT",
                    field: "VAL",
                    condition: "greater than or equal",
                    value: 1000.00
                },
                {
                    bind: "and",
                    table: "CONTRACT",
                    field: "TYP",
                    condition: "in",
                    value: ["Lease", "Sale"]
                }
            ]
        }
    } ),
    success: function(data) {
        // do something with response
    }
} );

{
    "data": {
        "meta": {
            "fields": [ "SUBJECT", "TYP", "VAL" ]
        },
        "records": [
            {
                "SUBJECT": "Contract 20/11/2-11",
                "TYP": "Lease",
                "VAL": 1899.45
            },
            {
                "SUBJECT": "Contract 44/01/9-11",
                "TYP": "Sale",
                "VAL": 4899.45
            }
        ]
    }
}

List Document Files

RequestResponse

$.ajax( {
    type: 'POST',
    url: "/document/files", 
    contentType: 'application/json',
    dataType: 'json',
    data: JSON.stringify( { 
        cls: "SYS$APP",
        ver: "00000000000000000000000000100034",
    } ),
    success: function(data) {
        // do something with response
    }
} );

{
    "data": {
        "meta": {
            "source": "SYSTEM",
            "fields": [ "ID", "VER", "NAME", "BUILD", "ARCHID", 
                        "FSIZE", "FHASH", "SHASH", "FLAG", "SDAT", "LWT", "LINK" ]
        },
        "records": [
            {
                "ID": "00000000000000000000000000100034",
                "VER": "00000000000000000000000000100034",
                "NAME": "index.mjs",
                "BUILD": 1,
                "ARCHID": "0000000000000034",
                "FSIZE": 0,
                "FHASH": "0000000000000000000000000000000000000000000000000000000000000000",
                "FLAG": 0,
                "SDAT": "0100-01-01T00:00:00.000Z",
                "LWT": "2023-06-20T23:50:53.000Z"
            }
        ]
    }

Retrieve File

Request

$.ajax( {
    type: 'POST',
    url: "/document/file", 
    contentType: 'application/json',
    data: JSON.stringify( { 
        cls: "SYS$APP",
        archid: "000000010000081B"
    } ),
    success: function(data) {
        // "data" is file Content
    }
} );

Check-out Document

RequestResponse

$.ajax( {
    type: 'POST',
    url: "/document/checkout", 
    contentType: 'application/json',
    dataType: 'json',
    data: JSON.stringify( { 
        cls: "INVOICE",
        id: "DA4DD561B41B4F2F8BDDBD9D48FAB723"
    } ),
    success: function(data) {
        // Do something with response
    }
} );

{
    "wver": "FE83636A872B41ACA76898F7F9D57378" // Working Version ID is used for all file operations
}

Check-in Document

Request

$.ajax( {
    type: 'POST',
    url: "/document/checkin", 
    contentType: 'application/json',
    data: JSON.stringify( { 
        cls: "INVOICE",
        id: "DA4DD561B41B4F2F8BDDBD9D48FAB723",
        major: 1,              
        minor: 67,                  // if omitted it will auto increment MINOR
        cmnt: "Some comment"
    } )
} );

Undo Check-out Document

Request

$.ajax( {
    type: 'POST',
    url: "/document/undocheckout", 
    contentType: 'application/json',
    data: JSON.stringify( { 
        cls: "INVOICE",
        id: "DA4DD561B41B4F2F8BDDBD9D48FAB723"            
    } )
} );

Add Document

This is an example how to add a document (record and files).
If you have a data class without files, you will just use "/record/add" as url parameter.

RequestResponse

$.ajax( {
    type: 'POST',
    url: "/document/add", 
    contentType: 'application/json',
    dataType: 'json',
    data: JSON.stringify( { 
        cls: "INVOICE",
        checkin: false,    // optional: 'false' will leave the document checked out (default is true)
        fields: [          // all data class 'must' fields must exists here
            {
                name: "TYP",
                value: "Recurring"
            },
            {
                name: "NAME",
                value: "Personal 11/2024 spending"
            },
            {
                name: "DAT",
                value: "2024-11-30T19:52:37.705Z"
            }
        ],
        files: [             // optional if you are adding a document without files
            {
                fileName: "Bill_1.png",
                data: "<Base64 encoded file content>"
            },
            {
                fileName: "MyOtherImage.png",
                data: "<Base64 encoded file content>"
            }
        ]
    } ),
    success: function(data) {
        // Do something with response
    }
} );

{
    "id": "DA4DD561B41B4F2F8BDDBD9D48FAB723", 
    "files": [
        {
            "fileID": "5BA72F711FA743CB88201A836ACAB6C4",
            "fileName": "Bill_1.png",
            "size": 3206310,
            "archiveID": "0000000100000820",
            "hash": "E3B0C44298FC1C149AFBF4C8996FB92427AE41E4649B934CA495991B7852B855",
            "lastWriteTime": "2024-11-29T18:52:37.689Z",
        },
        {
            "fileID": "9AC5C395B59542829A6DBF3EB9CC8999",
            "fileName": "MyOtherImage.png",
            "size": 2203120,
            "archiveID": "0000000100000822",
            "hash": "AE12C44298FC1C149AFBF4C8996FB92427AE41E4649B934CA495991B7852B866",
            "lastWriteTime": "2024-11-29T18:52:37.689Z",
        }
    ]
 }

Edit Document

This is an example how to change a document (record and/or files). If you have a data class without files, you will just use "/record/edit" as url parameter.

RequestResponse

$.ajax( {
    type: 'POST',
    url: "/document/edit", 
    contentType: 'application/json',
    dataType: 'json',
    data: JSON.stringify( { 
        cls: "INVOICE",
        id: "DA4DD561B41B4F2F8BDDBD9D48FAB723",
        checkin: true,       // optional: automaticaly checks-in document
        unlock: true,        // optional: automaticaly unlocks document
        fields: [            // optional if you are changing just files
            {
                name: "TYP",
                value: "Recurring"
            },
            {
                name: "NAME",
                value: "Personal 11/2024 spending"
            },
            {
                name: "DAT",
                value: "2024-11-30T19:52:37.705Z"
            }
        ],
        files: [             // optional if you are changing just attributes
            {
                action: "insert",
                fileName: "Bill_1.png",
                data: "<Base64 encoded file content>"
            },
            {
                action: "update",
                fileID: "9AC5C395B59542829A6DBF3EB9CC8999",
                fileName: "MyOtherImage.png",
                data: "<Base64 encoded file content>"
            }
        ]
    } ),
    success: function(data) {
        // Do something with response
    }
} );

{
    "files": [
        {
            "fileID": "5BA72F711FA743CB88201A836ACAB6C4",
            "fileName": "Bill_1.png",
            "size": 3206310,
            "archiveID": "0000000100000820",
            "hash": "E3B0C44298FC1C149AFBF4C8996FB92427AE41E4649B934CA495991B7852B855",
            "lastWriteTime": "2024-11-29T18:52:37.689Z",
        },
        {
            "fileID": "9AC5C395B59542829A6DBF3EB9CC8999",
            "fileName": "MyOtherImage.png",
            "size": 2203120,
            "archiveID": "0000000100000822",
            "hash": "AE12C44298FC1C149AFBF4C8996FB92427AE41E4649B934CA495991B7852B866",
            "lastWriteTime": "2024-11-29T18:52:37.689Z",
        }
    ]
 }

Delete Document

This is an example how to delete a document. If you have a data class without files, you will just use "/record/delete" as url parameter.

Request

$.ajax( {
    type: 'POST',
    url: "/document/delete",        
    contentType: 'application/json',
    data: JSON.stringify( { 
        cls: "INVOICE",
        id: "DA4DD561B41B4F2F8BDDBD9D48FAB723"            
    } )
} );

Finalize Document

Request

$.ajax( {
    type: 'POST',
    url: "/document/finalize",
    contentType: 'application/json',
    data: JSON.stringify( { 
        cls: "INVOICE",
        id: "DA4DD561B41B4F2F8BDDBD9D48FAB723"            
    } )
} );

Lock Record

Lock a record if you want to have an exclusive access to the record. Only one user from one session can lock the record at the time. Remember that one user can have multiple sessions (multiple Document Center windows and/or multiple web browsers). The lock will expire automatically after 15 minutes.
If you have locked records that need to be unlocked, you can force unlock via System Management→Locked Records app (requires admin rights).

RequestResponse (successful lock)Response (failed lock)

$.ajax( {
    type: 'POST',
    url: "/record/lock",
    contentType: 'application/json',
    dataType: 'json',
    data: JSON.stringify( { 
        locks: [
            {
              cls: "INVOICE",
              id: "DA4DD561B41B4F2F8BDDBD9D48FAB723",
            },
            {
              cls: "BILL",
              id: "745C881B10724EDFA13B1E944A903F09",
            }
        ]
    } ),
    success: function(data) {
        // Do something with response
    }
} );

{
    "locked": true
}

{
    "locked": false,
    "locks": [
        // this document is already LOCKED by another user or another session of the same user
        {
            "cls": "INVOICE",
            "id": "DA4DD561B41B4F2F8BDDBD9D48FAB723",
            "user": "b.alexander",
            "comp": "PC",
            "ipAddress": "112.101.22.123",
            "lockDate": "2024-12-01T21:25:30.410Z",
            "status": "locked"
        },
        // this document can be locked
        {
            "cls": "BILL",
            "id": "745C881B10724EDFA13B1E944A903F09",
        }
    ]
}

Unlock Record

RequestResponse (successful unlock)Response (failed unlock)

$.ajax( {
    type: 'POST',
    url: "/record/unlock",
    contentType: 'application/json',
    dataType: 'json',
    data: JSON.stringify( { 
        locks: [
            {
              cls: "INVOICE",
              id: "DA4DD561B41B4F2F8BDDBD9D48FAB723",
            },
            {
              cls: "BILL",
              id: "745C881B10724EDFA13B1E944A903F09",
            }
        ]
    } ),
    success: function(data) {
        // Do something with response
    }
} );

{
    "unlocked": true
}

{
    "unlocked": false,
    "locks": [
        // cannot unock the document which is already LOCKED by another user or another session of the same user
        {
            "cls": "INVOICE",
            "id": "DA4DD561B41B4F2F8BDDBD9D48FAB723",
            "user": "b.alexander",
            "comp": "PC",
            "ipAddress": "112.101.22.123",
            "lockDate": "2024-12-01T21:25:30.410Z",
            "status": "locked"
        },
        // this document can be unlocked
        {
            "cls": "BILL",
            "id": "745C881B10724EDFA13B1E944A903F09",
        }
    ]
}

Start Transaction

A transaction is a single unit of work. If a transaction is successful, all of the data modifications made during the transaction are committed and become a permanent part of the database. If a transaction encounters errors and must be rolled back, then all of the data modifications are erased.
To include other operations into your transaction, pass with each operation transactionId parameter with the value you obtained via /transaction/start request.

RequestResponse

$.ajax( {
    type: 'POST',
    url: "/transaction/start",
    dataType: 'json',
    success: function(data) {
        // store data.transactionId for later
    }
} );

{
    "transactionId": 6428
}

Commit Transaction

Request

$.ajax( {
    type: 'POST',
    url: "/transaction/commit",
    contentType: 'application/json',
    dataType: 'json',
    data: JSON.stringify( { 
        transactionId: 6428
    } )
} );

Rollback Transaction

Request

$.ajax( {
    type: 'POST',
    url: "/transaction/rollback",
    contentType: 'application/json',
    data: JSON.stringify( { 
        transactionId: 6428
    } )
} );

Get Generator Value

To get the next value for your generator/sequence use the following command.

RequestResponse

$.ajax( {
    type: 'POST',
    url: "/generator/next",
    contentType: 'application/json',
    dataType: 'json',
    data: JSON.stringify( { 
        name: 'BILL_ID_GEN'
    } ),
    success: function(data) {
        // do soemthing with data.value
    }
} );

{
    "value": 847
}

Send User a Message

Request

$.ajax( {
    type: 'POST',
    url: "/message",
    contentType: 'application/json',
    data: JSON.stringify( { 
        user: 'b.alexander', // omit `user` prameter to send the message to everybody
        message: 'Hello'
    } )
} );

Run App on NodeActa Server

Warning

To run app on the server side you must install nodeacta.command.exe on the server PC.

Request

$.ajax( {
    type: 'POST',
    url: "/app/run",
    contentType: 'application/json',
    dataType: 'json',
    data: JSON.stringify( { 
        name: 'Samples.MyRemoteApp',
        args: { param1: 'val1', anotherParam: 33 }, // one-dimensional json dict
        wait: true,
    } ),
    success: function(result) {
        // result is RemoteApp.run() method return value
    }
} );

Parameter args passed to the ajax call will be propagated to RemoteApp's constructor arguments. Also, it can be accessed via env.args.

Arguments mapping

param1 => env.args.param1   
anotherParam => env.args.anotherParam