Skip to content

Getting Started with Service Builder

The first thing to get started with data access service (DAS) is to get familiar with Service Builder. This tutorial walks you through the general steps of working with Service Builder, including

  • Setup
  • Development, and
  • Inspecting and testing DEV deployment.

To make this tutorial short, we will only show you the steps to generate a simple repository service from DB table. For steps to create the query, SQL and non-trivial repository services, please move on to our second tutorial:

Get Started with Data Access Services

The sample database used for both tutorials is the classicmodels database from mysqltutorial.org. The ER diagram is available here.

The Service Builder must connect to a workspace on a development server/platform to work. Therefore,

  • As a prerequisite, you will need to launch the development server and sample MySQL database on your local machine following the Get Started with Development Server tutorial.
  • Register the Service Builder with the development server to create and connect to a workspace.

However, you may also clone the Service Builder DevContainer project for a fully integrated development environment that includes the development server and a MySQL and a PostgreSQL database.

Note: The Service Builder DevContainer is the recommended way to set up the development environment. If you do use the Service Builder DevContainer, you may go to the Development section directly once the DevContainer is up.

Prerequisite

VS Code (version 1.87.0 or later) installed.
Development Server and sample MySQL database running on local machine.

Setup

Launch VS Code

From your OS terminal, create a work folder for Service Builder and launch VS code from the work folder:

mkdir builder
cd builder
code .

Install Service Builder

From the Extensions Explorer of VS Code, search and install Service Builder Pack, which includes the following VS Code extensions:

The JSON Grid View and REST Client extensions are required by some parts of Service Builder.

Activate Service Builder

Click the Service Builder icon Alt on the Activity Bar of VS Code. The Service Builder view opens up in the side bar, with three explorers:

  • The APPLICATIONS explorer at the top, for developing data access application in local workfolder and deploying it to remote workspace.
  • The DATA SOURCES explorer in the middle, for configuring data sources in local workfolder and deploying it to remote workspace.
  • The DEPLOYMENTS explorer at the bottom, for inspecting data sources and applications deployed in remote workspace.

service-builder-explorers

Register Service Builder

  • From the APPLICATIONS bar, click the more icon ..., and select Register Builder;
  • Enter dev server URL http://localhost:8080 in the input box, and hit Enter;

The Service Builder is connected to a new workspace on the development server.

Development

Create Data Source

  1. Add Data Source

    • On the DATA SOURCES bar, click the Add icon Alt;
    • Enter mydb for the data source name in the input box, and hit Enter;
    • Select mysql for database type in the quick pick.

    A data source named mydb is created.

    datasource-creation

  2. Configure Data Source

    • Click mydb to open the data source configuration file;

    • Copy and paste the following into the file:

      {
    "dbType": "mysql",
    "host": "mysql",
    "port": 3306,
    "database": "classicmodels",
    "username": "sample",
    "password": "password123",
    "comments": "mysql data source"
}

      which configures the sample MySQL running on the local machine as the data source.

    • Save the file.

    datasource-config

  3. Test Data Source

    • Click the TEST icon Alt on the mydb bar;

    The status bar at the bottom reads "data source test succeeded":

    datasource-test-succeed

    The password is stored as secret in the Service Builder and masked in the data source file.

  4. Deploy Data Source

    • Click the DEPLOY icon Alt on the mydb bar.

    The status bar reads "data source deployed".

    datasource-deployed

    The data source is deployed into the remote workspace with the password encrypted.

Create Application

  1. Generate Application

    • From the APPLICATIONS bar, click New Application icon Alt
    • Enter myApp as application name. Hit Enter.
    • Select mysql as database type.

    An application named myApp is generated:

    application-generated

  2. Configure Application

    • Open the application.json file;
    • Change dataSource value to mydb, and save.

    application-configured

    Note that you may optionally configure the schema to use with the application. Otherwise, the application schema defaults to the database property of the data source associated with the application, as in this case.

  3. Deploy Application

    • From the myApp bar, click the DEPLOY icon Alt;

    Application is deployed into remote workspace. The status bar reads "application deployed".

    application-deployed

    Note: The application must be deployed before proceeding to service development.

Create Module

  1. Generate Module

    • From the myApp bar, click New Module icon Alt.
    • Enter myMod as module name. Hit Enter.

    A module named myMod is generated for application myApp:

    module-generated

  2. Configure Module

    • Skip. Nothing to configure other than a description of the module.

  3. Deploy Module

    • Skip. The module will be deployed when the service is deployed.

Generate Simple Repository Service from Database Table

Note: here we are to generate a simple repository service from the offices table, for a simple Offices object mapped to the offices table. You may generate simple repository services from multiple tables at once, but here we only generate one service from the offices table.

  1. Generate service

    • From the myMod bar, click Generate repository from table icon Alt;
    • Select table classicmodels.offices from the quick pick. Hit Enter;
    • Select none for name convention.

    A simple repository service named Offices is generated for offices table:

    simple-crud-generated

Since no name convention is applied, the field names of the object match exactly the column names of the table.

  1. Review Service

    • Open object.json file to review the object structure and fields;
    • Open input.json file to review the input parameters for the read query;
    • Open query.sql file to review the SQL query for read operation;

    • From input-bindings bar, click the JSON viewer icon Alt, to open and review input bindings in JSON file and JSON grid side by side:

      input-bindings-view

    • From output-bindings bar, click the JSON viewer icon Alt, to open and review output bindings in JSON file and JSON grid side by side;

    • From tables bar, click the JSON viewer icon Alt, to open table bindings in JSON file and JSON grid side by side. Drag JSON grid below JSON file to get a better look of the table bindings:

      table-bindings-view

    • From offices.columns bar, click the JSON viewer icon Alt, to open columns bindings in JSON file and JSON grid side by side. Drag JSON grid below JSON file to get a better look of the column bindings.

      column-bindings-view

To make any change to the bindings file, just edit the JSON file. The change will be automatically reflected in the JSON grid.

  1. Generate Test

    • From tests bar, click Add Test icon Alt;
    • Select All from the quick pick. Hit Enter.

    Five tests are generated, one for each repository operation:

    tests-generated

  2. Executing Test

    • Open testReadOffices.json file;
    • Edit input of the test, to set officeCode to "1";
    • Click Run Test icon Alt in the upper right conner.

    Test is executed and test result is displayed on the right side.

    read-offices-test-output

  3. Deploy Service

    • From the Offices service bar, click the DEPLOY icon Alt;

    Service is deployed and the status bar reads "service is deployed.".

    service-deployed

Sync Application

From the myApp application bar, click the the DEPLOY icon Alt to redeploy the application, which syncs the application deployed in the remote workspace with the application in your local work folder.

Inspect and Test Deployments

  1. Inspect Data Source Deployment

    • From the Data Sources bar of DEPLOYMENTS explorer, click Refresh Data Source List icon Alt, to show the list of data sources deployed in the workspace.

      view-datasource-list

  2. Inspect Application Deployment

    • From Applications bar of DEPLOYMENTS explorer, click Refresh Application List icon Alt, to show the list of applications deployed in the workspace.

      view-application-list

    • From myApp bar in DEPLOYMENTS explorer, click Refresh Application icon Alt, to show the list of services of the application deployed in the workspace.

      view-services

  3. Test Service Deployment

    • From Offices bar in DEPLOYMENTS explorer, click View Tests icon Alt, to show the test file for the service.

      view-services

    All tests deployed into the remote workspace with the service are consolidated into a single test.http file, in a format that can be readily executed with the REST Client VS Code extension.

    • Open the test.http file, and from the file click Send Request under ### testReadOffices. The test is executed and response is shown on the side.

      view-services

The test is executed from the workspace service endpoint.

Conclusions

In this tutorial, we have shown you:

  • how to install and activate Service Builder.
  • how to register the builder with the Development Server to connect to a remote workspace,

as the setup process; shown you:

  • how to add and configure a data source.
  • how to create an application and module, and
  • how to generate a simple repository service from DB table,

as the development process; and shown you:

  • how to inspect the data sources and applications deployed in the remote workspace, and
  • how to test the data access services deployed in the remote workspace through the workspace service endpoint,

as the deployment inspection process.

What Is Next

Move on to Get Started with Data Access Services.