Guidelines for Setting Up Extensible Flexfields in Order Management

Use these guidelines to help you set up an extensible flexfield in Oracle Order Management.

• Unlike a descriptive flexfield, you can add as many segments as you need to an extensible flexfield.
• Use the context to organize your business data into a concise section of the Order Management work area, such as a dialog.
• Organize your attributes into logical groups according to your display and usage needs.
• Consider where an extensible flexfield might be useful in the order capture and order fulfillment lifecycle.
• Integrate with another Oracle application. See Use Extensible Flexfields to Integrate Order Management with Oracle Applications.
• An extensible flexfield that you add on the order header is independent of an extensible flexfield that you add on the order line. Order Management doesn't communicate or transfer values between them even if you use the same name for each extensible flexfield. If you need dependence between them, then create an order management extension, and then specify dependence logic in the extension.

Create Segments and Contexts

Note

If You	Then
Create a new segment.	Use the same value for the Code attribute and the API Name attribute. This will simplify setup and maintenance. You use API Name throughout the setup, such as when you integrate with a web service, business rule, business intelligence, and so on. You can't modify Code or API Name after you create the segment.
Modify a segment that already exists.	Don't modify API Name. The flexfield's logic examines API Name. If it's empty, then the logic uses the value in Code, so it isn't necessary to specify a value in API Name. If you modify API Name, then your flexfield might fail with unexpected results at run time.

Note

• Enter a unique code, name, and description for each segment. The Order Management work area doesn't display these values, so use whatever nomenclature is most helpful to you during setup and maintenance.

• You must not enable the Translatable option on the context. For details, see Set Up Extensible Flexfields in Order Management.

Nomenclature

Make sure the Display Name attribute and the Code attribute for each context that you create begins with a letter and contains only letters, numbers, and these special characters:

Character	Description
	Single space
.	Period
,	Comma
-	Hyphen Don't use an em dash or en dash.
_	Underscore
"	Double quotation mark
:	Colon
/	Forward slash

Note

• Don't include more than one consecutive space character.
• Don't end the attribute's value with a space character.

If you encounter an incorrect alias error when you run the Publish Extensible Flexfield Attributes scheduled process, then make sure your context has the correct nomenclature.

Number of Attributes and Segments

The number of attributes and segments that you can add to the context depends on the data type that you set for the context:

Data Type	Number of Attributes You Can Add	Number of Segments You Can Add
Varchar	20	20
Number	10	5
Date	5	10
Time	5	10

You can add a maximum of 40 segments to each context.

Order Management doesn't limit how many contexts that you can add, but you must add only the minimum number of contexts that you need because each context can affect performance.

Identify Your Flexfield

You need to correctly identify your flexfield's attribute and context code in your payload whether you use REST API, file-based data import, or an order management extension. Assume you need to add an extensible flexfield that you use to store a status on the order line:

1. Add the SourceLineInfo context and Status segment to the Fulfillment Line Information extensible flexfield.

   For details, see Set Up Extensible Flexfields in Order Management.

2. On the Manage Order Extensible Flexfields page, search for the value.

   Attribute	Value
   Name	Fulfillment Line Information

3. In the search results, click the row that contains Fulfillment Line Information in the Name column, then click Actions > Download Flexfield Archive.

4. In the Confirmation dialog, click Download, then save the zip file to any folder.

   The file manager for your operating system opens. For example, if you're using Microsoft Windows, then Windows Explorer opens.

5. In your file manager, double-click 10008_DOO_FULFILL_LINES_ADD_INFO.zip, then expand it to the view folder.

   For example:

   C:\downloads\10008_DOO_FULFILL_LINES_ADD_INFO.zip\oracle\apps\scm\doo\processOrder\flex\fulfillLineContextsB\view

   The FulfillLineEffBSourceLineInfoprivateVO.xml file contains the extensible flexfield segment that you must reference.

6. Use an xml editor to open FulfillLineEffBSourceLineInfoprivateVO.xml.

7. Identify the values that you will need in your web service payload.

   • Search for the attribute name.

     <ViewAttribute Name="status" EntityUsage="FulfillLineEffEO" EntityAttrName="status" AliasName="status">

   • Search for the context code.

     <Property Name="FND_ACFF_EFF_CONTEXT_CODE" Value="SourceLineInfo"/>

Use Order Management Extensions

Note

• Include an If statement to make sure each context and segment that your extension references exists and contains a value. If you don't check for missing objects and empty values, then your extension might fail with unpredictable results.

• Use the getOrCreateContextRow method to create or update a value in an extensible flexfield. If the object doesn't exist, then getOrCreateContextRow creates it, so it isn't necessary to determine whether the object exists before you use this method to do an update. Only use getContextRow to get a row.

• Use Context Code when you reference the flexfield's context.

• Use API Name when you reference the flexfield's segment. If you don't specify API Name when you set up the flexfield, then use Segment Code but with underscores ( _ ) instead of spaces ( ).

• Your Groovy code must traverse the context and the segment to get all of the flexfield's data.

  Here's an example that uses a while statement to traverse all data.

  def complianceDetails = header.getOrCreateContextRow("ComplianceDetails");
  complianceDetails.setAttribute("_ComplianceReason", "This has been set by pre submit extension.");
  
  def lines = header.getAttribute("Lines");
  while( lines.hasNext() ) {
    def line = lines.next();
    def inventoryItemId = line.getAttribute("ProductIdentifier");
    def orgId = line.getAttribute("InventoryOrganizationIdentifier");
    def item = getItem(inventoryItemId, orgId);
    
    String hazardous = item.getAttribute("HazardousMaterialFlag");
    def packShipInstruction = line.getOrCreateContextRow("PackShipInstruction");
    
    if( "Y".equals(hazardous) ) {
        // get details for fulfill line context PackShipInstruction
        
        packShipInstruction.setAttribute("_ShippingInstruction", "Hazardous Handling Required.");
    } 
    
  }

Import and Integrate

You can update an extensible flexfield on a closed order line or closed sales order only in the Order Management work area. You can't do this through import, such as through file based data import, a web service, REST API, or Oracle Application Development Framework (ADF).

Use REST API

Go to REST API for Oracle Supply Chain Management Cloud > Order Management > Sales Orders for Order Hub > Create Sales Orders, then scroll down to examine the examples. They all describe how to import an extensible flexfield.

Example	Description
19	Create and submit a sales order that has a flexfield on the order header. Use Oracle Pricing to price it.
20	Same as 19 but the flexfield is on the order line.
21	Same as 19 but there's a flexfield on the header and another one on the line.
41	Add a new flexfield on the header of a sales order that already exists.
42	Same as 41, but update that flexfield.
43	Same as 41, but also add a new flexfield at the same time.
44	Add a new flexfield on the line of a sales order that already exists.
45	Same as 44, but update that flexfield.
46	Same as 45, but also add a new flexfield at the same time.
47	Same as 44, but also add a flexfield on the header.

Use File Based Data Import

Use these guidelines when you use the order import template to import data for an extensible flexfield:

• Assign each segment's Table Column attribute so it references the correct column in the order import template.

• Use the DOO_ORDER_HDRS_ALL_EFF_B_INT worksheet to capture details for order headers.

• Use the DOO_ORDER_LINES_ALL_EFF_B_INT worksheet to capture details for order lines.

• Use columns, such as ATTRIBUTE_CHAR1, to capture details for each attribute.

• Don't modify worksheet names or column names. Instead, add a comment.

• Add a comment in Excel to document your set up.

You can use with an extensible flexfield only with these entities:

• Header

• Order line

You can't add an extensible flexfield on the order line entity. You can add one only on the order header entity or the order line entity. The template uses the phrase DOO_ORDER_LINES, but it uses details that you add on the DOO_ORDER_LINES_ALL_EFF_B_INT worksheet to interact with extensible flexfields on the order line, not on the order line. See Import Orders Into Order Management.

This example illustrates how to set up the Compliance Info segment that references the ATTRIBUTE_CHAR1 column:

Use Web Services

Add your flexfield's details to the web service payload:

• Use the Receive Fulfillment Task Response Service web service with all task types. Use the DooTaskFulfillOrderResponseInterfaceComposite composite.

• Run the Publish Extensible Flexfield Attributes scheduled process.

• Copy extensible flexfield data from the log file that the scheduled process creates into the XSD file that contains your payload. Copy this data onto each object that needs flexfield data. This approach helps to keep your channel system synchronized with your set up in Oracle Order Management.

• Use the import service from Application Development Framework (ADF). Don't use the SOA (Service Oriented Architecture) import service.

This example payload copies one section of code from the log file into the XSD file:

See Guidelines for Using REST API, Web Services, and FBDI to Integrate Order Management.

Display Your Flexfield

If you want to display a flexfield directly on the order header, then you must use Visual Builder Studio:

For critical details, see the Create Order - Business Rules video. The flexfield discussion starts at 3:50.

Here's a summary:

1. Set up your flexfield in the Setup and Maintenance work area.
2. Open Visual Builder Studio. For details, see Access Visual Builder Studio.
3. Click Configure Fields and Regions.
4. Create a regular form rule.
5. Expand the Order Header entity.
6. Click the Hidden column on the additionalInformation element, then click Visible By Default.
7. Expand Global Data Elements and DOO_HEADERS_ADD_INFO under additionalInformation, then set all of their child elements to Always Hidden except for your flexfield. Make sure your flexfield is visible.
8. As an option, use the Conditions to specify when to display your flexfield. For example, display it only if the Business Unit attribute contains Vision Operations.
9. Remove any pop up blockers on your browser, then click Preview to make sure the flexfield displays as you expect it to.

10. If all looks good, click Publish at the top of the page.

If you want to display the flexfield on a dialog instead of directly on the header, then you don't need to use Visual Builder Studio. Just use the DOO_HEADERS_ADD_INFO category when you set up your flexfield in Setup and Maintenance. To access it at run time, click Additional Order Details on the header and view the Additional Order Information section of the New Sales Order dialog.

Display Flexfields on Order Lines

You must use Visual Builder Studio to display a flexfield on the order line. Do the same steps that you use to add a flexfield to the header except create a collection rule instead of a form rule, and expand the Order Line (Table) entity.

For background, see:

• Set up VB Studio to Extend Oracle Cloud Applications
• Extend SCM Redwood Application Pages Using Visual Builder Studio

Manage Change

Identify your requirements for change management. For example, figure out whether the orchestration process must compensate when you change the value in your flexfield and the action to take when you compensate, such as schedule, call Oracle Receivables, and so on.

Set up the orchestration process differently depending on whether the value that it references changes any flexfield or only a specific one:

To Compensate Value For. . .	. . .Enable the Use Flexfield Attributes Option . . .
Any extensible flexfield	On the header of the orchestration process definition.
A specific extensible flexfield	In the Change Management section of the orchestration process definition. Add it to the orchestration process step that references the flexfield. Also set up a compensation pattern on this step. Use the compensation pattern to specify the action to do, such as Cancel, Create, Update, and so on, depending on the value that changes. Your set up can send an update when a single value changes and skip sending an update when other values change. This approach provides more detailed control regarding the compensation that you do.

Here's an example compensation pattern:

pseudocode: 
If segment3 changes, then cancel task x, and then recreate task x. 
If segment4 changes, then do nothing.
If segment5 changes, then call an update service. 

For a detailed example, see Compensate Sales Orders That Change.

To ignore changes to all flexfield values, make sure Use Flexfield Attributes for each step in the Change Management section isn't enabled.

Change management ignores each change that you make to a flexfield's value at run time when it's on the order header.

Use Reports and Analytics

Modify Reports

You can use the Sales Order report when you create or view a sales order.

Add the flexfield's data to the report:

1. Install Oracle Analytics Publisher Desktop,

2. Use the Edit Sales Order Report action in Oracle Analytics Publisher. This action displays Sales Order Report in rich text format so you can modify it.

3. Right-click a field, then click Copy.

4. Use Oracle Analytics Publisher Properties to specify the source that the report uses to display data for the field. Use this format:

   <?context/segment?>

   where

   • context. Name of the flexfield's context.

   • / (forward slash). You must use the forward slash between context and segment.

   • segment. Name of the flexfield's segment.

   • You must use a set of question marks ( ?? ) to enclose context/segment.

   • You must use a set of angle brackets ( < > ) to enclose the question marks.

   Assume you set up a flexfield that uses Context1 to store details about trade compliance, and SegmentA to store the compliance description. Use this code:

   <?Context1/SegmentA?>

Modify Analytics

Oracle Transaction Business Intelligence (OTBI) provides analytic reporting. You can display flexfield data in OTBI.

Note

• Enable the BI Enabled option when you set up your flexfield.

• Run the Import Oracle Fusion Data Extensions for Transactional Business Intelligence scheduled process. This process updates OTBI so it displays your flexfield in area Subject Areas in OTBI. For details, see Overview of Flexfield Change Import.

• Add your flexfield from Subject Areas into a report in OTBI.

• OTBI uses this format:

  Category_Context

  For example:

  Additional Fulfillment Line Information_Additional Details1

  where

  • Additional Fulfillment Line Information is the category.

  • Additional Details1 is the context.

And Yet More Guidelines

• An extensible flexfield supports a one-to-many relationship between one entity and one or more attributes. You can use it to add more than one context sensitive segment.
• Don't delete a context. If you create a context, delete it, and then create another context with the same name, you will likely encounter a runtime error that prevents you from processing your sales orders. Instead, revise the context you already have, or create another one with a different name.

  If you must delete a context, then remove all references to the context before you delete it. Assume you create a context named SourceLineInfo and associate it with the Additional Fulfillment Line Information category. If you need to delete SourceLineInfo, then you must first remove the association between SourceLineInfo and Additional Fulfillment Line Information. Next, deploy and publish to remove SourceLineInfo from your environment.

  Avoid modifying or deleting contexts or segments after you deploy and publish to your production environment. If you must modify or delete, then you must make sure no sales orders refer to the context or segment, and you must deploy and publish again after you're done making your modifications.

If you add a flexfield to an order line, and if you use the Update or Close Sales Orders scheduled process to close the order line that the order line references at run time, then at run time you:

• Can't update the value in the flexfield on the order line.

• Can revise the sales order and update the value in the flexfield on the order line, but Order Management won't use the revised value when it processes the revision.

• Can update a flexfield on the order header regardless of the sales order's or the order line's status.

What Happens to Flexfields When I Cancel Order Lines During Revision?

If you cancel an order line on a draft revision, and if you have an extensible flexfield on that line, then Order Management doesn't keep the flexfield's value after you submit the revision. Assume you set up an extensible flexfield named Update Reason on the order line and you use it to indicate why you changed the quantity on the line when you revise an order. You set it up so you can select one of these values at run time:

1. Customer Request
2. Insufficient Supply
3. Damaged During Shipment

You revise the order, set the Update Reason to Customer Request, cancel the line, then submit the revision. You notice that the quantity is now zero but Update Reason is empty on the revision. This is expected behavior. If you're using the flexfield only to indicate a return reason, then we recommend you use the predefined Return Reason attribute instead.