Connected Workspaces – Using the REST API
originally posted March 2019 | 🕐️ 11 minute read
Overview
Connected Workspaces are the main integration element used in OpenText Content Suite and OpenText Extended ECM. A business-centric API is available as part of Extended ECM Platform that saves the application developer from knowing about OpenText Content Server internals like nodes, templates and categories with their unique identifiers.
But sometimes, application developers want to have control about the creation workflow on their own and build a proprietary integration. This requires a deep understanding of the REST API and the underlying concepts.
In this document you learn basic operations with the REST API for workspaces. First the external application needs to authenticate. Then it is shown how to create a business workspace. Then you see how you can modify roles and participants.
Authentication
Authenticate a User
To authenticate a user, the credentials are sent.
Request
POST http://cs.example.com/OTCS/cs.exe/api/v1/auth
Form-Data
username=Admin001&password=123Bla
Response
{
"ticket": "x8kiQeEKQJesJFNmd7z3PGkLxri37wzoMAALheXP6btmdT8NGKbq\/xDOSQYALp3VI2QEpfuD56mxgwMdcHH8\/XgJF5EWomAl"
}
The client application takes the ticket from the “ticket” property in the result and sends it as request header field “otcsticket” with each subsequent request. This header field must be passed to the server with each request. Note that in the examples below, we do not mention this explicitly, as it is the same for every request. Yet it is necessary, otherwise the request will fail due to an authentication failure.
Creating Business Workspaces
To create a business workspace the external application needs to
- Understand which templates are applicable in a certain target location
- Retrieve the details of specific template as a form
- Map the application data into the form fields
- Trigger the workspace creation with the provided form
The following example will illustrate this procedure.
Applicable Templates
First, get all templates that can be used to create a business workspace in a folder, here the folder with ID 14313.
Request
GET http://cs.example.com/OTCS/cs.exe/api/v1/nodes/14313/businessworkspacetypes
Response
{
"businessworkspacetypes": [
{
"id": 1,
"name": "Contract",
"rm_enabled": false,
"templates": [
{
"id": 14316,
"name": "Contract template",
"subType": 848
}
]
},
{
"id": 2,
"name": "Customer",
"rm_enabled": false,
"templates": [
{
"id": 14318,
"name": "Customer template",
"subType": 848
}
]
}
]
}
In this example, there are two workspace types available, each of which associated with one template. Let us create a workspace for the “Contract” workspace type (ID 1) using its associated template (ID 14316).
Retrieve Template Details
The next step is to retrieve the creation form providing the necessary category information (the value for the parameter parent_id is the same as in the previous call, type is always 848, wksp_type_id is the ID from the previous call. Also, the template ID can be taken from the previous call):
Request
GET http://cs.example.com/OTCS/cs.exe/api/v2/forms/businessworkspaces/create?parent_id=14313&type=848&wksp_type_id=1&template_id=14316
Response
{
"forms": [
{
"data": {"description":"","external_create_date":null,"external_identity":"","external_identity_type":"","external_modify_date":null,"external_source":"","name":null,"parent_id":14313,"reference_type":1,"type":848},
"options": {"fields":{"name":{"hidden":false,"hideInitValidationError":true,"label":"Name","readonly":false,"type":"text"},"description":{"hidden":false,"hideInitValidationError":true,"label":"Description","readonly":false,"type":"textarea"},"parent_id":{"hidden":true,"hideInitValidationError":true,"label":"Location","readonly":false,"type":"otcs_node_picker"},"external_create_date":{"hidden":false,"hideInitValidationError":true,"label":"External Create Date","readonly":false,"type":"datetime"},"external_modify_date":{"hidden":false,"hideInitValidationError":true,"label":"External Modify Date","readonly":false,"type":"datetime"},"external_source":{"hidden":false,"hideInitValidationError":true,"label":"External Source","readonly":false,"type":"text"},"external_identity":{"hidden":false,"hideInitValidationError":true,"label":"External Identity","readonly":false,"type":"text"},"external_identity_type":{"hidden":false,"hideInitValidationError":true,"label":"External Identity Type","readonly":false,"type":"text"},"reference_type":{"hidden":true,"hideInitValidationError":true,"label":"Workspace Type","readonly":true,"required":false,"type":"text"},"type":{"hidden":true,"hideInitValidationError":true,"type":"integer"}},"form":{"attributes":{"action":"api/v1/nodes","method":"POST"},"renderForm":true}},
"schema": {"properties":{"name":{"maxLength":248,"minLength":1,"readonly":false,"required":true,"title":"Name","type":"string"},"description":{"default":"","readonly":false,"required":false,"title":"Description","type":"string"},"parent_id":{"readonly":false,"required":true,"title":"Location","type":"integer"},"external_create_date":{"readonly":false,"required":false,"title":"External Create Date","type":"string"},"external_modify_date":{"readonly":false,"required":false,"title":"External Modify Date","type":"string"},"external_source":{"default":"","readonly":false,"required":false,"title":"External Source","type":"string"},"external_identity":{"default":"","readonly":false,"required":false,"title":"External Identity","type":"string"},"external_identity_type":{"default":"","readonly":false,"required":false,"title":"External Identity Type","type":"string"},"reference_type":{"readonly":true,"required":false,"title":"Workspace Type","type":"string"},"type":{"required":true,"type":"integer"}},"type":"object"}
},
{
"data": {
"26196": {
"26196_2": null,
"26196_3": null,
"26196_4": null,
"26196_5": null,
"26196_1": { "version_number": 1 }
}
},
"options": {"fields":{"26196":{"fields":{"26196_2":{"hidden":false,"hideInitValidationError":true,"label":"Name","readonly":false,"type":"text"},"26196_3":{"hidden":false,"hideInitValidationError":true,"label":"Country","readonly":false,"type":"text"},"26196_4":{"hidden":false,"hideInitValidationError":true,"label":"Area","readonly":false,"type":"text"},"26196_5":{"hidden":false,"hideInitValidationError":true,"label":"Contact","readonly":false,"type":"text"},"26196_1":{"hidden":true,"hideInitValidationError":true,"readonly":true,"type":"object"}},"hideInitValidationError":true,"label":"Contract Properties","removeable":false,"type":"object"}}},
"role_name": "categories",
"schema": {
"properties": {
"26196": {
"properties": {
"26196_2": {
"maxLength": 32,
"readonly": false,
"required": false,
"title": "Name",
"type": "string"
},
"26196_3": {
"maxLength": 32,
"readonly": false,
"required": false,
"title": "Country",
"type": "string"
},
"26196_4": {"maxLength":32,"readonly":false,"required":false,"title":"Area","type":"string"},
"26196_5": {"maxLength":32,"readonly":false,"required":false,"title":"Contact","type":"string"},
"26196_1": {"readonly":true,"required":false,"type":"object"}
},
"title": "Contract Properties",
"type": "object"
}
},
"title": "Categories",
"type": "object"
}
},
{
"data": { "id": null, "name": null, "type": null, "selectable": null, "management_type": null, "score": null, "inherit_flag": null, "classvolumeid": 2059, "parent_managed": true },
"options": {"fields":{"id":{"fields":{"item":{"type":"number"}},"hidden":false,"hideInitValidationError":true,"items":{"showMoveDownItemButton":false,"showMoveUpItemButton":false},"label":"Classification","readonly":false,"toolbarSticky":true},"name":{"hidden":false,"hideInitValidationError":true,"label":"Classification Name","readonly":false,"type":"text"},"type":{"hidden":false,"hideInitValidationError":true,"label":"Subtype","readonly":false,"type":"integer"},"selectable":{"hidden":false,"hideInitValidationError":true,"label":"Selectable","readonly":false,"type":"checkbox"},"management_type":{"hidden":false,"hideInitValidationError":true,"label":"Management Type","readonly":false,"type":"text"},"score":{"hidden":false,"hideInitValidationError":true,"label":"Score","readonly":false,"type":"text"},"inherit_flag":{"hidden":false,"hideInitValidationError":true,"label":"Inherit","readonly":false,"type":"checkbox"},"classvolumeid":{"hidden":false,"hideInitValidationError":true,"label":"Classification Volume ID","readonly":false,"type":"integer"},"parent_managed":{"hidden":false,"hideInitValidationError":true,"label":"Parent managed","readonly":false,"type":"checkbox"}}},
"role_name": "classifications",
"schema": {"properties":{"id":{"items":{"defaultItems":null,"maxItems":null,"minItems":1,"type":"integer"},"readonly":false,"required":false,"title":"Classification","type":"array"},"name":{"readonly":false,"required":false,"title":"Classification Name","type":"string"},"type":{"readonly":false,"required":false,"title":"Subtype","type":"integer"},"selectable":{"readonly":false,"required":false,"title":"Selectable","type":"boolean"},"management_type":{"readonly":false,"required":false,"title":"Management Type","type":"string"},"score":{"readonly":false,"required":false,"title":"Score","type":"string"},"inherit_flag":{"readonly":false,"required":false,"title":"Inherit","type":"boolean"},"classvolumeid":{"readonly":false,"required":false,"title":"Classification Volume ID","type":"integer"},"parent_managed":{"readonly":false,"required":false,"title":"Parent managed","type":"boolean"}},"title":"Classifications","type":"object"}
}
]
}
The JSON element “forms” of the result is a list of forms. In there is one element, where the property “role_name” has the value “categories”. The properties branch in this element contains the ID of the category (26196 in this example). Under properties the ids of the attributes in the category are listed. For example: the attribute “Name” has the ID 26196_2 and the attribute “Country” has the ID 26196_3.
If the information is known upfront from some configuration then those two calls don’t need to be issued.
Passing the Data and Creating the Workspace
The workspace is then created with a POST call.
Request
POST http://cs.example.com/OTCS/cs.exe/api/v2/businessworkspaces
Complex parameters like categories can’t be set as URL parameters. They must be provided as JSON data in the request body. Data can’t be provided directly in the body, it must be wrapped in a multipart/form-data part with the name “body”.
Form-Data
------WebKitFormBoundaryPb17HIb2ZVnehkhz
Content-Disposition: form-data; name="body"
{"template_id":14316,"name":"Contract 003","type":848,"parent_id":14313,"description":"","external_source":"","external_identity":"","external_identity_type":"","reference_type":"1","mime_type":"Business Workspace","size":"","roles":{"categories":{"26196":{"26196_2":"Mega-Deal","26196_3":"Germany","26196_4":"","26196_5":"","26196_1":{"version_number":1}}},"classifications":{"create_id":[14315],"id":[]}},"source_parent_id":14313}
------WebKitFormBoundaryPb17HIb2ZVnehkhz--
Body
The JSON structure of the body in this example is as follows:
{
"template_id": 14316,
"name": "Contract 003",
"type": 848,
"parent_id": 14313,
"description": "",
"external_source": "",
"external_identity": "",
"external_identity_type": "",
"reference_type": "1",
"mime_type": "Business Workspace",
"size": "",
"roles": {
"categories": {
"26196": {
"26196_2": "Mega-Deal",
"26196_3": "Germany",
"26196_4": "",
"26196_5": "",
"26196_1": { "version_number": 1 }
}
},
"classifications": {
"create_id": [
14315
],
"id": []
}
The category data must be delivered in the roles/categories section. In this example we set the attribute 26196_2 (Name) to “Mega-Deal” and attribute 26196_3 (Country) to “Germany”. The version number is the version of the category and can be retrieved from the data section of the forms call as shown above.
It’s worth mentioning that also the correct classification information needs to be passed.
The result of the POST operation above is the creation of a new business workspaces node and the ID is returned.
Summary
This example illustrates the workspace creation based on templates and how an application developer can pass the necessary data.
Updating Roles and Members
For an existing workspace instance, we’ll now illustrate how to update the participants using the REST API.
Existing Roles and Members
Get the existing roles including members of a business workspace (where the node ID of the business workspace is 14972).
Request
GET http://cs.example.com/OTCS/cs.exe/api/v2/businessworkspaces/14972/roles?fields=members
Response
{
"links": {"data":{"self":{"body":"","content_type":"","href":"/api/v2/businessworkspaces/14972/roles"}}},
"results": [
{
"actions": {"data":{"change-reference":{"body":"","content_type":"","form_href":"","href":"","method":"","name":""},"complete-reference":{"body":"","content_type":"","form_href":"","href":"","method":"","name":""},"delete-role":{"body":"","content_type":"","form_href":"","href":"/api/v2/businessworkspaces/14972/roles/17070","method":"DELETE","name":"Delete Role"},"edit-role":{"body":"","content_type":"","form_href":"","href":"/api/v2/businessworkspaces/14972/roles/17070","method":"PUT","name":"Edit Role"}},"map":{},"order":[]},
"data": {"members":[{"birth_date":null,"business_email":null,"business_fax":null,"business_phone":null,"cell_phone":null,"deleted":false,"display_name":"user001","first_name":"First","gender":null,"group_id":1001,"group_name":"DefaultGroup","home_address_1":null,"home_address_2":null,"home_fax":null,"home_phone":null,"id":17074,"last_name":"One","middle_name":null,"name":"user001","office_location":null,"pager":null,"personal_email":null,"personal_interests":null,"personal_url_1":null,"personal_url_2":null,"personal_url_3":null,"personal_website":null,"photo_id":null,"privilege_grant_discovery":false,"privilege_login":true,"privilege_modify_groups":false,"privilege_modify_users":false,"privilege_public_access":true,"privilege_system_admin_rights":false,"privilege_user_admin_rights":false,"time_zone":-1,"title":null,"type":0,"type_name":"User"}],"properties":{"description":"","id":17070,"inherited_from_id":null,"leader":true,"name":"C2R1","perms":258207}}
},
{
"actions": {"data":{"change-reference":{"body":"","content_type":"","form_href":"","href":"","method":"","name":""},"complete-reference":{"body":"","content_type":"","form_href":"","href":"","method":"","name":""},"delete-role":{"body":"","content_type":"","form_href":"","href":"/api/v2/businessworkspaces/14972/roles/17071","method":"DELETE","name":"Delete Role"},"edit-role":{"body":"","content_type":"","form_href":"","href":"/api/v2/businessworkspaces/14972/roles/17071","method":"PUT","name":"Edit Role"}},"map":{},"order":[]},
"data": {
"members": [
{
"birth_date": null, "business_email":null,"business_fax":null,"business_phone":null,"cell_phone":null,"deleted":false,
"display_name": "user003",
"first_name": "Third", "gender":null,"group_id":1001,"group_name":"DefaultGroup","home_address_1":null,"home_address_2": null,"home_fax": null,"home_phone":null,
"id": 17078,
"last_name": "Three",
"middle_name": null,
"name": "user003", "office_location":null,"pager":null,"personal_email":null,"personal_interests":null,"personal_url_1":null,"personal_url_2":null,"personal_url_3":null,"personal_website":null,"photo_id":null,"privilege_grant_discovery":false,"privilege_login":true,"privilege_modify_groups":false,"privilege_modify_users":false,"privilege_public_access":true,"privilege_system_admin_rights":false,"privilege_user_admin_rights":false,"time_zone":-1,"title":null,"type":0,"type_name":"User"
},
{
"birth_date": null,"business_email":null,"business_fax":null,"business_phone":null,"cell_phone":null,"deleted":false,
"display_name": "user002",
"first_name": "Second", "gender":null,"group_id":17075,"group_name":"Group A OT-Research & Development-Qualitiy Assurance","home_address_1":null,"home_address_2":null,"home_fax":null,"home_phone":null,
"id": 17080,
"last_name": "Two",
"middle_name": null,
"name": "user002", "office_location":null,"pager":null,"personal_email":null,"personal_interests":null,"personal_url_1":null,"personal_url_2":null,"personal_url_3":null,"personal_website":null,"photo_id":null,"privilege_grant_discovery":false,"privilege_login":true,"privilege_modify_groups":false,"privilege_modify_users":false,"privilege_public_access":true,"privilege_system_admin_rights":false,"privilege_user_admin_rights":false,"time_zone":-1,"title":null,"type":0,"type_name":"User"
}
],
"properties": {
"description": "",
"id": 17071,
"inherited_from_id": null,
"leader": false,
"name": "C2R3",
"perms": 258183
}
}
}
]
}
Updating a Role
The intention is now to change the name of a role and make it the leader role. In the response of the previous request there is a role “C2R3” with ID 17071, which is not the leader role. Renaming the role to “C2R2” and making it the leader role can be done in one request.
Request
PUT http://cs.example.com/OTCS/cs.exe/api/v2/businessworkspaces/14972/roles/17071?name=C2R2&leader=true
Response
{
"links": {"data":{"self":{"body":"","content_type":"","href":"/api/v2/businessworkspaces/14972/roles/17071","method":"PUT","name":""}}},
"results": {
"data": {
"properties": {
"description": "",
"id": 17071,
"inherited_from_id": null,
"leader": true,
"name": "C2R2",
"perms": 258183
}
}
}
}
In the response the new properties of the role with name “C2R2” and the “leader” flag with value “true” is returned.
Deleting a Participant
In order to delete a participant from a role you need the ID for the business workspace, for the role and for the participant. All can be determined using the output from the request described above in “Existing Roles and Members”. In this example the business workspace ID is 14972, the role ID is 17071 and the member ID is 17078 (user003):
Request
DELETE http://cs.example.com/OTCS/cs.exe/api/v2/businessworkspaces/14972/roles/17071/members/17078
Response
{
"links": {"data":{"self":{"body":"","content_type":"","href":"/api/v2/businessworkspaces/14972/roles/17071/members/17078","method":"DELETE","name":""}}},
"results": {}
}
An empty result object together with HTTP status code 200 indicates the successful deletion of the participant.
Summary
This example illustrates how to get roles and members and how to update roles and members using the REST API.
Categories
- All Categories
- 122 Developer Announcements
- 53 Articles
- 149 General Questions
- 148 Thrust Services
- 56 OpenText Hackathon
- 36 Developer Tools
- 20.6K Analytics
- 4.2K AppWorks
- 9K Extended ECM
- 917 Cloud Fax and Notifications
- 84 Digital Asset Management
- 9.4K Documentum
- 31 eDOCS
- 181 Exstream
- 39.8K TeamSite
- 1.7K Web Experience Management
- 8 XM Fax
- Follow Categories