Using Multi-Request Service Helpers

Search Helpers

Search helpers build searches that reference objects created elsewhere in a multi-request.

The search helpers use this syntax:

<mapping id='MultiRequestSlot'>Helper ObjectSourceSlot</mapping>

Where:

MultiRequestSlot is a number that specifies the multi-request slot.
Helper is one of the search helpers listed below.
ObjectSourceSlot is a number that specifies the slot where the object was created.

When defining a multi-request REST service, you can use the following search helpers:

buildDeviceSearchMulti — Builds device searches that reference devices created elsewhere in a multi-request. For example, to create a device search object in the DeviceSearchData field of a request in slot 3 of the array that references the device created in slot 2 of the array, declare the following:
```
<mapping id='3'>buildDeviceSearchMulti 2</mapping>
```
buildGroupSearchMulti — Builds group searches that reference groups created elsewhere in a multi-request. For example, to create a group search object in the GroupSearchData field of a request in slot 8 of the array that references the group created in slot 6 of the array, declare the following:
```
<mapping id='8'>buildGroupSearchMulti 6</mapping>
```
buildSubscriberSearchMulti — Builds subscriber searches that reference subscribers created elsewhere in a multi-request. For example, to create a subscriber search object in the SubscriberSearchData field of a request in slot 7 of the array that references the subscriber created in slot 1 of the array, declare the following:
```
<mapping id='7'>buildSubscriberSearchMulti 1</mapping>
```
buildSubscriptionSearchMulti — Builds subscription searches that reference subscriptions created elsewhere in a multi-request. For example, to create a subscription search object in the SubscriptionSearchData field of a request in slot 4 of the array that references the subscriber created in slot 1 of the array, declare the following:
```
<mapping id='4'>buildSubscriptionSearchMulti 1</mapping>
```
buildUserSearchMulti — Builds user searches that reference users created elsewhere in a multi-request. For example, to create a user search object in the UserSearchData field of a request in slot 4 of the array that references the subscriber created in slot 0 of the array, declare the following:
```
<mapping id='4'>buildUserSearchMulti 0</mapping>
```

Set or Append Field Helpers

The setOrAppendField helper modifies a field in a specified array slot. You can specify a value by specifying a field and value (such as a string or integer) or you can use a helper that creates a data container with a complex value.

To specify a field and value, the syntax is:

<mapping id='MultiRequestSlot'>setOrAppendField "NamedField" "FieldValue"</mapping>

Where:

MultiRequestSlot is the multi-request slot.
NamedField is the field name.
FieldValue is the field value.

In the following example, the Age field in slot 4 of the multi-request is set with the value 42:

<mapping id='4'>setOrAppendField "Age" 42</mapping>

In the following example, the HairColor field is set with the value Blonde:

<mapping id='4'>setOrAppendField "HairColor" "Blonde"</mapping>

To specify a field and complex value using helpers, the syntax is:

<mapping id='MultiRequestSlot'>setOrAppendField "NamedField" Helper("HelperArgument")</mapping>

Where:

MultiRequestSlot is the multi-request slot.
NamedField is the field name.
Helper is one of the following helpers and the syntax of HelperArgument is determined by Helper:
- fromJson — Reads in an object defined in JSON that is used in setOrAppendField. In the following example, the JSON object is used as the role definition that is set in the RoleArray field in slot 4 of the multi-request by setOrAppendField:
```
<mapping id='4'>setOrAppendField "RoleArray" fromJson("{\"$\":\"MtxRoleData\", \"PricingId\": \"3\"}")</mapping>
```
- fromResource — Reads in an object defined in a JSON resource that is used in setOrAppendField. The fromResource argument is the path to the resource. The JSON is similar to the fromJson example's embedded string. In the following example, the JSON object defined in Role3.json is used as the role definition that is set in the RoleArray field in slot 4 of the multi-request by setOrAppendField:
```
<mapping id='4'>setOrAppendField "RoleArray" fromResource("/com/acme/extension/Role3.json")</mapping>
```

Set or Append Value Helper

The setOrAppendValue helper modifies a field value in a specified array slot that is not a top-level field in the MDC. If the field is an array and is not an instance of ArrayList, the value is appended; otherwise, the value is set. If the field is not an array, the value is set.

To specify a field and value, the syntax is:

<mapping id='MultiRequestSlot'>setOrAppendValue "container" "pathExpression" "value"</mapping>

Where:

MultiRequestSlot is the multi-request slot.
container is the MDC.
pathExpression is the path to the field.
value is the value to set in the array slot.

In the following example, the MtxRequestGroupModify MDC DateOffset field is set to 10 and the value is set in slot 4 of the multi-request:

<mapping id='8'>setOrAppendValue "MtxRequestGroupModify" "BillingCycle.DateOffset" "10"</mapping>

Set Value Helper

The setValueAt helper sets a value in an array structure in a specified slot in the array.

To specify a field and value, the syntax is:

<mapping id='MultiRequestSlot'>setValueAt "container" "pathExpression" "slot" "value"</mapping>

Where:

MultiRequestSlot is the multi-request slot.
container is the MDC.
pathExpression is the path to the array field.
slot is the integer value of the slot in the array to write to.
value is the value to set in the array slot.

In the following example, the MtxRequestGroupModify MDC PostalCode field is set to 81201 in slot 2 of the array and the value is set in slot 4 of the multi-request:

<mapping id='8'>setValueAt "MtxRequestGroupModify" "ServiceAddress.PostalCode" "2" "81201"</mapping>