ThingWorx Utilities Installation Guide - PTCsupport.ptc.com/WCMS/files/173116/en/ThingWorxUtilitiesInstall.pdf · installing and importing ThingWorx Utilities. For more information

Installation Guide8.0

ThingWorx Utilities

Copyright © 2017 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved.

User and training guides and related documentation from PTC Inc. and its subsidiary companies (collectively"PTC") are subject to the copyright laws of the United States and other countries and are provided under alicense agreement that restricts copying, disclosure, and use of such documentation. PTC hereby grants to thelicensed software user the right to make copies in printed form of this documentation if provided on softwaremedia, but only for internal/personal use and in accordance with the license agreement under which theapplicable software is licensed. Any copy made shall include the PTC copyright notice and any otherproprietary notice provided by PTC. Training materials may not be copied without the express written consentof PTC. This documentation may not be disclosed, transferred, modified, or reduced to any form, includingelectronic media, or transmitted or made publicly available by any means without the prior written consent ofPTC and no authorization is granted to make copies for such purposes. Information described herein isfurnished for general information only, is subject to change without notice, and should not be construed as awarranty or commitment by PTC. PTC assumes no responsibility or liability for any errors or inaccuraciesthat may appear in this document.

The software described in this document is provided under written license agreement, contains valuable tradesecrets and proprietary information, and is protected by the copyright laws of the United States and othercountries. It may not be copied or distributed in any form or medium, disclosed to third parties, or used in anymanner not provided for in the software licenses agreement except with written prior approval from PTC.

UNAUTHORIZED USE OF SOFTWARE OR ITS DOCUMENTATION CAN RESULT IN CIVILDAMAGES AND CRIMINAL PROSECUTION.

PTC regards software piracy as the crime it is, and we view offenders accordingly. We do not tolerate thepiracy of PTC software products, and we pursue (both civilly and criminally) those who do so using all legalmeans available, including public and private surveillance resources. As part of these efforts, PTC uses datamonitoring and scouring technologies to obtain and transmit data on users of illegal copies of our software.This data collection is not performed on users of legally licensed software from PTC and its authorizeddistributors. If you are using an illegal copy of our software and do not consent to the collection andtransmission of such data (including to the United States), cease using the illegal version, and contact PTC toobtain a legally licensed copy.

Important Copyright, Trademark, Patent, and Licensing Information: See the About Box, or copyrightnotice, of your PTC software.

UNITED STATES GOVERNMENT RIGHTS

PTC software products and software documentation are “commercial items” as that term is defined at 48 C.F.R. 2.101. Pursuant to Federal Acquisition Regulation (FAR) 12.212 (a)-(b) (Computer Software) (MAY 2014)for civilian agencies or the Defense Federal Acquisition Regulation Supplement (DFARS) at 227.7202-1(a)(Policy) and 227.7202-3 (a) (Rights in commercial computer software or commercial computer softwaredocumentation) (FEB 2014) for the Department of Defense, PTC software products and softwaredocumentation are provided to the U.S. Government under the PTC commercial license agreement. Use,duplication or disclosure by the U.S. Government is subject solely to the terms and conditions set forth in theapplicable PTC software license agreement.

PTC Inc., 140 Kendrick Street, Needham, MA 02494 USA

Contents

Overview ....................................................................................................................4

Prerequisites...............................................................................................................5

Installing ThingWorx Utilities ........................................................................................7

Importing the ThingWorx Utilities Demo Data Extension .................................................9Configuring Email Server Details.......................................................................... 11MRI Demonstration Data Post-Import Configuration ..............................................12

Updating to a New Version of ThingWorx Utilities.........................................................16Post-Update Steps..............................................................................................19Avoiding Upgrade Impacts...................................................................................23

Visibility Support for ThingWorx Utilities ......................................................................25

3

1Overview

This guide provides instructions for installing and importing ThingWorx Utilitiesinto ThingWorx and for importing ThingWorx Utilities utility extensions.

NoteThingWorx must be installed and configured properly on your system prior toinstalling and importing ThingWorx Utilities. For more information oninstalling ThingWorx, see the Installing ThingWorx guide.

4 Installation Guide

https://support.ptc.com/appserver/cs/doc/refdoc.jsp?p=browse_results&Product=ThingWorx&Release=&DocType=2114

2Prerequisites

The following should be installed prior to installing ThingWorx Utilities:• ThingWorx 8.0.0

NoteThingWorx Utilities is only compatible with the matching version ofThingWorx Core. It is not compatible with earlier or later releases.

• The following ThingWorx extensions are not required, but it is highlyrecommended that they be installed so that all features are available and workproperly. These extensions are available from the ThingWorx Marketplace:○ Google Maps Widget○ Mail Extension○ Web Sockets Tunnel Widget and Library

NoteYou will be able to upgrade these extensions after installingThingWorx Utilities.

• The following ThingWorx extensions that were bundled with ThingWorxUtilities have been deprecated and removed:○ LabelTooltip_ExtensionPackage○ LinkTooltip_ExtensionPackage○ ButtonTooltip_ExtensionPackage

5

https://marketplace.thingworx.com/Items/google-widgets

https://marketplace.thingworx.com/Items/mail-extension

https://marketplace.thingworx.com/Items/Web%20Sockets%20Tunnel%20Widget%20And%20Library

○ NavigationTooltip_ExtensionPackage

If you are using any of the widgets available in these extensions, you cancontinue to download them from the PTC eSupport page, under Release 8.0 ▶▶ThingWorx Utilities Deprecated Tooltip Widgets.

• Tomcat 8• Java 8


3Installing ThingWorx Utilities

The following are included in the ThingWorx Utilities ZIP file:• ThingWorx Asset Management• ThingWorx Alert Management• ThingWorx Product Relationship Management• ThingWorx Workflow Management• ThingWorx Software Content Management• ThingWorx Remote Access and Control1. Navigate to the PTC ThingWorx & Axeda eSupport page.2. In the Software Downloads section, click PTC Software Downloads.

3. Click Order or Download Software Updates. Enter your Customer Name andCustomer Number and click Next.

4. Under Step 1: Select the Product Family, click ThingWorx Platform.5. Under Step 2: Choose Release & Download, select Release 7.4.0 ▶▶ ThingWorx

Utilities ▶▶Most Recent Datecode.6. Click HTTPS or Download Manager.

7

https://support.ptc.com/appserver/cs/portal/

7. From theThingWorx Composer, navigate to Import/Export ▶▶ Import.

8. The Import Extensions window appears.9. Navigate to the ZIP file, and click Import.10. Click Close. When prompted to refresh your browser, click Yes.11. Verify that the extension has been successfully imported by searching for the

PTC.ConvergeConsole mashup. Select the mashup and click View, then clickView Mashup.

12. On the ThingWorx Utilities Console, click Asset Management and verify thatit loads.


4Importing the ThingWorx Utilities

Demo Data ExtensionConfiguring Email Server Details ................................................................................ 11MRI Demonstration Data Post-Import Configuration.....................................................12

NoteBecause the demo data requires specific thing shapes and thing templates, allThingWorx Utilities extensions, including Workflow Management andSoftware Content Management, must be loaded prior to importing the demodata.

Before working with the demo data or completing the configuration, you mustimport the ThingWorx Utilities Demo Data extension and the imports XML file intoThingWorx Composer. The download ZIP file (ThingWorx-Utilities-Demo-Data-version) contains the extension ZIP file and the imports XML file you will needfor the following steps.

9

Importing the Extension ZIP FileThe utl-demo-data-extension ZIP file contains the minimum supporting objects forrunning the MRI demo data. Complete the following steps to import theThingWorx Utilities Demo Data extension ZIP:1. Extract the contents of the ulto-demo-data-extension ZIP file to your system.2. From ThingWorx Composer, navigate to the Import/Export menu. Under

Extensions, select Import.3. Click Choose File, and navigate to the utl-demo-data-extension ZIP

file and select it.4. Click Import.

Importing the Imports XML FileThe utl-demo-data-imports XML file contains many of the files that you will wantaccess to when working with the MRI demo data. Complete the following steps toimport the utl-demo-data-imports XML file:1. From ThingWorx Composer, navigate to Import/Export ▶▶ Import ▶▶ From File.2. On the Single File tab, click Choose File, and navigate to the utl-demo-

data-imports XML file and select it.3. Click Import.

Extracting the Core Data Simulator1. Extract the contents of the ult-demo-data-simulator-zip ZIP file to your system.2. In the extracted ult-demo-data-simulator-zip directory on your

system, create 8 new directories, one for each MRI machine. Name thesedirectories SN0001, SN0002, and so on, through SN0008.

NoteYou must follow this naming convention, as the simulator relies on theseidentifiers.

3. In each of those 8 new directories, create 4 more directories:• in

• out

• staging

• updates

These directories are used for file transfer and are used for File Transfer andSoftware Content Management capabilities.


Configuring Email Server DetailsAfter you have installed ThingWorx Utilities, you must specify the email serverthat will be used for ThingWorx Software Content Management notifications:1. From ThingWorx Composer, navigate to the TW.RSM.SFW.Thing.MailServer

thing.2. Under Entity Information, click Configuration and then click Edit.3. Enter the appropriate information for Mail Server Connection Parameters.

4. Click Save.5. Restart the TW.RSM.SFW.Thing.MailServer thing to begin using the new

settings:a. Click Services.b. Under Generic Services, find the RestartThing row and click Test.

Importing the ThingWorx Utilities Demo Data Extension 11

c. On the RestartThing - Test Service window, click Execute Service.

NoteThese entities are not considered part of the extension, but are created after theThingWorx Utilities has been installed. If these entities are deleted for anyreason, ThingWorx Utilities will recreate them, but they must be reconfigured.

MRI Demonstration Data Post-ImportConfigurationAfter you have imported the MRI demo data extension, complete the followingsteps:

Configure DistributorNotifier Email Addresses1. From ThingWorx Composer, navigate to the PTC.Demo.DistributorTemplate

thing template.2. In the left panel, under Dependencies, click Use This Entity. A list of

distributors that you will update appears.• Air Source Industries• AMCS• Arcmaster Supply• Purity Cylinder Gases

For each of these entities, complete Steps 3 and 4.3. Click the entity, and then click Edit.


4. Under Entity Information, click Properties. Click Set next to the emailproperty. Enter the appropriate email address and click Set to save yourupdate.

Configure Email Server1. From ThingWorx Composer, navigate to the PTC.BPE.

BusinessProcessNotifier thing.2. Under Entity Information, click Configuration and then click Edit.


3. Enter the appropriate information for Mail Server Connection Parameters.

4. Click Save.5. Restart the TW.RSM.SFW.Thing.MailServer thing to begin using the new

settings:a. Click Services.b. Under Generic Services, find the RestartThing row and click Test.c. On the RestartThing - Test Service window, click Execute Service.

NoteThese entities are not considered part of the extension, but are created after theThingWorx Utilities has been installed. If these entities are deleted for anyreason, ThingWorx Utilities will recreate them, but they must be reconfigured.


Start the Core Data Similator1. Open the extracted Core_DataSimulator-zip directory on your system.2. Start the simulator by running the appropriate script for your system:

• Windows—startMRIClient.bat

• Linux—startMRIClient.sh

Add the MRI Demo Simulator Tile to the Console1. From the ThingWorx Utilities Console, click the Add/Remove Tiles tile.2. In the tiles table, find MRI Demo Simulator.3. Select the checkboxes in the In Console and In App Switcher columns.

4. Click .5. The MRI Demo Simulator now appears on the Console.Once you have imported and configured the MRI demonstration data, a MRIMachines section will also appear in ThingWorx Asset Management.


5Updating to a New Version of

ThingWorx UtilitiesPost-Update Steps ....................................................................................................19Avoiding Upgrade Impacts .........................................................................................23


To update to a new version of ThingWorx Utilities, complete the following steps:

NoteWhen upgrading from version 7.4.0 to 8.0.0, you can directly importThingWorx Utilities after an in-place upgrade of ThingWorx foundation 8.0.0and it is no longer necessary to follow the Export/Import extension upgradeprocess.

After performing the import, you must restart Tomcat. You may also need torun the AdjustUtilitiesVisibility service in the TW.UTL.UtilSetupHelperresource to ensure the visibility and permissions are properly set.

1. Export data:a. Export everything that has been developed in your current version of

ThingWorx from ThingWorx Utilities using the Import/Export drop-downand selecting To ThingWorxStorage under Export.

Updating to a New Version of ThingWorx Utilities 17

b. Select the Include Data checkbox.

c. Click Export.d. Once the export completes successfully, a directory is created in

/ThingworxStorage/exports. Create a ZIP file of the exportsdirectory.

2. Ensure that the ThingWorx 7.4.0 platform is installed.3. Install the ThingWorx Utilities 7.4.0 extension and any other optional

ThingWorx Utilities extensions that you previously had installed. For moreinformation, see Installing ThingWorx Utilities on page 7.

4. Import data:a. Navigate to the ZIP file that you created in step 1, and extract the contents

of the file to the newly installed ThingWorx Utilities 7.4.0/ThingworxStorage/exports directory.

b. From ThingWorx Composer, import the extracted files from theThingWorx Utilities 7.4.0 /ThingworxStorage/exports directoryusing the Import/Export menu and selecting From ThingWorxStorage underImport.

c. After the import has completed successfully, restart the application server.This enables ThingWorx Workflow Builder to create dynamicsubscriptions correctly.

5. Depending on the version you are updating from, follow the appropriateinstructions in Post-Update Steps on page 19.


Post-Update StepsAfter updating to a new version of ThingWorx Utilities, you may need to performpost-update tasks depending on the version of ThingWorx Utilities you areupdating from:

Updating from ThingWorx Utilities 7.4.0No post-update steps are required when updating from ThingWorx Utilities 7.4.0.



Updating from ThingWorx Utilities 7.1.0If you are updating from ThingWorx Utilities 7.1.0, you must complete thefollowing tasks.

If You Have Multiple OrganizationsIf you have more than one organization, you must manually add the following tagsafter updating your ThingWorx Utilities version:• ThingWorx Workflow Builder

○ TW.UTL.WB.Master.CommonHeader, TWUTL:Workflow○ TW.UTL.WM.Master.CommonHeader, TWUTL:Workflow

• ThingWorx Core○ TW.UTL.Alert.Master.CommonHeader, TWUTL:Core○ PTC.Asset.CommonHeader, TWUTL:Core○ TW.UTL.AssetDetail.Master.CommonHeader, TWUTL:Core○ TW.UTL.AssetSearch.Master.CommonHeader, TWUTL:Core○ TW.UTL.CommonHeader, TWUTL:Core○ TW.UTL.PRM.Master.CommonHeader, TWUTL:Core○ PTC.Asset.FlattenedOwnablesResourceProvider, TWUTL:Core○ PTC.Asset.FlattenedOwnablesDataShape, TWUTL:Core○ PTC.Resource.Asset.ThingworxAssetResourceProvider, TWUTL:

ResourceProvider


○ PTC.Resource.Asset.ThingworxAssetDataShape, TWUTL:ResourceProvider

○ PTC.Resource.CRM.OperatorContactRelationshipResourceProvider,TWUTL:ResourceProvider

○ PTC.Resource.CRM.OperatorContactRelationshipDataShape, TWUTL:ResourceProvider

○ PTC.Resource.CRM.OperatorRelationshipResourceProvider, TWUTL:ResourceProvider

○ PTC.Resource.CRM.OperatorRelationshipDataShape, TWUTL:ResourceProvider

○ PTC.Resource.CRM.OwnerContactRelationshipResourceProvider,TWUTL:ResourceProvider

○ PTC.Resource.CRM.OwnerContactRelationshipDataShape, TWUTL:ResourceProvider

○ PTC.Resource.CRM.OwnerRelationshipResourceProvider, TWUTL:ResourceProvider

○ PTC.Resource.CRM.OwnerRelationshipDataShape, TWUTL:ResourceProvider

○ PTC.Resource.CRM.ThingworxCustomerResourceProvider, TWUTL:ResourceProvider

○ PTC.Resource.CRM.ThingworxCustomerDataShape, TWUTL:ResourceProvider

○• Salesforce

○ PTC.Resource.CRM.SalesforceAccountResourceProvider, TWUTL:ResourceProvider

○ PTC.Resource.CRM.SalesforceAccountDataShape, TWUTL:ResourceProvider

○ PTC.Resource.CRM.SalesforceContactResourceProvider, TWUTL:ResourceProvider

○ PTC.Resource.CRM.SalesforceContactDataShape, TWUTL:ResourceProvider

• ThingWorx Software Content Management○ TW.UTL.SFW.Master.CommonHeader, TWUTL:RemoteServices○ PTC.Resource.Asset.RSMUpdatableResourceProvider, TWUTL:

ResourceProvider○ PTC.Resource.Asset.SCMResourceProvider, TWUTL:ResourceProvider○ PTC.Resource.Asset.SCMDataShape, TWUTL:ResourceProvider


○ TW.RSM.SFW.SoftwareManager.SoftwareAuditHistory, TWUTL:RemoteServices

○ TW.RSM.SFW.SoftwareManager.Configuration, TWUTL:RemoteServices○ TW.RSM.SFW.SoftwareManager.AccessPrivileges, TWUTL:

RemoteServices○ TW.RSM.SFW.SoftwareManager.DeliveryTarget, TWUTL:

RemoteServices○ TW.RSM.SFW.SoftwareManager.Campaign, TWUTL:RemoteServices○ TW.RSM.SFW.SoftwareManager.Definition, TWUTL:RemoteServices○ TW.RSM.SFW.FlattenedOwnablesResourceProvider, TWUTL:

RemoteServices○ PTC.Resource.Asset.RSMAssetResourceProvider, TWUTL:

ResourceProvider○ PTC.Resource.Asset.RSMAssetDataShape, TWUTL:ResourceProvider

• Styles○ PTC.ConvergeConsole.Master, TWUTL:Core

Updating from ThingWorx Utilities 7.0.1For most installations, no post-update steps are required when updating fromThingWorx Utilities 7.0.1.If you have more than one organization, you must add manually add tags asdescribed in the following topic: Updating from ThingWorx Utilities 7.1.0 on page19.

Updating from ThingWorx Utilities 6.6.0If you are updating from ThingWorx Utilities 6.6.0, you must complete thefollowing tasks.

Customizations to ThingWorx Utilities EntitiesCustom edits to ThingWorx Utilities entities are not supported and must be re-applied after upgrading to ThingWorx Utilities 7.0.1. This includes changes to themaster mashups to update logos in the utility banners.

Workflow DefinitionsThe workflow definitions created prior to ThingWorx Utilities 6.6.0 will continueto be supported. However, if there is a need to edit the events configured for areceive task in a pre-7.0.1 workflow definition, the event must be removed andreplaced with a newly created event.


Updating Pre-ThingWorx Utilities 7.0.1 Assets with Appropriate ThingShapesRun the UpdatePre40Assets utility service, available in the PTC.Asset.AssetCoreUtils thing, to update pre–7.0.1 assets with the appropriate thing shapesassociated with the new resource providers using the following steps:1. In ThingWorx Composer, navigate to the PTC.Asset.AssetCoreUtils thing.2. Click Services, and find the UpdatePre40Assets service. Click Test.The service finds all things which implement the TW.RSM.ManagedAssetthing shape, but do not implement theTW.RSM.SFW.ThingShape.Updateable thing shape. If they are notcurrently assigned to any thing-based resource provider, the service adds theresource thing shape,PTC.Resource.Asset.RSMAssetResourceThingShape to thosethings.It then finds all things which implement theTW.RSM.SFW.ThingShape.Updateable thing shape, and if they are notcurrently assigned to any thing-based resource provider, adds thePTC.Resource.Asset.RSMUpdatableResourceThingShape resourcething shape to those things.

DisplayName Property for ThingWorx Product Relationship ManagerA display name was added for ThingWorx Utilities customer things. A migrationscript is available to create the new DisplayName property for eachPTC.Resource.CRM.ThingworxCustomer thing and populate it based onits corresponding thing name. Complete the following steps to run theMigrateCustomerNames service on the PTC.Resource.CRM.CustomerManagementUtils thing:

1. In ThingWorx Composer, navigate to the PTC.Resource.CRM.CustomerManagementUtils thing.

2. Click Services, and find the MigrateCustomerNames service. Click Test.

ThingWorx Utilities Help CenterIf the Help Center tile is pointing to a previous version of the ThingWorx UtilitiesHelp Center, you must update the tile to point to the ThingWorx Utilities 7.4.0Help Center using the following steps:1. Click the Add/Remove Tiles tile.2. Select ThingWorx Utilities Help Center in the table.


3. In the Mashup or URL field, enter the following: http://support.ptc.com/help/thingworx_hc/thingworx_utilities_7_hc/[language]/, where [language] is the two-charactercode for your preferred language:• Simplified Chinese—zh_CN

• Traditional Chinese—zh_TW

• English—en

• French—fr

• German—de

• Italian—it

• Japanese—ja

• Korean—ko

• Russian—ru

• Spanish—es

4. Click Save Tile.

If You Have Multiple OrganizationsIf you have more than one organization, you must add manually add tags asdescribed in the following topic: Updating from ThingWorx Utilities 7.1.0 on page19.

Avoiding Upgrade ImpactsWhen developing on top of ThingWorx Utilities, steps can be taken to avoidissues when upgrading to a newer release in the future. Depending on the updatesthat are provided in future releases, you may need to ensure that custom code andobjects are compatible with the updates made to ThingWorx Utilities. To avoidupgrade issues, we recommend the following:

Resource Providers• When extending the ThingWorx Utilities ontology to support new domains,

avoid modeling specific resource types, such as Customer and Contact.Instead, model the capabilities that are provided by these resources, likeAddressable and Contactable.

• Java-based thing templates should not be modified in the ThingWorxComposer. To prevent a Java-based thing template from being modified in theThingWorx Composer, ensure that the thing template is set to be non-editablewhen it is imported as part of an extension.


Capabilities• To avoid naming conflicts, the field name of a capability data shape should

contain the prefix of a capability. For example, the Contactable capability hasfield names such as ContactablePhoneNumber andContactableEmail instead of PhoneNumber or Email.

• To prevent upgrade impacts due to future changes to any ontology extensionyou create, the ThingWorx entities that make up the capabilities that are partof your ontology extension (for example, the thing shapes and data shapes)should be set to be non-editable when imported through an extension.


6Visibility Support for ThingWorx

UtilitiesVisibility support for multiple organizations is available for non-asset entities(mashups, helper things, and so on). The TW.UTL.UtilSetupHelper resourcecontains the AdjustUtilitiesVisibility service to help align visibility and permissionfor ThingWorx Utilities.

NoteTo set visibility you must be an administrator or have the correct permissions.

Complete the following steps to set visibility:1. In ThingWorx Composer, navigate to System ▶▶ Resources.2. Click TW.UTL.UtilSetupHelper, and then click Services.3. Click Test next to the AdjustUtilitiesVisibility service.

25

4. Enter the organization for which you want to execute the service, or you canalso use a colon to enter the unit as well. In the example below, running theservice sets visibility for the core entities that are available to ThingWorxUtilities and some platform entities (subsystems, resources, and so on) for theAcmeOrganization and the AcmeUnit.

5. Click Execute Service.


Documents

ThingWorx Utilities Installation Guide - PTCsupport.ptc.com/WCMS/files/173116/en/ThingWorxUtilitiesInstall.pdf · installing and importing ThingWorx Utilities. For more information