Customizing Fields and Validations
This section describes the metadata and semantics for supporting custom validations and custom fields in CloudPortal Business Manager. Often, service operators or customers may require the collection and management of additional custom fields fro tenants users, or subscriptions. This specification describes the metadata that a service operator provides to collect, validate, and manage such custom fields. Also, custom validation rules can be defined for all customer or service provider editable fields. These validation rules are provided by the service operator as part of customization in a file called citrix.cpbm.custom.common/src/main/resources/validation-constraints.xml.
Requirements:
- Services team should be able to define Custom Fields for Tenant, User, and Subscription in the Customization SDK.
- Services team should be able to define Custom Validation for the Custom Fields in the Customization SDK.
- Custom Field values are stored in the custom_fields table.
- Supported custom fields types are text, text-area, radio, checkbox, select, hidden.
Defining custom fields for customizable objects: Tenant, User, and Subscription
Addition of custom fields is supported using dynamic proxy. This makes it possible to access custom fields objects in UI as the first level field from customizable objects.
Backend:
You need to add the getter and setter of the field into the proxy customizable object.
All the proxy customizable objects are located at citrix.cpbm.custom.model/src/main/java/com/citrix/cpbm/access.
-package com.citrix.cpbm.access; import citrix.cpbm.custom.field.annotation.UniqueValue; public interface User extends UserEntity { public String getAlternatePhone(); @UniqueValue public void setAlternatePhone(String phone); } Frontend:
<definition name="tenant.custom.fields" template="/WEB-INF/jsp/tiles/shared/custom_fields_tenant.jsp"/>
Used when creating/editing a new tenant in CPBM.<definition name="user.custom.fields" template="/WEB-INF/jsp/tiles/shared/custom_fields_user.jsp"/>
Used when creating a tenant(for master user details) and while creating a new user in existing tenant.<definition name="subscription.custom.fields" template="/WEB-INF/jsp/tiles/shared/custom_fields_subscription.jsp"/>
Used when creating/editing a new tenant in CPBM.<definition name="user.custom.fields.myprofile.edit" template="/WEB-INF/jsp/tiles/shared/custom_fields_myprofile_edit.jsp"/>x
Used when editing an user in CPBM ('My Profile' section).
Examples for code to put in these jsps for the custom fields to be visible in UI are included as commented code in respective files.
Convention
The fieldName in jsps, validation-constraint.xml (referred by xml tag <getter name="<fieldName>">) and the getter/setter methods should be in accordance with the Java bean specification http://download.oracle.com/otn-pub/jcp/7224-javabeans-1.01-fr-spec-oth-JSpec/beans.101.pdf. See section 8.8 in the linked document related to "Capitalization of inferred names" which briefly outlines how names of properties are derived.
Annotations
As seen in the example, the custom field is annotated with @UniqueValue annotation.
- @UniqueValue: To mark value of custom field unique across all entities of this customizable object.
- @Default: To set a default value for the field. For example,
@Default(value="<defaultValue>")
- @Encrypt: To keep the value encrypted in the database.
- @Searchable: To add the custom field into the list of searchable fields in UI. This will then act as a filter for the listed customizable entites:
Configuring error messages for unique fields
The unique constraint is applied to custom fields as soon as the annotation placed in the Java proxy class. However one can customize the error message that is shown in UI upon violation of this constraint while creating/editing a custom entity.
Value needs to be unique for field {0} In above message '{0}' will be replaced by the field name.The message can be customized for tenant, user or subscription by adding following key in CustomApplicationResources.properties:
com.citrix.cpbm.custom.field.unique.value.message.<entityClassName>
For example, to edit the message for custom fields belonging to tenant, add following key:
com.citrix.cpbm.custom.field.unique.value.message.tenant
To modify the field name passed to error message (if you want to give user friendly name in UI instead of java field name), add following keys:
com.citrix.cpbm.custom.field.<entityClassName>.<javaFieldName>
For example, to edit alternate phones for tenants and users add:
com.citrix.cpbm.custom.field.tenant.alternatePhone and com.citrix.cpbm.custom.field.user.alternatePhone to CustomApplicationResources.properties.
Accessing the custom fields in code
Once you have added the custom fields into the proxy interface, you can access it in the code as follows:
com.citrix.cpbm.access.User user = (com.citrix.cpbm.access.User) CustomProxy.newInstance(new com.vmops.model.User()); user.setAlternatePhone("9886123456"); Frontend:
- Tenant: ${tenant.customFieldMap.get("tenant.custom.field.alternatePhone")}
- User: ${user.customFieldMap.get("user.custom.field.alternatePhone")}
- Subscription: ${${subscription.customFieldMap.get("subscription.custom.field.subscriptionName")}}
Assumptions in above example
- Tenant and User have custom fields configured as alternatePhone
- Subscription has custom field configured as 'subscriptionName'
- Tenant, user, and subscription have prefixes configured as 'tenant.custom.field', 'user.custom.field', and 'subscription.custom.field' respectively (Note that prefixes is present for compatibility with 1.4.x, you need not to be concerned with it in 2.x.x).
Adding custom field validation
<bean class="com.citrix.cpbm.access.Tenant"> <getter name="alternatePhone"> <constraint annotation="com.citrix.cpbm.validator.constraint.NotBlank"> <message>com.citrix.cpbm.validator.constraint.impl.NotBlankAlternatePhone.message </message> </constraint> <constraint annotation="org.hibernate.validator.constraints.Length"> <message>javax.validation.constraints.Size.message</message> <element name="min">6</element> <element name="max">15</element> </constraint> </getter> </bean>
Make sure that all the message codes used above are present in CustomApplicationResources.proeprties file.
| Column Name | Sample value |
|---|---|
| id | 1 |
| prefix | test.user.custom.field |
| name | test.user.custom.field.AlternatePhone |
| value | 9886123456 |
| entity_id | 9 |
| entity_type | User |
| encrypt | 00000000 |
| updated_at | 2013-07-13 22:15:57 |
| updated_by | 1 |
| created_at | 2013-07-13 22:13:08 |
| created_by | 1 |
| version | 0 |
Prefixes
Prefixes are useful to distinguish between custom fields with same name but belonging to different entities, for example, alternatePhone can be defined for tenant as well as user.
tenant.custom.field.prefix=test.tenant.custom.field user.custom.field.prefix=test.user.custom.field subscription.custom.field.prefix=test.subscription.custom.field
Comments