Running the CoexistenceAdministration Batch

Coexistence scenarios enable you to transfer content from V5 to the 3DEXPERIENCE platform. All subsequent design updates are made on the 3DEXPERIENCE platform. The transfer history is stored in mapping tables. The mapping information contained in these tables can be viewed, edited, and deleted through the CoexistenceAdministration batch.

You can also view and delete mapping objects corresponding to a 3DEXPERIENCE platform object that has been deleted. In this page, these mappings are referred to as "obsolete mapping objects".

This task shows you how to:

Before you begin:
  • Before running the CoexistenceAdministration batch, you must run a batch using a Coexistence mapping context like, for example:
    • XPDMImportExportBatch
    • DownwardCompatibility
    • FBDI
    • CoexistenceBatch

    This scenario takes the Downgrade scenario through the Coexistence batch as an example. The CoexistenceAdministration batch can also be used for V5 products imported to 3DEXPERIENCE through the DBDI batch.

  • To support databases with huge mapping objects and solve the scalability limitation, you can add the following variables to your environment file to customize the query:
    • COEXADMIN_QuerybyPackage=[number_of_objects]: Mapping objects are loaded in packages of the specified size.
    • COEXADMIN_QUERYFILTER_BY_DATE=[StartDate-EndDate], where the dates are in the DD/MM/YYYY format: Only mapping objects with a last modification date between the start date and end date are loaded.
  • To view or delete obsolete mapping objects, add the following variable to your environment file: COEXADMIN_PROCESS_OBSOLETEMAPPING=1.
    Warning: If you do not have at least read-only rights for the corresponding 3DEXPERIENCE object, the mapping object can appear as obsolete. Only activate this variable if you have full People & Organization access rights for the objects.
For more information about environment files, see Installation and Setup: Install: 3DEXPERIENCE Platform: Installing 3DEXPERIENCE Platform Services for the First Time: Installing Services One-by-One: Native Apps Installation: Configuring the Software: Configuring Environments

Select the CoexistenceAdministration Batch

This task explains how to access the Batch Monitor to select the CoexistenceAdministration batch.

  1. Access the Batch Monitor from a Session.
  2. Double-click CoexistenceAdministration.
    The CoexistenceAdministration dialog box opens.

Search Objects

This task explains how to search the objects to process with the batch.

  1. In the Batch Monitor, double-click CoexistenceAdministration.
    Warning: Access to the CoexistenceAdministration batch can be granted or revoked by your administrator through the vplm:: COEXISTENCEADMIN VPLM command. If you cannot access the batch access, the following message is displayed when double-clicking the batch name:

    You are not allowed to do this operation. Contact your administrator.

  2. Click 3DEXPERIENCE platform Object Search to open the search dialog box.

    For more information, see:

    • Running queries and Output options, see Searching for Objects.
    • Rename Criteria options, see Searching for Files (if you use the Convert to file conversion type).
    Tip: To search for objects stored in specific connectors, use Change Location for Object Selection . If you do so, 3DEXPERIENCE platform Object Search is replaced with the command to let you search for files.
    Note: The Object Types filter enables you to search for the following object types:
    • VPMRepReference
    • VPMReference
    • Model
    • Configuration Feature
    • PLMActionBase
    • ENOWSP_WorkspaceRef
    • PLMWspPVS
    • Document
    • Generic Document

  3. Click Apply to start the search.
    Your search results are displayed in the Object Selection area.
  4. Optional: To cancel the operation, including the object selection you performed, click Cancel in the search dialog box.
    A warning message is displayed. You can either choose to keep your selection by clicking Yes, or confirm the removal by clicking No.
  5. Select the objects you want to process.

    In this scenario, we are searching for the 3DEXPERIENCE object that was created by the CoexistenceBatch batch and that originated from the V5 legacy server.

    In the 3DEXPERIENCE Component area, the information displayed in the Component name box corresponds to the PLM_External_ID and/or the V_Name attributes of the 3DEXPERIENCE component.

    The Related Component area provides information about the component associated to the object you double-clicked.

    • If the component is a V5 file: the full path of the file is displayed in the Component name box.
    • If the component is stored in a V5 database: the V5 Provider ID of the component is displayed in the Component name box (and in that case, it may contain special characters).

  6. Optional: Remove the objects you do not want to process.
    1. Select the objects to be removed.
      Tip: Double-click an object if you want to display the mapping information for this object in a separate window.
    2. Click Removes the selected objects from the list .

Configure the Operations

This task explains how to configure the mapping operations.

  1. In Mapping Operation, select one of the following:
    OptionDescription
    Delete Removes the mapping for all objects in the selected context if All components related to context is activated. You must be very careful when using this option because it does not only apply to search results but also to all objects in the selected context.

    If you activated the COEXADMIN_PROCESS_OBSOLETEMAPPING variable for obsolete mapping objects:

    • In the Process On section of the dialog box, select whether you want to delete valid mapping objects, obsolete mapping objects, or both.
    • If you only select the Obsolete Mapping option, you can either select a context, or select All contexts to delete obsolete mapping objects in all the available contexts.

    Mastership Transfer

    Modifies the mastership of the objects (V5 master or 3DEXPERIENCE master).

    • V5 to 3DEXPERIENCE Master: relevant for content imported through the XPDMImportExportBatch, FBDI or Coexistence batch.
      Note: The FBDI batch only imports V5 Master content or content without any mapping.
    • 3DEXPERIENCE to V5 Master: relevant for content exported through the DownwardCompatibility or Coexistence batch.
      Note: The Coexistence batch only exports 3DEXPERIENCE Master content or content without any mapping.

      When transferring the mastership from 3DEXPERIENCE to V5, you can select the Allow Representations option to transfer the mastership for each selected representation that has been exported. If you do not select this option, mastership transfer is not allowed for 3DEXPERIENCE representations.

    • You can instantiate a 3DEXPERIENCE object under a parent object with V5 mastership or a V5 object under a parent object with 3DEXPERIENCE mastership, as the parent object with V5 or 3DEXPERIENCE mastership is not modified during the instantiation process.

    Optional: If you have transferred the selected objects in an X-PDM context (XPDMImportExportBatch), the Allow Documents option is available. It allows you to include all the attached documents to the objects you selected, including their children if the propagation is asked.

    For more information about V5 and 3DEXPERIENCE mastership, see File Coexistence and Migration User's Guide: Downward Compatibility: About Downward Compatibility.

    Mapping Extracts mapping information for components into an XML file created into the Report directory.
    Note: If no object is selected when the Mapping Extract functionality is on, the user can select “All objects in selected context(s)” to extract mapping information for all objects in selected context(s).

    You can check the "Only Exposed Mapping" option to only retrieve DMT information.

    Fill the File Name field with the name of the Mapping Extract XML file, without the .xml extension.

    If you activated the COEXADMIN_PROCESS_OBSOLETEMAPPING variable for obsolete mapping objects:

    • In the Process On section of the dialog box, select whether you want to extract valid mapping objects, obsolete mapping objects, or both.
    • The All contexts option is available for valid, obsolete, and combined (valid and obsolete) mapping objects. You can either select a context, or select All contexts to extract mapping objects from all the available contexts.
    • In the Extract XML file, obsolete mapping objects only indicate the Physical ID of the corresponding 3DEXPERIENCE object. A second XML file named listOfObsoleteMpgObjs.xml is also created in the Report directory to list the obsolete mapping objects.

    In this scenario, we want to transfer a 3DEXPERIENCE product to V5 so we select 3DEXPERIENCE to V5 Master.

  2. Optional: Choose the propagation option:
    • Enter the propagation depth in the Propagate depth to box. For more information, see Propagation Depth.

      If you set the propagation depth to 1, you can select the First instance level option. This applies the operation to the selected objects and the first level of instances only. This option is not available for other propagation depth values.

    • If you want to apply the operation to all the children of the selected object, select the All children option.
    Notes:
    • The propagation depth is only available for Mastership Transfer and Mapping Extract operations.
    • The Selected objects within selected context(s) option is activated by default unless you have selected the Delete option in the Mapping Operation list.
  3. In the Context name box, select the context defined when running a batch mentioned above.
  4. Optional: If you selected the Mapping Extract option in the Mapping Operation list, you can check the All contexts option.
  5. Optional: Click Preview to test the mapping operation.

    This option ensures that the operation complies with the mapping operation rules.

    Note: If you selected the Obsolete Mapping option for a delete operation, the listOfObsoleteMpgObjs.xml is also created in the Report directory to list the obsolete mapping objects.

Run the CoexistenceAdministration Batch

This task explains how to run the CoexistenceAdministration batch and access the report.

  1. In the Report directory box, enter the report directory or click .

    This box is mandatory and is initialized with the current or temporary directory by default.

  2. Enter the name of report in the Report Name box.
    By default, the report is named CoexistenceAdmin.xml.
  3. Optional: Select the Verbose Report check box.

    The Verbose Report is a light version of the report.

  4. Click Run to start the batch.
    If one of the above boxes is not correctly filled, the command is grayed out. When the operation is over, the CoexistenceAdministration application generates:
    • Quick result information you can access in the Processes tab.
    • A detailed XML report saved in the report directory.
  5. Click Save.
    The batch parameters are saved in an XML file.

    When saved, this file can be edited manually and used later on to run the batch directly without accessing the batch interface.

  6. To display an XML version of the global report, click Open XML Report

    This command is available only when a report has been generated.

    The XML report contains three sections:

    • Data Source
    • Metrics and Options
    • Details for Objects

    Note: Errors are listed at the beginning of the report whereas warnings are displayed under each object responsible of the warning.

    Tip: Click the plus sign in the Status column to display the attributes of the processed objects.
    Note: The table of results for Mastership Transfer replaces the Data Source and Metrics of the report when the mapping operations are Delete Mapping, Migrate Mapping and Mapping Extract.
  7. Display the light version of the global results.
    1. Access the Processes tab in the Batch Monitor.
    2. Double-click the batch execution line.

    These results indicate if each of the selected objects has been processed or not along with the result (success or failure). The report contains only text and cannot reference images, URL links, etc.

    At the end of the report, one of the following return codes will be displayed:

    • ReturnCode0 The batch ended successfully.
    • ReturnCode4 At least one object could not be processed.
    • ReturnCode8 The batch stopped.
  8. Optional: To modify your conversion parameters, first close the window and then run the batch again.
  9. Click Save to save your results in the folder of your choice.

    Important:
    • The file formats available are .txt and .xml.
    • This file is different from the one you save from the batch interface: The Save command in the Batch Monitor window lets you save the batch results (that is, the content displayed in the Results window displayed above) whereas the Save command available in the batch interface lets you save the batch parameters.

  10. Click Close to exit the Results window.
  11. Access the Processes tab to display information about the batch execution.
    Tip: When the batch has been run at least once, an XML file containing the batch parameters is generated. You can reuse these parameters next time you run the CoexistenceAdministration batch by using the Read input from parameter file... contextual command.
  12. To read the reports generated by the batch execution, access the folder c:\temp\batchID or /temp/batchID.
  13. In the CoexistenceAdministration window, double-click the processed object again to check that the ownership has been changed from 3DEXPERIENCE Master to V5 Master.