Sometimes the best way to get a business point across to someone, or get them to look at something at all, is to make it insanely easy for them to get where they need to go with a single click. The Valence 5 portal makes it possible to do this with just about any app or Nitro Query you’ve got set up. Simply construct a special URL and email it!
Imagine this scenario: You’ve got an executive regularly harping on you to send him a snapshot of current monthly sales. Why can’t he just log in and run the report himself, you ask? Because he’s established a precedent of passing the ball to you to get the numbers for him.
So this month’s tip is a simple primer on how to generate a link that gets him to the information he wants. You can even make it possible to access the app from a function key in a green screen program!
Method 1: The basic URL
Perhaps the easiest way to get someone directly into a Valence Portal app is to simply create a URL that sends the user to your Valence instance, supplemented with query parameters that tell the portal which app to launch and, optionally, specific values for the program to pull in (such as, say, a date range or customer number). Query parameters are simply a series of “name=value” pairs that follow the base URL. The pairs begin with a question mark, with additional ones delimited with an ampersand. Possible values include the following (see the Valence Guide for additional details):
- app – the numeric Valence app ID to launch
- environment – the numeric Valence environment ID to use
- portal – a boolean value (true/false) indicating whether the user should have full Portal access (a value of false means they can’t launch other apps)
Example: www.myValenceInstance:7050?app=1001&environment=1002&portal=false&customerNbr=123456
When the Valence Portal is activated, it will pull in the query parameters, attempt to log in and then launch the specified app. As a convenience, if the user has already been authenticated to the Valence instance in another browser tab, they won’t have to supply their login credentials again, as the same session ID is shared between the tabs by default.
Alternatively, it is possible to include a user and password in the URL (&user=xxxx&password=yyyy), though this has obvious security ramifications since the credentials could be easily read by anyone who sees it. So it’s best to refrain from using this approach except for low-level user profiles with very limited access to apps with read-only authority. See method 2 below for information on pre-configuring a session for a specific user.
Method 2: The pre-configured session URL
If you’ve already set up a special user profile specifically to access a particular app or query for anybody, including people who don’t have a user profile on your system, this method can be a good approach. The technique is similar to Method 1 above, except that in this case you will be pre-creating a special session ID that corresponds to a specific user and environment, thereby bypassing the need for them to log in.
The first step is to programmatically generate a custom session ID (or SID), for which you would use the VVLOGIN program, as described here. This is typically done through an RPG or CL program call. You can pass to VVLOGIN up to four parameters:
- Session ID (64A): Pass a value of *CUSTOM to instruct the program that you want a custom SID returned
- User ID (15P5): The numeric Valence ID corresponding to the user for which you want to generate the SID
- Environment ID (15P5): (optional) The Valence ID corresponding to a specific environment for the session
- Language Code (10A): (optional) The language ID (i.e.: “en”) for the session, if to be different from the global default
VVLOGIN will then return a custom session ID in the first parameter, which you should use in your URL with a “customSID” query parameter, along with any other information you’d like to pass.
Example: www.myValenceInstance:7050?customSid=xxxxxx&app=1001&customerNbr=123456
Method 3: Launching a Valence app from a green screen program
Finally, for your “old school” users who have a seemingly unbreakable habit of logging into the green screen to do their daily work, it is possible to add a function key to a 5250 program such that it automatically launches a browser tab and brings up a specific app for the user. This makes for a good way to ease them into web applications your development team is rolling out.
This process was covered in detail in a prior blog post, but to summarize how this works, you simply add a call to VVRMTCALL inside your green screen program, passing the appropriate parameters as outlined here. In this case the query parameters are cross-referenced to the ID, as a workaround to the 123 character limit associated with the API (STRPCCMD) used to support this functionality.
You can see a demonstration of this concept in action by calling the example program EX5250INQ, included in the VALENCE50 library. With VALENCE50 in your library list, you can also see a practical example of this concept by using the “VV” command to pop into Nitro File Editor for a specific file, as follows:
VV DEMOCMAST
(Note: Mac users should prompt this command and specify *MAC as the operating system)