# PxPlus Web Services

Web Services Maintenance |

The Web Services Maintenance utility simplifies the creation of URLs for PxPlus Web Services. Using this utility, you can create records and define the parameters for different types of Web services. Once Web service records are created, you can customize the PxPlus Dashboard by adding widgets. See Adding and Maintaining a Widget.

In addition, Web services can be run on a Web browser. See Running the Web Service on a Browser.

You can define Web services as tasks that can be added to a menu and launched from the IDE Main Launcher. See Task Definition.

You can also define Web services that create REST-based URL-style read and write requests for file access. See Examples - File Access Web Service.

(The Web Services Maintenance utility was added in PxPlus 2016.)
(Support for defining Web services as tasks was added in PxPlus 2017.)
(The file access Web service was added in PxPlus 2022.)

To invoke Web Services Maintenance, use one of the following methods:

Location | Method
From the PxPlus IDE Main Launcher (Windows) | Expand the Web Deployment category and select Web Services Maintenance.
From the PxPlus Web IDE | Select Web Deployment > Web Services Maintenance.

Below are examples of Web Services Maintenance with a Query record and a Chart record entered.

| Web Services Maintenance - Query record | Web Service Maintenance - Chart record

This window consists of the following:

Settings | Menu bar option that displays the following:
Force ID in URL | When unchecked (default), you can add widgets to the Dashboard by specifying the Web Service ID to use and the required parameters. #### Warning! Leaving this option unchecked may allow users with knowledge of the system architecture to access data in files that they should not be allowed to access. Selecting this option (shows a check mark) forces the use of the new Web Service ID for all widgets on the Dashboard. For added security, the Allow Override checkbox should be unchecked for any parameters other than Type, Width and Height.
Service ID | Enter a unique alpha-numeric ID. Maximum length is 20 characters. When creating a record, type a new Service ID. To select an existing record, click the Query button (binoculars), use the browse buttons, or type the ID.
Copy Web Service | (Available when an existing Web Service ID is selected) Button used to create a new Web Service ID by copying the settings from an existing Web Service ID. Once it is created, the new Web Service ID must be saved, as the Copy process does not do this. (The Copy Web Service button was added in PxPlus 2020.)
Service Type | Select the type of Web service. This field is available when creating a new Service ID record. For an existing record, it can only be viewed. If the Service Type needs to be modified for an existing record, you will need to delete that record using the Delete button and then create a new record. Select from the list of available Service Types:
Query | (Default) Displays a list containing data from one or more linked files. For information on queries, see Query Subsystem.
Chart | Displays a defined chart (i.e. pie, bar, column, line). For information on charts, see Charting.
Report | Displays the contents of a defined Report Writer report. For information on reports, see Report Writer.
Maintenance | Generates an HTML form for user input with fields from the specified data table. For information on data dictionary definitions, see Data Dictionary. As of PxPlus 2017, the appearance of Maintenance Web Service pages can be customized by specifying the settings to be applied in a user-defined *web/services/maint_style.css style sheet.
File Access | Creates REST URL-style read and write requests for file access. See PxPlus Web Services and Examples - File Access Web Service.
#### Note: The Service Type determines the parameters that are loaded into the grid. See Parameter. (The File Access service type was added in PxPlus 2022.)
Select Chart | (Available when Service Type is Chart) When creating or editing a Web Service ID record with a Chart Service Type, select this button to invoke the Select a Chart Definition window. This window presents a tree-view structure that lists all of the public query AutoChart definitions that exist at the current display level and lower, arranged by directory, screen library, query and chart definition. When a chart definition is selected, the values for the Title, Dir, Lib, Qry and Chart parameters on the Web Services Maintenance window are automatically populated. Alternatively, a chart can be selected by manually entering the values for these parameters. (The Select Chart button was added in PxPlus 2020.)
Parameter | Lists the standard parameters to be supplied to the Web service, based on the Service Type selected. Not all of the parameters are mandatory. Hover the mouse pointer over a parameter in the grid to display a tooltip with a brief description of that parameter. A description of each parameter and the Service Type(s) to which it applies is provided below. To define a parameter as an expression, enter the value beginning with "=" (equals sign). User-defined parameters, such as parameters defined for a report, can be added in the blank row(s) at the bottom of the grid. #### Note: User-defined parameters cannot be named the same as the standard parameters that exist for any of the service types (i.e. Title, Dir, Lib, Dict, Table, Type, etc.).
Title | (Query, Chart, Report, Maintenance and File Access Types) Enter the text to use for the title if adding the current Web Service ID to the JSON file (see Add as an Option in JSON file). Maximum length is 50 characters. #### Note: Title is required when updating to the JSON file.
Function | (File Access Type) Select whether the Web service will Read or Write to PxPlus files. (The Function parameter was added in PxPlus 2022.)
Dir | (Query, Chart, Report, Maintenance and File Access Types) Path for the starting directory. May contain Start_up program.
Lib | (Query and Chart Types) Pathname for the NOMADS screen library.
Qry | (Query and Chart Types) Query object name.
Type | (Query, Chart, Report and File Access Types) Select the Output type:
Query | CSV, JSON, XML, PDF, HTML, TABLE (Default: HTML)
Chart | PNG, HTML (Default: HTML)
Report | CSV, HTML, PDF (Default: PDF)
File Access | CSV, JSON, XML (Default: JSON)
#### Note: For Maintenance, the type is always HTML. (File Access was added in PxPlus 2022.)
Sort | (Query Type) Select the 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. To clear a selected Sort column, select the "null" option from the drop down list. (The Sort parameter was added in PxPlus 2019.)
Descending | (Query Type - Available when a Sort column is selected) When unchecked (default), the query output will be sorted in Ascending order. #### Note: The Descending parameter will reset to the default (unchecked) if the Qry or the Sort parameter is changed. (The Descending parameter was added in PxPlus 2019.)
Records | (Query Type - Available when a Sort column is selected) Enter the number of records to display in the query output. If blank (default), all records will be displayed. 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. #### Note: The Records parameter will reset to the default (blank) if the Qry or the Sort parameter is changed. (The Records parameter was added in PxPlus 2019.)
Chart | (Chart Type) Chart name.
Width | (Chart Type) Width of the chart (in pixels). Defaults to fit widget.
Height | (Chart Type) Height of the chart (in pixels). Defaults to fit widget.
Rpt | (Report Type) Pathname for the report file.
Dict | (Maintenance and File Access Types) Pathname for the data dictionary file, providex.ddf.
Table | (Maintenance and File Access Types) Data table name in the data dictionary.
Key_Field | (Maintenance Type) Key field in the data table.
Key | (File Access Type) Enter the key of the record to read or write. This is usually left blank and the Allow Override? check box is set to On to enable each request to specify the data to be written. (The Key parameter was added in PxPlus 2022.)
Data | (File Access Type) Record data to write to the table. This is usually left blank and the Allow Override? check box is set to On to enable each request to specify the data to be written. (The Data parameter was added in PxPlus 2022.)
Security | (Query, Chart, Report, Maintenance and File Access Types) Security classification required for access via OAuth2 authentication. To prevent security being bypassed if this is set, the Force ID in URL option (the Settings menu) is also automatically set and the Allow Override? check box for this field is locked. 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.)
Value | Specify the parameter value by clicking the Browse button (where applicable) to locate the directory/file or by selecting from the drop-down list. Quotes are not required around pathnames. When creating a new record, the Value cells for all the parameters, except Title, are initially locked. As each parameter value is entered in grid row sequence, the following row becomes available for entry. When modifying an existing record, changing a parameter value resets and clears one or more other parameter values. Example: For a Maintenance Service, changing the Table value clears the Key_Field value, while changing the Dict value clears the Table and Key_Field values.
URL Order | Specify the order in which the URL sections of the request will be interpreted: "http://localhost:8080/do/service_name/URL_Order_1/URL_Order_2/URL_Order_3/ ..." Example: Suppose that a file access Web service is being defined with the Function set to Read. The Table parameter may be defined as URL Order 1, a user-defined parameter (e.g. kno) as URL Order 2, and the Key parameter as URL Order 3. This order will be reflected in the URL when it is created: "http://localhost:8080/do/service_name/table/kno/key" See Examples - File Access Web Service. (URL Order was added in PxPlus 2022.)
Allow Override? | When selected, the parameter can be overridden by modifying the URL. For details on modifying the URL, see Adding and Maintaining a Widget. When unchecked (default), the parameter is not overridden, even if a different value is entered in the URL. Example: id=tasks type=pdf Using this example, the Web Service ID is tasks, and the pdf output type overrides the default output type defined for this record only if Allow Override is selected. If Allow Override is not selected, the pdf output type will not override the default output type. An HTML error will display when a widget for this Web service is in the Dashboard or when this Web service is run as a URL on a browser. The HTML error will indicate that this Web Service ID does not allow the override of the specified parameter(s). #### Note: Other parameters can be overridden in the same manner.
Add as an Option in JSON file | Select this check box to add the current Web Service ID to the JSON file. Specify the JSON file in the input control by clicking the Query button or typing the full pathname. When the Web Service ID record is written, the JSON file is updated, and a backup file is created. The new Web service record is added to the "options" section of the JSON file. This information is used to load the Contents drop box for adding and maintaining a Dashboard widget. See Adding and Maintaining a Widget. #### Note: Resetting the Dashboard (see Dashboard Settings) reverts to the settings in the JSON file.
Test | (Available only when the Web service record is written to file) Button used to test the Web service record. If the Web service record has been defined correctly, the output displays on a separate test panel, using the default EZWeb Server settings. When the Test button is selected, EZWeb Server will automatically start (if not already running), using the default port and secure (HTTPS) settings specified in the Launch EZWeb Server window. If no default port has been assigned, a message will prompt you to define it. If you choose to define it, the Launch EZWeb Server window displays for entering a port. If you choose not to define it, you are returned to the Web Service Maintenance window with the current record still displayed. (The ability to enable secure TLS/SSL mode for the EZWeb server was added in PxPlus 2022.) If any of the settings is changed on an existing record, selecting the Test button automatically updates the record prior to displaying the test panel. This ensures that you are testing with the latest changes. #### Note: The Test button is not applicable when running WindX. (The Test button was added in PxPlus 2017.)
Write | Updates the current record. If the Add as an Option in JSON file check box is selected and a JSON file is entered, the JSON file is updated. The previous version of the JSON file is retained with a .bak extension.
Delete | Removes the current record. If this record was previously updated to a JSON file, a warning message displays, and you are asked to confirm the deletion. If the record is deleted, you should also edit the JSON file to remove the record's information. To edit a JSON file, select Configure Dashboard from the Web Deployment menu on the PxPlus Web IDE or from the Web Deployment category on the IDE Main Launcher (Windows). Select the file to edit from the list of JSON files stored in the *web/services/dashboard directory.
Clear | Clears the current record and does not exit the program.
Exit | Cancels any changes to the current record and exits the program.

## Running the Web Service on a Browser

To run the Web service on a browser, the URL must be entered with the following syntax:

> http://..site../services/service.pxp?id=service&type=output

Where:

| service | Service ID assigned to the Web service record.
| output | (Optional) Valid output Type for this Service ID. If Allow Override is selected, this output type overrides the default defined for this record. If Allow Override is not selected, the default output type is not overridden. An HTML error will display, indicating that the particular Web Service ID does not allow the override of specified parameter(s).

For information on how to access restricted PxPlus Web services, see Access OAuth2 Restricted Web Service.

(OAuth2 security was added in PxPlus 2021.)

Example:

The following URL will run the Web service record tasks and output to a CSV file:

> http://..site../services/service.pxp?id=tasks&type=csv

#### Note:
Only parameter values that are valid for the Type of Web service can be entered.
Example:
If the Web service record is a Query, you cannot enter type=png, as this applies only to a Chart.