Custom Flex Attributes

2 Custom Flex Attributes

Custom Flex Attribute Solution (CFAS) is a metadata driven framework that enables you to set up additional attributes on pre-enabled Merchandising entities without modifying base code.

The CFAS framework enables you to extend Merchandising entities to account for attributes that you require for your business, such as to support reporting or integration requirements. The entities that support flex attributes are:

Entity	Table Name
Address	ADDR
Class	CLASS
Cost Changes	COST_SUSP_SUP_HEAD
Cost Components	ELC_COMP
Deals	DEAL_HEAD
Department	DEPS
Diff Types	DIFF_TYPE
Item	ITEM_MASTER
Item Location	ITEM_LOC
Item Supplier	ITEM_SUPPLIER
Item Supplier Country	ITEM_SUPP_COUNTRY
Item Supplier Country Location	ITEM_SUPP_COUNTRY_LOC
Promotion Offers	RPM_PROMO_OFFER
Purchase Order	ORDHEAD ORDSKU ORDLOC
Partners	PARTNER
Return to Vendor	RTV_HEAD
Store	STORE
Suppliers	SUPS
Transfers	TSFHEAD
VAT Codes	VAT_CODES
Warehouses (physical and virtual)	WH

Once enabled for an entity, the flex attributes can be accessed using the More Actions menu in the relevant entity screen. The following figure illustrates how the option is displayed to users when attributes have been activated for purchase orders. The label displayed in the More Actions menu, in this case "Order Attributes", is also part of the CFAS configuration. The attribute screens do not have special security associated with them. If a user can edit the main entity screen, they will also be able to edit the flex attributes associated with the entity.

Figure 2-1 Illustration of a CFAS User Interface on Item Maintenance screen

In addition to managing the flex attributes in the Merchandising UI, these attributes can also be included on inbound integration if the source of the information is another application. And they are also published outbound so that they can be communicated to other dependent solutions.

Note:

When an entity record is deleted, the related CFAS attributes associated with that entity will also be deleted.

Defining Custom Flex Attributes

This chapter describes how flex attributes are organized so that you can plan for the best way to use the functionality to support your business and users. For example, it will be important to group together attributes that are being maintained by the same users. You should also consider structuring your attributes in such a way that you add more in the future as your business changes.

To help with the organization of attributes, a hierarchy is used, which consists of three levels: group set, group, and attribute. Group set is the name of the page, when the attribute screen is opened. Group level is shown as a container on the page, containing the attributes.

Group Sets

Group set is the highest level of the CFAS hierarchy. This is the level that is displayed in the Other Attributes menu where the attributes are accessed for each entity.

For each entity, you can define up to 99 attribute group sets. For each group set, you must define the following:

Display Order - The order in which the attribute group set will appear in the More Actions menu of the relevant entity.
View Name - The name that will be used for the database view that will be created for this group set. A view is a required information for each group set and is used for querying the data in Merchandising, as well as for integration from and to external solutions.
Staging Table Name - The name that will be used for the staging table that will be created for this group set. Although staging table information is optional, it is recommended that you provide staging table name to support data loading from integrated systems. Each group set can have one staging table.
Labels - Sets the business name for the group set. The label is the title that will appear in the Option menu for the entity when the attribute group set is accessed. You must set at least one label for the primary language for each group set you create. You can choose to create labels for more (alternate) languages, based on your business need.

Groups

Once you determine the attribute group sets needed for each entity, the next step is to determine how the attributes will be organized within these sets. The attributes themselves are organized into groups, which is the middle layer of the hierarchy. Although you can create as many attribute groups as you want for each group set, you can only have 25 attributes in each attribute group.

When planning the attribute groups, in order to properly validate and display the information in the screens, you must determine the following in addition to the attributes themselves:

Display Order - The order in which the attribute group set will appear in the Flex Attribute screen menu of the relevant entity.
View Name - The name that will be used for the database view that will be created for this group. Similar to the view defined at the group set level, this view will contain all attributes in the group. A view is a required information for each group and is used to facilitate querying attribute information for the group.
Labels - Sets the business name for the group and will be the name that appears on the screen. You must set at least one label for the primary language for each group set you create. You can choose to create labels for more (alternate) languages based on your business need.

Managing Entities, Group Sets and Groups

To add, update, or remove CFAS group sets or groups, select the template type of Administration from the Download Data screen and then the template Custom Flex Attribute Foundation. Click the Download button and when prompted, choose to either open the .ods file that is generated or save the file and open it separately in the spreadsheet application of your choice. There will be several tabs in the workbook that is generated that is used for managing the configuration of entities, group sets, and groups.

Note:

The Entity tab in this spreadsheet is for visibility only. New entities cannot be added and custom validation functions are not supported in a SaaS implementation.

Add a Group Set

To add a group set, select the action type of Create in an empty row in the CFA Group Sets tab in the workbook. Next, enter a unique number of up to 10 digits as the Group Set ID. Then, select the Merchandising base table name where the group set will be associated, the order you want it displayed in the Merchandising UI, and define the name you want to use for the view and staging tables that will be created for the group set when activated. The view and staging table names can be up to 30 characters in length. The columns for Qualifier Function, Validation Function, and Default Function should be left blank, as this functionality is not supported for SaaS implementations.

For each group set created, you will also need to define at least one label in your primary language. To do this, navigate to the CFA Group Set Labels tab in the workbook. In a blank row in the worksheet, select an action type of Create and then enter the group set ID you used for your group set. Then, select your primary language configured in Merchandising and enter the label name you want used in the Label field. You can create labels of up to 255 characters, but it is recommended to try not to exceed 60 characters for best display in the Merchandising screens. Repeat this process for all languages you require for your users.

Add a Group

To add a group, select the action type of Create in an empty row in the CFA Groups tab in the workbook. Next, enter a unique number of up to 10 digits as the Group ID. Then, select the group set where the group will be associated, the order you want it displayed in the Merchandising UI, and define the name you want to use for the view that will be created for the group when activated. The view name can be up to 30 characters in length.

For each group created, you will also need to define at least one label in your primary language. To do this, navigate to the CFA Group Labels tab in the workbook. In a blank row in the worksheet, select an action type of Create and then enter the group ID you used for your group. Then, select your primary language configured in Merchandising and enter the label name you want used in the Label field. You can create labels of up to 255 characters, but it is recommended to try not to exceed 60 characters for best display in the Merchandising screens. Repeat this process for all languages you require for your users.

Modify an Entity, Group Set, or Group

If you would like to update any details for an entity, group set, group, or record group, a similar process will be followed as that described above for creating new. First, download the spreadsheet, and then navigate to the tab where you would like to make your updates. In the tab where you are going to make your updates, select the action type of Update, and then correct the value in the spreadsheet. The following columns can be updated in each tab:

CFA Group Sets - Display Order; also, Group Set View Name and Staging Table Name prior to attributes being activated for the group set.
CFA Group Set Labels - Label
CFA Groups - Display Order; also, Group View Name prior to attributes being activated for the group.
CFA Group Labels - Label

Note:

Once attributes are active, the data that can be updated for each of these areas is limited to the following: labels and display order

Delete a Group Set

If you wish to remove a group set, navigate to the CFA Group Set tab in the spreadsheet and select the Delete action on the row of the group set, you wish to delete. You must also remove all labels that have been associated with that group set in the CFA Group Set Labels tab, by selecting the Delete action in the row associated with those labels. Group sets cannot be deleted if the attributes in the group set have been activated, however labels can be removed at any time.Group sets cannot be deleted if they are active.

Delete a Group

If you wish to remove a group, navigate to the CFA Groups tab in the spreadsheet and select the Delete action on the row of the group, you wish to delete. You must also remove all labels that have been associated with that group in the CFA Group Labels tab, by selecting the Delete action in the row associated with those labels. Groups cannot be deleted if the attributes in the group have been activated, however labels can be removed at any time.

Groups cannot be deleted if they are active.

Uploading Changes

For all actions defined above, once all the updates have been made to the data in the spreadsheet, save the file and close it. Then, return to the Merchandising screens and select Foundation Data > Upload Foundation Data from the main task list. In this screen, you'll again select the template type Administration and the template Custom Flex Attribute Foundation. This will generate a process description automatically, but this can be updated if desired. Lastly, select the Browse button and navigate to the directory where you saved the updated spreadsheet.

To review the status of the upload and check whether any errors occurred, select the Foundation Data > Review Status task from the main task list.

See also the Oracle Retail Merchandising Do the Basics User Guide section on "Download/Upload Data from Spreadsheets" for more information.

Attributes

Attributes are the bottom layer of the hierarchy. As mentioned above, you can have 25 attributes per group. Of those 25 attributes, up to 10 can to be character-based attributes, up to 10 can be number-based attributes, and up to 5 can be date attributes. You should consider this limit when planning the attributes to be included in each group.

To start specifying attributes, enter the entity you want to add the attributes to in the Application Table field, and then select the group set you previously created, then click Display Attributes. Next, select the Add option in the Actions menu or select the iconic button to begin adding attributes.

When creating attributes, you'll need to specify the following:

View Column Name - this value will be used to define the name of the attribute in the group set and group level views, as well as the group set level staging table.
Label - you will be required to add at least one label for the attribute in the primary language. But, labels for other languages can also be added.
Display Order - Indicates the order in which the attributes will appear in the attribute screen, from top to bottom. Attributes will appear in a single column on the screen.
Maximum Length - Indicates the maximum number of digits or characters that are allowed in the attribute, as well as the width of the attribute on the screen. You must specify this information for the attributes with Number or Varchar data types. This may not apply when you choose a List Item or Check box as the widget type. The maximum length for the List Item widget type is automatically set to 6 and the maximum length for the Check box widget type is automatically set to 1. For attributes with Number data type, you must enter the full length of the number. This includes the length to be allowed after the decimal point and positive/negative sign (if negative numbers are allowed). For example, if a particular attribute needs to allow for five digits with up to two digits after the decimal point and allow negative integers, you will need to specify the length as 9 (1 character for positive/negative sign, 5 digits before the decimal point, 1 decimal point, and 2 digits after the decimal point).

Note:

If you choose a record group, the maximum length will be automatically selected based on the value in the first column of the record group query.
Minimum/Maximum Value Allowed - Optional and applies to attributes with Number or Date data types. Indicates the minimum and maximum numeric or date value that can be entered for the attribute. For date widgets, the minimum and maximum definition is the number of days.

For example, if an attribute was added for an item that was Ecommerce Launch Date and the attribute was set like this:
- Lowest Allowed Val: 0
- Highest Allowed Val: 10
If the current VDATE is 12-SEP, then the min/max setup would not allow this attribute to be earlier than 12-SEP or greater than 22-SEP.
Data Type - Indicates the type of data for the attribute. You can set this as a Number, Varchar, or Date.
Widget Type - Indicates the type of the field that will appear for the attribute. You can select one of the following options:
- Text Item - used for both Number and Varchar data types. When used, the attributes field will appear as a text box on the screen.
- List of Values (LOV) - used for the Varchar data types only. A list of values appears as combo box LOV. If you choose to use this widget type, you must also specify a record group (see "Managing Record Groups").
- List Item - used for the Varchar data type only. When used, the attributes field will appear as a select one choice dropdown on the screen. If you choose to use this widget type, you must also specify a code type in the List Item Code Type field. The valid codes types are those that exist on the Codes and Descriptions table in Merchandising. For more information on Codes and Descriptions, see the Oracle Retail Merchandising Implementation Guide.
- Check box - used for Varchar data type only. When used, the attributes field will appear as a check box on the screen.
- Date - used for Date data type only. When used, the attributes field will appear with the calendar icon to allow users to select dates.
Required - Indicates whether the attribute will be considered as a mandatory field. Once an attribute is activated, it is recommended that you avoid changing this information.
Wrap Text - used for data type of VARCHAR and widget type Text Item, this may be used if you expect to have longer than usual text entered for your text item and want the widget to support wrapping text on the screen.
Enabled - Indicates whether the attribute appear as enabled or disabled (greyed out); only enabled attributes can be updated in the attribute screen. For attributes where you want the users to enter information, you must set them as enabled. For attributes that will display a default value (using a default function at the group set level), you will need to set them as disabled.
Validation Functions - this is not supported for SaaS implementations, so should always be left blank.

Once you have specified the attributes to be added, you can choose the View UI button to see an example of what the attributes will look like once they are activated. If needed, make any changes to display order, labels, and so on. When you are ready to activate the attributes, which will make them visible to users, click the Activate button. This also generate the views at the group set and group level as you have defined them.

Managing Record Groups

To add, update, or remove record groups, select the template type of Administration from the Download Data screen and then the template Custom Flex Attribute Foundation. Click the Download button and when prompted, choose to either open the .ods file that is generated or save the file and open it separately in the spreadsheet application of your choice. There will be two tabs in the workbook that is generated that is used for managing the configuration of record groups.

Add a Record Group

If you plan to add any attributes that are of type List of Values, then you will need to define a record group as part of the configuration. To add a record group, select the action type of Create in an empty row in the CFA Record Groups tab in the workbook. Next, enter a unique number of up to 10 digits in the Record Group column and enter a name in the Record Group Name column of up to 30 characters in your configured primary language. Next, you'll choose the query type of either simple or complex. A simple query will be generated systematically based on the addition of attributes in the spreadsheet. Whereas a complex query can include more conditions and must be defined outside this worksheet.

Note that in a cloud service implementation, only the simple query type is supported. For simple queries, you'll need to include the following information:

Table Name - the table against which the record group query will execute; this must be a valid table name in the Merchandising schema - for example, UDA_VALUES. This can be up to 30 characters in length.
Value Column - this will be part of the generated select statement in the record group that will return an entity ID; it is usually the primary key of the table specified in the Table Name column (for example, UDA_VALUE). This can be up to 30 characters in length.
Description Column - this will be part of the generated select statement in the record group that will return a description that corresponds to the value column; it is usually the description of the entity as defined in the table name (for example, UDA_VALUE_DESC). This can be up to 30 characters in length.
Column 1 - the three values here will be used to generate a where clause if you want the record group to return only a subset of the table. This is optional for all simple queries, but if one value is defined for column 1, then all three must be defined.
- Where - column name that should be used to limit the values returned (for example, UDA_ID). This can be up to 30 characters in length.
- Operator - valid values are !=, <, <=, =, >, >=, is NULL, or is not NULL
- Condition - indicates the condition that will limit the results. For the UDA example, this may be the specific UDA ID that should be returned. This can be up to 120 characters in length.
Column 2 - this is optional for all simple queries, but if one value is defined for column 2, then all three of where, operator, and condition must be defined.

For complex record groups, you will need to insert the query you want direction into the CFA_RECORD_GROUP table in Merchandising. So, the columns listed above are not required.

For each record group created, you will also need to define at least one set of labels in your primary language. To do this, navigate to the CFA Record Group Labels tab in the workbook. In a blank row in the worksheet, select an action type of Create and then enter the record group ID you used for your record group.

Then, select your primary language configured in Merchandising and enter the label names you want used in the LOV Title, Value Column, and Desc Column Header fields. You can create labels of up to 255 characters, but it is recommended to try not to exceed 60 characters for best display in the Merchandising screens. Repeat this process for all languages you require for your users.

Modify a Record Group

CFA Entity - add a custom function in the Validation Function column using the full package function name (package_name.function_name)
CFA Group Sets - Display Order, Qualifier Function, Validation Function, and Default Function; also, Group Set View Name and Staging Table Name prior to attributes being activated for the group set.
CFA Group Set Labels - Label
CFA Groups - Display Order; also, Group View Name prior to attributes being activated for the group.
CFA Group Labels - Label
CFA Record Groups - no changes can be made once the attribute using this record group is active; prior to activation, the following columns are editable: Record Group Name, Query Type, Table Name, Value Column, Description Column, Where Column 1, Operator 1, Condition 1, Where Column 2, Operator 2, Condition 2
CFA Record Group Labels - LOV Title, Value Column, Desc Column Header

Note:

Once attributes are active, the data that can be updated for each of these areas is limited to the following: labels, display order, and custom functions. For custom functions, the changes will be applicable going forward for editing or creating data in the impacted entity. It will not revalidate all the data that was previously created.

Delete a Record Group

If you wish to remove a record group, navigate to the CFA Record Groups tab in the spreadsheet and select the Delete action on the row of the record group, you wish to delete. You must also remove all labels that have been associated with that record group in the CFA Record Group Labels tab, by selecting the Delete action in the row associated with those labels. Record groups cannot be deleted if the attribute using the record group has been activated, however labels can be removed at any time.

Uploading Changes

To review the status of the upload and check whether any errors occurred, select the Foundation Data > Review Status task from the main task list.

See also the Oracle Retail Merchandising Do the Basics User Guide section on "Download/Upload Data from Spreadsheets" for more information.

Using Custom Flex Attributes

Flex attributes are not used in any base processing, but they can be included in custom reports, or integrated to other solutions. When querying flex attributes, it is recommended that you use the views at the group set or group level, so that the queries can be built more like for other tables. The views are automatically generated when the attributes are activated.

For integration, the flex attributes will also be automatically made available in inbound and outbound integration when they are activated. This is done slightly differently based on the method of integration.

For message-based integration through the Oracle Retail Integration Bus (RIB) and bulk data integration (BDI), attributes are published as name-value pairs based on the column name defined at the attribute level. This is true for outbound and inbound.

For spreadsheet upload and bulk loads that use those templates, the CFAS extension tables can also be enabled for addition to the templates. For entities like item and PO, where there is the ability to create your own templates, you will have the option to manually add the CFAS extension tables to your customized templates using the view name defined at the group set level. For other entities, like diff types, where customization of templates isn't supported, the flex attributes are added automatically to the template when activated. For more information on customizing spreadsheet upload templates, see the Configure Spreadsheet Download/Upload section in the Oracle Retail Merchandising Implementation Guide.

If you have built any custom reports, integrations, or bolt-on applications that are based on the RDS or DAS data and wish to use CFAS as part of those, then you will likely want to use the database views described above for easier access to the data. Because views cannot be replicated, they will need to be created on the target database. To create these, a script (gen_cfas_view.sql) can be accessed through My Oracle Support note 2283998.1, including instructions for how to use the script (in Appendix C of the Oracle® Retail Data Access Schema GoldenGate Target Installation and Configuration White Paper).

Note:

Deals Upload does not support uploading flex attributes. If you add attributes at that level, they can only be managed in the Merchandising UI.

Migrating Custom Flex Attributes

If you have set up flex attributes in one environment, such as a pre-production environment, and want to migrate them to another, such as a production environment, the following process should be followed. Starting with migrating any new or changed attribute foundation data and then migrating the attributes.

Migrate Attribute Foundation

If you are creating or updating the group sets, groups, record groups, and/or their labels. Then the appropriate data should be exported into a spreadsheet from the source environment using the following steps:

From the Merchandising task list, select Foundation Data > Download Foundation Data.
In the Download Data page, select template type Administration and template Custom Flex Attribute Foundation. Click Download.
You will be prompted to either open or save the .ods in the spreadsheet application of your choice. Choose to open the file.

The resulting file will include all source environment data for groups sets, groups, record groups, and their labels. Remove all data that does not require adding or updating in the target environment from all tabs by deleting the rows (do not delete tabs or columns).

For each row in each tab that will be migrated, set the Action column to either Create, if the data doesn't already exist in the target, or Update, if you are updating existing information. Save your .ods file. You are now ready to migrate these data points.

Log into the target environment and follow these steps:

From the Merchandising task list, select Foundation Data > Upload Foundation Data.
In the Upload Data page, select template type Administration and template Custom Flex Attribute Foundation. A Process Description should default. Then, select your file clicking the Browse…. Button. Click Upload.

To validate that your updates were processed without issue:

From the Merchandising task list, select Foundation Data > Review Status.
In the Data Loading Status page, check the status of the upload you just submitted. If the status is Processed with Errors, then click the View Issues button for more details and follow the error information to correct your data in the spreadsheet and repeat the upload steps with the corrected file.

Migrate Attributes

If you have new attributes to migrate the steps below should be followed.

In the source environment, from the Merchandising task list, select Foundation Data > Download Foundation Data.
In the Download Data page, select template type Administration and template Custom Flex Attributes. If desired, enter filter criteria to limit the table and group set whose details will be exported. Click Download.
You will be prompted to either open or save the .ods in the spreadsheet application of your choice. Choose to open the file.

The resulting file will include all source environment data for attributes, limited by the Merchandising table and group set, if you used the filtering. Remove all data that does not require adding to the target from all tabs by deleting the rows (do not delete tabs or columns), as needed.

For each row in each tab that will be migrated, set the Action column to Create. Save your .ods file. You are now ready to migrate these data points to the target.

Log into the target environment and follow these steps:

From the Merchandising task list, select Foundation Data > Upload Foundation Data.
In the Upload Data page, select template type Administration and template Custom Flex Attributes. A Process Description should default. Then, select your file clicking the Browse…. Button. Click Upload.

To validate that your updates were processed without issue:

From the Merchandising task list, select Foundation Data > Review Status.
In the Data Loading Status page, check the status of the upload you just submitted. If the status is Processed with Errors, then click on the View Issues button for more details and follow the error information to correct your data in the spreadsheet and repeat the upload steps with the corrected file.

The last step for attribute migration is to activate the attributes in the target environment. This will make the attributes visible to users in the target environment and also create or update the views at the group set and group level that are used for inbound and outbound integrations. Follow these steps:

From the Merchandising task list, select Application Administration > Custom Flex Attributes.
Select the Application Table and Group Set where your attributes were added. Click Display Attributes.
Review the attributes listed and ensure all the information is as expected. You may also want to click the View UI button to validate the layout matches what you had in source environment. Then click Activate.

Repeat these steps for each table/group set combination where you are adding attributes.