Changestatus using the integration framework: Object structure service vs Standard service

Changing the status of a stateful Mbo is one of the most common actions performed by an external system or a peer software or a Web 2.0 client using MEA services. There are various ways to do this using the integration framework (sometimes referred to as the MEA) and we are going to discuss some of them here.

The most common way of changing status of a stateful Mbo is using Object structure services. Within Object Structure services there are a few ways we can invoke the status change action. For the purpose of this discussion we are going to use the PO Mbo. The same concept can be applied to any other stateful Mbo.

Creating the Mbo in the desired status:

In this process the sender would create the stateful Mbo in the desired state alongside creating related business data/objects. An example of such a request document is shown below.

<SyncMXPO ...>

     <MXPOSet>

        <PO>

          <PONUM>1095</PONUM>

          <STATUS>APPR</STATUS>

          <NP_STATUSMEMO>approve 1095</NP_STATUSMEMO>

          <STATUSDATE>2012-03-10T16:16:55-05:00</STATUSDATE>

          <DESCRIPTION>something different</DESCRIPTION>

           .....

           .....

           <POLINE>

                 ......

                 ......

                 <POCOST>

                          ......

                          ......

                </POCOST>

         </POLINE>

      </PO>

  </MXPOSet>

</SyncMXPO>

This request document will be processed as below.

1. create the PO 1095 in its default state ie WAPPR with all the attributes and related Mbos [like POLINE/POCOST] as specified in the document.
2. Save it [note it does not commit yet]
3. If the default status of the Mbo is different from the desired status as per the request document - reload the saved Mbo and invoke changeStatus on that mbo with the
   1. status from the request document [STATUS]
   2. memo from the request document [NP_STATUSMEMO]
   3. status date as the current system date [will ignore the value provided in the request document].
4. Save and commit.

Changing the status of the Mbo while creating/updating other business data in the Mbo:

In this process the sender would send a PO document which would contain the new status as well as the status memo [optional] and some related data - like data for related Mbos that needs to get created or updated or data for other attributes of the stateful Mbo. An example of such a request document is shown below. This one will modify the DESCRIPTION attribute of the PO 1095 as well as some line details like ORDERQTY etc along with .

<SyncMXPO ...>

    <MXPOSet>

        <PO action="Change">

           <PONUM>1095</PONUM>

           <STATUS>APPR</STATUS>

           <NP_STATUSMEMO>approve 1095</NP_STATUSMEMO>

           <STATUSDATE>2012-03-10T16:16:55-05:00</STATUSDATE>

           <DESCRIPTION>something different</DESCRIPTION>

           ..........

          <POLINE>

              ......

              <ORDERQTY>3.0</ORDERQTY>

              ......

          </POLINE>

        </PO>

    </MXPOSet>
</SyncMXPO>

This request document will be processed as below.

1. Load the PO 1095 and update the attributes and related Mbos [like POLINE/POCOST] as specified in the document.
2. Save it [note it does not commit yet]
3. If the status of the Mbo is different from the desired status as per the request document - reload the saved Mbo and invoke changeStatus on that mbo with the
   1. status from the request document [STATUS]
   2. memo from the request document [NP_STATUSMEMO]
   3. status date as the current system date [will ignore the value provided in the request document].
4. Save and commit.

Just change status of the Mbo without explicitly requesting the modification of any other attribute or related Mbos:

This process involves requesting a change of status only for the target Mbo. An example document is shown below.

<SyncMXPO ...>

     <MXPOSet>

         <PO>

             <NP_STATUSMEMO>approve 1097</NP_STATUSMEMO>

             <PONUM>1097</PONUM>

             <SITEID>BEDFORD</SITEID>

             <STATUS>APPR</STATUS>

             <STATUSDATE>2012-03-10T16:16:45-05:00</STATUSDATE>

             <STATUSIFACE>1</STATUSIFACE>

           </PO>

     </MXPOSet>
</SyncMXPO>

In this document note carefully the STATUSIFACE element. This is a non-persistent attribute and is available for every stateful Mbo. Setting that to 1 indicates that the requestor is only interested in modifying the status of the target Mbo. If the request document contains other attributes like DESCRIPTION or related Mbos - those would be silently ignored by the processing logic.

This request document will be processed as below.

1. Load the PO 1095 and invoke changeStatus on it with the following parameter values.
   1. status from the request document [STATUS]
   2. memo from the request document [NP_STATUSMEMO]
   3. status date as the current system date [will ignore the value provided in the request document].
2. Save it and commit.

So as you can see there is no way you can get a status date thats different than the current date of the system. Also this process will always invoke the changeStatus method with 3 parameters - status, statusdate and memo. So if you need to invoke another overloaded method for your specific case you would need to extend the StatefulMicSetIn class [or the sublclass if the Object Structure already has extended that base class] and override the changeStatus method. An example is shown below - it will call the 3 parameter method but will use the statusdate as specified in the XML.

public void changeStatus(MboRemote setMbo, String stat, String memo) throws MXException, RemoteException

{

String sDate = struc.getCurrentDataAsDate("STATUSDATE");

setMbo.changeStatus(stat,sDate,memo);
}

Point to note here is that you can use the struc variable [which is a reference to StructureData object] which holds a reference to the request XML document and can be used to access the XML request values.

The historical reason why the changeStatus in the ObjectStructure service is desgined to always use the current date for status date is because some Mbos do have business rules to reject changing status to a date prior to the current status date or sometimes even to a future date. So the processing logic uses a blanket rule to set the status date always to the current date. The Standard Services however can be leveraged to pass in the status date as we will see in the next section.

Another way to do this without requiring any customization is to use the Standard Services

Most stateful Mbo services [App services] will have a version of the changeStatus method available as a annotated Standard Service. For example the PO service has a method as below

@WebMethod

public void changeStatus(@WSMboKey(value="PO") PORemote po, String status, java.util.Date date , String memo) throws MXException, RemoteException

This implies this method changeStatus can be invoked as a standard service as shown below.

<pochangeStatus ....>

    <po>

        <PO>

          <PONUM>1095</PONUM>

          <SITEID>BEDFORD</SITEID>

       </PO>

    </po>

    <memo>approve 1095</memo>

    <status>APPR</status>

    <date>2012-03-10T16:16:55-05:00</date>
</pochangeStatus>

So each parameter is represented by an xml element and the URL for this service is as below:

http://host:port/meaweb/ss/<service name>

So for this example the URL to POST this XML document would be

http://host:port/meaweb/ss/PO

This request document will be processed as below.

1. Identify the service from the service name value in the URL and load the service.
2. Invoke the changeStatus method on the service with parameters as below.
   1. status from the request document [status]
   2. memo from the request document [memo]
   3. status date from the request document [date].
   4. The PO mbo from the keys provided in the <po> element.
3. Save it and commit.

So as you can see - here you can pass the statusdate that you want for your status change instead of just using the current date.

To see the list of all Standard Services and their methods you want to go to the Web Service Library application and start registering standard services. This will show you the list of available methods and for each method you can see the sample input and output XML structure showing how to invoke them and what to expect as response. Note you dont have to deploy them as web services as these can be invoked [just like Object Structure Services] using plain old XML/HTTP. Registering the services is a good way to see the sample XML request and response documents for the various methods available in these services.