My name is Zeljko Ratkaj, and I am Senior PLM & IoT Specialist at BoostPLM A/S and in the following series of texts, I will address development/integration problems that we, as a small consultancy company, are facing when working on prototypes or blueprints for full projects.
It was while I was taking one of my first PTC online training classes that I realised the importance of asking questions not just to cover the curriculum but to pick the brain of the teacher.
The topic was ThingWorx Navigate, and during class, we covered integration connectors for Windchill and SAP, and worked on how to apply them in solving various problems.
For some of the presented solutions, I still wonder why they are so complicated (SAP connector, I’m looking on you), but that is a topic for some other time. My question concerned how to make use of external system connectors in Windchill. I presumed that it needed to combine Windchill Server and UI customisation, coupled with Info*Engine coding.
The answer was in the form of a question: “Why don’t you embed ThingWorx mashup into Windchill directly?”.
I was somewhat surprised; I was still in the process of learning the PTC platform solutions, and had been so preoccupied with its complexity that I hadn’t been able to see ‘the forest for the trees’.
The embedding process requires the use of HTTP iframe (inline frame – embed another document within the current HTML document). However, the process has one significant limitation, which PTC is probably/hopefully trying to resolve: The iframe functionality within Windchill, it’s height size, is hardcoded to 1200px.
So, if the mashup content size is more than 1200 px in height, there will be a scrollbar, and if the mashup content size is way less than 1200 px in height, the result can look rather strange in comparison to Windchill UI.
Because of this one issue, you can expect a lot of tweaks and how-is-it-looking cycles from ThingWorx to Windchill and back.
One important prerequisite for ThingWorx mashup embedding is that the user who performs it needs to have site administrator privileges in Windchill. If you don’t have such privileges, maybe get them and read on afterwards.
Another important prerequisite is to make sure that ‘Customization Utilities’ is enabled in Windchill. You can check this in the browsing section. If it is not enabled there, it needs to be enabled at site level. To do that, proceed as follows:
- Go to Site -> Utilities -> (under Business Administration) Preference Manager
- Find Client Customization section, right click, Set Preference, and set value to “Yes”.
- Refresh browser.
Screenshot 1,2 – Customization Utilities & Site access
Screenshot 3 – Client Customization in Preference Management
Now that we have all the prerequisites are in place, we can continue with the embedding process.
Design and develop a mashup to embed into Windchill
In this step, you create a mashup in ThingWorx. Based on my experience, you should begin by focusing on the desired functionality of the mashup and focus less on the mashup design; it is important to have the necessary functionalities and to make sure that all permissions/access rights are in place and the basic layout established.
Due to the 1200px hard-coded limit for the iframe, the actual design should take place only once you have your mashup embedded into Windchill.
To give a quick demonstration, I will now show how to create a simple mashup with two labels and button and then embed it into Windchill.
This mashup only has one functionality which is to show a message in label 2 when the button is pressed.
Screenshot 4 – Mashup example in ThingWorx
How to let Windchill know that you are going to embed ThingWorx mashup
Fire up the Windchill shell and invoke xconfmanager command with following parameters:
xconfmanager -s com.ptc.thingworxURL="http://server_name.domain1.com:XYZY/Thingworx/" -t codebase\wt.properties -p
s – source : ThingWorx platform url location; it is where our ThingWorx server is located; the parameter that we are creating is com.ptc.thingworxURL
t – target: the all important file wt.properties that resides in codebase folder
p: propagate the change
Verify that a parameter is added/changed by checking the value in file site.xconf (Windchill root folder). It is usually at the end of the file.
Screenshot 5 – parameter in site.xconf file
Which Windchill action model to use?
There are several ways to approach this task. The usual one is to enable the debug feature in Windchill (add &jcaDebug=true to the end of the http link). In this example, we want to put a new custom tab into the ‘part information’ page and make it permanent.
Screenshot 6 – Part Info page with jcaDebug enabled
As you can see, the action model, that we need to override, is partInfoPageTabSet.
Now proceed to Customization Utilities (we enabled it in perquisites section) -> Tools and select Action Model from the list of available utilities. From there, search for our model of interest.
Screenshot 7,8,9 – Find the Action Model for override
And click on “Create Action”. Like I mentioned above, there are several ways to do this, but this approach works best for me.
Create Custom Action
Screenshot 10 – Invoke “Create Action”
Note: If you look at the definition file in the image above, it says /config/actions/custom-actionModels.xml. This is because I’ve already customised this model. In your case, it may or may not point to this particular file.
Step 1. – Define Properties
Fields that needs to be filled are highlighted as required. Input a meaningful values.
Screenshot 11 – Create Action step 1.
Step 2. – Define Advanced Properties
Fill in the Action URL field with ptc1/twx?mashup=TestEmbeddingMashup. The URL part ptc1/twx?mashup handles the URL part that we introduced with xconfmanager. So, what we actually doing is entering the name of the mashup that we would like to display in Windchill.
There are some other options on this form, like Window Type and Supported and Non Supported types.
You can set Window Type to popup if you want the mashup to be presented in form of a popup. In our case, since we are embedding directly into the page, this field is blank.
Supported and Non-Supported types: With this parameter, you can fine-tune the visibility of the tab. For example, we can forbid this tab to be visible when the user is browsing Documents. In this case, we will put wt.doc.WTDocument in the field Non Supported Types. Leave it blank for now.
Click finish and you are done.
Screenshot 12 – Custom Action Model added.
When you press finish, 2 things happened. Two files, <wt home>/codebase/custom-actions.xml and <wt home>/codebase/custom-actionmodels.xml are updated with correspond data. All action models and actions that are customized or updated should be listed here.
Second, all the actions definitions are reloaded so, in principal you should be able to see and invoke your new tab.
Screenshot 13,14 – custom-action.xml and custom-actionmodels.xml
Screenshot 15 – Blocked Content
This lead us to …
Prerequisites – Part II
HTML iframe property is known as widely used by hackers for session hijacking, data collecting and such. This technique is known as clickjacking, and if you want to find out more about the issue, there are plethora of information on the internet.
The last thing that needs to be done is to “tell ThingWorx that it is safe to iframe itself in Windchill”.
Edit web.xml file of the ThingWorx application on Tomcat server where application resides. In my case the location of that particular web.xml file is (there can be lot of web.xml files on Tomcat server, depending on your setup):
<location of Tomcat server>/webapps/ThingWorx/WEB-INF/web.xml
Uncomment specific pieces of parameters definitions within the file and, in my case, since I decided to use WhiteList, add domains that are ok to iframe the content separated by spaces.
Screenshot 16 – uncomment filter WhiteList and add domains
Screenshot 17 – uncomment filter-mapping for WhiteList to enable clickjack filter
… And restart the Tomcat server. And that should be all. You should now have Thingworx mashup embedded into Windchill.
Screenshot 18 – functional ThingWorx mashup within Windchill
This post is based on information that can be found in online Windchill manual on following location:
Be sure to visit this link in order to find more information on embedding process.
Stay tuned for more content to come.