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.

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

• Name*. Enter the method 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 whose name 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.

6. Go to the Scripts tab and write the code. Use the TypeScript programming language. To learn more about the basic principles of script writing in ELMA365, please visit ELMA365 TS SDK.
7. Save and publish the method.

Access to global constants

By default, API methods can only access workspace components at the level of which they are configured. You can additionally access other system objects via global constant. To do this, in the method editor go to the Scripts tab and click Settings in the top panel.

You can use the following options:

• Global constants. Check the Global option to be able to refer to objects from all workspaces in the system and to global parameters. The Global constant is used for this purpose.

начало внимание

When using the Global constant to write an API method, a module with this method cannot be exported.

конец внимание

• Optional dependencies (available in the Imports object). Select workspaces or user modules and set optional dependencies for them. After that, they can be accessed in scripts via the Imports constant. When using optional dependencies, the module can be exported without restrictions.

• To create a dependency, click +Add Workspace and select a system component. Then, in the Alias column, set a unique name for it that will be used in the script. Latin letters and numbers are acceptable, and you can use an underscore to separate words. By default, the workspace code or module ID is used.

начало внимание

To make the adding optional dependencies available, the system administrator needs to enable the allowScriptImportsDependencies flag

конец внимание 

Use files in scripts

You can use images, document templates, instructions, etc. in the module scripts. To do this, in the method editor, go to the Files tab and upload the required document.

Open the file in view mode and copy its identifier in the URL of the page. Using the identifier, you can refer to the uploaded file in any module scripts.

Server dependencies

In ELMA365 On-Premises, you can add npm packages with server dependencies on the Files tab. Read more about it in the Server dependencies of npm packages article.

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 an external 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.

Was this helpful?

Thanks for your feedback!

Please specify why:

Recommendations did not help meArticle is hard to understandDidn`t answer my questionContent does not match the topicOther

How we can improve it?

YesNo

Please specify whyRecommendations did not help meArticle is hard to understandDidn`t answer my questionContent does not match the topicOther

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