Configuring SSL for EMS connections in TIBCO off-the-shelf adapters

When I started working with TIBCO products in 2004, the running gag was that on every project there should be a consultant hired directly from TIBCO, to help with the more advanced - and conspicuously undocumented - features of the software. Deceptively easy to install, configure and use, snags and gotchas were never far away, and you needed said consultant to help you out (or to call the helpline available only to insiders). After hours of fruitless trial and error it would usually turn out that some "secret" property in a TRA file was enough to make things work (and make you tear out your hair in frustration).

I was reminded of this when I was trying to configure SSL for an SAP/R3 Adapter with EMS connections in a BW 5.14 project. Although the adapter configuration does not depend on a shared EMS connection resource, configuration looks similar enough. So I approached it in the same way; by referring to a Trusted Certificates directory internal to the project, and creating the infamous global variable BW_GLOBAL_TRUSTED_CA_STORE, which we all know will be used at run-time to locate the external directory holding the trusted CA certificates.

Except, of course, that this won't work. 
The adapter SDK pre-dates BW by at least 5 years, and doesn't know this trick. If you missed this, don't feel bad - it wasn't included in the documentation prior to version 7.2.0, which is the second to last version compatible with BW5. Anyway, it clearly states that you need to (surprise!) add a property a TRA file, and create a special global variable. Specifically, it tells you to

• add this property to the designer.tra: RuntimeExternalCertificatesFeature true,
• then add a global variable named RuntimeCertificatesDirectory, and 
• refer to %%RuntimeCertificatesDirectory%% in the Trusted Certificates Folder field.

Except, of course, that this won't work either. 

Because it should be java.property.RuntimeExternalCertificatesFeature. Without the prefix, Designer will remain blissfully ignorant of your efforts. When in doubt, open the AdapterDefinitions/<adapter>.adr3 file in your project, and look for a line reading: 

<AEService:runtimeCertificateDir>%%RuntimeCertificatesDirectory%%</AEService:runtimeCertificateDir>

which is ultimately what will make the adapter read the external CA certificates at run-time. Except, of course, when it still doesn't. 

Maybe you assumed that (like BW_GLOBAL_TRUSTED_CA_STORE) the global variable must contain a URL, like file:///<directory> ? If yes, you should change that to a regular directory path.

If at this point the adapter still refuses to start, or - when run on the command line - it throws an unhelpful exception at you, don't tear out your hair just yet. 

At this point, the aforementioned consultant would step in and reveal - grinning - that trusted certificates MUST have a filename extension of .pem, for SDK adapters to find them...

Man, those were the days.