Action attributes

The following description describes the processing for inbound messages using the Sync operation. The external system must evaluate the action code that is provided with outbound messages and determine the processing that is appropriate for that external application.

Action attributes can apply to the content of the parent object and child objects in an object structure. An action attribute applied to the parent object specifies the overall processing action for parent and child records. Applied to a child object, an action indicates processing that is specific to that record. An attribute provided for a child object is evaluated only when the primary object has an action value of Change. When the action for the primary object is not Change, actions on the child object are ignored.

Business rules take precedence over action attributes. If a business rule prohibits an action that is specified on an inbound XML message, an error occurs. For example, an inbound transaction that attempts to update a closed purchase order generates an error.

If an XML message contains multiple instances of an object structure, each instance of the object structure can specify a different action attribute. In the following example, the COMPANIES record has multiple child COMPCONTACT records, and each instance has its own action attribute.

<MXVENDOR>
  <COMPANIES action="Change">
    <COMPANY>TEST4
      <NAME>test</NAME>
      <ADDRESS1>100 Main Str</ADDRESS1>
      <COMPCONTACT action="Add">
        <NAME>SMITH</NAME>
        <TITLE>MANAGER</TITLE>
      </COMPCONTACT>
      <COMPCONTACT action="Change">
        <NAME>JONES</NAME>
        <TITLE>ENGINEER</TITLE>
      </COMPCONTACT>
    </COMPANY>
  </COMPANIES>
</MXVENDOR>

The action attribute can have the following values which are case-sensitive:

• Add
• Delete
• Change
• Replace
• AddChange
• Null

Default action processing

When an inbound XML messages does not contain an action attribute, the message is processed as follows:

• If the primary record does not exist in the database, the Add action is applied.
• If the primary record exists in the database, the Replace action is applied.

For a message sourced from a flat file or an interface table, you can provide an action code for the primary object only. There is no support for providing action codes for child objects.

Add action

The Add action adds records to the database in the receiving system.

For inbound transactions, an error occurs if the data already exists. If the Add action is set on a parent object, the action extends to child objects and it is not necessary to specify the action at the child object level. Outbound transactions contain an Add action when the insert of an object generates the transaction.

Delete action

The Delete action deletes records from the database in the receiving system.

If the Delete action is set on a parent object, the action extends to child objects and it is not necessary to specify the action at the child object level.

If the Delete action is set on the parent object in an outbound XML message that does not include the child objects, the receiving system is responsible for identifying and deleting child objects.

If the Delete action is set on the parent object in an inbound XML message, the integration framework deletes the related child objects. If the parent object does not exist in the database, no error is reported to the sending system.

Change action

The Change action updates existing records in the database in the receiving system.

A Change action on the primary object in an XML message indicates that the message contains one or more parent or child records that are added, changed, or deleted. The message always contains the parent of any child record to be updated, even if the parent is unchanged.

The Change action on the primary object is the only case where you can supply an action for a child object. When the primary object in an inbound or outbound XML message contains a Change action, each child object in the message can contain one of the following actions.

Replace action

The Replace action updates existing records in the database in the receiving system.

A Replace action on the primary object in an XML message indicates that the message contains a complete set of objects that represents the result of additions, changes, and deletions to the object structure. These objects replace the existing database records and any record that is not referenced in the XML message is deleted.

For outbound processing, the Replace action is always used, not the Change action.

For inbound processing, any existing child record that is not explicitly mentioned in the message is deleted. External systems must also delete any child records that are not included in the XML message.

The Replace action can apply only to the primary object in an XML message. If a child record in an inbound XML message contains a Replace action when the primary object contains a Change action, the message is not processed. If a child level record contains a Replace action when the parent contains any action other than Change, the action on the child record is ignored.

AddChange action

The AddChange action adds or updates existing records in the database in the receiving system. The AddChange action is like the Replace action except that the AddChange action does not apply to child objects.

An AddChange action on the primary object adds the primary record and all the sub-records that are specfied in the message, if the primary record does not exist in the database. If the primary record does exist, it is updated and any child record that is included in the message. Existing child records that are not specified in the inbound message are not deleted.

The AddChange action is useful when an object structure includes elements that do not exist in the external system. For example, an external system can maintain vendor information but contact information is stored only in the database. An inbound message with a vendor record that has an action value of NULL deletes the contact information in the database. If the action is set to AddChange for this transaction, the vendor information is updated and the contact information remains the same.

Comparison of Change, Replace, and AddChange actions

The Change, Replace, and AddChange actions differ in the information that they include in the XML message and the processing that they require of the receiving system.

Action attribute combinations

The following table shows the combinations of action attributes you can include on primary and child records.