This collection provides a few common scenarios for Exstream API usage:
\nThe project you build needs a service request application created in Control Center whose port you need to call in the requests (defined in the environment variable SdpPort). The project itself needs to have an input channel of type Service Request of request type Generic with a service name set. The service name should also be set in the environment variable ServiceRequestInputName.
To start, all API calls need to be preceeded by requesting an authentication ticket. To authenticate, create a POST request as shown in the Authenticate folder. After having yourself authenticated successfully, you can proceed with any of the scenarios listed in the folders below.
Authentication is required to call most other APIs and should be your first step.
\nDepending on how you have installed your tenants, you either have to use the Authenticate Tenant (when using a separate tenant OTDS) or Authenticate Multitentant (for example when using the default bootstrap installation) request.
ProtocolOtds: protocol used for authentication (http or https)OtdsHost: fully qualified hostname of the OTDS serverOtdsPort: port for connecting to the OTDS serverTenantUserName: username for logging in (typically with the role of tenant administrator)TenantUserPassword: matching passwordOTDSTicket: the authorization ticket to use in the header for subsequent API callsA batch document gets created bypassing the message store. Therefore, no release or approval step is required. This also means that a user cannot modify the document in Retouch before printing.
Only one request is necessary to trigger this type of processing.
\nNote: you can control if you want to return the document produced in the payload. Check Include result in service response in the (PDF) output connector under the General section of the logical layer for sending the result back in the response.
The response carries the payload base64 formated. In order to decode and save the content to a file, run the following in your terminal:
base64 -d -o ~/Desktop/decoded.pdf <<< EncodedString\nYou will find the complete command in the debug console: go to the Application Menu > View > Show Postman Console. In the console, you will also see the encoded and the decoded file.
\n\nPlease note, that you cannot copy the decoded file out of there, because Postman adds non-printable return characters to the output which breaks the binary files.
\n
ProtocolExstream: protocol used for authentication (http or https)ExstreamHost: fully qualified hostname for the Exstream serverExstreamPort: REST port for the Exstream service gatewayServiceRequestInputName: name of the service request as defined in the input connector.ExstreamProjectVersion: Exstream project version (e.g. visible when checking out a project from the CAS next to the commit message)ThemeId: optional. A valid id can be found by calling the request List Themes from the Utilities folder. If left out, you will get one output per theme.SourceDataPlain: The XML source data to process.none
\n","event":[{"listen":"prerequest","script":{"id":"cd378f45-960a-4f48-8dee-e9015b074be3","type":"text/javascript","exec":["pm.test('OTDSTicket should be available', function () {"," pm.expect(pm.environment.has('OTDSTicket')).to.equal(true);","});","","pm.test('OTDSTicket should be set', function () {"," pm.expect(pm.environment.get(\"OTDSTicket\")).to.not.be.empty;","});"]}},{"listen":"test","script":{"id":"4d60f234-d7d9-4103-9670-b8e1dfe21d3c","type":"text/javascript","exec":[""]}}],"_postman_id":"0f9339e8-a5fa-47b4-b488-3983d1fa2a52","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"OTDSTicket"},{"key":"value","value":"{{OTDSTicket}}"}]},"isInherited":true,"source":{"_postman_id":"4c0de704-ea37-4ef5-8eb7-f2e999bd41e3","id":"4c0de704-ea37-4ef5-8eb7-f2e999bd41e3","name":"Exstream 16.6 API","type":"collection"}}},{"name":"Create on-demand document","item":[{"name":"Create Document","event":[{"listen":"test","script":{"id":"79dac493-87a5-4601-afa8-cebbfa6748f3","exec":["var jsonData = JSON.parse(responseBody);\r","postman.setEnvironmentVariable(\"DocId\", jsonData.data.messageId);"],"type":"text/javascript"}},{"listen":"prerequest","script":{"id":"b3654335-ba06-4e1b-91f6-6035a8c77b98","exec":["var plainData = pm.environment.get('SourceDataPlain');","var encodedData = CryptoJS.enc.Base64.stringify(CryptoJS.enc.Utf8.parse(plainData));","","console.log(`Encoded source data: ${encodedData}`);","pm.environment.set(\"SourceDataBase64\", encodedData);"],"type":"text/javascript"}}],"id":"e23b0162-118a-4584-8a65-ee7a9a0623a1","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"equals":true,"key":"OTDSTicket","value":"{{OTDSTicket}}"}],"body":{"mode":"raw","raw":"{\n \"theme\": {\n \"id\": \"{{ThemeId}}\"\n },\n \"content\": {\n \"data\": \"{{SourceDataBase64}}\",\n \"contentType\": \"text/xml\"\n }\n}","options":{"raw":{"language":"json"}}},"url":"{{ProtocolExstream}}://{{ExstreamHost}}:{{ExstreamPort}}/v3/documents","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"OTDSTicket"},{"key":"value","value":"{{OTDSTicket}}"}]},"isInherited":true,"source":{"_postman_id":"4c0de704-ea37-4ef5-8eb7-f2e999bd41e3","id":"4c0de704-ea37-4ef5-8eb7-f2e999bd41e3","name":"Exstream 16.6 API","type":"collection"}},"urlObject":{"protocol":"{{ProtocolExstream}}","port":"{{ExstreamPort}}","path":["v3","documents"],"host":["{{ExstreamHost}}"],"query":[],"variable":[]}},"response":[],"_postman_id":"e23b0162-118a-4584-8a65-ee7a9a0623a1"},{"name":"Approve document","event":[{"listen":"test","script":{"id":"01024a2f-6cc4-4234-b050-e50d5a314db5","exec":["var jsonData = JSON.parse(responseBody);\r","postman.setEnvironmentVariable(\"ApprovedRevision\", jsonData.data.revision);"],"type":"text/javascript"}}],"id":"968c25c5-93f9-4fc7-b9d7-22538440a9d5","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"PUT","header":[{"key":"OTDSTicket","value":"{{OTDSTicket}}","type":"text"}],"body":{"mode":"raw","raw":"{\n \"state\": \"Approved\"\n}","options":{"raw":{"language":"json"}}},"url":"{{ProtocolExstream}}://{{ExstreamHost}}:{{ExstreamPort}}/v1/documents/{{DocId}}?where_revision=-1","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"OTDSTicket"},{"key":"value","value":"{{OTDSTicket}}"}]},"isInherited":true,"source":{"_postman_id":"4c0de704-ea37-4ef5-8eb7-f2e999bd41e3","id":"4c0de704-ea37-4ef5-8eb7-f2e999bd41e3","name":"Exstream 16.6 API","type":"collection"}},"urlObject":{"protocol":"{{ProtocolExstream}}","port":"{{ExstreamPort}}","path":["v1","documents","{{DocId}}"],"host":["{{ExstreamHost}}"],"query":[{"key":"where_revision","value":"-1"}],"variable":[]}},"response":[],"_postman_id":"968c25c5-93f9-4fc7-b9d7-22538440a9d5"},{"name":"Release document","id":"b8a3c2cf-97b9-4f03-bf12-e2ffa34d8cd5","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"PUT","header":[{"key":"OTDSTicket","value":"{{OTDSTicket}}","type":"text"}],"body":{"mode":"raw","raw":"{\n \"state\": \"Released\"\n}","options":{"raw":{"language":"json"}}},"url":"{{ProtocolExstream}}://{{ExstreamHost}}:{{ExstreamPort}}/v1/documents/{{DocId}}?where_revision={{ApprovedRevision}}","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"OTDSTicket"},{"key":"value","value":"{{OTDSTicket}}"}]},"isInherited":true,"source":{"_postman_id":"4c0de704-ea37-4ef5-8eb7-f2e999bd41e3","id":"4c0de704-ea37-4ef5-8eb7-f2e999bd41e3","name":"Exstream 16.6 API","type":"collection"}},"urlObject":{"protocol":"{{ProtocolExstream}}","port":"{{ExstreamPort}}","path":["v1","documents","{{DocId}}"],"host":["{{ExstreamHost}}"],"query":[{"key":"where_revision","value":"{{ApprovedRevision}}"}],"variable":[]}},"response":[],"_postman_id":"b8a3c2cf-97b9-4f03-bf12-e2ffa34d8cd5"}],"id":"64f4b220-a0ca-45fc-bcb0-7c228ff42600","description":"Producing an on-demand document involves a few steps:
\nRetouch. This step is optional and currently not documented here.Note: you can search for your document placed in the document store by calling Get documents from message store from the Utilities folder.
ProtocolExstream: protocol used for authentication (http or https)ExstreamHost: fully qualified hostname for the Exstream serverExstreamPort: REST port for the Exstream service gatewayThemeId: a valid id can be found by calling the request List Themes from the Utilities folder. If left out, you will get one output per theme.SourceDataPlain: The XML source data to process.DocId: the message ID of the document generated.Get a list of all themes currently available in the system.
\n","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"OTDSTicket"},{"key":"value","value":"{{OTDSTicket}}"}]},"isInherited":true,"source":{"_postman_id":"4c0de704-ea37-4ef5-8eb7-f2e999bd41e3","id":"4c0de704-ea37-4ef5-8eb7-f2e999bd41e3","name":"Exstream 16.6 API","type":"collection"}},"urlObject":{"protocol":"{{ProtocolExstream}}","port":"{{ExstreamPort}}","path":["v1","themes"],"host":["{{ExstreamHost}}"],"query":[],"variable":[]}},"response":[],"_postman_id":"facb09ec-a84d-4e65-ab1e-85914bb25888"},{"name":"Get documents from message store","id":"051b1a6a-4953-4fd3-81bd-2de8a0b20bcf","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"{{ProtocolExstream}}://{{ExstreamHost}}:{{ExstreamPort}}/v1/documents?where_typeid=messageobject&fields=messageId,6B84E18B-F03D-350C-E040-007F0200026D","description":"Get a list of all documents stored in the message store. The request is currently only outputting two fields: message id and external message id, but this can be changed by removing or adding additional fields from the fields parameter.
Note: In order to populate the external ID, set a script on Event retrieved:
// GUID for \"External Job ID\" is 6B84E18B-F03D-350C-E040-007F0200026D\n$msgId = \"AppOne-\" + getdatetime(\"YYYYMMDD\") + \"-\" + getdatetime(\"HHMMSS\");\nSetMetaDataMessage(\"6B84E18B-F03D-350C-E040-007F0200026D\", $msgId);\nNote: using the Event retrieved event is critical. Otherwise the ID will get set too late and is not written to the message store.
Message ID and External Message ID
\n","type":"text/plain"},"key":"fields","value":"messageId,6B84E18B-F03D-350C-E040-007F0200026D"}],"variable":[]}},"response":[],"_postman_id":"051b1a6a-4953-4fd3-81bd-2de8a0b20bcf"},{"name":"List Services","event":[{"listen":"prerequest","script":{"id":"39957ba8-ef08-4f6f-a6e8-0e7228529de6","exec":["var plainData = pm.environment.get('SourceDataPlain');","var encodedData = CryptoJS.enc.Base64.stringify(CryptoJS.enc.Utf8.parse(plainData));","","console.log(`Encoded source data: ${encodedData}`);","pm.environment.set(\"SourceDataBase64\", encodedData);"],"type":"text/javascript"}},{"listen":"test","script":{"id":"38fa531d-670e-4c28-8904-1b86fa24762b","exec":["var jsonData = JSON.parse(responseBody);","","try {"," documentEncoded = jsonData.data.result[0].content.data;"," documentDecoded = atob(documentEncoded);"," "," console.log('returned document encoded:\\n');"," console.log(documentEncoded);"," "," console.log('returned document decoded:\\n');"," console.log(documentDecoded);"," "," console.log('In macOS, to save the decoded file, run the following in your terminal: ');"," console.log('base64 -d -o ~/Desktop/decoded.pdf <<< ' + documentEncoded);","}","catch (error) {"," console.log('no document retrieved');","}"],"type":"text/javascript"}}],"id":"1871b533-d871-45c3-aeb6-0be4feefddd0","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"OTDSTicket","type":"text","value":"{{OTDSTicket}}"}],"body":{"mode":"raw","raw":"{\r\n\t\"theme\" : {\r\n \"id\" : \"{{ThemeId}}\"\r\n },\r\n \"content\": {\r\n\t\t\"contentType\": \"text/xml\",\r\n\t\t\"data\": \"{{SourceDataBase64}}\"\r\n\t}\r\n}","options":{"raw":{"language":"json"}}},"url":"{{ProtocolExstream}}://{{ExstreamHost}}:{{ExstreamPort}}/v1/services?ignore_templates=true","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"OTDSTicket"},{"key":"value","value":"{{OTDSTicket}}"}]},"isInherited":true,"source":{"_postman_id":"4c0de704-ea37-4ef5-8eb7-f2e999bd41e3","id":"4c0de704-ea37-4ef5-8eb7-f2e999bd41e3","name":"Exstream 16.6 API","type":"collection"}},"urlObject":{"protocol":"{{ProtocolExstream}}","port":"{{ExstreamPort}}","path":["v1","services"],"host":["{{ExstreamHost}}"],"query":[{"key":"ignore_templates","value":"true"}],"variable":[]}},"response":[],"_postman_id":"1871b533-d871-45c3-aeb6-0be4feefddd0"}],"id":"4875ae9a-099a-4a70-a66f-1327ba968c07","event":[{"listen":"prerequest","script":{"id":"b13ddf77-daab-47a3-b664-c8d84d870b32","type":"text/javascript","exec":["pm.test('OTDSTicket should be available', function () {"," pm.expect(pm.environment.has('OTDSTicket')).to.equal(true);","});","","pm.test('OTDSTicket should be set', function () {"," pm.expect(pm.environment.get(\"OTDSTicket\")).to.not.be.empty;","});"]}},{"listen":"test","script":{"id":"9d46af62-f554-4ddc-b56e-b15b686913e9","type":"text/javascript","exec":[""]}}],"_postman_id":"4875ae9a-099a-4a70-a66f-1327ba968c07","description":"","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"OTDSTicket"},{"key":"value","value":"{{OTDSTicket}}"}]},"isInherited":true,"source":{"_postman_id":"4c0de704-ea37-4ef5-8eb7-f2e999bd41e3","id":"4c0de704-ea37-4ef5-8eb7-f2e999bd41e3","name":"Exstream 16.6 API","type":"collection"}}},{"name":"Beta","item":[{"name":"Trigger Exstream from Web Form","id":"3ab34218-dd8a-4893-92a0-11597899708d","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"body":{"mode":"formdata","formdata":[{"key":"Begin","value":"authenticate","type":"text"},{"key":"user","value":"exuser","type":"text"},{"key":"password","value":"opentext","type":"text"}]},"url":"localhost:8001?","description":"Submit a HTML form to a StreamIn event listening at an http port.
\n","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"OTDSTicket"},{"key":"value","value":"{{OTDSTicket}}"}]},"isInherited":true,"source":{"_postman_id":"4c0de704-ea37-4ef5-8eb7-f2e999bd41e3","id":"4c0de704-ea37-4ef5-8eb7-f2e999bd41e3","name":"Exstream 16.6 API","type":"collection"}},"urlObject":{"port":"8001","host":["localhost"],"query":[{"key":"","value":null},{"disabled":true,"key":"Content-type","value":"application/json"}],"variable":[]}},"response":[],"_postman_id":"3ab34218-dd8a-4893-92a0-11597899708d"}],"id":"17d81ceb-0945-46a2-8957-f44c84eccaf3","description":"These requests are currently being worked on and might not be functional.
\n","_postman_id":"17d81ceb-0945-46a2-8957-f44c84eccaf3","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"OTDSTicket"},{"key":"value","value":"{{OTDSTicket}}"}]},"isInherited":true,"source":{"_postman_id":"4c0de704-ea37-4ef5-8eb7-f2e999bd41e3","id":"4c0de704-ea37-4ef5-8eb7-f2e999bd41e3","name":"Exstream 16.6 API","type":"collection"}}}],"auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"OTDSTicket"},{"key":"value","value":"{{OTDSTicket}}"}]}},"event":[{"listen":"prerequest","script":{"id":"e9e01190-8742-4aa6-b0a2-b81a4bbb2f0c","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"81ac3bb5-f92b-4999-aba1-87c60348596e","type":"text/javascript","exec":[""]}}]}