API methods in custom modules

The platform allows you to create custom API methods as a part of your module and then use them in a web API or scripts in widgets, pages, and business processes. For example, you can create methods for starting a business process, complex data fetching, or set up methods for interaction with an internal or external system. You can create general-purpose methods and use them in different places repeatedly.

To create or edit a method:

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 HTTP request method: GET or POST. Specify at what address to access the method.
• Function*. Create a function to execute when getting a request.
• Authorization*. Select an authentication type to use when getting a request.
  • Internal authentication. When this option is checked, the method can only be called within the module using the Namespace.api.method_name command, for example, in other methods, widgets, business processes activities, event handlers. Read more below. The user on whose behalf the script is performed must be logged in ELMA365.
  • External authentication. When this option is selected, the method will be available from the external system by 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 here.

1. Go to the Scripts tab and write the method source code. Use the TypeScript programming language. If you'd like to know more about the basic principles of scrip-writing in ELMA365, please visit TypeScript SDK Help Center.
2. Save and publish the method.

Access to the Global constant

You can use the Global constant in API methods to access variables inside workspaces and global parameters. But, using such a constant prevents the module downloading. It means that enabling access to the Global constant in API methods limits the module export.

To enable the access to the Global constant:

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

2. In the top menu, click Settings;
3. 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 the same module. To do this, use an api property in 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 through the standard HTTP protocol. Therefore, the response from the method comes in the form of a standard FetchResponse object.

To configure modules with webhooks, you can get the 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 working with a third-party service, when it requires you to specify a return address for a call.

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