Modify a Device

Request to modify information in an existing device. If the request XML includes the extended objects field Attr, it must be of the same type used to create the device.

For information about extending an MDC, see the discussion about MDC and MDC field extension configuration in MATRIXX Integration.

Changing an IMSI or a Login ID

Using the device modify request API, you can change the IMSI for a mobile device or the login ID of a login device. If an IMSI or a login ID is already assigned to a device, an error is returned. When an IMSI or login ID is changed, the ProvisionedTime of the device is updated to the time of the modification.

To change a device IMSI, enter the new value in the Imsi field. To change a device login ID, enter the new value in the LoginId field.

Scheduling Life Cycle Transitions

Use the following modify APIs to schedule when the object status should transition:
  • MtxRequestSubscriberModify
  • MtxRequestGroupModify
  • MtxRequestDeviceModify
  • MtxRequestSubscriptionModify

Set the API field ScheduledStatusTransitionTime to specify an absolute future date and time when the status transition should take place. If you set a status (to transition to) and a ScheduledStatusTransitionTime, the status transition is scheduled. If you do not specify a ScheduledStatusTransitionTime, the status transition occurs immediately. If the new status to transition to is the same as the current status, an error is returned. To cancel an outstanding status transition request, set the IsCancelScheduledRequest field to "true".

The following object query APIs return the subscriber, group, and device object ScheduledStatusTransitionTime and IsCancelScheduledRequest field values, and the MtxPurchasedOffer objects (scheduled requests to suspend or resume).
  • MtxRequestSubscriberQuery
  • MtxRequestGroupQuery
  • MtxRequestDeviceQuery

Example: Modify a Device

In this example, TrainingDeviceObjectExtension extends MobileDeviceObject. The TAC_Code value in the extension overwrites the corresponding fields in the in-memory instance of the object.
URL 
PUT http://host:port/rsgateway/data/v3/device/<Device OID>
Request XML 
<MtxRequestDeviceModify>
      <ExternalId>1234567890</ExternalId>
      <DeviceType>0</DeviceType>
      <Attr>
        <TrainingDeviceObjectExtension>
          <TAC_Code>PM1225</TAC_Code>
        </TrainingDeviceObjectExtension>
      </Attr>
</MtxRequestDeviceModify>
Response 
<MtxResponse>
    <RouteId>1</RouteId>
    <Result>0</Result>
    <ResultText>OK</ResultText>
</MtxResponse>

Example: Modify a Device Status

In this example, querying the device reveals that the status is "1" indicating that the device is currently active. To delete the device, the status must be "2" indicating that it is inactive. The Status value in the extension overwrites the corresponding fields in the in-memory instance of the object.
URL 
PUT http://host:port/rsgateway/data/v3/device/0-2-5-1
Request XML 
<MtxRequestDeviceModify>
      <ExternalId>1234567890</ExternalId>
      <DeviceType>0</DeviceType>
      <Status>2</Status>
</MtxRequestDeviceModify>
Response 
<MtxResponse>
    <RouteId>1</RouteId>
    <Result>0</Result>
    <ResultText>OK</ResultText>
</MtxResponse>
After changing the status of the device to inactive, it can be deleted. For an example of how to delete a device, see "DeviceDelete".