Topic overview

To export objects to external applications from a customizable cockpit, an application of RPC service type and REST service usage must be developed for each such cockpit application. This article describes how to develop this application and connect it to the corresponding cockpit.

Target group

• Developers

Definition of terms

REST-conform – REST stands for Representational State Transfer. REST-conform means that applications and web services communicate with each other in a simple way. For example, HTTP and the operations defined by it are used for this purpose. The web service is accessible directly via URI and all information is contained in HTTP. This ensures that no application state needs to be stored neither on the client nor on the server.

Web service – a web service supports communication between different applications running on different platforms.  A web service is an application that can be uniquely identified with a Uniform Resource Identifier (URI). Direct interaction takes place via xml-based messages.

Description

A REST-conform web service can be invoked by REST clients, including web browsers.

With this web service, objects queried in a customizable cockpit can also be queried by an external application. The query can be done in two ways:

• either an external application queries the objects directly from the system using a REST-conform URI
• or the objects are stored in a REST-conform file using a background application and this file is stored in the Knowledge Store. An external application can access the file in the Knowledge Store.

Connecting to a customizable cockpit

A REST-confirm web service connects automatically to a corresponding customizable cockpit, if the basic queries match. This allows querying the REST service URI in the cockpit or invoking the background application. For more information, see chapter Connecting REST-conform web service and cockpit.

Basis for REST-conform exports

A REST-conform export is based on querying a customizable cockpit. Unlike the customizable cockpit, detailed queries are not taken into account. Only the objects that match the query characteristics from the main query are exported. For filtering, only the filter fields from the main query are available.

File formats

A REST-conform web service supports the following file formats:

• XLS (MS Excel)
• CSV
• XML
• HTML

The HTML file format can be customized using XSLT conversion. To do this, create an XSLT file and store it in the Knowledge Store as:

• Language- and export-specific XSLT file: kstore://<A>/Documents/CockpitDataSource/html/<S>-<L>.xslt
• Export-specific XSLT file: kstore://<A>/Documents/CockpitDataSource/html/<S>.xslt
• Language-specific and export-irrelevant XSLT file: kstore://<A>/Documents/CockpitDataSource/html/Global-<L>.xslt
• Export-irrelevant XSLT file: kstore://<A>/Documents/CockpitDataSource/html/Global.xslt

Explanation of placeholders:

• <A> – work pane (repository work pane for a query that is not set for OLTP database in a development object or the current OLTP work pane).

• <S> – full name of the query used in the REST-conform web service

• <L> – language symbol (e.g., de for German)

A sample XSLT file can be found in the development object of file type: com.cisag.sys.services.datasource.Html-transform

Invoking REST-conform web service

A REST-conform web service exports objects from a customizable cockpit. It is used by the client software via the HTTP GET protocol and parameterized via the REST service URI. Next to the REST-conform web service to be invoked, the REST service URI also contains the parameters that control the format and scope of the objects to be exported.

The return of the HTTP request contains the query objects from the cockpit in the desired file format, provided that the HTTP code 200 was returned. Otherwise, an error occurs.

Creating REST service URI in a cockpit application

You can create a REST service URI for a REST-conform web service using the Copy hyperlink with search criteria action in the customizable cockpit. The URI contains the search criteria from the customizable cockpit.

REST service URI format

REST service URI is created in line with the scheme below.

• entry with use of OLTP database as a query string: https://<sas>/services/rest/<service>/search.<extension>?<query>
• entry with the use of OLTP database under: https://<sas>/services/<oltp>/rest/<service>/search.<extension>?<query>

Explanation of placeholders:

• <sas> – host and port of the ERP system application server

• <oltp> – name of the OLTP database to access. If access to OLTP database is not required, “none” is specified instead.

• <service> – development object name of the service application

• <extension> – file extension corresponding to the desired output format (e.g., xls for MS Excel, csv, xml, html)

• <query> Query-Strings – to specify an OLTP database in the query string, use oltp=<oltp>. In addition, the following query strings are used for exports from cockpits.

 Query strings

The query strings described in article Interface for programmable web services are available for REST-conform web services.

The data source is parameterized using the following query strings:

Creating REST-conform web services

Web service application

The functional scope of the REST-conform web service depends only on the query applied. Therefore, the development of a REST-conform web service with existing query is very simple.

The following development objects are required:

• Application

Application of RPC service type with a special REST service usage and entered query.

• Java class of web service
• Query (entered in the web service)

The Java class should be named as the application. The service bean class required for a programmed web service is contained in the superclass com.cisag.pgm.services.datasource.DataSourceService as an inner class. The Java class must be implemented as follows:

public class XExport extends DataSourceService {
public XExport() { super();
}
}

Connecting REST-conform web service and cockpit

In order for a customizable cockpit to allow exports using the REST-conform web service and for the Copy hyperlink with search criteria dialog to be available, the same query must be entered in the development object of the cockpit application as in the development object of the RPC service application. The query must not be entered in several RPC service applications. Otherwise, only one REST-conform web service will be available in the cockpit application.

Furthermore, the query entered for an application must use the same development prefix and, if required, derive from the same APP as the application. Note that these preconditions are not verified in the Development objects application.

Search-Hooks

The following hook can be used to affect the behavior of the search function:

com.cisag.pgm.search.SearchHook

It is invoked from both a cockpit and a REST-conform web service. Only one hook implementation can be used per search.

More information can be found in the JavaDoc of this class.

Renderers and formatters

Renderers and formatters are used for output to a file format. A column can only be output if

• a renderer or a formatter exists or
• the column is based on the String data type.

However, only implementations of the TextRenderer and ToolTipRenderer interfaces are used for a renderer.

Note that renderers and formatters are invoked by the REST-conform web service in a non-dialog session. If a column cannot be rendered, an error value is returned instead. In the CSV file format, this is the string #####.

Authorizations

Each REST-conform web service is an application for which authorizations can be assigned in the system. The permission to open an application is required for establishing connection.