A Utility Business Services

This appendix contains the following topics:

A.1 Understanding Utility Business Services

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.

A.1.1 Implementing Utility Business Services

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.

A.2 Entity Processor Business Service

This section discusses the Entity Processor business service.

A.2.1 Understanding 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.

A.2.2 Implementation Detail

This topic identifies the methods, signature, and value object (VO) classes for the Entity Processor business service.

A.2.2.1 Methods

Methods for the business service are:

  • processEntity(Entity)

  • processEntity(InternalEntityUtility)

A.2.2.2 Signature

The signature for the business service is:

Public static E1MessageList processEntity(IContext context, IConnection, 
connection, ValueObject inputObject, ValueObject currentObject)

A.2.2.3 Value Object Classes

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.2.2.4 Functional Processing

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:

  1. Address Number

  2. Long Address Number

  3. 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.

A.2.3 Value Object Classes

The tables in this section provide data information for value object classes.

A.2.3.1 Business Service Value Object

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

A.2.3.2 Published Reusable Value Object

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

A.2.3.3 Output from Business Service to Published Value Object

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

A.3 GL Account Processor Business Service

This section discusses the GL Account Processor business service.

A.3.1 Understanding 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.

A.3.2 Implementation Detail

This topic identifies the methods, signature, and value object classes for the GL Account Processor business service.

A.3.2.1 Methods

Methods for the business service are:

  • processGLAccount(InternalGLAccountUtility)

  • processGLAccount(ProcessGLAccount)

A.3.2.2 Signature

The signature for the business service is:

Public static E1MessageList processGLAccount(IContext context, IConnection 
connection, ValueObject inputObject, ValueObject currentObject)

A.3.2.3 Value Object Class

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.3.2.4 Functional Processing

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:

  1. Account ID

  2. Account Long ID

  3. 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.

A.3.3 Value Object Classes

The tables in this section provide data information for value object classes.

A.3.3.1 Business Service Input and Output Interface

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.

A.3.3.2 Published Reusable Value Object

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

A.3.3.3 Published to Business Service Value Object

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

A.4 Inventory Item ID Processor Business Service

This section discusses the Inventory Item ID Processor business service.

A.4.1 Understanding 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.

A.4.2 Implementation Detail

This topic identifies the methods, signature, and value object classes for the Inventory Item ID Processor business service.

A.4.2.1 Methods

Methods for the business service are:

  • processInventoryItemId (InternalInventoryItemId)

  • processInventoryItemId (ProcessItemCustomer)

  • processInventoryItemId (ProcessItemSupplier)

A.4.2.2 Signature

The signature for the business service is:

Public static E1MessageList processInventoryItemID(IContext context, 
IConnection connection, ValueObject inputObject, ValueObject currentObject)

A.4.2.3 Value Object Classes

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.

A.4.2.4 Functional Processing

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:

  1. ItemCrossReference

  2. FreeForm

  3. ItemId

  4. ItemProduct

  5. 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.

A.4.3 Value Object Classes

The tables in this section provide data information for value object classes.

A.4.3.1 Business Service Value Object

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

A.4.3.2 Published Reusable Value Object

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

A.4.3.3 Input Business Service Processing

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

A.5 Net Change Processor Business Service

This section discusses the Net Change Processor business service.

A.5.1 Understanding 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.

A.5.2 Implementation Detail

This topic identifies the methods, signature, and value object classes for the Net Change Processor business service. Each method is discussed separately.

A.5.2.1 Method

The method that handles net change processing for value objects of this business service is performNetChange.

A.5.2.2 Signature

The signature for the business service is:

public static E1MessageList performNetChange(IContext context, 
IConnection connection, ValueObject inputObject, ValueObject currentObject)

A.5.2.3 Value Objects

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.

A.5.2.4 Functional Processing

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.

A.5.2.5 Method

The method that handles net change processing for fields of this business service is performNetChangeOnFields.

A.5.2.6 Signature

The signature for the business service is:

public static Object performNetChangeOnFields(IContext context, 
IConnection connection, Object inputFieldValue, Object currentFieldValue)

A.5.2.7 Value Objects

This utility business service has no specific value objects.

A.5.2.8 Functional Processing

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.

A.5.3 Value Object Classes

This utility handles all objects that extend the value object super class. Because the utility is written to handle generic objects, the utility does not have any specific value object mappings.

A.6 Processing Version Processor Business Service

This section discusses the Processing Version Processor business service.

A.6.1 Understanding 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.

A.6.2 Implementation Detail

This topic identifies the methods, signature, and value object classes for the Net Change Processor business service. Each method is discussed separately.

A.6.2.1 Method

The method for the business service is getProcessingVersion.

A.6.2.2 Signature

The signature for the business service is:

public static E1MessageList getProcessingVersion(IContext context, 
IConnection connection, InternalProcessingVersion processingVersionVO))

A.6.2.3 Value Object

The value object for the business service is InternalProcessingVersion.

A.6.2.4 Functional Processing

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.

A.6.3 Value Object Classes

The tables in this section provide data information for value object classes.

A.6.3.1 Business Service Value Object

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.