Integrator > Synchronize user data with EPIC > External ownership and locking

External ownership and locking

When you import objects such as users, devices, and groups from your management system into xMatters, you can specify which system owns the data. When your management system owns the data, it is said to be externally owned. Externally-owned data is primarily maintained by your management system and is updated in xMatters with a data synchronization process.

We use the term data synchronization process to refer to the process of importing data into xMatters, regardless of which tool is used to perform the data synchronization. These tools include the Data Synchronization tool and the EPIC tool, which you can run in CloudSync mode and ZipSync mode.

Externally owned objects

Marking an object as externally owned changes how it is managed in the xMatters user interface:

  • Externally-owned objects cannot usually be deleted using the xMatters user interface. Externally owned objects are typically deleted in the external management system and removed from xMatters during the next data synchronization process.
  • Externally-owned objects can be locked in the xMatters user interface. This prevents them from being modified by most users.

The data synchronization process can overwrite objects in xMatters, regardless of whether they are externally owned. Marking an object as not externally owned does not prevent it from being overwritten by the data synchronization process.

Deleting externally owned data

It is possible for a user with advanced permissions, such as a Company Administrator, to manually delete externally-owned data from xMatters using the web user interface. However, this data may be added back to xMatters during the next data synchronization if it is not also deleted from the external management system. To ensure that externally-owned data is deleted from xMatters permanently, you must also delete it from the external management system.  

The ability to delete externally-owned users is controlled by permission ability.act.ManageExternallyOwned.

Deleting an externally-owned user also deletes their devices.

To mark objects as externally owned:
  • EPIC using ZipSync mode: In ZipSync mode, you specify whether each object is externally owned by setting the IS_EXTERNALLY_OWNED flag to Y in the ZipSync archive files. For more information about running EPIC in ZipSync mode, see Running ZipSync mode.
  • EPIC using CloudSync mode: In CloudSync mode, all objects are set to be externally owned unless you run EPIC with the --migrate (or -m) option, in which case all objects are marked as not externally owned. For more information about running EPIC in CloudSync mode see, Running EPIC in CloudSync Mode.
  • Data Synchronization Tool: In the Data Synchronization tool, set the IS_EXTERNALLY_OWNED flag in the staging table for each object.
  • Web Service Methods: Some web service methods allow you to set whether an object is externally owned. For more information, see the Online Developer Guide.

Locked objects

You can prevent users from modifying externally-owned objects. Externally-owned objects observe the field locking rules that are configured for each object type. For example, you can lock the Name property of the Group object to prevent users from being able to modify names of externally-owned groups. Field locking rules only apply to externally-owned objects. In this example, users are able to modify the names of groups that are not externally owned.

Users who have a role that includes the Override Data Lock function can edit the values of locked properties. By default, the Company Administrator and Support User roles include the Override Data Lock function. For more information about how to lock the properties of an object, see Locking externally-owned objects in the xMatters user interface.

The Custom Attributes and Custom Fields properties appear as properties of the Person object. These settings must be marked as externally owned separately from the Person object. For example, if the Person object is not set as externally owned, but the Custom Attributes object is externally owned, then you can lock the Custom Attributes setting. Alternatively, if the Person object is flagged as externally owned, but Custom Fields property is not, then you cannot lock the Custom Fields property setting.

Summary of External Ownership and Locking objects
  Object is externally owned and locked Object is externally owned
and not locked

Object is not externally owned

Field locking rules are observed. Yes Yes No
Objects can be updated in the xMatters user interface. No
(except users with a role that has the Override Data Lock function)
Yes Yes
Objects can be deleted by using the xMatters user interface. No No Yes
Objects can be overwritten or deleted by the next data synchronization. Yes Yes Yes

Use cases for object ownership and locking

This section explains when to mark an object as externally owned and when to lock it, based on how you plan to maintain the data. It provides several typical use cases and describes the external ownership and locking settings you might use for each one.

The following table provides a summary of how an object behaves depending whether it is externally owned or locked.

Updating xMatters between data synchronization processes

When data is modified in your management system, it is not updated in xMatters until the next time data synchronization is performed. For example, if a user changes their mobile phone number in your management system, they will not receive xMatters notifications on that phone until their phone number is updated in xMatters. In this case, you may want to manually update the phone number in xMatters before the next data synchronization is performed.

There are two ways to manually update objects in xMatters :

  • If the object is not externally owned, or if it is externally owned and not locked, then any user who can view and modify the object can update it using the xMatters user interface.
  • If the object is externally owned and locked, then an advanced user can update the locked object. The advanced user must have the Override Data Lock function assigned to one of their roles and have permission to view and modify the object.

Use case 1: Your management system owns the data

Suggested settings: Externally Owned and Locked

When you mark an object as externally-owned and locked, your external management system maintains the data, and xMatters is updated through the data synchronization process. In this case, personnel do not typically log on to xMatters to update the data. However, advanced users can update objects in xMatters if modifications are required before the next data synchronization is performed.

Because objects are externally owned, they can only be deleted with the data synchronization process, and cannot be deleted through the xMatters user interface.

These settings are commonly used when the data synchronization process is run in mirror mode and is performed on a regular basis.

Use case 2: xMatters owns the data

Suggested settings: Not externally owned

When you mark an object to be not externally owned, the data is maintained in xMatters. Users are able to modify and delete objects in xMatters, and over time the data in xMatters may no longer exactly match the data in your management system.

If you are using data synchronization as part of a one-time process to import data to an xMatters system, but then plan on maintaining the data in xMatters, mark objects as not externally owned. This enables you to modify and delete them freely in the xMatters user interface without performing the data synchronization process again.

For this type of use case, exercise caution if you plan to use the data synchronization process in the future. The data synchronization process can overwrite objects even if they are not marked as externally owned. Ensure that the data in your management system matches xMatters data, or be careful only to update values that you intend to overwrite.

Use case 3: Data can be updated but not deleted in xMatters

Suggested settings: Externally owned and not locked

When the data is externally-owned and not locked, users are able to update it, but not delete it, using the xMatters user interface. You could use these settings if you use the data synchronization process to add and remove users from xMatters, but you want to allow users to modify their own information in the xMatters user interface.