PxPlus Web Services

PxPlus Web Services

PxPlus 2014 provides a number of Web-based services that are designed to take advantage of existing application logic - NOMADS Queries, NOMADS Charts, Report Writer and Data Dictionary. These Web services can be used with the PxPlus Dashboard and the PxPlus Web IDE and can work with either Apache or EZWeb. While iNomads allows existing graphical applications to run on the Web, PxPlus Web Services can be integrated with other Web-based applications.

PxPlus Web Services provide:

Data (XML, JSON, CSV) to Web applications. See Query Service.
Reports on demand. See Report Writer Service.
Charts as images that can be directly embedded into pages. See Chart Service.
A file maintenance panel for user input. See Maintenance Service.
URL-style read and write requests for file access. See File Access Service.

To access PxPlus Web Services, a Web server must be operating and configured to run PxPlus programs. PxPlus Web Services can run on either the PxPlus EZWeb Server or the Apache Web Server. See Web Server Configuration.

PxPlus Web Services are designed to conform to the REST design principles.

OAuth2 security can be added to restrict access to PxPlus Web Services. First, OAuth2 clients must be defined using either OAuth2 Client Maintenance or the OAuth2 Clients Object. Next, access is restricted either via NOMADS security on a query or report or by security enabled in Web Services Maintenance. For information on how to access restricted PxPlus Web Services, see Access OAuth2 Restricted Web Service.

Note:
A Web service with security enabled cannot be used with the dashboard or as an IDE task.

(OAuth2 security was added in PxPlus 2021.)

The following links provide additional information about working with XML and JSON:

	XML Object	*OBJ/XML
	System Functions	DIM( ) Generate String/Get Array Size
	Directives	DIM Define Arrays and Strings

Query Service

The following request runs the NOMADS Query (qry) Service to return data:

GET http://..site../services/qry.pxp?qry=query&lib=library

Parameters:

	qry=	Name of the query panel in the NOMADS library.
	lib=	Name of the NOMADS library.
	type=xxx	Output type (CSV, JSON, XML, HTML, PDF, TABLE) (*Default* is CSV.) For information on the TABLE output type, see Table Output for Query Web Service.
	dir=dddd	Directory in which it is to run if not the document root directory.
	sort	Column to use for sorting the query output. If no sort column is specified, the query output will be sorted based on the Query Definition. Columns defined as "hidden" in the query definition are not available as sort columns. (The Sort parameter was added in PxPlus 2019.)
	descending	Set to "1" or "Y" to sort the query output in Descending order. To sort in Ascending order, do not set this value at all, or set to "0", "N" or "null". This parameter is ignored unless the sort parameter has been set. (The Descending parameter was added in PxPlus 2019.)
	records=###	Number of records to display in the query output. If "null", *all* records will be displayed. (The Records parameter was added in PxPlus 2019.) *Example:* A Clients query with the Sort parameter set to the Year-to-Date Sales column, Descending set to On and Records set to 20 would result in a query output consisting of 20 records with the highest Year-to-Date Sales values in descending order.

A Web Services Maintenance utility has been added that simplifies the creation of a URL value.

(The Web Services Maintenance utility was added in PxPlus 2016.)

Chart Service

The following request runs the Chart Service to return a chart:

GET http://..site../services/chart.pxp?qry=query&lib=library&chart=name

Parameters:

	qry=	Name of the query in the library.
	lib=	Name of the NOMADS library.
	chart=	Name of the chart.
	type=xxx	Output type (PNG, HTML). *Default* is PNG.
	dir=dddd	Directory in which it is to run if not the document root directory.
	animate	Animate the chart. (HTML only where possible)
	width=	Width of the chart (in pixels). (If omitted, HTML is full screen resizable, PNG = 600.)
	height=	Height of the chart (in pixels). (If omitted, HTML is full screen resizable, PNG = 3/4 of width.)

The following is a list of Chart Service parameters for non-query based charts (chart=xxxx not provided in URL):

	style=	Chart style.
	data=	Data to chart; e.g. "Name=val,val,val;Name=val,val,val" (If not supplied, qry and lib then use query values.)
	max=	Maximum value for chart.
	labels=	Comma-separated list of value names.
	title1=	Chart title.
	xAxisTItle=	Chart X-Axis sub-title.
	yAxisTitle=	Chart Y-Axis sub-title.

A Web Services Maintenance utility has been added that simplifies the creation of a URL value.

(The Web Services Maintenance utility was added in PxPlus 2016.)

Report Writer Service

The following request runs the Report Writer (rpt) Service to return data:

GET http://..site../services/rpt.pxp?rpt=reportname

Parameters:

	rpt=	Name of the report file.
	type=xxx	Output type (PDF, HTML, CSV). *Default* is PDF.
	dir=dddd	Directory in which it is to run if not the document root directory.
Note: Includes all report parameters as well.

A Web Services Maintenance utility has been added that simplifies the creation of a URL value.

(The Web Services Maintenance utility was added in PxPlus 2016.)

Maintenance Service

The following request runs the File Maintenance Service to generate a file maintenance panel with controls based on a specified Data Dictionary table where the primary key has only one segment:

(The File Maintenance Service based on a data dictionary was added in PxPlus 2016.)

GET http://..site../services/maint.pxp?dir=directory&dict=dictionary&table=tablename&key_field=keyfield

Parameters:

	dir=	Path for the starting directory (may contain Start_up program).
	dict=	Pathname for the data dictionary file, providex.ddf.
	table=	Data table name in the data dictionary.
	key_field=	Key field in the data table.

A Web Services Maintenance utility has been added that simplifies the creation of a URL value.

(The Web Services Maintenance utility was added in PxPlus 2016.)

File Access Service

The following HTTP GET request runs the File Access Service for a read request:

GET "http://localhost:8080/services/fileaccess.pxp?function=read&dir=data_path&dict=dict&table=table_name&beg_key=key&end_key=key&filter=filter&type=output_type"

The following HTTP POST request, with the write request as the POST data, runs the File Access Service for a write request (see Write Request Format):

POST "http://localhost:8080/services/fileaccess.pxp?function=write&dir=data_path&dict=dict"

Parameters:

	function=	Either Read or Write.
	dir=	Path for the starting directory (may contain Start_up program).
	dict=	Pathname for the data dictionary file, providex.ddf.
	table=	Data table name in the data dictionary.
	kno=	Key name or number. If a key number, use format #num (i.e. #0 for the primary key, #1 for the first alternate key, etc.). Only used for read requests and is optional. If omitted, defaults to #0 (primary key).
	key=	Key of the record. Optional for read requests, and if a key range or filter is specified, then the key is not needed. For write requests, the key is used only for tables with an external key.
	beg_key=	Starting key of a range of records to read. String expression. Multiple colon-separated segments may be specified, if needed. Only used for read requests and is optional.
	end_key=	Ending key of a range of records to read. String expression. Multiple colon-separated segments may be specified, if needed. Only used for read requests and is optional.
	filter=	Condition must return true or false. If a record makes the condition true, then the record is read. If the record makes the condition false, then it is not read. Usually, field name variables are used in the condition to accomplish this; e.g. taxRate>10 would only read records with a tax rate higher than 10% from a table that includes a numeric field called taxRate. Numeric or string expressions are supported. Only used for read requests and is optional.
	type=	Output type. Only used for read requests. Can be JSON, XML and CSV. If omitted, defaults to JSON.

Note:
One or more of the following arguments must be included in a read request: key, beg_key, end_key or filter. If a key argument is specified, then no beg_key, end_key or filter argument is accepted. If no key argument is specified, then you must specify one or more beg_key, end_key or filter arguments.

Write Request Format

For POST request data, the valid request types are Insert, Update and Remove. The request can be in JSON or XML:

JSON:

{ "requests":[
    {"type":"insert"|"remove"|"update",
     "table":"table_name",
     "key":"key_data",     (Optional. Required only for tables with an external key.)
     "data":[
         {"field_name ":"field_data",
         …     (All fields from the table are included here.)
    ]
    },…     (Multiple requests can be included. A comma is required only if there is another request.)
]
}

XML:

<root>
<requests>
<request>
<type>insert|remove|update</type>
<table>tablename</table>
<key>key_data</key>     (Optional. Required only for tables with an external key.)
<data>
<field_name>field_data</field_name>
…     (All fields from the table are included here.)
</data>
</request>
…     (Multiple requests can be included.)
</requests>
</root>

The Web Services Maintenance utility simplifies the creation of URL-style read and write requests for accessing files.

See Examples - File Access Web Service.

(The file access Web Service was added in PxPlus 2022.)

Note: A Web service with security enabled cannot be used with the dashboard or as an IDE task.

Query Service

Chart Service

Report Writer Service

Note:Includes all report parameters as well.

Maintenance Service

File Access Service

Note:
A Web service with security enabled cannot be used with the dashboard or as an IDE task.

Note:
Includes all report parameters as well.