OAS Specifications Generation and Import

Content

This page provides an overview of the process of generating applications from OAS conform specifications and importing them into Xyna.

Process Overview

Below you can find an overview of import process of a specification file. The specification must be either a Yaml or JSON file. In the first step the generator reads the specification file and generates one or multiple applications, which are imported into Xyna automatically. Once all applications have been generated and imported into Xyna, several steps must be performed manually to implement business logic and to expose the api.

Step 1 - Import Specification File

The figure below shows the import mask for OAS/TMF specification files. The generation and import process can be started by navigating to the tab "OAS Import" on the left-hand side in the Xyna Factory Manager GUI. To start the import process a specification file muste be passed to the generator. Therefore [WIP]...

After the import process has completed successfully, three applications are available in Xyna.

• The datamodel application contains Xyna datatypes for every object defined in the specifications schema section (see content section of image below):

• The provider application contains the "OAS Filter" instance, the abstract path instance datatype and the response/request datatypes (see content section of image below):

• The client application contains request/response datatypes and workflows for the case Xyna acts as a client (see content section of image below):

Step 2 - Create new workspace for the implementation

The next step is to create a workspace that will be used for your implementation workflows. This is necessary because applications are readonly in Xyna. Inside the "Factory Manager" GUI click on the tab "Workspaces", which can be found on the left hand side (see image below).

Now click on the plus button in the top right corner to create a new workspace (see image below). Give it a descriptive name related to your application. For instance, when implementing the provider application workflows for the example API, this could be "OAS_Example_API_Provider_Impl".

The newly created workspace (OAS_Example_API_Provider_Impl) contains nothing and misses all dependencies except for the "Processing" application. Therfore you have to add the correct dependencies manually. In this case (implementation of provider application) following dependencies have to be added manually:

• Generic_OAS_Backend (optional): This application contains a generic backend implementation that can be used for convenience. Normally this would be substituted with an preexisting backend implementation.
• OAS_Example_API_Provider: This application has been generated by importing the specification file.
• OAS_Order_Entry (optional): This workspace contains a shared trigger instance that can be conveniently used for multiple filter instances for multiple APIs.

The result should look similar:

Step 3 - Derivation of the abstract datatype

The import process generates an abstract datatype which contains the methods your api will expose as abstract services. These methods are defined within your specification file (e.g. GET /resource) and structured via the "tags" keyword. For every tag defined in your specification one abstract datatype is created inside Xyna. This abstract datatype is needed to dispatch incoming requests to the implemented business logic, which was not existent at generation time, at runtime.

1. create a new datatype. Switch to the Process Modeller inside the Xyna GUI. Click on the plus symbol in the top left corner (see image below) to create a new object. Choose "Data Type". Leave the tab open and
2. navigate to the generated abstract datatype and open it. It is located directly under the folder "xmcp/oas".
3. Click on the details symbol [i] on the right hand side of the screen.

4. Copy the fully qualified name, switch back to the opened new datatype (step 1) and paste the fqn into the field Base Type.
5. Fill up the field "Label" using the same label that is used for the abstract datatype and append "Impl". This is not strictly necessary but a good naming convention to keep track of the datatypes.
6. Fill up the field "path": xmcp.oas
7. Hit the first cog symbol in the upper left corner to deploy the datatype

The result should look like:

Step 4 - Implementing the endpoints

The derived datatype from step 3 is still abstract. The abstract services must be overriden by the manual implementation.

1. Click on a path instance method under "Inherited Services" and hit the button "Override". The window should change:

2. Set the "Implementation Type" to "Reference". A Plus symbol should appear:

3. Clicking on the plus symbol "Open new workflow with matching signature" opens a new blank workflow with the correct signature (inputs/outpus) for the manual implementation workflow. Leave the derived datatype open in the background. The implementation workflow schould look like this:

4. Implement the method. An example implementation may look as follows:

The image above shows a simple example implementation that queries a generic ressource storable from the database by its's provider app name and version and maps it to a generated response datatype (GET /resource1 Response 200 OK). This response datatype extends the generic response datatype "GET /resource1 Response".

One important step that must be performed in every implementation workflow is to handle all exceptions except for "Server Exception" and "Exception". Since the imported specification file does not include a proper error response, the signature response datatype is returned instead.

5. When the workflow is finished click on the cog symbol to save and deploy the workflow.

6. Switch back to the derived datatype and click in the field "Reference". Select the workflow you deployed in step (5).

7. Deploy the derived datatype and repeat steps (1) to (6) for every inherited service until all services are overridden.

8. Click deploy to save and deploy the derived datatype.

Step 5 - Deployment of the filter instance

./xynafactory.sh deployfilter -workspaceName 'OAS_Example_API_Provider_Impl' -filterName 'OASFilter' -filterInstanceName 'OAS_Example_Filter' -triggerInstanceName 'OASEntry_4210'