USER MANUALS

XML Sources

To create an XML data source to access an XML document, right-click on the Server Explorer and click New > Data source > XML.

The Tool will display the dialog to create the data source.

Creating an XML data source

Creating an XML data source

The following data are requested in this dialog:

  • Name. Name of the new data source.

  • Endpoint access configuration. There are two options to configure the access to the data:

    • Direct. You configure the path to the XML file that contains the data.

    • From OpenAPI 3 document. You configure the connection details to an OpenAPI 3 document where the operations of a service are defined. The base views will be created from them.

  • Ignore route errors. If selected, the Server will ignore the errors occurred when accessing the file(s) to which the data source points.

    This option is not meant to be used when the data source reads a single file. Its main purpose is when the data source points to a collection of files and you know some of them may be missing. For example, you can create a JSON data source to read a set of log files with this local path: /opt/application/logs/log-^DateRange("yyyy/MM/dd",@start_date,@end_date,"yyyy-MM-dd").xml (see more about the function “DateRange” in the section Paths Using Date Ranges).

    When you query a base view created over this data source, the data source will read all the log files in order. For example, if in the query you put the condition start_date='2018/05/01' AND end_date = '2018/05/04', the data source will try to read the files “log_2018-05-01.xml”, “log_2018-05-02.xml”, “log_2018-05-03.xml” and “log_2018-05-04.xml”. If one these files is missing, the query will fail.

    If you want to ignore this error, select the check box Ignore route errors. With this option if one of the files does not exist or cannot be read, the data source will skip it and read the next one. If you run the query from the administration tool, you can identify which files could not be read in the Execution trace. In the trace, click on the nodes with Type = Route. The ones that could not be read will have the attribute Exception followed by an error message.

  • Validation type. If selected, the structure of the input XML file will be obtained from a Schema or a DTD. If “None” is selected, Virtual DataPort will analyze the XML document to infer its schema.

  • Validate route. Path to the Schema (XSD) or DTD of the input XML document. If present, instead of obtaining the XML document from the “Data Route” to calculate the schema of the new base view, the Server will use the contents of the XSD or the DTD.

    The path to the Schema or DTD cannot contain interpolation variables. I.e. this path cannot be parameterized and therefore, you have to provide its path when creating the data source.

    If you select the option Schema and the schema has more than one root element, when you create a base view over this data source, you will have to select the root type of the schema. That is, from which element the schema of the base view will be calculated from (see Creating an XML data source with a Schema that has multiple root elements).

  • Validate data. If selected, Virtual DataPort will validate the input XML file every time the data source is accessed.

The path formats available are described in detail in the section Path Types in Virtual DataPort.

In the Metadata tab, you can:

  • Set the folder where the data source will be stored.

  • Provide a description.

  • Set the infrastructure information where the data is stored. You can set the name of the infrastructure provider (e.g. on-premise, Amazon Web Services, Microsoft Azure, Google Cloud Platform, etc.) and the region name. You can type a custom name if the provider name or region is not on the list.

Click Save to create the data source.

When editing the data source, you can also change its owner by clicking the button image1.

Creating an XML data source with a Schema that has multiple root elements

Creating an XML data source with a Schema that has multiple root elements

Direct

When you use Direct configuration you have to configure the Data route. This is the path to the XML file that contains the data. This path can be parameterized according to the query made using interpolation variables (see section Paths and Other Values with Interpolation Variables). The section Path Types in Virtual DataPort describes the formats of the available paths and how to use parameters in them. The most common path type in this case is HTTP client.

After creating the data source, click Create base view to create a base view over this data source. If the path type selected is HTTP client, the Tool will open the “Configure XML base view” dialog where you can configure a relative route for the base view you want to create.

Configuring XML base view

Configuring XML base view

This dialog shows the following fields:

  • Configuration.

    • HTTP Method. HTTP method that the base view will execute.

    • Base URL. Data source’s URL (for example: http://www.library.com/). This field cannot be modified.

    • Relative URL. Base view’s relative URL (for example: “/books”), this URL will be concatenated to the Base URL when executing the base view (the resulting URL will be http://www.library.com/books).

    • HTTP headers. Base view’s URL headers, they will be applied to the URL when executing the base view.

  • Pagination. Pagination settings for the base view URL.

  • Filters. Filter settings for the base view URL.

This way, a data source that defines a base URL (http://www.library.com/) can be reused to create a base view with its own relative URL for each resource we want to access (“/books”, “/authors”, “/bookById/{id}”, etc).

After configuring the base view route and clicking Ok, the “Configure XML Wrapper” dialog will appear. If the selected path type is other than HTTP client, the “Configure XML Wrapper” dialog will appear immediately after clicking “Create base view” and the previously explained dialog (“Configure XML base view”) will not be displayed.

With the “Configure XML Wrapper” dialog you have to select one of these options (see Creating an XML base view):

  • Do not stream output. With this option, the new base view represents the compound values with the compound types array and register. Then, you can create a Flatten view (see section Creating Flatten Views) over this base view to transform the results in a way that is easy to combine with data from other sources.

  • Stream output at the specified level. With this option, the Server optimizes the processing of the XML document so it does not require the entire response to be realized in memory before processing it. Therefore, the memory consumption is much lower. When the base view is created with the first option (“Do not stream output”), the Server reads the entire XML document and then parses it thus having to store the entire message in memory.

    The drawback of using the “Stream output at the specified level” option over the other one is that with this option, the fields of the XML document “below” the selected level are ignored.

    The section Dealing with Web Service Operations that Return Compound Values explains this issue in detail.

Creating an XML base view

Creating an XML base view

After clicking Ok, the Tool will display the schema of the base view associated with the source. At this stage, you can do the following:

  • Change the name of the view.

  • Change the name of each field by double-clicking it and its type, by using the drop-down list to the right.

  • Set the primary key of the new view (see the section Primary Keys of Views).

  • In the Metadata tab, you can set the folder where the base view will be stored and provide a description.

  • When editing the base view, you can also change its owner by clicking the button image1.

After this, click Save (image4) to create the base view.

In the Server Explorer, double-click the new base view to display its schema (see section Creating Derived Views).

You can edit the schema of the view by clicking Edit.

From OpenAPI 3 Document

This option is to create the base views from an OpenAPI 3 document. You have to configure the route to the document. It can be a Local file or be accessible in a HTTP server (with HTTP basic or digest authentication).

Once the access to the OpenAPI 3 document has been specified, the following parameters can be configured: “Configuration”, “Pagination”, “Proxy”, “Authentication” and “Filters”. The base views that are created on this Open API data source, will use by default the values of this configuration when they are executed.

Creating an Open API data source

Creating an Open API data source

By clicking on the “Load default values from OpenAPI3 Specification” button, the Base URL field of the “Configuration” tab will be automatically filled with the URL specified in the OpenAPI 3 document. This Base URL will be the address to which the endpoints of the OpenAPI specification operations will be concatenated.

For example, if the API server defined in the document is https://www.library.com/ this will be the base URL. Then, if a base view is created for an operation with the “/books” endpoint, when this view is executed the endpoint will be concatenated to the base URL (obtaining the address https://www.library.com/books) and the configuration (authentication, paging, proxy, etc) defined in the data source will be used.

For more information about the Open API data sources you can see OpenAPI 3 Data Sources FAQ.

Add feedback