2 Installing and Configuring
CAD for Cloud Integration

Prerequisites

Before you run the WSS Configurator tool, ensure the following:

1. OWSM is installed in the Agile domain as described in "Installing Oracle Web Services Manager".

2. The attribute CLOUD_CAD_INTEGRATION_ENABLED in agileDomain/config/ CloudIntegration.properties is set to TRUE.

3. Unzip wssconfigurator.zip (in agileDomain/tools) into the same location agileDomain/tools/wssconfigurator.

4. Grant Execute privilege on shell script wssconfigurator.sh in folder wssconfigurator.

A. Attach Client Policy and Generate Key-pair using an Alias

Run the WSS Configurator tool to attach the Client Policy and generate a key-pair. The certificate generated here - CADforCloudSAMLSignKey - is displayed in the key-store under stripe OWSM in the WebLogic console.

It is also exported to the folder where the WSS Configurator tool is unzipped.

By default, it is issued by "Demo CA" ('Demo' Certifying Authority).

1. Run WSS Configurator tool under agileDomain/tools/wssconfigurator/ wssconfigurator.cmd for Windows and wssconfigurator.sh for Unix.

2. Select option 1 to enable Web Services Security.

3. Enter server URL, username, and password to connect to the WebLogic Server.

4. Select option 3 from the CAD for Cloud policy.

5. From the 3 options, select option 2 in the CAD-for-Cloud Client Policy: oracle/wss_saml_token_bearer_over_ssl_client_policy.

6. Enter the subject name and key-bit size, and press Enter.

   1. Subject name should be as follows: CN=MyCommonname, OU=OracleUnit, O=MyOrganization, L=MyCity, ST=MyState, C=MyCountry

      For example, CN=slc09pnr.us.oracle.com, OU=OracleUnit, O=Oracle, L=Redwood City, ST=California, C=US

   2. Oracle recommends using 2048 for key-bit size for the certificate.

   3. A certificate with an alias - CADforCloudSAMLSignKey - is generated and exported to the folder where the WSS Configurator tool is unzipped, usually in agileDomain/tools/wssconfigurator.

   4. The client policy is configured successfully. Two entries are added to agile.properties in agileDomain/config/ (near the end of the file).

      WSS.ClientPolicy.CADforCloud=oracle/wss_saml_token_bearer_over_ssl_client_policy
      WSS.CADforCloudSAMLSignKey.alias=CADforCloudSAMLSignKey
      

B. Generate and Export Certificate Signing Request

Run WSS Configurator tool to generate and export a Certificate Signing Request (CSR) based on the certificate that was generated in task A.

1. Launch WSS Configurator tool on Agile Server.

2. Select option 4 to manage OPSS OWSM key-store, and press Enter.

3. Enter server URL, username, and password to connect to WebLogic Server.

4. For the second prompt, select option 3 to export the certificate, and press Enter.

5. For the third prompt, select option 2 (Certificate Signing Request).

   1. Fill in the alias to be exported. Enter CADforCloudSAMLSignKey, which was generated in task A.

   2. For the CSR to be exported, fill in the absolute path and the CSR file name (and extension). For example: C:\Certificate\C4CSAMLSignKey.csr.

C. Request Signature for the Certificate

To request a signature for the certificate:

1. Send the generated CSR to your Certifying Authority (CA) to request a CA-signed certificate.

The generated certificates:

1. Root Certifying Authority certificate

2. Intermediate Certifying Authority certificate and the CA-signed certificate are then used by the Cloud Operations team, who must import the chain of certificates into the OWSM key-store of Product Development.

D. Import Certifying Authority-signed Certificate into Agile PLM Key-store

By default, the certificate (the alias is CADforCloudSAMLSignKey) generated earlier (in task A) is issued by "Demo CA". Import the CA-signed certificate as a certificate with the same alias - CADforCloudSAMLSignKey. Then its certificate type changes from "Demo CA-signed Certificate" to "Public CA-signed Certificate".

First, copy the CA-signed certificate (that was returned from the certifying authority) to the local file system of Agile Server. Run WSS Configurator tool to import the CA-signed certificate, as in this procedure.

To import the CA-signed certificate:

1. Launch WSS Configurator tool on Agile Server.

2. Select option 4 to manage OPSS OWSM key-store, and press Enter.

3. Enter the server URL, username and password to connect to WebLogic Server.

4. For the second prompt, select option 2: Import Certificate.

5. For the third prompt, select option 1: Certificate.

   1. Fill in the alias to be imported. Enter CADforCloudSAMLSignKey which was generated earlier, and press Enter.

   2. Fill in the absolute path and the CA signed certificate to be imported.
      For example: /opt/Certificate/slc07die.crt

6. Enter option 6: Exit.

E. Configure SAML Issuer Name to Enhance Security

For security reasons, you must set up a separate SAML issuer to overwrite the default value www.oracle.com. SAML issuer name can be any meaningful string, typically the host name of the client instance or company-specific information.

To configure the SAML Issuer Name:

1. Go to agileDomain/config/ and open the CloudIntegration.properties file.

2. Edit the attribute SAML_ISSUER_NAME to overwrite the default value.

3. Restart the Agile PLM Server.

   
   

   Note: SAML_ISSUER_NAME cannot be left empty. The value is case-sensitive.

   
   

F. Obtain Distinguished Name from the CA-Signed Certificate

You must obtain the Distinguished Name (DN) from the Certifying Authority (CA)-signed certificate using the JDK tool. Provide the DN in the service request for the Cloud Operations team, who will add it to the configured SAML issuer.

To obtain the Distinguished Name:

1. Copy the CA-signed certificate to a local drive.

2. Open a command line and run the following command:

   keytool -printcert -file <full name with certificate path>

   Example: keytool -printcert -file /opt/certs/slc07die.crt

   
   

   Note: if "keytool" cannot be recognized, go to $JAVA_HOME/bin to run it again.

   
   

3. Copy and save the Owner value.

   Example:

   keytool -printcert -file /opt/certs/slc07die.crt

   Owner: CN=slc07die.us.oracle.com, OU=Oracle PLMA FOR TESTING PURPOSES ONLY, O=Oracle Corporation, L=Redwood City, ST=California, C=US

   Issuer: CN=DigiCert SHA2 Secure Server CA, O=DigiCert Inc, C=US

   Here the DN for the certificate is CN=slc07die.us.oracle.com, OU=Oracle PLMA FOR TESTING PURPOSES ONLY, O=Oracle Corporation, L=Redwood City, ST=California, C=US.

G. Import Certificate Chain and Configure SAML Issuer and DN List in Oracle Applications Cloud

Based on the details provided in your service request, using WebLogic Scripting Tool (WLST), the Cloud Operations team performs these tasks:

• Import the signed certificates as trusted certificates into the OWSM key-store of Fusion Applications Cloud

• Configure the SAML issuer along with the DN list.

Raise a service request and include the following:

1. Signed certificates.

2. SAML issuer name and DN list.

3. Point of Delivery (POD) details.

4. My Oracle Support note IDs:

   1. Note 2404754.1 for certificates.

   2. Note 2427496.1 for configuring SAML issuer and DN List

   Signed certificates to be attached contains Root CA, Intermediate CA, and CA-signed certificate you received earlier. (See C. Request Signature for the Certificate.) SAML issuer name is the value you configured in CloudIntegration.properties file.

   
   

   Tip: If there are multiple Distinguished Names (DN), separate each one with a semicolon (;). Be sure to provide the complete DN list. If the SAML issuer name and DN was added previously, WLST will overwrite the DN list of the SAML issuer. For example, if SAML issuer CADforCloud already has "J" as DN and you want to add "K" as the DN, provide "J;K" as DN list, not just "K".

   
   
   
   

   Note: Oracle recommends that you enter the DN list in a single line within the file, then upload it to the SR. This is to avoid any data loss during copying and pasting.

   
   

H. Validate Secure Web Services Connection

Test to make sure web-services calls are working without any failures, by executing the CAD for Cloud functions in Agile PLM.

If the access denied ("oracle.wsm.security.WSIdentityPermission" "resource=AgilePLM" "assert") exception shows while testing the CAD for Cloud functions with this client policy, follow these steps to fix it in Agile PLM.

1. Set WLST_EXT_CLASSPATH

   1. Example for Windows: c:/> set WLST_EXT_CLASSPATH=<AgileHome>\agileDomain\lib\wlsauth.jar

   2. Example for Unix: $ export WLST_EXT_CLASSPATH=<AgileHome>/agileDomain/lib/wlsauth.jar

2. Open the WebLogic Scripting Tool, go to <weblogic _home>\oracle_common\common\bin\, run wlst.cmd for windows and wlst.sh for Unix.

3. Connect to the WebLogic domain using the following command: wls:/offline> connect (username, password, url). Enter appropriate values for the username, password and URL fields.

   • username: user to log in to WebLogic Server

   • password: password of the user

   • url: weblogic server url, the format is t3(s)://<server>:<port>.

4. Execute the following two commands to add permission:

   • grantPermission(permClass="oracle.wsm.security.WSIdentityPermission",permTarget="resource=AgilePLM", permActions="assert")

   • grantPermission(codeBaseURL="file:${common.components.home}/
     modules/oracle.wsm.common_${jrf.version}/wsm-agent-core.jar", permClass="oracle.wsm.security.WSIdentityPermission", permTarget="resource=AgilePLM", permActions="assert")

To configure the Product Development external application:

1. In Java Client Administrator, navigate to System Settings > Reference Objects Management.

2. Double-click the Applications node and, in the window that appears, click New.

3. Fill in the required fields.

   
   

   Example values for the required fields:

   • Name: Oracle Cloud

   • API Name: This API Name is also used later as the value for CLOUD_INTEGRATION_APPLICATION_APINAME property in CloudIntegration.properties file.

   • Host Base URL: Use the Domain URL of the Cloud Instance. Ensure that the Host Base URL includes the protocol and not the context path or port.

   • Port: Enter port number of the Cloud Instance.

   • Virtual Path: Enter the virtual path.

   • User ID: If SAML is configured to use Agile login user authentication, leave this field blank. If you are using common user authentication to access PD Cloud, provide that user name.

   • Password: Use the active user password

   • Enabled: Select Yes in the drop-down list to enable the application.

   • Include User ID of active user: Select Yes in the drop-down list.

4. Click Save.

To define attribute mappings:

Attribute mappings are automatically created when the subclass is created.

• Navigate to Settings > System Settings > Reference Objects Management.

• Double-click the Mapping node to display the Mappings window. The defined Reference Object subclasses are displayed in a table.

• Double-click the table row of the subclass you want to modify. The Mappings window appears.

• Under Attribute Mappings, you can modify the Web Services attribute.

• When you are finished in the Mapping dialog, click OK.

In Administrator, you can modify the existing Reference Object Attributes (Name, Description, Current Status) and save the changes. When a user logs in as a CAD Engineer (Design Engineer) and searches for PD Items on Publish Workspace, the modified Reference Object Attributes are visible.

For more details on reference objects and mappings, refer to Agile Product Lifecycle Management Administrator Guide, Rel. 9.3.6, in the chapter ”Administering Reference Objects”.

Template of C4C_Mapping.xml Configuration File

An understanding is required of Product Development Cloud's Item Class,
EFF CategoryContext (Attribute Group), EFF Attributes, Change Class, DFF Context Segment, and DFF attributes.

• PD Item Class: 1. Class Name; 2. Internal API name

• EFF CategoryContext: 1. Display Name; 2. Code; 3. API Name

• EFF Attribute in a CategoryContext: 1. Name; 2. Code; 3. API Name

• PD Change Class: 1. Class Name; 2. Internal API name

• DFF Context Segment: 1. Context Type

• DFF Attribute in a Context Type: 1. Name; 2. Code; 3. API Name

The PD Cloud administrator must:

• Complete configuration of Product Development Item EFF and Change DFF attributes if enabled;

• Deploy the EFF/DFF configuration in PD Cloud;

• Regenerate the WS Java Client stub jars; and,

• Package them in Agile PLM's appplication.ear file.

For more details on re-generating jar files, refer to Generating PD Cloud WS Java Client Stub Jars.

The default mapping file C4C_Mapping.xml is shipped with Agile PLM installation with CAD to Cloud mapping disabled.

Notes to C4C_Mapping.xml default template file:

If <MappingEnabled> is configured to be False, the C4C_Mapping is disabled: the loading and validation of C4C_Mapping.xml configuration will be skipped and ignored.

<PDItemClass> defines a Fusion Item Class and has attributes and one or more <CategoryContext> elements.

• Attribute (classname = "CADItem1"): ”CADItem1” is Item Class name

• Attribute (classinternalapiname = "CADItem1"): ”CADItem1” is Item Class Internale API name

• Attribute (uid = "caditem1clz"): ”caditem1clz” is user specified UID for PD Item in mapping;

• One or more <CategoryContext> element configured for this Item class.

<CategoryContext> defines EFF Attribute Context that associates with Item class

• Attribute (categorytype = "Caditem1"): "Caditem1" is the generated WS Item EFF category java classname, and can be found in package ”com\oracle\xmlns\apps\scm\productcatalogmanagement\advanceditems\flex\egoitemeff\item\categories” of WS stub jar file.

• Attribute (contexttype = "Caditemcontext1APIName"): ”Caditemcontext1APIName” is EFF Attribute context API name, and can be found in package ”com\oracle\xmlns\apps\scm\productcatalogmanagement\advanceditems\flex\egoitemeff\item\contexts” of WS Stub jar file.

• Attribute (uid = "caditem1.caditemcontext1apiname"): UID for CategoryContext in format of category + ”.” + context.

<DesignClass> defines Agile Design subclasses and it's table supported. Currently only ”TitleBlock” and ”PageTwo” tables are supported.

• Attribute (subclassname = "C4CDesign"): Design Subclass API name

• Attribute (uid ="c4cdesign"): UID for Design Subclass

• One or more <Table> elements;

<Table> defines Design subclass table supported in Design class.

• Attribute (tablename="TitleBlock"): either ”TitleBlock” or ”PageTwo”

• Attribute (uid="tb"): UID for table in <DesignClass>

< PDItemAttribute> defines Fusion Item attributes that are used in mapping configuration. It uses the following attributes.

• uid: UID for specified Item attribute. It is recommended to use syntax ”caditem1clz.caditem1.caditemcontext1apiname.cadattr1apiname” for EFF attribute. They are corresponding UID of Item class, CategoryContext, and attribute API name; or ”caditem1clz.itemnumber" for non EFF attribute (not used in current release) that are corresponding UID of Item Class, and attribute API name;

• type: Data type of Item Attribute. String, Numeric, and SingleList attributes are supported for mapping.

• name: attribute API name of Item (case sensitive). Recommend no special character and low case for first letter in EFF attribute API name

• eff: to specify if this is EFF attribute (true/false).

< PDItemAttributes> contains one or more < PDItemAttribute> elements in this configuration file for mapping.

< DesignAttribute> defines Agile Design subclass attributes that are used in mapping configuration, and has the following attributes:

• uid: UID for specified Agile Design subclass. It is recommended to use syntax "c4cdesign.tb.description" that are corresponding to UID of defined DesignClass, Table and attribute API name;

• type: Data type of Design attribute. String, Numeric, and List attributes are supported for mapping.

• name: attribute API name of Design (case sensitive)

< DesignAttributes> contains one or more < DesignAttribute> elements in this configuration file for mapping.

<ChangeClass> defines Agile Change object subclasses and it's table supported. Currently only Cover Page and ”PageTwo” tables are supported.

• Attribute (subclassname = "DFCO"): Change Object Subclass API name

• Attribute (uid ="dfco"): UID for Change Subclass

• One or more <Table> elements;

• <Table> defines Change object subclass table supported in Change class.

• Attribute (tablename="TitleBlock"): either ”TitleBlock” or ”PageTwo”

• Attribute (uid="cp"): UID for table in <ChangeClass>

<ChangeAttribute> defines Agile Change subclass attributes that are used in mapping configuration, and has the following attributes:

• uid: UID for specified Agile Change subclass. It is recommended to use syntax "dfco.cp.number" that are corresponding to UID of defined ChangeClass, Table and attribute API name;

• type: Data type of Design attribute. String, Numeric, and List attributes are supported for mapping.

• name: attribute API name of Design (case sensitive)

<ChangeAttributes> contains one or more <ChangeAttribute> elements in the configuration file for mapping

<PDChangeClass> defines a Fusion Change Class and has attributes and one or more <ContextSegmentDFF>

• Attribute (classname="C4C_PD_CO_TYPE"): "C4C_PD_CO_TYPE" is Change Class Type names

• Attribute (classinternalapiname = "C4C_PD_CO_TYPE"): "C4C_PD_CO_TYPE" is Change Class Internal API names

• Attribute (uid = "c4cpdcotypeclz"): "c4cpdcotypeclz"is user specified UI for PD Change in mapping

<ContextSegmentDFF>

• Attribute (contexttype = "C4cPdCoType"): "C4cPdCoType" is the API name for context in Context Sensitive Segments for Change Order Type - C4C_PD_CO_TYPE

• Attribute (uid = "ctxdff"): "ctxdff"is user specified UI for context in mapping

<PDChangeDFFAttributes>

• uid: UID for specified PD Change DFF attribute. It is recommended to use syntax ”c4cpdcotypeclz.ctxdff.c4cgsattrtext1” for DFF attribute. They are corresponding UID of Change class, ContextSegmentDFF, and DFF attribute API name;

• type: Data type of Change DFF Attribute. String, Numeric, and SingleList attributes are supported for mapping.

• name: attribute API name of Change DFF (case sensitive). Recommend no special character and low case for first letter in EFF attribute API name

• dff: to specify if this is EFF attribute (true/false), default: true.

< AttributeMap> defines the mapping between Design attribute and Item Attribute, and has the following attributes:

• designattribute/changeattribute: one of UID defined in <DesignAttributes>/<ChangeAttributes>;

• pditemattribute/pdchangedffattribute: one of UID defined in < PDItemAttributes>/<PDChangeDFFAttributes>

< MappingEntry> defines mapping entry. It contains one or more <AttributeMap> element.

type: mapping type. Currently "RedlineEFF" and "MapChangeDFF" types are supported.

name: user specifies mapping names

Loading, Parsing, and Validating C4C_Mapping.xml File

The C4C_Mapping.xml file can be found in the folder AGILE_DOMAIN\config, and is loaded, parsed, and validated during Agile Server startup. The statuses of loading, parsing and validating are logged in a log file in the folder

AGILE_DOMAIN\servers\YOURAGILESERVERNAME\logs\c4cmapping.

The log file name is in the format of status-MM-DD-YYYY.log and the example here is status-06-22-2018.log, where:

• DD - day (digits) of Agile PLM server startup day

• MM - month (digits) of Agile PLM server startup day

• YYYY - years (four digits) of Agile PLM server startup day.

The log file name and its folder is printed out in WebLogic Server console:

Agile log filename: C:\builds\agile9367\wls\apcm\agileDomain\servers\
SLC15ALJ-AgileServer\logs\c4cmapping\status-06-22-18.log

There are NO error messages while performing C4C mapping, file loading, parsing, and validating, as this is only for Agile Administrator configuration task.

If CAD integration is not enabled (CLOUD_CAD_INTEGRATION_ENABLED is FALSE in CloudIntegration.properties), no loading, parsing, or validation for C4C_Mapping.xml will be performed, and no logging status.

If CAD integration is enabled (CLOUD_CAD_INTEGRATION_ENABLED is TRUE in CloudIntegration.properties) and MappingEnabled in C4C_Mapping.xml is FALSE, no further loading, parsing and validation is performed with log status of "MappingEnabled: disabled"

In WebLogic Server console, while starting Agile PLM, "ERROR: C4C_Mapping.xml configuration file is not valid. Please contact your Agile Administrator!" may be found in the console if mapping configuration file is INVALID. The status logs will be appended to the end of the same log file if Agile server is started, restarted multiple times within the same day.

Here is one sample log file, status-06-22-18.log", for starting and restarting Agile server with the same C4C_Mapping.xml file, with only the difference of WS Java stub jars without EFF configured. Let's briefly go through some of them:

Status of Loading, Parsing, and Validating

• CADforCloud Integration: enabled

• MappingEnabled: enabled

• Configuration file is invalid.

Validation errors will be logged in the log file.

The mapping file will not be loaded and parsed any further if CAD to Cloud integration and MappingEnabled are disabled. Agile Administrator needs to resolve any configuration error for CAD to Cloud publishing, if MappingEnabled is enabled.

During Agile server startup, there is NO validation check for classname and classinternalapiname while validating PDItemClass. The Administrator must make sure that the correct classname and classinternalapiname for PDItemClass are configured and case sensitive. If they are not configured correctly, the error will ONLY be reported during the CAD for Cloud Publish (EFF redlining at runtime). The names of EFF Category, Context, and attribute will be validated by examining if the corresponding Java classes or attributes can be found in the WS stub jar file. Please note that they are the corresponding API names (case-sensitive) in PD Cloud configuration.

Validation of Designclass, table and its attribute will be performed with Agile live data in DesignClass, DesignAttribute, and DesignAttributes. This will ensure that Design subclass is defined and enabled. The table configured is either Title Block or Page Two, and existing attributes enabled with the correct data type.

Validation for AttributeMap and MappingEntry will check if designattribute and pditemattribute are defined early and if they are valid with the same data type between Design attribute and PD Item EFF attribute.

Publish the Mapped Design TB / P2 Attributes to PD Item EFF Attributes

If C4C Mapping is enabled in C4C_Mapping.xml and one or more mapping is invalid, this error message appears: "Invalid EFF Mapping configuration. Please contact Agile Administrator." This message appears in the business object's Tab Header area when clicking Validate or Publish in Publish Workspace. No other validation or publishing will be performed until the error is corrected.

If C4C Mapping is valid, it will continue with other validations. Publish EFF Attributes will be performed after publishing Item Relationship, and will report error in Details, if any. If not, it will show Completed in the Status of Publish Workspace.

If Change Class mapping is enabled in C4C_Mapping.xml, loading, parsing and validating C4C_Mapping.xml is similar to above and the mapped Change Cover page/P2 attributes will be published to PD Change DFF attributes.