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:

Get Session Variables

Set Session Variables

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. Note that this check box has no impact when a transformation is run in Spoon instead of in the BA server.

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.