Modules > Custom modules / API methods in modules

API methods in modules

In ELMA365, module authors can create their own custom methods and use them in the Web API, in widget, page, and process scripts, or when configuring document templates. For instance, one might design methods to initiate a business process, conduct complex data retrieval, or establish intermediate communication with an internal or external system.

You can also devise general-purpose functions and utilize them repeatedly across various locations.

Create a method

To create a method, do the following:

  1. Go to Administration > Modules.
  2. Hover the mouse over the module and click the gear icon.

custom-extension-settings-2

  1. Go to the API Methods tab.
  2. Click Edit. The method editor will open.
  3. Click the +Add button. In the window that opens, enter the required information.

extention-API-1

 

  • Name*. Enter the method’s name.
  • Address*. Select one or more HTTP request methods from the list. The following methods are available: GET, POST, PUT, PATCH, and DELETE. Specify at what address the method will be available at. Use a forward slash (/) to specify a path to nested methods. For example, /main/email_dispatch. The number of nesting levels is unlimited. The path to the method can end in a forward slash (/), for example, call_events/route/.
  • Function*. Create a function that will be executed when a request is received.
  • Authorization. Select an authorization type to use when a request is received.
    • Internal. When this option is selected, the method can only be called within the module, for instance, in other methods, widgets, business processes activities, and event handlers. To call it, you need to use the Namespace.api.method_name command. Read more below. The user under whom the script runs must be logged in to ELMA365.
    • External. When this option is selected, the method will be available from the external system via a token.
  • Asynchronous start. This option allows you to continue your work without waiting for method execution to finish.
  • Description. Write a detailed description of the method.
  1. Go to the Scripts tab and write the method source code. Use the TypeScript programming language. To learn more about the basic principles of script writing in ELMA365, please visit ELMA365 TS SDK.
  2. Save and publish the method.

Access to the global constants

You can use the Global constant in API methods to access variables inside workspaces as well as global parameters. However, using this object restricts the module export. It means that if you enable access to the Global constant in an API method, you will not be able to export the module.

To enable access to the Global constant:

  1. In the method editor, go to the Scripts tab.

extention-API-2

  1. In the top menu, click Settings.
  2. In the window that opens, select the Global option.

Call an API method from a script

After creating an API method in a module, you can call it in any script of this module. To do that, use the api property of the Namespace global variable:

let response = await Namespace.api.some_method.call({
    method: "POST",
    headers: {
        "X-My-CutomHeader": "Some header data"
    },
    query: {
        "skip": "0",
        "take": "10"
    }, body: "Any body here"
});

The FetchRequest type is sent to this method and is used in the fetch() method.

When this method is called, a web call to the API method is made using the standard HTTP protocol. Therefore, the response from the method comes as a standard FetchResponse object.

To configure modules with webhooks, you can get an API method address using the Namespace.api.some_method.getUrl() command. It will return a string with the full address of this method for further calling. This method is useful when a third-party service requires you to specify a return address for a call.

Service headers

In API methods, each request object passed into a script contains headers that store information about the invoked method:

  • :method. The HTTP method.
  • :path. The part of the URL method address that comes after the domain, along with query parameters. For example, /test1/test2?q=12345&n=aaa.
  • :scheme. The protocol used in the method: either http or https.
  • :authority. The domain and port (excluding 80 and 443) from which the request originated. Examples include elma365.eu or local.elma365.dev:4200.

Server dependencies

ELMA365 On-Premises users, when working with API methods in modules, can utilize npm packages during script development. For more details on this, refer to the article Server dependencies in npm packages.

Additionally, on the ELMA365 On-Premises server, activate the feature flag allowAttachExtensionScriptFiles. The Files tab will be added to the API method editor. This allows you to upload files and subsequently access them in scripts by their IDs.

Found a typo? Highlight the text, press ctrl + enter and notify us