Directed Web Access (DWA) in Pega

In this blog article, we will see the pre-requisites and the steps involved in implementing Directed Web Access in Pega

What is Directed Web Access?

You can get some idea from the name.  Providing direct web access for the application to someone.

We know that assignments (worklist/workbasket) are meant to be worked by some users. These users will always have their operator IDs in the Pega database and hence the right access is provided for them to work on the case.

Slowly a use case emerged where some external people or parties were involved within the case at a certain point in time. Just like temporary access to perform an action. Creating Operator IDs for each and every external person is expensive and may open up some security violations!

Steps involved are

a. External assignments are created.

b. An email is sent to the external party with a link to perform the action

Business scenario: A banking organization uses Pega application to process Mortgage loans. In the house valuation stage, a note is necessary from the external agency that does the valuation of the house.

Solution: DWA is the ideal solution here, where a note can be requested via email link and after submit,  the same note can be attached with the loan case.

Note: All processing for this particular use case can be easily achieved by using OOTB rules with less customization

What are external assignments?

– Assignments that are meant to be worked by external parties are referred to as external assignments.

– External assignments are of class instance Assign-External and are saved in the table – pr_Assign.

One interesting thing is the key for the Assign-External class.

pySignature is the Key for the class instance. We will see more detail about the signature as we move forward 🙂

What are the pre-requisites for implementing DWA?

There are two main pre-requisites.

1. A Valid email account to send out the email to external party.

I already set up an email account. Please follow the link to set up an email account on your own.

2. The external party should be added as a work party to the case.

I already have a loan processing case. I defined Valuator as a new work party in the rule and marked it as mandatory

So at the time of case creation, in the new harness, I can provide the Valuator details along with the email ID to which we will be sending the email with a link.

Now the basic pre-requisites are ready. Let’s start with the steps to implement the DWA.

What are the steps to implement Directed Web Access?

Step 1: Define an external Operator ID.

As we saw before, the external party will be given a directed web access one time to perform the action. Authentication will be through an encrypted signature. What about authorization?

We know that access groups associated with the operator specify the application access for the operator.

The DWA architecture expects an operator ID ( like a model operator) to provide the access.

I am creating an operator ‘Externalvaluator’ and provided the right access.

Note: By OOTB, Pega uses almost all rule with naming extension ‘External…’  for the DWA solution. It is recommended to create operator that starts with name External. Pega recommends using the minimum or only the necessary rulesets access to the external operator for security reasons.

You will also see an existing OOTB operator ‘External’

Make the License type Invocation in the security tab.

Invocation will normally be used if the operator is dedicated for external services or external users.

To read more about the license type, visit the pega link – https://community.pega.com/sites/default/files/help_v717/data-/data-admin-/data-admin-operator-/data-admin-operator-id/advanced.htm

Save the operator ID.

Step 2: Update the Public link URL.

Configure -> System -> Settings -> URL

Update the URL to your servlet name and save the configuration.

This will save an instance of class.

Data-Admin-System-Configuration

You also have a DSS setting – PublicLinkURL

Important note: If Public URL is configured using Data-Admin-System-configuration, then that will take precedence and override the DSS settings.

Step 3: Configure the flow and the correspondence rule.

Now the interesting part 🙂 to learn more about the DWA architecture.

Pega provides two flows OOTB.

1. EngageExternalQuick – This is the most used DWA processing flow that can used in synchronous processing case.  Synchronous here refers that the main flow waits for the response from the external user.

2. EngageExternalForInformation – Mostly used for asynchronous processing where this flow can be used as spin-off (parallel processing).

We will look into the EngageExternalQuick flow.

You see the flow is beautifully annotated. The flow is in available state and can be class specialized 🙂

There are three main parameters for the flow – Role, Subject and Message. ( we can also customize to parameterize corr name)

There is a first external assignment shape. You see the assignment type is of External and it gets route to the external party role.

In the assignment properties, you will see all the main parameters are getting passed.

By default, Operator ID – External is specified.

We will definitely specialize in this flow and customize it to use our new operator.

There is also a harness – PerformExternal to give the harness view for the external users.

Again you can customize this if needed (mostly you need to 😉)

We know that usually with the workbasket or worklist assignment shapes, default OOTB activities like NewAssignment, AddAssign will be called when the flow reaches the assignment shape. Similarly for the External assignment shape, activity External of class Work- will be invoked.

This is one of the Key activities for DWA processing.

The activity does the following things.

1. Prepares pyCorrPage of class Data-Corr-Email.

2. Creates a new external assignment.

3. Uses authentication java package and creates a new encrypted signature for the external assignment.

Remember, pySignature is the key for the Assign-External class.

4. Finally also updates the case status.

You can go through each step on your own.

Here is a look at the flow action rule used in the external assignment shape – EnterInformationExternal.

It refers non-autogenerated HTML which creates a Page ‘pyNewNote’ and refers the section – CoreExternal of class note attachment.

Seems the section is very simple to capture the Notes and developed in very older versions with deprecated controls!!

So this is the section that will be presented to the external user in the waiting assignment shape.

Once the user enters the notes and submits the external assignment, the flow moves to the next shape.

The next shape in the flow is the Collect Response utility. It creates a note attachment with the captured details entered from the external user and also stops the requestor at the end.

Getting back to the flow, the final shapes are used to review the response and also to restart it if needed.

Okay, now we have a picture of how we engage the external parties with an assignment. Once the assignment is submitted by the end user, then we process the data and update the values or create note attachments etc.

Let’s specialize the flow and change the parameter in the assignment shape.

Save the flow rule.

We will do only this small change and accept the other configurations by default.

Let’s talk about the correspondence and the link we send in the email. In the activity – ExternalRequestQuickStart, which gets called from activity External,  uses ExternalRequestBrief as the corr name when the parameter is empty.

So we have an OOTB sample.

Let’s explore it. You see it refers to two HTML fragments.

If you open the HTML fragment ExternalInstructions.Email, then you will see how the URL and link are formed with the signature.

One final time, you can always customize all these available rules as per your requirement, but do not tamper with the URL formation 😉

For tutorial purposes, I accept all the rulesof OOTB without customization.

How to invoke this flow?

You can do it in 2 ways.

1. You can use EngageExternal – local flow action to optionally engage the external parties to the case

2. You can call the flow directly as a step in the case stage, so that it always gets executed.

We will use option 1 to use the optional local flow action – EngageExternal.

The post-processing activity of the flow action – ActionEngageExternal invokes the EngageExternalQuick flow.

Step 4: We will use the local flow action in the first assignment shape.

We are ready to test.

How to test and debug the DWA functionality?

Step 1: Add the work party Valuator with the case. I am using pegaknowledgesharing@gmail.com as the external party address.

Step 2: In the Actions button, local action select the EngageExternalParty local action.

Case ID is L-5003. Choose the valuator work party and provide a valid subject and message.

Tip: If you need, you can trace and see the rules involved for external assignment creation.

Click the Submit button.

You will see the case status changed to Pending-External.

Note: Make sure you release the lock by closing the case so that the external user processes without lock contention.

Step 3: Verify the Assign-External instance. You should see a new instance.

Step 4: Verify the Data-Corr-Email instances. You will see a new instance as well.

Step 5: Now verify the email from the Gmail client.

You see the property valuation email with a link.

Use the developer console to check the Link URL – You see the signature as a query string.

Now get back to the email and click on the link.

You will see the same note section and harness we saw before. Enter a valid note.

Before submitting, open the remote tracer, you can also trace the newly created requestor session for the external user.

Click submit. Request is successfully completed.

Now if you click the mail link again, it will not work. DWA can be used only once. Why?!

Technically, after we submit the external assignment, the flow moves the assignment is completed and external assignment instance is removed for the signature key.

You can verify the Assign-External instances again to verify if the instance is removed.

Step 6: Open the case L-5003 and check if the note is attached to the case.

Yes it is!

Remember, DWA is not only about attaching notes, you can customize it to perform any single action.

As a summary,

– DWA – Directed Web Access for external users.

– External assignments will be created of class instance Assign-External.

– EngageExternalQuick is the main flow responsible for DWA processing – Creates external assignments and send email correspondence.

– An email will be sent to the external users with a signed link to perform the action.

– External users can perform the action only once using the same link.

– You can customize the DWA OOTB rules for custom requirements.

If you don’t understand the DWA architecture, give it another read 😉