9 Working with Softcoding

This chapter contains the following topics:

9.1 Understanding Softcoding

When you create a business service that enables JD Edwards EnterpriseOne to be a web service consumer, you can use softcoding to dynamically change the endpoint and security information that you provide in the web service proxy. You develop and test your web service against a development environment, which requires an endpoint and possibly security information. The endpoint and user credentials in the production environment will be different from those that you provide in the development environment. In the production environment, the web service proxy needs to know which machine to call for the service, and it needs to know what user credentials, if any, to pass for the external web service call. Softcoding enables you to dynamically plug in the machine name and user credentials at runtime instead of hard-coding them into the business service.

The business service requires a softcoding value at runtime. At a minimum, the softcoding value provides the endpoint for calling an external web service. If user credentials are required by the web service that is being called, the softcoding value includes security information, too. Depending on how many external web services you call, you can have many softcoding values. JD Edwards EnterpriseOne provides softcoding templates and softcoding records to help you manage multiple softcoding values.

Softcoding templates are used by developers during business service development and testing. The purpose of a softcoding template is to define what type of softcoding value is used by each business service. A softcoding template defines the expected structure of the softcoding value and serves as a communication mechanism between a developer and an administrator. Softcoding templates are not used at runtime, but they specify the softcoding value that a business service uses at runtime.

Softcoding records are created by administrators to be used by the system at runtime. A softcoding record contains the actual softcoding value that is to be used by a business service to call an external web service. Typically, softcoding records are created and maintained by an administrator. You can create many softcoding records for a business service. When you create a softcoding record, you provide a softcoding key, which is the name of the business service, a user ID or role information, and the environment.

9.2 Understanding Softcoding Applications

JD Edwards EnterpriseOne provides two applications to support softcoding. You use the Web Service Soft Coding Templates program (P953000) to configure web service softcoding templates based on web service security requirements. You use the Web Service Soft Coding Records program (P954000) to configure web service softcoding records based on web service softcoding templates. Both of these applications store XML documents.

Developers create both softcoding templates and softcoding records for testing the business service in the development environment. When testing is finished, the administrator creates softcoding records for the business service to use in the production environment. The softcoding records are based on the softcoding templates that developers created. Typically, softcoding values will be different in the development and production environments.

To improve performance, softcoding records are cached on the business services server at runtime. When you modify a softcoding record, you should also clear the jdbj service cache.

9.3 Understanding Encrypted and Dynamic Softcoding Values

Typically, you will want to encrypt your security information. Both softcoding applications (template and records) enable you identify values that are to be encrypted in the XML document. Both applications also enable you to use values that are dynamically replaced in the XML document.

9.3.1 Encrypted Values

You should consider protecting information such as passwords by encrypting the password. Both softcoding applications provide a way to encrypt information within the XML document. In the XML document, the encrypted value has an alias that is surrounded by a specific sequence of characters (_||_).

This example XML document shows a password that you might want to secure:

<username-token name="User Name" password="95T763i"
 password-type="PLAINTEXT" add-nonce="false" add-created="false"/> 

This example code shows how the XML document encrypts the secure value:

<username-token name="User Name" password="_||_maskedpassword_||_"
 password-type="PLAINTEXT" add-nonce="false"  add-created="false"/>

Both of the softcoding applications provide an area at the bottom of the form for you to enter data to be encrypted. The decryption and substitution occurs at runtime when the getSoftCodingRecord method is called. It is imperative that no logging of the softcoding value takes place between the call to getSoftCodingRecord and _setProperty.

9.3.2 Dynamically Replaced Values

Within a softcoding value, certain values can be used for dynamic replacement. Using these values in the XML means that the values are inserted and returned when getSoftCodingRecord is called. You might use dynamic replacement of values if you have multiple systems that contain the same set of user IDs and login criteria (environment and role) in both systems. You can use these values for dynamic replacement:

  • $e1user

  • $e1environment

  • $e1role

  • $ps_token

9.4 Creating Softcoding Values

A softcoding value is a segment of an XML document. The simplest softcoding includes only the machine name; no user credentials are required. The softcoding value always includes an endpoint and conditionally includes security information.

This sample code shows softcoding that provides an endpoint only:

<port-info> 
   <stub-property>  
      <name>javax.xml.rpc.service.endpoint.address</name>  
      <value>http://www.webservicex.net/WeatherForecast.asmx</value> 
   </stub-property> 
</port-info>

If the web service requires user credentials to be passed, the softcoding contains that information as well.

This sample code shows a softcoding value that provides both endpoint and user credentials:

<port-info>
 <stub-property>
   <name>javax.xml.rpc.service.endpoint.address</name>
   <value>http://dens001.mlab.jdedwards.com/Rollout/RI_AddressBookManager</value>
</stub-property>
<wsdl-port namespaceURI="http://oracle.e1.sbf.JPR01000/" 
localpart="RI_AddressBookManagerHttpPort"/>
 <runtime enabled=security>
  <security>
   <inbound/>
   <outbound>
    <username-token name="User Name" password="Password" password-type="PLAINTEXT"
add-nonce="false" add-created="false"/>
   </outbound> 
  </security>
 </runtime>
 <operations>
   <operation name='addAddressBook'>
  </operation>
   <operation name='addAddressBookAndParent'>
  </operation>
   <operation name='getAddressBook'>
  </operation>
 </operations>
</port-info>

You can use JDeveloper to create coding values with many different types of security information.

See Also:

  • Oracle JDeveloper Guide,http://www.oracle.com/technetwork/index.html .

9.5 Using Softcoding with Business Service Methods

Softcoding within a business service requires two methods. You use the method getSoftCodingRecord to retrieve the softcoding record. You use the method _setProperty to apply the softcoding record to the web service proxy. Calling _setProperty with a softcoding value overrides hard-coded values that might have been assigned in the web service proxy when it was generated.

This code sample shows how to retrieve a softcoding record and apply the softcoding value to the web service proxy:

Element softCodingValue; 

// Retrieve the softcoding record. The 'key' that is passed is a string confined
// only by methodology. It becomes part of a multipart key to retrieve a databas
// record. 
softCodingValue = SoftCodingRecordAccess.getSoftCodingRecord(context,
                                                           this.SOFTCODING_KEY);

// myPort is the Web Service Proxy 
myPort = new RI_AddressBookManagerHttpPortClient(); 

// apply the softcoding to the proxy if(softCodingValue!= null) { 

(Stub)myPort.getPort())._setProperty(oracle.webservices.ClientConstants.CLIENT_
                                                       CONFIG,softCodingValue); 
} 
else { 
   // respond to missing softcoding record. Log, set default values, and/or 
return error. 
}

9.6 Managing Softcoding Templates

This section provides an overview of softcoding templates and discusses how to:

  • Add a softcoding template prior to JDeveloper 11g

  • Add a softcoding template for JDeveloper 11g proxy

  • Update a softcoding template

  • Copy a softcoding template

9.6.1 Understanding Softcoding Templates

You use softcoding templates to create softcoding records. Using a softcoding template is productive because softcoding records have similar values, and reusing templates helps to minimize typing errors when entering record information. Softcoding templates are basically a unique name, a softcoding key that defines a relationship (the value used in the code), and the softcoding value.

A web service proxy has at least one softcoding template and one softcoding record; however, a web service proxy can have many templates and many records. The softcoding key is a grouping mechanism that is used to tie all of the related templates and records together for a given web service proxy. The softcoding key also acts as a communication vehicle for passing information from developers to administrators.

Because the development environment and the production environment are similar but not identical, a developer needs a way to communicate with an administrator. By creating a softcoding template, the developer has a way to communicate both the softcoding key the business service is expecting and the anticipated structure of the XML element.

You use the Web Service Soft Coding Templates Program (P953000) to add new templates, update existing templates, copy existing templates to create new templates, and delete templates.

9.6.2 Forms Used to Manage Softcoding Templates

Form Name FormID Navigation Usage
Work with SoftCoding Templates W953000A Type P953000 in the Fast Path. Locate and review existing templates or delete a template. Deleting a template deletes the mask fields associated with the template.
Add SoftCoding Template W953000C On Work with SoftCoding Templates, click Add. Add a new template.
Update SoftCoding Template W953000C On Work with SoftCoding Templates, click Find, select an existing template, and then click Select. Modify the key and value of an existing template. You cannot change the template name.
Copy SoftCoding Template W953000C On Work with SoftCoding Templates, select an existing template, and then click Copy. Copy an existing template to make a new template. You must change the template name.

9.6.3 Adding a Softcoding Template Prior to JDeveloper 11g

Access Add SoftCoding Template.

Figure 9-1 Add SoftCoding Template form

Description of Figure 9-1 follows
Description of "Figure 9-1 Add SoftCoding Template form"

Template Name

Enter a name for the template. JD Edwards EnterpriseOne templates are named E1_<BusinessService>, where BusinessService is the name of the business service; for example, J34A0010. Taking into consideration system updates and upgrades, you should not modify a JD Edwards EnterpriseOne template. Instead, copy the JD Edwards EnterpriseOne template and rename it using a similar naming convention.

Description

Enter text that identifies the purpose of the template.

Softcoding Key

A way to identify related templates and records for a given business service.

Value

An XML document without the header information; for example, <?xml version=1.0?>.

Mask Field

Enter a value that you want to appear in the XML document. This value is an alias for the value that you enter in the Mask Value column. The application automatically places the characters (_||_) around the alias value you enter.

Mask Value

Enter the value for which you have created an alias. This value will appear as the alias value in the XML document.

9.6.4 Adding a Softcoding Template for JDeveloper 11g Proxy

There is a standard softcoding template for 11g proxy that you can use for all the softcoding records. A generic key is used for all the WebLogic-specific consumer proxies.

Access Add SoftCoding Template.

Enter the following information:

Template Name

Enter a name for the template. The template name is a standard name for all proxies. For example, you might name a template SC4WLS to denote a proxy named Soft Coding for WLS server.

Description

Enter text that identifies the purpose of the template.

Softcoding Key

A way to identify related templates and records for a given business service. It is a unique key, such as SC4WLS.

Value

An XML document without the header information; for example, <?xml version=1.0?>. The following is an example value:

<scwls>

<endpoint>http://host:port/context-root/PortName</endpoint>

<username>username</username>

<password>_||_password_||_</password>

<policy>xyzPolicy.cml</policy>

<trustkey>abcTrustKey.xml</trustkey>

</scwls>

Mask Field

Enter a value that you want to appear in the XML document. This value is an alias for the value that you enter in the Mask Value column. The application automatically places the characters (_||_) around the alias value you enter.

Mask Value

Enter the value for which you have created an alias. This value will appear as the alias value in the XML document.

9.6.5 Updating a Softcoding Template

Access Update Softcoding Template.

Figure 9-2 Update SoftCoding Template form

Description of Figure 9-2 follows
Description of "Figure 9-2 Update SoftCoding Template form"

Use this form to change the Description, Softcoding Value, or Mask Field column of an existing template. You cannot change the template name.

9.6.6 Copying a Softcoding Template

Access Copy Softcoding Template

Figure 9-3 Copy SoftCoding Template form

Description of Figure 9-3 follows
Description of "Figure 9-3 Copy SoftCoding Template form"

Use this form to create a new softcoding template by copying an existing softcoding template. You must provide a new template name.

9.7 Managing Softcoding Records

This section provides an overview of softcoding records and discusses how to:

  • Add a softcoding record prior to JDeveloper 11g.

  • Add a softcoding record for JDeveloper 11g proxy.

  • Update a softcoding record.

  • Copy a softcoding record.

9.7.1 Understanding Softcoding Records

Softcoding records are used at runtime. They have a multipart key of user/role, environment, and softcoding key. Including environment in the key ensures that production and development entries are not used out of context. Including user/role in the key ensures that softcoding entries can be as specific as necessary. The softcoding key is the part that the business service passes to the getSoftCodingRecord method. The remainder of the information is provided by the context and is used in a hierarchical fashion so that the most specific records are used if available.

At runtime, when the business service passes J34A0010 as the softcoding key, the method looks for the following records in order and stops as soon as one is found, and returns the XML document.

In this example user KB123 has signed in with the role employee to environment PROD:

Sequence User/Role Environment Softcoding Key Softcoding Value
1 KB123 PROD J34A0010 XML document segment
2 employee PROD J34A0010 XML document segment
3 *PUBLIC PROD J34A0010 XML document segment

9.7.2 Forms Used to Manage Softcoding Records

Form Name FormID Navigation Usage
Work with Web Service Soft Coding Records W954000A Type P954000 in the Fast Path field. Locate and review existing records or delete a record. Deleting a record deletes the mask fields associated with the record.
Add Web Service Soft Coding Record W954000B On Work with Web Service Soft Coding Records, click Add. Add a new record.
Update Web Service Soft Coding Record W954000B On Work with Web Service Soft Coding Records, click Find, select an existing record, and then click Select. Modify an existing record. You cannot change the user/rode, environment, template, or softcoding key.
Copy Web Service Soft Coding Record W954000B On Work with Web Service Soft Coding Records, select an existing record, and then click Copy. Copy an existing record to make a new record. You must change the user/role, environment, and softcoding key.

9.7.3 Add a Softcoding Record Prior to JDeveloper 11g

Access the Add Web Service Soft Cording Record form.

Figure 9-4 Add Web Service Soft Coding Record form

Description of Figure 9-4 follows
Description of "Figure 9-4 Add Web Service Soft Coding Record form"

User / Role

Enter your JD Edwards EnterpriseOne user ID and role (such as *Public).

Environment Name

Enter the name of the JD Edwards EnterpriseOne environment in which you are working.

Template Name

Enter the name of the template that you want to use. For example, a JD Edwards EnterpriseOne template might be E1_J34A0010.

Soft Coding Key

Enter a value that defines the relationship of this record to other softcoding templates and records. The softcoding key is a way to tie together all related templates and records for a given web service proxy.

Soft Coding Description

Displays the text that identifies the softcoding record.

Soft Coding Value

Displays the XML document without header information, such as <?xml version="1.0"?>.

The XML document is automatically created when you click the Populate Softcoding Value button that appears on the form when you enter a valid template name.

Mask Field

Enter a value that you want to appear in the XML document. This value is an alias for the value that you enter in the Mask Value column. The application automatically places the characters (_||_) around the alias value that you enter.

Mask Value

Enter the value for which you have created an alias. This value will appear as the alias value in the XML document.

9.7.4 Add a Softcoding Record for JDeveloper 11g Proxy

Access the Soft Coding Records application (P954000).

Enter the appropriate information in the following fields:

User/Role

Enter your JD Edwards EnterpriseOne user ID and role (such as *Public).

Template Name

Enter the template name that you created for the WLS proxy, for example SC4WLS.

SoftCoding Key

Enter a unique key specific to the project.

SoftCoding Description

Enter a description of the record.

SoftCoding Value

Change the value to correspond with the project. Use the information below as an example:

<scwls>

<endpoint>https://10.177.115.221:7443/DV812/RI_AddressBookManager?WSDL</endpoint>

<username>JDE</username>

<password>_\\_password_\\_</password>

<policy>Wssp1.2-2007-Https-Usernametoken-Plain.xml</policy>

<trustkey>DemoTrust.jks</trustkey>

</scwls>

Mask Field

Enter a value that you want to appear in the XML document. This value is an alias for the value that you enter in the Mask Value column. The application automatically places the characters (_||_) around the alias value you enter.

Mask Value

Enter the value for which you have created an alias. This value appears as the alias value in the XML document.

9.7.5 Update a Softcoding Record

Access the Update Web Service Soft Coding Record form.

Figure 9-5 Update Web Service Soft Coding Record form

Description of Figure 9-5 follows
Description of "Figure 9-5 Update Web Service Soft Coding Record form"

Use this form to change the template name, softcoding description, softcoding value, or the Mask Field column on an existing softcoding record. You cannot change the softcoding key or user/role.

9.7.6 Copy a Softcoding Record

Access the Copy Web Service Soft Coding Record form.

Figure 9-6 Copy Web Service Soft Coding Record form

Description of Figure 9-6 follows
Description of "Figure 9-6 Copy Web Service Soft Coding Record form"

Use this form to create a new softcoding record by copying an existing softcoding record. When you click Copy, the Add form loads with the Mask Field column cleared.

9.8 Applying Softcoding Records

This section provides an overview of using softcoding records at design time and discusses how to configure the web service proxy with a softcoding record.

9.8.1 Understanding Softcoding Records

At design time, you add code to configure the web service proxy with the softcoding record. This involves adding import statements and using the getSoftCodingRecord API to retrieve the softcoding record. This API also replaces dynamic and encoded values if either or both of these types of values are used in the softcoding record.

9.8.2 Configuring the Web Service Proxy with a Softcoding Record

When adding code to configure the web service proxy with the softcoding record, you must add import statements to the XML document that was created by the softcoding record application. This code sample shows import statements for the business service:

import oracle.e1.bssvfoundation.util.SoftCodingRecordAccess;
import org.w3c.dom.Element;
import javax.xml.rpc.Stub;
import oracle.e1.bssvfoundation.exception.InvalidSoftCodingRecordException;

Next, you use the getSoftCodingRecord API to retrieve the softcoding record. The following sample code shows how to retrieve the softcoding record, where SAMPLE_KEY is the key that is used to retrieve the record:

Element softCodingRecord =
     SoftCodingRecordAccess.getSoftCodingRecord(context,"SAMPLE_KEY");

The getSoftcodingRecord API throws these two exceptions:

  • SoftCodingRecordAccessException

  • InvalidSoftcodingRecord Exception.

The API throws a SoftCodingRecordAccessException when a system error occurs during the retrieval of the softcoding record from the JD Edwards EnterpriseOne database. The API throws an InvalidSoftCodingRecordException when the softcoding record is not well-formed, causing a parsing error to occur when the API is converting the softcoding record into a document object model (DOM).

The last step in the process is to configure the web service proxy with the softcoding record. Be sure to check for a null condition before setting the softcoding record. The retrieved softcoding record is null if a softcoding record does not exist for the key. The following sample code shows how to check for a null condition, where the key is SAMPLE_KEY:

myPort = new WeatherForecastSoapClient();
if (softCodingRecord!= null)
{

((Stub)myPort.getPort())._setProperty(oracle.webservices.ClientConstants.CLIENT
                                     _CONFIG,softCodingRecord);
}

The EnterpriseOne SoftCoding (E1SC) code template is available in JDeveloper for inserting generated code in the business service. To place the template code into the source editor of JDeveloper, type E1SC and press the accelerator (Ctrl+Enter). This will also bring in any associated imports.