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:

  1. Services team should be able to define Custom Fields for Tenant, User, and Subscription in the Customization SDK.
  2. Services team should be able to define Custom Validation for the Custom Fields in the Customization SDK.
Note:
  • 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.

An example of how to add a custom field "Alternate Mobile number" to User object is given below:
   -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:

There are 4 tile views which are used various places where we create/edit tenant, user, or subscription:
  1. <definition name="tenant.custom.fields" template="/WEB-INF/jsp/tiles/shared/custom_fields_tenant.jsp"/>
    Used when creating/editing a new tenant in CPBM.
  2. <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.
  3. <definition name="subscription.custom.fields" template="/WEB-INF/jsp/tiles/shared/custom_fields_subscription.jsp"/>
    Used when creating/editing a new tenant in CPBM.
  4. <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.

Following 4 annotations are available to use::
  • @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.

If the message is not customized then the default message id used which is:
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:

Backend:
  com.citrix.cpbm.access.User user = (com.citrix.cpbm.access.User) CustomProxy.newInstance(new com.vmops.model.User());  user.setAlternatePhone("9886123456");

Frontend:

In case any of the custom fields are needed to show in tenant, user or subscription details UI, they can be accessed in following manner:
  1. Tenant: ${tenant.customFieldMap.get("tenant.custom.field.alternatePhone")}
  2. User: ${user.customFieldMap.get("user.custom.field.alternatePhone")}
  3. 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).

Create user with Custom Fields

Adding custom field validation

Custom field validation can be added into the validation-constraints.xml as described in Validation Rules. Example:
<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.

Sample contents of the custom_fields table:
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.

You can configure custom field prefixes by changing the following properties located at citrix.cpbm.custom.common/src/main/resources/custom.properties:
  tenant.custom.field.prefix=test.tenant.custom.field  user.custom.field.prefix=test.user.custom.field  subscription.custom.field.prefix=test.subscription.custom.field  
 
他にご質問がございましたら、リクエストを送信してください

コメント

 
Adding comment, please wait....

Provide Feedback on Article:

Subject:
Comments:*
Powered by Zendesk