Production readiness of 'Connected Workspace' object access through SOAP and/or REST APIs?

Kris Boutilier · 2020-12-20T03:17:42+00:00

There was an error rendering this rich post.

I have recently begun to work with Connected Workspaces in CS 16.2.11. After properly enabling them (and restarting all the servers) I can now successfully construct instances of the various custom workspace types through the web ui, so all good there.

I'm working with Java so I regenerated my stub class libraries for all the server SOAP webservices and diff'ed them against the classes generated prior to enabling, expecting to find new objects and methods specific to the 'connected workspace' builders and nothing has appeared. I cannot immediately find any additional SOAP webservice files that are not being loaded (I'm running the dotnet versions). Presumably there is a config directive hidden somewhere that I need to twiddle to expose the additional functions through one of the existing webservices - or is this a 'cannot/will not support' scenario as far as the SOAP API is concerned?

On the REST side of things, the API docs as recent as 20.4 have a bold disclaimer that:

Unpublished Calls: API calls not mentioned in this document (such as "csui" resources) are not officially supported and are subject to change. Use at your own risk.

Digging through the forum posts here, following the examples, and using Fiddler to reverse engineer my particular ActiveView requests (as seems to be the recommended learning method) I can successfully manipulate Connected Workspace objects using the undocumented api/v2/businessworkspaces/ - but everything about going down that route falls squarely in the 'Unpublished: use at your own risk' category. There is chatter in this forum as far back as 2017 referencing the businessworkspaces REST resource, and ActiveView relies directly on it, so I'm a bit surprised that it hasn't managed to reach supported status yet...

So, where are things at with leveraging Connected Workspace object in production 3rd party code?

Find more posts tagged with

SOAP

Connected Workspaces

Comments

Appu Nair

What exactly is the ask here , I for one has been able to create XECM workspaces using Soap UI then I take that payload and create it with java , similarly using postman payloads the counterpart in Rest as well . I only had to look at OT published resources as well as setup documents to do these things ..... Are you not having access to the rest APIs or soap APIs ?

Kris Boutilier

Sorry, I should have been clearer in my original post: am not using the XECM platform, I am using a vanilla installation of Content Suite Platform 16.2.11 running in a Windows environment with RM and PO modules and have recently enabled the 'Template Workspace and Connected Workspaces' functionality.

I have been able to use POST to api/v2/businessworkspaces to create instances of Connected Workspace objects, however the latest 20.4 API doc (https://developer.opentext.com/apis/1e147950-773d-49d2-b2d4-7dde2d21698e/Content%20Server%2020.4%20REST%20API ) still does not mention api/v2/businessworkspaces as an official resource - 'businessworkspaces' does not appear anywhere in that specification, which leads me to understand that it is still considered 'unpublished'. I'd like to be assured that if the API calls we rely on break one day without any deprecation notice the problem is treated as a regression by support and the documented functionality and behaviour restored. If you can point me to another API spec that does officially document businessworkspace REST resources I would be grateful - or if there is a different, supported method for achieving the same outcome just point me in that direction.

As for SOAP, I cannot seem to find where the 'Connected Workspace' builders would be exposed. I am looking for the equivalent of performing a POST to the resource /api/v2/forms/businessworkspaces/create?parent_id=...&type=848&wksp_type_id=...&template_id=... Perhaps I need to download and install and additional .dll to expose a webservice that doesn't ship with the system? I've searched through the knowledge base and can't find anything in that regard. Can you share a snippet of some calls you're using to fetch and execute a workspace builder? That would be incredibly helpful as at this point I can't see any obvious increase in available methods since turning on the additional functionality so I'm at a bit of a loss where I should even start looking (I us JAPICC to compare my versioned libraries of the generated stubs).

Thanks for your help.

Kris Boutilier

Alright - to answer my own concerns about the businessworkspaces REST calls, the Connected Workspaces functionality is documented at https://developer.opentext.com/apis/061923d5-1fc8-4f78-a6e2-6d276a3fcfe0/Connected-Workspaces-REST-API

Looks like I didn't find it previously for a few reasons - at the most basic, the search box on the APIs page (https://developer.opentext.com/apis ) does not index the contents of the various APIs, it only filters the product names in the catalog. Similarly the documentation search facility at knowledge.opentext.com doesn't surface any API specifications. However, the search box at the very top of the site (https://developer.opentext.com/ ) does index the full content of the APIs specification documents. Additionally, and this speaks to my inexperience, the Connected Workspaces API is presented as a different product from Content Server within the API catalog (presumably due to feature licensing issues?) so I didn't spend enough time rooting around manually either.

I'm still stumped on the SOAP calls though so I'd appreciate any suggestions you might have Appu.

Appu Nair

hi Kris,

Your question...

SOAP libraries are usually given out by OT and in regular services, it exists on OTHOME\webservices and java and dot net versions, The config file of that webservice determines which livelink server and port it works with.in IIS installations one is led to believe that something mysteriously exposed on the livelink server accomplishes SOAP but that is not the case the proxies that developers download allows the client code to reach a Livelink server. As for what happens at the end of the SOAP call is completely written inside oscript if you run Sysreport lite if you are not a programmer you will see the NodeTypes registration. Nowadays OT bundles subtype 848 part of the old XECM/TW in core code.In XECM installs one takes the jar equivalent of proxies and puts them in a TC server and calls that ECMLINK services. For reasons unknown to me, it is not given out as WCF as in the dot net equivalent.Side Note: When we create a web service as taught in SDK class one actually creates the LLNode/Webnode registration pair(think 0,144,848 and such like) then we run certain scripts in Visual Studio to generate the dot net proxies, then we take that and run ant scripts to generate the jars .it is very confusing if you do not come like me from the dot net or java world but at the end of it you get those proxies...What I am trying to say is that the 848 has been represented in core oscript that is why you can call the REST endpoints.REST also will only work if the subtype is defined.

SOAP is easier to work with when you are working with workspaces as one does not need to actually figure out the category information in CS so for e.g to create a WKSPACE in soap one just says the external system id,objectid, and objecttype the metadata if needed is passed as name-value pairs, the receiving code makes a determination of understanding how to take those name values and map it into categories which is a setup activity in XECM.

Compared to that a REST Wkspace creation means the caller needs to present this information in true gory fashion of CS category implementations a small payload shown that creates a business workspace

api/v2/businessworkspaces shown in Jquery code as taken form postman

The smartUI has helpers that allow it to form a form payload and so on..

var form = new FormData();

form.append("body", "{\"template_id\":93403,\"name\":\"Workspace name is generated automatically.\",\"type\":848,\"parent_id\":92964,\"bo_type\":\"ASSET\",\"bo_type_id\":2,\"bo_type_name\":\"ExtSystemID - Asset\",\"description\":\"\",\"ext_system_id\":\"ExtSystemID\",\"ext_system_name\":\"ExtSystemID\",\"external_identity\":\"\",\"external_identity_type\":\"\",\"external_source\":\"\",\"ibo_workspace_id\":0,\"reference_type\":\"1\",\"mime_type\":\"Business Workspace\",\"size\":\"\",\"roles\":{\"categories\":{\"94284\":{\"94284_2\":\"\",\"94284_3\":\"\",\"94284_4\":\"\",\"94284_5\":\"\",\"94284_6\":\"\",\"94284_7\":\"\",\"94284_8\":\"\",\"94284_9\":\"\",\"94284_10\":\"\",\"94284_11\":\"\",\"94284_12\":\"\",\"94284_13\":\"\",\"94284_14\":\"\",\"94284_15\":\"\",\"94284_16\":\"\",\"94284_17\":\"\",\"94284_18\":\"\",\"94284_19\":\"\",\"94284_1\":{\"version_number\":1}}},\"classifications\":{\"create_id\":[92965],\"id\":[]}},\"source_parent_id\":92964}");

var settings = {

"url": "http:///otcs/cs.exe/api/v2/businessworkspaces",

"method": "POST",

"timeout": 0,

"headers": {

"otdsticket": "*OTDSSSO**"

"processData": false,

"mimeType": "multipart/form-data",

"contentType": false,

"data": form

};

$.ajax(settings).done(function (response) {

console.log(response);

});

Note the integrator/ programmer needs to know that 93403 is a template 94284 is a category the trailing 2 and 3s are its attributes

compared to its soap implementation is much more verbose....

Hope that clears where you find the soap libraries :)

Kris Boutilier

Thanks for that detailed information.

I'm good with deploying the additional .net webservices on the CS server(s) and everything is working correctly there. I already have quite a bit of production Java code interacting purely through SOAP calls.

However, if I understand you correctly, the Connected Workspace builder functionality is simply not exposed through the .net implementation of the services that power that API - so there is currently no way for me to use SOAP calls to issue a request to the appropriate Workspace Type definition, along with the required Category Attribute values for that specific type, so that the CS server can populate the 'business workspace name pattern', the 'workspace creation location' and 'sublocation path' pattern, and so on as part of the process of creating the concrete instance of the new subtype 848 node under the uniquely calculated parent_id. Yes, executing that process through REST calls (now I've read the API documentation and your notes) is working well so I'll consider that my only path forward.

My latest challenge seems to be finding the REST equivalent for the getCategoryDefinition() and related calls from the com.opentext.livelink.service.docman SOAP interface... Ideally, as you've suggested, I could use the ActiveView function that interacts with Category definitions (similar to ?func=ll&objAction=EditTemplate in the classic interface) to allow me to sleuth out the appropriate REST calls, but it doesn't look like anything has been implemented to interact with Category definitions yet.

The more I look at this the more it feels like I'll need to use a mashup of both the SOAP and REST APIs to access the full functionality of the system because both APIs currently seem to have quite different functionality gaps. That's not ideal but if it gets the job done then that's the way it has to be until those inconsistencies are resolved.

Again, thank you for your time. It's very appreciated.