Payload Configuration File Syntax

29 Payload Configuration File Syntax

Learn about the payload configuration file syntax for Oracle Communications Billing and Revenue Management (BRM) Enterprise Application Integration (EAI) Manager.

Topics in this document:

About the Payload Configuration File Syntax

This section describes the syntax of the configuration file used to define the business events.

The configuration file has three sections:

"Publisher Definitions" (<PublisherDefs>) lists the publisher and the events to publish. Each event in the list is defined in the event definition section.
"Event Definitions" (<EventDefs>) defines the contents, source, and format of the events to publish. Each sub-element in the event definition is defined in the element definition section.
"Element Definitions" (<ElementDefs>) defines the sub-elements specified in the event definitions.

Figure 29-1 shows the relationship between the elements in the different sections of the configuration file:

Figure 29-1 Sample Payload Configuration File

Description of "Figure 29-1 Sample Payload Configuration File"

Publisher Definitions

You specify each business event that needs to be published, such as customer account creation, in the <PublisherDefs> section between the <Publisher> tags. The publisher definition is a list of all the business events to publish.

The <PublisherDefs> section defines the publisher to which the events are sent. You can include multiple publishers. You define each publisher as an element with the tag <Publisher>.

The publisher definition includes the following elements:

The mandatory attribute, DB, which specifies the database number of the EAI DM.

Note:

The database number must match the database number in the dm_pointer entry of the CM pin.conf file and the dm_db_no entry of the EAI DM pin.conf file.
An optional attribute, Format, which specifies the format for the published output. Possible values are XML, which is the default, and FLIST.
A list of events to publish. Each event is listed in a separate tag. If an event triggers an identifier to be returned from a third-party application, the tag must include attributes specifying where the identifier will be stored in BRM. These attributes are required only for events that trigger identifiers.

This example includes one event (CustCreate) that triggers an identifier:
```
<PublisherDefs>
<Publisher DB="0.0.9.1" Format="XML">
<CustCreate ObjectPoid="PIN_FLD_POID" IdentifierFld="PIN_FLD_ACCOUNT_NO"/>
<NameInfoUpdate/>
<BillInfoUpdate/>
...
</Publisher>
</PublisherDefs>
```
Note:

In previous versions of EAI Manager, a different syntax was used for event definitions. The events were defined in a comma-separated list, not as tags. This syntax is still supported when no events trigger an identifier. If any of the defined events returns an identifier, all of the events must be defined with tags.

Event Definitions

Each event listed in the publisher definition is defined in the event definition between the <EventDefs> and </EventDefs> tags. The event definition contains a list of events to publish, each of which contains elements and attributes that specify the following information:

Where to get the fields and the data for the event
The sub-elements that make up the event
The start and end event for the business event if multiple events are generated for the business event
How the elements should be presented in the final XML output

Note:

If only one BRM event is generated during a business event, you need to specify only the start event.

The <EventDefs> tag defines a business event. Event definitions must have the following attributes:

Optionally, the event definition can include the following elements and attributes:

This example shows the definition of the customer creation business event in the default configuration file:

<EventDefs>
   <CustCreate Source="/account" 
   Tag="Portal.Infranet.Events.CustCreate"
   StartEvent="/event/notification/account/create" 
   EndEvent="/event/notification/customer/reg_complete" 
   DTD="custcreate.dtd">
   <Attribute Tag="Version" Value="1.0"/>
      <Search SearchFld="PIN_FLD_POID" 
      SearchVal="PIN_FLD_ACCOUNT_OBJ"/>
      <Field PinFld="PIN_FLD_POID" Tag="AccountObj"/>
      <Field PinFld="PIN_FLD_STATUS" Tag="Status"/>
      <Field PinFld="PIN_FLD_STATUS_FLAGS" Tag="StatusFlags"/>
      <SubElement Name="BillInfo" 
      OnEvent="/event/customer/billinfo"/>
      <SubElement Name="PayInfo" 
      OnEvent="/event/notification/customer/reg_complete"/>
      <SubElement Name="NameInfo" 
      OnEvent="/event/customer/nameinfo"/>
      <SubElement Name="DealInfo" 
      OnEvent="/event/billing/deal/purchase"/>
      <SubElement Name="ProductInfo" 
      OnEvent="/event/billing/product/action/purchase"/>
      <SubElement Name="ProductDetail"
      OnEvent="/event/billing/product/action/purchase"/>
      <SubElement Name="Service"
      OnEvent="/event/notification/customer/reg_complete"/>
      <SubElement Name="Profile"/>
   </CustCreate>
</EventDefs>

Element Definitions

Each sub-element in the event definition must be defined as an element in the element definition (<ElementDefs>). An array or substructure (at element level 0) in the BRM event flist or the object flist is defined in the element definition.

Each element definition specifies the following information:

Where to get the data for the element
The BRM field name for the data
How to present the data in the final XML output

The <ElementDefs> tag is used to define elements. The element definition includes the following elements and attributes:

The mandatory attributes, "Source" and "Tag"
The optional attributes, "PinFld" and "UseOnlyElement"

Note:

If the output format for the payload is FLIST, PinField is mandatory.
The elements "Field" and "ExtendedInfo"

This example shows the definition of the sub-element NameInfo in the default configuration file:

<ElementDefs>
   <NameInfo Source="EVENT" PinFld="PIN_FLD_NAMEINFO" 
   DataFrom="PIN_FLD_NAMEINFO" Tag="NameInfo" UseOnlyElement="1" >
      <Field PinFld="PIN_FLD_ELEMENT_ID" Tag="ElementId"/>
      <Field PinFld="PIN_FLD_FIRST_NAME" Tag="FirstName"/>
      <Field PinFld="PIN_FLD_MIDDLE_NAME" Tag="MiddleName"/>
      <Field PinFld="PIN_FLD_LAST_NAME" Tag="LastName"/>
      <Field PinFld="PIN_FLD_ADDRESS" Tag="Address"/>
      <Field PinFld="PIN_FLD_CITY" Tag="City"/>
      <Field PinFld="PIN_FLD_STATE" Tag="State"/>
      <Field PinFld="PIN_FLD_ZIP" Tag="Zip"/>
      <ExtendedInfo PinFld="PIN_FLD_PHONES" Tag="Phones">
          <Field PinFld="PIN_FLD_PHONE" Tag="Phone"/>
          <Field PinFld="PIN_FLD_TYPE" Tag="Type"/>
      </ExtendedInfo>
   </NameInfo>
</ElementDefs>

Syntax of Elements and Attributes

This section describes the attributes and elements you use to define events and elements.

For an example of the relationship between the events, elements, and the flist data, see "Event Flist, Event Definition, and XML Output Example".

Source

Specifies where to get the data for fields specified in the event or element definitions.

Source can be a BRM storable class name or EVENT. If you set the Source attribute to EVENT, the Payload Generator EM reads the fields for the element from the incoming flist of the event. If you specify a storable class name, the Payload Generator EM reads the fields from the BRM database.

If all the data for the fields you need to publish is present in the event flist, specify EVENT for the source. If the event flist has a pointer to data through a POID (Portal object ID), specify Source to be a storable class.

For example:

<!-- Source is a Portal class name-->
PayInfo Source="/payinfo"
  
<!-- Source is the Event flist -->
NameInfo Source="EVENT"

Tag

Specifies the XML tag to be associated with the event, element, or field in the final XML output file.

For example, this entry in the configuration file appears as <FirstName>Name</FirstName> in the XML output:

<Field PinFld="PIN_FLD_FIRST_NAME" Tag="FirstName"/>

StartEvent

Specifies the BRM event that triggers the beginning of the business event. The Payload Generator EM starts caching event data when the event specified in the StartEvent attribute occurs. This element is mandatory in event definitions. If there is only one BRM event generated for the business event, the Payload Generator generates and publishes the business event as soon as it receives the event specified in StartEvent. If more than one BRM event is generated for a business event, the Payload Generator caches all the events starting with this event up to the event specified in EndEvent, and then generates and publishes the business event.

For example:

<-- StartEvent for customer creation business event -->
StartEvent="/event/notification/account/create"

EndEvent

Specifies the BRM event that marks the end of the business event. When the Payload Generator has cached all the events from the event specified in the StartEvent attribute to the event specified in the EndEvent attribute, the Payload Generator generates and sends the payload to the EAI DM.

When this attribute isn't present, the business event begins and ends with the BRM event specified in StartEvent.

For example:

<!-- EndEvent for customer creation business event -->
EndEvent="/event/notification/customer/reg_complete"

DataFrom

Specifies the array or substructure field in an flist from which to retrieve data for the event or the element.

If the source for the element data is specified as EVENT, the array or substructure is read from the incoming flist for the event. If the source for the element data is specified as a storable class, the array or substructure is read from the storable class in the BRM database.

For example:

<!-- Data to be read from PIN_FLD_NAMEINFO array for the NameInfo element -->
  
DataFrom="PIN_FLD_NAMEINFO"

UseOnlyElement

Specifies an element of an array to publish. Use this tag when you want to publish only one of the elements of the array in the flist.

For example, suppose the BillInfo element of a business event is constructed when an /event/customer/billinfo event occurs. To publish only element 1, specify UseOnlyElement="1".

UseElementId

Determines whether element IDs are retained with array fields. If you set UseElementId to 1, element IDs are retained with array elements. If you set UseElementId to 0, array elements are published in sequential order without their original element IDs.

Note:

If the data is published in flist format with UseElementID set to 0, elements are numbered sequentially starting from 0. These numbers do not correspond to the original element IDs. They are included only to ensure that the flist is in a valid format.

For example:

<!-- This tag will cause element IDs to be retained for elements in this array -->
  
<NameInfo Source="EVENT" PinFld="PIN_FLD_NAMEINFO"
DataFrom="PIN_FLD_NAMEINFO" Tag="NameInfo" UseElementId="1" >

Attribute

Adds an attribute to the XML output of the events.

Note:

Attribute is used only in event definitions.

You must specify two entries for the Attribute field:

Tag to specify the name of the attribute to add.
Value to specify the value of the attribute.

For example:

<!-- This Attribute adds the version number to a customer creation business event definition -->
<CustCreate ... Tag="Portal.Infranet.Events.CustCreate"
<Attribute Tag="Version" Value="1.0"/>

The XML output for this business event includes a Version attribute:

<Portal.Infranet.Events.CustCreate Version="1.0">

DTD

Specifies the data type definition (DTD) used for the XML output for this business event.

Note:

You need to specify a DTD only if you publish valid XML documents.

You must use the Name attribute to specify the name of the DTD file.

This example specifies that the custcreate.dtd file be used for the output:

<!-- Specifies the custcreate.dtd as the file to use for the XML output -->
  
<DTD Name="custcreate.dtd">

The XML output for that example includes the DTD file in its DOCTYPE tag:

<!DOCTYPE Portal.Infranet.Events.CustCreate SYSTEM "custcreate.dtd">

PinFld

Specifies the BRM field name.

For element and ExtendedInfo definitions, the data type of the BRM field must be an array or substructure.

Note:

This field is mandatory if you specify FLIST as the output format for the published event.

<--! Specifies that the data for the NameInfo element is from the PIN_FLD_NAMEINFO field of the event flist-->
  
<NameInfo Source="EVENT" PinFld="PIN_FLD_NAMEINFO"

Field

Specifies the BRM field to include in the definition of an event, element, or ExtendedInfo.

You must specify two attributes:

PinFld to specify the name of the field in BRM.
Tag to specify the XML tag to use for the value in the XML file generated for this business event.

This example specifies that the data is retrieved from the PIN_FLD_FIRST_NAME field and assigned to the <FirstName> tag in the XML output:

<Field PinFld="PIN_FLD_FIRST_NAME" Tag="FirstName"/>

The XML output:

<FirstName> Name </FirstName>

ExtendedInfo

Specifies an array or substruct field within an element definition.

For example, if the array that defines the element contains a nested array that you want to include in your element definition, use ExtendedInfo.

You must use the following attributes:

PinFld to specify the BRM field name. The data type must be an array or substruct.
Tag to specify the XML tag used for the value in the XML file generated for this business event.

You can optionally specify the "UseOnlyElement" attribute to read only the element specified from the array.

Search

Specifies the search criteria to read data from a storable class when Source is specified as a storable class.

Note:

You can specify Search only in event and element definitions.

EAI Manager searches the database by creating an SQL query using the attributes specified:

SearchFld specifies the field to search in the database.
SearchVal specifies the value in the input flist to be used in the search arguments.
SearchValFrom specifies that the value for the search needs to be read from an array or substruct element in the input flist.

For example, when this Search field is specified:

<PayInfo Source="/payinfo" PinFld="PIN_FLD_PAYINFO" 
   Tag="PayInfo" >
      <Search SearchFld="PIN_FLD_ACCOUNT_OBJ" 
      SearchVal="PIN_FLD_ACCOUNT_OBJ"/>
...

EAI Manager creates this query:

Select from /payinfo where PIN_FLD_ACCOUNT_OBJ equals the value of the field PIN_FLD_ACCOUNT_OBJ in the event flist.

When this Search field is specified:

<ProductDetail Source="/product" PinFld="PIN_FLD_PRODUCT"
   Tag="ProductDetail">
      <Search SearchFld="PIN_FLD_POID" 
      SearchVal="PIN_FLD_PRODUCT_OBJ" 
      SearchValFrom="PIN_FLD_PRODUCT"/>
....

EAI Manager creates this query:

Select from /product where PIN_FLD_POID equals the value of the field PIN_FLD_PRODUCT_OBJ in the PIN_FLD_PRODUCT array of the event flist.

SubElement

Specifies the element to add to an event in the event definition.

You must specify the Name attribute, which must match the tag of the element in the <ElementDefs> section. If you have an element called NameInfo in the <ElementDefs> tag:

<ElementDefs>
<NameInfo Source="EVENT"...>

the Name attribute in the SubElement must be:

<SubElement Name="NameInfo">

You can optionally include the OnEvent attribute if the Source for the sub-element is "Event". If you specify OnEvent, the data for the sub-element is generated when the event occurs.

If the Source for the data is a storable class, the data is read from the database before the business event is published.

For example, this entry specifies that the data for the NameInfo Sub-element is read when the nameinfo event occurs in BRM:

<SubElement Name="NameInfo"
OnEvent="/event/customer/nameinfo"/>

Event Flist, Event Definition, and XML Output Example

The following figures show the NameInfoUpdate business event definition, how the data in the event flist is used to construct the business event, and the published XML document.

Note:

These examples show only a few of the fields in the event flist and event definition.

Figure 29-2 shows a partial NameInfoUpdate event flist and the NameInfoUpdate definition:

Figure 29-2 NameInfoUpdate Event Flist and Event Definition

Description of "Figure 29-2 NameInfoUpdate Event Flist and Event Definition"

Figure 29-3 shows the published XML output of the NameInfoUpdate event in the previous example:

Figure 29-3 NameInfoUpdate XML Output

Description of "Figure 29-3 NameInfoUpdate XML Output"