Configuring a REST data source

Creating a data source (REST)

To add a new REST data source, click on the button from the main screen toolbar. To edit a data source, select it from the list of records and click on the button.

A REST data source is added and edited through a wizard. It contains the following steps:

tip

The REST data source can also be configured to use the SoftExpert Suite APIs. For each REST interface provided by SoftExpert Suite, a REST data source must be configured. For example: to use the RIS_RISK_INTERFACE interface, you need to create a REST data source, which will be used to establish the connection and will have the necessary parameters for this interface. If, in addition to this interface, you want to use the RIS_CONTROL_INTERFACE interface, you will need to create another data source.

1. REST service data

Field	Description
Click to add an image	Click on this square to add an image that will represent the REST data source.
ID #	Enter a number or code to identify the REST data source. The ID # must contain letters and may contain numbers, but it cannot start with a number.
Enabled	Use this option to enable/disable the data source.
Name	Enter a name for the REST data source.
Service URL	Enter the URL of theREST API that will be used to perform the integration. If the service uses parameters of the PATH type, they must be entered in the URL itself (just add an endpoint, such as: https://exampleservice.com/user/{path}). Note that the PATH parameter that is entered in the URL will be added by the system in the Input parameter step; it must have a value during consumption in order for the operation to be carried out successfully.

Option	Checked	Unchecked
SoftExpert Suite internal web service	Allows selecting an internal REST API provided by SoftExpert Suite. This means there will be no need to create a source if the domain settings of the environment change.	It will not be possible to select an internal SoftExpert Suite API.

Authentication

List field	**Description **	Unchecked
None	Select this option if the service does not requireauthentication.	It will not be possible to select an internal SoftExpert Suite web service.
Basic authentication	Select this option if the service will only require user login and password. In this case, the fields for entering the username and password that will be used for this operation will be displayed.
Internal authentication	Select this option if the service is an internal service. In this case, authentication takes into account the SoftExpert Suite user who is logged in at the time of consumption.
OAuth authentication Client Credentials	Select this option if the service uses OAuth authentication with the Client Credentials flow. In this case, the fields where ClientID, Client Secret and scope must be entered will be displayed. This information comes from the service that will be consumed. The resource to get the service token must comply with the standard specified by OKTA. Click here for more information. Refer to the Example of usage to see how to create a data source with OAuth authentication.
OAuth authenticationPassword Grant New	Select this option if the service uses OAuth authentication with the Password Grant Type flow. In this case, the fields for entering User, Password, Client ID, Client Secret and scope will be displayed. This information comes from the service that will be consumed. The resource to get the service token must comply with the standard specified by OKTA. Click here for more information.
API key	Select this option if the service is an internal service. In this case, the API Key field will be displayed; the user token for the operation must be entered in it. The token used can be generated through the API Gateway section of the user data screen, when the latter is accessed from the user panel.

caution

When configuring a REST interface provided by SoftExpert Suite:

• You can get the service URL in the Reference section.
• To use the logged in user, you can select the "Internal authentication" option. To define a specific user, you can select the "API key" option.

Use the Next button, at the bottom of the wizard, to go to the next step.

2. Input parameters

In this step, the necessary parameters for consuming the REST service must be set:

1. In the Method field, select the HTTP method that will be used to request the service:

List field	Description
GET	Performs the operation of retrieving the data of the added service.
POST	Performs the operation of sending the data of the added service.
PUT	Performs the operation of updating the data of the added service.
DELETE	Performs the operation of removing the data of the added service.

2. Then, fill in the fields that will be displayed next:

Field	Description
ID #	Enter the ID # of the parameter that will be added.
Constant value	This field must be filled in if the parameter has a fixed value. This way, when the service is executed, the parameter will always have the constant value defined.
Parameter	Select one of the following options to define the parameter type: -QUERY: Indicates that the parameter will be a Query string. - HEADER: Indicates that the parameter will be a necessary Header for the request. - PATH: This option will not be available for selection. It will be presented, already selected, when the listed parameter is an endpoint in the service URL entered in the previous step.
Type	Select one of the following options to define the data type that will be used when entering the parameter value: - STRING: The parameter value will be of the text type. - NUMERIC: The parameter value will be of the numeric type. - DECIMAL: The parameter value will be numeric with decimal places. -BOOLEAN: The parameter value will be logical-type:true or false. - DATE: The parameter value will be of the date type. When this option is selected, the Date mask field will be displayed. In it, select the date format in which the parameter value should be entered. See usage examples below.

3. If the previously selected method is POST or PUT, a field will be displayed, where an example must be added to the body of the request in the JSON format. The example body will be used by SoftExpert Suite to map the attributes that will be sent by the request. See an example of the request body that can be entered in the displayed field:

{
  "id": 1,
  "name": "New example name"
}

It is also possible to send examples with date type:

{
  "id": 10,
  "name": "example",
  "admission Date": "MM/dd/yyyy"
}

The date parameter must be using the formatting value correctly. See below some examples of date formats:

Formatting	Description	Example
MM/dd/yyyy	American date standard	06/22/2023
dd/MM/yyyy	European date standard	15/03/2023
HH:mm:ss	Hours, minutes and seconds	18:37:05
KK:mm:ss a	Hours, minutes and seconds (AM/PM)	07:44:23 PM
dd/MM/yyyy HH:mm:ss	Date, hours, minutes and seconds	26/12/2023 12:30:55
dd/MM/yyyy KK:mm:ss a	Date, hours, minutes and seconds (AM/PM)	12/07/2023 11:50:02 AM
EE MMM dd hh:mm:ss Z yyyy	Descriptive date, day, time (AM/PM), time zone, and year	Tue Aug 16 12:00:00 BRT 2023

4. To add another parameter, simply click on the Add button again and repeat the procedure described. To delete a parameter, click on the button Remove button, next to the desired parameter.

caution

When configuring a REST interface provided by SoftExpert Suite:

• You must select the POST method.
• You can get the body of the request in the Reference section.

Use the Next button, at the bottom of the wizard, to go to the next step.

3. Output parameter

In this step, it is possible to insert an example for the body of the response that will be returned in JSON format. This example will be used by SoftExpert Suite to map the attributes that will be obtained in the service response. See step 3 of the "Input parameter" step description for examples of the response body that can be entered in this step.

caution

• When entering the body of the request/response in the "Input parameters" and "Output parameters" sections, problems may occur and prevent you from moving on to the next step. Refer to the Troubleshooting section for possible problems and their solutions.
• When configuring a REST interface provided by SoftExpert Suite, you can get the response body in the Integration Guide document.

Use the Next button, at the bottom of the wizard, to go to the next step.

4. Security

In this step, you can define a security list for the REST data source. Enable the desired option:

1. Private

If this option is enabled, only the users specified in this tab will be able to edit or view the REST data source. To do this, use the following columns:

• Edit: Add the users, teams, departments and/or positions that will have permission to edit the data source.
• View: Add the users, teams, departments and/or positions that will have permission to view the data source.

2. Public

If this option is enabled, then all system users will be able to view the REST data source; however, only those specified in the respective column will be able to edit it. Therefore, the View column will be disabled (since the data source can be viewed by any user). In the Edit column, add the users, teams, departments and/or positions that will have permission to change the data source data.

info

To add a user/team/department/position to the security list, simply type the desired name in the available field and select the corresponding option from the list that will be presented, or press the "Enter" key. To delete a user/team/department/position from the security list, click on the button located next to the desired record.

Use the Next button, at the bottom of the wizard, to go to the next step.

5. Summary

In this step, an overview of the REST data source configurations is presented. Use the Consumption test button to test the service being created. See more details about this operation in the "Test service" section.

Sections

• Input parameters: Presents information regarding the parameters identified in the "Input parameters" step.
• Request: Presents the request attributes defined in the "Input parameters" step, if the method defined is POST or PUT. See how to identify attributes in the "Supported data type" topic.
• Return: Presents the attributes of the response body, defined in the "Output parameters" step. See how to identify attributes in the "Supported data type" topic.

Test service

To test the configured service, click on the Consumption test button. On the screen that will open, information must be entered in accordance with the specifications of the service being consumed. Among the parameters available in the consumption test, the following information can be provided:

Parameters	Description
Path``	PATH-type parameters defined in the service URL.
Query``	QUERY-type parameters defined in the "Input parameters" step.
Header``	HEADER-type parameters defined in the "Input parameters" step.
Request body``	Parameters of the request body used to consume the services.

To consume the service, click on the Run button located at the bottom of the screen. Two types of response can be presented:

Response - Consumption test
Success	Consumption was successful. In this case, it will be possible to view a JSON containing the service return via SoftExpert Suite.
Something went wrong	There was a problem when consuming the service. See the Troubleshooting section for possible responses and their meanings.

Supported data types

Click on the Finish button to finish configuring the REST data source. This will close the wizard screen. Refer to the "Example of usage" section to see how to create a data source with GET and POST methods, and services that can be consumed successfully.

tip

• Use the Previous button at the bottom of the screen to return to a previous step in the REST data source configuration and make the necessary changes.
• Use the Close button at the bottom of the screen to exit the REST data source configuration wizard. Note that all data entered up to this point will be lost. To carry out this operation effectively, you must answer the question asked by the system.