Home
Guides
Sign in

REST-XML Connector Guide

Suggest Edits

Guide layout

The REST XML connector guide includes the following topics:

  • Create a REST-XML asset: a detailed step-by-step tutorial on how to create a REST-XML module and assets.
  • Connector properties: a list of all the connector properties and their explanations.
  • Connector runtime behavior:  a short description of the connector role on runtime.
  • Configure the XML Parser: a detailed explanation on how to enable the XML parser to identify XML entity types.

Create REST-XML module and assets

To create a REST-XML asset, perform the following steps.  

Step 1. Before you start

Before you start creating the rest xml module, make sure that you have at your disposal:

  • XML data source files from which to generate asset metadata files.
  • An optional XML parser configurator YAML file to enable the parser to identify the type of XML entities.

Step 2. Create a REST-XML module

First, create the REST-XML module: 

> ol create module rest-xml-module --connector rest-xml

$ ol create module rest-xml-module --connector rest-xml

Step 3. View the properties of the REST-XML connector

After you created your connector module you can learn what properties you need to populate in order to continue creating the asset. For more information on the  REST-XML connection properties, see Properties below.

  1. Navigate to the module folder

    > cd rest-xml-module

    $ cd rest-xml-module

  2. From under the module directory, display the help menu of the ol add command:

    [module-name]> ol add --help

    [module-name]$ ol add --help

The ol add help menu displays the connector property list:

> ol add --help
Usage: ol add [OPTIONS]

  Add Asset to Module metadata

Options:
  --verbose                              Enables verbose mode
  --verbose-debug                        Enables debug mode
  --verbose-trace                        Enables trace mode
  --additional VALUE                     Additional properties
  --xml-file-path TEXT                   Define path to the input (request) XML file
  --xml-out-file-path TEXT               Define path to the output (response) XML file
  --operation-name TEXT                  Define name for this operation
  --http-method TEXT                     Define an HTTP method to call
  --xml-parser-config TEXT               Define path to the XML Parser configuration .yaml file
  --request-url TEXT                     Define a request URL to call
  --host TEXT                            Define host name (required)
  --http-protocol-version TEXT           HTTP Protocol Version. Available values: HTTP_1_0, HTTP_1_1, HTTP_2. Default value: HTTP_1_1
  --use-alpn TEXT                        Set to 'true' when Application-Layer Protocol Negotiation should be used
  --user TEXT                            Provide username to access the server
  --password TEXT                        Provide password to access the server
  --is-trust-self-signed TEXT            Specify if the HTTP client will trust self signed certificates (default: false)
  --timeout TEXT                         Sets the time in milliseconds before the client will drop the request. Setting zero or a negative value
                                         disables the timeout (default: 30000)
  --headers VALUE                        Provide request headers
  --format TEXT                          [JSON, XML] (default: XML)
  --decimal-separator TEXT               (default: .)
  --client-certificate TEXT
  --client-private-key TEXT
  --generate-null-elements TEXT          (default: false)
  --auth-type TEXT                       [NONE, BASIC, OAUTH2] (default: NONE)
  --header-propagation.enabled TEXT      enables http headers propagation (default: false)
  --header-propagation.headers TEXT      List of headers to propagate
  --truststore.pems TEXT                 Provide list of pems
  --escape-strategy.escape-letters TEXT  List of additional characters to escape when building xml request.
  --oauth2.token-host TEXT
  --oauth2.token-endpoint TEXT
  --oauth2.client-id TEXT
  --oauth2.client-secret TEXT
  --oauth2.body-client-credentials TEXT  (default: false)
  --oauth2.grant-type TEXT               [CLIENT_CREDENTIALS, AUTHORIZATION_CODE, RESOURCE_OWNER_PASSWORD_CREDENTIALS, IMPLICIT] (default:
                                         CLIENT_CREDENTIALS)
  --oauth2.scope TEXT
  --oauth2.additional-headers VALUE
  --oauth2.additional-body VALUE
  --profile TEXT                         Configuration profile
  -h, --help                             Show this message and exit

Step 4. Test the connection to the remote server

Run the ol test connection command with the --host property to verify that the data source is accessible and that the connection properties are correct. 

[module-name]> ol test connection --host https://run.mocky.io/

[module-name]$ ol test connection --host https://run.mocky.io/

Step 5. Add an asset to the REST-XML module

After you have verified the connection parameters, you can create the asset. The ol add command specifies the properties required for activating the business operation of the server and the XML local source files from which to create the asset metadata. To learn more about each property,  see Properties below.

The ol add command adds the asset folder inside the module directory. The folder contains the asset configuration file ([asset-name].json) and the asset testing resources.

[module-name]> ol add --xml-file-path ../xml_ex/call1.in.xml --xml-out-file-path ../xml_ex/call1.out.xml --verbose --xml-parser-config ../xml_ex/ol-fis-xml.yml --operation-name call1 --request-url /v3/215985c7-d586-4ad6-afb6-0853560b1226 --http-method post

[module-name]$ ol add --xml-file-path ../xml_ex/call1.in.xml --xml-out-file-path ../xml_ex/call1.out.xml --verbose --xml-parser-config ../xml_ex/ol-fis-xml.yml --operation-name call1 --request-url /v3/215985c7-d586-4ad6-afb6-0853560b1226 --http-method post

Step 6. Test the REST-XML asset

Test the asset you added to verify that you can request and receive actual business data from the data source.

  1.  From your module folder root go to assets/[asset-name]/test_data/case1/:

    [module-name]> cd assets/[asset-name]/test_data/case1/

    [module-name]$ cd assets/[asset-name]/test_data/case1/

  2. To specify the test input data open in.json:

    case-1> notepad in.json

    case-1$ notepad in.json

in.json contains the information sent to the remote business operation. It consists of the input keys and values that the business operation requires. This is a random example of an in.json file:

{
  "dfhcommarea" : {
    "custId" : "",
    "creditCards" : [ {
      "cardNumber" : "",
      "cardType" : "",
      "cardLimit" : 0,
      "cardUsage" : 0
    }, {
      "cardNumber" : "",
      "cardType" : "",
      "cardLimit" : 0,
      "cardUsage" : 0
    }, {
      "cardNumber" : "",
      "cardType" : "",
      "cardLimit" : 0,
      "cardUsage" : 0
    }]
  }
}

  1. In in.json, type the values of the input properties. In the example above, type the value 412-83254 for the custId key. see 

  2. Now you are ready to run ol test asset:

    [module-name]> > ol test asset call1

    [module-name]$ > ol test asset call1

Properties

--xml-file-path (required)

The local path to the input data source XML file

--xml-file-path (required) ../xml_ex/call1.in.xml

--xml-out-file-path

If the input metadata structure of the input XML is different than its output structure, specify the local location of the output XML.

--xml-out-file-path ../xml_ex/call1.out.xml

--xml-parser-config

The path to the XML Parser configuration YAML file. The YAML file extends the parser capability to process specific XML trees by mapping XML elements to types (e.g., primitives, structures collections, and data types).

--xml-parser-config ../xml_ex/ol-fis-xml.yml

--operation-name

The name of the asset. If --operation-name is not provided, the asset name is identical to the XML source file name.

--operation-name call1

--request-url

The request URL path of the business operation. The complete URL to the server is constructed by the following pattern: host + request-url. --request-url is required when the module includes more than one asset, each having an endpoint of its own, e.g., https://api.host.com/pets and https://api.host.com/users.

--request-url /v3/215985c7-d586-4ad6-afb6-0853560b1226

--http-method

The HTTP method of the operation HTTP request. If --http-method is not provided, the default HTTP method is POST.

--http-method get

--host (required)

The remote data source server address

--host https://run.mocky.io/

--profile

The connection profile of ol add or ol test connection (see: Connection Profiles).

--profile dev

Runtime behavior

The REST-XML connector receives a data request from the data consumer, converts it to XML, and transfers it via an HTTP request to the data source endpoint. The Data Source sends back its data response in an XML format. The connector parses the response and converts it to JSON before sending it to the data consumer. 

Configure the XML Parser

When the REST XML connector parses XML files, it cannot infer from the XML tag whether it represents a collection or a structure. To get this information, the parser refers to a YAML file that maps  XML entities to their type definition.

How to configure the XML parser YAML file

The YAML file maps all XML entities to one of the following categories: type attributes, types, primitives, structures, and collections. 

Type Attributes

The typeAttribute key enables the parser to identify the XML type attribute.

XML

<element type=“int”>42</element>

YAML

typeAttribute: type

Types

The types key enables the parser to identify the Java type of the type denoted by the type attribute. 

XML

<element type=“Int”>42</element>
<element type=“FortyTwo”>forty two</element>

YAML

types:
 Int: java.lang.Integer
 FortyTwo: java.lang.String

Primitives

The primitives key enables the parser to identify which XML entities describe elements with value. In cases where the XML element is not mapped in the YAML file, the parser identifies an element as primitive when it has no nested elements.

XML

<root>
  <one>123</one>
  <two/>
</root>

YAML

primitives:
 - root.one
 - root.two

Structures

The structures key enables the parser to identify which XML entities describe elements with nested elements and no values. If the element is not mapped in the YAML file, the parser identifies an element as a structure if it has nested elements. 

XML

<root>
  <structure1>
    <value1>1</value1>
    <value2>2</value2>
    <value3>2</value3>
  </structure1>
  <structure2/>
</root>

YAML

structures:
 - root.structure1
 - root.structure2

Collections

The collection key enables the parser to identify which XML entities describe collections (arrays, lists, dictionaries). In cases where the element is not mapped in the YAML file, the parser identifies an element as an array when all of its nested elements have the same name. 

XML

<root>
  <array>
    <value>1</value>
  </array>
</root>

YAML

collections:
 - root.array

Full example

XML

<?xml version="1.0" encoding="UTF-8"?>
<EngineDocList>
    <DocVersion DataType="String">1.0</DocVersion>
    <EngineDoc>
        <ContentType DataType="String">OrderFormDoc</ContentType>
        <DocumentId DataType="String">5c14c9b3-1528-3000-0088-0003ba9896f7</DocumentId>
        <Instructions>
            <Pipeline DataType="String">PaymentFA</Pipeline>
        </Instructions>
        <OrderFormDoc>
            <Consumer>
                <PaymentMech>
                    <CreditCard>
                        <Expires DataType="ExpirationDate">01/05</Expires>
                        <Number DataType="String">4111111111111111</Number>
                        <Type DataType="S32">1</Type>
                    </CreditCard>
                    <Type DataType="String">CreditCard</Type>
                </PaymentMech>
            </Consumer>
            <DateTime DataType="DateTime">1544892484336</DateTime>
            <GroupId DataType="String">5c14c9b3-1529-3000-0088-0003ba9896f7</GroupId>
            <Id DataType="String">5c14c9b3-1529-3000-0088-0003ba9896f7</Id>
            <Mode DataType="String">Y</Mode>
            <Transaction>
                <ChargeTypeCode DataType="String">S</ChargeTypeCode>
                <Currency DataType="String">840</Currency>
                <CurrentTotals>
                    <Totals>
                        <Total DataType="Money" Currency="840">1000</Total>
                    </Totals>
                </CurrentTotals>
                <Id DataType="String">5c14c9b3-152a-3000-0088-0003ba9896f7</Id>
                <Type DataType="String">Auth</Type>
                <ZeroAuthToVerify DataType="S32">0</ZeroAuthToVerify>
            </Transaction>
        </OrderFormDoc>
    </EngineDoc>
    <TimeIn DataType="DateTime">1544892484133</TimeIn>
    <TimeOut DataType="DateTime">1544892485272</TimeOut>
</EngineDocList>

YAML

collections:
primitives:
structures:
  - EngineDocList
  - EngineDocList.EngineDoc.Instructions
  - EngineDocList.EngineDoc.OrderFormDoc
  - EngineDocList.EngineDoc.OrderFormDoc.Consumer
  - EngineDocList.EngineDoc.OrderFormDoc.Consumer.PaymentMech
  - EngineDocList.EngineDoc.OrderFormDoc.Consumer.PaymentMech.CreditCard
  - EngineDocList.EngineDoc.OrderFormDoc.Transaction.CurrentTotals
  - EngineDocList.EngineDoc.OrderFormDoc.Transaction.CurrentTotals.Totals
typeAttribute: DataType
types:
  StartDate: java.lang.String
  Money: java.math.BigDecimal
  Numeric: java.math.BigDecimal
  S32: java.lang.Long
  ExpirationDate: java.lang.String
  String: java.lang.String
  DateTime: java.util.Date

Updated 4 months ago