Hi there AppWorks fans,

Welcome to a new installment of AppWorks tips.

With this post I want to share a nice feature that I tried out with input from a great person (you know who you are!) that made me enthusiast about it. This feature has to do with content linking that might solve several use-cases for your solution.

This is a shot from the documentation (AppWorks Platform 20.3 Release Notes.pdf) that explains the feature that we want to try-out in this post:

Also, have a look in the ‘AppWorks Platform 20.3 Low-Code Design Guide.pdf’ where we have nice chapter called ‘Adding business logic’. This chapter was totally empty in the 20.2 version, but in 20.3 it is richly filled with information. Like information about ‘SOAP web services on the application’ and specifically the call we want to make in the section ‘File and Content web services’ within that chapter.

But…

Let get right into it…

…and see how we can call the webservice and what it does in the background!?

Start your VM and open ‘design time’ with our developer account ‘awdev’. We start with a simple ‘project’ entity with a ‘Name’ property, default Create form and a view layout. On top if this we add a ‘File’ building block because we want to play with some content linking webservice later on.

This is how my layout looks like with also a preview panel for the upload of the content of that ‘File’ building block:

With…in runtime a screen like this after we’ve created a new instance of the ‘project’ entity, and the upload of a text document:

Next…

Call the ‘LinkDocument’ webservice

For this to happen we’ll use 2 approaches. First the one via de ‘Web Service Interface Explorer’ where we can do a search for the ‘LinkDocument’ webservice:

Right-click the service and open the ‘Test’ action. You get a new modal popup with a predefined SOAP message that looks like this:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

<SOAP:Envelope xmlns:SOAP="http://schemas.xmlsoap.org/soap/envelope/">
  <SOAP:Body>
    <LinkDocument xmlns="http://schemas.opentext.com/bps/entity/buildingblock/file">
      <Source>
        <ns0:ItemId xmlns:ns0="http://schemas.opentext.com/bps/entity/core">PARAMETER</ns0:ItemId>
        <DocumentPath>PARAMETER</DocumentPath>
        <BusinessWorkspaceId>PARAMETER</BusinessWorkspaceId>
      </Source>
      <Destination>
        <ns0:ItemId xmlns:ns0="http://schemas.opentext.com/bps/entity/core">PARAMETER</ns0:ItemId>
        <FolderPath>PARAMETER</FolderPath>
        <DisplayName>PARAMETER</DisplayName>
      </Destination>
    </LinkDocument>
  </SOAP:Body>
</SOAP:Envelope>

This webservice made me curious for this specific feature quoted from the documentation: A content system directly represented by the path of the document. Let’s find out if we can call something like that where this input would be valid:

1
2
3
4
5
6
7
8
9
10
11
12

<SOAP:Envelope xmlns:SOAP="http://schemas.xmlsoap.org/soap/envelope/">
  <SOAP:Body>
    <LinkDocument xmlns="http://schemas.opentext.com/bps/entity/buildingblock/file">
      <Source>
        <DocumentPath>test</DocumentPath>
      </Source>
      <Destination>
        <ns0:ItemId xmlns:ns0="http://schemas.opentext.com/bps/entity/core">0800273bf379a1eab5ca6723fbb797a6.655361</ns0:ItemId>
      </Destination>
    </LinkDocument>
  </SOAP:Body>
</SOAP:Envelope>

That itemID is retrieved from the runtime URL when you open the ‘project’ entity instance: http://192.168.56.107:8080/home/appworks_tips/app/start/web/item/0800273bf379a1eab5ca6723fbb797a6.655361/0800273bf379a1eab5cb29015b539626/4db832ded4853262967548c42abfeb5e?authID=XXX

We give that document path a simple ‘test’ value to see what the error will be!?

ERROR: Document with the URL 'test' not available in the repository.

Well…as expected!

Now for the great question? What path needs to be used and what is the physic location on the server?

Let’s upload a document to the server location: /opt/opentext/AppWorksPlatform/defaultInst/content/TestDocument.txt

Make sure the permission is fine: sudo chown tomcat:tomcat /opt/opentext/AppWorksPlatform/defaultInst/content/TestDocument.txt

I also made sure not use ‘spaces’ in the filename to avoid any naming conflicts with surrounding quotes and slash-escapes…You know what I mean when you work with CLI!

Hmmm….That’s again the same error!

#RTFM: DocumentPath = The path to the document in the system. What would that system be? A hint can be found in the DocumentURL definition that tells us something about a DMS as system!

Ok…Interesting conclusion: So this webservice uses the location from a DMS and a DMS is in this case a ‘Document Management System’ like OpenText Content Server or Documentum…or…by default the AppWorks platform itself like I have it running at the moment! Another conclusion is that the ‘document store’ service container has a direct relation with this webservice. So, if you have (for example) a Documentum connector up and running as back-end DMS the storage path will be different, but again…

…what will be that path for our input request?

For that we dive into our database where that location path is saved (independent of the DMS you are using!). After a HeidiSQL database connection we can run a query like this:

SELECT s_storage FROM o2appworkstipsappworksproject;

With some JSON result that looks like this:

1
2
3
4
5
6
7

{
   "documentURL":"/documentstore/appworks_tips/AppWorksTipsAppWorks/project/655361/New Text Document.txt",
   "documentName":"New Text Document.txt",
   "documentId":"0800273b-f379-a1eb-8088-c195db271ba3",
   "linked":false,
   "businessWorkspaceId":null
}

Now update our SOAP request (and yes…we just override our content by itself!):

1
2
3
4
5
6
7
8
9
10
11
12

<SOAP:Envelope xmlns:SOAP="http://schemas.xmlsoap.org/soap/envelope/">
  <SOAP:Body>
    <LinkDocument xmlns="http://schemas.opentext.com/bps/entity/buildingblock/file">
      <Source>
        <DocumentPath>/documentstore/appworks_tips/AppWorksTipsAppWorks/project/655361/New Text Document.txt</DocumentPath>
      </Source>
      <Destination>
        <ns0:ItemId xmlns:ns0="http://schemas.opentext.com/bps/entity/core">0800273bf379a1eab5ca6723fbb797a6.655361</ns0:ItemId>
      </Destination>
    </LinkDocument>
  </SOAP:Body>
</SOAP:Envelope>

And now we get our response:

1
2
3
4
5
6
7
8
9
10
11
12

<data>
  <ns2:LinkDocumentResponse xmlns:ns2="http://schemas.opentext.com/bps/entity/buildingblock/file" xmlns="http://schemas.opentext.com/bps/entity/core">
    <ns2:Document xmlns:ns2="http://schemas.opentext.com/bps/entity/buildingblock/file" xmlns="http://schemas.opentext.com/bps/entity/core">
      <ItemId xmlns="http://schemas.opentext.com/bps/entity/core">0800273bf379a1eab5ca6723fbb797a6.655361</ItemId>
      <ns2:Name>New Text Document.txt</ns2:Name>
      <ns2:Size>0</ns2:Size>
      <ns2:LastModified>2020-09-29T10:30:21.560+02:00</ns2:LastModified>
      <ns2:DocumentURL>/documentstore/appworks_tips/AppWorksTipsAppWorks/project/655361/New Text Document.txt</ns2:DocumentURL>
      <ns2:DocumentId>0800273b-f379-a1eb-8088-c195db271ba3</ns2:DocumentId>
    </ns2:Document>
  </ns2:LinkDocumentResponse>
</data>

After a refresh on database level we see a small change in the JSON data:

1
2
3
4
5
6
7

{
   "documentURL":"/documentstore/appworks_tips/AppWorksTipsAppWorks/project/655361/New Text Document.txt",
   "documentName":"New Text Document.txt",
   "documentId":"0800273b-f379-a1eb-8088-c195db271ba3",
   "linked":true,
   "businessWorkspaceId":null
}

Did you spot the change? 👊

That’s a green light!

The other approach

That second approach is via the service layer…

Go to: http://192.168.56.107:8080/home/appworks_tips/services/

Find the node ‘Method Set Entity File Services’. Inhere you’ll find our service call…

Hit that ‘Test’ button behind it, so you can fill in the SOAP request again like we did before in the ‘Web Service Interface Explorer’

After you hit the ‘send’ button you will see a similar result:

Nice…Not fancy, but good to know that this way of working is also a possibility! Coffee time…☕

Upload a document

Well, we learned a lot in this post, but for me, it doesn’t solve an issue I walk around with at the moment…And that’s the upload of a document that was retrieved from an external source! As I type this sentence and #RTFM I see another webservice passing by called ‘uploadDocument’…

hmmm…Let’s do a quick call to see if it does the trick that I would like to accomplish!

You start with a clean SOAP request that we’ll update like this (where we removed the ‘Create’ node as it’s only used for a ‘Content’ building block, and we have the ‘File’ building block applied!):

1
2
3
4
5
6
7
8
9
10
11

<SOAP:Envelope xmlns:SOAP="http://schemas.xmlsoap.org/soap/envelope/">
  <SOAP:Body>
    <UploadDocument xmlns="http://schemas.opentext.com/bps/entity/buildingblock/file">
      <Update>
        <ns0:ItemId xmlns:ns0="http://schemas.opentext.com/bps/entity/core">0800273bf379a1eab5ca6723fbb797a6.983041</ns0:ItemId>
        <FileName>TestDocument.txt</FileName>
        <FileURL>http://192.168.56.107:8080/home/appworks_tips/upload/TestDocument.txt</FileURL>
      </Update>
    </UploadDocument>
  </SOAP:Body>
</SOAP:Envelope>

Some notes

• Make sure the ‘FileName’ matches the initial upload document! You can check this with the CMC tool:

• The ‘Title’ can be removed from the request (as it’s not visible for a ‘File’ BB)

• The ‘Overwrite’ does not do anything (as far as I tested it correctly), so I just removed it from the request. With a ‘false’ value it also got updated!?…But it’s also not very clear in the low-code guide either, and maybe it only applies for the ‘Content’ BB

• To make that ‘FileURL’ available you need to place a document on the server in this folder with these commands:

  1 2 3

  mkdir /opt/opentext/AppWorksPlatform/defaultInst/webroot/organization/appworks_tips/upload chown tomcat:tomcat /opt/opentext/AppWorksPlatform/defaultInst/webroot/organization/appworks_tips/upload vi /opt/opentext/AppWorksPlatform/defaultInst/webroot/organization/appworks_tips/upload/TestDocument.txt

Did it work?…Hell yeah it works…!! 😎

Man-o-man…I give it a “DONE” on this post where we learned more about webservice calls and especially the calls where we can upload and play with links on content level. Great stuff that we can use in our future solutions. Have a knowledgeable week-end and see you in the next post with again a great topic on a new AppWorks Tips installment!

Don’t forget to subscribe to get updates on the activities happening on this site. Have you noticed the quiz where you find out if you are also “The AppWorks guy”?