Configure the integration of OpenText PPM tasks and Service Manager RFCs

To configure this integration, perform the following steps in OpenText PPM and Service Manager:

1. Prerequisites: You must have system administrator privileges in both OpenText PPM and Service Manager.

2. Stop the PPM Server.

3. Check the OpenText PPM web services configuration. Make sure the basic authentication mode is enabled.

   1. Open the configuration file located at: <PPM_Home>\server\<PPM_Server_Name>\deploy\itg.war\WEB-INF\conf\axis2.xml, where <PPM_Server_Name> is the host name or IP address of your OpenText PPM instance.

   2. Make sure the value of InFlowBasicAuth is true.

      Note: If OpenText PPM is operating in a cluster configuration, you must update the axis2.xml file for all the nodes in the cluster.

4. Log on to Service Manager. In the cm3r table in Service Manager, add a new field for the OpenText PPM task ID, for example, PPMTaskId.

   Caution: After adding the new field, for example, PPMTaskId, make sure you use the same case-sensitive field name PPMTaskId later when necessary.

   1. In the Service Manager command line, type dbdict and press Enter.

      The Database Dictionary screen opens.

   2. In the File Name field, enter cm3r and click Search.

   3. Select cm3r in the File Name section.

   4. Click the Name column of the descriptor row.

   5. Click New Field/Key.

      The field.window pops up.

   6. Enter taskId in the Name field.

   7. Select number from the Type drop-down list and click the Add Field icon.

      The field is added to the dbdict.

   8. Locate the TaskId field and double-click it.

   9. In the field.window that pops up, enter the following:

      Table Field	Value
      SQL Name	TASKID
      SQL Type	FLOAT Note: You may also choose VARCHAR2(400).
      SQL Table	m1

   10. Click OK.

   11. Click SM Alters after confirmation of SQL Statements.

5. In OpenText PPM, check the field mapping file, which defines the field mapping from OpenText PPM to Service Manager.

   1. In the <PPM_Home>\conf\smrfc directory, copy the field mapping file sm-rfc-mapping.xml.sample under the same directory and rename the copied file to sm-rfc-mapping.xml.

   2. In the new mapping file, map the TASK_ID field to the Service Manager field that you created in step 3. The fields in the mapping file are case-sensitive.

      The sample sm-rfc-mapping.xml file in PPM Center 9.1x in fact has smField->PPMTaskID that maps to ppmField->TASK_ID. Such as:

      <field>
      <smField>PPMTaskId</smField>
      <ppmField>TASK_ID</ppmField>
      <useOnCreate>true</useOnCreate>
      <useOnUpdate>true</useOnUpdate>
      </field>

   3. In the new mapping file, verify that the Status field in Service Manager is set to initial. This value will be maintained by Service Manager after the change record is created in Service Manager.

      <field>
      	<smField>Status</smField>
      	<useOnCreate>true</useOnCreate>
      	<useOnUpdate>false</useOnUpdate>
      	<defaultValue>initial</defaultValue>
       </field>

   4. In the new mapping file, configure the default value for the Service field by changing the sample value "Applications" to your target value.

      <field>
      	<smField>Service</smField>
      	<useOnCreate>true</useOnCreate>
      	<defaultValue>Applications</defaultValue>
       </field>

   The following is an example of the sm-rfc-mapping.xml file:

   <?xml version="1.0" ?>
   <PPMSMIntegration>
   <SMRFCMapping>
       <field>
   	 <smField>PPMTaskId</smField>
   	 <ppmField>TASK_ID</ppmField>
   	 <useOnCreate>true</useOnCreate>
   	 <useOnUpdate>true</useOnUpdate>
       </field>
       <field>
   	<smField>BriefDescription</smField>
   	<ppmField>TASK_NAME</ppmField>
   	<useOnCreate>true</useOnCreate>
   	<useOnUpdate>true</useOnUpdate>
       </field>
       <field>
   	<smField>Description</smField>
   	<ppmField>TASK_DESCRIPTION</ppmField>
   	<useOnCreate>true</useOnCreate>
   	<useOnUpdate>true</useOnUpdate>
   	<defaultValue>ppm task does not have a description</defaultValue>
       </field>
       <field>
   	<smField>RequestedDate</smField>
   	<ppmField>TASK_SCHEDULED_END_DATE</ppmField>
   	<useOnCreate>true</useOnCreate>
   	<useOnUpdate>true</useOnUpdate>
       </field>
       <field>
   	<smField>RequestedBy</smField>
   	<useOnCreate>true</useOnCreate>
   	<defaultValue>FALCON, JENNIFER</defaultValue>
       </field>
       <field>
   	<smField>Status</smField>
   	<useOnCreate>true</useOnCreate>
   	<useOnUpdate>false</useOnUpdate>
   	<defaultValue>initial</defaultValue>
       </field>
       <field>
   	<smField>Service</smField>
   	<useOnCreate>true</useOnCreate>
   	<defaultValue>Applications</defaultValue>   
       </field>
   </SMRFCMapping>
   </PPMSMIntegration>

   The elements in the mapping file are described in the following table:

   Element	Description
   field	Each field element represents a field mapping between OpenText PPM and Service Manager.
   smField	Caption name of the Service Manager field. The Service Manager field must be exposed through the ChangeIIA object in the ChangeManagement Web service in Service Manager. For more information, see step 5.
   ppmField	Field name of the OpenText PPM task. For the tokens available for this element, see the notes following this table.
   useOnCreate	Specifies whether or not the field value is sent to Service Manager when an RFC is created.
   useOnUpdate	Specifies whether or not the field value is sent to Service Manager when an RFC is updated.
   defaultValue	Provides a default value for the Service Manager field. If ppmField is not specified, or the value of ppmField is null or empty, then this default value is used.

   Note:

   • You can add more mappings as needed. However, make sure that all the Service Manager fields specified in the field mapping file are exposed through the Service Manager ChangeManagement Web service. For more information, see step 5.

   • The tokens in the following table can be used in the ppmField element.

     Token	Description
     TASK_ID	Task ID
     TASK_NAME	Name of the task
     TASK_DESCRIPTION	Description of the task
     TASK_STATUS	Status meaning of the task
     TASK_PRIORITY	Priority of the task
     TASK_IS_MILESTONE	Whether the task is a milestone
     TASK_IS_MAJOR_MILESTONE	Whether the task is a major milestone
     TASK_SCHEDULED_END_DATE	Scheduled finish date of the task
     TASK_SCHEDULED_START_DATE	Scheduled start date of the task
     TASK_PATH	Path of the task in the following format: rootTask > firstLevelTask > secondLevelTask >...
     TASK_USERDATA_01 through TASK_USERDATA_20	User data fields 1 – 20 of the task
     PROJECT_ID	Project ID
     PROJECT_NAME	Name of the project
     PROJECT_REQUEST_ID	PFM request ID of the project
     PROJECT_MANAGER_USER_ID	User ID of the project manager
     PROJECT_MANAGER_USERNAME	User name of the project manager
     PROJECT_MANAGER_FULLNAME	Full name of the project manager
     PROJECT_MANAGER_EMAIL	Email address of the project manager
     SYS_USER_ID	User ID of the current user
     SYS_USERNAME	user name of the current user
     SYS_USER_FULLNAME	Full name of the current user
     SYS_USER_EMAIL	Email address of the current user

6. Make sure that the Service Manager fields specified in the field mapping file are exposed through the ChangeIIA object in the ChangeManagement Web service in Service Manager.

   In Service Manager, make sure that all the fields are listed on the Fields tab of the ChangeIIA object (for the cm3r table) in the ChangeManagement Web service. If any field is not listed, add the field name and caption name to the Field and Caption columns.

   For details on how to expose the fields of a table through a Service Manager web service, see the Service Manager online help.

   To add TaskId to the ChangeManagement WSDL:

   1. Log on to Service Manager as system administrator.

   2. Select Menu Navigation > Tailoring > Web Services > WSDL Configuration.

      The External Access Definition page opens.

   3. In the Service Name field, type ChangeManagement and click Search.

   4. In the object.name section, select ChangeIIA.

   5. In the External Access Definition section, click the Fields tab.

   6. Scroll down to the bottom of the form, and on the next available line, enter the following:

      Table Field	Value
      Field	taskId
      Caption	TaskId Note: This caption will be exposed to WSDL and must match the smField name defined in the sm-rfc-mapping.xml file.
      Type	StringType Note: OpenText PPM web service only supports DateTime type and String type.

   7. Click Save.

   8. Click OK.

   9. Repeat step 3 through step 5 if you have other new fields added into Service Manager and mapped them with PPM Center in the xml file.

      However, it is recommended you to start with just TaskId field first, once the sample xml file works, then you may consider to customize.

   10. To validate whether the field is exposed to WSDL file, launch your browser and enter the following:

       http://<SM_WEB_SERVICES_URL>:<PORT>/sc62server/PWS/ChangeManagement.wsdl

   11. In the WSDL content file, search for TaskId, it is listed under ChangeIIAKeysType, this indicates the field is exposed properly. If you do not see it exposed, then go back to Service Manager and make sure that web service is working.

7. Import the following unload files provided with OpenText PPM (present in the <PPM_Home>\conf\smrfc directory) into Service Manager:

   • PPMIntegration.unl (the integration unload file)

   • PPMIntegration_Schedule.unl (the ppmfailover schedule object file)

   Caution: If OpenText PPM is integrated with Service Manager with a PD patch, you should also import the HPSMPPMIntegration.unl unl file into Service Manager. If you already deployed 9.22.0001 patch, the unl file is also present in the <PPM_ Home>\conf\smrfc directory.

   Tip:
   • If you are using an Oracle database with Service Manager, loading of the PPMIntegration.unl file might fail the first time. Normally, reloading the file could solve the problem.
   • If you load the PPMIntegration_Schedule.unl file more than once, duplicate ppmfailover schedules will be created in Service Manager. In this case, delete the redundant ppmfailover schedules.

   1. Log on to Service Manager as system administrator.

   2. Type db in the Service Manager command line and press Enter.

      The Database Manager window opens.

   3. Right click in the Database Manager window and select Import/Load from the context menu.

      The Service Manager File Load/Import screen opens.

   4. In the File Name field, specify the file to load:

      <PPM_Home>\conf\smrfc\PPMIntegration.unl

   5. Click Load FG.

      A message stating that the records have been loaded displays.

   6. Click Back.

   7. Repeat the step c through step e for the PPMIntegration_Schedule.unl file.

8. Configure the integration table in Service Manager.

   1. Type db in the Service Manager command line and press Enter.

      The Database Manager window opens.

   2. Select ppmIntegration from the Table drop-down list and click Search.

      The form for the ppmIntegration table displays.

   3. Add the following new record to the table:

      Table Field	Value
      Id	1
      Field to Store TaskId	The value of this field must match the field name you previously added to the cm3r table for the OpenText PPM task ID (see step 3). For example, PPMTaskId. Note: If the case-sensitive field names do not match, the integration will fail.
      PPM Server URL	URL of the OpenText PPM Web services. For example: http://<Host_Name>:<Port>/itg/ppmservices/
      PPM Server Username	The user name that Service Manager uses to call the OpenText PPM Web services. This user name must include only single-byte characters. We recommend that you create a separate user account for this purpose.
      PPM Server Password	The password of the user name that Service Manager uses to call the OpenText PPM Web services.

9. If necessary, modify the Service Manager processes that will call the OpenText PPM web services to update the RFC status and task status.

   Note:
   • The code is added to the cm.close, cm.reject, cm.update.save, and cm.next.phase processes when you load the PPMIntegration.unl file. The standard Save, Close, Reject, Next Phase, and Reopen actions for RFCs invoke these processes. If you have added any other actions used to update changes (through tailoring of your Service Manager instance), you must also modify the processes that these self-defined actions will invoke.
   • For Service Manager with a PD patch deployed, you only need to modify the cm.close and change.update.save processes.

   To modify the Service Manager processes:

   1. Log on to Service Manager as system administrator.

   2. Select Menu Navigation > Tailoring > Document Engine > Processes.

      The Process Definition search screen displays.

   3. Click Search.

   4. In the Process Name field, type cm.close.

   5. In the Process Definition section, click the Final JavaScript tab.

   6. Add the following code:

      if(vars.$L_exit!="bad.val")
system.library.HPPPMSMIntegration.integratePPM();

   7. Repeat step c through step f for the cm.reject, cm.update.save, and cm.next.phase processes.

      Note: For Service Manager with a PD patch, repeat step c through step f for the change.update.save process only.

   8. If you have other processes to call OpenText PPM web services to update the RFC status and task status, make sure to add the code to them as well.

10. Edit Javascript for correct host and port for OpenText PPM.

    1. In Service Manager, select Menu Navigation > Tailoring > Script Library.

    2. In the Name field, type Integration and click Search.

    3. Find the line that contains the URL for the PPM instance (should begin with "this.location = new String"). Set the URL to

       http://<Host_Name>:<Port>/itg/ppmservices/IntegrationService

       Then the line would look like the follows:

       this.location = new String("http://<Host_Name>:<Port>/itg/ppmservices/IntegrationService")

    4. Click Save, then click Compile.

    5. Click Cancel to return to the Search screen.

    6. Repeat the step b through step d, search for Project and set the URL for it to

       http://<Host_Name>:<Port>/itg/ppmservices/ProjectService

11. Configure the ppmfailover schedule in Service Manager.

    By default, the Repeat Interval of the ppmfailover schedule is one hour. You can change the default Repeat Interval to another value. However, do not change other field values.

12. Start the ppmfailover schedule in Service Manager.

13. Open the <PPM_Home>/server.conf file, add (if not exist) and configure the following parameters:

    All parameter names begin with com.kintana.core.server. but that is not shown in the table.

    Parameter	Description, Value
    SM_RFC_INTEGRATION_ENABLED	Setting the parameter to true enables SM RFC integration with PPM Center.
    SM_USERNAME	User name that OpenText PPM uses to access Service Manager. This user name must include only single-byte characters. For example: admin.
    SM_PASSWORD	Password that OpenText PPM uses to access Service Manager. You must encrypt this password by using the kEncrypt.sh script, which is located in the bin directory of the PPM Server. Then remove #!# from the beginning and the end of the encrypted password.
    SM_URL	Host name or IP address of Service Manager. For example: http://<Host_Name>:13080
    SM_WEB_URL	Address of Service Manager Web tier. For example: http://<Host_Name>:<Port>/<WebTier_Package_File_Name>/index.do To obtain the Service Manager Web tier URL, Log on to Service Manager as system admininistrator. Click Navigation > System Administration > Base System Configuration > Miscellaneous > System Information Record. Click Active Integrations, get the WebServer URL value. By default it would be http://<Host_Name>:13080/sm/index.do.
    ENABLE_WEB_SERVICES	Setting the parameter to true enables web services.

14. Run the kUpdateHtml.sh script to apply your changes to the server.conf file. For details, see kUpdateHtml.sh.

15. Start the PPM Server.