Interface Mapper

Describes the components of the Interface Mapper and explains the purpose of each.

The Interface Mapper user interface for COBOL Program service interfaces is split into two parts. The left side shows COBOL entry point fields, and the right shows interface fields, reusable fields, and COBOL assignments.

COBOL Entry Point pane: Shows the selected COBOL Entry Point from the selected COBOL program.
Interface Fields pane: In the Interface Fields pane, you define the details of each field you want to include in your service interface. Typically, an interface field corresponds to a COBOL field shown in the COBOL Entry Point pane. Only the interface fields for the current operation show in this pane.
The most straightforward way to create an interface field from a COBOL field is by dragging a COBOL field from the COBOL Entry Point pane and dropping it onto the Interface Fields pane. This creates a mapping between the COBOL field and the new interface field. From the Interface Fields pane, you can further define the details for that field as it is used by the service interface.
Reusable Fields pane: This pane is primarily for convenience. In it, you create fields you want to use across operations. Then, for each operation in which you want to use one of these fields, drag and drop it from the Reusable Fields pane to the Interface Fields pane. The contents of the Reusable Fields pane does not change from operation to operation in a single service interface.
The Type of interface field created is derived from the name of the reusable field. For example, if you create a reusable field named MyReusableField and then drag and drop it into the Interface Fields pane, the value in the Type column for that field is MyResuableField.
COBOL Assignments pane: Shows COBOL assignments you create for the service interface. For example, you can use a COBOL assignment to define the path taken by the application for the current operation by providing a unique parameter value. This enables you to perform a different function from each operation even if all operations use the same entry point. The program takes a different path depending on the value of a parameter. Instead of defining an interface field to map to that parameter, place the value here that makes the program take the required path.

Special considerations for interface fields of JSON (RESTful) service interfaces

Path and Query fields

Interface Fields have three location options: Body, Path, or Query. Body means that the interface field corresponds to the body of the JSON message. Path and Query are for fields which correspond to the request URI used to invoke the operation. For Path fields, you specify the corresponding part of the URI by going to Operation > Properties and selecting the Path/HTTP tab. Query interface fields correspond to the query string at the end of a request URI. A Path or Query interface field must have a primitive data type, though it may have a nonzero Occurs value (which would be expressed in the actual URI as a comma-separated array). Note that a Path or Query interface field need not have a mapping if it is intended to only be used for output filtering, as described below.

At run time, the output response body is filtered by any path- and query-parameter values received in the URI whose parameter names match the name of an output field in the response body. For example, if an operation is defined with a path of /cars/{make} and an output body array of "car" items, and the run-time request URI is .../cars/ford?color=red&doors=4 (where "make", "color" and "doors" are all names of fields defined within "car"), then the response body array would exclude any instances of "car" whose "make", "color", and "doors" values don't match the URI-specified values. If there are two or more body fields with the same name, those fields can be differentiated in the query string by specifying one or more parent fields of the desired field separated with periods (e.g. car.color=red). Partial or incomplete values for filtering can be indicated by using an asterisk character (*) at the beginning and/or end of the value (e.g. color=red* would match both "red" and "reddish"). Case-sensitive filtering can be performed by wrapping the value in single quotes (e.g. color='Red'). Note that if you do not want a Path or Query interface field to act as a filter on the output message, ensure that its name does not match the name of any output Body interface field. Additionally, there are four special built-in query parameters that can provide further control over the contents of the response:

$fields=commaSeparatedListOfOutputFieldNames>: Indicates that the response body is to contain only the specified fields (and their parent fields and any subordinate fields) and exclude all other defined fields of the response.
$limit=maxNumberOfItems: For array paging, specifies the maximum total number of array elements to return in the response.
$offset=startIndex: For array paging, specifies the minimum index of any returned array elements in the response.
$sort=commaSeparatedListOfOutputFieldNames: For array sorting, indicates that any returned array elements in the response are to be sorted by the specified field(s), by default in ascending order. Optionally, placing a plus (+) or minus (-) character before a field name indicates the order is to be ascending or descending, respectively.

Anonymous root field

For service interface operations that send and/or receive a JSON message body, even though the outermost (root) structure, i.e. a JSON object, array, or primitive, is obligatorily nameless in the message, it still must be represented in the operation's interface fields as the top-level Body field (so that it can be given a Type and Occurs). This so-called "anonymous root" interface field will be marked with an asterisk (*) to the right of the Location column and, though it will have a name in the Interface Mapper, that name will not appear in the JSON message. Since there cannot be more than one input top-level Body interface field nor more than one output top-level Body interface field in an operation, all interface fields that appear in the body of a message must be children of the top-level Body field. See picture below showing an example of a message body with an a nonymous-root group field in the Interface Mapper and its corresponding {}-enclosed JSON object in the JSON message.
Anonymous Root

Array fields in JSON

In SOAP (like COBOL), an array is an item defined with a nonzero occurs attribute, and such an item appears in the message repeated multiple times. For example, an interface-field group array named "group1", with occurs 2, would be represented in a SOAP message as follows:

<group1>
  <field1>someValue1</field1>
  <field2>someValue2</field2>
</ group1>
< group1>
  <field1>someValue3</field1>
  <field2>someValue4</field2>
</ group1>

JSON is different in that it provides explicit array syntax such that an array item is not a repeated item but rather a single item that contains repeated values. So, the same interface-field group array from above would look like the following in a JSON message. Note how "group1" is not repeated but rather appears only once and contains the individual array-element values, which appear as repeated {}-enclosed JSON objects.

"group1":
[
  {
   "field1":"someValue1",
   "field2":"someValue2"
  },
  {
   "field1":"someValue3",
   "field2":"someValue4"
  }
]

For "group1" to be included in each repeated array element value in the JSON message (so that it would look more like the SOAP message), an extra interface-field group would be needed as a parent of the "group1" field in the Interface Mapper, and the nonzero occurs put on that extra parent field instead of on "group1". The resulting JSON message would then be as follows:

"extraGroup":
[
  {
    "group1":
    {
      "field1":"someValue1",
      "field2":"someValue2"
    }
  },
  {
    "group1":
    {
      "field1":"someValue3",
      "field2":"someValue4"
    }
  }
]

For all service interfaces in general, a nonzero occurs property indicates that an interface field is an array. However, for JSON service interfaces in particular, when an interface field has specifically occurs 1, it will appear in the JSON message as a single object or primitive, without the JSON array syntax.