The following identify the classes that support the Validation Issue handling in the Core layer of the API.
Classes
AutoResponsesCollection
The AutoResponsesCollection class contains a list of automatic responses to validation issues. The collection is loaded and referenced by the API Core Application object. The collection is implemented as a hash table that is keyed by API item type/issue type. For example, an auto-response fro the “product out of stock” issue that is coded in the base OrderInfo namespace is keyed in the hash table as “OrderInfo.OrderMaster/
OrderInfo.ProductOutOfStockIssue”. It is the responsibility of the consumer to load the autoresponses collection with the appropriate responses for that collection. The API developer may check for an auto response using the HasResponse and GetResponse methods.
Example
From within the OrderInfo.OrderMasters collection, the following call determines if an auto response exists for the ProductOutOfStockIssue.
Global.App.AutoResponses.HasResponse(Me.ItemType, GetType (ProductOutOfStockIssue)
Methods
Add Adds an auto response to the collection. Remove Removes the response from the collection.
HasResponse Returns TRUE if the requested response exists in the collection.
GetResponse Returns the StandardResponseType value of the response. If the response does not exist in the collection
StandardResponseType, NONE is returned.
IssueBase
The IssueBase class is the base class for all validation issues.
Classes
Properties
Name Description
Caption A short descriptive caption for the issue. This is used by UI programs as a dialog title when displaying the issue. If not overridden, the caption defaults to the Severity of the issue. Key A string that uniquely identifies the issue within an issues
collection. The issue base class requires that the key be passed on the constructor. Inherited classes may
automatically generate this key as appropriate. For example, the InformationMessageIssue in the Core generates a GUID for the key and combines the class name and additional key, if applicable, to arrive at the Unique key for the issue.
It is up to the API developer to determine if an issue needs an additional key. If the additional key is passes to the constructor, it is included as part of the Key.
Message This is the text message displayed for the issue. Overloaded constructors on IssueBase allow this to be specified as either a string message or as a MessageId number. Both
constructors also take a number of issue parameters as well, allowing this message to be used as a format string. In addition, an inherited issue class may choose to override the message property so that more complex logic may be implemented to show a more appropriate message.
Reference The reference property provides a place for the creator of the issue to store contextual information about the issue. For example, if the issue is a question about a particular product, the API developer may choose to store the product object in the reference property. This way, when the question is answered, the API developer can take action against the stored product value.
Response The response property returns the
Responses.SelectedResponses property. This supports legacy validation issue code.
ResponseRequired This is a Boolean data type indicating whether a response is required for the issue.
Severity The severity of the issue. See IssueSeverityEnum for a list of values.
IssueEventArgs
The IssueEventArgs class is used when the IssueAdded event is raised from the
IssueCollection class. These events are intended to be used by the consumer to react to the raising of validation issues.
Properties
Name Description
Issue The issue that was added to the collection
IssueResponse
The Issue Response class represents a single response to the issue.
Properties
Responded This property indicates whether a response has been received from the consumer of the API for the issue.
ParentGuid This returns the GUID of the parent object of the object that raised the validation issue.
AdditionalKey When identical issues exist in the same object, this property allows the user to obtain the AdditionalKey associated with the issue.
Name Description
Description The text description of the response. This is the string that displays to the end user in an interactive application when the issue provides a choice of responses. The value for the description may be set using a string or message ID. Empty Shared property that returns an empty response.
Reference The reference property provides a place where the creator of the issue can store contextual information about the
response. For example, if an issue is asking the consumer to choose between a list of alternate products, the API
developer may choose to store the ProductId of each choice in the Reference property.
StandardResponseValue Converts the Value property, which is a string, to one of the value in StandardResponseEnum. If the Value property cannot be converted into a StandardResponseEnum, then StandardResponseEnum.None is returned.
Classes
IssueResponsesCollection
The IssueResponsesCollection contains a list of IssueResponse objects. It is typically referenced via the Responses property of an Issue object.
Properties
Item Returns a single IssueResponse object from the collection using either the response’s string value, the
StandardResponseEnum value, or the numeric index of the item within the collection.
SelectedResponse Returns the response that was chosen by the consumer. If no choice has been made SelectedResponse returns Nothing. DefaultResponse Returns the response marked as the default response for the
issue.
Responded Returns TRUE if the consumer has responded to the issue.
Methods
Add Adds a new response to the collection. Remove Removes the response from the collection.
Contains Returns TRUE if the collection contains the specified response.
IndexOf Returns the integer index of the response within the collection. If the response is not found, it returns a negative number.
IssuesCollection
The IssuesCollection is a collection of validation issues. The IssuesCollection class is referenced from the within a BusinessObject or BusinessObjectCollection by referencing the ValidationIssues property of the object. There is only one IssuesCollection for each top-
Value The sting value of the response. This value is determined by the API developer when the issue is created. The developer may use the StandardRespons values (i.e., OK, Cancel, Yes, No, etc.) or any other sting value (i.e., a product code, customer ID, etc.).
Name Description
Name Description
level API collection. Each member of the top-level collection, all of its child collections, and all of their items point to the root-level ValidationIssues collection.
Properties
Item Returns an individual issue from the collection either via the issue’s key or the numeric index of the issue within the collection.
TriggerValidaitonIssueEvent Set to TRUE by default. When this is set to FALSE, the ValidationIssueEvent will not be raised. This can be used to make the UI ignore the event when the issue is generated by the API.
Methods
Assert Accepts a conditional expression and an issue. If the
condition is TRUE the issue is added to the collection. If the condition is FALSE the issue is removed from the collection. ClearResponseNotRequiredIs
sues
Shortcut method that removes all issues from the collection that do not require a response.
Add This adds a new issue to the collection. By default, when an issue is added, the Add method checks the AutoResponses collection determine if there are any auto responses for the issue. If there is, the Add method sets the selected response on the issue to the appropriate value before adding it to the collection. If the auto response value is Ignore, the Add method ignores the issue and does not add it to the collection.
Remove Removes the issue from the collection. RemoveAll Removes all of the issues from the collection.
Contains Returns TRUE if the specified issue is in the collection. ErrorCount Returns the number of issues in the collection that have a
severity of “ERROR”. The default save method checks this value before attempting to save a collection. If the
ErrorCount > 0, the save method does not attempt to save the collection.
IndexOf Returns the numeric index of the issue within the collection. If the issue is not found, IndexOf returns a negative number.
Name Description
Classes
Events
IssueRaised This event occurs whenever a new issue is added to the collection. It is used by the consumer to react to new validation issues.
IssuesReset This event occurs when the issues collection is cleared. It is used by the consumer to display the list of current
outstanding issues.
IIssue
This is the interface implemented by all validation issues. This interface is implemented by IssueBase.
Properties
Name Description
Name Description
Caption A short descriptive caption for the issue. This is used by UI programs as a dialog title when displaying the issue. If not overridden, the caption defaults to the Severity of the issue. Key A string that uniquely identifies the issue within an issues
collection. The issue base class requires that the key be passed on the constructor. Inherited classes may
automatically generate this key as appropriate. For example, the InformationMessageIssue in the Core generates a GUID for the key and combines the class name and additional key, if applicable, to arrive at the Unique key for the issue.
It is up to the API developer to determine if an issue needs an additional key. If the additional key is passes to the constructor, it is included as part of the Key.
Message This is the text message displayed for the issue. Overloaded constructors on IssueBase allow this to be specified as either a string message or as a MessageId number. Both
constructors also take a number of issue parameters as well, allowing this message to be used as a format string. In addition, an inherited issue class may choose to override the message property so that more complex logic may be implemented to show a more appropriate message.
IIssuesCollection
The interface implementedd by the IssuesCollection class.
Properties
Item Returns an individual issue from the collection either via the issue’s key or the numeric index of the issue within the collection.
TriggerValidaitonIssueEvent Set to TRUE by default. When this is set to FALSE, the ValidationIssueEvent will not be raised. This can be used to make the UI ignore the event when the issue is generated by the API.
Reference The reference property provides a place for the creator of the issue to store contextual information about the issue. For example, if the issue is a question about a particular product, the API developer may choose to store the product object in the reference property. This way, when the question is answered, the API developer can take action against the stored product value.
Response The response property returns the
Responses.SelectedResponses property. This supports legacy validation issue code.
ResponseRequired This is a Boolean data type indicating whether a response is required for the issue.
Severity The severity of the issue. See IssueSeverityEnum for a list of values.
Responded This property indicates whether a response has been received from the consumer of the API for the issue.
ParentGuid This returns the GUID of the parent object of the object that raised the validation issue.
AdditionalKey When identical issues exist in the same object, this property allows the user to obtain the AdditionalKey associated with the issue.
Name Description
Classes
Methods
Assert Accepts a conditional expression and an issue. If the
condition is TRUE the issue is added to the collection. If the condition is FALSE the issue is removed from the collection. ClearResponseNotRequiredIs
sues
Shortcut method that removes all issues from the collection that do not require a response.
Add This adds a new issue to the collection. By default, when an issue is added, the Add method checks the AutoResponses collection determine if there are any auto responses for the issue. If there is, the Add method sets the selected response on the issue to the appropriate value before adding it to the collection. If the auto response value is Ignore, the Add method ignores the issue and does not add it to the collection.
Remove Removes the issue from the collection. RemoveAll Removes all of the issues from the collection.
Contains Returns TRUE if the specified issue is in the collection. ErrorCount Returns the number of issues in the collection that have a
severity of “ERROR”. The default save method checks this value before attempting to save a collection. If the
ErrorCount > 0, the save method does not attempt to save the collection.
IndexOf Returns the numeric index of the issue within the collection. If the issue is not found, IndexOf returns a negative number.
Events
IssueRaised This event occurs whenever a new issue is added to the collection. It is used by the consumer to react to new validation issues.
IssuesReset This event occurs when the issues collection is cleared. It is used by the consumer to display the list of current
outstanding issues.
Name Description
IssueSeverityEnum
The IssueSeverityEnum identifies the severity of the issue.
Information The is extra information provided to the consumer and is only used if no response is necessary.
Warning Warns the consumer about a particular action. Similar to Information, but allows the consumer to display the message differently.
Question Used when a response from the consumer is needed. Error Identifies the issue as an error. Errors may or may not
include responses. If a BusinessOject’s issues collection contains error issues, the save method does not attempt to save the object.
StandardIssueResponseEnum
The StandardIssueResponseEnum represents a list of standard responses to issues. An issue may or may not use the standard responses, or may use a combination of standard and custom responses. It is the responsibility of the API developer to determine the correct set of responses for a particular issue.
Valid values are: • Cancel • Continue • Ignore • No • None • OK • Retry • Yes Name Description
Classes
Core Validation Issues
The following issue classes are coded in the API core.
PropertyMissingIssue
This issue is raised when an object requires a property value, but that value has not been set. The Reference property of the issue contains the object that is missing the property and the issue provides a property name property as well.
BusinessObjectPropertyMissingIssue
This issue is similar to the PropertyMissingIssue, except that the Reference property is strongly typed to an IBusinessObject object. The name of the missing property is stored in the issue as well. This issue is raised by the core Validate() methods when checking that all required properties on a business object are set.
InvalidPropertyValueIssue
This issue is raised when a consumer attempts to set a property to a value that is not valid for that property. This may be a violation of the minimum or maximum length of a string, the minimum or maximum value for a number, a setting outside of a specified date range, etc. The issue is raised by the various Property Setter methods in the core BusinessObject.
YesNoIssue
This is a generic issue that automatically adds the YES and NO responses to its responses collection. This issue is not used by the core, but is available for the base layer developers to inherit from.
DuplicateObjectIssue
This issue identifies that a duplicate object has been detected. It is raised by the DuplicateCheck() process in the Core.