Back to Search Back to Search Results

Find Update and Create Use Case

Application Overview

When configured in a specific way, this utility will migrate content from Windchill to Titania. It will find any of the content that already exists in Windchill and update it using its Windchill Number. The Windchill Number can exist as metadata, or in the filename. If a publication does not exist in Titania, this utility will create a project, and upload the publication to that project along with all referenced content. A publication, as it pertains to this utility, is identified by any document that a title is extracted for using the titleXPath task configuration parameter.

At a high level, how this utility accomplishes that is by executing an export collection to generate output in a local folder. It then loops over each file in the folder, pulling the metadata from a HARP-META/metadata.json file. It queries Titania for the object using its Windchill Number which is retrieved from the metadata.json. If the object exists, it updates all instances of it. If it does not, and it is a publication, it creates a project based on the publication title, and uploads it along with any referenced content.

The application has the following flow.

  • Configure the application

  • Clean up the Windchill export cache

  • Archive the last export job if needed

  • Delete the export directory if needed

  • Run Windchill Export if job is set to pull or full

  • Run Windchill Upload if job is set to push, or full

    • Delete the Manifest

    • Recursively loop over each file in the export directory

      • Query Titania for objects that have the same number, or have the number in the name

      • Loop over each result

        • Recursively update referenced files

        • Update the document if an object doesn’t already exist with the same version, and iteration

      • If the object does not exist in Titania, and a title is returned from one of the titleXPath values, then create a new project and recursively upload referenced files

Running the Utility

Three batch files are provided with the application and are in the root of the extracted package. These tasks can be executed by opening a command prompt, navigating to the root folder of the extracted package, then running one of the batch files listed below, followed by a space, then the name of the task from the sync-config.xml. For example, the following text could be typed into the command line “content_sync.bat DemoFullSync” assuming a task named DemoFullSync exists in the sync-config.xml.

At a high level, what you should do is configure the application, run the pull batch file, verify the output looks good, and there is a HARP-META/metadata.json in the export directory that looks complete. If everything looks good, run the push batch file, then verify the files made it to Titania as expected. Once the utility is running as expected, the full sync batch file can be executed, without push or pull in the name.

  • content_sync - pull.bat — This file runs the utility in an export from Windchill mode. It is usually a good idea to run this first, then check the exportFolder and verify content is making it there, and there is a folder at the root level called HARP-META with a file in it called metadata.json that has the metadata for the files being migrated.

  • content_sync - push.bat — This file runs the utility in a push to Titania mode that will skip over the Windchill export and attempt to sync whatever is in the export folder. The export folder should have files to migrate and the HARP-META/metadata.json when this is executed.

  • content_sync.bat — This file runs the application in its full sync mode where content is exported from Windchill and pushed to Titania. This is the mode that will typically be run on an ongoing basis.

Configuring the Utility to use a Proxy

This utility is designed to support running with a proxy. To do this, open each of the batch files, and add the four proxy parameters.

  • proxyHost — The value of this parameter is the host name for a proxy.

  • proxyPort — The value of this parameter is the port enabled for a proxy.

  • proxyUser — The value of this parameter is the username for an authenticated proxy.

  • proxyPass — The value of this parameter is the password for an authenticated proxy.

The following graphic is an example of what the batch file will look like.

Sync Configuration File

Windchill Sync has two primary configuration files. The first is the repo-config.xml which contains the configuration information such as Windchill and Titania Delivery connection information such as the URL, username and password. The following is an example of the content of the repo-config.xml

There are two types of Repository configuration elements. One of type “windchill”, the other of type “titania-delivery”. You must have both to sync data between the two systems.

The windchill repository must have the following configuration parameters.

  • url — The URL to the Windchill server, ending in /Windchill/

  • username — The Windchill username of a user that has access to all the content that is being exported.

  • password — The password for the Windchill user.

The titania-delivery repository must have the following configuration parameters.

  • url — The URL to the Titania Delivery server ending in /admin/

  • username — The Titania Delivery user that has access to the organizations that content will be uploaded to.

  • password — The Titania Delivery user’s password.

  • organizationKey — The organization key defining the organization where new projects will be created. This key can be found in the URL when navigating to that organization in the Titania Delivery admin UI.

  • updateKey — This is typically the Windchill Number, as mapped to Titania Delivery in the sync config. It must match the metadata name of Windchill number in Titania Delivery.

  • revisionId — This is typically the Windchill revision ID, as mapped to Titania Delivery in the sync config. It must match the metadata name of Windchill revision ID in Titania Delivery.

  • iterationId— This is typically the Windchill Iteration number, as mapped to Titania Delivery in the sync config. It must match the metadata name of Windchill iteration number in Titania Delivery.

Sync Configuration File

The sync-config.xml contains the configuration information for the tasks that sync information from Windchill to Titania Delivery. The following image is an example of the Task in a sync-config.xml.

The sync configuration has a specific element hierarchy that must be preserved. A single sync-config.xml can have many Task elements. Each Task represents a specific synchronization job or task designed to pick up a certain collection of documents and migrate them to Titania in a specific way. The task can be called from the command line by it’s name. The task ties together various configuration components and triggers certain features and functions. Each task must have certain configuration components. As an example, each task must have “repository”, “collection”, and “titaniaRepository” Param elements that ties Windchill, Titania, and the collection of documents that will be migrated to Titania.

The following list describes the Task parameters available for use in the sync-config.xml.

  • repository — The name of the Windchill Repository defined in the Repo-Config.xml. This must match the name attribute of the Windchill Repository.

  • titaniaRepository — The name of the Titania Delivery Repository defined in the Repo-Config.xml. This must match the name attribute of the titania-delivery Repository.

  • collection — The name of the collection defined later in the sync-config.xml. This must match the name attribute of a collection.

  • exportToFolderPath — The path to a folder where the content will be to from Windchill.

  • mirrorRepositoryFolderPaths — This determines whether or not the Windchill Repository folder structure is recreated. This must be set to false.

  • fileReferenceAttributes — A comma delimited list of names of attributes in the XML that reference other documents.

  • exportAllReferencedGraphics — If set to false, graphics will not be exported.

  • outputJSONMetadataFile — This must be set to true It creates a file in the export directory /HARP-META/metadata.json that contains all the metadata for files being pushed to Titania.

  • nameByNumber — If set to true, the Windchill number will be used as the base name for the file being exported from Windchill. The default value is false, and if ensureFileUniqueness is also set to false, then files will be named by their Windchill filename.

  • reprocessAllProjects — If set to true, all of the projects that were updated will be reprocessed. The project level process will be called with modified dependents to prevent processing files that do not need to be processed. Then a file with the metadata attribute topdocno will be reprocessed.

  • archivePath — Before the sync task is executed, the export folder is zipped up and placed in the folder defined in this value.

  • cleanup — This should be set to true. When true this deletes the export directory before the sync job is executed.

  • titleXPath — A comma delimited list of xpaths used to extract the title of publications. If a title is extracted, a new object will be created in Titania Delivery if the file does not already exist in Titania Delivery.

  • elementsToNotResolve — A comma delimited list of element names. Documents referenced by these elements will not be exported. As an example, the xref element in DITA is a cross reference. It should have already been included in the current manual export. This configuration parameter takes precedent over downloadReferences, and resolveIfNotInTitania.

  • filenameAppender — A value to append to the filename before the extension. Windchill attributes can be enclosed in ${} and will be filled in at runtime. An example is "-${revision}${iteration}" where Windchill revision and iteration will be filled in. This may negatively impact This utilities ability to keep the most up to date version of files in Titania Delivery and should be left out. This is purely for export functionality.

  • downloadReferences — If set to true, referenced files such as topicrefs, conrefs, etc, will be downloaded for files picked up by the main QueryFilter or StateFilter.

  • resolveIfNotInTitania —This flag works in conjunction with downloadReferences. If this parameter is set to true, and downloadReferences to false, this flag triggers functionality in the pull from Windchill that will cause the utility to only export referenced components when the latest version of them does not already exist in Titania. This code attempts to query Titania Delivery to determine if the file exists and if it does, and it is the latest version, then it will not export it. If it does not exist, or the version and iteration does not match, then it will be exported. The code also queries Titania Delivery for the parent file, and makes sure that the referenced file exists with the correct version and iteration in those projects. If this code fails for some reason, then it fails safely and exports the documents.

  • reprocessInitialDelay — After all of the content migration is complete, the next step is to reprocess all the projects that content was uploaded to. This parameter is a number, in milliseconds, that the thread is delayed between the content upload, and the reprocess. This occurs once.. This is useful what a lot of content has been uploaded, to give Titania some time to finish processing the files uploaded, before the reprocessing of the projects begins.

  • reprocessDelay —After all of the content is migrated, all of the projects that were uploaded to are reprocessed. This parameter is a number, in milliseconds to delay between reprocessing each project. This delay can occur many times in a sync job, between each project that needs to be reprocessed.

  • ensureFileUniqueness — This parameter triggers code that names the objects being exported from Windchill with the following format. The name of the file from windchill, followed by a dash “-” followed by the document number. It is recommended to leave this out, or set the value to false, and set nameByNumber to true for this migration utility. If nameByNumber is set to true, it will take precedence. The default value is false.

  • fullSync — This is a deprecated parameter and is no longer in use.

  • carryOverMetadata — This parameter triggers functionality that copies existing values defined in Titania over to the new object. An example value would be “portalVisible,hideOnLandingPage,_td.profiles” where values from portalVisible, hideOnLandingPage, and _td.profiles will be carried over. If this parameter is not defined, and metadataToDrop is also not defined, then no metadata will be carried over to the new object. Only metadata mapped from Windchill, and metadata extracted from the document will show up on the new version of the document.

  • metadataToDrop — This parameter triggers functionality that copies all existing metadata fields from Titania over to the new version of the object being uploaded to Titania except for the comma delimited list of attributes in the value of this parameter. As an example, you could specify “devicename,faultcode,servicemodel” to include all other metadata fields, but drop these. If a metadata field is also defined in carryOverMetadata, that takes precedence. carryOverMetadata or metadataDrop should be used, not both.

  • maxReprocessMapWaitMinutes — This parameter defines the maximum number of minutes to watch the map reprocessing before starting the next map reprocessing. How this works is after all the projects have been reprocessed, code checks the servers content processing queue. If there are any items in the content processing queue, then the thread waits for 30 seconds, and checks again. This check occurs between each project with maps to reprocess. Once the content processing queue is empty, code queries Titania Delivery for any documents that have a value for a metadata field called topdocno. If any are found, that document is reprocessed. After the reprocess is called, code watches and checks the status of this documents reprocessing. It waits for X number of minutes (where Xis by default 20 minutes, or the number of minutes defined in maxReprocessMapWaitMinutes), or until the document processing is complete before proceeding to the next project. After that, the code waits for the content processing queue to be empty, and repeats the process on the next project. Please note: The Titania Delivery user account used for this sync job must be a member of the System Monitors group, and be able to see “Content Engine Status” in the upper right when logging into the Titania Delivery admin UI.

Mapping Metadata

The MetadataMappings contains key value pair mappings of the Windchill attribute names to Titania Delivery metadata names. The target values must match what is defined in the repo-config.xml for updateKey, revisionId, and iterationId.

Sync Configuration Collections

A collection must also be configured to provide the information needed about the collection of documents to by pushed from Windchill to Titania Delivery.

Certain information must be provided. See the following list.

  • containerName — This is the name of the Windchill container, which can be a library, product, etc.

  • containerType — This is the Windchill object type for the Windchill container.

  • objectType — This is the type of objects that will be queried for. It is a best practice to be specific as possible on this. As an example “WCTYPE|wt.epm.EPMDocument” will also retrieve documents that are of types that inherit from EPMDocument, however, sometimes custom soft attributes will not be retrievable unless you use the specific object type that has the custom soft type on it.

  • syncSubFolders — This is used in conjunction with a folder filter. If you sync objects from a folder, and this is set to true, the descendant folders will also be exported. In most cases this should be set to false, or left out.

The following are a few examples of collections.

This collection targets one document by its Windchill number.

The next example targets multiple documents by their number using a pipe “|” delimiter between number queries.

The next example targets documents that were updated today, or yesterday. The currentDate-24 can be modified to target a longer range of updated documents. This can be done by increasing the 24 by increments of 24. Windchill only supports increments of days.

The following example uses a state parameter. This parameter ensures only objects that are in the specified state will be exported. This should include the states for topics, maps, graphics, etc that will be exported by this job..

Parent topic: Configuration