Triggering procedures with REST API Calls from within Board

Options
Center of Excellence
Center of Excellence Employee
5 Likes First Anniversary First Comment Name Dropper
edited November 2023 in Best Practices
image.png

1. Abstract

This article discusses the possibilities of triggering Board procedures via Rest API Calls from within Board itself and the how’s and why’s of this approach. 

2. Context

The Board Public APIs empower external systems to seamlessly interact with a Board application. By utilizing REST API calls, you can, for instance, initiate procedures within a Board database. Furthermore, the 'Rest API call' procedure step enables you to trigger another Board procedure from within Board itself, presenting a multitude of use cases and benefits discussed in this article. 

3. Content

3.1 Using a Rest API call to trigger a procedure 

To execute a procedure through the API, navigate to the 'Rest API Call' step located in the Execution Flow section of procedure steps. First, select a connection (please refer to the manual for setup instructions). Next, you'll need the API path, which follows the format /procedure/Execute/[Procedure Name]. The required method for calling a procedure is "POST". Finally, you must specify how you want to handle the output. If you wish to run the target procedure in the background, refrain from selecting the "Show dialog" option. 

Here's an example of what a REST API call might look like: 

image.png

3.2 Passing selections with the Rest API call 

Starting with the Board 2023 Summer Release, you can transmit procedure selections with the REST API call to the target procedure. This functionality essentially replicates the 'Copy current select' option of regular procedure calls, with the difference that API calls require handling selections individually. Consequently, the target procedure will commence with all the selections provided. 

Selections can be passed using the '@Selection_Ex' feature as parameters. The setup appears as follows: 

  • Parameter Name: Name of the entity 
  • Value: @Selection_Ex(Entity="[Entity Name]", Display="Code") 
  • Type: QueryString 

An example REST API call with selections might resemble this:  

image.png

3.3 Use Cases 

3.3.1 Running a procedure outside of security restrictions 

One compelling reason to utilize a REST API call to invoke another procedure, instead of the conventional 'Call procedure' method, is to execute a procedure beyond the constraints of a user's security settings. This can prove essential, particularly in scenarios like intercompany calculations, where a user's security permissions might prohibit access to certain company data. 

It's important to note that a procedure initiated through a REST API call is always executed by the designated API user, not the user who initiated the initial procedure. Consequently, if the API user is not bound by specific selections, the procedure will run with unrestricted access to the entire database, including all companies. This presents an alternative to using the "Run as administrator" option in the 'Remove selection' steps of procedures, which might be required at multiple junctures. The REST API call provides a streamlined approach to bypass security selections when necessary, requiring only one call. 

3.3.2 Parallelization of calculations 

Another valuable use case involves the parallelization of calculations. By default, Board procedures run sequentially, meaning each step is executed only after the preceding one is complete. This sequential process can result in extended runtimes when dealing with numerous or time-consuming steps. To mitigate this, you can parallelize different portions of the procedure using API calls. This outsources the execution of target procedures, with only the REST API calls running sequentially while the ensuing calculations are processed concurrently. However, a few considerations are in order: 

  • Running multiple calculations in parallel can strain the server's resources, as it consumes more RAM. 
  • It's crucial to ensure that calculations can function in parallel without relying on the completion of all other steps. This is particularly relevant for concurrent calculations, such as those pertaining to different plan versions. 
  • There are limitations to API calls: 
  • 500 calls per day, with the possibility of increasing this limit through additional licenses. 
  • 10 calls per second, a fixed limit. 

3.3.3 Triggering procedures on different databases with applied selections 

Using the normal “Call procedure” step, when calling a procedure in a different database it is not possible to pass any selections to it. A way around this is to also use a Rest API Call to execute the other database’s procedure, as using the abovementioned parameters it is also possible to pass the current selection to the other database. Just make sure to adjust the parameter name to the target database’s entity names if necessary. 

3.3.4 Triggering procedures on multiple servers 

Yet another compelling use case involves initiating procedures on multiple servers simultaneously. By default, a Board procedure can only trigger procedures within the same environment. This limitation means that when employing a multi-environment approach (e.g., development, testing, production), procedures can only invoke other procedures within the same server. A viable solution to this issue is through the use of API calls. These calls have the capability to trigger a procedure regardless of the server. For instance, if you need to refresh master data across all servers or extract specific data from your data warehouse concurrently, API calls offer a solution. In such a scenario, you can create an API source for all respective systems on a leading server and simply call each one within a procedure. 

Tagged:

Comments

Categories