Call Endpoint
Overview
Call Endpoint step helps users who want to build custom solutions for the BA Platform using the Pentaho API. Pentaho API is REST-based, so it can be operated using HTTP calls. This step exposes the Pentaho public API and offers an interface which allows advanced users to build custom solutions which interact with a running BA Server. Click here for a list of the available Pentaho public APIs.
Audience: Developers with previous experience with programming and API use.
Description
The Call Endpoint step performs a call from within a PDI transformation to endpoints in your running Pentaho system. The BA platform contains a rich amount of extensible endpoints for users to customize the BA platform. This step connects to the BA server, allowing users to view the available endpoints, and then calls the specified endpoint in your transformation. You can employ this step in one of two ways:
- Inspect the server for an endpoint. If the user is connected to a server and wants to search for an endpoint against that server, you can use this step to fetch and display the public information stored on the server about the selected endpoint. The available endpoints on the server are considered "public endpoints" and are supported by Pentaho.
- Manually enter an endpoint. The user can manually define the endpoint he wants to call, such as an unsupported endpoint. These endpoints are not supported by Pentaho and should be used with caution because their behavior can change without notice.
See Also:
Options
The Call Endpoint step features several tabs with fields. Each tab is described below.
BA Server Tab
Option |
Description |
|---|---|
Step Name |
The name of the step as it appears in the transformation workspace. This name must be unique within a single transformation. |
URL |
The base URL string used to connect to the server. |
User Name |
The user name required to access the server. |
Password |
The password associated with the provided user name which is passed during the authentication process. |
Test Connection button |
Select this button to test the connection to the BA server using the information provided in the above fields. |
Use authentication from BA Server session check box |
Select this check box to authenticate the user using the credentials from the current BA server session when the transformation is run from the BA Server. If the check box is clear, the user is authenticated using the username and password provided. It is recommended that you use session authentication when available. |
API Endpoint Tab
Option |
Description |
|---|---|
From Server |
Select this option to retrieve the API endpoint you want to use from those available in the BA Server. A list of available endpoints appears in the Web Service Endpoint group box. When this option is left unselected, the drop-down lists in the group box will be empty. Click here for more information on available Pentaho public APIs. |
Refresh Endpoints |
Select this button to refresh the list of available API endpoints from within the BA server which displays in the Web Service Endpoint group box. It is recommended that you select this button whenever you select the From Server option. |
Fields upstream |
Select this option to retrieve the API endpoint from the transformation on your canvas. This endpoint is considered 'dynamic' and is dependent on the transformation. |
BA Server Module |
Specify the Pentaho module where the endpoint is located on the server. Click in the field to display a drop-down list of available modules. For example, you may want to include an endpoint specific to the Pentaho platform module. You can find information on available Pentaho public APIs here (mks://localhost/Documentation/5.4/0R0/070). Note that when From server is selected as the endpoint location, this list automatically generates. You may need to click the Refresh Endpoints button to view the complete list. |
Resource Path |
Specify the path of the API endpoint. Click in the field to display a drop-down list of available paths for public APIs. A description of the selected API endpoint, if available, displays in the Resource Path Details box on the right side of the tab. If you choose to use an unsupported API endpoint, you must type its path into the field. Note that unlisted APIs are not supported by Pentaho, and their usage may affect your results. |
HTTP Method |
Specify the method for the selected path of the API endpoint, such as 'GET' and 'PUT'. Note that some of the resource paths are associated with multiple methods, such as 'platform/repo/files/{pathId }/localeProperties', so it is recommended that you verify your selection. |
Resource Path Details |
A description of the selected API endpoint. |
Parameters Tab
The Parameters tab enables you to specify parameters associated with your selected API endpoint. Not all endpoints have associated parameters. Entering parameter information must be done manually by the user.
Option |
Description |
|---|---|
# |
The order which this parameter will be passed. |
Field |
Specify the name of the field which contains the value to map to the parameter. |
Parameter |
Specify the name of the parameter. |
Default |
Specify the default value to map to the parameter. |
Output Fields Tab
The Output Fields tab enables you to specify how the result will display for your selected API endpoint call when the transformation is run.
Option |
Description |
|---|---|
Result Name |
Specify the field which will store the result of the endpoint when it is called in a transformation. By default, the field 'Result' is used. It is recommended that you provide a more specific result name. |
Status Code Name |
Specify the field which will store any possible error codes and other variables. |
Response Time Name |
Specify the field to which you want to post the response time (in milliseconds). |
Sample Transformations
Below, are descriptions of six sample transformations included in the attached archive.
- callEndpointExample.ktr -- This transformation executes three different endpoint calls where the module, service , and method are parameterized from the input fields.
- setSessionVariable.ktr -- This transformation illustrates setting a session variable from an input stream. The Data Grid step is used to generate the field.
- getSessionVariable.ktr -- This transformation retrieves the variable defined in the SetSessionVariable.ktr sample.
- getRolesForUser.ktr -- This transformation fetches the roles for the 'Admin' and 'Suzy' personas by executing two calls to the /userrolelist/getRolesForUser endpoint.
- listRepository.ktr -- This transformation executes two calls to the repository, fetching the folder structure from the repository from /Home. One call is executed with a depth of '1' and the other with a depth of '4'.
- showPlatformVersion.ktr -- This transformation executes an endpoint call to retrieve the platform version.