Web Service Descriptors

Creating web service descriptors

Follow the subsequent steps to create a new web service descriptor.

Step 1 To access the New Descriptor wizard, click the Create icon in the toolbar of the Web Service Descriptors search view.

Step 2 Select the Web Service Type in the drop-down menu.

Select 5250 to create a web service based on a scenario.
Select SQL to create a SQL web service.
Select REST to turn a 5250 web service into a RESTful web service.

Click Next > to continue.

Step 3 Define the descriptor's ID and enter a description. These values are required to create a new descriptor but can be edited later.

Step 4 Define the root context to include in the web service's final URL. The text should be unique to this web service.

Step 5 Select the Category in which to save the descriptor.

The list of categories includes all of the pre-defined categories available.

Reference

For more information about creating and managing descriptor categories , refer to Defining the default web service categories.

Step 6 [For 5252 web service types only] Select the Scenario on which the 5250 web service descriptor will be based.

Step 7 Click Finish.

Result The new web service descriptor is created and is displayed in the Web Service Descriptors search view. The descriptor must be edited before it is ready for production.

Defining 5250 web service descriptors

Follow the subsequent steps to edit 5250 web service descriptors.

All changes made in the Web Service Descriptor editor are saved automatically.

Editing 5250 descriptor details

To edit a descriptor's details, either right-click on it in the Web Service Descriptors search view then select Edit properties, or select the item then click the Edit icon in the toolbar. You can also double-click on the Web Service Descriptor to open its editor.

The descriptor's ID is displayed at the top of the editor.

Web Service ID: The descriptor's unique ID.
Description: A short description of the web service to help you identify what the scenario accomplishes.
Root context: This unique information will be used in the URL for the final web service.
Category: Select a category in which to organize the descriptor. The categories available in the drop-down list are those created in the studio preferences.; Reference
For more information about creating categories, refer to Defining the default web service categories.

The Web Service Descriptors editor has a 5250 emulator that allows you to browse through all of the screens in the scenario. An image of the initial screen of each step in the scenario is displayed.

Use the navigation buttons to browse through each screen.

navigate to the first step in the scenario
navigate to the previous step
navigate to the next step
navigate to last step in the scenario

The metadata for each screen are displayed in the Metadata section on the right.

Defining input and output content

On the left of the Descriptor editor, in the Fields section, you can define the input and output values to use when replaying the scenario.

An input value type describes a field in which content/commands must be entered for the scenario to continue forward. Input data can only be a field ID, represented by '0'.

Example

Consider input fields as variables. The content of the input field is the value of the variable to apply to the field when the web service executes the scenario.

Output fields are fields whose content will be returned by the web service execution. Output data can be a field or a column ID, represented by '1'.

Example

Consider the output data as the result of an operation carried out during the scenario. The output the web service recovers may be the customer ID for a client. The scenario to execute is intended to recover the customer ID using a specific command. The value of the customer ID that is displayed is the output content that the web service is looking for; the result of the execution.

To tag fields/columns as places input/output data, each field/column must be identified via a metadata ID. Metadata must already be assigned to each field/column that is to be used as input/output sources.

Reference

For more information about creating metadata IDs, refer to Metadata.

Follow the subsequent steps to tag fields/columns as input or output data.

Step 1 Use the forward and back buttons to browse to a screen where a field or a column has been defined.

As you click through the screens, the Metadata section on the right displays the declared metadata for each screen so that you can easily see which screens require input.

Step 2 Add the metadata in the Fields section.

Drag each field from the Screen Metadata section and drop it to the Fields section on the left.
You can also [ctrl+click] on several metadata to select them and drag and drop them.
You can also double-click on the metadata to add it.

Metadata can only be used once in a descriptor. When you add metadata into the section, a dialog appears.

Tip

You can define multiple input/output fields at the same time: Ctrl+click] to select multiple fields and drag and drop them together into the Fields list on the left. All the fields can be defined in the dialog.

Step 3 Define the properties for the added metadata in the dialog. If the metadata is a column, a field or a list, the properties to define are different. Refer to the Field properties, Column properties or the List properties below.

Step 4 Click OK to save.

Result The metadata value is defined for the web service as a child of the parent step in the Fields section.

Field properties

Field name: Sets the name of the field as defined in the Metadata editor. This value cannot be modified.
Field Alias: Sets a Field Alias to attribute a unique identifier to the field. This option is useful if there are several input fields with the same name.; Note
In the Web Service Descriptor Execution editor, the Alias Name is used instead of the Field Name in the Input Fields List.
Data Type: Sets the data type of the field as defined in the Metadata editor. This value cannot be modified.
I/O Type: Sets the type of value to create for the field: input or output.
Default Value: For input fields, enter a Default Value to use automatically as the input value if the web service user does not assign a value for the field when replaying the scenario.; You can define an input field value as a reference to another input field value. Enter ${refi:<another_input_field_name>} in the Default Value field where <another_input_field_name> is the name of the field from which you want to use the value.; You can define an external value as a reference to another input field value. Enter ${refp:<properties_name>} in the Default Value field where <property_name> is the name of the property from which you want to use the value.; Note
The reference fields tags ($refi{...}, $refo{...}, $refp{...}) are case-sensitive. Enter them in lowercase.; Note
Field references support text decoration before and after the reference field tag, for exemple: ABC${ref:<input_field_name>}XYZ.
Mapping Table: For output fields, select a Mapping Table in the drop-down list to ensure that the value returned is translated with a specific chosen value. You can assign mapping entry to columns. The mapped value is applied to the output fields of the column.
Required: Tick the Required box to make the input field mandatory. When executing the web services, an error is shown if the required fields are not defined.

Defining success messages

You can define the conditions for what is considered a "functional success" of the execution of a web service. This means that the execution could be technically successful (the scenario has been successfully executed) but the functional execution could have failed.

Example

To identify a functional failure, you can use the content of a message that appears somewhere in a given step's screen.

To be able to use messages on screen as proof of functional success, each message must be identified via a metadata ID. A field ID must already be assigned to each message that is to be used as proof of success.

Reference

For more information about creating metadata IDs, refer to Metadata.

Follow the subsequent steps to tag success messages.

Step 1 Use the Forward and Back buttons to browse to a screen where a functional message has been defined.

Step 2 Drag the field ID for the message from the Screen Metadata section and drop it to the ID field in the Success Message section on the left.

Step 3 In the dialog, enter the Expected Message, word for word, that should appear when the execution is successful. It is important to enter the exact text of the message in order for the system to recognize it as proof of success.

You can reference the value of an input or an output field in the success message, using a variable. Enter ${refi:<field_name>} in the Default Value field where <field_name> is the name of the input or output field from which you want to use the value.

Example

Library ${refi:<input_field_name>} is created.

Result The success message is defined for the whole scenario.

Defining a custom JSON output format for a web service

You can define a custom format template for the returned JSON file. The format editor is in the Output Format tab on the left section of the Descriptor editor. Enter the custom format template of the JSON output in the Output Format definition field.

To validate your template, click on the Validation icon. A dialog is displayed, showing if the output format is valid or invalid.

To display a simulation of the final JSON output result, click the Sample icon. ARCAD API generates fake values and uses the defined template to display them.

Elements of customization

To define a custom Output Format, you have to define a valid JSON template including the following different elements:

Field References
List/Column References
Execution Information References
Static text

The available reference tags are:

Reference tags to use in custom JSON output format
Tag	Description
<field:[name_of_the_field]/>	Use to reference an output field value
<list:[name_of_the_list]\|[display_type]>	Use to reference a list
<col:[name_of_column]/>	Use to reference a column
<instance/>	Use to reference the execution instance ID.
<messagecode/>	Use to reference the error code
<messagelvl1/>	Use to reference the error text level 1
<messagelvl2/>	Use to reference the error text level 2
<result/>	Use to reference the functional execution result
<status/>	Use to reference the execution result

Using a Field Reference Tag

To display a Field value , use the following Field Reference Tag in your template: <field:[name_of_the_field]/>

When generating the JSON output, this tag is replaced by the value of the Output Field

Using a List Reference Tag

To display the values that come from a list, you must first use a List Reference Tag. This tag is used to define where the list is displayed and how the list content is displayed.

This tag is a Container Tag; this means that you also have to define child Column Reference Tags to used it.

To display a List values , use the following List Reference Tag in your template:

Copy

List Reference Tag Syntax

<list:[name_of_the_list]|[display_type]>
    <col:[name_of_col1]/>
    ...
    <col:[name_of_coln]/>
</list>

In this syntax sample,

[name_of_the_list] is the reference name of the list,
[display_type] defines the type of display (ARRAY_OF_OBJECTS or OBJECT_of_ARRAYS),
[name_of_col] is the Reference Name of the column.

There are two types of display for list: ARRAY_OF_OBJECTS or OBJECT_of_ARRAYS.

Example

With the ARRAY_OF_OBJECTS type into the JSON Output Definition as follows:

Copy

Array of objects list type

<list:[name_of_the_list]|ARRAY_OF_OBJECTS>
    <col:[name_of_col1]/>
    ...
    <col:[name_of_coln]/>
</list>

You obtain the following:

The <list:....></list> tag will be replaced by the JSON string: []

The <col:[name_of_col1]/>,..,<col:[name_of_coln]/> tags will be replaced by the JSON string: {col1-value-1,..., coln-value-1},...,{coln-value-1,..., coln-value-m}

Copy

Array of object list type JSON result

[
     {
         col1-value-1
         ...
         coln-value-1
     },
     {
         col1-value-m
         ...
         coln-value-m
     }
 ]

Example

With the OBJECT_OF_ARRAYS type into the JSON Output Definition as follows:

Copy

Objects of arrays list type

<list:[name_of_the_list]|OBJECT_OF_ARRAYS>
    <col:[name_of_col1]/>
    ...
    <col:[name_of_coln]/>
</list>

You obtain the following:

The <list:....></list> tag will be replaced by the JSON string: {}

The <col:[name_of_col1]/> tag will be replaced by the JSON string: [ "col1-value-1", ..., "col1-value-m"]

Copy

Objects of arrays list type JSON result

{
     [
       col1-value-1,
       ...
       col1-value-m,
    ],
     [
       coln-value-1,
       ...
       coln-value-m,
    ]
 }

Important!

The usage of the list's Display Type is not enough to generate a valid custom JSON Output Format. Indeed, it is mandatory to setup the static text correctly to get a valid output.

Example

Valid output format templates that generates valid custom JSON output.

Copy

ARRAY_OF_OBJECTS Type

{

    "MyList" : <list:[name_of_the_list]|OBJECT_OF_ARRAYS>
        "mycol1" : <col:[name_of_col1]/>,
        "mycol2" : <col:[name_of_coln]/>
    </list>

}

Copy

OBJECT_OF_ARRAYS Type

{

    "mylist" : <list:[name_of_the_list]|ARRAY_OF_OBJECTS>
        "mycol1": "<col:[name_of_col1]/>",
        "mycol2": "<col:[name_of_coln]/>"
    </list>

}

Important!

It is recommended to specify the type of value expected for each output in the custom JSON script.

The available values are the following:

Alpha (string)
Boolean
Integer
Float (decimal number)
Date

Example

Copy

{

"Col1":<field:Col1|INTEGER/>,

"Col2":<field:Col2|ALPHA/>,

"Col3":<field:Col3|FLOAT/>,

"Col4":<field:Col4|ALPHA/>

}

Defining SQL web service descriptors

Follow the subsequent steps to edit an SQL web service descriptor's details. All changes made in the Web Service Descriptor editor are saved automatically.

Defining an SQL Select Query

In the middle of the editor, you can write SQL logic to provide values for SQL based web services. The input and output fields are included within the SQL logic.

Note

Define the Input Fields and Output Fields in order to test the execution of the web service.

The SQL query uses an SQL inherited syntax and allows you to define the Input and Output fields.

The syntax is the following one:

Copy

SELECT <output_field_definition1>, <output_field_definition2>, ..., <output_field_definitionN>
FROM <from_clause>
WHERE <where_clause_including_input_field_definitions>

Defining output fields

The Output fields are the fields that are returned into the JSON Content of the Web Service.

To define the output field, use the following syntax:

Copy

${o:<output_fieldname>:<column_name>}

where:

<output_fieldname> is the name used into the JSON Output Result,
<column_name> is the name of the column of the table you want to get the data.

Defining input fields

To define the input field, use the following syntax:

Copy

${i:<input_fieldname>:<datatype_id>}

where:

<input_fieldname> is the name used to define input data,
<datatype_id> identifies the datatype. Use 0 for Integer, 1 for Float, 2 for String.

The output field definitions will appear into the select clause and the input field definition generally appear into the where clause.

Example

Copy

SELECT ${o:CODE:APP_CAPP}, ${o:TEXT:APP_CTXT}
FROM ARCAD_PRD/AARCAPPF1
WHERE APP_CAPP like '${i:APPLICATION_CODE:2}%'

In this query:

The values of the columns APP_CAPP and APP_CTXT will be extracted from the table ARCAD_PRD/AARCAPPF1 and will be respectively returned as a value of the CODE and TEXT of the JSON Result.

The table will be filtered to the content of the APP_CAPP column and will return only the records where the value of the APP_CAPP column starts with a input value defined by the user. The API call must include a input parameter called APPLICATION_CODE.

The SQL execution process

For SQL APIs, the execution process:

Discovers all the output field definitions.
Extracts the related column names.
Replaces the output field definition by their related <column_name>.
Discovers all the input field definitions.
Replace the input field definition by the input value defined by the user.
Execute the SQL Query.
Get the value of all the columns defined into the output field definition.
Generate the JSON Result.

Example

Assign BUI to the input field APPLICATION_CODE.

Discovers all the output field definitions:

${o:CODE:APP_CAPP}

${o:TEXT:APP_CTXT}
Extracts the related column names:

APP_CAPPAPP_CTXT

Replaces the output field definition by there related <column_name>:

Copy

SELECT APP_CAPP, APP_CTXT
FROM ARCAD_PRD/AARCAPPF1
WHERE APP_CAPP like '${i:APPLICATION_CODE:2}%'

Discovers all the input field definitions:

${i:APPLICATION_CODE:2}

Replace the input field definition by the input value defined by the user:

Copy

SELECT APP_CAPP, APP_CTXT
FROM ARCAD_PRD/AARCAPPF1
WHERE APP_CAPP like 'BUI%'

Execute the SQL Query.

Generate the JSON Result:

Copy

    {
        "CODE": "BUILDER ",
        "TEXT": "ARCAD-Builder Demo Application"
    },
    {
        "CODE": "BUILDTEST ",
        "TEXT": "buildtest "
    }

Defining REST web service descriptors

Follow the subsequent steps to edit a REST web service descriptor's details. All changes made in the Web Service Descriptor editor are saved automatically.

To edit a descriptor's details, either right-click on it in the Web Service Descriptors search view then select Edit properties, or select the item then click the Edit icon in the toolbar. You can also double-click on the Web Service Descriptor to open its editor.

The descriptor's ID is displayed at the top of the editor.

Web Service ID: The descriptor's unique ID.
Description: A short description of the web service to help you identify what the scenario accomplishes.
Root context: This unique information will be used in the URL for the final web service.
Category: Select a category in which to organize the descriptor. The categories available in the drop-down list are those created in the studio preferences.; Reference
For more information about creating categories, refer to Defining the default web service categories.

Testing the execution of the web service

This feature allows you to test the execution of the web service. Testing your web services is an important step in creating APIs. You can catch any anomalies, clean up the process and find out what can be improved before it becomes available.

There are two ways of testing the execution of a web service. You can run an execution of the service as a whole, or execute it step by step.

Execute a test of a web service

Follow the subsequent steps to run a test execution of a web service.

Step 1 Right click on web service descriptor in the Web Service Descriptors view and select Execute (test) in the contextual menu to open the Test Execution editor.

Step 2 Select a Target Configuration to define the execution context. This is the machine on which the execution will be run. The list is prepopulated with the list of sessions available.

Important!

Define the correct Login and Password of the target configuration in order to execute a SQL query-based web service.

Step 3 [For REST web service descriptors] Select the rest action to test on the REST Actions drop-down list.

Step 4 Define the Input Fields and Output Fields values that are needed to execute the web service. For SQL web services, the fields are retrieved automatically from the SQL query.

The Web Service URL is displayed with the input and output field once these fields are defined.

Step 5 Click the Execute button.

Result The test execution is launched and when it is finished, the execution results are displayed in the Execution Results section.

Execute a test of a web service step by step

Executing the web service in this way can be very useful to debug step by step. Follow the subsequent steps to run a test execution of a web service step by step.

Step 1 Right click on web service descriptor in the Web Service Descriptors view and select Execute (test) in the contextual menu to open the Test Execution editor.

Step 2 Select a Target Configuration to define the execution context. This is the machine on which the execution will be run. The list is prepopulated with the list of sessions available.

Important!

Define the correct Login and Password of the target configuration in order to execute a SQL query-based web service.

Step 3 [For REST web service descriptors] Select the rest action to test on the REST Actions drop-down list.

Step 4 Define the Input Fields and Output Fields values that are needed to execute the web service. For SQL web services, the fields are retrieved automatically from the SQL query.

The Web Service URL is displayed with the input and output field once these fields are defined.

Step 5 Click the Execute button.

Result The execution starts and then stop after the end of the first step of the scenario is reached.

Step 6 Click the Next icon to execute the next step, and so on until you reach the end of the execution.

Result The test execution is launched and when it is finished, the execution results are displayed in the Execution Results section.

View execution results

Execution Results are in JSON format. They display output and field data, and other information concerning the execution of the web service.

Note

Web services using a Success Message return an Error message in the JSON execution result if the captured value does not match with the one that has been defined as a Success Message value.

Click the Get log button to download a log file. For a step by step execution, they are available once the execution is complete.

For 5250 descriptors, the log file shows the different screens that have been used during the execution of the web service. With this log, any unexpected screens used can be easily identified and the scenario can be modified accordingly.

For all descriptor types, the time consumption during the test execution a web service is stored at the end of the log file. The values given are in milliseconds.

Important!

These values are stored in the log file, do the acces to this file must be possible. The returned content in the JSON file must include the instance ID. So, if you use HTTP headers to return values or if you use a customized JSON output format without including this value, you will not be able to access to the instance ID.

Reference

For more information about HTTP Headers, refer to Defining the use of HTTP headers.

For more information about customized JSON output format, refer to Defining a custom JSON output format for a web service.

The related URL to call the web service is displayed in the Web Service URL field. This URL is updated each time a value changes in the editor (input values or target configuration).

Copy the URL and paste it into a browser. A REST request is executed and the tool replies in a REST format (JSON) containing the expected result. This result can be read by a web application and handled by web developers.

Exporting web service descriptors

Export a descriptor from ARCAD-API to share it and make it available to be imported into a different ARCAD-API production server other than the local one accessible from your current ARCAD-API Studio.

Exporting a descriptor will create a compressed file that contains all of the elements required to run the web service on a production server.

For 5250 web services:

The web service type: 5250,
The web service descriptor's properties (identifier, category code, and category name, etc.),
The scenario's properties,
The metadata used by the descriptor or by one of the involved scenarios,
The steps containing screen content captured during the scenario recording.

For SQL web services:

The web service type: SQL,
The web service descriptor's properties (identifier, category code, and category name, etc.),
The Query information.

For REST web services:

The web service type: REST,
The web service descriptor's properties (identifier, category code, and category name, etc.),
The information about the 5250 linked scenario,
The information about the rest actions and their parameters.

Follow the subsequent steps to export a descriptor to run your web service outside of the ARCAD-API Studio.

Step 1 Right click on a web service descriptor in the list and select Export or select the descriptor and click the Export icon.

Step 2 Browse to select the desired location in which to save the file in the Save As dialog and enter a name for the exported file.

Step 3 Click the Save button to export the package.

Result The exported package can now be imported into an ARCAD-API production server.

Reference

For more information about importing a descriptor into a production server, refer toImporting web service descriptors.

Exporting web service descriptors' Open API specifications

Generate a documentation for the web service descriptor compliant to the Open API specification. You can choose to use the Swagger 2.0 version or the Open API 3.0 version of the standard.

Reference

For more information about Open API standard, refer to:

https://spec.openapis.org/oas/v3.1.0 or https://swagger.io/resources/open-api/

Exporting a descriptor will create a compressed file that contains all of the elements required to describe the web service according to the Open API specification.

Follow the subsequent steps to export a descriptor specification to the open API standard.

Step 1 Right click on a web service descriptor in the list and select Export Specification or select the descriptor and click the Export Specification icon.

Step 2 Define the specification version: select 2.0 to use Swagger 2.0 or 3.0 to use Open API 3.0 in the Open API Version drop-down list.

Step 3 Browse to select the desired location in which to save the file in the Save As dialog and enter a name for the exported file.

Step 4 Click the Save button to export.

Result The Open API web service specification is exported to the JSON format.

Use the following web service URL for displaying the documentation:

http://<server>:<port>/arcapi/export/specification/<specVersion>/<webServiceDescriptorCode>

Promoting descriptors to the production server

Once a web service has been designed and tested, it must be available for the final API consumer. To make it available, you must promote it into production. Promote a descriptor to push it to the internal production server available by default in ARCAD-API.

Every time you promote the same web service descriptor to production, a new version is added to the list. Newer versions of the web service don't override the previous versions.

Follow the subsequent steps to promote a web service descriptor to the production server.

Step 1 Right click on a web service in the list and select Promote or select the descriptor and click the Promote icon.

Step 2 Select the Production Package in which to save the descriptor from the drop-down list. This list is pre-populated with all of the production packages available on the local production server.

Important!

In order to save a web service in a package on the production server, the package must already exist.

Reference

For more information about creating production packages, refer to Production packages.

Step 3 Enter a Version Description to summarize the details of the current version of the descriptor that is being pushed to the production server.

Step 4 Click Finish.

Result The promoted web service can be found in the Registered Web Services view. After promoting your web service you must also create the packaged version before it is available to be consumed.

Reference

For more information about accessing promoted web services, refer to Registered web services

Promoting entire descriptor categories to the production server

Promote entire categories to push them to the internal production server available by default in ARCAD-API. When a category is pushed to production, all of the web service descriptors in the category are pushed at the same time.

Follow the subsequent steps to promote a web service descriptor category to the production server.

Step 1 Right click on category in the list and select Promote category or select the category and click the Promote Category icon.

Step 2 Select the Production Category in which to save the descriptors from the drop-down list. This list is pre-populated with all of the production packages available on the local production server.

Reference

For more information about production categories, refer to Production packages.

Step 3 Enter a Version Description to summarize this delivery.

Step 4 Click Finish.

Result The promoted web services can be found in the Registered Web Services view.

Reference

For more information about accessing promoted web services, refer to Registered web services

Deleting web service descriptors

Warning!

Deleted web service descriptors cannot be acceded or recovered.

To delete a web service descriptor, either right-click on the item in the Web Service Descriptors view and select Delete, or select the item and click the Delete icon in the toolbar. Click OK to confirm or click Cancel to keep the web service descriptor.

Web service descriptors