A user-defined models (UDM) allows you to create reusable data access objects, or models, and annotate their getters and setters as user-defined properties. You can then use models with JsonService to translate data to and from JSON, or with HttpService to send and receive data using Vault API.

With UDMs, you can:

Execute a VQL query against a remote Vault. First, useHttpService to query Vault API, then return the response body as a model, which deserializes the response JSON into fields defined by the model’s user-defined properties.
Using QueryService, stream VQL query results that are mapped automatically to a UDM.
Using JsonService, pass Vault data into a model which, based on its user-defined properties annotations, serializes the data into a JSON string which can be used as input for a REST API or stored in a Long Text field in an object record.
Using JsonService, deserialize a JSON string to a UDM.

Creating User-Defined Models

A user-defined model (UDM) is an interface that uses the @UserDefinedModelInfo annotation and extends the UserDefinedModel interface. For example, the following is an example of a UDM that represents three fields on a single document: id, name__v, and product__v.

@UserDefinedModelInfo(include = UserDefinedPropertyInclude.NON_NULL)
public interface BasicDocModel extends UserDefinedModel {

   @UserDefinedProperty()
   BigDecimal getId();
   void setId(BigDecimal id);

   @UserDefinedProperty(name = "name__v", aliases = {"name", "name__c"})
   String getName();
   void setName(String name);

   @UserDefinedProperty(name = "product__v", include = UserDefinedPropertyInclude.ALWAYS)
   ProductModel getProduct();
   void setProduct(ProductModel product);

}

A UDM can extend another UDM. For example, a PresentationDocModel might extend the BasicDocModel.

About User-Defined Properties

The @UserDefinedProperty annotation can only be used on an interface with the @UserDefinedModelInfo annotation. All @UserDefinedProperty annotations must have a defined getter method with no parameters and a valid return type. Setter methods must have one parameter of a valid type. See the Javadoc for valid types for getters and setters. The name parameter is the JSON field name that will be serialized from and deserialized to this property. If the JSON field name is not always the same, you can define one or more aliases to be deserialized to this property. If the JSON field name value exactly matches the getter and setter name pattern, the name parameter can be omitted as shown for getId() and setId() below.

You can set one or more default values using the defaultValue or defaultValues parameter. You can only set default values for properties whose type is BigDecimal, Boolean, String, or a collection of Strings.

@UserDefinedProperty(name = "pageoffset", aliases = {"offset"})
BigDecimal getPageOffset();

@UserDefinedProperty(defaultValue = "New Document")
String getName();

@UserDefinedProperty
BigDecimal getId();
void setId(BigDecimal id);

About UserDefinedPropertyInclude

The UserDefinedPropertyInclude enum specifies how JsonService should serialize values and is set by the include parameter of a user-defined model or property. If no value is set for a user-defined property, serialization defaults to the behavior of the user-defined model it belongs to. During deserialization, JsonService ignores any fields that are not defined in the user-defined model. Learn more in the Javadoc.

@UserDefinedModelInfo(include = UserDefinedPropertyInclude.ALWAYS)
public interface MyModel extends UserDefinedModel {

@UserDefinedProperty(include = UserDefinedPropertyInclude.NON_NULL)
String getData();
}

Using User-Defined Models

Use UserDefinedModelService to create a new, empty model instance in a trigger or action. You can then use JsonService to serialize and deserialize data. You can also use HttpService to create an HTTP request that accepts one or more user-defined models (UDMs) as the request body, or returns a UDM as the response body.

UserDefinedModelService modelService = ServiceLocator.locate(UserDefinedModelService.class);
BasicDocModel docModel = modelService.newUserDefinedModel(BasicDocModel.class);

JsonService jsonService = ServiceLocator.locate(JsonService.class);
String newJSON = jsonService.convertToString(docModel);

Once deployed, UDMs are visible in the Vault UI from Admin > Configuration > User-Defined Models.