Configuring upgrade mappings for free or paid upgrades

About the Mapping tab

Controlling how Poetic applies multiple upgrade rules

Selecting the rule to use during upgrade activation

About the upgrade-from products

About upgrade-to products

Mapping upgrade-from products to upgrade-to products

Handling non-whole number upgrade-to quantities

Configuring the upgrade rules

Adding and editing the upgrade rules
Adding and removing lines within a rule
Configuring the upgrade-from products
Configuring the upgrade-to products

About the Mapping tab

The Mapping tab lists the upgrade-from and to products for the automated upgrade job. The Mapping tab does not display for notification only jobs.

The upgrade-from products are the products that determine eligibility for the job.
The upgrade-to products are the products that eligible customers receive.

The upgrade-from and upgrade-to products are organized into upgrade rules. Each rule represents one upgrade option for this job. For example, if your upgrade-from products are available in multiple languages, you may set up one rule for each language. If the user has the English version of DocumentWriter V1, they get the English version of DocumentWriter V2. If they have the French version of DocumentWriter V1, they get the French version of DocumentWriter V2.

If the job has been executed, then users can only edit the information on the Mapping tab if:

The Registry setting ALLOW_AU_JOB_MAPPING_EDIT_AFTER_EXECUTION is set to True
They have the security setting CAN_EDIT_MAPPING_AFTER_EXECUTION

Controlling how Poetic applies multiple upgrade rules

If an upgrade job has more than one upgrade rule, then when you run the upgrade job, the Registry APPLY_ALL_MATCHED_UPGRADE_DELIVERABLE_RULES determines how Poetic applies the rules.

If the Registry is true, then when the job is run, all of the upgrade rules are applied, and Poetic finds all of the entitlements that match any of the rules.
If the Registry is false, then each rule is checked until a matching entitlement is found. Only that rule is then applied. Poetic finds all of the entitlements that match that rule, and ignores the other upgrade rules.

For example, an upgrade job has two rules:

Rule 1 - Product A is upgraded to Product B
Rule 2 - Product X is upgraded to Product Y

The system includes entitlements for both Product A and Product X.

When the job runs:

If APPLY_ALL_MATCHED_UPGRADE_DELIVERABLE_RULES is true, then Poetic first finds all of the entitlements that match Rule 1, then finds all of the entitlements that match Rule 2. All of the entitlements for Product A and Product X are upgraded.
If APPLY_ALL_MATCHED_UPGRADE_DELIVERABLE_RULES is false, then Poetic first looks for entitlements that match Rule 1. Because there are entitlements for Product A, Poetic does not apply Rule 2. Only the entitlements for Product A are upgraded.

Selecting the rule to use during upgrade activation

During upgrade activation, if more than one upgrade rule could be applied, then Poetic uses the Registry setting UPGRADE_ACTIVATION_RULE_MATCH_ALGORITHM to determine which rule to use.

The possible values are:

FIRST_AVAILABLE	Poetic uses the first matching rule, and does not look at any of the other rules. This is the default value.
MAX_MARKED	Poetic finds all of the mapping rules that could be used, and checks the number of marked entitlements on the machine for that rule. Poetic then uses the rule that has the most marked entitlements.

About the upgrade-from products

The product type for upgrade-from products is based on the selection mode.

If product security categories are used (Registry IS_PRODUCT_SECURITY_CATEGORY_SUPPORTED is true), then you can only select upgrade-from products that belong to a product security category that you have the privileges to view.

Maintenance entitlements	Upgrade-from products must be maintenance products.
License with linked maintenance	Upgrade-from products must be license products. If CAN_UPGRADE_MAINTENANCE_ENTITLEMENT is True, then there must be both license and maintenance products.
License with related product line level maintenance at company level	Upgrade-from products must be license products.
License without related product line level maintenance at company level	Upgrade-from products must be license products.
License with related product line level maintenance at group level	Upgrade-from products must be license products.
License without related product line level maintenance at group level	Upgrade-from products must be license products.
License entitlements	Upgrade-from products must be license products.
Products only	Upgrade-from products may be license or maintenance products.
Loaded list of entitlements	If you are loading the upgrade-from entitlements from a flat file, then you do not need to provide upgrade-from products. When the job runs, Poetic automatically upgrades all of the entitlements in the file. Note that if you do not provide upgrade-from products, you can only configure one rule, and the rule can only have one upgrade-to product. If you do provide upgrade-from products, Poetic checks the entitlements in the loaded file to see if they use those products and then only upgrades those entitlements that match.

About upgrade-to products

Upgrade-to products are the products received if a customer is eligible for the job based on the upgrade-from product(s) in the upgrade rule and the entitlement selection criteria.

In each rule, the first upgrade-to product is the product used to perform the upgrade. Additional upgrade-to products may be added. These additional products may be of any type. For example, when users upgrade from version 1 to version 2, they also get a free documentation set.

When selecting upgrade-to products:

Do not use products that have a post-activation swapping product. The upgrade-to product should be the final product after the upgrade.
Do not use products that use a different activation method from the upgrade-from products. For example, if the upgrade-from product uses registration-only activation, then the upgrade-to products must also use registration activation. If the activation methods do not match, Poetic raises an error during the upgrade activation.
If product security categories are used (Registry IS_PRODUCT_SECURITY_CATEGORY_SUPPORTED is true), you should not use products that have a different product security category from the upgrade-from product. Also, you can only select products that belong to a product security that you can view.

Maintenance entitlements	Within each upgrade rule: The first upgrade-to product must be a license or upgrade product. This is the product that replaces the license product in license entitlements that are linked to the maintenance entitlements for the upgrade-from products. Subsequent upgrade-to products may be of different types.
License with linked maintenance	Within each upgrade rule: The first upgrade-to product must be a license or upgrade product that replaces the upgrade-from product. Subsequent upgrade-to products may be of different types.
License with related product line level maintenance at company level	Within each upgrade rule: The first upgrade-to product must be a license or upgrade product that replaces the upgrade-from product. Subsequent upgrade-to products may be of different types.
License without related product line level maintenance at company level	Within each upgrade rule: The first upgrade-to product must be a license or upgrade product that replaces the upgrade-from product. Subsequent upgrade-to products may be of different types.
License with related product line level maintenance at group level	Within each upgrade rule: The first upgrade-to product must be a license or upgrade product that replaces the upgrade-from product. Subsequent upgrade-to products may be of different types.
License without related product line level maintenance at group level	Within each upgrade rule: The first upgrade-to product must be a license or upgrade product that replaces the upgrade-from product. Subsequent upgrade-to products may be of different types.
License entitlements	Within each upgrade rule: The first upgrade-to product must be a license or upgrade product that replaces the upgrade-from product. Subsequent upgrade-to products may be of different types.
Products only	Within each upgrade rule: The first upgrade-from product in a rule must be of the same type as the upgrade-from product. Subsequent upgrade-to products within a rule may be of other types.
Loaded list of entitlements	Within each upgrade rule: The first upgrade-to product must be the license or upgrade product used when the entitlement is replaced. If there are upgrade-from products, then the subsequent upgrade-to products may be of other types. If no upgrade-from product is specified, then there can only be one upgrade-to product.

Mapping upgrade-from products to upgrade-to products

Within each rule, the upgrade-from products on the left make the user eligible for the upgrade-to products on the right. For example, you may use the upgrade rules to consolidate two separate products into a single unified product, or offer the upgrade plus a free documentation set.

Within each row, the product on the left makes the user eligible for the product on the right. So in this example, users with Acme DocumentWriter 1.0 receive Acme DocumentWriter 2.0, users with Acme PictureEditor 1.0 receive Acme PictureEditor 2.0, and users with Acme SpreadsheetWriter 1.0 receive Acme SpreadsheetWriter 2.0.

Line #	Upgrade-From	Upgrade-To
1	Acme DocumentWriter 1.0	Acme DocumentWriter 2.0
2	Acme PictureEditor 1.0	Acme PictureEditor 2.0
3	Acme SpreadsheetWriter 1.0	Acme SpreadsheetWriter 2.0

To replace one product with multiple products, leave the left column blank for the additional products. In this example, users with Acme DocumentWriter 1.0 receive Acme DocumentWriter 2.0, Acme PictureEditor 2.0, and a user's guide:

Line #	Upgrade-From	Upgrade-To
1	Acme DocumentWriter 1.0	Acme DocumentWriter 2.0
2		Acme PictureEditor 2.0
3		Acme DocumentWriter User's Guide

You can also replace multiple products with one product. In this example, users with Acme DocumentWriter 1.0, Acme SpreadsheetWriter 1.0, and Acme PictureEditor 1.0 receive AcmeOffice 2.0:

Line #	Upgrade-From	Upgrade-To
1	Acme DocumentWriter 1.0	Acme Office 2.0
2	Acme SpreadsheetWriter 1.0
3	Acme PictureEditor 1.0

In this example, users with Acme DocumentWriter 1.0, Acme SpreadsheetWriter 1.0, and Acme PictureEditor 1.0 receive both AcmeOffice 2.0 and Acme ImageManager 2.0:

Line #	Upgrade-From	Upgrade-To
1	Acme DocumentWriter 1.0	Acme Office 2.0
2		Acme ImageManager 2.0
3	Acme SpreadsheetWriter 1.0
4	Acme PictureEditor 1.0

Handling non-whole number upgrade-to quantities

When the upgrade-to quantity is calculated using a multiplier, the multiplier value may be a decimal value. For example, if the unit of measurement for a product is changing from MB to GB, then the quantity for the upgrade-to quantity might be calculated as .001 of the original quantity. Note that decimal values are only permitted if you are marking entitlements as upgradeable. You cannot use decimal values for upgrade jobs that generate upgrade orders or shipping files, or for jobs that replace entitlements.

On the Mapping tab, the For non-whole upgrade-to quantity dropdown determines what Poetic should do if the calculated upgrade-to quantity is not a whole number. The options are:

Error	When the calculated upgrade-to quantity is not a whole number, Poetic returns an error.
Round up	When the calculated upgrade-to quantity is not a whole number, Poetic rounds up to the next whole number.

For example, an upgrade job is configured to have the upgrade-to quantity be .25 of the upgrade-from quantity.

An eligible entitlement has a quantity of 25, so the upgrade-to quantity calculates to 6.25.

If the job is configured to return an error for non-whole numbers, then Poetic returns an error
If the job is configured to round up, then the upgrade-to quantity becomes 7

To remove a line from a rule, click its Remove link.

Configuring the upgrade-from products

For each upgrade-from product:

Required for Upgrade	If the product must exist on a system in order for the upgrade to occur, check the Required for Upgrade check box.
Use for Marking	The Use for Marking check box determines which entitlements or machines or registration certificates to mark as upgradeable. To mark entitlements for the selected upgrade-from product, check the Use for Marking check box.
Upgrade-From Product #	In the Upgrade-From Product # field, type the product number of a product that is being upgraded. To search for and select a product, click Find.

Configuring the upgrade-to products

For each of the upgrade-to products:

Upgrade-To Product #	In the Upgrade-To Product # field, type the product number of a product users are eligible for if they meet the upgrade-from requirements.
Determine Qty From	From the Determine Qty From dropdown, select which entitlements to use to determine the quantity for the upgrade-to product. To determine the quantity based on the quantity of the upgrade-from product, select Upgrade-from. To set the quantity based on the quantity of the validation entitlement, select Validation entitlement. Do not select this option if there is no entitlement validation.
Qty Mode	From the Qty Mode dropdown, select the method to use to set the quantity. To multiply the quantity from the upgrade-from or validation entitlement by a multiplier, select Multiplier. In the Qty field, type the multiplier. For example, to set the quantity equal to the entitlement quantity multiplied by 3, select Multiplier from the Qty Mode dropdown, and type 3 in the Qty field. For the Multiplier quantity mode, if the upgrade job is marking entitlements, you can provide a decimal value for the Qty value. For example, to make the upgrade-to quantity half of the upgrade-from quantity, type .5 in the Qty field. If you are replacing entitlements, then Qty Mode must be Multiplier, and Qty must be 1. To set the quantity to a fixed value, select Fixed. In the Qty field, type the quantity value. To set the quantity to the minimum of the quantities from the upgrade-from products, select Minimum of upgrade-from. For example, if you're consolidating Acme DocumentWriter 1.0 and Acme SpreadsheetWriter 1.0 into Acme Office 1.0, then if you select Minimum of upgrade-from, customers who have 5 copies of DocumentWriter and 3 copies of SpreadsheetWriter will receive 3 copies of Acme Office. To set the quantity to the maximum of the quantities from the upgrade-from products, select Maximum of upgrade-from. For example, if you're consolidating Acme DocumentWriter 1.0 and Acme SpreadsheetWriter 1.0 into Acme Office 1.0, then if you select Maximum of upgrade-from, customers who have 5 copies of DocumentWriter and 3 copies of SpreadsheetWriter will receive 5 copies of Acme Office.
Adjust by	In the Adjust by field, set any quantity to add to or subtract from the quantity determined using the Qty Mode and Qty fields. For example, to subtract 3 from the quantity, type -3 in the Adjust by field. To add 5 to the quantity, type +2 in the Adjust by field.
Unit price (%)	Enter a value to calculate the upgrade-to product net price based on a percentage of the upgrade-to product unit price. For example, if the unit price for Product A is $100, and you enter a unit price percentage value of 50, then the calculated upgrade-to product net price is $50.00.