Fields and Fieldsets

Context Service ships with the following default or base fields and fieldsets:

• cisco.base.customer—Intended for use with customer type Context Objects.
• cisco.base.request—Intended for use with request type Context Objects.
• cisco.base.pod—Intended for use with pod type Context Objects (activities).
• cisco.base.comment—Intended for use with detail.comment type Context Objects.
• cisco.base.rating—Intended for use with detail.feedback type Context Objects.

You can use any fieldset with any type of Context Object.

By default, all fields are searchable. Change the value of the searchable property to specify if a field is searchable or non-searchable. Valid values are:

• No value—Default value. Indicates that the field is searchable.
• false—Specifies that a field is non-searchable.
• true—Specifies that a field is searchable.

Default or Base Fields and Fieldsets

Fields and fieldsets available out-of-the-box currently include:

Fieldset cisco.base.request

Fieldset cisco.base.pod

Fieldset cisco.base.customer

Fieldset cisco.base.comment

Fieldset cisco.base.rating

Fieldset cisco.base.escalation

Fieldset cisco.base.external.ids

Fieldset cisco.base.ccc.pod

Fieldset cisco.base.socialminer.pod

Fieldset cisco.base.ccx.pod

Fieldset cisco.base.ece.chat.pod

Fieldset cisco.base.ece.email.pod

Fieldset cisco.base.ece.request

Custom Fields and Fieldsets

In addition to the base fields and fieldsets built into Context Service, you can create custom fields and fieldsets specific to your data model. You can create up to 100 custom fields and 100 custom fieldsets for your organization.

You can also create custom fields with enumerated values by using Cisco Webex Control Hub to create fields with the single-select type. The single-select menu options that you define in Cisco Webex Control Hub correspond to the valid enumerations for the field.

Field Enumerations

Fields use the restriction property to restrict the possible field values further than the dataType constraints.

The Context Service SDK can only read fields with enumerated values. You cannot use the Context Service SDK to create or update fields with enumerated values. Use Cisco Webex Control Hub to create new fields with enumerated values or to update an existing field with enumerated values. For more information on managing fields in Cisco Webex Control Hub, see Manage Context Service Fields.

You can use get methods on fields to determine:

• If a field is enumerated.
• If an enumeration is set as visible or hidden in your application UI.
• The enumeration values.
• The enumeration translations.

restriction—Restricts the value of a field to the defined type.

type—Defines the type of restriction applied to the field as the string. For fields with enumerations, this value is Restriction.Types.ENUM.

EnumRestriction—Contains a map of enumeration values (String) to enumeration definitions (EnumValue). EnumRestriction contains a LinkedHashMap<String, EnumValue> and extends Restriction.

EnumValue—Provides the enumeration definition using:

• translations—Contains a map of ISO
  LanguageType
  
  codes to enumeration translations.
• active—Specifies if the enumeration value is selectable in the application UI (true) or if the enumeration value is hidden (false).

This example demonstrates using get methods on a field to determine the enumeration values, the enumeration translations, and the visibility of the enumerations in the application UI.

Copy/**
 * Get an enumValues from Field
 * @param contextServiceClient an initialized Context Service Client
 * @return a linkedhashmap with the String and the EnumValue
 */
public static LinkedHashMap<String, EnumValue> getEnumValues(ContextServiceClient contextServiceClient) {

    Field preferredLanguage = contextServiceClient.get(Field.class, "Context_Preferred_Language");
    com.cisco.thunderhead.dictionary.Restriction restriction = preferredLanguage.getRestriction();
    LOGGER.info("Restriction Type: ", restriction.getType());

    LinkedHashMap<String, EnumValue> enumValues = ((EnumRestriction)restriction).getEnumValues();
    EnumValue spanish = enumValues.get("es-ES");

    LOGGER.info("Spanish enum value: isActive: ", spanish.isActive());
    LOGGER.info("The English translation of the Spanish enum value:", spanish.getTranslations().get("en_US"));

    return enumValues;
}

For more information on returning enumeration information, see the

Create New Fields

Use the field() constructor to create a new field with these arguments:

• id—Field identifier specified as a string. The field ID must be unique with a maximum of 475 characters.

• classification—Security classification specified as a property of ElementClassification. Fields are classified as:

  • Unencrypted—Data is not encrypted and contains no personally identifiable information.
  • PII—Data is encrypted and contains personally identifiable information (PII).
  • Encrypted—Data is encrypted and contains no personally identifiable information.

• dataType—Data type of the field specified as a property of ElementDataType. Valid data types are:

  • String
  • Double
  • Integer (32-bit)
  • Boolean—The default value of a Boolean data type is false.

• publicallyAccessible—Flag specifying if the field is globally accessible by all organizations or just the organization that created the field. You cannot create new fields that are globally accessible. Setting publicallyAccessible to true throws an unauthorized error.

• translations—Specifies if the field is translated. Valid values are null for no translations or a map of ISO

  LanguageType
  
  codes and the translated texts that define the field name in the format Map<String, Object>.

• searchable—Specifies if the field is searchable. Set this value to true to allow search, and to false to make the field non-searchable. Fields are searchable by default if you do not set any value.

• locales—List of locals that this field can be searched on as a map of ISO

  LanguageType
  
  codes.

This example shows how to create a field where the value is specified in English and translated in French. The function takes an initialized contextServiceClient as the input parameter and returns the new field.

Copy/**
 * Create a field with translations.
 *
 * @param contextServiceClient an initialized Context Service Client
 * @return a field with translations
 */
public static Field createFieldWithTranslations(ContextServiceClient contextServiceClient){

    Map<String, Object> translations = new HashMap<>();
    translations.put(LanguageType.EN_US, "First Name");
    translations.put(LanguageType.FR, "Prenom");

    List<String> locales = new ArrayList<>();
    locales.add("en_US");
    locales.add("en_GB");
    locales.add("zh_CN");

    Field field = new Field("sdkExample_fieldOne", ElementClassification.PII, ElementDataType.STRING, false, translations, "true", locales);

    contextServiceClient.create(field);
    LOGGER.info("Created field: "+field.getId()+" with translations: "+translations.toString() + " and locales: " + String.join(", ", locales));

    return field;
}

Delete Fields

This example shows how to delete a field. The function takes an initialized contextServiceClient and the name of the field to be deleted as input arguments.

Copy/**
 * Delete the specified field.
 *
 * @param contextServiceClient an initialized Context Service Client
 * @param field a field
 */
public static void deleteField(ContextServiceClient contextServiceClient, Field field){
    contextServiceClient.delete(field);
    LOGGER.info("Deleted field: "+field.getId());
}

Create New Fieldsets

Use fieldset() to add one or more fields to a fieldset, with these arguments:

• ID—Fieldset identifier specified as a string. The fieldset ID must be unique with a maximum of 475 characters.
• Fields—Set of strings containing the fields to include in this fieldset. You must define fields before you can add them to a fieldset.

This example shows how to create two new fields and add them to a fieldset. The function takes an initialized contextServiceClient as the input parameter and returns the new fieldset with two new fields.

Copy/**
 * Create two new fields and add them to a fieldset.
 *
 * @param contextServiceClient an initialized Context Service Client
 * @param uniqueName
 * @return a fieldset
 */
public static FieldSet createFieldSet(ContextServiceClient contextServiceClient, String uniqueName){

    Field field1 = new Field("sdkExample_" + uniqueName + "fieldOne", ElementClassification.UNENCRYPTED, ElementDataType.STRING, false, null);
    contextServiceClient.create(field1);

    Field field2 = new Field("sdkExample_" + uniqueName + "fieldTwo", ElementClassification.UNENCRYPTED, ElementDataType.STRING, false, null);
    contextServiceClient.create(field2);

    FieldSet fieldset = new FieldSet("sdkExample_" + uniqueName + "fieldSet", new HashSet<>(Arrays.asList(field1.getIdentifier(), field2.getIdentifier())), false);
    contextServiceClient.create(fieldset);

    LOGGER.info("Created fieldset: "+fieldset.getId()+" with fields: "+fieldset.getFields().toString());
    return fieldset;
}

Update Fieldsets

You can update fieldsets to add new fields, delete fields, or modify fields.

In Cisco Webex Control Hub, after you add or remove fields to an existing fieldset, any changed fields are not immediately available in the Context Service SDK. For up to 30 minutes, you can not associate the modified fieldset with an object if the fieldset contains changed fields.

This example shows how to add a new field to a fieldset. The function takes an initialized contextServiceClient and the chosen fieldset as input parameters and returns the updated field.

Copy/**
 * Add a new field to the specified fieldset.
 *
 * @param contextServiceClient an initialized Context Service Client
 * @param fieldSet a fieldset to be updated
 * @return a fieldset
 */
public static FieldSet updateFieldSet(ContextServiceClient contextServiceClient, FieldSet fieldSet){

    Field field = new Field("sdkExample_fieldThree", ElementClassification.UNENCRYPTED, ElementDataType.STRING, false, null);

    Set<String> fields = fieldSet.getFields();
    fields.add(field.getIdentifier());
    fieldSet.setFields(fields);

    LOGGER.info("Updated fieldSet: "+fieldSet.getId()+" by adding field "+field.getId());
    return fieldSet;
}

Delete Fieldsets

Deleting a fieldset does not delete the fields included in that fieldset.

This example shows how to delete a fieldset. The function takes an initialized contextServiceClient and the name of the fieldset to be deleted as input arguments.

Copy/**
 * Delete the specified fieldset.
 *
 * @param contextServiceClient an initialized Context Service Client
 * @param fieldSet a fieldset
 */
public static void deleteFieldSet(ContextServiceClient contextServiceClient, FieldSet fieldSet){
    contextServiceClient.delete(fieldSet);
    LOGGER.info("Deleted fieldSet: "+fieldSet.getId());
}

Search Fields and Fieldsets

Use a search query to search fields and fieldsets.

These examples show how to search using a search query specifying ID and field or fieldset name. The functions take an initialized contextServiceClient and the search query as the input argument and return a list of fields or fieldsets that match the search query.

Copy/**
 * Search fieldsets using a search query.
 *
 * @param contextServiceClient an initialized Context Service Client
 * @param uniqueName
 * @return List<FieldSet> a list of fieldsets that match the search query
 */
public static List<FieldSet> searchFieldSet(ContextServiceClient contextServiceClient, String uniqueName){

    LOGGER.info("Constructing search query ...");
    SearchParameters params =  new SearchParameters();
    params.add("id","sdkExample_" + uniqueName + "fieldSet");

    LOGGER.info("Searching for fieldSet in ContextService based on query: " + params.toString());
    List<FieldSet> fieldsets = contextServiceClient.search(FieldSet.class, params, OR);
    for (FieldSet fieldset : fieldsets) {
        LOGGER.info("Found Field Set " + fieldset.getId());
    }
    return fieldsets;
}
/**
 * Search fieldsets using a search query.
 *
 * @param contextServiceClient an initialized Context Service Client
 * @param uniqueName
 * @return List<FieldSet> a list of fieldsets that match the search query
 */
public static List<FieldSet> searchFieldSet(ContextServiceClient contextServiceClient, String uniqueName){

    LOGGER.info("Constructing search query ...");
    SearchParameters params =  new SearchParameters();
    params.add("id","sdkExample_" + uniqueName + "fieldSet");

    LOGGER.info("Searching for fieldSet in ContextService based on query: " + params.toString());
    List<FieldSet> fieldsets = contextServiceClient.search(FieldSet.class, params, OR);
    for (FieldSet fieldset : fieldsets) {
        LOGGER.info("Found Field Set " + fieldset.getId());
    }
    return fieldsets;
}