Hi there AppWorks fans,
Welcome to a new installment of AppWorks tips.
In this post we’ll explore the Identity package which is delivered with our platform. I heard a lot of things about it, but I never made use of it…till this post! We’ll just dive in and see what we can accomplice with it!?
Let get right into it…
And our first start (this time) is the manual! Normally I’m not really from #RTFM, but this time it will help me on my journey…
There is a great chapter called ‘Using the Identity Package’ from the Low-Code development guide that is available from the documentation folder of the downloaded installation package \opentext-appworks-suite-20.3-linux\OpenTextAppWorksPlatform\documentation
The first thing we see is that we really need OTDS this time to consume the good stuff of the identity package…Lucky we’ve installed it already…If not? You can make it available in 3 steps; specially crafted for you! 😍
Extra note: During my latest OTDS installation I noticed the OTDS services does not spin up automatically after a restart of Tomcat (and after a restart of my VM!). You will end up with an
Could not connect to OTDS repository. Retrying...error intail -f /opt/tomcat/apache-tomcat-8.5.57/logs/otds.log.This is because (according to the documentation) you need to run the OpenDJ service yourself on a Unix OS…Don’t ask me why!? You can start it with
sh /opt/opentext/otds/opendj/bin/start-ds. You can also craft a nice daemon service for it like we did for our Tomcat/Tomee instances….Let me know in the comments if you require more information!?
After this OTDS tackle we can continue our Identity journey that we will split in several sections…
What’s in it?
Well…simple…All the required entities that exposes your identity in the solution related to your account. So, not only your username and password, but also your role, address, position, department etc… This is a full set of entities available OOTB for you to use in your solution…How nice of OpenText to give us a head start!
There is a long list of entities available to be consumed, but 3 are special as they can’t be manipulated from the identity homepage (we’ll check out this page later on). They can only be manipulated from OTDS! The magic three are: User, Group and Role!
Later on you’ll see that related entities are also used when creating a new user in OTDS and pushed to the platform. This is because there is a mapping available between what is happening in OTDS and the identity entities in the platform. This is also well documented in the documentation!
The other entities (see the ERD diagram) can be created and manipulated from the identity homepage…
There are even more entities related within the ‘Person’ entity…See the documentation!
Also, our well-knows building blocks on our created entities rely on the identity package; These are the three building blocks that rely on them. We don’t focus too deeply on them now as they will be discovered in other posts in the future.
Assignee: used for entity responsibility, so we can for example directly assign a case-manager to a case entity; The case manager can be a user from the identity package which is related to an OTDS account!
Email: for sending out an email to a person…again an account related to OTDS that we can then also use for the authentication on the SMTP server
Deadline: it’s for scheduling an item for completion within a certain time…An identity person can be notified when the deadline expires.
Identity management roles
The identity package is delivered with a default set of roles. For this we’ll check the ‘User manager’ artifact in design-time.
Mark the ‘Include internal roles’ option and start to search for ‘Identity’; You’ll see 2 roles passing by:
Identity administrator: Is a sub-role of the administrator role and makes it possible to manipulate the identity data from the identity homepage.
How do we know it’s a sub-role?…Well, check the great CMC tool with
sudo sh /opt/opentext/AppWorksPlatform/defaultInst/bin/cmc.shwhile you have exported to the correctexport DISPLAY=IP:0.0variable!![identity_003]()
Identity Push service: This is that role where we applied our ‘sysadmin’ account on to get data from OTDS into the platform. Remember that push URL
http://192.168.56.107:8080/home/system/app/otdspushthat we used during the OTDS configuration to AppWorks?Identity User: You don’t see this role in the list? That is because each user is by default applied to this role to be able to consume the identity data! But what if we really don’t want to use all this fancy stuff from our end-users? Well…There’s a section for it, but it looks like OTDS is irrefutable connected with the platform! 😉
Identity homepage
Ok…We talked several times about this page…Now, where can we find it!?
Make sure you are an ‘Identity Administrator’ rolled user and then login into runtime with your OTDS account. In my case ‘awdev@aw’!
If you have problems with OTDS login? You can always skip the OTDS login page with this parameter (as long as the value after the equal sign does not match an OTDS configuration in AppWorks!):
authID=XXX
Go to the top left hamburger menu icon and hit it like a pro…
There you have it…with our users from OTDS!
Update some OTDS data (and resynch!)
Let’s see if we can update some user information in OTDS and publish into the Identity homepage for some results!
Go to OTDS (http://192.168.56.107:8181/otds-admin/) and login with the otadmin@otds.admin account with, in my case, password ‘admin’
Open the ‘Partitions’ section where you probably have your AppWorks partition created with some members…correct?
Well, view those members and get to the properties of one of them:
Fill in as much data as you can for this user (also in the other tabs) and in the end you nicely save the user information.
Next step is to update/resynch or even better ‘Consolidate’ the user information to our AppWorks platform:
In the next screen you just select your resource that needs to be applied and then you’re ready to hit that blue ‘Consolidate’ button!
Back in runtime of our platform identity homepage we open our consolidated user account and see that magic…
Now we have updated a user in OTDS. Our next step is to craft a role and a group in OTDS…Remember those 3 identity entities that can’t be managed from the Identity homepage? Exactly…We create them in OTDS and consolidate them to our platform!
Back to our AppWorks partition in OTDS…Where we can add new groups, roles and…Also, ‘organizational units’! That was not in the documentation (or maybe overseen!?), but we’ll just create one to see the effect.
When ready you can also ‘Consolidate’ the full partition:
To check some logging on the consolidation:
tail -f /opt/tomcat/apache-tomcat-8.5.57/logs/directory-provenance.log
And now I start to see some strange behavior I can’t directly explain!?
I created a group ‘development’ in OTDS, but after a synch I did not see it in the ‘All Groups’ list in runtime; Later on, when I created an OTDS role ‘Manager’ and connected this role as ‘Application role’ to the group ‘development’, I started to see the group in the ‘All Groups’ list!
![identity_012]()
Also, strange is that my crafted OTDS role ‘Manager’ is only visible in the ‘All groups’ list? As I thought it would be available in the ‘All roles’ list, but that’s not the case!?
![identity_013]()
And the next strange thing is that my OTDS created ‘Organizational Unit’ can’t be found back in runtime, although I see it consolidated in the logging? But OK…It was also not in the documentation…so be it!?
Let’s check our CMC tool and check what is updated in our CARS/LDAP instance?
The manager role
The developer group
You can clearly see that our OTDS ‘Development’ group is a ‘Functional role’ in our platform!…Although it is shown in the ‘All groups’ list in runtime…Do you still understand what is happening here…Well…I don’t?…Well…I do…looks like a group, or a role in OTDS are both ‘Functional roles’ in AppWorks and shown in the ‘All groups’ list in the identity package…It’s what it is!
The ‘awdev’ account
Looks fine as I connected my user to both the group and the role in OTDS!
The role overview
And I made the ‘Manager’ role indeed an ‘Application role’ to the group ‘development’…it looks fine to me; although ‘Development’ is a group in OTDS
A look in the ‘User Manager’ artifact tells me the same information for my user:
Note that I noticed a delay before the roles showed up in this list…Also, after some refreshing!
And in runtime…
Well…This knowledge only leaves me with one last question!…How to get an OTDS role in the ‘All roles’ list in the identity homepage?…But we’re not going to cover that in this post…enough is enough!
Identity manipulation (from the homepage)
Now we covered the ‘Role’, ‘Group’ and ‘User’ entity in the identity package, let’s see “what else?” we can update!?
‘What else?’…Yes, I learned it that during a Kepner Tregoe (KT-method) session for problem analyses…Nice stuff!
Well, let’s see what is already created during all the consolidation actions we did from the OTDS UI. For example, a ‘Gender’ entity instance!
How did it get there? Well, that’s from the OTDS properties of our user account!
But then there should be some kind of relation between or ‘User’ entity instance, and the ‘Gender’ entity instance…correct? Well, check the ERD in the top of this post!
Or better…Check in design-time!
Create a simple test project (with a workspace) and right-click the ‘Imported Application Packages’ where you can select the action ‘Show Platform Packages’
You will get a list of all the Identity package entities…Now we can just right-click for example the ‘User’ entity and hit the ‘customize’ action.
Don’t worry…As long as you don’t save the entity you don’t do anything, but you just view and extend your knowledge!
Now you can see that it is related to the ‘Person’ entity…
And when you do exactly the same for that ‘Person’ entity…et voila
Do we learn some nice stuff here…Or what? Do you feel the excitement?…Knuckle bump me! 👊
‘What else?’
Hmmm…I see already a ‘Country’ passing by with a ‘State/Province’; This was also filled in by me as property on my user in OTDS.
- NL for ‘Netherlands’
- NB for ‘Noord-Brabant’ where we do all this fancy stuff at the moment!
Now let’s add entity instances ourselves directly in runtime…Create a new ‘worklist’ instance!?…Just because we can…
Nothing fancy, but in a follow-up post we’ll work with this worklist to send a task to!
Also create a new ‘VisaType’ with the name ‘Passport’…you never know when you need it in some property selection list!?
Next are 2 ‘Title’ instances…Like ‘CEO’ and ‘Specialist’…
And some ‘SocialMedia’ like ‘LinkedIn’ and ‘Facebook’
We’ll create some ‘PhonenumberType’ with values ‘Home’ and ‘Work’
Add some ‘Language’ instances like ‘Dutch - nl_NL’ and ‘English - en_US’
Etc., etc…
One thing I noticed is that I couldn’t find directly how to create a new ‘State/Province’ that you need to fill in when you create new instances of ‘Enterprise’, ‘Organizational unit’ or ‘Contact’! To create a new ‘State/Province’ instance you need to be in an instance of ‘Country’…
It’s getting more interesting when we start to add a new ‘organizational unit’! And especially when we also start to add new positions and add our OTDS users to that position!
In the ‘Positions’ tab we just add 2 new instances with names like ‘Developer’ and ‘Tester’. In that ‘Members’ tab we can attach our user to the appropriate position…
In the documentation we also discovered that an ‘organizational unit’ will also be called a ‘Team’…So, now you know it’s the same! In a follow-up post we’ll want to send tasks to a ‘Team’…This info is just to make sure we don’t mix things up!
This last action was the intention to start this blog post! As I want to play a bit with that ‘Teams’ mindset in another post, but now it’s ready for usage.
OK…Coffee break… ☕
Identity customization
Well, you saw it already a little in the previous section…Let’s customize the ‘SocialMedia’ entity.
Add a new text property with the name ‘website’ and make sure you add it to the ‘Create’ and ‘Default’ form. To update the form you need to click that special ‘Replace’ button to overwrite the initial form. Just click ‘Yes’ on the ‘Replace building block’ question.
After that ‘Replacement’ you see 2 things…
A ‘Revert’ button that brings you back to the original form
An information message (you can close it safely…We cover this later on!):
![identity_034]()
Now open the ‘Create’ form and add that new ‘website’ property to it. After this action you can save the entity…Nicely in our project structure (that you can also create during that save!).
I also updated the ‘Default’ form like this and one thing I noticed that it’s not including the ‘Create’ form!?…And what I also see that we don’t know what form to add as I see the original ‘Create’, and the extended ‘Create’ form in the list! 😜
We just try one, and it looks like the first form in a ‘Bingo!’
Let’s also replace the list building block with a name ‘AllSocialmediaForAdmin’, and add the ‘website’ property to the list!
I know there is also an ‘AllSocialMedia’ list, but that one is used ‘internally’ of the ‘Identity package solution’…How do I know!?…Well, check to properties of that list…
Save and continue with a close of the entity….
Let’s reconstruct those translations?…shall we!? Just right click that ‘customized’ entity from the project!
Let’s do a publish, and check the result in runtime…
Hmm…nothing happens, and it all looks the same!?
Ok…let’s add our own list ‘MySocialMedia’ and see if that is shown in runtime!? That way we the involvement of some cache or not?
Also, nothing…Then it must be security!
Now I see it…There is a ‘Security’ building block on the entity we also need to replace!
Now we’re talking…
Another great lesson learned from an internal AppWorks guy about this way of customization: Make sure your deploy your ‘entity’ projects into the organization space. If you want to customize an entity (like for example the ‘Person’ entity of the identity package) it will work perfectly fine. This is because you can only customize and entity from within the ‘organizational’ space!!
Identity disablement for end-users
What if you really don’t want your end user to be able to use any of the identity package stuff?
Well…There are only 2 ways from what I could find:
In the
app/adminpanel you see this:![identity_041]()
You can remove that role from the ‘Home Page’ layout!, but this only removes the standard ‘Homepage’ layout where your inbox task can be found. What I miss here is the ‘Identity Homepage Layout’ we saw in during our customization!
![identity_042]()
I don’t know why it’s not available in that ‘Layout security’ in the
/app/adminpanel? What I do know is the second way of disablement…(later on we’ll discover why this homepage is not available!)When you don’t apply your beloved end-users to the ‘Identity Administrator’ role they will also not see the ‘Identity homepage’! And let us be honest…You will probably not apply this role to a normal user! So, we should be fine with this!
Maybe another thing to note is that since version 20.2 you need to apply the security of a homepage in design-time and not in the
/app/adminpanel. I also tried to do this on the ‘IdentityHomePage’, but the context menu provided only an ‘open’ action and there is no such action to ‘customize’ a homepage document (yet?).
Identity fully disablement (don’t do this for real!)
NOTE: I work on a VM that can easily be rolled back!! This section will give some nice insides, but are (probably) not meant to be executed like we show you…Play at your own risk, but be careful as a good developer is intent to be.
What if you really, really want to disable all the identity stuff…? Well, undeploy the package?
Let’s see what we can do in the ‘Application deployer’ artifact!
Hmmm…multiple packages!?…what’s in those packages?
For that we dive into the server with MobaXTerm to this location: /opt/opentext/AppWorksPlatform/defaultInst/capcontent/packages/shared/
Looks like OpenText Entity Identity Components is the most interesting! When you download the .cap file and extract it with 7-Zip we’ll see some interesting things passing by that we covered in this post!!
And because I’m just curious why the ‘IdentityHomePage’ is not available in the app/admin panel I also found the answer by comparing both of those XML files!
In theory, we might update the .cap file and redeploy it as new version, but that’s not for now!
Well…let us undeploy this package and see what is left over…shall we?
We get into an undeployment wizard, and the first thing we see is a dependency of 2 packages…
But we’ll just push through with ‘Next >’ and again a ‘Next >’ and last but least the ‘Undeploy’ action!
That last one (the package that we started with) is failing…again and again with an error:
You can check these log files on it with messages like this The 'Use Solution' permission is not granted in any security policy role.
tail -f /opt/opentext/AppWorksPlatform/defaultInst/Logs/Application_Server.xmltail -f /opt/tomee/apache-tomee-plus-8.0.3/logs/catalina.outtail -f /opt/opentext/AppWorksPlatform/defaultInst/install_log/OpenText\ Entity\ Identity\ Components.xml
Also, when I try to access the runtime again it hangs…Looks like we damaged some stuff here!
In the logging I see this message during login: The requested permission 'Access' was denied. Looks fair to me as the dependent ‘Entity Instance Security’ package got a removal with our last undeploy action! So, was it smart…Not really…Was it a learning experience…Hell yeah!!! 😍
Let’s install those 3 packages again (take a look in the ‘New’ and ‘Incomplete’ package status of the ‘Application Deployer’ artifact!):
- “OpenText Entity Instance Security”
- “OpenText Entity Identity Runtime”
- “OpenText Entity Identity Components”
After this redeployment we could (luckily) login again in runtime!
Final note!
During my exploration of the Identity package I used the /app/system organization. Normally we would want to manipulate the identity entities from our own solution in our own organization! But why did I do it in ‘system’?….Well, for only one reason! I connected OTDS to the shared space in AppWorks and from what I see is that my OTDS users are only available in the ‘system’ organization! Not a big problem for this post, but for your solution you probably want to synch your users from OTDS to your specific organization to have them available in the identity homepage. I also know you can ‘connect’ a user from the system space to your organization space, but from what I see in my environment is that these users are not available in the identity homepage. I couldn’t figure out why that is? Maybe it’s just my foolishness!? 😜
Well…That’s a well-earned “DONE” on this pretty hot day (when I crafted this post some weeks ago!) where we learned a lot of information about the identity package. Again nice stuff that we covered not only on the front-end, but also in the back-end (even on server-level). These kinds of dives take some time, but it’s fascinating to see how things work in the back-end, and you learn a lot about the platform this way. I see you in a follow-up post where we continue to use the identity package as we want to play a bit around with worklist and teams (= organizational units); And as we learned from this post that’s all related to the identity package! Have a great day…
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”?
