User Variables

Creating Java Variables

If you are creating user variables in a non-Cloud environment, then you can use Java variables. Java string and Java table variables require you to create Java methods to capture attribute values. Sample code is provided in the topic Creating Java Methods for User Variables: Examples. While Java string and table variables require programming knowledge, you can create manual user variables without programming. To do so, you:

Create a value set starting from the Setup and Maintenance work area to validate the value entry for the variable.

A value set can either specify the list of values that users must choose from or merely specify the variable format and length. Value sets are common application components described in the Oracle Fusion Applications Functional Setup Manager Developer's Guide.
Navigate to the Create Variable page.
Enter a name for the variable. It can be any text that describes the purpose of the variable but it should not have the prefix OKC$ that is used for system variables.
Select the variable intent.

Variables can be created for either buy (procurement) or sell contracts.
Select the value set, and enter the name and the description that will help users identify the variable when they are inserting into a clause or entering its value in Contract Expert.
If you are creating a variable for buy intent, then you can make the variable updatable by vendors in the Oracle Fusion Sourcing application by selecting the Updatable by External Parties option.

Creating Descriptive Flexfield Variables

You can use the variable source Descriptive flexfield to capture the values you enter in the Contract Headers flexfield and embed those values into the clauses that make up the terms and conditions of the contract.

Use the Manage Contract Descriptive Flexfields task to define the global segments that you need to reference in your contract variable. This task in the Setup and Maintenance work area is part of the Enterprise Contracts offering in the Enterprise Contracts Base functional area.

Use the following steps to create Descriptive flexfield variables:

Navigate to the Terms Library and select the Create Variable task.
Enter the name, intent, and description for the new variable.
Select the Descriptive flexfield source and select the global segment on which the variable is based.
Assign the following job roles to users who want to use the terms library to create variables and author contracts:
- Customer Contract Manager - OKC_CUSTOMER_CONTRACT_MANAGER_JOB
- Business Practices Director - OKC_BUSINESS_PRACTICES_DIRECTOR_JOB

Descriptive flexfield variables have the following limitations:

You can use only global segments in contract variables.
In Contract Expert rules, you cannot use segments that use a value set with a Number or Character data type and use the Independent validation type.
The following data and display types are not supported:
- Drop-down List, Hidden, Date/time are not supported for any data types.
- No display types are supported for the Date Time data type.

Creating Object Variables

You can use the variable source, Object or Child object, to create variables that reference fields associated to the Sales Account and Opportunity objects in Application Composer. You can reference either standard child objects, or user-specific child objects that you define for the Sales Account or Opportunity objects.

To define Object or Child object variables, you should ensure the following:

Using Application Composer, define the fields you want to use in your variables on the Sales Account or Opportunity objects. You can use standard fields or set up user-specific fields.
Expose the new fields you created on the Sales Account or Opportunity pages.
If these changes are defined in a sandbox, they must be published before values can be used in Contract Expert rules or for printing a contract.

Creating Object Variables and Child Object Variables

You start by adding the following duty roles to the user depending on their requirements:

A user that needs to view or edit contracts that use opportunity variables must be assigned to this duty: Opportunity Administration.
A user that needs to view or edit contracts that use sales account variables must be assigned to this duty: Sales Party Review.
A user that needs to use the Terms Library, for example, to create variables or author contracts, must be assigned the following job roles: Customer Contract Manager - OKC_CUSTOMER_CONTRACT_MANAGER_JOB, Business Practices Director - OKC_BUSINESS_PRACTICES_DIRECTOR_JOB.

Use the following steps to create object variables:

Navigate to the Terms Library and select the Create Variable task.
Enter the name, intent, and description for the new variable.
Select the source as Object and select the object name as either Sales Account or Opportunity.
Enter the field name. This is the API name assigned to the field in Application Composer.
Select the Character, Date, or Number data type.
For Character data type, enter the lookup types as follows:
- For variables of type Fixed Choice List, enter the lookup type assigned to the field in Application Composer.
- For fields of the check box type, enter a lookup type that has codes defined as True (Yes) and False (No).

Use the following steps to create child object variables:

Navigate to the Terms Library.
Select the Create Variable task.
Enter the name, intent, and description for your variable.
Select source Child object.
Select the parent object name, either Sales Account or Opportunity.
Obtain the child object name from the Sales Account or Opportunity XSD file. This is the API Name assigned to the child object in Application Composer. The path to the XSD file is of the format http://server_name:port_number followed by the following strings:
- /crmCommonSalesParties/SalesPartyService?XSD=/oracle/apps/crmCommon/salesParties/salesPartiesService/SalesParty.xsd
- /opptyMgmtOpportunities/OpportunityService?XSD=/oracle/apps/sales/opptyMgmt/opportunities/opportunityService/Opportunity.xsd
Enter the child object name obtained from the XSD file on the Create Variable page.
Enter the print layout template name. As for any other table variable that could contain multiple records, you will need to specify which values captured in the child object are to be printed on the contract, and how they should be formatted. This layout will need to be obtained from the RTF file. (See the related "Printing Contract Child Object Variables: Procedure" topic.)

Note: To view or print any user-specific child object values, the user must be assigned a privilege that allows them to view the user-specific child object. For more information refer to the "Managing Security for Custom Objects" topic in the extending sales guide for your cloud service.

Object variables have the following limitations:

Object variables based on fields of type Dynamic Choice List are not supported.

Initiating Contract Creation from An Opportunity Object

You can add an action to initiate the creation of a contract using the application composer.

You can create the contract from the opportunity object as a draft contract using the following APIs: All subsequent steps of the contract, like approving and signing, will happen through Enterprise Contracts.

Public static AttributeList createContract(AttributeList contractList) throws JboException
Public static void deleteContract(String externalSourceKey, String externalReferenceKey, boolean deleteAllVersions) throws JboException

Use the following steps to add an action to the opportunity object to create a contract:

Create an object function within the server script for the opportunity object to initiate the createContract API. The sample code and helper methods are given at the end of this section.
Ensure that the AttributeList input parameter to call the createContract Java API includes the ExternalSourceKey as OPPORTUNITY and ExternalReferenceKey as Opportunity ID.
Create a new action under the Action and Links section of the opportunity object to initiate the object function created in Step 1.
Add the action on the opportunity page, for example, Create Contract.
If defined in a sandbox, publish these changes once testing is complete.

Note: Instead of invoking the API directly in the first step, you can choose to create a global function and reference from the opportunity object.

You should grant the following privileges to users who use the opportunity object:

Privilege: OKC_EDIT_CONTRACT_VIA_WEB_SERVICE_PRIV
Duty: OKC_ALL_BUSINESS_UNITS_CONTRACT_MANAGEMENT_DUTY

Contract creation from opportunity objects has the following limitations:

The contract created from the opportunity cannot use template selection rules to apply the terms template. The terms template must be the default assigned to the contract type of the contract.
Application Composer does not support disabling the Create action if a contract is already created for the opportunity object.

Sample code - Object function to create contract:

Note: The values for Business Unit and Contract Type should be replaced with those appropriate to your own instance. Vision Operations and Service Agreement are only examples for illustration purposes.

def startDate = new Date(); 
  def endDate = null; 
  def externalSourceKey = 'OPPORTUNITY'; 
  def businessUnitName = 'Vision Operations'; 
  def contractTypeName = 'Service Agreement'; 
  def deleteSuccess = 'Y'; 
  // Get ContractType Id using ContractType Name 
  def contractTypeId = 
oracle.apps.partnerMgmt.partnerProgram.util.service.con
tractsCoreTransactionSe 
rvice.ContractsCoreTransactionServiceWrapper.getContrac
tTypeIdentifier(adf.sou 
rce, contractTypeName ); 
  // Get businessUnitId Id using Business Unit Name 
  def businessUnitId = 
oracle.apps.partnerMgmt.partnerProgram.util.service.con
tractsCoreTransactionSe 
rvice.ContractsCoreTransactionServiceWrapper.getBusines
sUnitIdentifier(adf.sou 
rce, businessUnitName  ); 
// Delete all versions of the Contract using Chr Id and 
MajorVersion 
  try { 
     
oracle.apps.partnerMgmt.partnerProgram.util.service.con
tractsCoreTransactionSe 
rvice.ContractsCoreTransactionServiceWrapper.deleteCont
ract(externalSourceKey, 
 OptyId.toString(), true); 
  } 
  catch (java.lang.Exception e) { 
    deleteSuccess = 'N'; 
  } 
   
  if (deleteSuccess == 'Y') { 
   // Create Contract 
   oracle.jbo.AttributeList contractHeader = new 
oracle.jbo.NameValuePairs(); 
   // Set Contract Header Attributes 
   contractHeader.setAttribute("OrgId", 
businessUnitId); 
   contractHeader.setAttribute("StartDate", startDate); 
   contractHeader.setAttribute("EndDate", endDate); 
   contractHeader.setAttribute("ContractTypeId", 
contractTypeId); 
   contractHeader.setAttribute("CurrencyCode", 
CurrencyCode); 
   contractHeader.setAttribute("ContractNumber", Name); 
   contractHeader.setAttribute("PartyId", 
TargetPartyId); 
   contractHeader.setAttribute("ContractOwnerId", 
OwnerResourcePartyId);   
   contractHeader.setAttribute("WebServiceFlag", "N");  
 
   contractHeader.setAttribute("ExternalSourceKey", 
"OPPORTUNITY"); 
   contractHeader.setAttribute("ExternalReferenceKey", 
OptyId); 
   // Invoke createContract API to create a contract 
   
oracle.apps.partnerMgmt.partnerProgram.util.service.con
tractsCoreTransactionSe 
rvice.ContractsCoreTransactionServiceWrapper.createCont
ract(contractHeader); 
  } 
 } 
. 
. 
. 
Corrected code that should be used: 
. 
def OrgIdStr="OrgId"; 
def ContractTypeIdStr='ContractTypeId'; 
def WebServiceFlagStr='WebServiceFlag'; 
def ExternalSourceKeyStr='ExternalSourceKey'; 
def ExternalReferenceKeyStr='ExternalReferenceKey'; 
def ContractNumberStr='ContractNumber'; 
def ContractOwnerIdStr='ContractOwnerId'; 
def startDate = new Date(); 
def endDate = null; 
def externalSourceKey = 'OPPORTUNITY'; 
def businessUnitName = 'Vision Operations'; 
def contractTypeName = 'Service Agreement'; 
def deleteSuccess = 'Y'; 
// Get ContractType Id using ContractType Name 
def contractTypeId = 
oracle.apps.partnerMgmt.partnerProgram.util.service.con
tractsCoreTransactionSe 
rvice.ContractsCoreTransactionServiceWrapper.getContrac
tTypeIdentifier(adf.sou 
rce, contractTypeName ); 
// Get businessUnitId Id using Business Unit Name 
def businessUnitId = 
oracle.apps.partnerMgmt.partnerProgram.util.service.con
tractsCoreTransactionSe 
rvice.ContractsCoreTransactionServiceWrapper.getBusines
sUnitIdentifier(adf.sou 
rce, businessUnitName ); 
// Delete all versions of the Contract using Chr Id and 
MajorVersion 
try { 
oracle.apps.partnerMgmt.partnerProgram.util.service.con
tractsCoreTransactionSe 
rvice.ContractsCoreTransactionServiceWrapper.deleteCont
ract(externalSourceKey, 
 OptyId.toString(), true); 
} 
catch (java.lang.Exception e) { 
deleteSuccess = 'N'; 
} 
. 
. 
if (deleteSuccess == 'Y') { 
// Create Contract 
oracle.jbo.AttributeList contractHeader = new 
oracle.jbo.NameValuePairs(); 
// Set Contract Header Attributes 
contractHeader.setAttribute(OrgIdStr, businessUnitId); 
contractHeader.setAttribute("StartDate", startDate); 
contractHeader.setAttribute("EndDate", endDate); 
contractHeader.setAttribute(ContractTypeIdStr, 
contractTypeId); 
contractHeader.setAttribute("CurrencyCode", 
CurrencyCode); 
contractHeader.setAttribute(ContractNumberStr, Name); 
contractHeader.setAttribute("PartyId", TargetPartyId); 
contractHeader.setAttribute(ContractOwnerIdStr, 
OwnerResourcePartyId); 
contractHeader.setAttribute(WebServiceFlagStr, "N"); 
contractHeader.setAttribute(ExternalSourceKeyStr, 
"OPPORTUNITY"); 
contractHeader.setAttribute(ExternalReferenceKeyStr, 
OptyId); 
// Invoke createContract API to create a contract 
oracle.apps.partnerMgmt.partnerProgram.util.service.con
tractsCoreTransactionSe 
rvice.ContractsCoreTransactionServiceWrapper.createCont
ract(contractHeader); 
}

Use the following helper methods to collect the required information for your implementation:

Method Signature	Description
public static Long getBusinessUnitIdentifier(Object context*, String businessUnitName)	Get business unit ID for a given business unit name.
public static Long getContractTypeIdentifier(Object context*, String contractTypeName) Note: Object context is either EntityImpl or ViewRowImpl object.	Get contract type ID for a given contract type name.
public static Long getPersonIdentifier(Object context*, Long resourceId)	Get person ID for a given resource ID.
public static AttributeList createContract(AttributeList contractHeaderList)	Create contract with only header, party and party contact entities.
public static void deleteContract(String externalSourceKey, String externalReferenceKey, boolean deleteAllVersions)	Delete a contract using the external keys.
public static AttributeList findContract(String externalSourceKey, String externalreferenceKey)	Find a contract using the external keys.
public static void deleteContract(Long contractId, Long majorVersion) (Existing PRM API)	Delete a contract using the contract ID and version.

Viewing a Contract from an Opportunity

You can add a link to view the contract from an opportunity using Application Composer. From the opportunity, you can access the contract through URL navigation.

Use the following steps to add an action to the opportunity object to create and view a contract:

Create a link in Application Composer on the opportunity object, for example, Preview Contract.
Return the URL for navigating to the Contracts AuthoringMainFlow in the groovy script editor for the link.
Add the link to the Opportunity page.
If defined in a sandbox, publish these changes once testing is complete.

You should grant the following privileges to Opportunity users:

The entitlement View Opportunity must be assigned the getOpportunity resource.
Users viewing contracts from an opportunity must be granted permission for viewing the AuthoringMainFlow taskflow:
- Privilege: OKC_VIEW_CONTRACT_PRIV
- Duty: OKC_ALL_BUSINESS_UNITS_CONTRACT_INQUIRY_DUTY or OKC_CONTRACT_INQUIRY_DUTY

Creating and viewing a contract from an opportunity has the following limitations and known issues:

Performing a save or roll back is not recommended in the Application Composer groovy script. The user must click Save on the Opportunity page to persist the user-specific fields, ContractId and MajorVersion, on the Opportunity object.
Application Composer does not support identity switch when invoking a web service for GPA policy.
The standard for building the URL for navigating to a taskflow is to call the getURL() API on the oracle.apps.fnd.applcore.patterns.uishell.context.UIShellContext. Application Composer does not support the UIShellContext class on the groovy script.
fileDownloadActionListener is not supported in Application Composer, so the Preview Contract PDF file cannot be downloaded by clicking a button on the Opportunity page. The alternative approach is to drill down to the Contracts Application using URL navigation.

How User Variables Are Used in a Contract

The user variables that you create can be:

Inserted in the Contract Terms Library clauses
Inserted into individual nonstandard clauses created by contract authors during contract authoring.
Used in Contract Expert rule conditions

When contract authors run Contract Expert during authoring, they are prompted to enter the variable value. The value is automatically substituted in the contract terms and any rules where the variable is used are evaluated.

Descriptive flexfield variables and Application Composer objects have a similar behavior when they are inserted into a clause text and the variable value is embedded. A contract that uses a terms template containing a clause that uses the variable takes the value entered in that field and embed it into the variable value. When previewing or printing the contract, the variables are resolved and the values printed in the document. For variables based on descriptive flexfields, the value is sourced based on the segment name and the attribute number. The ContractSample.xml file exposes the contract header descriptive flexfield so that the values are formatted and used correctly when printed with your own layout templates. For variables based on Application Composer objects, variable resolution uses the opportunity unique ID and the primary party ID to source the opportunity and sales account variable values.

This approach has the following limitation: if you create a contract from the contracts work area, and if the terms template associated with the contract contains variables sourced from the Opportunity object, no variables in the terms template are resolved because the contract was not created from an opportunity and the reference information cannot be retrieved.