Hi there AppWorks fans,

Welcome to a new installment of AppWorks tips.

An interesting milestone as this is the first time I taught the AppWorks BPM “godfather” something which opened his eyes too. Looks like my own weekly posts brought me to a new level of experience…Which is off-course a wonderful thing! What simple thing are we talking about? Well, the simple thing on how to retrieve the current user into a BPM. Not just the username, but the full “User” entity (part of the Identity package!). Why? Well, because (maybe?) our entity has a relation to the ‘User’ entity, and we want to update this relation from a BPM perspective. You might have some other interesting use-case yourself!?
By now we know the entity-modeling-world and BPM-modeling-world have only some small connections together. There is a gap between those worlds which most off the time can be filled up with a webservice call. Only, sometimes you really don’t know where to find a matching webservice for your needs. This is also experience, reading, and trying out. Some time ago, we also faced such issue, but we found a solution to be shared with you all! Behold the power of the FindUserByName webservice with an XPath sauce.

Let get right into it…

Let’s say we have a prototype ‘Issue’ entity like this (nicely saved in the ‘entities’ folder of our project):

All default BBs are applied, so we are able to create a new instance in runtime. These are the extra configurations I did:

• Creating a ‘toOne’ relation to the ‘User’ entity with name to_one_user
• Updating the ‘Create’ form with the ‘Name’ property of the related ‘User’ entity (not the full relation with the search-icon!)
• Creating an unconditional action rule a_assign_current_user which starts a simple “short-lived” BPM (just one activity with nothing assigned) which gets the name bpm_assign_current_user. Saved in the ‘bpms’ folder of the project

Make sure to update the ‘Monitoring’ of the BPM properties. When we make it “short-lived”, it doesn’t monitor that much anymore!

Publish it all, test in runtime, and see you have a BPM instance in your PIM…

So far, so good…next step…

The great BPM service call

Before we update the BPM, let us first have a look on the available metadata after we started a BPM instance in runtime. For this we open the PIM artifact again where we have a look in the ‘Message Map Data’ of a running instance.

Have a look in the ‘instanceProperties’ message where we see this content as an example (with stripped namespaces and removal of the less crucial elements for this post):

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

<instanceProperties>
  <processName>nl-bos/bpms/bpm_assign_current_user</processName>
  <processDescription>bpm_assign_current_user</processDescription>
  <startTime>1638196875904</startTime>
  <mainProcess>true</mainProcess>
  <rootInstance>080027e8-4f06-a1ec-9448-9a051dde0ccf</rootInstance>
  <rootInstanceType value="1">PROCESS</rootInstanceType>
  <modelSpace>organization</modelSpace>
  <crashRecovery>false</crashRecovery>
  <monitor monitorLevel="COMPLETE">true</monitor>
  <startedBy>cn=awdev@appworks,cn=organizational users,o=appworks_tips,cn=cordys,cn=defaultInst,o=mydomain.com</startedBy>
  <currentOwner>cn=awdev@appworks,cn=organizational users,o=appworks_tips,cn=cordys,cn=defaultInst,o=mydomain.com</currentOwner>
  <organization>o=appworks_tips,cn=cordys,cn=defaultInst,o=mydomain.com</organization>
  <processInstantiationType>SOAP Request</processInstantiationType>
  <priority>3</priority>
  <parentType value="1">PROCESS</parentType>
  <rootEntityInstanceId>080027e84f06a1ec93825fe775732604.1</rootEntityInstanceId>
  <stateInfo />
</instanceProperties>

What we are interested in most of the time are the “ItemId” values which we can clearly see passing by in the ‘rootEntityInstanceId’ element related to our crafted ‘issue’ entity instance. There is no ‘ItemId’ for the current running user account, so how are we able to connect the current running account as related identity ‘User’ entity to our ‘issue’ entity…As our use-case describes!?

For this we reach out to the power of webservices. In particular the FindUserByName webservice. Why this conclusion? Well, have a look again at the element ‘currentOwner’ or ‘startedBy’. Both expose relevant information as input to our service call…

Let’s open the ‘Web Service Interface Explorer’ artifact and start searching for the requested service name:

You already see it’s a webservice part of the ‘OT Entity Identity Component’ which is delivered with the platform.

Hit the ‘Test’ action, and provide a SOAP Request with a valid ‘Name’ input:

1
2
3
4
5
6
7

<SOAP:Envelope>
  <SOAP:Body>
    <FindUserByName>
      <Name>awdev@appworks</Name>
    </FindUserByName>
  </SOAP:Body>
</SOAP:Envelope>

The (stripped) response will look like this:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

<data>
  <wstxns1:FindUserByNameResponse>
    <wstxns2:User>
      <wstxns3:Name>awdev@appworks</wstxns3:Name>
      <FullName>awdev</FullName>
      <wstxns4:IdentityDisplayName>AppWorks Developer</wstxns4:IdentityDisplayName>
      <UserId>awdev@appworks</UserId>
      <memberid>5847cc6c-bc98-103b-9ca4-29444f98050d</memberid>
      <toPerson>
        <wstxns6:Person-id>
          <Id>2</Id>
          <ItemId>F8B156B4FF8F11E6E6562305FE2BDF32.2</ItemId>
        </wstxns6:Person-id>
      </toPerson>
      <wstxns7:Identity-id>
        <Id>3</Id>
        <ItemId>F8B156E1037111E6E9CB0FBF3334FBBF.3</ItemId>
      </wstxns7:Identity-id>
      <wstxns8:Title>
        <Value>awdev@appworks</Value>
      </wstxns8:Title>
    </wstxns2:User>
  </wstxns1:FindUserByNameResponse>
</data>

An interesting result as it closes the gap between the BPM-User, and the Identity-User (see those ‘ItemId’ values). There is even more to be found! The relation to the identity ‘Person’ entity!

Have a look at 2 new services ReadUser, and ReadPerson with input of the valid ‘ItemId’ values. The difference? Well, the Person entity contains much more related metadata like ‘email’, ‘phone-nr.’, ‘department’, ‘birthdate’, and so on. All metadata which described the ‘Identity’ of the user! Ahaaa, would that be the reason they call it ‘Identity Package’! ❓

After exposing all this information, it’s time to get back to our BPM…Right-click the activity, and insert the webservice FindUserByName:

From the ‘Message Map’ of the BPM, we can connect (from the left-source-side) the instanceProperties/startedBy to (on the right-target-side) the FindUserByNameInput/FindUserByName/Name. Only, this is not enough! Our input is an invalid value cn=awdev@appworks,cn=organizational users,o=appworks_tips,cn=cordys,cn=defaultInst,o=mydomain.com. We only need the value awdev@appworks!…remember?

To make this happen, we make a small adjustment on the XPath expression like this (with some helping functions):

1
2
3
4
5
6
7

substring-after(
    substring-before(
        instance:instanceProperties/instance:startedBy/text()
        , ',cn='
    )
    , 'cn='
)

Place is all after each other in the editor, the above code part just shows the readable structure!

Not required but teach yourself a good habit to also update the ‘Usage’ option, like in the above screenshot (“Replace Content With Expression”).

To “test” the expression quickly it’s as easy to update the XML input in the XML tab of the editor:

With our first webservice in place, we can add another webservice call. This is the call to our (not yet!) exposed webservice Setto_one_user

I said, ‘not yet!’ because we first need to expose it on our entity like this:

By now (I hope), you all know we also need to add a new service container of type ‘Application Server’ in the ‘System Resource Manager’ artifact. This container is responsible for managing the requests for these types of entity service calls. Have a search for plenty of examples. Comment me for more help!

Back to the BPM, and insert the webservice as new activity:

The consolidated message map will eventually look like this:

Let’s have a publication, and a retest in (a responsive!) runtime…

NICEEE!! And “no”, there was no manipulation in the background to make the screenshot nice and shiny! 😏

Bam…”DONE”…Nothing more, nothing less! Again we see the power of webservices solving the gap between entity modeling and BPM modeling. In the post we just exposed some interesting webservices to solve a particular problem, but also have a look at all the other services via the ‘Web Service Interface Explorer’ artifact. The possibilities are endless and this post brings it all a bit closer to your own project. Have a great “exploratory” week-end, and I see you in another great post on AppWorks Tips.

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