Skip to content

MVrest quick start

How to expose an MVsharp subroutine as a REST service in the fewest steps.

Introduction

This guide walks through the minimum steps needed to publish a BASIC subroutine as a REST service with MVrest. The guide covers the following areas:

  1. Creating the MVrest configuration files in an account.
  2. Defining classes that shape the JSON returned.
  3. Defining a REST method that calls a subroutine.
  4. Deploying and starting the REST server.
  5. Stopping, resetting and checking the status of the server.

MVrest differs from the MVsharp REST interface in two ways. It gives you full control over complex JSON structures returned from a call, and it runs as a self-hosted .NET Core application, so no IIS or web server configuration is required.

Generated source is overwritten

Deployment generates a complete .NET Core project with full source. Any changes you make to that source are lost when the services are redeployed.

For full details and screenshots of every step, see Creating REST services.

Prerequisites

The following environment is required in order to use MVrest:

  1. Microsoft .NET Core 3.1 installed on the server.
  2. MVsharp 4.0.8.0 or later.
  3. MVrest Administrator 4.0.1 or later.

Setting up the account

MVrest configuration is stored in the account you connect to, so it can be backed up and restored with the account. Each account can have its own services running on its own port.

  1. Open the MVrest Administrator and select the Web Services tab.
  2. Select the Source System and Source Account where the REST services will be created.
  3. The first time you connect, accept the prompt to Create Web Services Files.

The following files are created in the account:

File name Description
MvClasses The class definitions that shape the input and output of the services. Names must be unique.
MvRestServices The method definitions and the input and output mappings for each service.

Planning your classes

Classes map attributes of a dynamic array to JSON properties. You need one class for the record itself, plus one class for each group of associated multivalues.

This guide uses an example INVOICES file:

Field name Position Description
InvoiceNumber 0 Record key (Numeric)
CustomerName 1 Single valued
Address 2 Multivalued, not associated
ProductNo 3 Multivalued, associated with 4 and 5
Quantity 4 Multivalued, associated with 3 and 5
Price 5 Multivalued, associated with 3 and 4
OrderTotal 6 Single valued

This gives two classes:

  1. Invoice containing CustomerName, Address, OrderTotal and the Invoice_Detail class.
  2. Invoice_Detail containing ProductNo, Quantity and Price.

Creating classes

Adding the classes

Create the associated classes first, so they are available to pick from the ClassName dropdown later.

  1. Enter Invoice next to Add Class and click Add Class.
  2. Repeat for Invoice_Detail.

Each property of a class can be set as follows:

Property name Description
Name The name of the JSON property.
Location The attribute number the value is taken from.
IsList True for a multivalue that is not associated with any other value.
ClassName The inner class to use, for associated multivalues.
DataType Always string, as MultiValue platforms have no data typing.

Note

ArrayLength and IsArray are deprecated and only kept for backwards compatibility.

Defining the main class

  1. Expand Class Definitions, click Invoice and click the (Collection) button in the Properties window.
  2. Click Add 4 times to create 4 properties.
  3. Set the properties as below and click OK.
Name Settings
CustomerName Location 1
Address Location 2, IsList true
OrderTotal Location 6
Invoice_Detail ClassName Invoice_Detail, Location 3 (the controlling field), IsList true

Defining the associated class

  1. Click Invoice_Detail, open (Collection) and add 3 properties.
  2. Set the properties as below and click OK.
Name Settings
ProductNo Location 3, IsList false
Quantity Location 4, IsList false
Price Location 5, IsList false

IsList stays false here because the parent Invoice class already marks the whole Invoice_Detail class as a list.

Save each class by right clicking it in the tree and selecting Save.

Creating a REST method

Server settings

Select the REST Web Services tab at the bottom of the screen and click the REST Web Services tree item. The properties default from your current connection. Check the following and click Save:

Property name Description
MVSHARPServer Hostname or IP address of the MVsharp server.
AccountName The account containing the data and subroutines.
LoginId / Password The credentials used to connect to MVsharp.
DeploymentPath The local folder where the .NET Core project will be deployed.
Route The REST route for each subroutine call.
HttpPort Port for HTTP traffic. 0 disables HTTP.
SSLPort Port for SSL traffic. 0 disables SSL.
PoolMinSize Connections started when the server starts.
PoolMaxSize Maximum concurrent connections to MVsharp.
ConnectionTimeout Seconds to wait for a connection before timing out.
IdleTimeout Seconds an idle connection stays open before it is closed.

Adding the subroutine

  1. Enter the subroutine name, for example GetInvoice, next to Add REST Subroutine.
  2. Click Add REST Subroutine.

Defining the parameters

The example subroutine is called as GetInvoice(InvoiceNo, Status, Invoice).

  1. Click the Parameters button in the Object Explorer and add 3 parameters.
  2. Set the parameters as below.
Name Settings
InvoiceNo Order 1, ParameterType Input, Type String
Status Order 2, ParameterType Output, Type String
Invoice Order 3, ParameterType Output, Type String, ClassName Invoice

Save the definition by right clicking the subroutine in the tree and selecting Save.

ParameterType is Input for values passed to the subroutine and Output for values used to build the JSON response. Type can be String, Json or dynamicarray.

The example subroutine

The following test subroutine creates and populates an InvoiceFile with two records (1000 and 1001) if it does not exist, then reads the requested invoice:

MV BASIC
Subroutine GetInvoice(InvoiceNo,Status,Invoice)
Open "InvoiceFile" To InvoiceFile Else
    Execute "Create.File InvoiceFile"
    Open "InvoiceFile" To InvoiceFile Else Return
    Rec1 = "Customer1,addr line1|addr2|addr3,prod1|prod2|prod3,10|5|22,11.99|88.98|67.12,1099.66"
    Rec2 = "Mr Joe Bloggs,370 Rivonia Blvd|Rivonia|Sandton,123-001|01x-321|667-123,1|2|3,1.99|8.77|12.55,27.44"
    Convert "," To @Am in Rec1
    Convert "|" To @Vm in Rec1
    Convert "," To @Am in Rec2
    Convert "|" To @Vm in Rec2
    Write Rec1 On InvoiceFile , 1000
    Write Rec2 On InvoiceFile , 1001
End
Status = "Record Not Found - ":InvoiceNo
Read Invoice From InvoiceFile , InvoiceNo Then
    Status = "Ok"
End
Return

Deploying the REST application

  1. Right click in the REST Web Services tab and select Publish.
  2. The project is written to the DeploymentPath and compiled. The compile results are displayed.

If the compile fails

A failed compile means there is an incorrect configuration. The generated project can be opened in VS Code or Visual Studio and run in debug mode.

Managing the REST server

For testing, start the server from the REST Web Services tab by selecting Start the REST Server. This runs the server on your local machine.

The server can then be managed with the following HTTP GET calls from a browser or REST client:

URL Description
http://localhost:{port}/api/stop Stops the REST server.
http://localhost:{port}/api/reset Resets all connections to MVsharp without restarting.
http://localhost:{port}/api/status Returns the number and status of connections.

Example status response:

JSON
[
    {
        "connection": "Thread 1",
        "lastProcessed": "2020-04-08T16:34:20.1146296+02:00",
        "messagesProcessed": 1,
        "isProcessing": false
    }
]

Next steps