4 Using OSM Security Callback

About Security Callback

OSM provides a callback interface that is designed to intercept order access from the following functions:

• GetOrder

• Web Service GetOrder

• Order Automation Context getOrder()

• XML API GetOrder.Request, GetNextOrderAtTask.Request, GetOrderAtTask.Request

• Opening the order from the Task web client Worklist and Query pages

• Worklist

• XML API WorkList.Request

• Query

• XML API Query.Request

• OrderDataHistory

• Task web client Order Data History page (clicking on view or node URLs in Order Editor)

• XML API GetOrderDataHistory.Request

The callback is called before sensitive order data is about to be retrieved or displayed to a user. The normal security authorization for the call being made remains in place and runs before this callback interface.

About the Security Callback Interface

The security callback interface (contained in the com.mslv.osm.security Java package) is implemented by a registered custom class which calls the defined method (single order or result set) and passes information about the order which has been exposed to the user. In the single order or result set method, the custom class can be passed either a single order or a result, depending on which interface it is invoked. For example, if you select multiple orders in a worklist, the security callback would be passed a result set of orders.

For more information about the security callback interface, install the OSM SDK and extract the OSM Javadocs from the OSM_home/SDK/osm7.w.x.y.z-javadocs.zip file (where OSM_home is the directory in which the OSM software is installed and w.x.y.z represents the specific version numbers for OSM). See OSM Installation Guide for more information about installing the OSM SDK.

package com.mslv.oms.security;

import java.util.Collection;

/**
 * The interface provides the callback to user defined custom code in which 
 * the external call accesses the order.
 *
 */
public interface OrderViewAccessProvider extends Callback {
/**
 * Called before the details of an order are retrieved for a user. This occurs 
   when an order is displayed in the order editor, or retrieved via APIs e.g. 
   GetOrder, GetWorklist, GetQuery, GetOrderDataHistory, GetOrderAtTask, 
   GetNextOrderTask (xmlapi only).
     * @param userId The user that accessing the order.
     * @param orderId OSM order ID.
     * @param cartridgeName The cartridge name that order belongs to. 
     * @param cartridgeVersion The cartridge version that order belongs to.
     * @param orderType The order type.
     * @param orderSource The order source.
     * @param view The view mnemonic.
     * @throws OrderViewAccessNotAllowedException This embeds any custom code 
       application exceptions. The exception to differentiate unexpected exception 
       that may be occurring in custom code.
     * Any exceptions other than OrderViewAccessException suppressed and logged by 
       OSM core.
     * @see OrderViewAccessNotAllowedException
*/
public void checkOrderAccess(String userId, String orderId, String cartridgeName, 
                             String cartridgeVersion, String orderType, 
                             String orderSource, String view)
                             throws OrderViewAccessNotAllowedException;

    /**
     * Invoked before a summary of an order is displayed for a user. This occurs before an order is returned on a worklist or query. Note that multiple order summaries may be passed through the supplied array. This allows the core to optimize invocations of this method to pass multiple orders at the same time.
     * @param userSummaryInfo
     *    The collection of Workgroups of the user who is accessing the order.
     * @param orderSummaryInfo
     *    The collection of order summaries accessed by the function.
     * @return order IDs 
          The collection of order IDs that need be filterd from the order list. If returns null or empty collection, Order and Service Management returns the whole list.
     * @throws OrderViewAccessNotAllowedException
     *    This may embed any custom code application exceptions. Order and Service Management core would deny the access to all orders if the exception is thrown. Other exceptions suppressed and logged by Order and Service Management core.
     * @see OrderViewAccessNotAllowedException
     */
Public Collection<String> checkOrderSummaryAccess
                            (UserSummaryInfo userInfo, 
                             Collection<OrderSummaryInfo> ordersInfo 
                             ) throws OrderViewAccessNotAllowedException;
}

Security Callback Sample

You can find the following sample in the installation's SDK/Samples/SecurityCallback directory.

import java.util.Collection;
import java.util.Map;
 
import org.apache.commons.logging.Log;
import org.apache.commons.logging.LogFactory;
 
import com.mslv.oms.security.OrderSummaryInfo;
import com.mslv.oms.security.OrderViewAccessNotAllowedException;
import com.mslv.oms.security.OrderViewAccessProvider;
import com.mslv.oms.security.UserSummaryInfo;
 
/**
 * The sample provides an example of security callback.
 * 
 */
 
public class MyViewAccessCallback implements OrderViewAccessProvider {
 
    private static final Log LOG = LogFactory.getLog(MyViewAccessCallback.class);
 
    /**
     * Invoked before the details of an order are retrieved for a user. This occurs when an order is displayed in the order editor, or
     * retrieved via APIs (e.g. GetOrder, GetWorklist, GetQuery, GetOrderDataHistory, GetOrderAtTask and GetNextOrderAtTask).
     * 
     * @param userId
     *            The user that acessing the order.
     * @param orderId
     *            Order and Service Management order ID.
     * @param cartridgeName
     *            The cartridge name that order belongs to.
     * @param cartridgeVersion
     *            The cartridge version that order belongs to.
     * @param orderType
     *            The order type.
     * @param orderSource
     *            The order source.
     * @param view
     *            The view mnemonic.
     * @throws OrderViewAccessNotAllowedException
     *             This embeds any custom code application exceptions. The exception to differentiate unexpected exception that may be
     *             occurring in custom code.
     * 
     * @see com.mslv.oms.security.OrderViewAccessProvider#checkOrderViewDetail(java.lang.String, java.lang.String, java.lang.String,
     *      java.lang.String, java.lang.String, java.lang.String, java.lang.String)
     */
    public void checkOrderAccess(final String userId, final String orderId, final String cartridgeName, final String cartridgeVersion,
            final String orderType, final String orderSource, final String view) throws OrderViewAccessNotAllowedException {
 
        if (LOG.isInfoEnabled()) {
            LOG.info("MyViewAccessCallback called on checkOrderViewDetail:" + "by:" + userId + " orderID:" + orderId + " cartridgeName:"
                    + cartridgeName + " cartridgeVersion:" + cartridgeVersion + " orderType:" + orderType + " orderSource:" + orderSource
                    + " view:" + view);
 
        }
 
    }
 
    /**
     * Invoked before a summary of an order is displayed for a user. This occurs before an order is returned on a worklist or query. Note that multiple order summaries may be passed through the supplied array. This allows the core to optimize invocations of this method to pass multiple orders at the same time.
     * @param userSummaryInfo
     *    The collection of Workgroups of the user who is accessing the order.
     * @param orderSummaryInfo
     *    The collection of order summaries accessed by the function.
     * @return order IDs 
          The collection of order IDs that need be filterd from the order list. If returns null or empty collection, Order and Service Management returns the whole list.
     * @throws OrderViewAccessNotAllowedException
     *    This may embed any custom code application exceptions. Order and Service Management core would deny the access to all orders if the exception is thrown. Other exceptions suppressed and logged by Order and Service Management core.
     * @see OrderViewAccessNotAllowedException
     */
    public Collection<String> checkOrderSummaryAccess(final UserSummaryInfo userSummaryInfo,
            final Collection<OrderSummaryInfo> orderSummaryInfo) throws OrderViewAccessNotAllowedException {
 
        if (LOG.isInfoEnabled()) {
            LOG.info("MyViewAccessCallback called on checkOrderViewSummary");
        }
 
        for (final OrderSummaryInfo order : orderSummaryInfo) {
 
            if (LOG.isInfoEnabled()) {
                LOG.info("MyViewAccessCallback called on checkOrderViewSummary" + " by:" + userSummaryInfo.getUserId() + " orderID:"
                        + order.getOrderId() + " orderHistID:" + order.getTaskInfo().getOrderHistId() + " cartridgeName:"
                        + order.getCartridgeName() + " cartridgeVersion:" + order.getCartridgeVersion() + " orderType:"
                        + order.getOrderType() + " orderSource:" + order.getOrderSource() + " orderState:" + order.getOrderState()
                        + " targetOrderState:" + order.getTargetOrderState() + " reference:" + order.getReference() + " priority:"
                        + order.getPriority() + " processStatus:" + order.getProcessStatus() + " orderCreationDate:"
                        + order.getOrderCreationDate() + " orderCompletedDate:" + order.getOrderCompletedDate()
                        + " expectedOrderCompletionDate:" + order.getExpectedOrderCompletionDate() + " expectedGracePeriodCompletionDate:"
                        + order.getExpectedGracePeriodCompletionDate() + " taskMnemonic:" + order.getTaskInfo().getTaskMnemonic()
                        + " taskState:" + order.getTaskInfo().getTaskState() + " taskStartDate:" + order.getTaskInfo().getTaskStartDate()
                        + " executionMode:" + order.getTaskInfo().getExecutionMode() + " expectedTaskCompletionDate:"
                        + order.getTaskInfo().getExpectedTaskCompletionDate());
 
            }
            final Map<String, String> flexHeadersWithValues = order.getFlexibleHeaders();
            if (LOG.isInfoEnabled()) {
                LOG.info("FlexibleHeaders in the form {(MnemonicPath=Value)} " + flexHeadersWithValues);
            }
 
        }
 
        return null;
    }
 
}