Web Service Schema Nodes and Attributes

A REST inbound web service (IWS) operation invokes a single schema based object, either a Business Object, a Business Service or a Service Script. The object has one schema which by default acts as both the Request and the Response schema. The product provides the ability to define an explicit schema for a web service operation that represents a view of the underlying internal schema for an external facing consumer. Note that the operation schema is a strict view of the internal schema and as such does not introduce structural changes.

While optional, defining an operation schema has the following benefits:

  • Declaring the usage of an element as to whether it is part of the Request schema, Response schema, both or neither. 

  • Assigning an external element name to an internal element.  Useful to avoid cloning of internal services for this purpose only.

  • Better management and visibility of GET operation references.

  • Support HATEOAS style structures outside of the internal schema. This allows for seamless internal processing.

  • Providing help text for individual elements.

The following documentation is a complete list of the attributes available to you when constructing an IWS operation schema.

Operation Schema Definition

The following attributes defines the external facing operation schema that establishes the request and response schema for the operation.

Mnemonic Valid Values Description Examples
usage= "REQ"

Indicates that the element should be included in the request schema only.

When specified for a group or list element the value applies to the entire container. A specific element in the container may override the container default.

 
<customerName usage="REQ" />
"RESP"

Indicates that the element should be included in the response schema only.

When specified for a group or list element the value applies to the entire container. A specific element in the container may override the container default.

 
<customerId usage="RESP" />
"BOTH"

Indicates that the element should be included in both request and response schema definitions. This is the default value

When specified for a group or list element the value applies to the entire container. A specific element in the container may override the container default.

 
<customerName usage="BOTH" />
"EXCL"

Indicates that the element should not be included in either the request or the response schema definitions.

When specified for a group or list element the value applies to the entire container. A specific element in the container may override the container default.

 
<httpMethod usage="EXCL" />
mapTo= "internal element name"

Maps a web service element to an internal element. By default the internal element name is assumed to be the same as the web service element name. Use this attribute to assign an external facing element name in the operation schema and map it to a corresponding internal element.

Note that this is not an XPath expression but rather a reference to a valid element name that corresponds to the structure of the expanded internal schema.

The owner of the element must be the same as the owner of the web service schema. If an operation’s underlying schema was extended (using dynamic data area extension) then the extending owner may only reference their elements on their web service schema extension for the operation.

Internal schema element:

<toDoPriority .../>

Operation schema element:

<priority mapTo="toDoPriority"/>
role= "FKGP"

Establishes a group structure that represents a foreign key to an entity.

The element itself does not exist in the internal schema. It groups together the foreign key value element(s) along with a corresponding _​link element that at run time provides the endpoint URL of that entity’s GET operation. Consumers of the web service may use the link to get the data for the entity.

Internal schema element:

<user .../>

Operation schema group:

<user role="FKGP">
   <user>
   <_link getOperation="mo:'USER';pk1:user;"/>
</user>
"COLL"

Establishes a group structure that represents a collection of entities that corresponds to an internal service list.

The element itself does not exist in the internal schema. It groups together the internal list mapped to a _​data element along with a corresponding _​link element that at run time provides the endpoint URL for the collection's GET operation. Consumers of the web service may use the link to get a more detailed set of information for each entity in the list.

By default all the elements in the referenced list are included in the operation schema. You may explicitly reference and define attributes for specific elements as needed.

Internal schema element:

<alerts type="list">
     <alert/>
     <startDate />
     <endDate />
     <version />
   </_data> </alerts>

Operation schema group:

<alerts role="COLL">
   <_link getOperation="... "/>
   <_data mapTo="alerts">
        <version usage="EXCL"/>
   </_data>
</alerts>
getOperation=

“expression”

Expression components:

  • mo:’<maintenance object>’;

  • pk1:<relative xpath to an element in the internal schema>;

  • pk2:...;

  • pk3:...;

  • pk4:...;

  • pk5:...;

Parameters pk2–5 are required to match the maintenance object’s prime key definition.

Only valid on _​self and _​link elements. The attribute is used to reference the default GET operation for an entity as defined by its maintenance object or business object.

The application determines the GET operation to use as follows:

  • If the entity’s business object references an operation using the GET Operation option then it is used.

  • If the entity’s maintenance object references an operation using the GET Operation option then it is used.

  • If a GET operation is found that references the maintenance object then it is used.

If a GET operation cannot be determined for the entity a standard text indicating that a link is not available is returned instead.
 
<_link getOperation="mo:'TO DO ENTRY';pk1:toDoEntryId;"/>

“expression”

Expression components:

  • iws:’<inbound web service name>’;

  • operation:’<operation name>’;

  • parms:[<external reference as defined on the GET operation record>:<relative xpath of an element name in the internal schema that holds the value>; <another external reference name>:<another relative xpath>;...];

Only valid on _​self and _​link elements. The attribute is used to reference a specific GET operation along with the information needed to compose its path parameters.

 
<_self getOperation="iws:'F1-ToDoEntry'; operation:'getToDoEntry'; parms:[toDoEntryId:toDoEntryId;]"/>

Specialized Elements

The operation schema definition makes use of specialized element names in the style of the Hypermedia as the Engine of Application State (HATEOAS) standard. These elements should only be defined by the operation schema as they are not relevant to nor should be managed by the internal operation service.

The following list describes each element and how it is used.

Element Name Description Examples
<_​self .../>

Response payloads may include a "_​self" element that contains the endpoint URL of the GET operation related to the entity returned in the response.

This is an optional element and only one may exist in an operation schema.

Refer to getOperation= schema definition attributes for more information.

 
<_self getOperation="mo:'TO DO ENTRY';pk1:toDoEntryId;"/>
<_​link .../>

Response payloads may include foreign keys and for those entities, the response includes a "_​link" element that contains the endpoint URL of the GET operation for that entity (if it exists).

Refer to role= and getOperation= schema definition attribute for more information.

 
<_link getOperation="mo:'TO DO ENTRY';pk1:toDoEntryId;"/>
<_​data .../>

Provides a standard reference to a list of entities in the internal schema.

Refer to role=”COLL” schema definition attribute for more information.

 
<alerts role="COLL">
   <_link getOperation="... "/>
   <_data mapTo="alerts">
   </_data>
</alerts>

Documentation Attributes

The following attributes provide additional documentation for individual elements that is included as part of the web service’s Open API specification.

Mnemonic Valid Values Description Examples
helpText= “help text field name”

Associates an element with a specific help text record defined for the Inbound Web Service. If the element is included in both request and response schema the same help text is used in both.

If this attribute is not specified, and a single Help Text Field record exists for the Field associated with the internal element, that help text record is used. If more than one such Help Text Field record exists the one where the help text name is the same as the Field name is used.

Note that an internal element is associated with a Field name via the mdField= attributes, if any, else via the mapField= attribute.

No valid for _​self and _​link elements.

 
<toDoEntryId usage="BOTH" helpText="TD_ENTRY"/>

In this example the inbound web service defines a help text field name “TD_​ENTRY” that provides help text for this element. The same help text is included for the element in both request and response schema.
helpTextResponse= “help text field name”

Associates an element that is included in both request and response schema with a specific help text record to be used in the context of the response schema.

Follows same rules as the helpText= attribute.

 
<toDoEntryId usage="BOTH" helpText="TD_ENTRY" helpTextResponse="TD_ENTRY_RESP"/>
In this example the inbound web service defines the following help text records:

  • Help text field name “TD_​ENTRY” describes the element sent in the request schema.

  • Help text field name “TD_​ENTRY_​RESP” describes the element populated in the response schema.