The following section identifies the steps needed to define a new REST call.

  1. Define an actor-chain component.

    When you define an actor-chain component, define it in the same module as the component it references. For example:

    /atg/commerce/custsvc/order/CommitOrderActor.properties
    $class=atg.service.actor.ActorChainService
    definitionFile=/atg/commerce/custsvc/order/commitOrderActor.xml

  2. Define the actor-chain definition XML file.

    It is best to define success and error URLs in the actor rather than on the client-side. You should also define a success and error URL per form handler. You can use nested actors to reference a shared error handler.

    <?xml version="1.0" encoding="UTF-8"?>
    <actor-template default-chain-id="commitOrder"
    xsi:noNamespaceSchemaLocation="http://www.atg.com/xsds/ActorChain.xsd"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <actor-chain id="commitOrder" transaction="TX_SUPPORTS">
      <form id="commitOrderFormHandler"
          name="/atg/commerce/custsvc/order/CommitOrderFormHandler"
          handle="commitOrder" var="commitOrderFormHandler">
        <input name="allowEmptyOrders" value="${param.allowEmptyOrders}"/>
        <input name="salesChannel" value="${param.salesChannel}"/>
        <input name="siteId" value="${param.siteId}"/>
        <input name="commitOrderErrorURL"
            value="/model/atg/commerce/custsvc/order/
            CommitOrderActor/commitOrder-error"/>
        <input name="commitOrderSuccessURL"
            value="/model/atg/commerce/custsvc/order/
            CommitOrderActor/commitOrder-success"/>
      </form>
    </actor-chain>
    <actor-chain id="commitOrder-success" transaction="TX_SUPPORTS">
      <actor id="success" name="/atg/commerce/custsvc/order/
          OrderConfirmationActor" chain-id="orderConfirmation"
          return-model-var="model">
        <output id="model" add-map-children="true" value="${model}"/>
      <actor>
    </actor-chain>
    <actor-chain id="commitOrder-error" transaction="TX_SUPPORTS">
      <component id="fh" name="/atg/commerce/custsvc/order/
          CommitOrderFormHandler" filter-id="full"
      <output id="concurrentUpdate" name="concurrentUpdate"
          value="${fh.concurrentUpdate}"/>
      <output id="order" name="order" value="${fh.concurrentUpdate ?
          fh.order : null}" filter-id="full"
    </actor-chain>
    </actor-template>

    When creating a form handler, it is best to define success and error chains the base module, for example DCS, and xml-combine success chain in the application module.

    Note that when you are creating an actor-chain component in development mode, it is best to disable the Dynamo session confirmation number. To do this, disable the enforceSessionConfirmation parameter in your local /atg/dynamo/service
    /actor/Configuration.properties
    file. Once you have finished testing the component, you can set the property back to use session confirmation. Refer to the
    Using Dynamo Session Confirmation Numbers section for further information.

  3. If required, create a success chain using xml-combining in the application module.

    For example, the following example, when xml-combined, will display an order confirmation after the order has been committed. Note that for form handlers, you should define success and error chains in the base module and create the xml-combined success chain in the application module:

    <actor-template default-chain-id="commitOrder">
    <actor-chain id="comittOrder-error" transaction="TX_SUPPORTS">
    </actor-chain>
    <actor-chain id="commitOrder-success">
      <actor id="success" name="/atg/commerce/custsvc/order/
          OrderConfirmationActor" chain-id="orderConfirmation"
          return-model-var="model"/>
        <output id="model" add-map-children="true" value="${model}"/>
      </actor>
    </actor-chain>
    </actor-template>

  4. Register the actor-chains in the ActorChainRestRegistry so that they are enabled for REST access.

    By default, no actors are registered. Actor-chains accessed from REST or from success and error ULRs must be registered in the application module. Actor-chains that are accessed only from nested actors do not need to be registered. Note that each chain ID should be registered separately.

    # /atg/rest/registry/ActorChainRestRegistry.properties

    registeredUrls+=\
      /atg/commerce/custsvc/order/CommitOrderActor/commitOrder, \
      /atg/commerce/cstsvc/order/CommitOrderActor/
          commitOrder-success, \
      /atg/commerce/custsvc/order/CommitOrderActor/
          commitOrder-error

  5. Define the Java servlet bean filters.

    Bean filters are shared across all actor calls. Use a separate filter ID if you need a specific view for a specific actor. It is best to define properties per class, as filtering will be applied to each class or interface in the class hierarchy. You can define filters for both repository items and wrapper classes for repository items.

    <bean name="atg.commerce.order.Order" default-filter="summary">
      <filter id="summary">
        <property name="commerceItems"/>
        <property name="priceInfo"/>
        <property name="totalCommerceItemCount"/>
      </filter>
      <filter id="full">
        <property name="commerceItems"/>
        <property name="creationTime"/>
        <property name="id"/>
        <property name="lastModifiedTime"/>
        <property name="paymentGroupCount"/>
        <property name="paymentGroups"/>
        <property name="priceInfo"/>
        <property name="profileId"/>
        <property name="relationships"/>
        <property name="shippingGroupCount"/>
        <property name="shippingGroups"/>
        <property name="siteId"/>
        <property name="stateDetailAsUserResource"/>
        <property name="taxPriceInfo"/>
        <property name="totalCommerceItemCount"/>
      </filter>
    </bean>

    Note that you can enable debugging when creating your filter by setting the loggingDebug attribute to true in the /atg/dynamo/service/filter/
    bean/BeanFilterService
    . This will provide a log of what is being filtered.

  6. Test your new REST call.

    When you have created your new REST call, you can test it using cURL. It is best to test success and the error conditions, as well as JSON or XML input and output types. For example, you can test the new Commit Order call using the following cURL:

    curl -L -v -b agent_cookies.txt -H "Content-Type: application/json"
    "http://localhost:8280/rest/model/atg/commerce/custsvc/order/
    CommitOrderActor/commitOrder {"orderId": {"orderId":
    "o99520004"}}"

    During your development and testing, you may want to disable the Dynamo session confirmation numbers, as discussed in the Using Dynamo Session Confirmation Numbers section. To disable the session confirmation numbers, set the enforceSessionConfirmation parameter in your local /atg/dynamo/service
    /actor/Configuration.properties
    file to false. Note that the following type of ambiguous error will occur when session confirmation is disabled:

HTTP Status 409 - Your session expired due to inactivity.
type - Status report
message - Your session expired due to inactivity.
description - The request could not be completed due to a conflict with the
current state of the resource.

Copyright © 1997, 2013 Oracle and/or its affiliates. All rights reserved. Legal Notices