createCostRules

Purpose

Creates a collection of new cost rules in the system.

Caution: Do not use the createCostRules operation to migrate a large volume of cost rule data from a legacy system into PPM as it will take too much time.

Creating a cost rule or any other operation is expected to take just slightly less time than the same operation run from within the PPM application.

Function

Creates a new set of cost rules in the system. The cost rule update service picks up these new cost rules and modifies the costs on any affected entities depending on the corresponding effective dates.

Limitations

The creation of cost rules using this operation occurs in a single transaction, where if one cost rule fails, the entire operation is rolled back.

Related Information

updateCostRules updates a collection of cost rules.

Input

An array of WSCostRuleBean.

Note: For date values entered, the format should be a parsable string by Java DateFormat class. Otherwise a ParseException will be thrown by the DateFormat class, which will occur on the client side and not on the server side.

Return

An array of WSCostRuleBean.

Java Interface

CreateCostRulesResponseDocument createCostRules (CreateCostRulesDocument in)

Parameters	Description
CreateCostRulesDocument	Wrapper for the WSCostRuleBean array. See the following example for the construction. The bean includes the following fields: Long id int ruleNumber List costRates// List<CostRateBean> List costFactorValues// List<WSCostFactorValueBean>
CreateCostRulesResponseDocument	Wrapper for the array of created cost rule ids. See the following example for retrieving the bean and its fields.

Parameters

Description

CreateCostRulesDocument

Wrapper for the WSCostRuleBean array.

See the following example for the construction.

The bean includes the following fields:

Long id
int ruleNumber
List costRates// List<CostRateBean>
List costFactorValues// List<WSCostFactorValueBean>

CreateCostRulesResponseDocument

Wrapper for the array of created cost rule ids. See the following example for retrieving the bean and its fields.

Java Examples

Example: create a new set of cost rules.

public void testCreateCostRule() throws Exception {
   enableAllCostFactors();
   CostRule costRule = CostRule.Factory.newInstance();
   costRule.setFactorArray(new CostFactorValue[] {
   costFactorValue(DEPARTMENT, "Finance"),
   costFactorValue(REGION, "America"),
   costFactorValue(MISC_WORK_ITEMS, "Vacation"),
   costFactorValue(REQUEST_TYPE, "Bug")
   }
   );
   costRule.setRateArray(new CostRate[] {
   costRate(null, "Oct 13, 1994", 1.0f),
   costRate("Oct 14, 1994", "Jan 1, 2000", 2.0f),
   costRate("Jan 1, 2001", "Jan 1, 2001", 3.0f),
   costRate("Jan 2, 2001", "June 28, 2006", 3.7f)
   }
   );

   createCostRules(new CostRule[] { costRule });
   }
   CostRule[] createCostRules(CostRule[] costRules) throws
Exception {
   FinanceServiceStub FM = new FinanceServiceStub(ctx, WSURL);
   CreateCostRulesDocument createCostRulesDoc =
CreateCostRulesDocument.Factory.newInstance();

createCostRulesDoc.addNewCreateCostRules().setCostRuleArray(cos
tRules);
   CreateCostRulesResponseDocument response =
FM.createCostRules(createCostRulesDoc);
   return
response.getCreateCostRulesResponse().getCostRuleArray();
}

Errors and Exceptions

When an error occurs with this operation, you will see a description of the root cause in the log or in the response message.

The server log file content is similar to the following:

Exception in thread "main" org.apache.axis2.AxisFault:
<exception:exceptionDetails xmlns:exception="http://
www.mercury.com/ppm/ws/exception">
<exception:detail>[root cause description] </exception:detail>
</exception:exceptionDetails>

Root Cause Descriptions

Possible root cause descriptions:

Message Code	Message	Cause(s)	Possible Corrective Action
exception.authorization	You do not have the privilege to take this action. Please consult your PPM Administrator.	User not authorized to read the cost rule.	Check the user licenses and privileges (access grants).
error.ws.rateOverlap	One of the cost rules being created has two rates with overlapping effective ranges. Please check the rule and fix the rate overlap.	One of the rules has two or more rates with overlapping effective ranges.	Check the effective date ranges specified for the cost rate in the cost rule and make sure the dates are not overlapping.
error.conflictingCostFactors	You are adding a rule that has an illegal cost factor combination. No cost rule may have values for both the Resource and Role cost factor.	One of the rules has a combination of cost factors that is not allowed.	Avoid using the combination of cost factors mentioned in the message.
error.conflictingRules	You are adding a rule that has a conflict with an existing rule (Rule#30061). Please make sure the new rule has at least one cost factor with a different value.	One of the rules has the same set of cost factors as another rule in the system.	Change the cost factor values or use different cost factors.
validationError.nameNotFound	Could not find a Department whose name is MANUFACTUR. Please verify that a Department with this name exists in the system. Alternatively, you may specify the Department by ID instead of name.	One of the rules has a cost factor that is not in the system wide selected cost factor set.	Verify the cost factor values given for a cost rule. These values should be already seeded in the system.
ex.InvalidCurrency	Could not find a Currency with id USWD. Please verify that a Currency with this id exists in the system.	Specified currency does not exist in the PPM system.	Verify that a currency with this ID exists in the system. Alternatively, you may specify the Currency by name instead of ID.
ex.InvalidDateRange	The effective end date {0} is before the start date {1}.	Specified start date is after the end date.	Specify the start date before the end date.
error.ws.notSelectedCostFactor	The cost factor {Project} is not selected for use. The selected cost factors are {Resource, Role, Region.}	Specified cost factor is not selected for use.	Use selected cost factors.
validationError.nameNotFound	Could not find a {0} whose name is {1} or the {0} with name {1} is disabled. Please verify that a {0} with this name exists in the system or enable it. Alternatively, you may specify the {0} by id instead of name.	Specified cost factor value you selected does not exist or disable.	Verify that a cost factor value with this name exists in the system.
validationError.nameAndIdNull	When specifying a {0} you must provide either its name or id. If you do not want to specify a {0} please omit it entirely.	The user selects a cost factor, but does not input the factor id or name.	Specify a value either for the name of the ID.