Use Application Development Framework Desktop Integration to Manage Rules

You can use ADF Desktop Integration with Microsoft Excel (ADFdi) to maintain a common set of rules across multiple models and environments.

Download rule definition data to a spreadsheet connected to your development environment, optionally modifying the definitions, and uploading the definitions to the same or another model or environment.

Rule Management Summary

You can perform the following operations when managing configurator rules:


Search	To manage rules for a draft model, search for the model by its name, across workspaces, or by the name of the workspace that contains the model.
Create	To create a rule for the model you searched for, download its rule data to an using an Application Development Framework Desktop Integration (ADFDI) enabled spreadsheet, add details for the rule, then upload the rule data.
Update	To update an existing rule for the model you searched for, download its rule data to an ADFDI-enabled spreadsheet, make changes to certain details for the rule, then upload the rule data.

Management Procedure

The following procedure applies to both updating or supplementing existing rules, and to replicating rules in another environment.

Before using this feature, you must have downloaded and installed the latest version of ADF Desktop Integration with Microsoft Excel, by selecting Download Desktop Integration from your Home page.

The models containing the rules to be managed must be in Draft status and must be participants in an unreleased workspace (a workspace with the status of In Development).

To create or modify rules using ADFDI:

From the File-Based Data Management section of the task drawer panel, click the Manage Rules task.
When prompted, open the Excel spreadsheet.
When prompted, sign in with the credentials that you use for the Configurator Models work area. You may need to sign in each time you make the ADFDI connection.

The spreadsheet for managing rules opens automatically in Microsoft Excel. The spreadsheet includes controls for working with ADFDI functions, on a worksheet ribbon tab named Manage Rules.
Click the Search button on the ADFDI tab. Enter selection criteria for the models whose rules you want to manage. You can restrict the search by model or workspace name, or both.

When your search completes, select the model whose rules you want to manage and click OK. The spreadsheet becomes populated with a row for each rule currently existing in the model.

Optionally, you can log out of your ADFDI connection, to work offline, by clicking a button on the ADFDI tab.

If you want to modify the downloaded rules, you can edit existing values for the rules, or insert new rows to create new rules or cell values that accomplish your update, using the columns of the spreadsheet as described in the following table. The columns whose values can be updated correspond to fields on the Rules tab of the Edit Configurator Model page.

Don't replicate data in an existing row by copying and pasting the entire row, because the generated read-only value in the Key column must be unique. Only replicate cells that can be updated, which are displayed without shading.

Column	Can Be Updated?	Description
Changed	No	Indicates that a row was changed or entered since the last download or upload.
Flagged	No	Reserved for future use.
Status	No	Displays the results of the validation of the row data that's performed on each upload. Values include: Update failed Insert failed Row inserted successfully
Model	Yes	Name of the existing model containing the rule. You can't create a new model this way.
Workspace	Yes	Name of the existing workspace containing the model draft that contains the rule. You can't create a new workspace this way.
Name	Yes	Name of the rule. Entering a new name creates a new rule in the specified model, workspace, and folder. You can't change the name of an existing rule this way. You can't use a rule name that already exists in another draft of the model.
Description	Yes	Description of the rule. You can change the description as desired.
Folder Path	Yes	Name and path of the folder containing the rule. Entering a new folder name creates a new folder under the top-level Rules folder for the model. To create or use subfolders, use the following notation: `subfolder/sub-subfolder/...`
Type	Yes	Type of the rule. Only Statement Rules are supported.
Rule Class	Yes	The current rule class of the rule. To change, the class, select one of: Constraint Default Search Decision
Rule Text	Yes	The CDL text that defines the rule. The rule text is validated when you upload it, following all the rules that apply to rules in the Configurator Models work area. It's possible to upload invalid rule text, but it will cause the status of the uploaded rule to be Error. Ensure that node names are enclosed with single quotation marks, so that nodes can be located correctly when the rule text is parsed. If a rule begins with a node name, add an additional single quotation mark before it, to accommodate the behavior of Microsoft Excel.
Enabled	Yes	Whether the rule is enabled or not. Select Yes or No.
Rule Status	No	Displays the results of the validation of the rule text that's performed on each upload. Values are: Modified Valid Error
End Date	No	The date this rule becomes invalid due to end dating of participants.
Error Message	No	Error message generated when validating the rule during upload. The messages are the same as those generated by validation in the Configurator Models work area.
Key	No	Unique key value used by ADFDI to associate spreadsheet rows with rules.

A marker appears in the Changed column of the spreadsheet in each row that you modify. This marker indicates which rows will be uploaded to the model.

Tip: You can maintain a separate offline spreadsheet containing the data to be used for updates, then copy and paste that data into the ADFDI connected spreadsheets that you download.

Click the ADFDI Create or Update button, which submits the update using your current ADFDI connection.

The upload process updates the rule definitions based on the changes you made in the downloaded ADFDI spreadsheet. After every upload, each row in the spreadsheet is subjected to two-step validation:
1. The data in the spreadsheet row is validated by ADFDI. The results are displayed in the Status column.
2. The rule text is validated by Configurator. The results are displayed in the Rule Status column.
Examine the messages in the Status and Error Message columns of the spreadsheet for information on the update, or possible errors.

If the Status cell of a row contains Insert failed, click No when you're prompted whether to discard the pending changes from your update, and examine click the Status Viewer button to examine details about the failure.

To see the effect of your rule updates, you might have to close the affected Rules page, if it's open, and reopen it to refresh the display.

Migrating Rules

You can migrate rules from one instance of the Configurator Models work area to another instance, in a way similar to creating or updating rules in a single instance.

For example, assume that you want to migrate rules from a Test instance to a Production instance. To migrate rules:

Sign into Test, search for the model containing the rules, and download the rules from that model.
Copy the downloaded rule data from the spreadsheet for Test. Only copy the cells that allow updating. You can modify the rules, as long as you follow the restrictions described here about which data can be changed.

Tip: You can set aside a backup of the copied rule data by pasting it in a separate spreadsheet that's not connected by ADFDI.
Sign into Production, search for the model that will receive the rules, and download the rules from that model. The workspaces and models referenced in your copied rule definitions must exist in Production.
Copy the rule data that came from Test, and paste it into the spreadsheet connected to Production, in the columns that are eligible for updating.
Click the ADFDI Create or Update button, to upload the rule data to the model in Production.