Toggle menu

End Point Library Workers

There are four end point Library Workers, the ajaxlibrary, securelibrary, serverlibrary and remotelibrary. End points deployed to them can be called in your forms, workflow models, website templates and by third parties.

Description

The API Server includes four end point capable workers (workers you are able to deploy end points to).

The workers themselves are identical.

The ajaxlibrary and serverlibrary are enabled as standard, with different security. The ajaxlibrary is bound to the "open" key so that the end points deployed to it can be called in AJAX requests from a user's browser. The serverlibrary is bound to the "local open" key which means the end points deployed to it can only be called server-side by other workers (eg in forms, workflow, other end points etc).

The securelibrary is secured to the internal key. It can also be bound to API keys you create yourself. The end points deployed to it could then be called by external services when the key is provided. You could also set up additional security and method filters.

The remotelibrary is designed to be deployed on a remote API Server, not hosted alongside iCM or your website, and accessed via a VPN to provide more advanced integrations with third party services. See Remote API Servers for more information.

Worker Configuration Properties

We don't recommend changing any of these default values.

PropertyTypeDescription
enableDirectoryBooleanDefault: true for serverlibrary, false for ajaxlibrary and securelibrary

Enables the _directory method on the worker
enableDocumentationBooleanDefault: true for serverlibrary, false for ajaxlibrary and securelibrary

Enables the _documentation method on the worker
enableVerboseLoggingBooleanIf enabled the name of the unavailable end point called via this.invokeEP() will be added to error messages caused by end points not being found. This property should be false for the ajaxlibrary and securelibrary to prevent the names of end points being displayed publicly
deploymentRefreshSecondsIntegerDefault: 120

Determines how frequently the worker checks for newly published end points
endPointRefreshSecondsIntegerDefault: 30

Determines how frequently the worker checks published end points for modification
updateOnNotFoundBooleanDefault: true

Worker will update information on published end points if a requested end point is not found
updateOnNotFoundDelaySecondsIntegerDefault: 2

Prevents updated of published end point information within specified period
maximumFormUtilsGetLockTimeoutIntegerDefault: 60000

Maximum amount of time that an end point can wait for a lock
defaultNamespaceStringDefault: "DEFAULT"

The namespace of the DEFAULT group. Do not change this.

Worker Methods

MethodPropertiesDescription
_directoryNoneLists all of the end points published on the specified worker
_documentationendPointReturn the documentation, schema and examples of the named end point. The end point must available on this worker

Example: _directory

Request

function( params, credentials ) {
    let resp = this.callWorkerMethod("ajaxlibrary", "_directory",{
    });
    return resp;
}

Response

{
    "jsonrpc": "2.0",
    "id": 422,
    "result": {
        "GOSS.EXAMPLES.NODEMODULES.CRYPTOJS": [{
            "name": "cryptojs",
            "namespace": "goss.Examples.NodeModules",
            "version": "1.0",
            "fullyQualifiedName": "GOSS.EXAMPLES.NODEMODULES.CRYPTOJS:1.0",
            "description": "CryptoJS example",
            "loaded": false
        }],
        "GOSS.EXAMPLES.NODEMODULES.MOMENT": [{
                "name": "moment",
                "namespace": "goss.Examples.NodeModules",
                "version": "1.0",
                "fullyQualifiedName": "GOSS.EXAMPLES.NODEMODULES.MOMENT:1.0",
                "description": "Example moment usage",
                "loaded": false
            }]
            ....
            ....
    }
}

Example: _documentation

Request

function( params, credentials ) {
    let resp = this.callWorkerMethod("serverlibrary", "_documentation",{
        "endPoint": "goss.documentationExample"
    });
    return resp;
}

Response

{
    "jsonrpc": "2.0",
    "id": 425,
    "result": {
        "name": "documentationExample",
        "namespace": "goss",
        "version": "1.0",
        "fullyQualifiedName": "GOSS.DOCUMENTATIONEXAMPLE:1.0",
        "description": "An end point that shows what a documentation request looks like",
        "documentation": "<p>Here's the end point's help text</p>",
        "paramsSchema": {
            "additionalProperties": false,
            "type": "object",
            "required": ["myString"],
            "properties": {
                "testArray": {
                    "description": "An array of testing things",
                    "type": "array"
                },
                "myString": {
                    "minLength": 5,
                    "maxLength": 10,
                    "type": "string"
                }
            }
        },
        "returnSchema": {
            "additionalProperties": false,
            "type": "object",
            "properties": {
                "result": {
                    "type": "boolean"
                }
            }
        },
        "paramsExamples": [{
            "name": "My Test",
            "params": {
                "test": "test"
            }
        }]
    }
}

Invoking an End Point

A published end point is invoked using a standard JSONRPC2 request to the relevant worker, using the fully qualified end point name as the method name. This can be done using the apiclient library, or if you are calling one end point from another, the End Point this Object includes this.invokeEP(). To call end points from your form, use the .utilServerAPIServerCall helper function.

For more information about end points, including the end point this object, see the Writing and Deploying End Points article.

Last modified on June 20, 2024

Share this page

Facebook icon Twitter icon email icon

Print

print icon