External Segments
This topic explains external segments in Oracle Unity.
In this topic:
Introduction
Segments in Oracle Unity can be created either through the Oracle Unity segmentation canvas or through the API. The API provides more expressive power and flexibility, but also requires a working knowledge of JSON.
Important: To complete these steps, you will need the Instance admin user role assigned to you.
You can use the Oracle Unity application to create segments through the API by following the steps below.
Creating external segments
Creating external segments involves two tasks.
Step 1: Create the query
When creating the query, keep the following in mind:
- You will be creating two requests: mcpsqueries and objectsets.
- Creating the two requests allows you to nest segments within segments.
- The objectsets request will have a first-level .ObjectSet. The first-level .ObjectSet:
- Can only have one output attribute: MasterObject_ID. This is the base object for the segment. For example, if the base object will be MasterCustomer, then the output attribute will be MasterCustomer_ID.
- Must have a name and uniqueId and they must both match exactly.
- Both requests must have the second-level .ObjectSet and they must match exactly in both requests.
- The second-level .ObjectSet can have multiple output attributes.
To create the query:
- Navigate to the expert config page of Oracle Unity by going to the following URL: https://[your
- Use the drop-down lists to select POST and api-metadata. In the /metadata/ input field, enter mcpsqueries/.
- Copy and paste your query in the Request text area. Include a name, description, and uniqueId. The uniqueId and name need to be unique. Ensure that the uniqueId is unique across all MCPS queries.
- Click Run.
- Review the response in the Response text area and copy the uniqueId for the next steps.
- Clear the request to start a new one.
- Use the drop-down lists to select POST and api-metadata. In the /metadata/ input field, enter objectsets/.
- Copy and paste your query in the Request text area.
- Other than the uniqueId and the name, the rest of the payload must exactly match the one that was used in the previous call.
- Provide a new uniqueId that is different than the one used in the previous call.
- Use the same value you used as the uniqueId for the name value.
- Click Run.
- Review the response in the Response text area.
Here is a request example.
{
"MCPSQuery": {
"name": "External Segment",
"description": "Example description",
"uniqueId": 1600813677934,
"tenantId": 200000,
"operation": {
"ctype": ".SetOperation",
"name": "S_01647984564",
"distinct": true,
"operands": [
{
"ctype": ".ObjectSet",
"criteria": {
"ctype": ".Criteria",
"operator": "AND",
"operands": [
{
"ctype": ".Criteria",
"operator": "GREATER_THAN",
"operands": [
{
"ctype": ".FunctionAttribute",
"type": "CUSTOM",
"functionName": "LENGTH",
"attributes": [
{
"tableName": "S_01647984564",
"attributeName": "Email",
"atype": ".ReferenceAttribute"
}
]
},
{
"ctype": ".StaticAttribute",
"data": 0
}
]
},
{
"ctype": ".Criteria",
"operator": "NOT_NULL",
"operands": [
{
"ctype": ".ReferenceAttribute",
"tableName": "S_01647984564",
"attributeName": "Email"
}
]
}
]
},
"groupBy": [
],
"objectName": "MasterCustomer",
"outputAttributes": [
{
"atype": ".ReferenceAttribute",
"tableName": "S_01647984564",
"attributeName": "ID",
"alias": "MasterCustomer_ID"
}
],
"uniqueId": "cxunity_1614413571_T13677934",
"name": "S_01647984564",
"distinct": true,
"tenantId": 200000
}
],
"operator": "INTERSECTION",
"outputAttributes": [
{
"atype": ".ReferenceAttribute",
"alias": "MasterCustomer_ID",
"tableName": "S_01647984564",
"attributeName": "MasterCustomer_ID"
}
],
"tenantId": 200000
}
}
}
Here is a request example.
{
"tenantId": 200000,
"ctype": ".ObjectSet",
"name": "cxunity_1600813677934_T13677935",
"uniqueId": "cxunity_1600813677934_T13677935",
"outputAttributes": [
{
"atype": ".ReferenceAttribute",
"tableName": "S_01647984564",
"attributeName": "MasterCustomer_ID",
"alias": "MasterCustomer_ID"
}
],
"operand": {
"ctype": ".ObjectSet",
"criteria": {
"ctype": ".Criteria",
"operator": "AND",
"operands": [
{
"ctype": ".Criteria",
"operator": "GREATER_THAN",
"operands": [
{
"ctype": ".FunctionAttribute",
"type": "CUSTOM",
"functionName": "LENGTH",
"attributes": [
{
"tableName": "S_01647984564",
"attributeName": "Email",
"atype": ".ReferenceAttribute"
}
]
},
{
"ctype": ".StaticAttribute",
"data": 0
}
]
},
{
"ctype": ".Criteria",
"operator": "NOT_NULL",
"operands": [
{
"ctype": ".ReferenceAttribute",
"tableName": "S_01647984564",
"attributeName": "Email"
}
]
}
]
},
"groupBy": [
],
"objectName": "MasterCustomer",
"outputAttributes": [
{
"atype": ".ReferenceAttribute",
"tableName": "S_01647984564",
"attributeName": "ID",
"alias": "MasterCustomer_ID"
}
],
"uniqueId": "cxunity_1614413571_T13677934",
"name": "S_01647984564",
"distinct": true,
"tenantId": 200000
}
}
Step 2: Create the external segment
When creating the segment, consider what the segment will be used for.
Segment only used for campaigns
For this type of segment, the payload must include a description, uniqueId, and baseObjectId. The segment name will be automatically populated with the name of the MCPS Query that is referenced. The uniqueId must match the uniqueId provided in the previous call to mcpsqueries.
-
The segment will be visible in the list of segments on the Segments page.
-
The segment can be selected for campaign jobs and export jobs.
-
The segment can't be referenced from other segments.
-
The segment will not be visible in the list of segments from the My segments section on the segmentation canvas.
Here is an example.
{
"description": "Example description",
"uniqueId": 1587383768169,
"baseObjectId": "MasterCustomer"
}
Segment can be referenced by other segments
To create a segment that can be referenced by other segments and is visible in the My segments section on the segmentation canvas, you must add mcpsObjectsetId as an additional parameter in the payload. The value for mcpsObjectsetId must match the uniqueId value used in the previous call to objectsets. The uniqueId must match the uniqueId provided in the previous call to mcpsqueries. The segment name will be automatically populated with the name of the MCPS Query that is referenced.
Here is an example.
{
"description": "Example description",
"uniqueId": 1587383768169,
"mcpsObjectsetId": "cxunity_1600813677934_T13677935",
"baseObjectId": "MasterCustomer"
}
To create the external segment:
- Navigate to the expert config page of Oracle Unity by going to the following URL: https://[your
- Use the drop-down lists to select the following:
- POST
- cxunity
- segments
- In the input field, enter /external.
- Copy and paste your request in the Request text area with a description, uniqueId, baseObjectId, and mcpsObjectsetId (optional) for your external segment. Refer to the examples and types of segments above.
- Click Run.
- Review the response in the Response text area.
Here is a response example.
{
"id": "26ea3712-7baa-4f7f-b3b4-9efcc4290cf5",
"name": "External Segment",
"audienceStatus": "active",
"createdTS": "2020-04-15T04:15:02.235+0000",
"versionTS": "2020-04-15T04:15:02.235+0000",
"uniqueId": "1587383768169",
"description": "Example description",
"mcpsTenantId": "361",
"cxunityTenantId": "c948377b728641778fb57518977c18f9",
"createdBy": "ec1b711f42d94d71877c901f68d5f938",
"createdByLastName": "2",
"createdByFirstName": "cxuser",
"createdOn": "2020-04-15T04:15:02.235+0000",
"lastModifiedBy": "ec1b711f42d94d71877c901f68d5f938",
"lastModifiedByLastName": "2",
"lastModifiedByFirstName": "cxuser",
"lastModifiedOn": "2020-04-15T04:15:02.235+0000",
"segmentType": "external",
"source": "MCPS",
"touchedTS": "2020-04-15T04:15:02.235+0000",
"draft": false,
"mcps": true,
"template": false
}
After creating the external segment, it will be available from the Managing segments page.
Response notes
SegmentInvalidException is triggered if any of the following are not met:
- A unique segment name.
- Valid uniqueId or MCPS Query Id.
- A unique uniqueId.
External segments in Oracle Unity
Keep in the mind following for external segments in Oracle Unity :
- You cannot edit external segments from the Manage segments page.
- The following options are available for external segments from the Action menu (
) in the Manage segments page:- Rename
- Copy
- Delete
- Count
- Favorite
- When creating a new segment or editing a segment, you can access external segments from My segments under the Smart data tab. Learn more about Creating segments.
- You can add external segments inside segments you create on the segmentation canvas (a segment within a segment). Learn more about Creating segments.
Using materialized views with External Segments
External objects can also refer to Materialized Views in their queries, just like any other data object.
Definition of Materialized View: CUST_ORDER_JOIN_DW
{
"tenantId": 100066,
"name": "CUST_ORDER_JOIN_DW",
"versionTS": 1618234402174,
"active": true,
"createdTS": 1618234402174,
"materializedViewID": "CUST_ORDER_JOIN_DW",
"subQuery": {
"queryType": "mcpsQuery",
"value": {
"MCPSQuery": {
"tenantId": 100066,
"name": "AB_CART",
"versionTS": 1612888707031,
"active": true,
"lastModifiedBy": "mcps",
"createdBy": "mcps",
"createdTS": 1603374090309,
"uniqueId": "abcart",
"operation": {
"ctype": ".SetOperation",
"name": "AbCart",
"tenantId": 10,
"uniqueId": "abcart",
"operands": [
{
"ctype": ".ObjectSet",
"tenantId": 10,
"name": "C1",
"description": "C1",
"objectName": "Customer",
"uniqueId": "abcart_c1",
"outputAttributes": [
{
"atype": ".ReferenceAttribute",
"tableName": "C1",
"attributeName": "ID"
}
],
"distinct": false,
"objectJoin": {
"type": "LEFT",
"condition": [
{
"left": {
"atype": ".ReferenceAttribute",
"tableName": "C1",
"attributeName": "ID"
},
"right": {
"atype": ".ReferenceAttribute",
"tableName": "E1",
"attributeName": "CustomerID"
}
}
],
"targetSet": {
"ctype": ".ObjectSet",
"tenantId": 10,
"name": "E1",
"description": "E1",
"objectName": "Event",
"uniqueId": "abcart_e1",
"outputAttributes": [
{
"atype": ".ReferenceAttribute",
"tableName": "E1",
"attributeName": "CustomerID"
}
],
"distinct": false,
"criteria": {
"ctype": ".Criteria",
"operator": "AND",
"operands": [
{
"ctype": ".Criteria",
"operator": "EQUALS",
"operands": [
{
"ctype": ".ReferenceAttribute",
"tableName": "E1",
"attributeName": "Type"
},
{
"ctype": ".StaticAttribute",
"data": "AddToCart"
}
]
},
{
"ctype": ".Criteria",
"operator": "BETWEEN",
"operands": [
{
"ctype": ".ReferenceAttribute",
"tableName": "E1",
"attributeName": "EventTS"
},
{
"ctype": ".ParameterValue",
"identifier": "startWindow"
},
{
"ctype": ".ParameterValue",
"identifier": "endWindow"
}
]
}
]
},
"occurrence": {
"type": "LAST",
"partitionAttribute": {
"atype": ".ReferenceAttribute",
"tableName": "E1",
"attributeName": "CustomerID"
},
"limit": 1,
"count": 5,
"orderAttribute": {
"atype": ".ReferenceAttribute",
"tableName": "E1",
"attributeName": "EventTS"
}
},
"parameters": [
{
"identifier": "startWindow",
"type": "TIMESTAMP",
"data": {
"ctype": ".StaticAttribute",
"data": 1422748800000
}
},
{
"identifier": "endWindow",
"type": "TIMESTAMP",
"data": {
"ctype": ".StaticAttribute",
"data": 1448928000000
}
}
]
}
}
},
{
"ctype": ".ObjectSet",
"tenantId": 10,
"name": "C2",
"description": "C2",
"objectName": "Customer",
"uniqueId": "abcart_c2",
"outputAttributes": [
{
"atype": ".ReferenceAttribute",
"tableName": "C2",
"attributeName": "ID"
}
],
"distinct": false,
"objectJoin": {
"type": "LEFT",
"condition": [
{
"left": {
"atype": ".ReferenceAttribute",
"tableName": "C2",
"attributeName": "ID"
},
"right": {
"atype": ".ReferenceAttribute",
"tableName": "E2",
"attributeName": "CustomerID"
}
}
],
"targetSet": {
"ctype": ".ObjectSet",
"tenantId": 10,
"name": "E2",
"description": "E2",
"objectName": "Event",
"uniqueId": "abcart_e2",
"outputAttributes": [
{
"atype": ".ReferenceAttribute",
"tableName": "E2",
"attributeName": "CustomerID"
}
],
"distinct": false,
"occurrence": {
"type": "LAST",
"partitionAttribute": {
"atype": ".ReferenceAttribute",
"tableName": "E2",
"attributeName": "CustomerID"
},
"limit": 1,
"count": 1,
"orderAttribute": {
"atype": ".ReferenceAttribute",
"tableName": "E2",
"attributeName": "EventTS"
}
}
}
}
}
],
"operator": "EXCLUSION",
"distinct": false,
"outputAttributes": [
{
"atype": ".ReferenceAttribute",
"tableName": "C1",
"attributeName": "ID"
}
],
"joinConditions": [
{
"left": {
"atype": ".ReferenceAttribute",
"tableName": "C1",
"attributeName": "ID"
},
"right": {
"atype": ".ReferenceAttribute",
"tableName": "C2",
"attributeName": "ID"
}
}
]
},
"type": "DW"
}
}
},
"refreshMode": "ON_DEMAND",
"refreshType": "COMPLETE",
"stageCompletionTrigger": [
{
"value": "DW"
}
]
}
External Segment is using the MCPSQuery that is using the Materialized View: CUST_ORDER_JOIN_DW
{
"MCPSQuery": {
"tenantId": 100066,
"name": "example MV query",
"uniqueId": "exampleMV",
"operation": {
"ctype": ".SetOperation",
"name": "example",
"tenantId": 100066,
"uniqueId": "example",
"operands": [{
"ctype": ".ObjectSet",
"tenantId": 100066,
"name": "C1",
"description": "C1",
"objectName": "CUST_ORDER_JOIN_DW",
"uniqueId": "C1",
"outputAttributes": [{
"atype": ".ReferenceAttribute",
"tableName": "C1",
"attributeName": "ID"
}],
"distinct": false
}, null],
"operator": "INTERSECTION",
"distinct": false,
"outputAttributes": [{
"atype": ".ReferenceAttribute",
"tableName": "C1",
"attributeName": "ID"
}],
"joinConditions": []
}
}
}
We can now follow the rest of the steps for External Segment creation.