Using REST API Methods with Excel & Swagger
Using a REST API typically requires programming skills and an understanding of how a REST API works. This document describes a simple way of using REST API methods with Excel to create an administration dashboard for the GBS Workflow Manager.
In this case, the administrator creates an overview of the process instances in the GBS Workflow Manager.
The excel file created here as an example is called "Workflow Manager Administrator Dashboard" and uses the REST API methods with the help of Swagger directly in Excel. The Excel file consists of three tabs working together. The first tab "Dashboard" has an overview which visualizes specific statements based on the pivot tables from the second tab.
The Second Tab
Der zweite Reiter „Pivot Tabellen“, bezieht seine Informationen aus dem dritten Reiter „Daten“. Dieser dritte Reiter ist auch der wichtigste Reiter, da von hier aus auch der REST API-Aufruf gestartet wird. Es werden jedoch bestimmte Daten gefordert, um erfolgreich den REST API-Aufruf durchzuführen. Die benötigten Daten können z.B. die „URL des GBS Workflow Manager Server, Domänenname, Applikations- ID, Formularname & Benutzername“ sein. Dem Bild kann beispielhaft eine mögliche Abbildung des dritten Reiters entnommen werden.
The second tab "Pivot Tables" gets its information from the third tab "Data". This third tab is the most important tab, because the REST API request starts from here. However, certain data is required to complete the REST API request successfully. The required data can be e.g. the "URL of the GBS Workflow Manager Server, domain name, application ID, form name & user name". The image shows an example of a possible mapping of the third tab.
There are two relevant sections in the configuration area, marked with a red and a purple border on the image. Below the configuration area is the data area. It defines which data should be taken and what headline should be used for it. In the picture, this area is outlined in green.
The red border contains the core data so that each REST API request knows which data to use. The password of the user is requested after activating the "Import Data" button and executing the respective function.
The data is then fetched and stored in a table in the data area.
In line 11, the green border contains the parameters that have to be fetched from the application. Pay attention that the parameters should be written correctly, using upper and lower case letters, since they are case-sensitive. The next line is the title and describes how the data is named in the pivot diagrams and tables.
The data from line 11 are only examples and can be adapted according to your own needs. In principle, workflow-specific objects can also be fetched, but these must then be separated with a backslash "\", so that the data can also be interpreted correctly. This may look like this: "bos\subject\value". However, note that the data may vary according to the term "bos\". This depends on how the names of the fields in the GBS Workflow Manager and the submitted form and application were selected. In the example, there is a field called "subject". However, the value of this field is addressed with the name "value", therefore, after the term "bos\", the term "subject\value" must also be added.
In general, other functions can also be entered in this Excel file. However, for this purpose, the corresponding URLs should be retrieved from Swagger and the exemplary structure of existing methods should be taken into account.
If an error "401" occurs when calling the Swagger URL, the "System.properties" file should be checked for incorrect values by the GBS Workflow Manager Server. It is possible that the parameters "security.allowSwaggerUI" and "security.crossSiteRequestForgerySolution" are set to "false". This should then be changed to the value “true”, so that it can work again.
By default, the "System.properties" file is located in the path "wildfly-9.0.1.final\standalone\configuration\GBSWorkflowManager". However, the path may vary from user to user.
Default view: This is how Swagger can look to the user if the configuration has been performed correctly.
Last updated: 07.10.2019