Extending Data Objects

All primary objects (subscriber, group, device, and user) and product offers, bundles, purchased offers, and purchased bundles can be extended with a private object type using the Attr parameter in REST calls.

You can create private objects that extend base objects with additional information by using the create_config.py script. The process involves creating a custom MATRIXX Data Container (MDC), for example, MySubscriberObject, to hold the additional data. This creates two MDCs in MATRIXX Engine: an internal MySubscriberObject object, which is stored in the in-memory database, and an external representation that has the same name but with the word Extension appended to it. In this example, the external object is called MySubscriberObjectExtension. This is the object that is exposed through the SubMan API and the one you specify when making API calls. The API automatically takes care of any mapping between the internal and external representations.

The following information is important when dealing with extended objects:

You must create a private object that extends a base object using the create_config.py script before extending a base object using REST calls.
When changing an object type, the extension type in the request message must correspond to the actual in-memory object type. This data is contained in the Attr element. It is important to note that the REST request XML documented in this guide specifies a generic Extension object in the Attr element, for example, MtxSubscriberExtension. You must replace this value in the input XML with the actual name of the external subscriber extension, for example, MySubscriberObjectExtension.
When changing an object, any inherited fields in the extension that contain values overwrite the corresponding fields in the in-memory instance. If the fields do not have values, the in-memory values are left unchanged.
You can revert a private object to its original type by modifying the Attr parameter with the base extension type.

When an object type is changed, all fields inherited from the common base class are retained. For example, consider the scenario where the MtxSubscriberObject type is extended with a MySubscriberObjectExtension object with the following fields:

Birthday
Age

Two additional subscriber objects are created that extend MySubscriberObjectExtension, each with one field:

SilverSubscriberObjectExtension
- CompanyName
GoldSubscriberObjectExtension
- CorporateId

Using the MtxRequestSubscriptionCreate REST API, the following subscriber is created:

<MtxResponseSubscriber>
    <ObjectId>0-1-5-13326</ObjectId>
    <Status>1</Status>
    <TimeZone>America/New_York</TimeZone>
    <Attr>
        <SilverSubscriberObjectExtension>
            <CompanyName>MyCompany</CompanyName>
            <Birthday>March 21, 1967</Birthday>
            <Age>46</Age>
        </SilverSubscriberObjectExtension>
    </Attr>
    <AdminGroupCount>0</AdminGroupCount>
    <AdminGroupCursor>0</AdminGroupCursor>
    <ParentGroupCount>0</ParentGroupCount>
    <ParentGroupCursor>0</ParentGroupCursor>
    <RouteId>1</RouteId>
    <Result>0</Result>
    <ResultText>OK</ResultText>
</MtxResponseSubscriber>

Note: SilverSubscriberObjectExtension inherits the fields from MySubscriberObjectExtension.

The subscriber type is later changed using the SubscriberModify REST API to GoldSubscriberObjectExtension with one field, CorporateId. All field values from MtxSubscriberObject and MySubscriberObjectExtension are retained and only the SilverSubscriberObjectExtension fields are lost.

After modifying the subscriber with the MtxRequestSubscriptionModify REST API, the subscriber object includes the following information:

<MtxResponseSubscriber>
    <ObjectId>0-1-5-13326</ObjectId>
    <Status>1</Status>
    <TimeZone>America/New_York</TimeZone>
    <Attr>
        <GoldSubscriberObjectExtension>
            <CorporateId>12345</CorporateId>
            <Birthday>March 21, 1967</Birthday>
            <Age>46</Age>
        </GoldSubscriberObjectExtension>
    </Attr>
    <AdminGroupCount>0</AdminGroupCount>
    <AdminGroupCursor>0</AdminGroupCursor>
    <ParentGroupCount>0</ParentGroupCount>
    <ParentGroupCursor>0</ParentGroupCursor>
    <RouteId>1</RouteId>
    <Result>0</Result>
    <ResultText>OK</ResultText>
</MtxResponseSubscriber>

Note: Only the CompanyName is lost. The Birthday and Age fields are unchanged because new values were not provided in the MtxRequestSubscriptionModify operation.

For information about adding custom MDCs, see the discussion about extending MATRIXX Engine functionality in MATRIXX Integration.