/ Management  

Embed 'Intelligent Viewing' in AppWorks to view content

Hi there AppWorks fans,

Welcome to a new installment of AppWorks tips.

In this post we continue our grind on the intelligent viewer. Last week we did the installation of the software package; in this post we dive into the AppWorks side of things. This means creating an entity with content BB, update the documentstore connector (or create a new one) with the viewing settings. You’ll also see OTDS settings passing by for a correct authorization where we will discover an interesting way of authorization (through OAuth!).

Let get right into it…

Time to #RTFM where we find ourselves two sections in the AppWorks administration guide:

  • “Configuring OTDS to integrate Intelligent Viewing with AppWorks Platform”
  • “Creating and modifying document store repository”

First step off-course is to spin up our VM again (if not up and running yet) and make sure the IV services are up and running (incl. RabbitMQ). Check the post-checks from last week to verify it all.

Ohw yeah…double-check! I assume you already have a connection from the AppWorks platform to OTDS like explained in this post!

Next step is to dive into OTDS…

OTDS configuration

Jump directly into the section ‘OAuth Client’ with URL: http://192.168.56.107:8181/otds-admin/#oauthclients

Here we need to create a new ‘OAuth Client’ with name iv-appworks. Don’t forget the make it ‘Confidential’. This makes sure you retrieve a ‘client secret’ key which we’ll use later on. This mark also consolidates the corresponding user into AppWorks (keep on reading…)

iv_awp_001

Hit the ‘Next >’ button and fill in the other tabs with this information in mind:

  • User Partition: global
  • Advanced: Add these 3 scopes for ‘Permissible’ and ‘Default’
    • create_publications
    • view_publications
    • view_any_publication
  • Redirect URLs: Add the AWP base URL http://192.168.56.107:8080
  • Custom Attributes: leave as is

When you hit the ‘Save’ button, you’ll get a modal popup with a secret key…Save it for later on!

This is my secret: 9Y2YtbsNZR1uq60Ka4d2RK1o3hrHMsq6

Now open the ‘Actions’ for our brand-new iv-appworks OAuth client and make sure to enable the ‘Impersonation’ settings!

‘Impersonation’? #RTFM of OTDS admin guide: Allows a user of one resource to appear as a different user on a target resource and to potentially acquire all the privileges of the impersonated user in that resource…YOLO! 🤓

Extra notes:

  • I did this exact same impersonation settings also on the iv-publisher client!
  • For the iv-publisher client, I also added the AWP base URL as a redirect URL in the properties. Why? Because later on we use this OAuth client id in the parameters of the AppWorks URL like this ?client_id=iv-publisher and then we have a nice redirect to the OTDS login page!

Next is the ‘Trusted Sites’ tag where we add our valuable platform URL (if not yet in place):

iv_awp_002

After this we jump to the ‘Access Roles’ section where we make sure to open the ‘View Access Role Details’ on our already available resource for the AppWorks platform!

iv_awp_003

From this ‘Access Role’ we add the ‘OAuthClients’ user partition next to the already assigned partition you might have created for the AppWorks in the past.

iv_awp_004

Don’t forget to save!…It’s a common mistake.

This last save triggers a ‘consolidate’ action to synchronize the users of the ‘OAuthClients’ partition into AppWorks!

iv_awp_005

Also check the log tail -999f /opt/tomcat/latest/logs/directory-provenance.log on entries like this one:

1
2
3
4
Push Connector|Success Provenance|15,Account Create In Resource||""||""|
"Created object of type __ACCOUNT__ named 'iv-appworks@OAuthClients' 
in resource awp_resource (4c77bd0b-49d5-46f5-a24b-0a550996ac07) 
with UID 'USER~096a8f24-241e-103c-933b-21cc238849de'"

Now we go to the ‘Users & Groups’ section where we need to allocate the user iv-appworks@OAuthClients to the IV license (under the ‘Actions’ menu):

iv_awp_006

Just click the ‘Allocate to License’ once…You don’t retrieve any verification, but it’s updated for sure. ‘Close’ the modal popup and double-check the ‘Counters’ for the current license in the ‘License Keys’ section of OTDS!

iv_awp_007

NOTE: I also did the same license allocation for my awdev account as that’s the account I use for the final test in runtime!

So far, so good for the OTDS side of things…

Nooooo…One thing! Well, two things from my experience. Make sure to also enable the impersonation settings on both the resources (awp_resource and iv) in the ‘Resources’ section of OTDS! It will improve your life…trust me!

AppWorks configuration

We already verified our users and saw the availability of iv-published and iv-appworks. First we’ll configure iv-published as “OAuth Authenticator” for the AppWorks platform. Open the ‘Security Administration’ artifact of AppWorks and edit the currently available (for my VM) “OTDS” authenticator. Change the type from ‘OTDS’ to ‘OAuth’ and provide the iv-publisher client ID in the properties:

iv_awp_008

Logout from the platform and login again and have a view on the described parameter in the URL: ?client_id=iv-publisher

Now we go to the ‘System Resource Manager’ artifact (in my case, my own organization) where we will start the wizard ‘New Service Group’ for a new documentstore type of service container. Can we also do this in the ‘system’ space for the ‘Repository’ service container? For sure, you can! It’s just a customary practice to leave the system space as is and extend functionality in your own organization (a choice to make on your own!)

We will follow the wizard with this information in mind:

  • Application connector: Document Store
  • Service group name: docstore_service_group
    • Mark all the web service interfaces!
  • Service container name: docstore_service_container
    • With an automatic startup
    • Assigned to the OS process

This is a screenshot of the most crucial step where we glue it all together:

iv_awp_009

Notes:

  • XDS is just the default XML Data Storage of the platform itself.
  • We want to use the ‘Intelligent Viewing’ as viewer type…duh!?
  • Make sure your services are up and running and point to the root of the URL (see screenshot):
    • http://192.168.56.107:3358/viewer/api/v1
    • http://192.168.56.107:3356/publication/api/v1
  • Client ID: iv-appworks
  • Client secret: I hope you still have that copy from the beginning…I warned you! 🙄
  • Repository root: /documentstore
  • You also find most settings from the ‘Repository’ service container in ‘system’…Have a look!

A final ‘Next >’, and a ‘Finish’ will deliver you with a ‘green’ up and running service container…great!

Verification URL: http://192.168.56.107:8080/home/appworks_tips/app/documentservices/rest/config/viewer
With JSON data response:

1
2
3
4
5
6
7
8
9
10
{
   "ViewerConfiguration":{
      "Viewer":{
         "@type":"IntelligentViewing",
         "OtdsToken":"...",
         "PublicationServiceUrl":"http://192.168.56.104:3356",
         "ViewerServiceUrl":"http://192.168.56.104:3358"
      }
   }
}

Next…

AppWorks basic entity modeling

I assume you know (by now) how to create a simple entity; quickly prototyped with the default BBs…correct? Let’s skip that part for this post and create it on your own with these notes in mind:

  1. Make sure add the ‘File’ BB or the ‘Content’ BB
  2. Depending on your choice, make sure to add the ‘Content’ panel and ‘Preview’ panel on the default layout
  3. Add a ‘Security’ BB with a special iv-publisher sauce!

Special ‘Security’ BB info:

  • With the Security BB applied, you explicitly need to assign the correct roles to make the entity usable for ‘normal’ identity users. I always add the ‘Identity User’ as a default role (with required permissions)
  • IMPORTANT!! You also need to define a new role (func_iv role for example) which is assigned to the iv-publisher account! This role gets a minimal permission of viewing capabilities like this:

iv_awp_010

From the ‘User Manager’ artifact we’ll assign the ‘iv-publisher’ account to our func_iv role:

iv_awp_011

Finally, you can safely publish the entity and do a first test in runtime…Believe it or not, but for me, it’s a direct bullseye after the upload of a .DOCX document:

iv_awp_012

NICEEEEE! Especially when I’m looking back to my Brava! viewer post. This viewer ‘feels’ much nicer. The performance? Well, my VM uses maximum resources at the moment. So viewing content is still a challenging thing to do (same for indexing content and searching)…Why? Well, when you look again in the IV data folder structure /opt/opentext/IVArtifacts/fs-0/publications you’ll get a better understanding as content gets an index and is unified/converted to a standard format (incl. thumbnail images).

Other insights?

When &^%&%^ hits the fan? Well, the logfiles (see previous post) are your best friend! That’s the same for the <F12> developer console of Chrome where you will find yourself a view like this:

iv_awp_013

That’s an interesting JSON

What about the fancy features like ‘Redaction’, ‘Annotation’, and ‘Comparing’? Well, those need to be enabled from the ‘Security’ BB of the entity. Only from OT support I retrieved (in that moment in time) information that our AWP only supports the ‘viewing’ part of IV which is sufficient for our post this far. Keep yourself informed on the new IV releases for an update on these topics!

Time to wrap up with a “configured” DONE. We saw an interesting configuration procedure for bringing alive the popular Intelligent Viewing package within our platform. I must admit that it’s a new product, with “in progress” documentation and not all features enabled yet at the moment of writing this post. For now, we provided ourselves sufficient information for a bright viewing experience for the future! Have yourself a great weekend, and I see you in the next post; with great new stuff…Grz!

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”?