Example Custom Multi-Request REST Service

This example shows a custom multi-request service with a request and response. It creates a user, a subscription, and a device and purchases offers atomically. Additionally, it can provision group tiers.

This example multi-request service does the following:

Checks for the existence of a subscriber, device, and user. If one of the fields is missing, sends an error and stops.
Copies the user into the request array at slot 0.
Copies the subscription into request array slot 1.
Copies the device into request array slot 2.
Creates a new MtxRequestSubscriberAddDevice object and puts it into slot 3.
Populates the SubscriberSearchData field in the MDC of slot 3 with the object result from slot 1.
Populates the DeviceSearchData field of slot 3 with the object result from slot 2.
Creates a new MtxRequestUserAddSubscription object and puts it into slot 4.
Populates the SubscriptionSearchData field in the MDC of slot 4 with the object result from slot 1.
Populates the UserSearchData field of slot 4 with the object result from slot 0.
Populates the RoleArray field of slot 4 with the object created from FromJson or FromResource.
If:
- GroupBA, GroupRA, SubscriberOfferPurchase are present:
  - Copies GroupBA into slot 5.
  - Copies GroupRA into slot 6.
  - Populates the MtxRequestGroupAddMembership field of the slot 7 MDC with the results from the request of slot 5.
  - Creates a new object with the results of the request from slot 6 and puts it into the GroupArray field of slot 7.
  - Creates a new object with the results of the request from slot 1 and puts it into the SubscriberArray field of slot 8.
  - Populates the SubscriberSearchData field of the slot 4 MDC with the results from the request of slot 0.
  - Adds subscriptions to users.
- If GroupBA, GroupRA, and SubscriberOfferPurchase are not present, continues to evaluate the optional mappings until the MtxRequestMulti object is assembled.
The MtxRequestMulti object is completely assembled and is transmitted to the engine for execution. An MtxResponseMulti is produced and processing continues with the next step.
Copies the result from slot 0 into UserResponse.
Copies the result from slot 1 into SubscriptionResponse.
Copies the result from slot 2 into DeviceResponse.
Copies the result from slot 3 into SubscriptionResponse.
Copies the result from slot 4 into SubscriptionResponse.
Copies the optional mappings if present.

REST Service

The following is an example of a custom multi-request REST service.

<?xml version='1.0' encoding='UTF-8'?>
<MtxRestServices xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance' xmlns='http://www.matrixxsw.com/XML_Schema/rest_service' xsi:schemaLocation='http://www.matrixxsw.com/XML_Schema/rest_service http://www.matrixxsw.com/XML_Schema/rest_service.xsd rest_service.xsd ../rest_service.xsd'>
    <info>
        <class>acme</class>
        <filename>web/rsgateway/rest/acme.xml</filename>
        <date>2024-08-23T15:25:27</date>
    </info>
    <path_array>
        <path url='/acme/provision'>
            <service id='POST'>
                <name>acme_provision</name>
                <description>This service provisions a user, subscription, device, and optional groups.</description>
                <request>AcmeRequestProvision</request>
                <response>AcmeResponseProvision</response>
                <parameters>
                    <RequestParameterArray>
                        <request_param>
                            <description>Optional routing data used by the TRA to route this SubMan call to the correct engine.</description>
                            <name>TrafficRouteData</name>
                            <type>String</type>
                            <use>optional</use>
                        </request_param>
                    </RequestParameterArray>
                </parameters>
                <MetadataArray>
                    <metadata>
                        <name>mtx:result_filter</name>
                        <type>string</type>
                        <value>{}</value>
                    </metadata>
                </MetadataArray>
                <code_generation>
                    <mapping>readData</mapping>
                    <mapping>attachVersion 1</mapping>
                    <patch>route = setRoute(route)</patch>
                    <multi_request required_fields='User Subscription Device'>
                        <missing_fields>
                            <error id='2002'>You must specify a user, subscription and a device.</error>
                        </missing_fields>
	                    <input_mapping>
	                        <request_copy id='0'>User</request_copy>
	                        <request_copy id='1'>Subscription</request_copy>
	                        <request_copy id='2'>Device</request_copy>
                            <request_create id='3'>MtxRequestSubscriberAddDevice</request_create>
                            <mapping id='3'>buildSubscriberSearchMulti 1</mapping>
                            <mapping id='3'>buildDeviceSearchMulti 2</mapping>
                            <request_create id='4'>MtxRequestUserAddSubscription</request_create>
                            <mapping id='4'>buildSubscriptionSearchMulti 1</mapping>
                            <mapping id='4'>buildUserSearchMulti 0</mapping>

                            <!-- Showing two alternatives, fromJson or fromResource, for constructing objects out of json. -->
                            <mapping id='4'>setOrAppendField "RoleArray" fromResource("/com/acme/extension/Role1.json")</mapping>
                            <mapping id='4'>setOrAppendField "RoleArray" fromResource("/com/acme/extension/Role2.json")</mapping>
                            <!-- mapping id='4'>setOrAppendField "RoleArray" fromResource("/com/acme/extension/Role3.json")</mapping  -->
                            <mapping id='4'>setOrAppendField "RoleArray" fromJson("{\"$\":\"MtxRoleData\", \"PricingId\": \"3\"}")</mapping>

                            <optional_field_mappings>
                                <fields_present id='GroupBA GroupRA SubscriberOfferPurchase'>
                                    <request_copy id='5'>GroupBA</request_copy>
                                    <request_copy id='6'>GroupRA</request_copy>
                                    <request_create id='7'>MtxRequestGroupAddMembership</request_create>
                                    <mapping id='7'>buildGroupSearchMulti 5</mapping>
                                    <mapping id='7'>setOrAppendField "GroupArray" fromJson("{\"$\":\"MtxGroupSearchData\", \"MultiRequestIndex\": 6}")</mapping>
                                    <request_create id='8'>MtxRequestGroupAddMembership</request_create>
                                    <mapping id='8'>buildGroupSearchMulti 6</mapping>
                                    <mapping id='8'>setOrAppendField "SubscriberArray" fromJson("{\"$\":\"MtxSubscriberSearchData\", \"MultiRequestIndex\": 1}")</mapping>
                                    <request_copy id='9'>SubscriberOfferPurchase</request_copy>
                                    <mapping id='9'>buildSubscriberSearchMulti 1</mapping>
                                </fields_present>
                                <fields_present id='GroupBA GroupRA'>
                                    <request_copy id='5'>GroupBA</request_copy>
                                    <request_copy id='6'>GroupRA</request_copy>
                                    <request_create id='7'>MtxRequestGroupAddMembership</request_create>
                                    <mapping id='7'>buildGroupSearchMulti 5</mapping>
                                    <mapping id='7'>setOrAppendField "GroupArray" fromJson("{\"$\":\"MtxGroupSearchData\", \"MultiRequestIndex\": 6}")</mapping>
                                    <request_create id='8'>MtxRequestGroupAddMembership</request_create>
                                    <mapping id='8'>buildGroupSearchMulti 6</mapping>
                                    <mapping id='8'>setOrAppendField "SubscriberArray" fromJson("{\"$\":\"MtxSubscriberSearchData\", \"MultiRequestIndex\": 1}")</mapping>
                                </fields_present>
                                <fields_present id='GroupRA SubscriberOfferPurchase'>
                                    <request_copy id='5'>GroupRA</request_copy>
                                    <request_create id='6'>MtxRequestGroupAddMembership</request_create>
                                    <mapping id='6'>buildGroupSearchMulti 6</mapping>
                                    <mapping id='6'>setOrAppendField "SubscriberArray" fromJson("{\"$\":\"MtxSubscriberSearchData\", \"MultiRequestIndex\": 1}")</mapping>
                                    <request_copy id='7'>SubscriberOfferPurchase</request_copy>
                                    <mapping id='7'>buildSubscriberSearchMulti 1</mapping>
                                </fields_present>
                                <fields_present id='GroupRA'>
                                    <request_copy id='5'>GroupRA</request_copy>
                                    <request_create id='6'>MtxRequestGroupAddMembership</request_create>
                                    <mapping id='6'>buildGroupSearchMulti 6</mapping>
                                    <mapping id='6'>setOrAppendField "SubscriberArray" fromJson("{\"$\":\"MtxSubscriberSearchData\", \"MultiRequestIndex\": 1}")</mapping>
                                </fields_present>
                                <fields_present id='SubscriberOfferPurchase'>
                                    <request_copy id='5'>SubscriberOfferPurchase</request_copy>
                                    <mapping id='5'>buildSubscriberSearchMulti 1</mapping>
                                </fields_present>
                            </optional_field_mappings>
	                    </input_mapping>
	                    <output_mapping>
                            <response_copy id='0'>Null</response_copy>
                            <response_copy id='0'>UserResponse</response_copy>
                            <response_copy id='1'>SubscriptionResponse</response_copy>
                            <response_copy id='2'>DeviceResponse</response_copy>
                            <response_copy id='3'>SubscriptionResponse</response_copy>
                            <response_copy id='4'>SubscriptionResponse</response_copy>
                            <optional_field_mappings>
                                <fields_present id='GroupBA GroupRA SubscriberOfferPurchase'>
                                    <response_copy id='5'>GroupBAResponse</response_copy>
                                    <response_copy id='6'>GroupRAResponse</response_copy>
                                    <response_copy id='7'>GroupBAMemberResponse</response_copy>
                                    <response_copy id='8'>GroupRAMemberResponse</response_copy>
                                    <response_copy id='9'>PurchaseResponse</response_copy>
                                </fields_present>
                                <fields_present id='GroupBA GroupRA'>
                                    <response_copy id='5'>GroupBAResponse</response_copy>
                                    <response_copy id='6'>GroupRAResponse</response_copy>
                                    <response_copy id='7'>GroupBAMemberResponse</response_copy>
                                    <response_copy id='8'>GroupRAMemberResponse</response_copy>
                                </fields_present>
                                <fields_present id='GroupRA'>
                                    <response_copy id='5'>GroupRAResponse</response_copy>
                                    <response_copy id='6'>GroupRAMemberResponse</response_copy>
                                </fields_present>
                                <fields_present id='SubscriberOfferPurchase'>
                                    <response_copy id='5'>PurchaseResponse</response_copy>
                                </fields_present>
                            </optional_field_mappings>
                        </output_mapping>
	                </multi_request>
                </code_generation>
            </service>
        </path>
    </path_array>
</MtxRestServices>

Request Message

The following is an example of a request message.

{
  "User": {
    "$": "MtxRequestUserCreate",
    "ContactEmail": "[email protected]",
    "ContactPhoneNumber": "0012345",
    "ExternalId": "u42",
    "FirstName": "Sally",
    "Language": "en_US",
    "LastName": "Smith",
    "NotificationPreference": 3,
    "TenantId": "invisible",
    "UserId": "i41"
  },
  "Subscription": {
    "$": "MtxRequestSubscriptionCreate",
    "TenantId": "invisible",
    "ExternalId": "s42",
    "Name": "sallys sub",
    "BillingCycle": {
      "$": "MtxBillingCycleData",
      "BillingCycleId": 300
    }
  },
  "Device": {
    "$": "MtxRequestDeviceCreate",
    "Attr": {
      "$": "MtxMobileDeviceExtension",
      "AccessNumberArray": [
        "12345"
      ],
      "Imsi": "0012345"
    },
    "ExternalId": "d42",
    "TenantId": "invisible"
  },
  "GroupBA": {
    "$": "MtxRequestGroupCreate",
    "TenantId": "invisible",
    "ExternalId": "ba42",
    "Name": "BaGroup"
  },
  "GroupRA": {
    "$": "MtxRequestGroupCreate",
    "TenantId": "invisible",
    "ExternalId": "ra42",
    "Name": "RaGroup"
  },
  "SubscriberOfferPurchase": {
    "$": "MtxRequestSubscriberPurchaseOffer",
    "OfferRequestArray": [
      {
        "$": "MtxPurchasedOfferData",
        "CatalogItemId": 5
      }
    ]
  }
}