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

Transcription

1 Connector Guide 8.0

2 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 a license agreement that restricts copying, disclosure, and use of such documentation. PTC hereby grants to the licensed software user the right to make copies in printed form of this documentation if provided on software media, but only for internal/personal use and in accordance with the license agreement under which the applicable software is licensed. Any copy made shall include the PTC copyright notice and any other proprietary notice provided by PTC. Training materials may not be copied without the express written consent of PTC. This documentation may not be disclosed, transferred, modified, or reduced to any form, including electronic media, or transmitted or made publicly available by any means without the prior written consent of PTC and no authorization is granted to make copies for such purposes. Information described herein is furnished for general information only, is subject to change without notice, and should not be construed as a warranty or commitment by PTC. PTC assumes no responsibility or liability for any errors or inaccuracies that may appear in this document. The software described in this document is provided under written license agreement, contains valuable trade secrets and proprietary information, and is protected by the copyright laws of the United States and other countries. It may not be copied or distributed in any form or medium, disclosed to third parties, or used in any manner 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 CIVIL DAMAGES AND CRIMINAL PROSECUTION. PTC regards software piracy as the crime it is, and we view offenders accordingly. We do not tolerate the piracy of PTC software products, and we pursue (both civilly and criminally) those who do so using all legal means available, including public and private surveillance resources. As part of these efforts, PTC uses data monitoring 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 authorized distributors. If you are using an illegal copy of our software and do not consent to the collection and transmission of such data (including to the United States), cease using the illegal version, and contact PTC to obtain a legally licensed copy. Important Copyright, Trademark, Patent, and Licensing Information: See the About Box, or copyright notice, 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 Pursuant to Federal Acquisition Regulation (FAR) (a)-(b) (Computer Software) (MAY 2014) for civilian agencies or the Defense Federal Acquisition Regulation Supplement (DFARS) at (a) (Policy) and (a) (Rights in commercial computer software or commercial computer software documentation) (FEB 2014) for the Department of Defense, PTC software products and software documentation 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 the applicable PTC software license agreement. PTC Inc., 140 Kendrick Street, Needham, MA USA

3 Contents About This Guide...4 Overview...6 PTC Servigistics InService Connector Product Overview...7 Product Requirements and Limitations...7 Entity Overview...8 Installing Servigistics InService Connector Installation Overview...12 Downloading the Installation File from the Marketplace...12 Installation Procedure...13 Installing the Servigistics InService Connector Extension in ThingWorx Composer...18 Configuring Your System...21 Configuring the Servigistics InService Connector...22 Creating the Thing Instance (Optional)...23 Configuring Internet Explorer...23 The Log File...24 Servigistics InService Connector Services and Entities...26 Servigistics InService Connector Services...27 Search Services...29 Retrieve Part Information Services...33 Retrieve Parts List Information Services...35 Retrieve Service Information Service...38 Retrieve Product Instance Information Services...40 Servigistics InService Connector Datashapes...42 Servigistics InService Connector Entities

4 About This Guide This guide documents the installation and use of the PTC Servigistics InService Connector. It is intended for system administrators who are installing the Servigistics InService Connector and application developers who are using ThingWorx Composer to build ThingWorx applications that connect to Servigistics InService. To take advantage of the functionality in the Servigistics InService Connector, you should have: Working knowledge of your Servigistics InService instance Working knowledge of the ThingWorx Composer Technical Support Contact PTC Technical Support through the PTC website, or by phone, , or fax if you encounter problems using this product or the product documentation. The PTC Servigistics esupport portal provides the resources and tools to support your implementation: For complete support details, see the PTC Customer Support Guide: You must have a Service Contract Number (SCN) before you can receive technical support. If you do not know your SCN, see Preparing to contact TS on the Processes tab of the PTC Customer Support Guide for information about how to locate it. 4 Connector Guide

5 Comments PTC welcomes your suggestions and comments on its documentation. To submit your feedback, you can send an to To help us more quickly address your concern, include the name of the PTC product and its release number with your comments. If your comments are about this book, include the PTC Servigistics InService Connector Guide book title. About This Guide 5

6 1 Overview PTC Servigistics InService Connector Product Overview...7 Product Requirements and Limitations...7 Entity Overview...8 This chapter describes the product functionality and requirements. 6 Connector Guide

7 PTC Servigistics InService Connector Product Overview The PTC Servigistics InService Connector enables ThingWorx application developers to quickly and easily create connected applications that retrieve specific content from Servigistics InService and displays it in a customizable user interface. This extension provides the following capabilities: Retrieve search results based on specified search criteria. The search criteria is based a selection of the information type and the search criteria specification. Search for a specific product or serial number specification (that is, a context). You can filter search results based on the context. Access and view search result document content, attributes, and related illustrations. This applies to service information (PDF, XML, and GRAPHICS), parts lists (including line items and related illustrations), and parts. Product Requirements and Limitations The Servigistics InService Connector has the following requirements and limitations Requirements To use the PTC Servigistics InService Connector, you must be using the following products: ThingWorx or later Servigistics InService 7.1 F000/M001 or later Limitations The Servigistics InService Connector has the following limitations when connecting to ThingWorx: The authentication to Servigistics InService is made based on hard coded administrator user credentials that are defined in the Servigistics InService Connector extension. User access control is also applied based on specific hard coded user credentials in the extension. Overview 7

8 The drop-down list in the PTC.Connector.Mashup.AllSearchTypes. V8Example sample mashup does not work with a mouse or similar pointing device when you are using the Firefox web browser with ThingWorx 8.0. In this case, you can select items in the list using the arrow keys on your keyboard. Media download links and hyperlinks embedded in documents do not work. If the serviceable value for a part is unspecified or null, the Serviceability column for that part is blank in a parts list displayed in the sample mashup. For XML documents containing applicability information in specific chapters or content, that information is not shown in the sample mashup. The following limitations apply when accessing graphics stored in Servigistics InService: The following graphic formats are supported: BMP EPS GIF JPG PDF PNG PVZ The following graphic formats are not supported: CGM Creo Illustrate DJV ISO ISOZ The graphic tool bar is only available for PVZ images. Hotspot linking between parts in a parts list and the associated graphic is not supported. Entity Overview This section provides a high level overview of important entities provided with the files included in the Servigistics InService Connector. The Servigistics InService Connector Extension includes the following entities: 8 Connector Guide

9 Entity Description PTC.InService.Connector.V8 The Servigistics InService Connector Thing Template PTC.InService.Connector. The Servigistics InService Connector Instance V8.Thing containing service methods and common available integration points specific to Servigistics InService. PTC.Connector. SearchResultsEquipment. DefaultDataShape PTC.Connector. SearchResults. DefaultDataShape PTC.Connector. SearchOptions. DefaultDataShape PTC.Connector. PartsListInfo. DefaultDataShape PTC.Connector. PartsListImages. DefaultDataShape PTC.Connector.PartsList. DefaultDataShape PTC.Connector.Part. DefaultDataShape PTC.Connector.Equipment. DefaultDataShape PTC.Connector.Mashup. AllSearchTypes.V8Example This datashape is used to define the output of the Servigistics InService context search results in the Servigistics InService Connector. This datashape is used to define the output of the Servigistics InService search results in the Servigistics InService Connector. This datashape is used to define the output of the Servigistics InService search options in the Servigistics InService Connector. This datashape is used to define the output of the Servigistics InService parts list information in the Servigistics InService Connector. This datashape is used to define the output of the Servigistics InService parts list images in the Servigistics InService Connector. This datashape is used to define the output of the Servigistics InService parts list line items in the Servigistics InService Connector. This datashape is used to define the output of the Servigistics InService part information in the Servigistics InService Connector. This datashape is used to define the output of the Servigistics InService product instance and product hierarchy Information in the Servigistics InService Connector. This is an example mashup that uses all of the available search types in an example user interface. In ThingWorx, the entities are marked with the PTC_InService_Connector tags. For example: Overview 9

10 10 Connector Guide

11 2 Installing Servigistics InService Connector Installation Overview...12 Downloading the Installation File from the Marketplace...12 Installation Procedure...13 Installing the Servigistics InService Connector Extension in ThingWorx Composer...18 This chapter contains download and installation information. 11

12 Installation Overview To install the Servigistics InService Connector you must have the Connector- Installer bin.zip compressed archive file containing the software. Note that you must also have administrator privileges on the system where you are installing Servigistics InService Connector. The installation requires the following steps: 1. Download the Servigistics InService Connector compressed archive file from the ThingWorx Marketplace. 2. Install the Servigistics InService Connector on an existing Servigistics InService installation: a. Unzip the compressed archive file to a temporary location on the Servigistics InService system. b. Run the Servigistics InService Connector Installer and follow the installation steps. 3. Get the Servigistics InService Connector extension from the Servigistics InService Connector installation on your system. 4. Delete any existing Servigistics InService Connector extensions in ThingWorx. 5. Import the new Servigistics InService Connector extension in ThingWorx. Downloading the Installation File from the Marketplace The Servigistics InService Connector installation package is delivered in a ZIP file named TW_Download_ptc Servigistics InService Connector.zip. This file is available from the ThingWorx Marketplace: marketplace.thingworx.com. Follow these steps to download the installation file: 1. In your web browser, open the ThingWorx Marketplace. 2. From the welcome page, click LOGIN. Note You must have a valid ThingWorx user name and password to download this file. If you do not have a valid ThingWorx user name and password, you can click SIGN UP on the Marketplace home page to create an account. 12 Connector Guide

13 After you have logged in, the Marketplace home page opens. 3. Locate and download the PTC Servigistics InService Connector installation file. For example, click TOOLS at the top of the page to open that page, then navigate to the BUSINESS SYSTEMS category and click the Servigistics InService Connector icon: 4. From the PTC Servigistics InService Connector page, click Download Extension and accept the technical support terms of use. Once you accept the terms, the Servigistics InService Connector ZIP file begins to download automatically. After you download the installation file, you can install the Servigistics InService Connector. Installation Procedure Ways to Install Servigistics InService Connector You must install Servigistics InService Connector on a system with an existing Servigistics InService installation. You must have administrator privileges on the system to install the software. Also, you must close any running Servigistics InService sessions before installing the Servigistics InService Connector. The following two installers are available: Microsoft Windows systems: InServiceConnectorInstaller-8.0- windows-installer.exe Linux systems: InServiceConnectorInstaller-8.0-linux-x64- installer.run You can either install the Servigistics InService Connector through a silent installation or you can manually run the installation file. Silent Installation For a silent installation, you must run the installation file from a terminal session and specify the following parameters on the command line: Installing Servigistics InService Connector 13

14 mode unattendedmodeui installdir This must be the Servigistics InService installation directory. accept_eula On a Windows system, extract the compressed archive file to a temporary location on your system and open a Command Prompt window in the Connector- Installer directory. Next, run the following command from thecommand Prompt window: InServiceConnectorInstaller-8.0-windows-installer.exe --mode unattended --unattendedmodeui minimal --installdir "INSERVICE_HOME" --accept_eula YES On a Linux system, extract the compressed archive file to a temporary location on your system and open a command window in the Connector-Installer directory. Next, run the following command from the window prompt:./inserviceconnectorinstaller-8.0-linux-x64- installer.run --mode unattended --unattendedmodeui minimal --installdir "INSERVICE_HOME" --accept_eula YES Manual Installation Follow these steps to install the Servigistics InService Connector manually: 1. Close any running Servigistics InService sessions. 2. Extract the compressed archive file to a temporary location on your system. 3. Open the Connector-Installer folder in the extracted installation folder. 4. Execute the installation file for your operating system. For example, on Windows execute the InServiceConnectorInstaller-8.0- windows-installer.exe file in the folder to start the installation. After you execute the installer, the Welcome screen opens: 14 Connector Guide

15 5. Click Next. Note that on the Linux platform the button is named Forward instead. The License Agreement screen opens: Installing Servigistics InService Connector 15

16 6. Review the license and select I accept the agreement if you accept it. Click Next to proceed with the installation. The Installation Directory screen opens: 7. Enter the Servigistics InService installation directory in the field, then click Next. You can also click the button to open the Browse for Folder window. This window enables you to find and select the desired folder. The Ready to Install screen opens: 16 Connector Guide

17 8. Click Next to begin the installation. When the Installation is complete, the Installation Complete screen appears: Installing Servigistics InService Connector 17

18 9. Click Finish to complete the installation. 10. Restart the Servigistics InService server. Installing the Servigistics InService Connector Extension in ThingWorx Composer The Servigistics InService Connector extension is delivered in a ZIP file named PTC_TWX_InService_Connector_V8.zip. This file is located in your Servigistics InService installation directory after you install the Servigistics InService Connector. The following sections describe the actions needed to complete the installation of the Servigistics InService Connector extension in the ThingWorx Composer. All actions described in these sections require that you are logged in as an administrator. Deleting Existing Extensions Before Installing PTC Servigistics InService Connector on page 18 Installing the Extension on page 20 Deleting Existing Extensions Before Installing PTC Servigistics InService Connector If you have previously installed the Servigistics InService Connector, continue reading this section to learn how to find and delete existing extensions. If you have not previously installed the Servigistics InService Connector, you can skip this section. Note Failing to remove the extensions before importing updates can cause problems with the updated files. This is because data can be stored in Tomcat memory that is associated with the old extension and this data is not removed unless you delete the extensions and restart Tomcat. Complete the following steps: 1. For the previous version of Servigistics InService Connector, delete the TWX_ InService_Connector extension. For deletion instructions, see Deleting Extensions below. 2. Restart Tomcat to clear the Tomcat memory. 18 Connector Guide

19 Deleting Extensions To delete an extension, complete the following steps: 1. From the Import/Export menu in the ThingWorx Composer, select Extensions Manage. For example, the following screen shows the actual name and description of the previous Servigistics InService Connector extension that has been installed: 2. Select an extension name and then click Delete Extension. Installing Servigistics InService Connector 19

20 Installing the Extension To install the extension included with the Servigistics InService Connector, complete the following steps: 1. From the Import/Export menu in ThingWorx Composer, select EXTENSIONS Import: 2. In the Import Extensions window, click Browse and navigate to PTC_TWX_InService_Connector_V8.zip file on your system. 3. Click Import. 4. If prompted, refresh the composer. To view the extensions after the import is complete, select Import/Export Manage. Selecting a row in the Installed Extension Packages table displays the entities in the extension details under Package Details. 20 Connector Guide

21 3 Configuring Your System Configuring the Servigistics InService Connector...22 Creating the Thing Instance (Optional)...23 Configuring Internet Explorer...23 The Log File...24 This chapter contains configuration considerations for your system. All actions described in this chapter require that you are logged in as an administrator. 21

22 Configuring the Servigistics InService Connector If your Servigistics InService system has multiple viewer servers, the Servigistics InService Connector must be installed and set up on all of the viewer servers. To configure the Servigistics InService Connector in ThingWorx, the Servigistics InService Connector contains an example of the instance named PTC.InService. Connector.V8.Thing that is available after you install the extension. This is an instance of the PTC.InService.Connector.V8 templates with its associated services. To configure this instance, you must provide the following configuration properties: serverurl This is the Servigistics InService server URL with Connector/RestAPI appended to the end. For example: However, if your Servigistics InService system has a load balancer server set up, you must set this property to the load balancer server URL. For example: You must also do the following configuration on the load balancer server: 1. Log in to the load balancer server. 2. Edit the load_balancer.conf file (generally located in the HTTPServer/conf/extra directory). 3. Add the following entries to this file inside the section # For InService (as a RESTful app) the following ProxyPass and ProxyPassReverse statements should work: ProxyPass /Connector balancer://restfulcluster/ Connector ProxyPassReverse /Connector balancer:// RESTfulCluster/Connector 4. Restart the load balancer server. authheader This requires the following syntax: Basic Base64.encode(username:password). For example, using wcadmin as the username and wcadmin as the password, you would enter the following value: Basic d2nhzg1pbjp3y2fkbwlu 22 Connector Guide

23 Following is an example of the required configuration: Creating the Thing Instance (Optional) A connector is configured for a specific Servigistics InService instance. If you need to connect to multiple Servigistics Servigistics InService instances, you must create new connector Thing instances. Follow these steps to create a new Thing instance: 1. Create a new Thing Instance in the ThingWorx Composer. 2. Add PTC.InService.Connector.V8 as a Thing Template. The new Thing automatically inherits all of the services from the Servigistics InService Connector. Configuring Internet Explorer When using the Servigistics InService Connector with Internet Explorer, you must make sure that compatibility view is not enabled. Follow these steps to disable compatibility view: 1. In Internet Explorer, choose Tools Compatibility View settings. You can also click the gear icon at the top right of the window and select Compatibility View settings. The Compatibility View Settings window opens. 2. Make sure the following settings are not checked: Display intranet sites in Compatibility View Use Microsoft compatibility lists For example: Configuring Your System 23

24 The Log File If you have any issues configuring or running the Servigistics InService Connector, a log file is available to help you with troubleshooting. The file is named sce-connector.log. It is located in the INSERVICE_HOME\InS_ SW\Log\System\Log folder. The log contains all of the actions performed by the Servigistics InService Connector. For example, following is a log entry where a search was started: [ :15:45,080] [DEBUG,RestAPI;;default task-10;;] Search start for expr=sedan; type=pi; resfields=title; top=null; filter=null The log can also show you the JSON results returned for a service request in the jsonresults listing. For example, the following log entry is for parts list information in JSON: [ :16:40,935] [DEBUG,RestAPI;;default task-93;;] GetPartsList start for ID=PL_ASM_C _KMT-ORG; filter=null; collection=null [ :16:41,023] [DEBUG,JsonHelper;;default task-93;;kmt-ex11] jsonresults = 24 Connector Guide

25 JSON object to be used as a parts list service JSON input [ :16:41,023] [DEBUG,RestAPI;;default task-93;;kmt-ex11] GetPartsList end. Elapsed time: 88ms Configuring Your System 25

26 4 Servigistics InService Connector Services and Entities Servigistics InService Connector Services...27 Search Services...29 Retrieve Part Information Services...33 Retrieve Parts List Information Services...35 Retrieve Service Information Service...38 Retrieve Product Instance Information Services...40 Servigistics InService Connector Datashapes...42 Servigistics InService Connector Entities...45 This chapter provides detailed information about the Servigistics InService Connector services and entities. 26 Connector Guide

27 Servigistics InService Connector Services The Servigistics InService Connector (PTC.InService.Connector.V8) provides the following services to access content in Servigistics InService: The services are grouped by those that enable you to search content in Servigistics InService and those that enable you to retrieve content from Servigistics InService. JSON Services in ThingWorx This section applies to the following services: This applies to the following services: getcontextlistjson getpartinfojson getpartslistinfojson getproductinstanceinfojson getsearchresultsjson The returned value from these JSON services is a JSON object that can be used as the JSON input parameter for the related service. This prevents the need for multiple server calls. This JSON object results appear in the log file as jsonresults. See The Log File on page 24 for more information. You can also develop additional services to extract more information from the JSON object results retrieved from the log file. However, this requires advanced knowledge of developing ThingWorx services. Note that when you are testing a Servigistics InService Connector service that returns JSON output in the ThingWorx Test Service user interface, it is not an issue if you do not get a result in the interface when you click Execute Service. The Test Service feature does not display JSON objects. Servigistics InService Connector Services and Entities 27

28 For example, if you are working with the PTC.InService.Connector.V8 thing and click Test for the getpartinfojson service: When you then click Execute Service in the Test Service interface, no results are returned: Error When Testing a Service and Not Providing the Required Input Parameters When you are testing a Servigistics InService Connector service in the ThingWorx Test Service user interface and do not provide the required input parameters, you receive an when you click Execute Service. For example, if you are working with the PTC.InService.Connector.V8 thing and testing the getsearchresultsexample service, you get the following error when you click Execute Service in the Test Service interface without providing a required input parameter: 28 Connector Guide

29 Search Services The Servigistics InService Connector provides the following services for searching content in Servigistics InService: getcontextlistjson on page 29 Returns the list of product instances (serial numbers), product hierarchies, or both for a given SearchString and Type in JSON (JavaScript Object Notation) format. getcontextlistexample on page 30 Returns the list of product instances (serial numbers), product hierarchies, or both for a given SearchString and Type. getsearchtypes on page 31 Returns the search result types used in the various searches. getsearchresultsjson on page 31 Returns the search results for a given SearchString and Type in JSON format. getsearchresultsexample on page 32 Returns the search results for a given SearchString and Type. getcontextlistjson This service returns the list of product instances (serial numbers), product hierarchies, or both for a given SearchString and Type in JSON (JavaScript Object Notation) format. Input: SearchString the context name for which to search based on the Type Servigistics InService Connector Services and Entities 29

30 Type the type of context for which to search One of the following values must be provided: ProductInstance ProductHierarchy ProductInstance ProductHierarchy This is the default. DataShapeName the name of the datashape to use The default is PTC.Connector.SearchResultsEquipment.DefaultData Shape. Output: The context list in JSON format getcontextlistexample This service returns the list of product instances (serial numbers), product hierarchies, or both for a given SearchString and Type. For performance reasons, you can just provide the contextlistjson value if it was already returned from the getcontextlistjson service. Otherwise, you must provide the other parameters. Input: SearchString the context name for which to search based on the Type Type the type of context for which to search One of the following values must be provided: ProductInstance ProductHierarchy ProductInstance ProductHierarchy This is the default. DataShapeName the name of the datashape to use The default is PTC.Connector.SearchResultsEquipment.DefaultData Shape. 30 Connector Guide

31 contextlistjson the value returned from the getcontextlistjson service, if available Output: DataShapeName the datashape provided as input getsearchtypes This service returns the search result types used in the various searches. It translates the values seen in the PTC.Connector.Mashup.AllSearchTypes. V8Example mashup example s drop-down search menu to the Servigistics InService internal search types. Input: None Output: The PTC.Connector.SearchOptions.DefaultDataShape datashape getsearchresultsjson This service returns the search results for a given SearchString and Type in JSON format. Input: SearchString the string for which to search based on the Type Type the type of context for which to search One of the following values must be provided: Part Parts List Service Information Part Parts List Service Information This is the default. Filter the value returned from the context list search Servigistics InService Connector Services and Entities 31

32 Top the number of results to return The default is 50. DataShapeName the name of the datashape to use The default is PTC.Connector.SearchResults.DefaultDataShape. Output: The search results in JSON format getsearchresultsexample This service returns the search results for a given SearchString and Type. For performance reasons, you can just provide the searchresultsjson value if it was already returned from the getsearchresultsjson service. Otherwise, you must provide the other parameters. Input: SearchString the string for which to search based on the Type Type the type of context for which to search One of the following values must be provided: Part Parts List Service Information Part Parts List Service Information This is the default. Filter the value returned from the context list search Top the number of results to return The default is 50. DataShapeName the name of the datashape to use 32 Connector Guide

33 The default is PTC.Connector.SearchResults.DefaultDataShape. searchresultsjson the value returned from the getsearchresultsjson service, if available Output: DataShapeName the datashape provided as input Retrieve Part Information Services The Servigistics InService Connector provides the following services for retrieving information about parts from Servigistics InService: getpartinfojson on page 33 Returns part information in JSON format. getpartinfoexample on page 34 Returns part information. getpartimageexample on page 34 Returns the image for a part. getpartinfojson This service returns part information in JSON format. Input: InS_ID the Servigistics InService identifier This can be obtained from the persistentid field returned by the getsearchresultsexample or getsearchresultsjson services. Type the type of information The value of this must be Part, which is the default. Filter the value returned from the context list search Output: The part information in JSON format Servigistics InService Connector Services and Entities 33

34 getpartinfoexample This service returns part information. For performance reasons, you can just provide the partjson value if it was already returned from the getpartinfojson service. Otherwise, you must provide the other parameters. Input: InS_ID the Servigistics InService identifier This can be obtained from the persistentid field returned by the getsearchresultsexample or getsearchresultsjson services. Type the type of information The value of this must be Part, which is the default. Filter the value returned from the context list search DataShapeName the name of the datashape to use The default is PTC.Connector.Part.DefaultDataShape. partjson the value retrieved from the getpartinfojson service, if available Output: DataShapeName the datashape provided as input getpartimageexample This service returns the image for a part. For performance reasons, you can just provide the partjson value if it was already returned from the getpartinfojson service. Otherwise, you must provide the other parameters. Input: InS_ID the Servigistics InService identifier This can be obtained from the persistentid field returned by the getsearchresultsexample or getsearchresultsjson services. Type the type of information The value of this must be Part, which is the default. 34 Connector Guide

35 Filter the value returned from the context list search partjson the value returned from the getpartinfojson service, if available Output: The image of a part as a string to put in the HTML TextArea widget Retrieve Parts List Information Services The Servigistics InService Connector provides the following services for retrieving information about parts lists from Servigistics InService: getpartslistinfojson on page 35 Returns the parts list information in JSON format. getpartslistinfoexample on page 36 Returns the parts list information. getpartslistlineitemsinfoexample on page 37 Returns the parts list line items information. getpartslistimageslistexample on page 37 Returns the images contained in a parts list. getpartslistimageexample on page 38 Returns the image for a parts list. getpartslistinfojson This service returns the parts list information in JSON format. Input: InS_ID the Servigistics InService identifier This can be obtained from the persistentid field returned by the getsearchresultsexample or getsearchresultsjson services. Type the type of information The value of this must be partslist, which is the default. Filter the value returned from the context list search Collection the value returned from the search results Servigistics InService Connector Services and Entities 35

36 It is recommended that you provide this value to improve performance. Output: The parts list information in JSON format getpartslistinfoexample This service returns the parts list information. For performance reasons, you can just provide the partslistjson value if it was already returned from the getpartslistinfojson service. Otherwise, you must provide the other parameters. Input: InS_ID the Servigistics InService identifier This can be obtained from the persistentid field returned by the getsearchresultsexample or getsearchresultsjson services. Type the type of information The value of this must be partslist, which is the default. Filter the value returned from the context list search Collection the value returned from the search results It is recommended that you provide this value to improve performance. DataShapeName the name of the datashape to use The default is PTC.Connector.PartsListInfo.DefaultDataShape. partslistjson the value retrieved from the getpartslistinfojson service, if available Output: DataShapeName the datashape provided as input 36 Connector Guide

37 getpartslistlineitemsinfoexample This service returns the parts list line items information. For performance reasons, you can just provide the partslistjson value if it was already returned from the getpartinfojson service. Otherwise, you must provide the other parameters. Input: InS_ID the Servigistics InService identifier This can be obtained from the persistentid field returned by the getsearchresultsexample or getsearchresultsjson services. Type the type of information The value of this must be partslist, which is the default. Filter the value returned from the context list search Collection the value returned from the search results It is recommended that you provide this value to improve performance. DataShapeName the name of the datashape to use The default is PTC.Connector.PartsList.DefaultDataShape. partslistjson the value retrieved from the getpartslistinfojson service, if available Output: DataShapeName the datashape provided as input getpartslistimageslistexample This service returns the images contained in a parts list. For performance reasons, you can just provide the partslistjson value if it was already returned from the getpartslistinfojson service. Otherwise, you must provide the other parameters. Input: InS_ID the Servigistics InService identifier This can be obtained from the persistentid field returned by the getsearchresultsexample or getsearchresultsjson services. Servigistics InService Connector Services and Entities 37

38 Type the type of information The value of this must be partslist, which is the default. Filter the value returned from the context list search Collection the value returned from the search results DataShapeName the name of the datashape to use The default is PTC.Connector.PartsListImages.DefaultDataShape. partslistjson the value retrieved from the getpartslistinfojson service, if available Output: DataShapeName the datashape provided as input getpartslistimageexample This service returns the image for a parts list. Input: InS_ID the Servigistics InService identifier This can be obtained from the persistentid field returned by the getsearchresultsexample or getsearchresultsjson services. Collection the value returned from the search results Output: The image for a parts list as a string to put in the HTML TextArea widget Retrieve Service Information Service The Servigistics InService Connector provides the following service for retrieving service information in XML, PDF, or media formats from Servigistics InService. 38 Connector Guide

39 getserviceinformation This service returns the service information based on the Type. Input: InS_ID the Servigistics InService identifier This can be obtained from the persistentid field returned by the getsearchresultsexample or getsearchresultsjson services. SearchString the string for which to search based on the Type Type the type of context for which to search One of the following values must be provided: PDF XML Media Filter the value returned from the context list search Collection the value returned from the search results It is recommended that you provide this value to improve performance. Top the first page to return for the PDF type This parameter only apples to the PDF type. The default is 1. Size the maximum number of pages to return for the PDF type This parameter only apples to the PDF type. The default is 5. Output: The service information as a string to put in the HTML TextArea widget Servigistics InService Connector Services and Entities 39

40 Retrieve Product Instance Information Services The Servigistics InService Connector provides the following services for retrieving information about product instances from Servigistics InService: getproductinstanceinfojson on page 40 Returns the product instance information in JSON format. getproductinstanceinfoexample on page 40 Returns the product instance information. getproductinstanceimageexample on page 41 Returns the image for a product instance. getproductinstanceinfojson This service returns the product instance information in JSON format. Input: InS_ID the Servigistics InService identifier This can be obtained from the persistentid field returned by the getcontextlistexample or getcontextlistjson services. Type the type of information One of the following values must be provided: PI This is the default. PH Collection the value returned from the search results It is recommended that you provide this value to improve performance. Output: The product instance information in JSON format getproductinstanceinfoexample This service returns the product instance information. For performance reasons, you can just provide the productinstancejson value if it was already returned from the getproductinstanceinfojson service. Otherwise, you must provide the other parameters. 40 Connector Guide

41 Input: InS_ID the Servigistics InService identifier This can be obtained from the persistentid field returned by the getcontextlistexample or getcontextlistjson services. Type the type of information One of the following values must be provided: PI This is the default. PH Collection the value returned from the search results It is recommended that you provide this value to improve performance. DataShapeName the name of the datashape to use The default is PTC.Connector.Equipment.DefaultDataShape. productinstancejson the value retrieved from the getproductinstanceinfojson service, if available Output: DataShapeName the datashape provided as input getproductinstanceimageexample This service returns the image for a product instance. For performance reasons, you can just provide the productinstancejson value if it was already returned from the getproductinstanceinfojson service. Otherwise, you must provide the other parameters. Input: InS_ID the Servigistics InService identifier This can be obtained from the persistentid field returned by the getcontextlistexample or getcontextlistjson services. Type the type of information Servigistics InService Connector Services and Entities 41

42 One of the following values must be provided: PI This is the default. PH Collection the value returned from the search results It is recommended that you provide this value to improve performance. productinstancejson the value retrieved from the getproductinstanceinfojson service, if available Output: The image for a product instance as a string to put in the HTML TextArea widget Servigistics InService Connector Datashapes The Servigistics InService Connector provides the following datashapes to support the services. Search Services Datashapes The following datashapes support the search services: PTC.Connector.SearchResultsEquipment.DefaultDataShape Defines the output of the Servigistics InService context search results in the Servigistics InService Connector. The following default values are provided in JSON results: Position persistentid SRCType COLLECTION TITLE 42 Connector Guide

43 FILTER PTC.Connector.SearchResults.DefaultDataShape Defines the output of the Servigistics InService search results in the Servigistics InService Connector. The following default values are provided in JSON results: Position persistentid SRCType COLLECTION TITLE FILTER PART_NUMBER PTC.Connector.SearchOptions.DefaultDataShape Defines the output of the Servigistics InService search options in the Servigistics InService Connector. The InfoTable of this datashape contains name - value translations between the values seen in the provided mashup example drop-down search menu to the Servigistics InService internal search types. Retrieve Part Information Services Datashape The following datashape supports the retrieve part information services: PTC.Connector.Part.DefaultDataShape Defines the output of the Servigistics InService part information in the Servigistics InService Connector. The following default values are provided in JSON results: partname partnumber quantity serviceable THUMBNAIL ID Retrieve Parts List Information Services Datashapes The following datashapes support the retrieve parts list information services: PTC.Connector.PartsListInfo.DefaultDataShape Defines the output of the Servigistics InService parts list Information in the Servigistics InService Connector. Servigistics InService Connector Services and Entities 43

44 The following default values are provided in JSON results: partslistname partnumber partslistnumber PTC.Connector.PartsListImages.DefaultDataShape Defines the output of the Servigistics InService parts list images in the Servigistics InService Connector. The following default values are provided in JSON results: imagename imagepath PTC.Connector.PartsList.DefaultDataShape Defines the output of the Servigistics InService parts list line items in the Servigistics InService Connector. The following default values are provided in JSON results: THUMBNAIL partslistitemname partnumber hasassociatedpartslists ID quantity partslistid serviceable partid associatedpartslist position linenumber itemnumber Retrieve Product Instance Information Services Datashape The following datashape supports the retrieve product instance information services: PTC.Connector.Equipment.DefaultDataShape Defines the output of the Servigistics InService product instance and product hierarchy Information in the Servigistics InService Connector. The following default values are provided in JSON results: 44 Connector Guide

45 SN alias1 alias2 alias3 DESCRIPTION alternateserialnumber salesordernumber FILTER Servigistics InService Connector Entities The Servigistics InService Connector provides the following entities: PTC.InService.Connector.V8.Thing This is an instance of the PTC.InService.Connector.V8 template with it s services. Refer to Configuring the Servigistics InService Connector on page 22 for more information. PTC.Connector.Mashup.AllSearchTypes.V8Example This is an example mashup that uses the various services in an example user interface: You can use this interface with your Servigistics InService system. The mashup has the follow capabilities: Search Servigistics InService data You can search for a part, parts list, or service information using the dropdown menu. You can also search without filtering. View Search Results Click on one of the entries under Title to view a search result including document content, attributes, related illustrations, and so forth. Filtering You can filter search results based on a specific context. To apply filter, first search for a context. Select the desired context in the Title list, which displays the context filter value in the field next to the Clear Filter button. Subsequent searches for service and parts information will apply this context filtering. To cancel filtering, click Clear Filter. Following is how the mashup appears when displaying parts list information: Servigistics InService Connector Services and Entities 45

46 Following is how the mashup appears when displaying part information: Following is how the mashup appears when displaying service information: 46 Connector Guide

47 Servigistics InService Connector Services and Entities 47