Schema Nodes and Attributes

For business object definition, the purpose of the schema is to create a link between the schema and a maintenance object. For business service definition you are specifying the link between the schema and a service (either a general service, search service, or a maintenance object service). For service script definition, you are defining the API for passing information to and from the script. The following documentation is a complete list of the XML nodes and attributes available to you when you construct a schema.
Note: The definition of a schema may include user interface related attributes that represent a separate aspect of the schema for presentation purposes. These attribtutes belong to a separate name space known as UI Hints and as such are not part of the schema's data structure. Refer to Understanding UI Hints for more information.

The Four Element Types

A schema element can be one of four different structure types. Note that there are two classes of element types: the structural nodes group and list, and the data containing nodes of field and raw.

Mnemonic Valid Values Description Examples
type= "field"

The field type is the default type for any element not explicitly labeled as something other than a field. Therefore, you virtually never have to explicitly label an element as a field. Note that a field element, unlike group or list, will contain information in its nodes - rather than other nodes.
"group"

The group element is typically a structural element of the schema only, in which case it has no mapping.

Note that when grouping several elements that are all used to map an XML structure of a CLOB / XML field of a business object driven record, the mapping may be at the group level.

Example where a group is used to create a structure

<schema>
  <input type="group"
    <userId/>
  </input>
  <output type="group">
    <firstName/>
    <lastName/>
  </output>
</schema>

Example where the group includes the mapping:

<parameters type="group" 
mapXML="BO_DATA_AREA" mdField=
"F1_TODOSUMEMAIL_PARM_LBL"/>
  <numberOfDays 
  mdField="F1_NBR_DAYS" 
  required="true"/>
  <frequency 
   mdField="F1_FREQUENCY"/>
"list"

The list node is structural node like the group node. The only difference is that the list structure has the ability to repeat multiple times in an XML document.

Example of a schema with a list:

<schema>
  <statesList type="list">
    <state isPrimeKey="true"/>
    <description/>
  </statesList>
</schema>

Example of a schema with a list:

<xml>
  <statesList>
    <state>AK</state>
    <description>Alaska</description>
  </statesList>
  <statesList>
    <state>AL</state>
    <description>Alabama</description>
  </statesList>
...
</xml>
"raw"

The raw data type is used to capture a chunk of raw text that doesn't have any inherent structure associated with it.

 
<sendDetail type="raw" />

Example of an XML instance for the above schema:

<sendDetail>
  <messageInfo>
    <senderAddress>123 W. Main St,    Ontario, CA
    </senderAddress>
    <corpZone>3A</corpZone>
  </messageInfo>
</sendDetail>

The Data Type of a Field Element

Of the four different element types, only a field can have a data type.

Mnemonic Valid Values Description Examples
dataType= "string"

By default, a field element is a string. Therefore, there is no requirement to specify the string data type.

 
<schema>
  <custName dataType="string"/>
</schema>
"number"

Defines an element that is a number.

Note: UI hints include a setting to Suppress Automatic Number Formatting.
Note: Use currencyRef attribute for auto-display of currency symbol that is associated with the referenced currency code. The currency decimal positions are ignored by this formatting allowing you to display a currency symbol for a unit rate with many decimals.

Examples

<schema>
  <count dataType="number"/>
</schema>
<schema>
  <taxRate dataType="number" 
   currencyRef="currency"/>
</schema>
"money"

Optional additional attributes

currencyRef="element name"

Defines an element that represents a monetary amount.

The currency reference is optional and if left blank the installation currency will be used. Automatic formatting and validation to be applied based on the currency. For example, the currency symbol will be shown when auto-rendering. In addition, the number of decimal places must not exceed the valid number defined for the currency.

Note: Refer to Referencing Other Elements for supported syntax for referring to other elements. 
<schema>
  <currency default="USD" 
    suppress="true"/>
  <balance dataType="money" 
   currencyRef="currency"/>
</schema>
"lookup"

Required additional attribute

lookup="field name"

Defines an element that has valid values defined using a lookup. The lookup field is required.

 
<schema>
  <status dataType="lookup" 
   lookup="STATUS_FLG"/>
</schema>
"lookupBO"

Required additional attribute

lookupBO="bo name"

Defines an element that has valid values defined using an extendable lookup. The extendable lookup's business object is required.

 
<schema>
  <category dataType="lookupBO" 
   lookupBO="CM-BusinessCategory"/>
</schema>
"boolean"

Defines an element that has values of "Y" and "N".

 
<schema>
  <allowsEdit dataType="boolean"/>
</schema>
"date"

Defines an element that represents a date.

 
<schema>
  <startDate dataType="date"/>
</schema>

"dateTime"

Defines an element that represents a date and time.

Note: Refer to Standard Time Considerations for additional configuration available for date / time fields that represent standard time.
 
<schema>
  <startDateTime 
  dataType="dateTime"/>
</schema>
"time"

Defines an element that represents a time.

 
<schema>
  <startTime dataType="time"/>
</schema>
"uri"

Defines an element captures a URI. Elements defined with this type enable the support for URI Allowlist and Substitution as described in Referencing URIs .

 
<schema>
  <exportDirectory dataType="uri"/>
</schema>

Referencing Other Elements

There are several attributes that allow for a reference to another element in the same schema. The supported syntax of the XPath reference is the same in every case. This section provides examples using the default reference attribute (defaultRef).

Reference a sibling element:

<schema>
   <id mapField="ACCT_ID" required="true"/>
   <altId defaultRef="id" required="true"/>
</schema>

Reference an element in a higher group:

<schema>
   <id mapField="ACCT_ID" required="true"/>
   <msgInfo type="group" mapXML="XML_FIELD">
     <altId defaultRef="../id" required="true"/>
   </msgInfo>
</schema>

Reference an element in a lower group:

<schema>
   <id mapField="ACCT_ID" defaultRef="msgInfo/altId" required="true"/>
   <msgInfo type="group" mapXML="XML_FIELD">
     <altId required="true"/>
   </msgInfo>
</schema>

Reference an element in another group:

<schema>
  <acctInfo type="group">
    <id mapField="ACCT_ID" required="true"/>
  </acctInfo>
   <msgInfo type="group" mapXML="XML_FIELD">
     <altId defaultRef="../acctInfo/altId" required="true"/>
   </msgInfo>
</schema>

Standard Time Considerations

Most date / time fields represent "legal" time such that if a time zone changes their clocks for winter and summer time, the date / time field captures the current observed time. However, some date / time fields should always be captured in standard time to avoid confusion / ambiguity. A good example is a date and time related to detailed interval data. Refer to Designing Time Zones for more information.

When defining an element with dataType="dateTime", you may optionally configure stdTime="true" indicating that data captured in the element always represents standard time in the 'base' time zone. The 'base' time zone is specified on the Installation options.

Note: If an element is mapped to a table / field with a Standard Time Type of Physical, then stdTime="true" is implied. Refer to Fields for more information.

Example:

<schema>
  <startTime dataType="Time" stdTime="true"/>
</schema>

If the time zone that represents the date / time field is not the installation time zone, use the optional setting stdTimeRef="XPath to time zone element" on a date / time element to indicate that the element represents standard time and indicates the time zone to use. Refer to Referencing Other Elements for supported syntax for referring to other elements. .

Example:

<schema>
  <alternateTimeZone fkRef="F1-TZONE" suppress="true"/>
  <startDateTime dataType="dateTime" stdTimeRef="alternateTimeZone"/>
</schema>
Note: If an element is mapped to a table / field with a Standard Time Type of Referenced, then stdTime="XPath" is implied. Refer to Fields for more information.
Note: When schema elements are captured in standard time the UI map supports HTML notation to automatically display the data applying a daylight savings time / summer time correction. Refer to the HTML attribute oraType="dateTime; stdTime:true" for more information.

There may be cases where the date / time is captured as standard time in one time zone, but should be displayed using a different time zone. In this case, the attribute displayRef="XPath" may be used in addition to the appropriate attribute that identifies the time zone that the data is capture in. Refer to Referencing Other Elements for supported syntax. 

<schema>
  <displayTimeZone fkRef="F1-TZONE" suppress="true"/>
  <startDateTime dataType="dateTime" stdTime="true" displayRef="displayTimeZone"/>
</schema>

The Mapping Attributes

When constructing your schema, you can choose from one of the following mapping attributes.

Mnemonic Valid Values Description Examples
mapField= "field name"

In the case of a business object, the mapField attribute is used to identify the database column the element is related to. For business service schemas, the mapField= attribute is used to link a schema element with a service element. 

<schema>
  <factId 
   mapField="FACT_ID"/>
</schema>
mapChild= "table name"

The mapChild attribute is used only for business object mapping. It is used in two ways:

  • First, to create a list in the business object that corresponds to a child table of an MO.

  • Second, you can use mapChild to identify the child table a flattened field lives in. For more information on flattening, refer to flattening section below.

 Example of a list within a child table in a BO:
<persons type="list" 
   mapChild="CI_ACCT_PER"
  <personId mapField="PER_ID"/>
</persons>
mapList= "list name"

The mapList attribute is used only for business service mapping. It is used in two ways:

  • First, to create a list in the business service that corresponds to a list in the service.

  • Second, you can use mapList to identify the list that a flattened field lives in. For more information on flattening, refer to flattening section below.

 Example of a list within a business service:
<selectList type="list" 
  mapList="DE" 
  <value mapField="COL_VALUE"> 
    <row mapList="DE_VAL"> 
      <SEQNO is="2"/> 
    </row> 
  </value>  
</selectList>
mapXML= "field name"

The mapXML attribute is typically used to map XML structures into a large character / XML field of the service. Note that when you use mapXML to map either a list or group structure (type="list" or type="group") you don't have to map all the child elements within the structure. It is also possible to map list elements to a large character field associated with the list child.

 
<enrollmentRequest type="group" 
mapXML="CASE_CLOB">
  <messageID/>
  <sender/>
</enrollmentRequest>
<enrollmentKey 
mapXML="CASE_CLOB"/>
<enrollmentInfo type="list" 
mapChild="CI_CASE_CHILD">
  <sequence 
  mapField="CHILD_SEQ"/>
  <name 
  mapXML="CASE_CHILD_CLOB"/>
  <value 
  mapXML="CASE_CHILD_CLOB"/>
</enrollmentInfo>
isPrimeKey= "true"

You must specify a primary key for a list defined within a mapped XML element (type="list" mapXML="CLOB"). The primary key is used by the framework to determine whether a list element add, update or delete is required during a business object update.

Note: You do not need to specify the prime key for a business object list mapped to maintenance object list. When a physical list is mapped, the prime key is derived from existing physical meta-data.
 
<questionnaire 
type="list" mapXML="CASE_CLOB">
  <question 
  isPrimeKey="true"/>
  <answer/>
</questionnaire>
orderBy= "XPath asc|desc, XPath asc|desc"

By default, a list defined within a mapped XML element (type="list" mapXML="CLOB") is sorted by the first element of the list. A different sort order may be specified using the orderBy attribute. The attribute value is a comma separated list of field XPaths (relative to the list element) with an optional sort order (ascending is the default).

Note: This is only available for lists mapped as XML within business objects.
 
<questionnaire type="list" 
  orderBy="page/section, 
page/sequence" 
mapXML="CASE_CLOB">
<question isPrimeKey="true"/>
<answer/>
<page type="group">
  <section/>
  <sequence/>
</page>
</questionnaire>

Descriptive Attributes

The following attributes can be used to describe a schema element and provide additional configuration related to the element. Typically, these attributes are useful for field elements only.

Mnemonic Valid Values Description Examples
<!-- comment -->

Use this to add a comment to a schema by using special open and close characters: <!-- and -->.

 
<schema>
  <!-- This schema is used to 
capture business information 
only, please refer to the 
'HUMAN' BO for person 
information -->
</schema>
description= "text"

The description of an element may be used to provide an internal description of the element to help a reader of the schema to understand the business reason for the element.

 
<schema>
  <active type="boolean" 
description="active account" 
label="Active"/>
</schema>
label= "text"

The label of an element is meant to be a short bit of verbiage that would typically precede the element in a user interface. 

<schema>
  <active type="boolean" 
description="active account" 
label="Active"/>
</schema>
required= "true"

Used to require the existence of an element during object interaction.

Note: For included schemas, the required="true" attribute is not processed on business object and business service schemas when they are included within a service script schema. This is to support the ability of the service script to populate required elements before an embedded business object or business service is invoked from the service script.
 

<schema>
  <logDate mapField="LOG_DT" 
default="%CurrentDate" 
required="true" 
private="true"
</schema>
mdField= "field code"

The meta-data field attribute is used to associate an element with a field's metadata. The field defines data type, as well as its label and help text. If you link an element with a meta-data field, you don't need to specify any of these attributes.

Note: For a business object schema, the mapField attribute is used to derive the data type and label. An mdField attribute may be provided to override these attributes, if needed. If the element is mapped to an XML column, the mdField is needed to provide the appropriate data type and label.
 
<schema>
  <active 
mdField="CM_ACTIVE_SW"/>
</schema>
fkRef= "FK Reference Code"

If the element is a foreign key, defining its FK Reference will enable framework validation of the element during schema interaction and automatically provide descriptions and navigation capability.

 
<schema>
  <person fkRef="PER" 
mapField="CHAR_VAL_FK1">
   <row mapChild="CI_SA_CHAR">
      <CHAR_TYPE_CD is="PER"/>
    </row>
  </person>
</schema>
private= "true"

Marking an element as private will prevent it from being exposed in schema interaction.

Note: A private element requires a default.
 
<schema>
  <type mdField="SA_TYPE_CD" 
default="E1" private="true"/>
</schema>
suppress= "true"

This setting prevents an element from appearing in automatically generated user interfaces.

Note: This attribute can be specified on a group, in which case all elements of the group will be suppressed.
Note: Refer to Defaulting and System Variables for advice related to default values for suppressed elements.
 
<schema>
    <ls mdField="LIFE_SUPPORT_FLG" 
default="N" suppress="true"/<
</schema>
"blank"

This setting means that automatic UI rendering in display mode will hide the element if its value is blank. The element will still be modifiable on the input map whether blank or not.

 
<schema>
  <email mdField="EMAIL" 
suppress="blank"/>
</schema>
"input"

This setting means that automatic UI rendering will suppress the element for input, although it may still be displayed if it is not blank.

Note: Elements marked as suppress="input" will behave as with suppress="blank". If the value is blank, no value will be displayed on either the display or input map. If the element's value is present, then the element will be displayed on both the display and input map.
Note: Refer to Defaulting and System Variables for advice related to default values for suppressed elements.
 
<schema>
  <email mdField="EMAIL" 
suppress="input"/>
</schema>
noAudit= "true"

This setting prevents an element from appearing as a changed element in the business object's audit plug-in spot. If specified on a group or list node it applies to the whole node. You cannot specify it on the schema root node, only on schema elements.

Note: This attribute is only applicable to business object schemas.
 
<schema>
  ...
  <version mapField="VERSION_NBR"
 noAudit="true"/>
  ...
  <workFields type="group"
 noAudit="true"
    <lastProcessedId/>
    <lastProcessedTime/>
  </workFields>
</schema>
storeEmptyNodes= "true"

By default, empty nodes are removed from a business object instance when saved. This setting allows a group or a list element to explicitly keep its empty nodes.

This attribute may be useful in situations where business object data is exchanged with an external system and there is a need to distinguish between an empty value for an element that participates in the synchronization and an element that does not participate and therefore omitted from the message altogether.

Note: This is only available for group and list elements.
 
<schema>
  <message type="group" storeEmptyNodes="true">
  ...
  </message>
</schema>
emitEmptyGroups= "true"

By default, empty nodes are not included in the output of a business object or a business service call. This attribute is set at the top level schema node, allowing empty nodes of all groups and list elements to be included in the output.

This attribute may be useful in the same situations that may require the use of the storeEmptyNodes= attribute.

Note: This is only available for business object and business service schemas.
 
<schema emitEmptyGroups="true">
  <message type="group">
  ...
  </message>
</schema>
emitEmptyElements= "true"

This attribute is similar to the emitEmptyGroups= attribute but may also be specified at the field level. The attribute is applicable to all schema types.

 
<schema>
  <messageNumber type="field" emitEmptyElements="true">
  ...
  </message>
</schema>
adheresToDA= “comma separated list of data area names.”

This attribute is applicable to the schema, group and list nodes. It claims that this sub-schema node is intended to "look like" the schema of one of the listed data areas, for polymorphism reasons in general.

Note: The recommended approach for enforcing the structure of a shared data area is by including it in the schema. This attribute should be limited to use cases where the ability to include the data area is not possible.
 
<schema>
  <messageNumber type="group" adheresToDA="DataAreaName">
  ...
  </message>
</schema>

Schema Constants

There are some product owned schemas where the design warrants a value to be defaulted in the schema, but where the value is implementation specific and therefore cannot be defined by the product. For these situations, the product may use a technique called a schema constant. The design of the schema will include a declared constant. At implementation time, a configuration task will include defining the appropriate value for the constant.

For example, imagine the product delivers an algorithm that will create an outbound message when a certain condition occurs. The outbound message type to use must be configured by the implementation. To use a schema constant to define the outbound message type, the base product will configure the following:

  • An option type lookup value for the lookup F1CN_​OPT_​TYP_​FLG is defined. For example, M202 - Activity Completion Outbound Message Type with a Java Value Name of outmsgCompletion

  • The base schema that is used to create the "complete activity" outbound message references the schema constant using the Java Value Name of the option type's lookup value

    ...
<outboundMessageType mapField="OUTMSG_TYPE_CD" default="%Constant(outmsgCompletion)"/>
...

At implementation time, the administrative users must configure the appropriate outbound message type for "activity completion". Then, navigate to Feature Configuration, choose the Schema Constants feature type, choose the option type Activity Completion Outbound Message Type and enter the newly created outbound message type in the option value.

Schema constants may also be used in the flattening syntax to define the row elements required for flattening.

Defaulting and System Variables

The default attribute can be used to default values into field elements as well as the row elements required for flattening . You can default a field to a constant or to one of several system variables.

When an element is required, the default value is applied at the server level when adding or changing the record where no value is provided for this element.

When an element is optional, a default value may be configured to provide a suggested value to the user when populating the record on the user interface in Add mode. Users should be able to remove the default value for this type of element and the system will not attempt to populate it at save time.

Note:

The standard for our 'list' maintenance is to show an empty row for a new list that a user may or may not choose to populate. As such, UI default values are not shown for list elements.

It is not recommended to configure a default attribute for an optional element that is not editable or visible on the user interface in Add mode (for example an element with suppress="true" or suppress="input" or a list element whose default value is not shown per the previous point). The default for this type of element is still applied but the user doesn't have the ability to reset the value. This may result in inconsistencies as defaulting does not occur for optional fields added by a use case other than the UI interaction.

Mnemonic Valid Values Description Examples
default= "value" Use this attribute to default an element to a specified value. The values that are valid depend on the dataType setting. 
<schema>
  <perType mapField="PER_OR_BUS_FLG" 
default="P" required="true"/>
</schema>
<schema>
  <frequency dataType="number" 
default="1" required="true"/>
</schema>
"%CurrentDate" Used to default the element to the current date. This is only applicable to date elements. 
<schema>
  <logDate mapField="LOG_DT" 
default="%CurrentDate" required="true"/>
</schema>
"%CurrentDateTime" Used to default the element to the current date / time. This is only applicable to date / time elements. 
<schema>
  <logDateTime mapField="LOG_DTTM" 
default="%CurrentDateTime" 
required="true"/>
</schema>
"%StandardDateTime" Used to default the standard date and time. The standard date and time is identical to the current date and time, unless daylight savings time / summer time is in effect for the base time zone. This may be used with the stdTime attribute.
Note: Refer to Standard Time Considerations for more information.
 
<schema>
  <startDateTime mapField="START_DTTM" 
default="%StandardDateTime" 
required="true"/>
</schema>
"%ProcessDate" You can default the process date. The process date differs from the current date because the process date will remain constant throughout the duration of the process being executed. The current date will reflect the actual date of processing. This is similar to the batch business date that is a standard batch parameter. 
<schema>
  <billDate mapField="BILL_DT" 
default="%ProcessDate" 
required="true"/>
</schema>
"%ProcessDateTime" This is similar to "%ProcessDate" but for date / time fields. 
<schema>
  <calcDateTime mapField="CALC_DTTM" 
default="%ProcessDateTime" 
required="true"/>
</schema>
"%CurrentUser" Used to default the element to the current user. 
<schema>
  <logUser mapField="LOG_USER" 
default="%CurrentUser" 
required="true"/>
</schema>
"%CurrentUserTimeZone" Used to default the element to the current user's time zone. If the current user's time zone is not found, the installation time zone is used. 
<schema>
  <timeZone 
default="%CurrentUserTimeZone" 
required="true"/>
</schema>
"%CurrentUserLanguage" Used to default the element to the current user's language. 
<schema>
  <custLanguage mapField="CUST_LANG" 
default="%CurrentUserLanguage" 
required="true"/>
</schema>
"%InstallationCurrency" Used to default the currency from the installation record. 
<schema>
  <currency mapField="CURRENCY_CODE" 
default="%InstallationCurrency" 
required="true"/>
</schema>
"%InstallationCountry" You can default the country from installation record. 
<schema>
  <country mapField="COUNTRY" 
default="%InstallationCountry" 
required="true"/>
</schema>
"%InstallationLanguage" You can default the language from the installation record. 
<schema>
  <language mapField="LANGUAGE" 
default="%InstallationLanguage" 
required="true"/>
</schema>
"%Constant( )" You can default an element value using a schema constant. The following is an example of a schema constant used as a default value, where the Java Value Name of the Lookup Value is 'customerLanguage'.
<language mapField="CUSTOMER_LANG" 
default="%Constant(customerLanguage)" 
required="true"/>
"%Context( )" You can default a value contained in a context variable.
Warning: Context variables must be initialized within a server script before the schema context default can be applied. Refer to Context Variables for more information.
 An example of a context variable used as a default value: 
<source mapField="PER_ID" 
default="%Context(source)" 
required="true"/>
Note: When defining a context variable in scripting, it should be prefixed with $$. When referring to the variable in the %Context( ) syntax, the prefix is not included.
defaultRef= "XPath"

Use this attribute to default the value of one element to the value of another one.

Refer to Referencing Other Elements for supported syntax for referring to other elements.

The Flattening Nodes and Attributes

The term "flattening" is used to describe the act of defining one or more single elements for a schema that are actually part of a list within the maintenance object. Flattening is possible if there are other attributes of the list that can be defined to uniquely describe the element or elements. A common use case for flattening is a characteristic. Rather than defining the characteristics of an object using a collection where the user must choose the characteristic type and then define the value, the characteristics are defined as actual elements with the appropriate label already displayed. This technique enables the designer of the schema and the user interface to display each separate characteristic in the logical place in the user interface rather than all lumped together.

Note: A flattened element represents a unique row in the database. This row is inserted when the flattened values are created. The row is updated when any of the flattened values are changed. The row is deleted when all the flattened values are removed. The behavior of effective dated elements is slightly different - please see Flattening an Effective Dated List.
Note: The flattening feature can also be used to define a list, see Flattened List.

Identifying the List or Child Table

When flattening a child table, the row node is required to identify the list / child table that the element comes from. Within the row node, at least one element must be defined with an is= definition that ensures that the element is a unique row in the database. It may also define elements or fields in the row that are suppressed and are populated using default value configuration.

  • For a business object, the row node defines the child table the flattened field belongs to.

    The syntax is <row mapChild="table name">. This example is for the list of persons for an account in the customer care and billing product. One person may be marked as the "main" person. This illustrates how to define an explicit element for the main person ID to simplify references to that field. It is part of the CI_​ACCT_​PER child table. What makes it unique is that the MAIN_​CUST_​SW is true (and only one row may have that value)

    <custId mapField="PER_ID" mdField="CM-MainCust">
  <row mapChild="CI_ACCT_PER">
    <MAIN_CUST_SW is="true" />
    <ACCT_REL_TYPE_CD default="MAIN" />
  </row>
</custId>
    Note: The above example illustrates that the row node may also define elements within the list that are suppressed and assigned a default value. This syntax is never used to identify a particular row. Note that a default value can either be a literal string, or a system variable.

  • For a business service, the row node identifies the list name the flattened field belongs to.

    The syntax is <row mapList="list name">. This example shows two entries from a list being flattened to a field value and description.

    <selectList type="list" mapList="DE"> 
    <value mapField="COL_VALUE"> 
<row mapList="DE_VAL"> 
          <SEQNO is="2"/> 
</row> 
    </value>  
  <description mapField="COL_VALUE"> 
<row mapList="DE_VAL"> 
        <SEQNO is="3"/> 
</row> 
  </description> 
</selectList>

Uniquely Identifying the Flattened Field or List

The is= syntax within a row or rowFilter element is used to uniquely identify the row.

Mnemonic Valid Values Description Examples
is= "value" Use this attribute to reference a value directly. 
<tdTypeCd 
  mapField="CHAR_VAL_FK1">
  <row 
    mapChild="F1_EXT_LOOKUP_VAL_CHAR">
    <CHAR_TYPE_CD 
   is="CM-TD-TYPE"/>
  </row>
</tdTypeCd>
"%Constant( )" You can configure a flattened element using a schema constant. During a service interaction the value of the schema constant will be used to identify the flattened element in its child row.

An example of a schema constant used in flattening syntax where the Java Value Name of the Lookup field value is 'cmRate'.

<unitRate mapField="CHAR_VAL" 
  dataType="number">
  <row mapChild=
   "F1_EXT_LOOKUP_VAL_CHAR">
    <CHAR_TYPE is
   ="%Constant(cmRate)"/>
  </row>
</unitRate>
"%n" The %n substitution value is used to reference a relative list instance. A relative list instance is typically used to configure a flattened element for a child table keyed by sequence number. The value of n should be a positive integer value. During a business object read interaction the relative list instance (position) specified by the integer will be returned. An example with a relative list instance - where the first instance of the row is returned.
<schema>
  <mainPhone mapField="PHONE">
    <row mapChild="CI_PER_PHONE">
      <PHONE_TYPE_CD 
      is="%Constant(mainPhoneType)"/>
      <SEQ_NUMis="%1"/>
    </row>
  </mainPhone>
</schema>
Fastpath: Additional values for is= are used when Flattening an Effective Dated List. Refer to that section for more information.

Flattening a Pre-defined Characteristic Type

If the flattened field is in a characteristic collection and the characteristic type is a predefined characteristic, automatic UI rendering will generate a dropdown for the list of valid values. For example, the schema below will generate a dropdown for the Usage element showing the valid values of the Status Reason Usage (F1-SRUSG) characteristic type.

<usage mdField="STATUS_RSN_USAGE" mapField="CHAR_VAL">
  <row mapChild="F1_BUS_OBJ_STATUS_RSN_CHAR">
      <CHAR_TYPE_CD is="F1-SRUSG"/>
      <SEQ_NUM is="1"/>
  </row>
</usage>

Defining Multiple Elements from the List

When attempting to include multiple columns from the same list, the system provide shorthand notation for copying the flattening rules defined on another element so that the flattening rules do not need to be repeated. To do this, the row node includes the rowRef attribute and it indicates the other element name that defines the mapping information. The following example illustrates flattening the fields Customer ID and Receives Copy of Bill from the same list of Persons for an Account (where the MAIN_​CUST_​SW is true ).

<custId mapField="PER_ID">
  <row mapChild="CI_ACCT_PER">
      <MAIN_CUST_SW is="true" />
      <ACCT_REL_TYPE_CD default="MAIN" />
  </row>
</custId>
<copyBill mapField="RECEIVE_COPY_SW" rowRef="custId"/>

Note that the above notation also illustrates that the rowRef may be defined directly in the element's attribute definition.

Note: Refer to Referencing Other Elements for supported syntax for referring to other elements.

Flattening Two Layers Deep

If your maintenance object or service has nested lists two layers deep, the system supports flattening an element within a flattened element. This technique also uses the rowRef attribute. The flattening of the second level refers to the flattened element of the first level. The following example illustrates flattening a characteristic into an element called legalContact for the "main" customer. Notice that the legalContact element has two row nodes: one to refer to the flattening information for its parent record and one to define its child table

<custId mapField="PER_ID">
  <row mapChild="CI_ACCT_PER">
    <MAIN_CUST_SW is="true" />
    <ACCT_REL_TYPE_CD default="MAIN" />
  </row>
</custId>
<legalContact mapField="CHAR_VAL_FK1">
  <row rowRef="custId">
    <row mapChild="CI_ACCT_PER_CHAR" >
       <CHAR_TYPE_CD is="LEGAL" />
    </row>
  </row>
</legalContact>

Note that the above notation also illustrates that the rowRef may be defined as an attribute of a row node rather than directly in the element's attribute definition.

Defining a Flattened List

There are times that a list or child table supports multiple values of the same "type" and these should be presented as a list. To continue with the example above, the list of persons for an account may identify one person as the "main" person. This person has been flattened to a single element (with the account relationship type defaulted and suppressed). To maintain the other persons related to an account, you can define a list where each row captures the Person Id and the Account Relationship Type.

Rather than a row node, the flattened list is configured with a rowFilter element. The following schema illustrates the described example. The list node defines the child table. The rowFilter includes the criteria that identify the rows within the table to include. The elements of the list are defined within the list node outside the rowFilter element.

<custId mapField="PER_ID">
  <row mapChild="CI_ACCT_PER">
    <MAIN_CUST_SW is="true" />
    <ACCT_REL_TYPE_CD default="MAIN" />
  </row>
</custId>
<miscPersons type="list" mapChild="CI_ACCT_PER">
  <rowFilter>
    <MAIN_CUST_SW is="false" />
  </rowFilter>
  <relType mapField="ACCT_REL_TYPE_CD"/>
  <personId mapField="PER_ID"/>
</custId>

Note that the system will validate that if a schema contains flattened single elements and flattened lists from the same child table, the criteria that defines what makes them unique must be analogous.

Flattening an Effective Dated List

There are some lists in the application that are effective dated (and still others that have effective date and time). For example, there are some effective dated characteristic collections. In these collections, the design is to capture a single value for a characteristic type that may change over time. It is not meant to support multiple characteristic values in effect at the same time.

There are some maintenance objects that have effective dated characteristics and no sequence based characteristics. For those entities, implementations may want to use the characteristic to define an additional field that doesn't require effective dates.

When considering designing an element for your schema that represents a value in an effective dated collection, consider if the value is one that is used in processes, like calculating a bill, such that it is important to capture changes to the value over time.

  • If it is not important to track the changes to the value, the recommendation is to set the effective date to a fixed value in the schema. (Examples below).
  • If it is important to track the changes to the value, then you need to consider how you want to design the schema.
    • One option is to define a flattened list as described above. Both the value and the effective date are elements in this list. In this use case, you manage the list just like any list. You can add or remove values.
    • Another option is to define a flattened single value in the schema. With this option, when retrieving the record, the latest effective value is returned. In this design, the important question is how is the reference date defined.
Note: Refer to Referencing Other Elements for supported syntax for referring to other elements.

Flattened Elements Where Changes Are Not Tracked

The following is an example of flattening an element in an effective dated collection where the value does not need to be effective dated. The recommendation in this case is to simply hard-code the date in the is= attribute. 

<schema>
  <externalReference mapField="ADHOC_CHAR_VAL" mdField="CM_EXT_REF" dataType="string">
    <row mapChild="CI_SA_CHAR">
      <CHAR_TYPE is="CM_EXT_REF"/>
      <EFFDT is="2000-01-01"/>
    </row>
  </externalReference>
</schema>

Flattened Elements Where Changes Are Effective Dated

If you want the BO schema to flatten an effective dated value that should keep track of changes over time, the flattened value will represent the latest effective entry. In this case, the recommendation is to explicitly define the date or date/time field as an element. Then there is syntax for the is= attribute to indicate that the explicit date field is the date to use for the value.

Mnemonic Valid Values Description Examples
is= "%effectiveDate( )" Use this configuration to indicate that the date to use is the value of another element.
Note: Refer to Referencing Other Elements for supported syntax for referring to other elements. 
<schema>
  <price mapField="CHAR_VAL" 
   dataType="number" required="true">
    <row mapChild="CI_SA_CHAR">
      <CHAR_TYPE is="PRICE"/>
      <EFFDT 
   is="%effectiveDate(priceEdate)" />
    </row>
  </price>
<priceEdate mapField="EFFDT" 
  rowRef="price"/>
</schema>
"%effectiveDateTime( )" Use this configuration to indicate that the date / time to use is the value of another element.
Note: Refer to Referencing Other Elements for supported syntax for referring to other elements. 
<schema>
  <price mapField="CHAR_VAL" 
  dataType="number">
    <row mapChild="RATE_CHAR">
      <CHAR_TYPE is="PRICE"/>
      <EFFDTTM 
  is="%effectiveDateTime(priceEdatetime)"/>
    </row>
  </price>
  <priceEdatetime mapField="EFFDTTM" 
  rowRef="price"/>
</schema>

You should consider if the explicit date or date/time element should be displayed on the user interface when the flattened field is shown or if that should be suppressed. Designers should also consider the user dialogue for updating the value. It may be more intuitive for the flattened field to be display only and to have a separate dialogue for updating the effective dated value.

For this option, the suggestion is that the maintenance page for the object includes a separate zone that shows the history of the effective dated values over time. The latest value may be included in that zone as well.

Note that for backward compatibility, the system also supports the following options. However, they are not recommended. They implicitly defined the reference date as the current date at all times. The options supported adding new effective dated rows when the value changed. But the technique also caused new effective dated rows to appear when other elements of the same schema were updated. The new rows would have the current date or date/time with the same row value because the reference date or date/time is the current date, which is a change. The product does not recommend managing an effective dated characteristic without defining the date or date/time as an explicit element.

Mnemonic Valid Values Description Examples
is= "%effectiveDate"

This configuration is not recommended

 
<schema>
  <price mapField="CHAR_VAL" 
  dataType="number">
    <row 
  mapChild="CI_SA_CHAR">
      <CHAR_TYPE is="PRICE"/>
      <EFFDT
   is="%effectiveDate"/>
    </row>
  </price>
</schema>
"%effectiveDateTime"

This configuration is not recommended

 
<schema>
  <price mapField="CHAR_VAL" 
   dataType="number">
    <row mapChild="RATE_CHAR">
      <CHAR_TYPE is="PRICE"/>
      <EFFDT 
    is="%effectiveDateTime" />
    </row>
  </price>
</schema>

Search Zone

A UI Map schema element can be configured to enable an automatic search dialog when the schema is included within a maintenance UI map.

Note: Please note that an fkRef can be configured with a search zone. If a schema element has an fkRef but no explicit search attributes (as described here) then the fkRef search information will be used in the UI map. In other words, if the schema element already has an fkRef, then these explicit search attributes in the schema are only used to override the fkRef search information.
Note: Refer to the UI Map Attributes and Functions for more information on search zone configuration.

search="search zone"

The search attribute can be used within a UI map schema and is used to automatically generate the oraSearch UI map attribute. The search zone is an explorer zone configured as a search.

<person fkRef="PER" search="C1_PSRCH"/>

searchField="search field:element|'literal';"

The searchField attribute can only be used in conjunction with the search attribute. The searchField attribute is used to build the oraSearchField UI map attribute. The searchField value is used to populate a search zone filter with an initial value when the search zone is launched. The initial value can be a literal also. The searchField value is used to match to the filter mnemonic also named searchField.

Search field: element|'literal'. The search field represents the search zone filter to populate on launch. The element is the map's schema element used to populate the filter. The element is optional, if left blank, it will default to the element that this attribute is specified on. The searchField also takes 'literal' as input value

Note: Multiple filters can be populated within the search zone at launch, but multiple search field pairs must be constructed within the attribute value. The value specified here will be used to directly build the HTML attribute oraSearchField within the UI map where this schema is specified.
Note: Note that the element reference is relative. Refer to Referencing Other Elements for supported syntax for referring to other elements.
<person fkRef="PER" search="C1_PSRCH" searchField="PERSON; PER_TYPE:personType;"/>

searchOut="search field:element;"

The searchOut attribute can only be used in conjunction with the search attribute. The searchOut attribute is used to build the oraSearchOut UI map attribute. The searchOut value is used to capture a selected value from the search zone and move it to a UI map element. The searchOut value specified should match the ELEMENT_​NAME mnemonic within the search result zone parameter.

Search field: element. The search field represents the search zone result brought back to the UI map. The element is the map's schema element to be populated. The element is optional, if left blank, it will default to the element that this attribute is specified on.

Note: Multiple elements can be populated as a result of search zone selection, but multiple search field pairs must be constructed within the attribute value. The value specified here will be used to directly build the HTML attribute oraSearchOut within the UI map where this schema is specified.
Note: Note that the element reference is relative. Refer to Referencing Other Elements for supported syntax for referring to other elements.
<person fkRef="PER" search="C1_PSRCH" searchField="PER_ID" 
searchOut="PER_ID;PRIMARY_PHONE:personPhone;"/>

Extend Security for Service Script

Application service security will be enforced when either a business object or a service script is invoked from a BPA script or a UI map, but not from a service script. If you want security to be enforced when the business object or a service script is invoked from a service script, you must add the following attribute to the service script's schema.

appSecurity="true"

The appSecurity attribute is only available for service script schemas. If specified, any business object or service script directly invoked by the service script will have their application service evaluated for access.

<schema appSecurity="true">
  ...
</schema>

Overriding Action for a Business Service

If you want to invoke a business service with an action other than 'read', you need to specify the action attribute on the primary node business service schema.

pageAction="add, change, delete"

The action attribute is used to override the default action of read on a business service schema. Valid values are:

  • add

  • update (only allowed for maintenance object service)

  • change (not allowed for maintenance object service)

  • delete

  • read (this is the default action if no pageAction specified)

Example:

<schema pageAction="change">
  <parm type="group">
    <ele1/>
    <ele2/>
  </parm>
</schema>

Specifying searchBy for a Search Service

If you want to invoke a search service then you must explicitly specify the searchBy attribute appropriate for the elements mapped in the schema.

searchBy="MAIN"

The value values of the searchBy attribute can be found by viewing the XML schema linked to the business service, use the View XML URL. Typical values are:

  • MAIN

  • ALT

  • ALT2

  • ALT3

  • etc.
<schema searchBy="MAIN">
  <AccountID mapField="ACCT_ID"/>
  <Results type="list">
    <AccountID mapField="ACCT_ID"/>
  </Results>
</schema>

Including Other Schemas

There are no limitations on your ability to include a schema into another schema - all types can be included in all other types. Nested includes are also allowed - and at present there is no limitation on the depth of the nesting.

Including a schema requires two parts:

  1. The include node
  2. The name attribute

The following table highlights the supported include statements.

Mnemonic Description Examples

<includeBO name=" "/>

Including a business object schema into another schema is allowed.

Note that the mapping rules of a business object or business service schema may or may not make sense in the context of the parent schema. Include other schemas at your own risk. However, a very useful aspect of XML processing is that the framework ignores non-pertinent attributes. In other words, it will not hurt to have mapping attributes included into a script schema.

 
<schema>
  <cust type="group">
<includeBO name="C1-Person"/>
</cust>
  <spouse type="group">
<includeBO name="C1-Person"/>
</spouse>
</schema>

<includeBS name=" "/>

Used to include a business service schema.

 
<schema>
<includeBS name="F1-ReadMOLog"/>
</schema>

<includeDA name=" "/>

Used to include a data area schema.

 
<schema>
<includeDA 
   name="F1CommonSchemaFieldData"/>
</schema>

<includeMP name=" "/>

Used to include a UI map schema.

 
<schema>
<includeMP 
   name="F1-DisplayRecordActions"/>
</schema>

<includeSS name=" "/>

Used to include a service script schema.

 
<schema>
<includeSS name="F1-ActShowZn"/>
</schema>

Compatibility Attributes

These attributes were added as part of upgrades from previous versions of the Framework.

fwRel="2"

This attribute has been added to schemas created in Framework 2 as part of a Framework 4 upgrade. New schemas will not need this attribute. It is not advisable to modify this attribute without understanding the following behavior differences as improper changes could result in errors:

Note: Schemas created in Framework 2 with the fwRel="2" attribute will store any XML mapped fields under groups as top-level XML elements in the mapXML field. This means that if two or more fields, in different group structures, were to have the same field name, their storage would conflict with one another resulting in errors. The new behavior, without the fwRel="2" attribute, will preserve the group structure and avoid the conflicts.
<schema fwRel="2"
    ...
</schema>