This appendix contains the following topics:
Utility business services are generic, reusable services that perform standard operations. Utility business services are called by other business services to process information that is associated with the calling service. Utility business services eliminate the need to write the same code in a number of business services, and they ensure that a specific process is performed in a uniform manner.
The utility business services follow the rules, best practices, and guidelines discussed in this methodology guide. Utility business service processing should be transparent to consumers of the published business service that calls them. General information about each utility business service is provided in this appendix. If you create custom published business services, you can use these predefined utilities, or you can copy a predefined utility business service into a new business service object, modify it, and call it from your new business service.
General information for creating utility business services is provided in this guide. Here are some key items about utility business services:
Utility business services are called from more than one business service or published business service.
All data mappings are made inside of the utility, not by the service calling the utility.
Any errors that are encountered by the utility during processing are returned to the calling service to handle.
This section discusses the Entity Processor business service.
The Entity Processor business service (J0100010) provides a published interface that exposes three ways to provide address book key information for an entity.
The Entity Processor business service retrieves entity ID, entity long ID, and entity tax ID based on input that is supplied by the published business service that calls the utility. This utility business service processes data in these ways:
Retrieves Entity ID and Entity Long ID when Entity Tax ID is supplied as input.
Retrieves Entity ID and Entity Tax ID when Entity Long ID is supplied as input.
Retrieves Entity Tax ID and Entity Long ID when Entity ID is supplied as input.
This topic identifies the methods, signature, and value object (VO) classes for the Entity Processor business service.
Methods for the business service are:
processEntity(Entity)
processEntity(InternalEntityUtility)
The signature for the business service is:
Public static E1MessageList processEntity(IContext context, IConnection, connection, ValueObject inputObject, ValueObject currentObject)
Value object classes for the business service are:
Entity
InternalEntityUtility
The Entity value object class is a published value object that is owned and managed by the Entity Processor business service. Any published business service that wants to use the Entity value object class within its interface must import the class.
A published business service calls processEntity and passes an input value to the method. The processEntity method sets processing parameters based on the input value. The method compares the input with null or an empty string to determine which values are not included in the input. The order of null comparison is:
Address Number
Long Address Number
Tax ID
If the comparison is successful, the processEntity method calls the internal method, InternalEntityUtility. The InternalEntityUtility method calls the ScrubAddressNumber business function (B0100016) passing in the desired action code. The business function retrieves the appropriate data from the Address Book Master table (F0101).
Note:
This method retrieves records from F0101 and ensures that the ScrubAddressNumber business function selects the appropriate data. Using the business function instead of using direct table input/output has no significant performance impact.The tables in this section provide data information for value object classes.
InternalEntityUtility | N/A | N/A |
---|---|---|
Business Service VO Field Name | Data Type | Input/Output |
mnAddressNumber | MathNumeric | I/O |
szLongAddressNumber | String | I/O |
szTaxId | String | I/O |
Entity | N/A | N/A | N/A | N/A |
---|---|---|---|---|
Published Business Service VO Field Name | Data Type | Input | Key | Javadoc |
entityId | Integer | Yes | Yes | Address book number |
entityLongId | String | Yes | No | NA |
entityTaxId | String | Yes | No | NA |
InternalEntityUtility | Entity | N/A | N/A | N/A |
---|---|---|---|---|
Business Service VO Field Name | Data Type | Published Business Service VO Field Name | Data Type | Transformer |
mnAddressNumber | MathNumeric | entityId | Integer | MathNumeric to Integer |
szLongAddressNumber | String | entityLongId | String | Map |
szTaxId | String | entityTaxId | String | Map |
This section discusses the GL Account Processor business service.
The GL Account Processor business service (J0900010) provides a published interface that exposes four ways to provide general ledger account information.
The GL Account Processor business service retrieves account information based on input that is supplied by the published business service that calls the utility. This utility business service processes data in these ways:
Retrieves GL Account Long ID, GL Account Alternate data, and account information from objectAccount, businessUnit, and subsidiary fields when GL Account ID is supplied as the input field.
Retrieves GL Account ID, GL Account Alternate data, and account information from objectAccount, businessUnit, and subsidiary fields when Account Long ID is supplied as the input field.
Retrieves GL Account ID, GL Account Long ID data, and account information from objectAccount, businessUnit, and subsidiary fields when Account Alternate is supplied as the input field.
Retrieves GL Account ID, GL Account Long ID, and GL Account Alternate data when account information fields (objectAccount, businessUnit and subsidiary) are supplied as the input field.
This topic identifies the methods, signature, and value object classes for the GL Account Processor business service.
Methods for the business service are:
processGLAccount(InternalGLAccountUtility)
processGLAccount(ProcessGLAccount)
The signature for the business service is:
Public static E1MessageList processGLAccount(IContext context, IConnection connection, ValueObject inputObject, ValueObject currentObject)
Value object classes for the business service are:
InternalGLAccountUtility
ProcessGLAccount
GLAccount
GLAccountKey
The GLAccount and GLAccountKey classes are published value objects that are owned and managed by the GL Account Processor business service. Any published business service that wants to use the GLAccount or GLAccountKey classes within its interface must import these classes.
A published business service calls processGLAccountUtility and passes an input value to the method. The processGLAccountUtility method sets processing parameters based on the input value. The method compares the input with null to determine which values are not included in the input. The order of null comparison is:
Account ID
Account Long ID
Account Alternate
If all the values are null for these account fields, then the method evaluates these fields:
objectAccount
businessUnit
subsidiary
If the comparison is successful, the processGLAccountUtility method calls the internal method, InternalGLAccountUtility. The InternalGLAccountUtility method calls the ValidateAccountNumber business function (XX0901), passing in the desired action code. The business function retrieves the appropriate data from the Account Master table (F0901).
Note:
This method retrieves records from F0901. The ValidateAccountNumber business function selects 19 columns from the table. Using the business function does not have a significant performance impact.The tables in this section provide data information for value object classes.
InternalGLAccountUtility | N/A | N/A |
---|---|---|
Business Service VO Field Name | Data Type | Input/Output |
szAccountNumber | String | Input/Output |
szAccountId | String | Input/Output |
szUnstructuredAccount | String | Input/Output |
szDatabaseBusinessUnit | String | Input/Output |
szDatabaseObject | String | Input/Output |
szDatabaseSubsidiary | String | Input/Output |
Note:
For the account to be located, business unit, object, and subsidiary must be passed.ProcessGLAccount | N/A | N/A | N/A |
---|---|---|---|
Published Business Service VO Field Name | Data Type | Input | Key |
GLAccount | N/A | N/A | N/A |
objectAccount | String | Yes | No |
businessUnit | String | Yes | No |
subsidiary | String | Yes | No |
GLAccountKey | N/A | N/A | N/A |
accountId | String | Yes | Yes |
accountLongId | String | Yes | No |
accountAlternate | String | Yes | No |
ProcessGLAccount | InternalGL AccountUtility | N/A | N/A | N/A |
---|---|---|---|---|
Published VO Field Name | Data Type | Business Service VO Field Name | Data Type | Transformer/ Formatter |
GL Account | N/A | N/A | N/A | N/A |
objectAccount | String | szDatabaseObject | String | Map |
businessUnit | String | szDatabaseBusinessUnit | String | Map |
subsidiary | String | szDatabaseSubsidiary | String | Map |
GLAccountKey | N/A | N/A | N/A | N/A |
accountId | String | szAccountId | String | Map |
accountLongId | String | szAccountNumber | String | Map |
accountAlternate | String | szUnstructuredAccount | String | Map |
This section discusses the Inventory Item ID Processor business service.
The Inventory Item ID Processor business service (J4100010) provides a published interface that exposes five ways to provide item identification information.
The Inventory Item ID Processor business service retrieves all potential identifiers for an inventory item based on input that is supplied by the published business service that calls the utility. This utility business service processes data in these ways:
Retrieves itemProduct and itemCatalog when itemId is supplied as the input field.
Retrieves itemId and itemCatalog when itemProduct is supplied as the input field.
Retrieves itemId and itemProduct when itemCatalog is supplied as the input field.
Retrieves itemId, itemProduct, and itemCatalog when itemCustomer or itemSupplier and entity ID and cross-reference type code are supplied as input fields.
Retrieves itemId, itemProduct, and itemCatalog when itemFreeForm, branch plant, cross-reference type code, and entityId are supplied as input fields.
This topic identifies the methods, signature, and value object classes for the Inventory Item ID Processor business service.
Methods for the business service are:
processInventoryItemId (InternalInventoryItemId)
processInventoryItemId (ProcessItemCustomer)
processInventoryItemId (ProcessItemSupplier)
The signature for the business service is:
Public static E1MessageList processInventoryItemID(IContext context, IConnection connection, ValueObject inputObject, ValueObject currentObject)
Value object classes for this business service are:
InternalInventoryItemId
ProcessItemCustomer
– ItemGroupCustomer
ProcessItemSupplier
– ItemGroupSupplier
The ItemGroupCustomer and ItemGroupSupplier classes are published value objects that are owned and managed by the Inventory Item ID Processor business service. Any other business service that wants to use the ItemGroupCustomer and ItemGroupSupplier classes as part of its interface must import these classes.
The Inventory Item ID Processor determines processing based on whether a supplier item or a customer item class was passed by the published business service. The utility retrieves related cross-reference data for the supplier or customer item, if required. The ProcessItemCustomer or ProcessItemSupplier method compares the input value with null or an empty string to determine processing. The first match that the utility finds determines how the utility retrieves the data. The order of null comparison is:
ItemCrossReference
FreeForm
ItemId
ItemProduct
ItemCatalog
Depending on which field, if any, is selected during the comparison process, the ProcessItemCustomer or ProcessItemSupplier method calls the internal method, InternalInventoryItemID, and makes a call to the appropriate business function, passing the expected parameters. Finally, all retrieved item numbers (mnShortItemNumber, sz2ndItemNumber, sz3rdItemNumber) are populated at the end of the process.
These business functions are used with this utility business service:
Validate and Retrieve Item Master (X4101)
Get Item Master Description UOM (B4001040)
Verify and Get Item Xref (B4100600)
Verify and Get Branch Plant Constants (B4101390)
Depending on the business function that is used, data is retrieved from these tables:
F4101 (Item Master)
F4104 (Item Cross Reference)
F41001 (Inventory Constants)
Note:
Database I/O operations are performed through business functions in the JD Edwards EnterpriseOne Validate and Retrieve Item Master module (X4101). This module performs efficient fetches from F4101, retrieving only the columns needed for each type of fetch.To prevent recalling the VerifyandGetBranchPlantConstants function, any cross-reference code that is fetched will be passed back so that users can pass it in instead of having the utility pass the cross-reference code.
The tables in this section provide data information for value object classes.
InternalInventoryItemId | N/A | N/A |
---|---|---|
Business Service VO Field Name | Data Type | Input/Output |
mnShortItemNumber | MathNumeric | Input and Output |
sz2ndItemNumber | String | Input and Output |
sz3rdItemNumber | String | Input and Output |
szFreeFormItemNumber | String | Input |
szBranchPlant | String | Input |
szCrossRefItemNumber | String | Input |
mnAddressNumber | MathNumeric | Input |
szCrossRefTypeCode | String | Input |
ProcessItem | N/A | N/A | N/A |
---|---|---|---|
Published Business Service VO Field Name | Data Type | Input | Key |
crossReferenceType | String | Yes | No |
entityId | Integer | Yes | No |
branchPlant | String | Yes | No |
ItemGroupCustomer | N/A | N/A | N/A |
itemId | Integer | Yes | No |
itemProduct | String | Yes | No |
itemCatalog | String | Yes | No |
itemFreeForm | String | Yes | No |
itemCustomer | String | Yes | No |
ItemGroupSupplier | N/A | N/A | N/A |
itemId | Integer | Yes | No |
itemProduct | String | Yes | No |
itemCatalog | String | Yes | No |
itemFreeForm | String | Yes | No |
itemSupplier | String | Yes | No |
From VO/BSFN/Business Service Property/Other | To BSFN/Other | N/A | N/A | N/A |
---|---|---|---|---|
Field Name | Data Type | Field Name | Data Type | Transformer |
Based on Input VO | N/A | VerifyAndGetBranchPlant Constants (B41001390 / D41001390A) | N/A | N/A |
szBranchPlant | String | szBranchPlant | String | Map |
ItemIdsByXref-MODE | N/A | N/A | N/A | N/A |
N/A | N/A | VerifyAndGetItemXref (B4100600 / D4100600) | N/A | N/A |
Business Service Property NUMBER_OF_KEYS = 3 | String | szKeys | String | Map |
Business Service Property INDEX_ID = 4 | String | szIndex | String | Map |
szCrossRefItemNumber | String | szCustomerItemNumber | String | Map |
mnAddressNumber | MathNumeric | mnAddressNumber | MathNumeric | Map |
szCrossRefTypeCode | String | szCrossRefTypeCode | String | Map |
N/A | N/A | getItemIdsByItemId (internal function) | N/A | N/A |
mnShortItemNumber | MathNumeric | mnShortItemNumber | MathNumeric | Map |
ItemIdsByItemFreeform – MODE | N/A | N/A | N/A | N/A |
N/A | N/A | GetItemMasterDescription UOM (B4001040 / D4001040) | N/A | N/A |
szFreeFormItemNumber | String | szPrimaryItemNumber | String | Map |
szBranchPlant | String | szBranchPlant | String | Map |
ItemIdsByItemId – MODE | N/A | N/A | N/A | N/A |
N/A | N/A | GetItemMasterByShortItem (X4101 / DSDX4101B) | N/A | N/A |
mnShortItemNumber | MathNumeric | mnShortItemNumber | MathNumeric | Map |
ItemIdsbyItemFreeForm – MODE | N/A | N/A | N/A | N/A |
N/A | N/A | GetItemMasterBy2ndItem (X4101 / DSDX4101C) | N/A | N/A |
sz2ndItemNumber | String | sz2ndItemNumber | String | Map |
ItemIdsByItemCatalog – Mode | N/A | N/A | N/A | N/A |
N/A | N/A | GetItemMasterBy3rdItem (X4101 / DSDX4101D) | N/A | N/A |
sz3rdItemNumber | String | sz3rdItemNumber | String | Map |
This section discusses the Net Change Processor business service.
The Net Change Processor business service (J0000020) handles net change processing for both fields and value objects. The utility processes changes depending on which method is called:
Net Change by Field
The Net Change Processor utility determines the value of a field to use to update an entity. If you do not specify a new value for a field, the utility preserves the current value.
Net Change by Value Object
The Net Change Processor utility determines the value of all of the fields within a value object to use to update an entity. If you do not specify a new value for a field within a value object, the utility preserves the current value of the field within the value object.
Blank and zero are valid values for fields in the input object, and the utility preserves these values. If a field in the input object has a null value, the utility replaces the null value with the current database value.
This topic identifies the methods, signature, and value object classes for the Net Change Processor business service. Each method is discussed separately.
The method that handles net change processing for value objects of this business service is performNetChange.
The signature for the business service is:
public static E1MessageList performNetChange(IContext context, IConnection connection, ValueObject inputObject, ValueObject currentObject)
Value object classes for the business service are:
ValueObject inputObject
This value object holds the values received from a business service or published business service.
ValueObject currentObject
This value object holds the values of an entity as they exist in the database.
When you update an entity in the database, the performNetChange method determines the value of all fields within the value object that you are using. If no new value for a field within a value object is specified, the method preserves the current database value of the field. This method allows processing of value objects of different types. The performNetChange method assumes that the value object is flat. Field values of blank and zero are valid values in the input object, and the method preserves them. Only fields with a value of null in the input object are replaced with the current database value.
The method that handles net change processing for fields of this business service is performNetChangeOnFields.
The signature for the business service is:
public static Object performNetChangeOnFields(IContext context, IConnection connection, Object inputFieldValue, Object currentFieldValue)
The performNetChangeOnFields method determines the value of a field to use when you are updating an entity. If no new value for a field is specified in the input field, the method returns the current value of the field. Field values of blank and zero are valid values in the input object, and the method preserves them. Only a value of null in the input object is replaced with the current database value.
Note:
The value object net change methods operate on a flat value object class only. Processing over compound value objects is complex and negatively affects performance.The net change processor exposes the performNetChangeOnFields method to expose a less complex implementation of net change processing for use in those instances in which processing the full value object is undesirable.
This section discusses the Processing Version Processor business service.
The Processing Version Processor business service (J0000010) determines the processing option version that a business service uses when it calls a business function. The consumer of a published business service is responsible for providing the service constant key to the Processing Version Processor utility. If no version is specified in the published business service, the Processing Version Processor utility retrieves a processing option version from service constants.
This topic identifies the methods, signature, and value object classes for the Net Change Processor business service. Each method is discussed separately.
The signature for the business service is:
public static E1MessageList getProcessingVersion(IContext context, IConnection connection, InternalProcessingVersion processingVersionVO))
A business service calls the getProcessingVersion method. This method verifies that the required input parameters are specified. If all required parameters are passed, the method checks the processingOptionVersionValue parameter to determine whether it contains a value. If no value exists, the method looks up the default value in service constants using a consumer-provided key. The default value must be set up in service constants. The utility does not validate the value that it retrieves from the service constants systems. If no errors are encountered, the correct processing option version value is returned to the published business service consumer.
Note:
The Processing Version Processor utility retrieves a value from the service constants system only when a processing option version value is not provided by the consumer of the published business service.The tables in this section provide data information for value object classes.
InternalProcessAddressBook | N/A | N/A | N/A |
---|---|---|---|
Business Service VO Field Name | Data Type | Input / Output | Comments |
processingOptionVersionValue | String | Input/Output | On input, this field contains the processing option version value provided by the consumer. |
defaultValueServiceConstantKey | String | Input | This field contains the service constant key for the default processing option version to use if no processing option version is provided by the consumer. |