Technical Documentation

This page contains a technical overview of the Generalized Interface (GI), Natural programming standards for the GI, and a quick guide for the PSU Pay GI Services.

Technical Overview

Introduction

The primary purpose of the Generalized Interface (GI) is to facilitate the exchange of information between differing computer systems at the University. This is done through the development and re-use of Web services. At its most basic level, a Web service can be defined as a way for different systems to exchange information over the Internet. A Web service transfers information from one point to another over the Internet via HTTP and provides a means of making sure that both systems understand the information being transmitted via XML.

GI diagram

Note: The term “service” will be used interchangeably with “Web service” throughout this documentation.

The GI is the server on which individual Web Services for the Penn State Community reside. Applications make use of services on the GI  by generating a request via an XML-Remote Procedure Call (XML-RPC). XML-RPC is a simple specification that defines a method of making remote procedure calls in XML and also defines how to encode the response in XML. It has more than 30 implementations that cover a wide variety of software running on different systems. “XML-RPC is designed to be as simple as possible, while allowing complex data structures to be transmitted, processed, and returned.”

To use a service that accesses Enterprise Data, the required parameters are sent via XML-RPC. The GI passes these parameters to the requested service through a Smalltalk application. The Smalltalk application then passes the request to a Natural Routine, which in turn retrieves the data from the appropriate AIS Database (Enterprise Servers or Mainframes). The process is then reversed until the data provided by the service is returned to the client as an XML-RPC response.

Diagram of the Generalized Interface

Getting Started--New Application

 

  1. Before any work can begin on a GI application several administrative tasks need to be completed:
    • The Partner Office will work with the GI Administrator to create a Project Implementation Plan (PIP). The PIP lays out a timeline for the basic steps necessary to take a GI project from conception to production.

      The PIP also contains a list of services required by an application.
    • The Partner Office must read over the GI Memo of Understanding (MOU).

      The MOU is a document that defines what the responsibilities of both AIS and the Partner Office are with regards to a GI application.
    • To begin the MOU/PIP process please, contact the Generalized Interface Administrator.
    • AIS and the Partner Office must sign an MOU cover letter indicating agreement on the scope, timeframe, and responsibilities of the project.
  2. Login to the Development Environment
    • Note: The first time you login, you must register by providing some basic personal information. This is used to track what Applications and Services you have access to and how AIS can contact you. Once the registration process is complete, exit the system and logon again.
  3. Select the ‘Review Current Web Services’ option to see if any of the available services meet your needs. If not, return to the main menu and select “Add a Service Request,” then proceed with the directions on that page.
  4. Select “Add an Application Request,” and enter information on the screens as follows:
    • “Application Name Request:”

      Enter the name of your application in the text box. The naming convention for applications is to make them nouns. For example an application used to find the status of a prospective student’s application to Penn State would be called “Applicant Status” (noun) as opposed to the service used by the application, which would be called “getApplicantStatus” (verb).

      Note: “Demo” is added to at the beginning of an application name. The “Demo” reference will remain in front of the name of the application as long as the application is in the Development Environment. When the application is moved to the acceptance and production environments, the “Demo” will be removed.

      Click on the ‘Next’ button
    • “Service Name(s) Requested:”

      Select the services which the application will use. Click the ‘Add’ to move the services to the “Current Service Names Selected for Application” column. Multiple services may be selected at one time by holding the ‘Ctrl’ or ‘Shift’ key while making selections.

      Click the ‘Next’ button when finished adding services.
    • “IP Addresses Requiring Access to the Application:”

      Enter the IP address(s) for the server on which the application will reside. Click the “Add->” button.

      Enter the IP address(es) for the server on which the application will reside in the text box. A range of IP addresses may be specified by using an “*” in the third or fourth octet.

      For example, 128.118.110.* represents the entire 110 subnet.

      If you use a wildcard in the IP address in the Development Environment (Test), you will need to pick specific addresses for the server when the application goes into production. If you require a range of IP addresses in production, contact the Generalized Interface Administrator.

      Clicke the "Add->" button to place an IP address on the list.

      Click the ‘Next’ button.
    • “Network Administrator Contact:”

      From the drop down list, select the person who will be the system/network administrator contact for the application. Once a contact has been selected, click the “Next” button.
    • “Peak Periods for Application:”

      Use the drop down lists to select the periods when the application is expected to be at peak usage. Click the “Next” button.
    • “Description for Application:”

      Enter a brief description about the purpose of the application. Please indicate what the application will be developed in, i.e. ColdFusion, ASP. Click the ‘Next’ button.
    • “Add Application Request:”

      If you wish to register the application, click “Save” If you do not wish to register the application, click “Return to Generalized Interface Menu”
  5. Code, test, and retest the application and service(s) in the test environment. This includes integration of using the getBalancedURL service for load balancing.
  6. Initiate approval procedure

    Contact the data steward(s) of the services used by the application to inform them of the planned use.
  7. Get a security scan done on the server where the production Application will reside.

    Visit the PSU Security Office and initiate the ISS Scan Request for your server. Clean scan results will need to be sent to the Generalized Interface Administrator ten business days before the application can be approved for production.
  8. Test the application in GI acceptance environment. See Acceptance Testing.
  9. Request for the application to be moved into production. See Production Move.

Getting Started--Web Services

Web Services are the backbone of the Generalized Interface’s (GI) utility.

Note: The term “service” will be used interchangeably with “Web service” throughout this documentation.

A Web service is what enables an application to get the data it needs. Web services reside in the GI and are used and re-used by applications. The first step in designing an application is determining what data elements the application needs. This is done before considering what services the application will use. Once the required data has been determined, it is time to review current services available to see if any already provide the necessary data.

When looking at existing services, keep in mind that services that return more information than required will often function just as well as a service that returns exactly the required information. For example, if your application requires an e-mail address, it is very likely that you will not find an existing service that only returns an e-mail address; however, you may find a service which returns all of a person’s contact information. It would be quicker to use the contact information service, pick out the e-mail address from the returned data, and ignore the rest of the data than it would be to create an entirely new service that just returns an e-mail address.

Ideally, services will be designed as components that do one thing. This means that it will take many services to meet the needs of an application. While this may seem a little tedious at first, there are substantial benefits to designing components in this fashion, such as reusability and ease of debugging. The example below demonstrates the point of designing services to be reusable components. Not only is a service that takes 30 input parameters and returns a large amount of data going to be more difficult to design than multiple smaller services, it also has almost no chance of being used again. The ability to reuse components is the whole point of designing a Web service.

Example: A service is designed that returns the current room a class is scheduled for and a list of technology classrooms of similar size available at the same time. A single service could be designed which would accept ‘instructor name’, ‘semester’, ‘course name’, ‘course number’ as parameters. The technology and size specifications could be hard coded into the service. The problem with this approach is that not many other developers would be able to use this service because its input and return values are so specific.

The better approach is to create three separate services, all of which may be very useful in the future. One service would accept the ‘instructor name’ and ‘semester’ as parameters and would return all the instructor’s courses for that semester. The second service would return room assignments for a given ‘course number’ and ‘section number’. (Perhaps this service would also return rooms for all sections of a course if the ‘section number’ parameter sent was 0). A third service would accept ‘time’, ‘size’, ‘room characteristic codes’ and return available rooms. All three of these services could be used in a multitude of future applications as opposed to the single service approach in which there would be almost no chance of reuse.

Registering New Web Services

  1. Log into the Development Environment.
  2. Select ‘Review Current Web Services’ to see if any of the currently available services meet your needs. If not, return to the main menu and select ‘Add a service request’ enter information on the screens as follows:
    • “Enter Request for Service Name” Enter the name for the new service in the text box. The naming convention for services is to make them verbs, i.e. call your service “getStudentBirthday” as opposed to “StudentBirthday”. If the service will change data the verb of choice is “manage”.
    • “Select Data Source for Service” Select the data source the service will use--IBIS, ISIS, CIDR, ST etc. If the service uses TEST data on the Development Server the data source will need to be changed to ISIS or IBIS before the application that uses the service is moved into production.
    • “Select Authentication Type for Service” Select the type of authentication (None, CAC User ID, eAccount or Secure ID, which is a two factor authentication that also requires the Access User ID) you would like the service to use. Most services will use CAC User ID for authentication.
    • “Description of Service” Enter a description of what function the service performs. Be sure to include information on the necessary input parameters and the return value(s) so that other developers can reuse the service in the future. This field must be filled in before your application will be available in production. If you are not able to supply this information when you are first registering the service, return at a later date and add them.
    • “Data Stewards:” Select the data steward(s) for the required data elements from the list. Click the ‘Add ->’ button for each steward you wish to place on the “Current Stewards for Service Request” list.
    • “NATURAL Glue Routine” Enter the name of the NATURAL routine that the service will use in the text box. Use the radio buttons to indicate whether you will require assistance with the NATURAL development used by the service. If your service does not use NATURAL or you are unsure what to enter please leave this field blank.
    • “Modify Data Elements” Select the “Modify Data Elements” button. Enter file/table name and field information for each data element that the service will use. These data elements must be filled in before your service will be available in production. If you are not able to supply this information when you are first registering the service, return at a later date and add them. Click the ‘Submit – I’m Finished’ button when you are done.
    • “Will your service be for update or inquiry?” Use the radio button to indicate if the service will update any data elements or whether it will be read-only.
    • “Add Request for Service:” If you are happy with your request select the ‘Add Request for Service’ button. Once you have added your service request, an e-mail will be sent to the GI Administrator stating that a new request has been added.
  4. You may now begin work on the NATURAL routines for your service. The GI Administrator will be in touch with you shortly to make arrangements for help with the NATURAL routines if necessary and to get the following information about your Data In and Data Out areas:
    • The name of each Data In and Data Out element
    • All data types must be Alpha.
    • The size of each element (A10, A3 etc)
    • Error codes and messages

      This information is necessary for the Small Talk code, generally provided by AIS.
  6. Once the NATURAL and Small Talk code is written, testing of the service may begin.

    Once testing is completed satisfactorily, the service is complete.

    Once testing has been completed satisfactorily, the service in complete.

    Important Note: The only additional work the service may need before it can be used in a production application is to correct the “Data Source Information:” if the service originally was set to Test. Updates to the service, such as changing the data source information, are done via the ‘Update a Service Request’, available on the main menu of the Development Environment.

Developing Applications

What is an application? For our purposes, an application is the software that will call a Web service residing on the Generalized Interface (GI). In a little more detail, an application is the user interface that translates a request from the end user into a remote procedure call understood by a service and, in turn, translates the response from the service back into a form that is understandable to the end user. A single application can, and likely will, use multiple services to fulfill its function. It should also be noted that multiple applications might use the same service.

The remote procedure call initiated by the application is done via XML-RPC. The GI supports applications written in any language for which there is an XML-RPC client implementation --a quick check of the list will reveal support for many popular languages.

Due to the fact that all the services residing on the GI understand XML-RPC, a developer will be able to create applications in a familiar language, and that application will be able to communicate with any of the available services, which, in return, will be able to retrieve data from the AIS Databases (Enterprise Servers or Mainframes).

Parameters

Every XML-RPC call will require some set of standard parameters. The first parameter will be the URL to which the procedure call is being made. The second parameter will be the name of the Web service being called. The third parameter will be an array (or equivalent) that contains all the remaining parameters, the number of which will vary depending on the service being called. The array will start out with the following three parameters in this order. The first parameter is an ASET User ID, second is the password, and third is the name (as assigned in the Interface) of the application making the call. Any additional parameters required by the service being used will follow the first three required parameters. If you are designing a service that does not require end user authentication, then a “dummy” ASET User ID and password will need to be created and the dummy values will be still need to be sent as the first and second parameter.

In the case of an application that uses two-factor authentication, the secure ID number should be submitted as the fourth parameter of the array. So for two-factor authentication, the first four mandatory parameters of the array would be as follows:

  1. ASET User ID
  2. ASET password
  3. Name of the application making the call

Any additional parameters required by the service being used will follow the three required parameters. If you are designing a services that does not require end user authentification, then a "dummy" ASET User ID and password (also referred to as System Account) will need to be created and the dummy values will still need to be sent as the first and second parameters.

In the case of an application that uses two-factor authentification, the secure ID number should be submitted as the fourth parameter of the array. So, for two-factor authentification, the first four mandatory parameters of the array would be as follows:

  1. ASET user ID
  2. ASET password 
  3. Name of the application making the call
  4. Secure ID number

For specific information on sending a RPC from a particular type of application (i.e., ColdFusion, ASP, etc.), see Specific Implementations below.

ASP Applications

Setting Up An Application Server for ASP

The setup for the Generalized Interface and ASP requires that several packages of software be installed on the computer that will be making the calls to the Generalized Interface. Remember to setup the development and production servers in the same manner. The first step to using ASP with the Generalized Interface is to be sure that your server meets the systems requirements. While these requirements are not hardware related, they define a select set of software that must be installed on the ASP server for the ASP validating library to work.

System Requirements

Setting Up the ASP Validating Library

An ASP file has the ability to reference another ASP file through the use of the “include” directive. This ability is used to allow an ASP programmer to access the Generalized Interface via XML-RPC.

The ASP file containing the logic (xmlrpc1_3_ParseErrors.asp) necessary to access the Generalized Interface is available by contacting the Generalized Interface Administrator. The following support files are also included:

Upon receiving the XMLPRC_ASP.zip file, extract the contents into an empty directory.

Installing Alvaro's Base 64 Library (Optional)

Note: Currently all information transmissions so and the from the GI are sent in arrays and structures of strings. As such, installation of the Base 64 library is not technically necessary.

Installing the Microsoft 3.0 XML Parser (not necessary with IE 5.0.1 or later)

Go back to the folder that you unzipped the XMLRPC_ASP.zip file into. Double click the file xml_3.0parser.exe. Follow the command prompts. This will install and register version 3.0 of the Microsoft XML Parser. This installation process will not affect older, newer or the same version of the XML parser which may already be on your system.

Windows folder tree structure 

Installing the ASP Library File

Move the xmlrpc1_3.asp file to a directory on your Win32 server that can execute ASP pages. For example, the /Inetpub/wwwroot/ directory created by IIS as illustrated in the image to the right.

Once the file has been placed in the correct directory, it must be referenced by the ASP page that will be making the XML-RPC call. This is done with the “include” directive: <!-- #include file ="somefilename"-->

The “somefilename” may include a relative path to the included file. In this case, where application and the ASP Library are in the same directory, the statement would be as follows: <!-- #include file ="xmlrpc1_3_ParseErrors.asp"-->

If you are using a virtual directory, the syntax is for the include directive is: <!-- #include virtual="somefilename"-->

This directive statement should be included in the application’s ASP page before the first XML_RPC call is made, as illustrated in Example 1.

XML-RPC Call in ASP (Calling a Service)

The code used to call the Generalized Interface consists of three parts. The parameters being sent to the Service must be set. The actual call is then made to the Generalized Interface server; then, the data returned from the Service must be moved into the appropriate variables within the application. This is, in principle, no different from making any other function call.

The following is an example of the ASP code necessary to call a service named “validateAccount." The function xmlRPC (contained in the xmlrpc1_3.asp file) has the following syntax: xmlRPC (server, function, argumentArray). In this case, the server is the Development Environment of the Generalized Interface, function is the name of the Web Service being called and argumentArray is parameter list.

This service requires three secondary parameters: budget, fund, and location. These parameters required by the service are sent after the mandatory first three parameters of user ID, password, and application name. In this case, the application has been named “Demo Validation” in the Interface.

Example 1: Calling the Service in ASP

<!-- #include file ="xmlrpc1_3_ParseErrors.asp"-->
<%
on error resume next
Dim paramList(5)
ParamList(0)=userId
ParamList(1)=password
ParamList(2)=”Demo Validation”
ParamList(3)=account
ParamList(4)=date

myResp= xmlRPC ("https://vwtest.oas.psu.edu/isapi/gi.dll/rpc2", "validateAccount", paramList)
%>

After this call, the return data will be in the variable named myResp. In this particular case, the validateAccount service returns a simple string value of “true” or “false” in the variable myResp. In other cases, the returned variable may be a complex data structure such as an array, a dictionary object or even an array of dictionary objects. If the data is returned in a complex structure, such as a dictionary object, it is necessary to iterate through the dictionary object to retrieve the data. A sample of this is shown below.

Example 2: Retrieving Structure Data in ASP

Dim eachItem
eachItem =myresp.items
For i=0 to myresp.count-1
response.write (eachItem (i)& "<BR>")
Next

The above code iterates through the dictionary object and writes each item to the screen.

The most common way for data to be returned is in an array of strings. A sample of retrieving data from an array of strings is shown below.

Example 3: Retrieving Array Data in ASP

For i=0 to Ubound(myresp)
response.write(myresp(i) & “<BR>”)
Next

The previous two examples may or may not be the way a particular application uses the return data; these simply illustrate two ways to use the data.

Moving ASP Test Application Into Production

Once the application has been approved for production, two changes must be made in order to call services in the Production Environment.

In the sample code of Example 1, the Development Environment is designated as the first parameter of the “xmlRPC” function. This parameter contains the address of the Generalized Interface server that you wish your application to call. To have your application call the production server, simply change the address in this field as shown below in Example 4.

The second required change is to the third parameter of the array. In Example 1 the third parameter is “Demo Validation." When an application is moved into the Production Environment, the “Demo “ is removed. In this case, the third parameter of the array must be changed to “Validation” as indicated in Example 4.

Example 4: Calling the Service in the Production Environment

<!-- #include file =" xmlrpc1_3_ParseErrors.asp"-->
<%
on error resume next
Dim paramList(5)
ParamList(0)=”userId”
ParamList(1)=”password”
ParamList(2)=”Validation”
ParamList(3)=account
ParamList(4)=date


myResp= xmlRPC ("production GI Url", "validateAccount", paramList)
%>

ColdFusion 4.5 and 5 Applications

Setting Up an Application Server for ColdFusion

The setup for the Generalized Interface and ColdFusion requires that several packages of software be installed on the computer that will be making the calls to the Generalized Interface (GI). The GI can be accessed from a ColdFusion server but these software packages need to be installed. The setup for the development and production ColdFusion servers should be the same. The first step to using ColdFusion with the GI is to be sure that your server meets the system requirements. While these requirements are not hardware related, they define a select set of software that must be installed on the ColdFusion server for the custom tags to function properly.

System Requirements

Windows folder tree structureSetting Up the ColdFusion Custom Tags

ColdFusion provides the facility to write custom tags. ColdFusion’s ability to adapt to custom tags has allowed for the creation of a set of tags that allow a ColdFusion programmer to access the GI via XML-RPC.

If you are designing an application in ColdFusion and require the custom tags, please contact the Generalized Interface Administrator. Please do not use the XML-RPC tags available from the Macromedia Web site. The tags supplied directly by AIS have been modified to fix a bug and increase performance.

The custom tags need to be installed into the ColdFusion custom Tags directory. This directory is usually C:\CFusion\customtags. Unzip the custom tag files into a new directory named Xmlrpc under the custom tags directory. The directory structure should look similar to the image to the left.

XML-RPC Call In ColdFusion (Calling a Service)

The code used to call the GI consists of three parts. The parameters being sent to the service must be set. The actual call is then made to the GI server. Then the data returned from the service must be moved into the appropriate variables within the application. This is, in principle, no different from making any other function call.

The following is an example of the ColdFusion code necessary to call a service named “validateAccount”. The value of “XMLRPCSERVER” is the address of the server where the web service resides. In this case, it is the listening port of the Generalized Interface Development platform. (All applications in development will make their XML-RPC call to this address.) The value of “METHODNAME” is the name of the service in the GI that the application is calling.

This service requires two parameters: account number and date. The two parameters required by the service are sent after the mandatory initial three parameters: user ID, password, and application name. In this case, the application has been named “Demo Validation” in the Interface, which is the value of the third parameter.

Example 5: Calling the Service in ColdFusion

<!--- Perform the XMLRPC call to the server --->
<CF_XMLRPC_CLT
XMLRPCSERVER="https://vwtest.oas.psu.edu/isapi/gi.dll/rpc2"
METHODNAME="validateAccount"
OUTPUT="xmlResponse"
RAWRESPONSE="aResponse">
<CF_XMLRPC_CLT_REQUESTPARAM VALUE=#userId# TYPE="string">
<CF_XMLRPC_CLT_REQUESTPARAM VALUE=#password# TYPE="string">
<CF_XMLRPC_CLT_REQUESTPARAM VALUE="Demo Validation" TYPE="string">
<CF_XMLRPC_CLT_REQUESTPARAM VALUE=#account# TYPE="string" >
<CF_XMLRPC_CLT_REQUESTPARAM VALUE=#date# TYPE="string">
</CF_XMLRPC_CLT>

After this call, the return data will be in the variable named in the “OUTPUT” field. In this case, the xmlRespsonse.ResponseValue variable will contain the returned data as a simple string. In other cases, however, this variable may be a complex structure. If the data returned is a complex structure, it would be necessary to iterate through the structure, retrieve the data from the structure and place it into the appropriate ColdFusion variables. A sample of this is shown below.

Example 6: Retrieving the Data

<CFIF #ISSTRUCT(XMLRESPONSE.RESPONSEVALUE)# EQ "Yes">
<CFLOOP COLLECTION = "#xmlResponse.ResponseValue#" ITEM = "Z">
<CFSET "#Z#" = "#xmlResponse.ResponseValue[Z]#">
<!--- <BR>[#Z#] - #xmlResponse.ResponseValue[Z]#<BR> --->
</CFLOOP>
</CFIF>

The above code iterates through the structure capturing the value of each element in the structure in a ColdFusion variable. This may or may not be the way a particular application uses the return data; this simply illustrates one way to use the data.

Moving ColdFusion Test Application Into Production

Once the application has been approved for production, two changes must be made in order to call services in the Production Environment.

First, in the sample code of Example 5, the Development Environment is designated within the “XMLRPCSERVER =” field. This field contains the address of the GI server that you wish your application to call. To have your application call the production server, simply change the address in this field as shown in Example 7.

The second required change is to the third parameter. In Example 5, the third parameter is “Demo Validation." When an application is moved into the Production Environment, the “Demo “ is removed. In this case, the third parameter must be changed to “Validation” as indicated in Example 7.

Example 7: Calling the Service in the Production Envrionment

<!--- Perform the XMLRPC call to the server --->
<CF_XMLRPC_CLT
XMLRPCSERVER=" production GI URL"
METHODNAME="validateAccount"
OUTPUT="xmlResponse"
RAWRESPONSE="aResponse">
<CF_XMLRPC_CLT_REQUESTPARAM VALUE=#userId# TYPE="string">
<CF_XMLRPC_CLT_REQUESTPARAM VALUE=#password# TYPE="string">
<CF_XMLRPC_CLT_REQUESTPARAM VALUE="Validation">
<CF_XMLRPC_CLT_REQUESTPARAM VALUE=#account# TYPE="string" >
<CF_XMLRPC_CLT_REQUESTPARAM VALUE=#date# TYPE="string">
</CF_XMLRPC_CLT>

ColdFusion MX Applications

Setting Up an Application Server for ColdFusion MX

The original XMLRPC_CLT custom tag will work with ColdFusion MX; however, it is extremely slow. It is highly recommended that the PSU_AIS_XMLRPCMX custom tag be used with MX. The new custom tag does not use the MSXML parser, which makes it easier to use and less likely to be affected by Microsoft security changes. The setup for the Generalized Interface (GI) and ColdFusion MX requires that two custom tags be installed on the computer that will be making the calls to the GI. The setup for the development and production ColdFusion MX servers should be the same. The first step to using ColdFusion with the Generalized Interface is to be sure that your server meets the system requirements. While these requirements are not hardware related, they define a select set of software that must be installed on the ColdFusion server for the custom tags to function properly.

System Requirements

Windows folder tree structureSetting Up the ColdFusion Custom Tags

ColdFusion provides the ability to write custom tags. ColdFusion’s ability to adapt to custom tags has allowed for the creation of a set of tags that allow a ColdFusion programmer to access the Generalized Interface via XML-RPC.

If you are designing an application in ColdFusion and require the custom tags, please contact the Generalized Interface Administrator. Please do not use the XML-RPC tags available from the Macromedia Web site. The tags supplied directly by AIS have been modified.

The custom tags need to be installed into the ColdFusion MX custom Tags directory. This directory is usually C:\CFusionMX\CustomTags. Unzip the custom tag files into a folder called XmlRpc in the custom tags directory. The directory structure should look similar to the image to the right.

XML-RPC Call in ColdFusion (Calling a Service)

The code used to call the GI consists of three parts. The parameters being sent to the service must be set. The actual call is then made to the Generalized Interface server; then, the data returned from the service must be moved into the appropriate variables within the application. This is, in principle, no different from making any other function call.

The following is an example of the ColdFusion code necessary to call a service named “getEmployeeBasicData." The value of “XMLRPCSERVER” is the address of the server where the web service resides. In this case, it is the listening port of the Generalized Interface Development platform. (All applications in development will make their XML-RPC call to this address.) The value of “METHODNAME” is the name of the service in the Generalized Interface that the application is calling.

This service requires one parameter: access account id. The one parameter required by the service is sent after the mandatory initial three parameters: user ID, password, and application name. In this case, the application has been named “Demo Application” in the Interface, which is the value of the third parameter.

Example 11: Calling the Service in ColdFusion MX

<!--- Perform the XMLRPC call to the server --->
<CF_PSU_AIS_XMLRPCMX
XMLRPCSERVER= #giURL#
METHODNAME="getEmployeeBasicData"
OUTPUT="giResponse"
TIMEOUT="30"><!--- seconds; default is 60 if attribute not set--->
<CF_PSU_AIS_XMLRPCMX_REQUESTPARAM VALUE=#userId# > <!--- auth ID--->
<CF_PSU_AIS_XMLRPCMX_REQUESTPARAM VALUE=#password# > <CF_PSU_AIS_XMLRPCMX_REQUESTPARAM VALUE="Demo Application" > <CF_PSU_AIS_XMLRPCMX_REQUESTPARAM VALUE="EJH122" > <!---lookup ID --->
</CF_PSU_AIS_XMLRPCMX>

<!--- Check for Errors upon return data --->
<cfif IsDefined("giResponse.Fault")>
<!---The fault is for problems with the GI server, client, or one of their subsystems--->
Fault Number: <cfoutput>#giResponse.fault.faultCode#</cfoutput><br>
Fault Message: <cfoutput>#giResponse.fault.faultString#</cfoutput>
<cfelseif (giResponse.responseValue[1] IS NOT 0)>
<!--- Here I’m just checking the first parameter that is returned to see if it’s not 0--->
<!--- For this service, as with most that return mainframe data, the first two --->
<!--- parameters returned are Error Code and Error Message. These are returned --->
<!--- by the Natural routine that gets data for the service.--->
Error Number: <cfoutput>#giResponse.responseValue[1]#</cfoutput><br>
Error Message: <cfoutput>#giResponse.responseValue[2]#</cfoutput>
<cfelse><!---Display response since no errors--->
<cfdump var=#giResponse# expand="yes"><!---for debug only--->

<!--- loop through giResponse.responseValue, dump to screen--->
<cfloop index="i" from="1" to="#ArrayLen(giResponse.responseValue)#">
<cfoutput> #giResponse.responseValue[i]# <br></cfoutput>
</cfloop>
</cfif>

After this call, the return data will be in the variable named in the “OUTPUT” field, giResponse in this case. The giResponse variable will contain one of two possible structures depending on the outcome of the call. If there was a fault, then giResponse.fault will be a structure containing the values giResponse.fault.faultCode and giResponse.fault.faultCode. If there was not a fault, then the response will be in giResponse.responseValue. The giResponse.responeValue variable may itself be a string, array or structure, depending on the service called. The simplest way to determine the data type returned is with the <cfdump var=#giResponse# expand="yes"> tag. In other cases, however, this variable may be a complex structure.

In the case of getEmployeeBasicData, the giResponse.responseValue variable is an array, as is the case for most services. If a service returns its data in a form other than an array, it will be noted in the service’s specification sheet (available from the GI Administrator). In the above example, the code iterates through the array displaying each element. This may or may not be the way a particular application uses the return data; this simply illustrates one way to use the data.

Moving ColdFusion MX Test Application Into Production

Once the application has been approved for production, two changes must be made in order to call services in the Production Environment.

First, in the sample code of Example 11, the Development Environment is designated within the “XMLRPCSERVER =” field. This field contains the address of the Generalized Interface server that you wish your application to call. To have your application call the production server, simply change the address in this field as shown in Example 12.

The second required change is to the third parameter. In Example 11, the third parameter is “Demo Application”. When an application is moved into the Production Environment, the “Demo “ is removed. In this case the third parameter must be changed to “Application” as indicated in Example 12.

Example 12: Calling the Service in the Production Environment

<!--- Perform the XMLRPC call to the server --->
<CF_XMLRPC_CLT
XMLRPCSERVER=#productionGiUrl#
METHODNAME="validateAccount"
OUTPUT="xmlResponse"
RAWRESPONSE="aResponse">
<CF_XMLRPC_CLT_REQUESTPARAM VALUE=#userId# TYPE="string">
<CF_XMLRPC_CLT_REQUESTPARAM VALUE=#password# TYPE="string">
<CF_XMLRPC_CLT_REQUESTPARAM VALUE="Application ">
<CF_XMLRPC_CLT_REQUESTPARAM VALUE=#account# TYPE="string" >
<CF_XMLRPC_CLT_REQUESTPARAM VALUE=#date# TYPE="string">
</CF_XMLRPC_CLT>

COM Applications

Setting Up an Application Server To Use COM

The setup for the Generalized Interface (GI) and COM requires that several packages of software be installed on the computer that will be making the calls to the GI. Remember to setup the development and production servers in the same manor. The first step to using COM with the GI is to be sure that your server meets the systems requirements. While these requirements are not hardware related, they define a select set of software that must be installed on the COM server for the COM dlls to work.

System Requirements

Installing Required Components

The quickest way to install the two required dlls and the MS XML 3.0 parser is to install the XML-RPC for COM demonstration program. This program can be obtained by emailing the Generalized Interface Administrator. Once you have obtained the previous file, unzip it into a temporary directory. Once unzipped, there are two folders. The Program folder has a compiled version of the program along with an installer. The SourceCode folder has the source code for the program. Since the installation process registers the necessary dlls on your system, it must be run before the source code will work. To install the program open the Program folder, double click on ‘setup.exe’ and follow the directions.

Once set up is complete you may delete the original zip file, as well as the contents you unzipped, into a temporary directory. The demonstration program will be in the c:\program files\GI_COM directory\GI_COM.exe directory unless you specified elsewhere during the installation process. To begin using the demonstration program, simply start the GI_COM.exe executable. Instructions on using the program are provided at run time.

Note: Before you will be able to use the demonstration program you must have an application registered on the GI that includes the IP address where the demonstration program will reside. The application must also have the following services registered: “getEcho”, “validateAccessAccount”, and “validateAccessAccount2Factor”. When you first start the GI_COM.exe, you will be asked to enter the name of the application you have registered in the GI. Make sure to enter the application name exactly (case sensitive) as you entered it in the GI.

When you begin developing your own applications using the COM client, remember that you need to reference the three above dlls. In Visual Basic, you reference dlls in your project by:

XML-RPC Call in COM (Calling a Service)

The call the GI consists of three parts. The parameters being sent to the service must be set. The actual call is then made to the GI server. Then the data returned from the service must be moved into the appropriate variables within the application. This is, in principle, no different from making any other function call.

The following is an example of the COM code necessary to call a service named “validateAccount” in Visual Basic. The “execute” method of the “client” object has the following syntax: ClientObject.Execute (hostname, hostpage, service, argumentArray). In this case, hostname is the Development Environment of the GI ("atsc44.oas.psu.edu"), hostpage is the location of the XML-RPC server ("/cgi-bin/axis.exe/rpc2”), and service is the name of the Web Service being called and argumentArray is parameter list.

This service requires two parameters: account number and date. The two parameters required by the service are sent after the mandatory initial three parameters: user ID, password, and application name. In this case, the application has been named “Demo Validation” in the Interface, which is the value of the third parameter.

Example 8: Calling the Service Using the COM Cllient in Visual Basic

Dim accountClient As New Client
Dim DOMdocument as DOMdocument
Dim paramList() as Variant
Dim response as Variant

‘sets https
With accountClient
.Secure = True
.Port = 443
End With

‘loads parameters into an array
paramList() = array(userId, password, “Demo Validation”, _account, date)

‘call to GI in XML-RPC
Set DOMDocument = accountClient.Execute("vwtest.oas.psu.edu", _
“isapi/gi.dll/rpc2", "validateAccount", paramList)

‘Parse the xml response into the “response” variable
Call accountClient.ResponseToVarient (DOMDocument, response)

In this particular case, the validateAccount service returns a simple string value of “true” or “false” in the variable response. In other cases, however, the returned variable may be a complex data structure such as an array, the user defined data type of struct (name/value pair) included in the XML-RPC for COM Utilities or even an array of structs. If the data is returned in a complex structure, such as a struct, it is necessary to iterate through the struct to retrieve the data. A sample of this is shown below.

Retrieving the Data from a Struct

In the case that the data being returned is in a struct format, the response variable from Example 8 would have been defined as: Dim response as Struct . The code in Example 8 would otherwise look the same. In order to use the struct data type, “XML-RPC for COM-Utilities” must be reference in your project.

The struct data type essentially consists of an array of a name/value pairs. The following example iterates through a struct and stores the names and values in a single variable that could be used to display the information on screen. The code also creates an array that contains only the values from the struct. Note that the first index number of the struct is 1 as opposed to 0 for an array.

Example 9: Retrieving the Data from a Struct

ReDim values(response.Count - 1)
For i = 1 To response.Count
nameValue = nameValue + response.Member(i).Name & "= " & _ response.Member(i).Value & vbCrLf
values(i-1)= response.Member(i).Value
Next

The above code iterates through the struct and writes each name value pair to a single variable as well as writing each value into an array. This may or may not be the way a particular application uses the return data; this simply illustrates one way to use the data.

Moving COM Test Application Into Production

Once the application has been approved for production, two changes must be made in order to call services in the Production Environment.

The first change that needs to be made is to the third element of the argumentArray used by the clientObject.execute method. In Example 8, the third element is “Demo Validation." When an application is moved into the Production Environment, the “Demo “ is removed. In this case, the third element of the array must be changed to “Validation” as indicated in Example 10.

The second required change is to the hostname parameter of the clientObject.execute method. This parameter contains the address of the GI server that you wish your application to call. In the sample code of Example 8, the Development Environment is designated. To have your application call the production server, simply change the hostname parameter to the address shown below in Example 10.

Example 10: Calling the Service in the Production Environment

Dim accountClient As New Client
Dim DOMdocument as DOMdocument
Dim paramList() as Variant
Dim response as Variant

‘sets https
With accountClient
.Secure = True
.Port = 443
End With

‘loads parameters into an array
paramList() = array(userId, password, “Validation”, _account, date)

‘call to GI in XML-RPC
Set DOMDocument = accountClient.Execute("production GI URL", _
isapi/gi.dll/rpc2", "validateAccount", paramList)

‘Parse the xml response into the “response” variable
Call accountClient.ResponseToVarient (DOMDocument, response)

JSP/Java Applications

This section is still under construction. If you need to call the Generalized Interface from JSP/Java please contact the General Interface Administrator for assistance.

Smalltalk Applications

The code used to call the Generalized Interface (GI) consists of three parts. The parameters being sent to the service must be assigned values. The actual call is then made to the GI server. Then the data returned from the service must be moved into the appropriate variables within the application. This is, in principle, no different from making any other function call. The VisualWave base image already has methods for “calling” GI services.

The following is an example of the Smalltalk code necessary to call a service named “getStudentOrEmployeeID”.

Example 13: Calling the Generalized Interface Service

“Set the parameters before invoking the GI service”

parms := List new.
parms add: (PSU.PSUXML.XMLRPCScalar type: #string data: (OASMainframeManager userID)).
OASMainframeManager getMFComm authManager auth1stFactorAgent shouldPassToken
ifTrue: [parms add: (PSU.PSUXML.XMLRPCScalar type: #String data:
OASMainframeManager getMFComm authManager auth1stFactorAgent tgtTicketString)]
ifFalse: [parms add: (PSU.PSUXML.XMLRPCScalar type: #String data: OASMainframeManager userPW)].
parms add: (PSU.PSUXML.XMLRPCScalar type: #string data: (ServerSystemVariables default applicationName)).
parms add: (PSU.PSUXML.XMLRPCScalar type: #string data: (OASMainframeManager userID)).

“Invoke the GI service”

result := PSU.PSUXML.XMLRPCClient
responseWithMethod: 'getStudentOrEmployeeID'
params: parms.

“Process result of GI service”

(result isNil or: [(result at: 1) isKindOf: PSU.PSUXML.XMLRPCFault])
ifTrue: [errorMessage := 'Unable to access Generalized Interface service.'.
errorCode := '1'.
result isNil
ifTrue: [aReply recordErrorWith: errorCode with: errorMessage.]
ifFalse: [((result at: 1) members do:
[:each | each name = 'faultString'
ifTrue: [errorMessage := each value data].
each name = 'faultCode'
ifTrue: [errorCode := each value data].
]).
aReply recordErrorWith: errorCode with: ('Unable to retrieve PSU ID for student.<br>', errorMessage).
].
]
ifFalse: [aReply recordErrorWith: 0 with: 'Successful'.
aReply returnData: result.
].

The parameters to be passed to the GI service are added to a Smalltalk List instance. User ID, password, and application name are the first three mandatory parameters for any service; then, the parameters specific to the service are assigned values. This service requires only one specific parameter which is the user ID. For VisualWave applications using the latest base image, the application name is derived from an instance variable from the ServerSystemVariables class.

After the “call," the returned data will be in the temporary variable result, which is an instance of a List. The output parameters from the service are XMLRPC types as shown below:

#(XMLRPCScalar(#string data:'')
XMLRPCScalar(#string data:'')
XMLRPCScalar(#string data:'KKH5')
XMLRPCScalar(#string data:'911170502')
XMLRPCScalar(#string data:'S'))

The structure of the temporary variable result corresponds to the parameter data area output fields from the Natural subprogram. In this case, the parameter area is:

DEFINE DATA
PARAMETER
1 #RETURN-CODE(A4)
1 #RETURN-MSG(A250)
1 #PARM-CODE-PERS-ACCESS-ACCT-ID(A8)
1 #NUMB-ID (A9)
1 #CODE-TYPE(A1)

The resulting string data items can be parsed as required by the application.

If the returned value from the service is of the XMLRPCFault type, or nothing was returned(nil), an error message can be generated.

Applications can eliminate duplication of Smalltalk code by moving Generalized Interface access methods into an abstract class.

GI Load Balancing

The GI consists of a dynamic number of individual servers. One of these servers is used as a GI load balancer which distributes the load across the multitude of GI servers. It was set up this way to allow AIS to monitor the performance of the GI servers and add or subtract servers as necessary for the load at any time throughout the day without impacting the end user.

When building an application which will utilize GI services, the application needs to call the GI load balancer ‘getBalancedURL’ as the first GI call of each user session. The call to the load balancer returns only a GI URL and this URL should be used for all the GI calls for that particular session.

The getBalancedURL service does not appear in the GI Management System.  The service can be used by anyone by calling it from the application that is being implemented.

Like all xmlrpc calls there are three necessary items for the getBalancedURL call:

  1. Service/Method Name: getBalancedURL
  2. URL to use for GI when calling getBalancedURL

    Test: https://vwtest.oas.psu.edu/isapi/gi.dll/rpc2
    Acceptance: https://GiAcceptance.ais.psu.edu/cgi-bin/gi.exe/rpc2
    Production: https://gi2.ais.psu.edu/isapi/gi.dll/rpc2
  3. Input parameter list. As in most implementations of XMLRPC the parameter list is sent as an array. 
Input parameters to the getBalancedURL are:
  1. ASET User ID
  2. ASET Password
  3. Name of the application making the call

The response to a getBalancedURL call will be a string consisting of the URL of a currently valid GI Server.

If, for any reason, any call to the GI returns a timeout or a communication error, the application may make another call to the load balancer for that session and retrieve a different URL, and then continue with requests from users without impacting their session. In this situation a returned XML-RPC Fault will not indicate a need for a new GI URL but it will indicate a successful call to the GI, with an error occurring in the call itself or in the input parameters. This error should be addressed by the application before continuing with the session requests.

A standard flow would be similar to the steps below for each user:

  1. User logs in to an application (optional depending on application)
  2. Application calls ‘getBalancedURL’ to get a GI URL
  3. Application makes GI calls using the returned URL
    1. XML-RPC Fault returned from GI
      1. Application handles error and continues with the same GI URL
    2. Timeout or communication error returned from GI call
      1. Application handles error and can request a new GI URL using the getBalancedURL service
  4. User ends session
         a. Application discards GI URL from that session

Acceptance Testing

  1. Contact the Generalized Interface Administrator and request the application be moved to acceptance for further testing (Information about the acceptance environment will be given at this time).  The request must be sent at least 3 business days prior to when the test is to begin.
  2. Remove the "Demo" prefix from the application name which is sent as a third parameter of the XML-RPC call.
  3. When acceptance testing is complete, change references from TEST data sources to reflect production data sources. This must be done before the application is moved to the Production Environment. Do this by logging into the Development Environment and selecting “Update a Service Request”. This screen allows the developer to change the data source to ISIS or IBIS.

Production Move

To request for the application to be moved to production:

[ Back to Top ]

GI Web Services Natural Programming Standards

The Generalized Interface (GI) communicates to a Natural subprogram via a .dll created by the Entire X Workbench. Entire X is “middleware” messaging software which allows the GI Server to communicate with the mainframe. With this architecture, we are able to run Natural modules on the mainframe and pass data back and forth between the mainframe and the GI Server. Utilizing Entire X Broker, the GI Server can open a conversation with the mainframe and keep that conversation open. The ability to maintain a conversation is what allows the GI to safely update mainframe data via Natural’s record locking capability.

GI flow diagram

In many cases, groups of data will need to be processed together and therefore the modules to access and maintain that data should be coupled. The following standards have been developed for several reasons

The following standards were developed by a group which consisted of the GI maintenance team, application developers, Natural programmers, and database administration staff.

Actions

Most groups of data will need the following actions performed on them:

Actions on a group of data will be divided into two GI Services--a getService and a manageService. The getService will simply do as the name implies, retrieve a group of data for inquiry purposes. The manageService will be a single service that controls Locking, Updating, Validating, Storing, and Deleting data. The single manageService control a Natural Driver module. The Driver module will determine, based on a code sent, which of the appropriate Natural subprograms to call (i.e. lock, update, validate, store, etc.). The main benefits of this structure are as follows:

Note: It may not be efficient to completely separate the Validate and Update and Store actions. It is more efficient, from a network traffic perspective, to “CALLNAT” the Validate subprogram from the Update and Store action subprograms rather than making two distinct service calls over the network. For similar reasons, it is be more efficient to invoke the Store action from within an Update action when the record to be updated does not exist in the database.

Natural modules for these services will reside in new libraries created by DBA, with the suffix ‘RPC’. Placement of modules into a library should follow existing conventions such that: any module that would normally be placed in EMPLIB should be place in EMPRPC, any module that would normally be placed in PAYLIB should be placed in PAYRPC, and any module that would normally be placed in AISLIB should be placed in AISRPC, etc. Any module that needs to reside in APPLSYS can still be placed in APPLSYS since it will continue to be the step-lib for the new xxxRPC libraries. The new libraries will be set up as a step-lib to their counterparts and vice-versa (i.e. EMPLIB is step-lib to EMPRPC and vice-versa). This way if subprograms are created in a certain library for existing online mainframe systems/processes (and vice-versa) they can still be called.

Program naming standards have also been developed for the Natural modules.

For IBIS

The first 5 characters of the program name will follow existing IBIS Program Naming Standards. The 6th and 7th characters are defined as below, and the 8th character will follow existing IBIS Program Naming Standards (“N” for a subprogram).

For ISIS

The first 6 characters of the program name will follow existing ISIS Program Naming Standards. The 7th character represents the following:

Examples of IBIS Data Functions

The following are examples of working IBIS data functions that reside in the Natural library EMPRPC:

Examples of ISIS Data Functions

The following are examples of working ISIS data functions that reside in Natural library AISRPC:

Driver Module Codes

The following codes are to be passed into the driver module to determine which action routine to call:

Parameter Data

When creating a manageService, the driver along with all the individual action modules should make use of a single Natural Parameter Data Area (PDA). The getService associated with a mangageService may also make use of the mangageService’s PDA. This will allow increased ease of maintenance. There is also a specific order of parameters for services depicted as follows:

Group or Array Structures

Array or group structures can be passed via the GI Services however they should be passed as individual array elements as opposed to a group structure. For example, you should use this structure:

Instead of:

Size of Data

There is a size limitation to the amount of data that can be passed between the calling application, the GI Server, and the Mainframe. SAG says the limit is 32K; however, in testing, we have found that it is closer to 30K. Therefore, services that may need more than 30K of data passed into or out of them must be broken down into multiple services, or calling a single service multiple times. It will be up to the application developer and the Natural programmer to spec out a service or services to accommodate this limitation.

Time Considerations

Services which run longer than seven (7) minutes must be broken down into multiple services or call a single service multiple times. A timer can be used for calling a single service multiple times. It will be up to the application developer and the Natural programmer to spec out a service or services to accommodate this limitation.

Dates and Numeric Data Format

It was also decided that since XML returns data as a string, all parameters should be sent as a string, including numeric and data parameters. The string conversion is to be done in Natural before sending the data back to the calling application.

There will also be a special convention for handling dates. Dates should be converted to true Windows/PC/database format of MM/DD/YYYY before being returned. This will make it easier for the calling application to use the data. Several Natural utility subprograms have been written to convert dates and numeric fields to string.

Conversions can be done in the driver module, thus allowing to the sub programs to be used for other non-EntireX applications.

Dates

Numeric Data

Numeric utility modules are named based on the action and the field size that needs to be converted. For example, numeric-to-alpha conversion modules will be named GUNTAxxN and alpha-to-numeric conversion modules will be named GUATNxxN. Where the “xx” is the size of the numeric field to be converted. (i.e. an N3.2 field will use GUATN32N or GUNTA32N, an N5.0 field will use GUATN50N/GUNTA50N). The alpha field resulting from the conversion will be two bytes longer than the original numeric field in order to account for the decimal and sign. A more generic conversion module for numerics has been developed. Module A6ZNCA accepts parameters for the number of digits to the left and to the right of the decimal point and returns the character representation for that number with leading zeros suppressed.

ON ERROR Logic

Each Natural subprogram invoked by EntireX must contain an ON ERROR logic block. This will ensure the client will receive Natural errors as part of the standard output parameters from EntireX. The recommended ON ERROR block follows:

ON ERROR
MOVE '9999' TO #RETURN-CODE
COMPRESS 'ERROR' *ERROR-NR 'FROM NATURAL MODULE' *PROGRAM
'- LINE#' *ERROR-LINE
INTO #RETURN-MSG
ESCAPE ROUTINE
END-ERROR

The “9999” value for #RETURN-CODE may be used by the GI as a key for knowing a Natural system error occurred. Other application errors should not use “9999” as their return code.

[ Back to Top ]

PSU Pay GI Services Quick Guide

This guide documents the steps necessary to use PSU Pay through GI Services.

Processing Steps

  1. The Customer on the Client application site is ready to pay. The Client application calls the GI Service startPSUPayTransaction to retrieve a Transaction ID. This is called the PSUBeginTransactionCmd API because it begins the transaction. Client will use the Transaction ID to track the customer and use this number in a hidden field form in Step 2. Input parameters are MerchantNumber, Amount, TaxAmount, UserID, Product, Location, ReturnURL, and AutoDeposit (flag). The ReturnURL is the page on the client site where PSU Pay will redirect the customer after payment. AutoDeposit is a flag designating the payment for automatic deposit (Y) or wait until the merchandise is shipped (N).
  2. The Client application uses an HTML form post to redirect the customer to the PSU Pay Buy Page. The URL to post to for testing is https://ibm2.oas.psu.edu/PSUPay/Checkout. The form post must include the hidden fields TRANSACTION_ID, which is the TransactionID value returned by startPSUPayTransaction and MERCHANT_NUMBER, which is the clients designated eCommerce merchant account number.
  3. The customer will now be on the PSU Pay website. They will be presented with a Buy Page to complete with credit card information. They will have 10 minutes to complete the transaction before PSU Pay ends his or her session. They will be given 3 attempts to finish the transaction. Once the transaction is completed, PSU Pay will redirect to the client website as stated in the ReturnURL parameter in the startPSUPayTransaction.
  4. Once the transaction is completed, PSU Pay will redirect to the client website as stated in the ReturnURL parameter in the startPSUPayTransaction.
  5. When the customer is redirected back to the Client application site, the client must call the getPSUPayTransactionStatus.The input parameters are the MerchantNumber and TransactionID. The results are the Order Status, Order Number, Merchant Number, and Transaction ID. The Payment Status will be success, failure, or maxattempt (3 failed attempts). If the call is made before PSU Pay has returned the customer browser, the client may also get a pending or waitinput state.
  6. The Client application will present an error message to the customer for maxattempt or failure states. The Client will proceed with backend processing for a success state. A pending or waitinput state will require the Client to re-issue the getPSUPayTransactionStatus until a state of success, failure, or maxattempt is reached, or until the Client application “decides” it can timeout the transaction.
  7. If backend processing is successful, the Client application will call the getPSUPayConfirmation to confirm the order should be processed and the funds collected. The input parameters are the Merchant Number and Transaction ID. The result is either a success or failure, which will be determined by the Primary and Secondary Return Codes. Any code other than 0(zero) is a failure. After a Success, the client should indicate to the customer the success of the transaction. Please include the Order Number so the customer can reference their order in the future.

[ Back to Top ]