PeopleCode | Immediately transfer the user from one component to the next
A. Transfer and Co
The PeopleCode ‘Transfer’ function is used for transferring the user from component A to component B. All control is passed to component B; component A is closed completely.
‘Transfer’ should not be confused with the ‘TransferPage’ function. The latter function is only used to transfer from one page to another within the same component. Another similar function is ‘DoModalComponent’. This is used to open a secondary component in a modal window while still keeping the original component held in memory. The secondary component must be completed and dismissed before the user can resume working in the original component. ‘Transfer’ on the other hand, works as a one-way street.
B. The Challenge
The ‘Transfer’ function can be quite a challenge to get right, mainly due to three things. Firstly, the function allows for a large number of parameters, so it is easy to get the parameters in the wrong order, or miss out on one or more of the parameters entirely. Secondly, some of the parameters are not what they seem at first glance. Thirdly, even after crafting a perfect ‘Transfer’ statement, you might find some or all of your users lack the correct security for the target component.
C. The Mandatory Parameters
Let’s begin by considering the ‘Transfer’ function in its most minimal form, with only the mandatory fields included:
Transfer( False, MenuName.SA_LEARNER_SERVICES, BarName.FINANCES,
ItemName.SSF_SS_MISC_PUR, Page.SSF_SS_BU_SELECT, %Action_Add);
Each of these parameters will next be considered in turn:
- Open New Browser Window – this True/False value indicates whether a new browser window should be opened. ‘True’ indicates that a new window should be opened while ‘False’ will keep the target component in the current window.
- Menu Name – the name of the menu containing the target component.
- Bar Name – a PeopleSoft menu is divided into functional groups, typically called ‘Use’, ‘Process’ and ‘Setup’ (a hangover from the pre-Portal days when the menu played more of a role). To work out the Bar Name, open the menu in App Designer and double-check on the Bar Name at the top of the menu. You should see two pieces of information: Name and Label. These are usually set to the same value, but in case they aren’t, it is the ‘Name’ field that is required for the ‘Transfer’ command.
- Item Name – this one can be confusing, especially for older components. In the majority of cases, the Item Name is the same as the component name. However, strictly speaking, the ‘Item Name’ is the name of the item as it appears on the menu. This defaults to the component name, but can be changed in App Designer. To check the correct Item Name, double-click on the menu item and make a note of the Menu Item ‘Name’ field at the top of the properties window. In the example below, the ‘Menu Item Name’ and the ‘Component Name’ are the same:
Here is example of a component in which the Menu Item Name (ACCT_SUMM) and Component Name (SSF_SS_ACCT_SUMM) are different:
- Page – similar to Item Name, this is another one that can catch the unwary. In most cases, the Page Name required for the ‘Transfer’ command is the usual name of the page object. However, at the component level, it is possible to set a page ‘Item Name’ to a different value from the object name. For the purposes of the ‘Transfer’ command, you must enter the ‘Item Name’ as it appears in the component. In the following example, pages 1 and 5 have a different Item Name to the object page Name. However, the other four pages keep the same value:
- Mode – this parameter specifies the manner in which the target component should be opened. The value of this parameter can be entered as a single letter (“A”) or as a Constant Value (‘%Action_Add’). Typical values for the mode are A / ‘%Action_Add’, U / ‘%Action_UpdateDisplay’, and C / ‘%Action_Correction’. While setting this parameter is straightforward enough, often users are caught out by security. You might specify a ‘Transfer’ in correction mode, but when a particular user tries to access the target component, you then discover that the user does not have correction access to that component. In this case, an error message is displayed. Therefore, user security should always be kept in mind when specifying the ‘Mode’.
D. The Optional Parameters
Congratulations if you’ve managed to get this far. But we’re still not quite done. As an additional step, you might want to consider the optional parameters to the ‘Transfer ‘function: specifying the values to use for the search record of the target component.
In the normal course of being a PeopleSoft user, when you enter any component with a search record, you must start by selecting the desired record from the search. However, if you’re entering a component via a ‘Transfer’ function, you typically want to retain the same key values that you were originally working with. So if you were using Customer 123 in the first component, you would want to continue working with the same customer in the second component. This would save you the bother of having to go through the search all over again. To ensure the search record is bypassed, the values required for the search record should be included in the ‘Transfer’ function.
The search record fields can be set by specifying each field value individually, or by passing in a record object that is pre-populated with the search values.
Here is an example of using ‘Transfer’ with individual fields specified for the search:
Transfer( True, MenuName.SA_LEARNER_SERVICES,
BarName.FINANCES, ItemName.SSF_SS_MISC_PUR,
Page.SSF_SS_BU_SELECT, &Action_UpdateDisplay,
&guid, &oper, &ver, &trxtype);
Here is an example of a record object being used to set the search record fields:
&searchRec = CreateRecord(Record.RECORD_NAME);
&searchRec.EMPLID.Value = ¤tEmplID;
&searchRec.ACAD_CAREER.Value = ¤tCareer;
Transfer( True, MenuName.SA_LEARNER_SERVICES, BarName.FINANCES,
ItemName.SSF_SS_MISC_PUR, Page.SSF_SS_BU_SELECT,
&Action_UpdateDisplay, &searchRec);
Incidentally, the ‘Transfer’ function has one other parameter that can be added right at the end of the statement. This is the auto-search field, another True/False value indicating whether the search should be performed automatically as soon as the user is transferred to the new component. However, as of PeopleBooks v8.55, this parameter is no longer included as part of the ‘Transfer’ functionality. Instead, the search is performed automatically as long as a sufficient number of key fields are provided. ‘Transfer’ statements that already include the auto-search True/False parameter will still continue to work.
E. Transfer and TransferExact
Finally – yes, we are almost at the end – one other ‘quirk’ about the ‘Transfer’ search is worth mentioning. When the ‘Transfer’ attempts to do the search based on the passed parameters, it will do a ‘LIKE’ search on all the string parameters. If however, you prefer the system to do an exact match on the passed parameters, which will always be quicker than a ‘LIKE’ search, then use the ‘TransferExact’ function instead. As long as you have provided the function with all the necessary values, ‘TransferExact’ will deliver a faster response time.
See Also:
Tip 016: Dynamic Object Names