A data service provides a Web service interface to access data that is stored in relational databases, CSV files, Microsoft Excel sheets, Google spreadsheets, and more. The following sections describe how to you can use WSO2 EI Tooling to create artifacts for data integrationwork with data services' artifacts.
Table of Contents | ||
---|---|---|
|
Prerequisites
- Install WSO2 EI tooling using the instructions in Installing Enterprise Integrator Tooling.
Creating a data service project
To demonstrate how data services work, we will use a MySQL database as the datasource. Follow the steps given below
...
- You can either use the link on the dashboard (click Developer Studio -> Open Dashboard) as shown below or use the File-> New -> Other -> Data Service Project option.
- On the window that appears, specify a project name.
- If you want to customize the Maven options (such as including parent POM information in the file from another project in this workspace), click Next and specify the options.
- Click Finish.
Once you have created the Data Service product, you can create multiple data services and add them to the same project. For example, if you create a data service project called DSS_Project, the folder structure will be as follows:
Creating a data service
A data service provides a Web service interface to access data that is stored in relational databases, CSV files, Microsoft Excel sheets, Google spreadsheets, and more. You can create a new data service following the steps given below. Alternatively, you can import an existing data service using the data service descriptor (DBS) file.
Step 1: Creating the datasource connection
Follow these steps given below.
...
to set up a MySQL database:
- Install the MySQL server.
Download the JDBC driver for MySQL from here and copy it to your
<EI_HOME>/lib
directory.Note If the driver class does not exist in the relevant folders when you create the datasource, you will get an exception such as '
Cannot load JDBC driver class com.mysql.jdbc.Driver
'.Create a database named
Employees
.Code Block CREATE DATABASE Employees;
Create the Employee table inside the Employees database:
Code Block USE Employees; CREATE TABLE Employees (EmployeeNumber int(11) NOT NULL, FirstName varchar(255) NOT NULL, LastName varchar(255) DEFAULT NULL, Email varchar(255) DEFAULT NULL, Salary varchar(255));
Creating a data service
Follow the steps given below to create a new data service.
Step 1: Creating a data service project
All the data services' artifacts that you create should be stored in a Data Service project. Follow the steps given below to create a project:
- Open the Developer Studio Dashboard (click Developer Studio > Open Dashboard) and click Data Service Project.
- Enter a name for the project and click Next.
- If required, change the Maven information about the project.
- Click Finish. The new project will be listed in the project explorer.
Step 2: Creating the datasource connection
Follow the steps given below to create the data service file:
- You can start creating a new data service in two ways:
- Open the dashboard (click Developer Studio -> Open Dashboard) , and click click Data Service.
- Select the already created Data Service project on Project in the navigator, right click and click go to New -> Data Service.
To start creating a data service from scratch, select Create New Data Service and click and click Next.
Type unique names Enter a name for the project and data service.:
Data Service Name RDBMSDataService Click Click Next and start adding the datasource connection the datasource connection details given below.
Datasource ID Datasource Datasource Type RDBMS Datasource Type (Default/External) Leave Default selected. Database Engine MySQL Driver Class com.mysql.jdbc.Driver URL jdbc:mysql://localhost:3306/Employees User Name root - Save the data service with the datasource connection.
A data service file (DBS file) will not now be created in your data service project. Shown below is the project directory.
Step
...
3: Creating a query
Now, letLet's add a write an SQL query to the data service.GET data from the MySQL datasource that you configured in the previous step:
- Select the data service you created in the previous step.
- Right-click and click Add Query.
Enter the following query details:
Query ID GetEmployeeDetails Datasource Datasource - Save the query. The query element is now added to the data service:
Right-click the the GetEmployeeDetails query, query and click click Add SQL SQL to add the following SQL statement:
Code Block select EmployeeNumber, FirstName, LastName, Email from Employees where EmployeeNumber=:EmployeeNumber
- Save the SQL statement. The SQL statement is now added to the query.
Right-click the query again , and click click Add Input Mapping.
Enter the following input mapping details:
Mapping Name EmployeeNumber Parameter Type SCALAR SQL Type STRING - Save the input mapping.
Right-click the query again , and click Add Output Mapping.
Enter the following value to group the output mapping:
Grouped by Element Employees Save the output mapping.
Right-click the output mapping , and go to to Add Output Mapping → Add Element to to create an element.
Enter the following element details.
Datasource Type column Output Field Name EmployeeNumber Datasource Column Name EmployeeNumber Schema Type String - Save the element.
Follow the same steps to create the following output elements:
Datasource Type Output Field Name Datasource Column Name Schema Type column FirstName FirstName string column LastName LastName string column Email Email string - Save the output elements.
The data service should now have the query element added as shown below.
Step
...
4: Creating a resource to invoke the query
Now, let's create a REST resource that can be used to invoke the query.
Right-click the datasource, data service and click click Add Resource. Add the following resource details.
Resource Method GET Resource Path Employee/{EmployeeNumber} Expand the GET resource, and click the the GetEmployeeDetails (call-query). Connect the query to the resource by adding the following:
Query ID GetEmployeeDetails - Save the resource.
The data service should now have the resource added as shown below.
Step 5: Testing the data service
You can test the data service artifacts by following the steps given below.
- Package the data service file (.dbs file) into a Composite Application (CApp). See the instructions in Packaging Artifacts into Composite Applications.
- Add your WSO2 EI product instance to the Tooling environment and deploy the CApp in the server. See the instructions in Deploying Composite Applications in the Server.
- Start the ESB profile. The data service is now deployed in WSO2 EI.
Send a GET request to invoke the service. You can use curl as shown below.
Code Block curl -X GET http://localhost:8280/services/RDBMSDataService.HTTPEndpoint/Employee/3
You will receive the employee's details in the response.
Importing a data service
Follow these steps to import an existing data service from a data service descriptor file (DBS ) filefile) to a Data Service project in Tooling. Alternatively, you can can create a new data service.
- You can either use the Data Service link on the dashboard (click Developer Studio -> Open Dashboard) or right-click on the Data Service project in the project explorer and click New -> Data Service.
- Select Select Import Data Service and click and click Next.
- Specify the data service descriptor (DBS) file by typing its full pathname or clicking by clicking Browse and and navigating to the file.
- Optionally, specify the location and working sets for this project.
- A Maven POM file will be generated automatically for this project. If you want to customize the Maven options (such as including parent POM information in the file from another project in this workspace), click click Next and and specify the options.
- Click Finish Finish. The data service is created, added and the data service is open in the editor. You can now right-click the data service in the outline and add queries, operations, additional data sources, and so on, or click the Source view to add components using XML.
Anchor | ||||
---|---|---|---|---|
|
WSO2 supports WS-Security, WS-Policy, and WS-Security Policy specifications and these . These specifications define a behavioral model for Web services. To enable a security policy for a data service, you need to first create a security policy file, and then add it to the data service.
Step 1: Creating a
...
Follow the instructions given below.
...
Open your data service in Developer Studio as explained in the Creating a new data service section given above. You can either create a new data service or import an existing DBS file.
...
registry resource project
Registry artifacts (such as security policy files) should be stored in a Registry Resource project. Follow the steps given below to create a project:
- Open the Developer Studio Dashboard (click Developer Studio > Open Dashboard) and click Registry Resource Project.
- Enter a name for the project and click Next.
- Enter If required, change the Maven information about the project and click Finish.
Right-click on the SecurityPolicyProject in the left navigation panel, click New and then select Registry Resource.
. - Click Finish. The new project will be listed in the project explorer.
Step 2: Creating a security policy as a registry resource
- You can start creating a registry resource in two ways:
- Open the dashboard (click Developer Studio -> Open Dashboard) and click Registry Resource.
- Select the already created Registry Resource Project in the navigator, right click and go to New -> Registry Resource.
Select From existing template and click Next.
Enter a resource name and select the WS-Policy template along with the preferred registry path.Anchor step5 step5
the following details:Resource Name Sample_Policy Artifact Name Sample_Policy Template WS-Policy Registry gov Registry path ws-policy/ - Click Finish and the policy file will be listed in the navigator.
Let's use the Design View
Enable required scenario.Localtabgroup Localtab title Design View Localtab title Source View to enable the required security scenario. For example, enable the Sign and Encrypt security scenario as shown below.
Tip Click the icon next
to the scenario to get details of the scenario.
You can
also provide encryption properties, signature properties, and advanced
rampart configurations as shown below.
Localtabgroup Localtab title Encryption/Signature Properties Localtab title Rampart Properties Info title Using role-based permissions? For certain scenarios, you can specify user roles. After you select the scenario, scroll to the right to see the User Roles button.
Either define the user roles inline or retrieve the user roles from the server.
Localtabgroup Localtab title Define Inline Localtab title Get from the
server
The security policy will now be saved to the resource project as shown below.
...
Save the policy file.
Step 3: Adding the security policy to the data service
Once you have configured the policy file, you can add the security policy to the data service as explained below.
Select the If you have already created a data service using Tooling, select the file from the Project Explorer. Alternatively, you can download this sample data service (.dbs file) that is already stored in the workspace, and click the browse icon file and import it to your Tooling environment.
Once you have select the data service file, click the browse icon for the Policy field.
There are two ways to add a security policy to the data service: If you have a policy file already stored in your product registry, you can add it by clicking registry. If you want to use a new policy file that you have created and stored in your current workspace, you can add it by clicking workspace.Info - Click workspace, to add the security policy from the current workspace. You can select the path to the
sample_policy.
xml file that you created in the previous steps. - Click OK, and the security policy will be added to the data service.
...
- Save the data service.
Step 4: Testing the data service with the security policy
Follow the steps given below.
Package the data service file (.dbs file) and the security policy file into a Composite Application (CApp). See the instructions in Packaging Artifacts into Composite Applications.
Warning Once you create the CApp project, note that the information about each of the projects and artifacts that you packaged into the CApp will be listed (under Dependencies in the Composite Application Project POM Editor).
Be sure to set the server role to Enterprise Service Bus
...
for the security policy file as shown below
- Add your WSO2 EI product instance to the Tooling environment and deploy the CApp in the server. See the instructions in Deploying Composite Applications in the Server.
Start the ESB profile. The data service and the security policy is now deployed in WSO2 EI.
Filtering content by user role (Optional)
When you work with data services, you can control access to sensitive data for specific user roles. This facility is called role-based content filtering. It filters data where specific data sections are only accessible to a given type of users. Follow the instructions given below to add role-based filtering for output elements in your data service.
- Open the data service file in WSO2 EI tooling.
- Add an output element to your data service:
- Right-click the data service and click Add Query to add a new query.
- Right-click the query and click Add Output Mapping to add an output mapping.
- Right-click the output mapping and go to Add Output Mapping → Add Element to add an element.
- Right-click the data service and click Add Query to add a new query.
- Add the user roles as a comma-separated list in the Allowed User Roles field for the output element as shown below.
Creating a custom validator
An input validator allows a data service to validate the input parameters in a request and stop the execution of the request if the input doesn’t meet the required criteria. In addition to the default validators provided by Data Service Server, you can create your own custom validators by creating a Java class that implements the org.wso2.carbon.dataservices.core.validation.Validator
interface. You can create a new custom validator or import an existing validator project.
...
- You can either use the Data Services Validator Project link on the dashboard (click Developer Studio -> Open Dashboard) or click File-> New -> Other -> Data Services Validator Project option.
- Select Create New Data Services Validator Project and click Next.
- Type a unique name for the project and specify the package and class name for this validator.
- Optionally, specify the location and working set for this project.
- A Maven POM file will be generated automatically for this project. If you want to customize the Maven options (such as including parent POM information in the file from another project in this workspace), click Next and specify the options.
- Click Finish. The project is created, and the new validator class is open in the editor , where you can add your validation logic.
...
Follow these steps to import an existing custom validator project. Alternatively, you can create a new custom validator.
- You can either use the Data Services Validator Project link on the dashboard (click Developer Studio -> Open Dashboard) or click File-> New -> Other -> Data Services Validator Project option.
- Select Import Project From Workspace and click Next.
- Select the existing validator project, and optionally specify the location and working sets for the new project.
- A Maven POM file will be generated automatically for this project. If you want to customize the Maven options (such as including parent POM information in the file from another project in this workspace), click Next and specify the options.
- Click Finish. The project is imported, and the validator class is open in the editor, where you can modify the validation logic as needed.
...
Once you have created the data service artifacts as explained in the previous topics, you need to create a Composite Application project, and then create a CAR file to deploy it in the ESB server.
- Right-click the Project Explorer and click New -> Project.
- From the window that opens, click Composite Application Project.
- Give a name to the Composite Application project and select the projects that you need to group into your C-App from the list of available projects.
In the Composite Application Project POM Editor that opens, under Dependencies, note the information for each of the projects you selected earlier. If you have added a security policy to your data service using a registry resource as explained above, be sure that EnterpriseServiceBus is selected as the server role as shown below.
- To deploy the artifacts using the ESB's management console, you need to create a CAR file as follows:
- Right-click the C-App project and select Export Composite Application Project from the pop-up menu.
OR - Open the
pom.xml
file in the Composite Application Project POM Editor and click the button for creating an archive in the upper-right corner.
Info The CAR file is now saved in the location you specify. See Packaging Artifacts into Composite Applications, for more information on using CAR files
- Right-click the C-App project and select Export Composite Application Project from the pop-up menu.
- Next, deploy the CAR file in the server.