Import Source Orders That Include Coverages and Subscriptions

Import and update a source order that includes a covered item, coverage item, or subscription into Order Management.

This topic describes how to import or update source orders that include coverage. However, you can also use it to import subscriptions.

Import source orders that include coverage into Order Management.

1. Select a technology to import your source orders.

   • Web service in Oracle Application Development Framework (ADF).

   • Web service in Oracle Service-Oriented Architecture (SOA).

   • Business-to-business (B2B) messaging in Oracle Collaboration Messaging Framework.

   • File Based Import. For details, see Import Orders Into Order Management.

2. Make sure your source order includes the required attributes.

   Attribute	Value
   Document Reference Type	Specify the type. It creates a relationship between the covered item and the coverage item.
   Document Line Id	Line Id in the source transaction. This Id identifies the coverage item.
   Document Sub Line Id	Line Id in the source transaction. This Id identifies the coverage item. To purchase an item and apply coverage for it. At the same time. This subline can reside in the same source order. At some later time. This subline can reside in a closed order line from another sales order that you already imported.
   Document Id	Source order Id of the covered line.
   Document Number	Sales order number of the covered line.
   Document Line Additional Id	Line Id from the source transaction. This Id identifies the coverage for the root parent of a configured item.

   The import uses these attributes to establish a relationship between the coverage item and the covered item. The import process you use must map each of these attributes in the import payload of the source order to an attribute in a sales order in Order Management.

3. Make sure your source order includes a value for the Number of Billing Periods attribute for the coverage item.

4. Make sure your source order includes values for coverage item attributes, depending on whether the source order contains price details.

   Contains Price Details	Doesn't Contain Price Details
   Oracle Pricing won't price the item. Duration Extended Amount must contain a value, and this value must use the same currency that the order header uses. Contract Start Date must contain a value. Values for Duration, Period, and Contract End Date can be empty.	Oracle Pricing will price the item. Each of these attributes must contain a value. Duration Period Contract Start Date

5. Verify settings in the Product Information Management work area.

   • Make sure you set up the Enable Contract Coverage attribute and Sales Product Type attribute so they support the covered item. For details, see Set Up Coverages for Sales Orders.

   • To specify a subscription item, set Sales Product Type to Subscription. To use a subscription as a covered item, enable Contract Coverage for the subscription.

     A subscription is similar to a coverage item. It includes a Duration, Period, Contract Start Date, and Contract End Date. In general, the rules that apply when you import a coverage item also apply when you import a subscription. For details, see Set Up Subscriptions for Sales Orders.

6. Set the values for duration and period differently according to your set up.

   Service Duration Type in Product Information Management	Description
   Fixed	Make sure the Duration and Period in the source order match the values you set for Duration and Period in Product Information Management.
   Open Ended	If you import a source order that includes a coverage item, and if the coverage item doesn't include price details, then make sure the import includes values for Duration and Period.

7. Make sure the value of the coverage quantity equals the value of the covered quantity.

8. Make sure the value of the coverage UOM equals the value of the covered UOM.

9. If the coverage item covers a covered item that Order Management already submitted to order fulfillment, then make sure the status of the covered item is Closed.

10. Examine your import payload. Make sure the document references that identify the coverage line map to only a single covered line.

    One coverage line can cover only one covered line. A coverage line must not cover more than one covered line.

Import Date and Time

As an option, specify the time stamp for the contract start date and the time stamp for the contract end date for the coverage or subscription. The time stamp includes the date and time of day.

• If you import the start time stamp, duration, and period, then Order Management uses these values to automatically calculate the end time stamp for you. Order Management will set the end of day to 23:59:59, UTC (Coordinated Universal Time).

• If you import the start time stamp and the end time stamp, then Order Management uses these values to automatically calculate the duration and period.

For example, use REST API to import the contract duration, start time stamp, and end time stamp. For details and examples, go to REST API for Oracle Supply Chain Management Cloud, expand Order Management, then click Sales Orders for Order Hub.

This example payload imports the OAL_EW_2Y_VAR warranty with.

• A duration of 2

• Period of 0zE

• Contract start time stamp of 2019-12-13T19:51:49+05:30

• No value for the end time stamp

Note

• Import your time stamp in UTC.

• You can include an offset from UTC. For example, 2019-12-13T19:51:49+05:30 includes an offset of +05:30.

• The Order Management database stores time stamp values in UTC. The Order Management work area displays them in UPTZ (User Preference Time Zone). For details, see Time Zone Differences in Order Management.

• Use a whole number for the duration. Don't include a decimal value.

Use different attributes for different technologies.

Technology	Attributes
Sales Orders for Order Hub REST API or an Application Development Framework (ADF) web service.	Use the ContractStartDateTime and ContractEndDateTime attributes to import your time stamps for the current release. Use the ContractStartDate and ContractEndDate attributes for earlier releases. Use the ServiceDuration attribute to import the duration of a coverage or subscription. Use the ServiceDurationPeriodCode attribute to import the period of a coverage or subscription.
SourceSalesOrderImportTemplate FBDI template.	Use these attributes. Contract Start Date Contract End Date Service Duration Service Duration Code

Import Coverage with Configured Items That You Already Priced

If the source order contains price details for a configured item, and if you set each of these attributes in the source order to Y:

• Freeze Price

• Freeze Shipping Charge

• Freeze Tax

Then make sure the input payload includes coverage for each configure option that you enable for contract coverage.

If you set the Enable Contract Coverage attribute to Y on the Edit Item page in the Product Information Management work area, then the configure option is enabled for contract coverage.

Make sure your import does these validations:

• If the source order doesn't contain a coverage for each configure option, then reject the source order.

• If the coverage quantity and the UOM for each configure option don't match the line quantity and UOM for the covered item, then reject the source order.

Make sure it does these validations for each configure option that's enabled for contract coverage.

For details, see Pricing for Covered Items.

Import Coverage with Configured Items That You Haven't Priced

If the source order doesn't contain price details, and if you set any of these attributes in the source order to N:

• Freeze Price

• Freeze Shipping Charge

• Freeze Tax

Then Oracle Pricing will price it.

Note

• The source order must include coverage only for the configured item that's the root parent, and not for each configure option.

• If you enable the configure option for contract coverage, then your import process must create a coverage line for each configure option. Each configure option can be an option class or option item.

• If the input payload contains a coverage for the root parent and also for one or more configure options, then your import must reject the source order.

Import Coverage That Includes a Return

You can import a covered item that includes a return.

• You can keep the covered item and return only the coverage item. Make sure your import payload includes only the return lines for the coverage item.

• If the Contract End Date of the coverage line happens before the return date of the coverage line, then you can't return a coverage line.

Your return must include these details:

• The status on the covered line and on the coverage line are each Closed.

• Return quantity is greater than zero.

• Return quantity doesn't exceed the quantity that's available to return. For example, if the sales order included a quantity of 10, and if you already returned a quantity of six, then the return quantity can't exceed four.

• The return coverage line must have the Original_Sales_Order document reference type.

• The covered line must have the Source_Coverage_Covered_Association document reference type.

Note these points when you return a covered item, depending on whether the source order contains price details:

Contains Price Details

Doesn't Contain Price Details

If Oracle Pricing doesn't price the item, then you can return the coverage item that covers the covered item. Make sure your import payload includes these details. The quantity and UOM of the coverage line equal the quantity and UOM of the covered line. For example, assume a sales order includes a quantity of 5 for the covered item and a quantity of 5 for the coverage item. If the return includes a quantity of 3 for the covered item, then make sure the coverage line in the return includes a quantity of 3. Adds the returned quantity to the quantity that's available. Includes return charges.

If Oracle Pricing prices the item, then the import payload can specify to return the covered item and the coverage lines. Make sure your import payload includes the return line for the covered item. Oracle Applications will create the return lines for the coverage lines.

If your import payload returns only the coverage item, then note these points:

• The quantity for the coverage line must equal the total returnable quantity of the covered line. Your import payload can't return only part of the returnable quantity.

• The coverage return UOM in the import payload must equal the covered line UOM.

• If the source order contains price details, then the import payload must include the return charges.

Update Coverages and Subscriptions Through Web Services

Use attributes in the FulfillmentResponseService payload to update contract dates.

• ContractStartDate

• ContractStartDateTime

• ContractEndDate

• ContractEndDateTime

Note

If You Import	Description
Only the start date.	Order Management uses the duration and period on the fulfillment line to calculate the contract end date.
Contract start date and contract end date.	If you set Service Duration Type to Variable when you set up the coverage, and if you import the contract start date and the contract end date, then Order Management recalculates the duration on the fulfillment line. However, the revised duration doesn't result in a price change on the fulfillment line. Learn about Service Duration Type. For details, see Set Up Coverages for Sales Orders.
Only the contract end date.	Order Management ignores the request and doesn't update any dates because it requires the contract start date.

If you use FulfillmentResponseService to update contract dates, then make sure you specify the same contract dates in any subsequent updates you make to other attributes on the coverage line. If you don't specify contract dates in subsequent updates, then Order Management uses the Coverage Start Date parameter and the actual shipment date or actual delivery date to determine how to set the values for the contract dates. For details, see Manage Order Management Parameters.

Splitting Lines

You can't use a FulfillmentResponseService request to split:

• An order line that has a covered item, and then use the same request to update the contract dates on the coverage line that covers the covered item. Instead, use one request to split the line that contains the covered item, then send a subsequent request to update the coverage item.

• Only the coverage line. Order Management automatically processes the coverage line when it splits the covered line.

If Order Management already split a line, then you can't use Application Development Framework (ADF) to add a coverage to the line. You can use only the Order Management work area or REST API to add coverage to a split line.

For details about using FulfillmentResponseService, see Connect Order Management to Your Fulfillment System.

Import Billing Plans

If you import a billing plan, then make sure the PeriodicityCode attribute doesn't contain ONE TIME under the BillingPlans entity for the order line in your import payload.

Consider an example.

"shipToCustomer": [
  {
    "PartyId": 1006,
    "SideId": 1036,
  }
],
"lines": {
  {
  "SourceTransactionLineId": "CPQ_LINE_ID_001",
  "SourceTransactionLineNumber": "CPQ_LINE_NUM_001",
  "SourceTransactionScheduleId": "CPQ_SCH_ID_001",
  "SourceScheduleNumber": "CPQ_SCH_NUM_001",
  "ProductNumber": "CPQ_SCH_NUM_001",
  "InvoicingRule": "CPQ_SCH_NUM_001",
  "BillingTransactionTypeName": "CPQ_SCH_NUM_001",
  "PaymentTermsCode": "CPQ_SCH_NUM_001",
  "TransactionLineType": "Buy",
  "OrderedUOM": "Each",
  "PurchasingUOMCode": "Ea",
  "OrderedQuantity": 1,
  "ServiceDuration": 1,
  "ServiceDurationPeriodName": "YEAR",
  "ContractStartDateTime": "2020-10-01",
  "ContractStartEndDateTime ": "2021-09-30",
  "SubscriptionProfileName": "Subs_Profile",
  "ExternalPriceBookName": "CPQ_Price_List",
  "billingPlans": [
    {
      "BillingNumberOfPeriods": 12,
      "BillingPlanTypeCode": "PERIODIC",
      "PeriodicityCode": "MONTH",
    }
  ]
''charges" : [
  {
      "SourceChargeId": "C1-OT",
      "ApplyTo": "Price",
      "PriceType": "One_time",

Here we have "PeriodicityCode": "MONTH" in the billingPlans entity, which should work fine. But "PeriodicityCode": "ONE TIME" would fail.