Actions on structs（结构体操作）

Struct property values can be created and modified with actions, through values supplied in a struct parameter.

Struct parameters

A struct parameter is a parameter of base type STRUCT, where the type contains nested parameter fields that have their own individual names and base types. A struct parameter can be only be used to supply values for a struct property. The supported base types for struct parameter fields are BOOLEAN, DATE, DOUBLE, GEOPOINT, INTEGER, LONG, STRING, and TIMESTAMP.

Below, we have a Resolution struct parameter for a Create Ticket action. The nested fields of summary, resolutionTime, and owner compile information on how the ticket was resolved into a single parameter.

Defining actions on struct properties

Using actions with struct parameters, you can create and modify object types with struct properties. The values for the struct property are submitted in a struct parameter mapped to the property; each individual field of the struct property is mapped to a specific field of a struct parameter. In the example below, each field of the Resolution struct parameter is mapped to its corresponding field in the Resolution struct property of the Ticket object type.

A mapping between a struct property and a struct parameter must be complete, with each field of the struct property mapped to a field in the struct parameter. The base type of the struct parameter field must match the base type of a mapped struct property field. If any breaking changes are to be made to the struct property type (for example, if a new field is added, a field is deleted, or a field's base type is changed), then the related action types must also be modified to incorporate those changes.

Struct parameters in an action form

A struct parameter can be populated through action forms similarly to any other parameter type. However, struct parameter fields are rendered as a group in the form instead of individually.

Default values for struct parameter fields

Default values are defined individually for struct parameter fields. Each struct parameter field is mapped to fields of a specified object type's struct property. A default value must be defined for all fields in the struct parameter and must be mapped to fields of the same object type struct property. Only struct property fields can act as default values for struct parameter fields. The object type whose struct property fields will act as default values is specified in the ObjectReference parameter.

An instance of an object of the type specified in the ObjectReference parameter is supplied when submitting the action, and that object's struct property field values will automatically fill in the values of the corresponding struct parameter fields.

Constraints on struct parameter fields

Constraints can be configured individually for struct parameter fields, as with regular parameters. For example, a string length constraint can be defined on struct parameter fields of string types to only allow string value that are between 10 and 500 characters long. This would mean that the summary field of a the Resolution struct parameter must be at least 10 characters long, but no longer than 500 characters.

A struct parameter value is only valid if all fields meet the defined constraint. Users can only submit a struct parameter value if each field value satisfies the constraints defined on them. As defined for the summary field, a value shorter than 10 characters would be invalid.

Limitations

Consider the following limitations when creating or modifying struct parameters with actions:

• Struct property values can only be created or modified through struct parameters. Other forms of entry, such as static values or references to object properties, are not supported.
• A struct property can only be created or modified through a single struct parameter. A struct property mapping in actions cannot more than one parameter.
• A struct parameter can only be used to create or modify struct properties. Struct parameter fields cannot be used individually to create or modify non-struct properties.
• Only references to a single object type struct property values can act as default values for struct parameter fields. Other forms of entry, such as static values, are not supported.

---

中文翻译

结构体操作

通过操作（actions），可以使用结构体参数（struct parameter）中提供的值来创建和修改结构体属性值。

结构体参数

结构体参数是一种基础类型为 STRUCT 的参数，其类型包含具有各自独立名称和基础类型的嵌套参数字段。结构体参数仅用于为结构体属性提供值。结构体参数字段支持的基础类型包括：BOOLEAN、DATE、DOUBLE、GEOPOINT、INTEGER、LONG、STRING 和 TIMESTAMP。

下面是一个用于"创建工单"操作的 Resolution 结构体参数。summary、resolutionTime 和 owner 的嵌套字段将工单解决方式的相关信息整合到一个参数中。

定义结构体属性上的操作

使用带有结构体参数的操作，您可以创建和修改具有结构体属性的对象类型。结构体属性的值通过映射到该属性的结构体参数提交；结构体属性的每个单独字段都映射到结构体参数的特定字段。在下面的示例中，Resolution 结构体参数的每个字段都映射到 Ticket 对象类型的 Resolution 结构体属性中的对应字段。

结构体属性与结构体参数之间的映射必须完整，结构体属性的每个字段都必须映射到结构体参数中的一个字段。结构体参数字段的基础类型必须与映射的结构体属性字段的基础类型匹配。如果要对结构体属性类型进行任何破坏性更改（例如，添加新字段、删除字段或更改字段的基础类型），则必须同时修改相关的操作类型以纳入这些更改。

操作表单中的结构体参数

结构体参数可以像其他参数类型一样通过操作表单填充。但是，结构体参数字段在表单中会以组的形式呈现，而不是单独显示。

结构体参数字段的默认值

默认值是针对结构体参数字段单独定义的。每个结构体参数字段都映射到指定对象类型的结构体属性的字段。必须为结构体参数中的所有字段定义默认值，并且这些字段必须映射到同一对象类型结构体属性的字段。只有结构体属性字段可以作为结构体参数字段的默认值。其结构体属性字段将作为默认值的对象类型在 ObjectReference 参数中指定。

提交操作时，会提供 ObjectReference 参数中指定类型的对象实例，该对象的结构体属性字段值将自动填充到对应结构体参数字段的值中。

结构体参数字段的约束

与常规参数一样，可以针对结构体参数字段单独配置约束。例如，可以在字符串类型的结构体参数字段上定义字符串长度约束，仅允许长度在 10 到 500 个字符之间的字符串值。这意味着 Resolution 结构体参数的 summary 字段长度必须至少为 10 个字符，但不超过 500 个字符。

结构体参数值仅在所有字段都满足定义的约束时才有效。用户只有在每个字段值都满足为其定义的约束时才能提交结构体参数值。如 summary 字段的定义所示，长度少于 10 个字符的值将被视为无效。

限制

在通过操作创建或修改结构体参数时，请考虑以下限制：

• 结构体属性值只能通过结构体参数创建或修改。不支持其他输入形式，例如静态值或对象属性引用。
• 结构体属性只能通过单个结构体参数创建或修改。操作中的结构体属性映射不能包含多个参数。
• 结构体参数只能用于创建或修改结构体属性。结构体参数字段不能单独用于创建或修改非结构体属性。
• 只有对单个对象类型结构体属性值的引用才能作为结构体参数字段的默认值。不支持其他输入形式，例如静态值。