Edit object types（编辑对象类型）

:::callout{theme="warning" title="Warning"} Editing an object type and its properties can have application-breaking consequences that can disrupt user workflows. Read the section below on potential breaking changes before proceeding with any object type or property edits. :::

Potential breaking changes

Object type without writeback

Changes that require Object Storage V1 (Phonograph) to unregister and reregister the backing datasources of an object type will make the objects of that type unavailable in user applications during that reindex time; these changes are described below.

The following changes will unregister and reregister (or delete) the backing datasources of an object type when saved:

• Changing an object type’s backing datasource.
• Changing the primary key of an object type.
• Deleting an object type.

When you try to save any of these changes, you will be warned about the potential impact on user applications.

For example, if an object type is used in a Workshop application, that Workshop application will be broken until the reindex completes. You can track the progress of the reindex for an object type in the Phonograph pane of its Datasources page.

Learn more about Object Storage V1 (Phonograph).

Object type with writeback

If an object type has writeback enabled, extra precaution should be taken when making edits to that object type. The history of edits made to an object type are stored in Object Storage V1 (Phonograph). Every time a writeback dataset is built, the history of edits is reapplied to get the final state of edited objects in the writeback dataset. When the backing datasources of an object type are unregistered from Object Storage V1 (Phonograph), the history of edits in Object Storage V1 (Phonograph) is deleted and future builds of the writeback dataset will fail.

In addition to the changes that require unregistering that were listed in the previous section, unregistering is required for object types with writeback when schema changes are made to any property of an object type that has ever received edits, even if it does not currently receive edits. Schema changes include changes to the ID and base type of a property.

The following changes do not require unregistering and therefore do not risk losing the edit history:

• Changing the display name, title key, render hints, type classes, and visibility of a property that has received edits will not require the object type to unregister.
• Deleting fields or making schema changes to fields that have never received edits will not require the object type to unregister, and therefore will not erase or undo edits on other fields that are receiving edits.

:::callout{theme="warning" title="Warning"} Object Storage V1 (Phonograph) will not automatically unregister the backing datasources of an object type in response to one of these schema changes. Instead, the reindex will fail and will only succeed if the saved schema changes are undone, or if you manually unregister and reregister the backing datasources of the object type in the Phonograph pane of the object type’s Datasource page. :::

The properties pane in the property editor highlights whether a field has ever received edits.

Furthermore, when you try to save any changes that risk erasing the edit history, you will be warned about the potential impact on edits.

Now that you understand the considerations in editing existing object types and properties, you can safely make your changes.

Edit an existing object type

• Navigate to an existing object type
• Delete an object type
• Change a backing datasource
• Edit an object type’s metadata

Navigate to an existing object type

You can always change the object type you are working on by selecting the object type page from the home page sidebar and selecting a different object type from the list. You can also always search for a new object type in the search bar in the application header. Read more about navigation.

Delete an object type

You can delete an object type by selecting the (three dots) icon at the top right of the object type view sidebar (see image below) and then selecting the Delete option from the dropdown. A dialog will pop up to confirm you want to stage the object type and all of its associated link types for deletion.

• Note that the deletion of the object type only takes effect after you save your changes, and will break any views or applications referencing the object type.
• Object types with an active status cannot be deleted. Read more about statuses.

Change a backing datasource

You can change a backing datasource with the following steps:

1. Navigate to the property editor by selecting Edit property mapping at the top of the Properties page of an object type.
2. Select the Replace button at the top of the Datasources pane. This will allow you to browse and select available datasources in Foundry.

:::callout{theme="warning" title="Warning"} Changing the backing datasource of an object type will remove any connection between columns in the old datasource and the object type’s properties. Properties will be automatically remapped for you only if you change to a new datasource with the same schema as the old datasource. Otherwise, you will need to remap the object type’s properties to the new datasource. :::

Edit an object type’s metadata

1. Icon: Select the default icon to customize the icon and color of the object type that will appear in user applications when a user views an object of this type.
2. Display names and description: Select into the existing display names or description to edit the text.
3. Status: Select the existing status to open a dropdown of available statuses. Choose from the deprecated, experimental, and active statuses.
4. Read more about statuses.
5. Visibility: Select the existing visibility to open a dropdown of available visibilities. A prominent object type will lead applications to show this object type first to users. A hidden object type will not appear in user applications.
6. API name: Select into the existing API name to change its value.
7. Note that you cannot change the API name for object types with an active status.
   • Read more about statuses.
   • Read more about valid API names.

:::callout{theme="neutral"} The object ID of an object type cannot be edited after the initial object type creation process. :::

Troubleshooting

Error: Phonograph2:FoundryColumnNameNotFound

If you receive the error Phonograph2:FoundryColumnNameNotFound, a column has been removed from the datasource backing the object type you are trying to save and a property is left unmapped. The property needs to either be mapped or deleted.

Error: Phonograph2:InvalidColumnRemoval

If you receive the error Phonograph2:InvalidColumnRemoval, a column has been removed that was backing a property that has received edits. Either the column needs to be added back to the datasource, or the object type needs to be unregistered and reregistered.

See the section above on potential breaking changes to learn more.

Error: Phonograph2:InvalidColumnFieldSchemaChange

If you receive the error Phonograph2:InvalidColumnFieldSchemaChange, a property that has received edits has had its ID or key changed. Either the change needs to be reverted, or the object type needs to be unregistered and reregistered.

See the section above on potential breaking changes to learn more.

Error: OntologyMetadata:IncompatibleFoundryFieldSchemaForPropertyType

If you receive the error OntologyMetadata:IncompatibleFoundryFieldSchemaForPropertyType, you are trying to save a property with a base type that is incompatible with the column type that is backing it. For example, the type of column X may been changed to “string”, but is mapped to property X of base type “integer”.

Error: Phonograph2:SchemaMismatch

If you receive the error Phonograph2:SchemaMismatch, you likely made an intentional change to the schema that backs the object but have have not yet updated the object's property types in Ontology Manager. Modify the Ontology by editing the property's data type to accept the new type. Publish the changes and rebuild the dataset, then initiate a re-index of the object.

Error: FieldTypeIncompatibleWithOntologyPropertyType

If you receive the error FieldTypeIncompatibleWithOntologyPropertyType or receive the message "Failed to Update Object Type in Phonograph", there is a mismatch between the data types in the dataset that backs your object and the data types that the ontology expects. You must ensure that any schema updates are reflected in both the dataset and the ontology.

If you did make any intentional changes to the ontology or the dataset, communicate with the owner of the object and its backing data source to understand recent changes.

---

中文翻译

编辑对象类型

:::callout{theme="warning" title="警告"} 编辑对象类型及其属性可能会产生破坏应用程序的后果，从而中断用户工作流。在继续编辑任何对象类型或属性之前，请阅读下方关于潜在破坏性变更的章节。 :::

潜在破坏性变更

不支持回写的对象类型

需要对象存储 V1（Phonograph）注销并重新注册对象类型底层数据源的变更，将导致该对象类型的对象在重新索引期间在用户应用程序中不可用；这些变更如下所述。

以下变更在保存时将注销并重新注册（或删除）对象类型的底层数据源：

• 更改对象类型的底层数据源。
• 更改对象类型的主键。
• 删除对象类型。

当您尝试保存这些变更中的任意一项时，系统将警告您对用户应用程序的潜在影响。

例如，如果某个对象类型在 Workshop 应用程序中使用，则该 Workshop 应用程序将在重新索引完成前无法使用。您可以在对象类型数据源页面的 Phonograph 窗格中跟踪重新索引的进度。

了解更多关于对象存储 V1（Phonograph）的信息。

支持回写的对象类型

如果对象类型启用了回写功能，则在编辑该对象类型时应格外谨慎。对对象类型所做的编辑历史记录存储在对象存储 V1（Phonograph）中。每次构建回写数据集时，都会重新应用编辑历史记录，以获取回写数据集中已编辑对象的最终状态。当对象类型的底层数据源从对象存储 V1（Phonograph）注销时，对象存储 V1（Phonograph）中的编辑历史记录将被删除，未来对回写数据集的构建将失败。

除了上一节中列出的需要注销的变更外，对于支持回写的对象类型，当对曾经接收过编辑的任何属性（即使当前未接收编辑）进行模式变更时，也需要注销。模式变更包括更改属性的 ID 和基本类型。

以下变更不需要注销，因此不会丢失编辑历史记录：

• 更改已接收编辑的属性的显示名称、标题键、渲染提示、类型类和可见性不需要对象类型注销。
• 删除字段或对从未接收过编辑的字段进行模式变更不需要对象类型注销，因此不会擦除或撤销其他正在接收编辑的字段上的编辑。

:::callout{theme="warning" title="警告"} 对象存储 V1（Phonograph）将不会自动响应这些模式变更而注销对象类型的底层数据源。相反，重新索引将失败，并且只有在撤销已保存的模式变更，或者您在对象类型数据源页面的 Phonograph 窗格中手动注销并重新注册对象类型的底层数据源时，重新索引才会成功。 :::

属性编辑器中的属性窗格会高亮显示某个字段是否曾接收过编辑。

此外，当您尝试保存任何可能擦除编辑历史记录的变更时，系统将警告您对编辑的潜在影响。

现在您已经了解了编辑现有对象类型和属性时的注意事项，可以安全地进行更改了。

编辑现有对象类型

• 导航到现有对象类型
• 删除对象类型
• 更改底层数据源
• 编辑对象类型的元数据

导航到现有对象类型

您可以通过从主页侧边栏选择对象类型页面，然后从列表中选择不同的对象类型，来随时更改您正在处理的对象类型。您也可以始终在应用程序顶部的搜索栏中搜索新的对象类型。了解更多关于导航的信息。

删除对象类型

您可以通过选择对象类型视图侧边栏右上角的 （三点）图标（见下图），然后从下拉菜单中选择删除选项来删除对象类型。将弹出一个对话框，确认您要暂存删除该对象类型及其所有关联的链接类型。

• 请注意，对象类型的删除仅在您保存更改后生效，并且会破坏引用该对象类型的任何视图或应用程序。
• 状态为 active（活跃）的对象类型无法删除。了解更多关于状态的信息。

更改底层数据源

您可以通过以下步骤更改底层数据源：

1. 通过选择对象类型属性页面顶部的编辑属性映射，导航到属性编辑器。
2. 选择数据源窗格顶部的 替换按钮。这将允许您浏览并选择 Foundry 中可用的数据源。

:::callout{theme="warning" title="警告"} 更改对象类型的底层数据源将移除旧数据源中的列与对象类型属性之间的任何连接。仅当您更改为与旧数据源具有相同模式的新数据源时，属性才会自动为您重新映射。否则，您需要将对象类型的属性重新映射到新数据源。 :::

编辑对象类型的元数据

1. 图标： 选择默认图标以自定义对象类型的图标和颜色，这些图标和颜色将在用户查看此类型的对象时显示在用户应用程序中。
2. 显示名称和描述： 选择现有的显示名称或描述以编辑文本。
3. 状态： 选择现有状态以打开可用状态的下拉菜单。从 deprecated（已弃用）、experimental（实验性）和 active（活跃）状态中选择。
4. 了解更多关于状态的信息。
5. 可见性： 选择现有可见性以打开可用可见性的下拉菜单。prominent（突出）对象类型将导致应用程序首先向用户显示此对象类型。hidden（隐藏）对象类型将不会出现在用户应用程序中。
6. API 名称： 选择现有的 API 名称以更改其值。
7. 请注意，您无法更改状态为 active（活跃）的对象类型的 API 名称。
   • 了解更多关于状态的信息。
   • 了解更多关于有效的 API 名称的信息。

:::callout{theme="neutral"} 对象类型的对象 ID 在初始对象类型创建过程完成后无法编辑。 :::

故障排除

错误：Phonograph2:FoundryColumnNameNotFound

如果您收到错误 Phonograph2:FoundryColumnNameNotFound，则表示支持您尝试保存的对象类型的数据源中已移除了一列，并且某个属性未映射。该属性需要被映射或删除。

错误：Phonograph2:InvalidColumnRemoval

如果您收到错误 Phonograph2:InvalidColumnRemoval，则表示已移除了一列，而该列支持一个已接收过编辑的属性。要么需要将该列重新添加回数据源，要么需要注销并重新注册该对象类型。

请参阅上方关于潜在破坏性变更的章节以了解更多信息。

错误：Phonograph2:InvalidColumnFieldSchemaChange

如果您收到错误 Phonograph2:InvalidColumnFieldSchemaChange，则表示一个已接收过编辑的属性的 ID 或键已更改。要么需要还原该更改，要么需要注销并重新注册该对象类型。

请参阅上方关于潜在破坏性变更的章节以了解更多信息。

错误：OntologyMetadata:IncompatibleFoundryFieldSchemaForPropertyType

如果您收到错误 OntologyMetadata:IncompatibleFoundryFieldSchemaForPropertyType，则表示您尝试保存一个基本类型与支持它的列类型不兼容的属性。例如，列 X 的类型可能已更改为"字符串"，但它映射到基本类型为"整数"的属性 X。

错误：Phonograph2:SchemaMismatch

如果您收到错误 Phonograph2:SchemaMismatch，则您可能有意更改了支持该对象的模式，但尚未在 Ontology Manager 中更新对象的属性类型。通过编辑属性的数据类型以接受新类型来修改 Ontology。发布更改并重建数据集，然后启动对象的重新索引。

错误：FieldTypeIncompatibleWithOntologyPropertyType

如果您收到错误 FieldTypeIncompatibleWithOntologyPropertyType 或收到消息"无法在 Phonograph 中更新对象类型"，则表示支持您的对象的数据集中的数据类型与 Ontology 期望的数据类型之间存在不匹配。您必须确保任何模式更新都同时反映在数据集和 Ontology 中。

如果您确实对 Ontology 或数据集进行了有意更改，请与对象及其底层数据源的所有者沟通以了解最近的更改。