Using Synchronizable Component Interfaces

This chapter provides an overview of synchronizable component interfaces and discusses how to:

• Use the synchronization ID and synchronization datetime stamp.

• Mobilize applications.

• Define synchronizable component interfaces.

• Use reference properties.

• Use attachments.

See Also

Developing the Component Interface

Understanding Synchronizable Component Interfaces

The basis for defining a PeopleSoft mobile page is a synchronizable component interface. You can use existing component interfaces or build new ones. However, for a mobile application to access data through a component interface, the component interface must be synchronizable.

This chapter assumes that you are familiar with developing, validating, and testing component interfaces using PeopleSoft Application Designer.

This section discusses:

• Data synchronization.

• Synchronization conflict resolution.

Data Synchronization

Data synchronization initially copies selected application metadata and instance data from the server to the mobile device while the mobile device is connected to the network. This initial synchronization is also called a bootstrap synchronization. While disconnected, the data might change on the server, on the mobile device, or on another user’s mobile device that subsequently updates the server data through synchronization.

The goals of subsequent synchronization between the server and the mobile device are to:

• Determine whether data has changed on the server, the mobile device, or both the server and the mobile device.

• Determine whether there is a conflict with changed data as determined by comparison with the original property values of the object.

• Determine how to resolve a conflict based on standard conflict-resolution algorithms combined with OnConflict PeopleCode event handlers.

• Update changed data on the server and the mobile device after resolving any conflicts.

Synchronization Conflict Resolution

A mobile device can be attached to the network for update and data synchronization. If data has changed on only the server or only the mobile device, as determined by a three-way comparison of the original server values from the last synchronization, the current server values, and the device values, the synchronization server updates the unchanged value. In this case, no conflict resolution is required. However, if data has changed on both the server and the mobile device, a conflict occurs. The developer assigns a conflict resolution rule to each component interface that determines how to resolve the conflict.

For every property that has changed on the device, the original server value from the last synchronization and the current device value are transmitted to the synchronization server. Conflicts are determined by a three-way comparison of the original server value, the current server value, and the device value. A conflict exists if the property value has changed on both the server and the device, but not to the same value. If the property value is changed on both the server and the device to the same value, there is no conflict. The synchronization server does not attempt to determine which change was made first, because it is not possible to accurately determine the date and time that the update was made on the mobile device. It is considered a conflict that must be resolved.

If the server object has been deleted, it remains deleted, and the mobile device updates to the deleted object are discarded. A notification is sent to the mobile device to notify the user that this has occurred. No error or conflict arises.

Many synchronization conflicts can be handled by selecting from a short list of standard conflict resolution algorithms provided as standard components of the synchronization server. Select the standard resolutions in the Properties dialog box: Synchronization tab of the component interface. PeopleTools also provides PeopleCode events to use to invoke a custom procedure in response to a conflict.

See Using OnConflict.

Note. Applying the conflict resolution algorithms might result in business rule violations. The application developer must provide resolutions that are compatible with the operative business rules. Manage unresolvable conflicts using events.

The following resolution strategies are available:

• Server wins.

  This setting does not cause unresolvable conflicts. The synchronization server assumes that values on the server take precedence, and the mobile device values are discarded. No PeopleCode is run, and no update takes place. Although a conflict is detected, the server values are maintained, and a message is returned to the mobile device alerting the user that the change was not accepted. The server data is sent to the device. The user can reapply changes on the device and upload the changes again.

• Device wins.

  The synchronization server assumes that all values on the mobile device take precedence. Where a conflict is detected between server and device values (because the values have changed on both the server and on the device), field values from the mobile device replace the values on the server. Field values that have changed on the server but do not result in a conflict are updated to the mobile device. No PeopleCode is run.

  Fields that are not exposed through properties, but have changed on the server, are retained. No message is issued to the device.

• Custom resolution.

  No automatic conflict resolution is attempted. The application developer determines conflict resolution using OnConflict PeopleCode events according to the following:

  • For a property conflict, the OnConflict PeopleCode attached to the property is run.

  • If there is a conflict, the OnConflict PeopleCode attached to the level zero object is run after all other OnConflict PeopleCode.

  Use OnConflict PeopleCode to set the ConflictAlgorithm property on the SyncServer object to either device wins or server wins. This causes the device update to be accepted or rejected. All of the OnConflict PeopleCode programs are run before the value of the ConflictAlgorithm property is checked.

If an object is deleted on the server, conflicts are not generated. The device update is accepted (if there were no other conflicts or the conflict resolution rule is device wins). The server data is sent to the device. If an object is deleted on the device and changed on the server, conflicts are not generated.

Property values changed on the device replace property values on the server. Property values changed on the server and not on the device are left equal to the server values. Objects added on the server are left in place. Objects added on the device are added on the server.

The merge algorithm runs when the conflict resolution rule is device wins or custom. When the conflict resolution rule is custom, the merge algorithm runs before the OnConflict PeopleCode is run. While it is possible for the OnConflict PeopleCode to change the outcome of the merge algorithm, it should not do so. The purpose of OnConflict PeopleCode is to decide whether the device update is accepted or rejected.

See Also

SyncServer Class

Understanding Synchronization

Using the Synchronization ID and Datetime Stamp

This section provides an overview of the synchronization ID and datetime stamp and discusses how to:

• Create the SYNCID field.

• Create the SYNCDTTM field.

• Add SYNCID and SYNCDTTM fields to component records.

• Initialize synchronization IDs.

Understanding the Synchronization ID and Datetime Stamp

Every row of data (record) exposed on a component interface to be synchronized must include two fields:

• A synchronization ID, commonly named SYNCID.

• A synchronization datetime stamp, commonly named SYNCDTTM.

If a derived (calculated) value is displayed on the mobile page, its originating records must include SYNCID and SYNCDTTM and must be exposed on the component interface. However, a work (derived) record should not have SYNCID and SYNCDTTM, because the value of the work record changes with changes to its originating data.

Note. PeopleSoft Application Designer allows reference and data collection properties to be marked as derived in the component interface definition. Derived references are not supported; a derived flag on a reference is ignored.

If you include the SYNCID and SYNCDTTM fields in a subrecord, define the fields in both the subrecord and the parent record.

The developer can define the actual names for the synchronization ID and synchronization datetime stamp, but use the names consistently. This document uses SYNCID for the synchronization ID and SYNCDTTM for the synchronization datetime stamp. SYNCDTTM is sometimes named SYNCTIMESTAMP.

The synchronization datetime stamp must be dedicated to the synchronization function. If another datetime stamp (such as LASTUPDTTM) already exists in the selected record, do not use it as the synchronization datetime stamp. Create another specifically for synchronization.

After adding SYNCID and SYNCDTTM, the Build or Alter tables process creates database triggers to:

• Assign a synchronization ID and initial synchronization datetime stamp when new rows are inserted into the table.

• Update the synchronization datetime stamp when rows are modified.

The synchronization datetime stamp cannot be updated by any method other than the database trigger. An insert trigger assigns synchronization IDs, except in the case of existing rows in an altered table. For an existing table, you must initialize the synchronization IDs using the Set Sync ID utility.

For a new table, synchronization IDs are automatically assigned as the table is populated with data, and cannot otherwise be changed or updated.

Synchronization IDs are unique to each table, except for effective-dated tables. In an effective-dated table, all instances of a specific row share the same synchronization ID. If you select only in-effect rows, you get unique synchronization IDs within that table.

Note. Each record being mobilized must include at least one key field (not SYNCID or SYNCDTTM) for the trigger to use when building or altering the table.

See Also

Creating Field Definitions

Creating Record Definitions

Creating Page Definitions

Administering Data

Setting System IDs

Creating the SYNCID Field

To create the SYNCID field:

1. Open PeopleSoft Application Designer, and select File, New, Field.

2. In the Field Type field, select Number.

3. Clear the Signed check box.

4. In the Integer Positions field, enter 10.

5. Enter 0 in the Decimal Positions field.

6. (Optional) Select the Raw Binary Format check box.

7. Enter SYNCID as the label ID.

8. Enter Synchronization ID as the long name.

9. Enter Sync ID as the short name.

10. Select the Def (default) check box.

Creating the SYNCDTTM Field

To create the SYNCDTTM field:

1. Open PeopleSoft Application Designer, and select File, New, Field.

2. Select Datetime for the field type.

3. Enter SYNCDTTM for the label ID.

4. Enter Synchronization DateTimeStamp as the long name.

5. Enter SyncDateTime as the short name.

6. Select the Def (default) check box.

7. Enter 50 in the Default Century field.

8. Select HH:MM:SS:999999 in the Time Formatting field.

Adding SYNCID and SYNCDTTM Fields to Component Records

This section discusses how to add SYNCID and SYNCDTTM fields to component records and how to build and index the record tables before creating the synchronizable component interface.

To add SYNCID and SYNCDTTM to component records:

1. Open PeopleSoft Application Designer.

2. Open the selected component.

3. Insert the SYNCID and SYNCDTTM fields for each record that you want to expose in the component interface.

   Add SYNCID and SYNCDTTM at the end of the list of record fields.

4. For each record:

   1. Open the Record Properties dialog box.

   2. On the Use tab, set the Record-level Auto-Update, System ID Field to SYNCID.

      If you do not set the Record-level Auto-Update, System ID Field, you receive an error message when initializing the synchronization ID.

      Note. Subrecords exist only in relation to their parent records. If you include SYNCID and SYNCDTTM fields in a subrecord, those fields automatically appear as if they belong to the parent record. However, the SetSyncID function does not set SYNCID in subrecords. Set the Record-level Auto Update field in both the parent record and subrecord to SYNCID and SYNCDTTM. SetSyncID recognizes the subrecord SYNCID field as the parent’s, and sets it if necessary.

   3. Set the Timestamp field to SYNCDTTM.

5. If SYNCID is not a key of the record, add SYNCID to the properties index.

   The new index should not be unique.

   If you do not add a custom index for SYNCID, you cannot save the record.

6. Build or alter the project tables to add the new fields.

   • If you added SYNCID and SYNCDTTM to an existing component, select Build, Project, and specify Alter Tables and Create Views.

     Create Trigger is selected by default.

   • If you created a new component that includes SYNCID and SYNCDTTM, select Build, Project, and specify Build Tables, Create Views, and Create Trigger.

     If you do not specify Create Trigger, SYNCID and SYNCDTTM are not updated during synchronization.

   • If the record type is SQL View, open the SQL editor and manually add SYNCID and SYNCDTTM.

     Because the record is only a view of a table, not a table itself, the Build or Alter process does not update the view. Note also that views may not include data altered on the device until the next synchronization.

     Note. Select Create Trigger for every new component that is associated with or referenced by a synchronizable component interface and mobile page.

You can now create a synchronizable component interface based on this component.

See Also

Administering Data

Initializing Synchronization IDs

If you included a synchronization ID in a new component, any row that is added afterwards will have the synchronization ID set by the insert trigger.

If you added a synchronization ID to an existing component, the synchronization ID value is zero, and the synchronization ID therefore does not update properly. Initialize the synchronization ID to a value greater than zero with the Set Sync IDs utility.

You can set synchronization IDs in these ways:

• From the PeopleTools, Utilities, Administration page.

• Using the Application Engine program AE_SYNCIDGEN from Application Designer or from the command line.

  See Using the Command Line to Invoke Application Engine Programs.

You can either reset all sync IDs, or you can set them by the specified record or project.

Warning! If you choose to run the Set Sync IDs utility for any set of synchronization IDs, you must stop the application server, delete the application server cache, and restart the application server after running the Set Sync IDs utility.

To initialize Sync IDs by Record:

1. Sign in to PeopleSoft.

2. Select PeopleTools, Utilities, Administration, Set Sync IDs.

3. Select the Set By Record tab.

4. Specify the name of the record containing the Sync IDs that you want reset.

5. Optionally specify Reset all Sync IDs.

   If you do not select this option, only invalid synchronization IDs on the associated record are reset. An invalid synchronization ID is either null or zero. If you select this value, all synchronization IDs in the record are reset to a value greater than zero.

6. Click Set Sync IDs.

   This initializes all synchronization IDs, as specified.

To initialize Sync IDs for a project:

1. Sign in to PeopleSoft.

2. Select PeopleTools, Utilities, Administration, Set Sync IDs.

3. Select the Set by Project tab.

4. Optionally select Reset All Sync IDs.

   If you do not select this option, only invalid synchronization IDs are reset. An invalid synchronization ID is either null or zero. If you select this value, all synchronization IDs in the entire project are reset to a value greater than zero.

5. Click Set Sync IDs.

   This initializes all synchronization IDs, as specified.

To initialize all synchronization IDs:

1. Sign in to PeopleSoft.

2. Select PeopleTools, Utilities, Administration, Set Sync IDs.

3. Select the Set All Sync IDs tab.

4. Optionally select Reset All Sync IDs.

   If you do not select this option, only invalid synchronization IDs are reset. An invalid synchronization ID is either null or zero. If you select this value, all synchronization IDs in the entire database are reset to a value greater than zero.

5. Click Set Sync IDs.

   This initializes all synchronization IDs, as specified.

Note. You can also set up a Process Scheduler job to set synchronization IDs on a recurring basis. Select PeopleTools, Utilities, Administration, Set Sync ID Process to set up the job.

See Also

Setting System IDs

Mobilizing Applications

Making an application available on mobile devices is known as mobilizing an application.

Note. While synchronizable component interfaces are the requisite building block of mobile applications, the base component interface and underlying components must be thoroughly tested and working properly before defining the mobile component interface. Using a nonfunctional component as the basis for a mobile component interface results in a nonfunctional component interface and failure of the associated mobile pages.

If you are mobilizing an existing working application, begin by opening an existing component interface. Using the instructions provided in this chapter, build the synchronizable component interface by:

1. Opening a component interface.

2. Running the Validate for Consistency process to identify record definitions requiring modification.

3. Adding synchronization ID and synchronization datetime stamp fields to the required records, creating an index for each table based on the synchronization ID, and building or altering the tables (which includes building the required database triggers).

Note. Every property exposed in the component interface is synchronized with the mobile device during synchronization, even if the property is not displayed on a mobile page. Synchronizing properties that are not displayed might cause performance issues and should be avoided. When mobilizing an existing application, consider creating new component interfaces specifically for use with PeopleSoft Mobile Agent.

If you are developing a new application for use with PeopleSoft Mobile Agent, include synchronization ID and synchronization datetime stamp fields in the records of the application’s components before creating the associated component interfaces.

See Also

Developing the Component Interface

Understanding Mobile Pages and Classes

Defining Synchronizable Component Interfaces

You can base your mobile page on an existing component and component interface or create a new component interface. In either case, each record to be exposed in the synchronizable component interface must include synchronization ID and datetime stamp fields.

This section discusses how to:

• Create synchronizable component interfaces.

• Add component interfaces to permission lists.

Creating Synchronizable Component Interfaces

To create a synchronizable component interface, select the Synchronization tab of the Properties dialog box in Application Designer.

Synchronizable

Select to create a synchronizable component interface.

Conflict Resolution

Select one of the following options to resolve conflicts in data between the device and the server.

See Synchronization Conflict Resolution.

Application Messages

Application developers can write PeopleCode to issue a message to the mobile device. Specify the message set number to be synchronized on the component interface designer dialog box, Synchronization tab.

Upload Changes from Mobile Device?

Select an option from the Upload changes from mobile device? group box to determine whether data created or modified on the mobile device is uploaded to the server. None of these options affect new data created on the server. New server data is always downloaded to the mobile device, regardless of the value of this setting.

Related Content Project

Note. Every property exposed in the component interface is synchronized with the mobile device during synchronization, even if the property is not displayed on a mobile page. Synchronizing properties that are not displayed might cause performance issues and should be avoided.

Creating Synchronizable Component IDs

To create a synchronizable component ID:

1. Create a new component interface for the selected component.

   Accept the default properties from the associated component, or select properties after creating the component interface.

2. Add properties to, or delete properties from, the component interface.

   Drag properties from the associated component.

3. Open the component interface Properties dialog box.

4. Select the Synchronization tab.

5. Select Synchronizable.

6. Select a conflict resolution method.

7. Select from Upload changes from mobile device? group to determine whether or not data created or modified on the mobile device will be uploaded to the server:

8. Save the component interface.

Validating and Testing the Component Interface

Select Tools, Validate for Consistency from the PeopleSoft Application Designer menu to validate the current component interface.

Validation checks for the presence of a synchronization ID and synchronization datetime stamp for each record exposed in the component interface. A list of errors and warnings appears in the Validate window. If an error indicates that a record requires a synchronization ID or datetime stamp, double-click the message to open and edit the property.

Testing for validation before the component interface is defined as synchronizable does not locate missing synchronization IDs and synchronization datetime stamps on associated records.

See Validating the Component Interface.

Select Tools, Test Component Interface from the PeopleSoft Application Designer menu to test the current component interface.

The Component Interface Tester appears, enabling you to perform search tests on the component interface and its associated records using existing data. Synchronization uses the get method, so it is important to test this method. If you receive a Not Authorized error message, you do not have permission for this component interface. You must obtain permission.

See Testing the Component Interface.

Adding Component Interfaces to Permission Lists

Include every component interface associated with a mobile page in the appropriate permission lists for mobile users.

The mobile personalization component interface, MOBILE_PREFS_CI, handles the specification of date format, time zone, currency code, and daylight savings time parameters. The user sets mobile preferences using the My Personalizations link in the Mobile Portal menu.

Add permissions to MOBILE_PREFS_CI through the PTPT1000 (PeopleSoft user) permissions list. The administrator then adds this permissions list to the role of the mobile users.

Note. Every component interface referenced by a mobile page must be included in the appropriate permission list, even if the component interface is not the basis for the mobile page. Without permission to all referenced component interfaces, data is not available during synchronization, and the synchronization fails.

Adding a Component Interface to the Permission List

To add a component interface to a permission list:

1. Sign in to PeopleSoft in your browser.

2. Select PeopleTools, Security, Permissions & Roles, Permission Lists.

3. On the Find an Existing Values page, search for and select the appropriate permission list.

   If the appropriate permission list does not yet exist, select Add a New Value and create a permission list for mobile applications.

4. Scroll right to display the Component Interfaces tab.

5. Add the component interface.

6. Click Save.

See Also

Managing Permission Lists

Using Reference Properties

Each component interface is unaware of the other component interfaces in the system. To access and update information from other component interfaces, references establish relationships between component interfaces.

This section provides an overview of references and discusses how to create reference properties.

Understanding References

A component interface reference property is equivalent to a database table foreign key (or multiple keys), which links one table to another. A reference property defines the relationship between two or more tables (objects), allowing a component interface to access data from another component interface.

As components represent business objects, component interfaces represent the exposed properties (fields) of those business objects. Each component interface may contain one or more foreign keys to the database tables exposed by another component interface, but that relationship is not formalized and available for use unless explicitly linked using a reference property.

Create a reference property in one component interface to access data exposed in another component interface. For example, the Customer object and the component interface exposing its properties include properties such as the customer’s name, address, and telephone numbers. Another object, Contact, includes data associated with all contacts in the system. The link between a specific customer and its associated contacts is owned by the Contact record, not the Customer record.

Therefore, to access contact data, the Customer component interface needs a reference property referring to the Contact component interface. To update contact data from the Customer component interface, the reference must include a valid reference path and reference back-pointer back to the customer ID.

Note. PeopleSoft Application Designer allows reference and data collection properties to be marked as derived in the component interface definition. Derived references are not supported; a derived flag on a reference is ignored.

Creating Reference Properties

A reference property always points to another component interface. A database relationship must exist between the current component interface and the component interface being referenced. Define the mapping of the relationship while creating a reference property.

Note. All references, including dynamic enumerations, are treated the same in regards to being required. If you mark the record field for a property as required, the reference is also automatically marked as required. When multiple properties are used to form the basis of a reference, even if only one of the underlying properties is required, the reference is treated as required by the system, even though it may not have been marked explicitly as required.

To create a reference property:

1. Open the selected component interface.

2. Select the fields that form the foreign key to the related component.

3. Right-click a selected field, and select Create Reference.

   The Create Reference dialog box appears.

Name	Enter an identifying name for the reference, which becomes a property that can be used in PeopleCode. Appears in the component interface.
Related Component Interface	Select the component interface referenced from the current component interface. Only synchronizable component interfaces appear in the list.
Related Key Mapping	Map the property from the related component interface to the selected component interface property.
Valid Reference Path	Specify dynamic enumeration of the objects that can be selected as the value of the reference property being defined. This effectively filters these values so that you can select only objects that support the defined reference. Because references use the concept of a walkpath to go from level zero of one component interface to level zero of another component interface, and then “walk” down to the lower levels of the component interface, only the level zero references are displayed in the Valid Reference Path drop-down list of a reference definition
Reference Backpointer	Select a backpointer to the originating component interface.

Using Attachments

PeopleSoft Mobile Agent supports attachments, which require setting up reference properties on synchronizable component interfaces. PeopleTools supports attachments for mobile devices. The attachment consists of header information (such as size, type, and description) and the corresponding document object. The attachment events occur when the mobile user synchronizes the mobile device.

PeopleSoft Mobile Agent supports attachments from many different technologies. For example, a relational database, FTP server, or document management system are all possible sources of attachment data.

To enable attachments for mobile pages:

1. Build a synchronizable component interface on a component that is set up to use attachments.

   See Using File Attachments in Applications.

2. Create a reference property in the synchronizable component interface.

3. Select the reference property, right-click, and select Edit Reference from the popup menu.

4. On the Edit Reference property page, specify the related component interface for the ATTACHMENT reference property as <Attachment>.

5. On the Edit Reference property page, associate the file name with the ATTACHUSERFILE field.

   Once you have created the ATTACHMENT property, all the attachment events are displayed in the PeopleCode editor for the ATTACHMENT property.

Both binary and text document types are supported. You can define storage interaction mechanisms. For example, you can directly retrieve a Calico project file from Calico's native storage mechanism, or move content to and from a document management system such as Documentum.

Note. When enabling attachments, add filtering programs to block malicious programs from accessing the system. For example, you might not allow .exe file types, so that destructive macros or HTML scripts are not brought into the system as attachments.

See Also

Mobile Classes