Jump to: navigation, search

Data Segmentation

Important
Other Genesys applications such as ESJ or ChatServer don't currently support segmentation. This article is relevant to users developing their own applications.

The Segmentation concept

UCS 9.1 supports data segmentation on contacts and interactions. In the API the segment is referred to as SubscriberId, and in Cassandra and Elasticsearch schema it is stored in the Segment column/field. A segment exists only within a tenant—it can be considered as a "sub-tenant".

When segmentation is enabled, it allows the restriction of searches to a particular segment. Contact identification also follows segmentation, identify on the same email address will create different contacts for different segments. The segment is immutable—it is not possible to reassign the segment of a contact or an interaction. UCS also prevents mixing segments—a contact created in segment "A" can't be associated with an interaction in segment "B".

Accessing a contact or an interaction by its Id does not require a SubscriberId or Segment. UCS does not support authentication so it's not possible to prevent a client with an Id from accessing data from a particular segment. Filtering should be enforced on the application side. Note that SubscriberId/Segment is always a parameter and is never returned to the client application, even when using wildcards.

When segmentation is disabled or if a segment is not provided, the value will default to "not-applicable".

UCS Options

  • [subtenant]/enabled
    • Default value—false
    • Valid values—true, false
    • Changes take effect—Immediately
    • Description—Enables/disables support for segmentation.
  • [subtenant]/subscriberid-required
    • Default value—true
    • Valid values—true, false
    • Changes take effect—Immediately
    • Description—Specifies whether SubscriberId is required for segmentation. If the parameter is missing, UCS rejects the request.

Creating Segments

Segment are created dynamically on the General tab of the Transaction folder of a tenant. The segment's name must follow this format:

ContactCenterSettings.<name>


and the segment's type should be Attribute. The example below shows the creation of a Support segment:

DataSegmentAll.png

Using PSDK—Sample Java Code

This example assumes UCS is running with the option settings below:

  • [subtenant/enabled] = true
  • [subtenant/subscriberid-required] = false


final UniversalContactServerProtocol ucsClient = getPSDKClient();
    final int tenantId = 101;
 
    //Creating the first contact
    RequestIdentifyContact identifyContact1 = new RequestIdentifyContact();
    identifyContact1.setTenantId(tenantId);
    identifyContact1.setSubscriberId("Support"); //This is the first segment
    identifyContact1.setMediaType("email");
 
    KeyValueCollection fields1 = new KeyValueCollection();
    fields1.addString("EmailAddress", "buffy.summers@sunnydale.univ");
    fields1.addString("FirstName", "Buffy");
    fields1.addString("LastName", "Summers");
 
    identifyContact1.setOtherFields(fields1);
 
    EventIdentifyContact eventIdentifyContact1 = (EventIdentifyContact) ucsClient.request(identifyContact1);
    String contactIdSupport = eventIdentifyContact1.getContactId();
    contactIds.add(contactIdSupport);
 
    RequestGetAttributes getAttributes1 = new RequestGetAttributes();
    getAttributes1.setContactId(contactIdSupport);
    EventGetAttributes attributes1 = (EventGetAttributes) ucsClient.request(getAttributes1);
    System.out.println("First contact created:" + attributes1);
/*
    11:03:45.663 Trc 21125 [SvcSrvW-1  ] RequestLogger        <esp156Id1r1> Response:
      Id = esp156Id1r1
      Type = Response
      AppName = UCS
      AppType = UCS
      Service = OMContacts
      Method = IdentifyContact
      Parameters =
        FirstName [utf] = "Buffy"
        LastName [utf] = "Summers"
        EmailAddress [utf] = "buffy.summers@sunnydale.univ"
        ContactIdList [utf] = "1000AE9YfdHYpsPK"
        NumberOfContactsFound [int] = 0
        ContactCreated [utf] = "true"
        ContactId [utf] = "1000AE9YfdHYpsPK"
 */
 
 
    //Creating the second contact with the same attributes
    RequestIdentifyContact identifyContact2 = new RequestIdentifyContact();
    identifyContact2.setTenantId(tenantId);
    identifyContact2.setSubscriberId("VIP"); //This is the second segment
    identifyContact2.setMediaType("email");
 
    KeyValueCollection fields2 = new KeyValueCollection();
    fields2.addString("EmailAddress", "buffy.summers@sunnydale.univ");
    fields2.addString("FirstName", "Buffy");
    fields2.addString("LastName", "Summers");
 
    identifyContact2.setOtherFields(fields2);
 
    EventIdentifyContact eventIdentifyContact2 = (EventIdentifyContact) ucsClient.request(identifyContact2);
    String contactIdVIP = eventIdentifyContact2.getContactId();
    contactIds.add(contactIdVIP);
 
    RequestGetAttributes getAttributes2 = new RequestGetAttributes();
    getAttributes2.setContactId(contactIdVIP);
    EventGetAttributes attributes2 = (EventGetAttributes) ucsClient.request(getAttributes2);
    System.out.println("Second contact created:" + attributes2);
 
    /*
    11:03:45.722 Trc 21125 [SvcSrvW-3  ] RequestLogger        <esp158Id3r3> Response:
      Id = esp158Id3r3
      Type = Response
      AppName = UCS
      AppType = UCS
      Service = OMContacts
      Method = IdentifyContact
      Parameters =
        FirstName [utf] = "Buffy"
        LastName [utf] = "Summers"
        EmailAddress [utf] = "buffy.summers@sunnydale.univ"
        ContactIdList [utf] = "1000AE9YfdHYAPPq"
        NumberOfContactsFound [int] = 0
        ContactCreated [utf] = "true"
        ContactId [utf] = "1000AE9YfdHYAPPq"
  */
 
 
    Thread.sleep(1000); //Wait for Elasticsearch refresh, not needed when accessing data by Id or using identify requests
 
    RequestContactListGet contactListGet = new RequestContactListGet();
    contactListGet.setSubscriberId("Support");
    contactListGet.setTenantId(tenantId);
 
    SearchCriteriaCollection search = new SearchCriteriaCollection();
    SimpleSearchCriteria searchRequest = new SimpleSearchCriteria();
    searchRequest.setAttrName("ESQuery");
    searchRequest.setOperator(Operators.Equal);
    searchRequest.setAttrValue("AttributeValues.FirstName:buffy AND AttributeValues.LastName:summers"); //New simple Lucene syntax
 
    search.add(searchRequest);
    contactListGet.setSearchCriteria(search);
 
    EventContactListGet contactList = (EventContactListGet) ucsClient.request(contactListGet);
    System.out.println("Finds first contact only:" + contactList);
/*
    11:03:46.022 Trc 21125 [SvcSrvW-5  ] RequestLogger        <esp161Id5r5> Response:
    Id = esp161Id5r5
    Type = Response
    AppName = UCS
    AppType = UCS
    Service = OMContacts
    Method = ContactListGet
    Parameters =
      TotalCount [int] = 1
      PageSize [int] = 1
      ContactData [lst] =
        0 [lst] =
          Id [utf] = "1000AE9YfdHYpsPK"
          Attributes [lst] =
            TenantId [int] = 101
            FirstName [utf] = "Buffy"
            CreatedDate [utf] = "2019-02-05T10:03:45.462Z"
            LastName [utf] = "Summers"
            ModifiedDate [utf] = "2019-02-05T10:03:45.462Z"
            EmailAddress [utf] = "buffy.summers@sunnydale.univ"
      HasNext [utf] = "FALSE"
 */
 
    //SubscriberId is not mandatory to removing it will find both contacts, by default segment is set to "not-applicable"
    contactListGet.setSubscriberId(null);
    contactList = (EventContactListGet) ucsClient.request(contactListGet);
    System.out.println("Finds both contacts:" + contactList);
 
 
    //When segment is not required it is still possible to use it in regular queries including wildcard searches.
    //Segment column is analysed in ES using Keyword analyser, it means it is possible to use path in segments.
    //For example /emea/europe/france when inserting contacts and interactions making it possible to filter by /emea/europe/*
    contactListGet.setSubscriberId(null);
    searchRequest.setAttrValue("AttributeValues.FirstName:buffy AND Segment:Supp*");
    contactList = (EventContactListGet) ucsClient.request(contactListGet);
    System.out.println("Finds contact in Support segment:" + contactList);
 
 
    //Interactions
    RequestInsertInteraction insertInteraction = RequestInsertInteraction.create();
    InteractionAttributes interactionAttributes = new InteractionAttributes();
    interactionAttributes.setTenantId(tenantId);
    interactionAttributes.setSubscriberId("Support");
    interactionAttributes.setContactId(contactIdSupport);
    interactionAttributes.setTypeId("Inbound");
    interactionAttributes.setSubtypeId("InboundNew");
    interactionAttributes.setCanBeParent(true);
    interactionAttributes.setEntityTypeId(EntityTypes.EmailIn);
    interactionAttributes.setMediaTypeId("email");
    interactionAttributes.setStartDate(new Date());
    interactionAttributes.setStatus(Statuses.New);
    interactionAttributes.setSubject("Requesting assistance for customer billing");
 
    insertInteraction.setInteractionAttributes(interactionAttributes);
 
    EmailInEntityAttributes entityAttributes = new EmailInEntityAttributes();
    entityAttributes.setFromAddress("buffy.summers@sunnydale.univ");
    entityAttributes.setToAddresses("help@hunters.callcenter");
    entityAttributes.setMailbox("help@hunters.callcenter");
    insertInteraction.setEntityAttributes(entityAttributes);
 
    InteractionContent content = new InteractionContent();
    content.setText("Hi, I killed two vampires in one blow, should I bill them separately? Buffy.");
    insertInteraction.setInteractionContent(content);
 
 
    EventInsertInteraction eventInsertInteraction = (EventInsertInteraction) ucsClient.request(insertInteraction);
    String interactionId = eventInsertInteraction.getInteractionId();
    interactionIds.add(interactionId);
 
    Thread.sleep(1000); //Wait for Elasticsearch refresh
 
    RequestInteractionListGet interactionListGet = new RequestInteractionListGet();
    interactionListGet.setSubscriberId("Support");
    interactionListGet.setTenantId(tenantId);
 
    SearchCriteriaCollection searchIxn = new SearchCriteriaCollection();
    SimpleSearchCriteria searchIxnRequest = new SimpleSearchCriteria();
    searchIxnRequest.setAttrName("ESQuery");
    searchIxnRequest.setOperator(Operators.Equal);
    searchIxnRequest.setAttrValue("Text:buffy");
 
    searchIxn.add(searchIxnRequest);
    interactionListGet.setSearchCriteria(searchIxn);
 
    EventInteractionListGet ixnListGet = (EventInteractionListGet) ucsClient.request(interactionListGet);
    System.out.println("Finds the interaction from the first contact:" + ixnListGet);
 
/*
    14:38:27.686 Trc 21125 [SvcSrvW-7  ] RequestLogger        <esp162Id7r7> Response:
    Id = esp162Id7r7
    Type = Response
    AppName = UCS
    AppType = UCS
    Service = OMInteractions
    Method = InteractionListGet
    Parameters =
      PageSize [int] = 1
      InteractionData [lst] =
        0 [lst] =
          Id [utf] = "1000AE9YffYzRJYI"
 */
 
    //Using ES JSON DSL, UCS takes care of wrapping segment constraint, query requests text highlighting that will in ES metadata
    searchIxnRequest.setAttrValue("{\"query\":{\"wildcard\":{\"Text\":\"buff*\"}},\"highlight\":{\"fields\":{\"Text\":{}}}}");
    ixnListGet = (EventInteractionListGet) ucsClient.request(interactionListGet);
    System.out.println("Finds the interaction from the first contact:" + ixnListGet);
 
 
/* In below partial log, ES metadata found in ESQuery column contains the highlighted match of the wildcard query to substitute in a UI
    15:00:36.979 Trc 21125 [SvcSrvW-8  ] RequestLogger        <esp163Id7r8> Response:
    Id = esp163Id7r8
    Type = Response
    AppName = UCS
    AppType = UCS
    Service = OMInteractions
    Method = InteractionListGet
    Parameters =
      PageSize [int] = 1
      InteractionData [lst] =
        0 [lst] =
          Id [utf] = "1000AE9Yfgd5qXCM"
          Attributes [lst] =
            AllAttributes [lst] =[]
            ContactId [utf] = "1000AE9Yfgd4txXG"
    ...
            ESQuery [lst] =
    ...
              highlight [lst] =
                Text [utf] = "<em>Buffy</em>."
    ...
            Text [utf] = "Hi, I killed two vampires in one blow, should I bill them separately? Buffy."
            Subject [utf] = "Requesting assistance for customer billing"
            ToAddresses [utf] = "help@hunters.callcenter"
            TenantId [int] = 101
            Id [utf] = "1000AE9Yfgd5qXCM"
            Mailbox [utf] = "help@hunters.callcenter"
            ThreadHash [utf] = "136444583"
      HasNext [utf] = "FALSE"
      TotalCount [int] = 1
 */
 
    //Search again in the other segment finds no interaction
    interactionListGet.setSubscriberId("VIP");
    ixnListGet = (EventInteractionListGet) ucsClient.request(interactionListGet);
    System.out.println("No interaction found: " + ixnListGet);
 
    //UCS ensures that it is not possible to associate a contact and an interaction in different segments
    interactionAttributes.setSubscriberId("VIP");
    Message error = ucsClient.request(insertInteraction);
    System.out.println(error);
    //FaultString = 10:03:46.162 Server: UCS Msg: Contact '1000AE9YfdHYpsPK on tenant 101/VIP' not found in database
 
  }
This page was last modified on March 13, 2019, at 10:59.

Feedback

Comment on this article:

blog comments powered by Disqus