Item Actions
Copy
dss_syncAdd
AML
<Item type='Part' id='7073098207234317BBC2CA865413CAD5' action='dss_syncAdd'>
<config_id>7073098207234317BBC2CA865413CAD5</config_id>
<generation>1</generation>
<major_rev>A</major_rev>
<!-- Item properties with sync data-->
<item_number>PA-1586-0</item_number>
<name>Engine</name>
<!-- … the rest of Item props to be synced -->
</Item>
Implementation Details
The main differences between the add action and dss_syncAdd are dss_syncAdd:
- Requires id, generation, and config_id values to be provided for the Item. dss_syncAdd does not generate an ID.
- Skips determination of the initial LifeCycle State.
- Allows the setting of system properties such as created_on, modified_on, etc.
- The default onBeforeAdd/onAfterAdd events are not called. Use the new server events onBeforeSyncAdd/onAfterSyncAddinstead.
Generally, dss_syncAdd directly saves the provided properties to the database.
Table 3 describes the processing of system properties in the dss_syncAdd action.
Table 2: The dss_syncAdd action processing of system properties
| System Property | Required * | Validation in syncAdd | Comments |
| id | Yes** | Is not null. Has valid ID format. | Saved as is. Since synchronization is run per Item generation, it is required that properties id, config_id, and generation are provided from the Source system or at least set inside the onBeforeSyncAdd event handler. If any of these properties are missing, an error occurs and the Item is not saved. |
| config_id | Yes | Is not null. Has valid ID format. If generation is 1, config_id should be the same as id. | |
| generation | Yes | Is not null. Is a positive number. | |
| major_rev | Yes | Is not null. If the ItemType has a Revision List, the property value should match its values; otherwise, it should be empty (to match the current logic of major_rev initialization in such cases) | Saved as is. |
| locked_by_id | No | - | Value provided from Source is ignored. Because the initial DSS implementation only supports read-only data being passed to the Destination system, the locked_by_id property on the synchronized Item is set to null as a result of the synchronization action. |
| is_current | No | - | Value provided from Source is ignored. The value for the property is set by the Destination system: For a non-Versionable ItemType the value is set to 1 (as there can only be one generation per Item). For a Versionable ItemType the is_current property is adjusted on the whole sequence of generations sharing the same config_id. is_current is set to 1 only on the last generation. |
| new_version | No | - | The new_version property is an internal system property required for proper update handling for versionable Items. For the add action, it is closely coupled with the value for the current item lock state and depending on the versioning method, may dictate if a new Item version should be created to save changes to the Item. For dss_syncAdd any passed value for this property from Source is ignored. The value is set on the Destination system. The resulting value in this property after dss_syncAddis calculated in the same way that it is done for the add action with the difference being that dss_syncAdd does not lock the item. |
| classification | No | If provided, should match class structure declared on an ItemType | Saved as is. |
| current_state | No | If value is not null, it should correspond to the ID of the lifecycle state from the Destination system. | If valid, saved as is. If not provided, should be set to null. |
| state | No | - | If current_state is null (and this is valid), state property is also set to null Otherwise, it gets the name of the LC state corresponding to current_stateon the Destination system. |
| is_released | No | - | Saved as is. If not provided, set to False = 0. |
| released_date, effective_date | No | If provided for a released Versionable Item it should not be null and should be in a valid date format | Saved as is. |
| permission_id | No | - | Value provided from Source is ignored. If required, it is possible to add the permission_id property to the Item in the onBeforeSyncAdd event handler on the Destination system. |
| keyed_name | No | - | Otherwise it is calculated in the same way it is done for the add action. Assuming that the Source and Destination systems have the same metadata, the result should be the same. |
| created_by_id, modified_by_id | No | - | Saved as is if not null or empty, otherwise should be initialized using the same logic as the add action. Source values for the obligatory modified_by_id, created_by_id and optional owned_by_id, managed_by_id, team_id may not correspond to the user/team items in the Destination database. It may break permissions calculation for dynamic roles and links in the UI. However, if required, the values from the Source system can be replaced with local Destination values in the onBeforeSyncAdd event handler |
| created_on, modified_on | No | If provided, should be a valid date. | Saved as is if not null or empty. Otherwise, it is initialized using the same logic as the add action. |
| sort_order | No | - | The processing of sort_order is the same as the add action: If passed from Source, sort_order on Relationship Items is written on Destination as is. If it is not provided, the value should be calculated |
- * - Required properties should be provided with an Item, otherwise an error is returned.
- ** - For compatibility with the format of the standard add action, the id property is expected to be provided for an Item as an attribute in the AML request. The <id/> property tag is ignored.
dss_syncUpdate
AML
<Item type="Part" id="7073098207234317BBC2CA865413CAD5" action="dss_syncUpdate">
<!-- Item properties with sync data-->
<item_number>PA-1586-0</item_number>
<name>Main Engine</name>
<!-- … the rest of Item props to be synced -->
</Item>Implementation Details
The main differences from update are that dss_syncUpdate:
- Allows the setting of system properties like modified_on, modified_by_id.
- Does not handle the float behavior of Relationships.
- The default onBeforeUpdate/onAfterUpdate events are not called. Instead, the new server events onBeforeSyncUpdate/onAfterSyncUpdate should be used.
- Does not handle versioning for Versionable Items.
Generally, dss_syncUpdate directly saves the provided properties to the database on the Item generation corresponding to the provided Item ID.
Table 4 describes the processing of system properties in the dss_syncUpdate action.
Table 3: The dss_syncUpdate action processing of system properties
| System Property | Required * | Validation in syncUpdate | Comments |
| config_id itemtype relationship_id is_current source_id | No | - | Are ignored. |
| created_on created_by_id | Yes | Validated that is not null or empty. | If valid, saved as is, otherwise ignored. |
| generation minor_rev | No | - | Saved as is. |
| major_rev | No | If provided, validated that: It is not null. If ItemType has Revision List, then the property value should match its values. Otherwise, it should be empty (to match the current logic of major_rev initialization in such cases) | Saved as is. |
| locked_by_id | No | - | Value provided from Source is ignored. Since the initial DSS implementation only supports read-only data being passed to the Destination system, the locked_by_id property on the synchronized Item is set to null as a result of the synchronization action. |
| is_current | No | - | Value provided from Source is ignored. |
| new_version | No | - | Value provided from Source is ignored. new_version is left unchanged on an Item. |
| classification | No | If provided, should match class structure declared on an Item Type. | Saved as is. |
| current_state | No | If value is provided and it is not null, it should correspond to the ID of the lifecycle state from the Destination System. See more in LifeCycle state processing for a synced Item on Destination | If valid, saved as is. |
| state | No | Since state contains a name of a LCS referenced via the current_state property, the value will be overridden: If current_state is null (and this is valid), state property is also set to null Otherwise, it gets the name of the LC state corresponding to current_state on the Destination system. | |
| is_released | No | - | Saved as is. |
| released_date effective_date | No | If provided for a released Versionable Item it should not null be and should be in a valid date format | Saved as is. |
| permission_id | No | - | Value provided from Source is ignored. If required, it is possible to add the permission_id property to the Item in the onBeforeSyncUpdate event handler on the Destination system. |
| keyed_name | No | - | If the keyed_name is provided and is not null or empty, it is used as is. Otherwise it is calculated in the same way it is done for the update action. Assuming that the Source and Destination systems have the same metadata, the result should be the same. |
| modified_by_id | No | - | Saved as is if not null or empty. Otherwise, it is initialized using the same logic as the update action. |
| modified_on | No | If provided, should be valid date | |
| sort_order | No | - | If passed from Source, sort_order on Relationship Items is written on Destination as is. |
* - Required properties should be provided with an Item, otherwise an error is returned.
dss_syncPurge
AML
<Item type="Part" id="7073098207234317BBC2CA865413CAD5" action="dss_syncPurge" />Implementation Details In Aras Innovator 11.0 SP15 this item action is implemented as a wrapper for the purge action. In future releases, it is planned to introduce custom onBeforeSyncDelete/onAfterSyncDelete events and switch off calls for onBeforeDelete/onAfterDelete which are not marked as required.