Argos API

Before any reports can be called via the API, a MAPS Administrator must first configure the HTTP Referrer(s) in the MAPS Configuration. An HTTP Referrer is a URL (web address, internal server location, etc.) that has been approved for making calls to the Argos API. When referrer checking is enabled, API calls will automatically fail if they are made from a location not in this list.

 

Since the API can make data available to a very wide audience via a web server, portal, or third party application server, an Argos Administrator (or a user with a custom role that includes the "Edit Report API" permission) must specifically enable the API for each report they wish to make accessible via the API. To enable API access, edit the report and go to the API tab. Then, check the box to Make this report accessible to API.

Note: Non-administrators will not be able to see any details on this tab when editing a report.

Once the box has been checked, MAPS generates a Report Unique Identifier for the report. This is the string that identifies this specific report when making an API call. If the report or DataBlock is moved at a later date, it will retain its Report Unique Identifier. If the report or DataBlock is copied, an Argos Administrator will need to generate a new Report Unique Identifier for the copy to make it accessible via the API.

Username and Password

These fields allow you to specify a default username and/or password to use when calling this report. If there is a username and password that is passed in via the API call (GET, POST form, or the MAPRAPI application), it will override the username and password entered here. If the default user is an LDAP user, you must enter the password here or pass in the password via the API call.

Variables

If you want to choose default values for any of the Argos variables, you can do so in the Variables section. Select the variable you want to specify the value for, and then click the green plus button to add a value.

Any parameters passed in from the GET, POST, or MAPRAPI call will override the default values entered here. When calling a report via Interactive mode, default parameter values will be ignored because the user inputs all data.

 

When making a call to the Argos API, you have a choice of automatic mode or interactive mode.

Automatic Mode

Automatic mode uses predefined parameter values supplied either on the API tab of the report, or by the HTML that is invoking the API.

• HTML GET
  The easiest way to call the Argos API is with an HTML GET request, which is basically a standard HTML link. When following the link, the API executes using the parameters as defined in the Variables section of the API tab.
  
    <a href="http://10.1.1.10:8080/mrr?report=WUH5C7TOR5MSZL6YSNYMC62WDVLCFOQXE6JD635WOKQILQ">Click here to execute the report</a>
  
  
• HTML POST
  The other automatic mode method is via HTML POST request. A POST request is an HTML form which supplies the parameters to be used to generate the report. Note that it is the calling program or webpage that is specifying the parameters, not the end user (unless the user entered them somewhere in the calling program/webpage before the API call was made). Any variable values not specified in the form will use the values specified on the API tab.
  
   <form method=post action="http://10.1.1.10:8080/mrr">
    <input type="hidden" name="report" value="WUH5C7TOR5MSZL6YSNYMC62WDVLCFOQXE6JD635WOKQILQ">
    <select name="PO_HEADER.DEPARTMENT">
    <option value="ACCT">Accounting</option>
    <option value="HR">Human Resources</option>
    <option value="RECP">Reception</option>
    </select>
    <input type="hidden" name="REPORTFORMAT" value="xls">
    <input type="submit" value="Get POs">
    </form>

Click the Sample Post or Sample Get buttons to copy sample HTML to the clipboard. You can use this HTML as a starting point by pasting it into the calling webpage or application. Check the options to generate secure (HTTPS) or unsecure (HTTP) HTML as desired; the only difference is the protocol specified. For information on how to format the HTML in your calling webpage or application, consult an HTML reference such as http://www.w3.org/TR/html4/interact/forms.html.

The following is the list of parameters that you can specify when making GET and POST requests:

Parameter	Description
REPORT	The Report Unique Identifier. Required.
FILENAME	The name of the file to be returned, if you do not want to use the default filename.
PASSWORD	The password corresponding to the provided username. Overrides the password on the API tab if one is specified.
USERNAME	The user to run the report as. Overrides the username on the API tab if one is specified.
REPORTFORMAT	This can be any of the valid Argos output types (CSV, PDF, RTF, XLS, HTM, or TXT).

In the example POST shown above, the HTML form uses the REPORTFORMAT parameter to specify that the API should return an .xls file to the user.

In addition to the above parameters, if the report format is PDF, you can specify various PDF Options as parameters.

Interactive Mode

Interactive mode does not pass in any variables. Instead, the API launches a restricted version of the Argos dashboard, enabling the user to enter their desired parameters. Running a report in interactive mode is similar to running the report in the Argos Windows client, except that the user does not see the Argos interface. Users can only access the report specified by the API link and the dashboard (parameter entry form) needed to run that report. They are not able to see the Explorer tree in Argos, nor navigate to a different report or DataBlock.

Interactive Mode Requirements

Since the Argos client is a Windows application, it only runs on devices using the Windows operating system. If your users may be on different platforms, you should consider using the Web Viewer API instead.

Interactive Mode API users must have the Evisions Application Launcher (EAL) and Microsoft .NET Framework installed on their machines. If users do not have the ability to install software on their machines, an alternative is for your IT department to install the EAL via Group Policy (available in MAPS 4.5 and higher). For more information, please refer to the MAPS Help.

Calls to interactive API reports ignore any parameters that are specified on the API tab. Instead, the user enters parameter values in the dashboard after it loads:

Notice how the "Select a letter" and "State filter" dropdowns are in their default state, and the listbox is not populated with any data. Users can select the parameters of their choice before running the report selected in the Report Options dropdown at the top of the window. No other reports are available to the user.

Creating the API Call

To specify that an API call should use interactive mode, include the &AutoLogOn parameter in the API call. To see an example, when you are editing a report, click the Sample Interactive button on the API tab of the Edit Report dialog to copy a simple HTML link to the clipboard. You can then paste this HTML into the calling application or web page.

<!-- Report = My Folder.List of names.Name report (banded) -->

<a href="https://myserver/argos/index.html?report=USIXECCRQWTQY2C6IH6EMZXQFEB6TCA4DEQZ6N7UTKTK434Z2S2VSX6NANRUY7MONWZWYRQ73GQZQ&AutoLogOn">Text</a>

<!-- Report = My Folder.List of names.Name report (banded) -->

<a href="http://myserver/argos/index.html?report=USIXECCRQWTQY2C6IH6EMZXQFEB6TCA4DEQZ6N7UTKTK434Z2S2VSX6NANRUY7MONWZWYRQ73GQZQ&AutoLogOn">Text</a>

You can choose either the HTTP or HTTPS link depending on your needs. Your MAPS administrator can advise you on the method(s) configured for your server.

There are two components to note in the URL:

• The long string after ?report= is the Report Unique Identifier that identifies the report to be called.
• The &AutoLogOn parameter indicates that the report should be run in interactive mode.
  
  
  
  

Passing Parameters in the Interactive API Call

If you would like to pre-populate some or all of the variables in the dashboard, Argos 4.3 and higher allows you to pass dashboard parameters in the URL. The dashboard in the screenshot above has three variables, two of which are used to generate the banded report. The first variable is the first letter of the students' last names. The second variable is the state of residency. Finally, the "Get names" button controls whether or not the list box populates, assuming the other two variables have been specified.

• Parameter - The name of the form object in Argos.
• Field - The name of the sub-variable in Argos. For a drop-down selection, this is the name of the column shown in the drop-down.
  

Parameter	Field	Value	Function
DropDown1	Letter	C	Required to run report; selects the students' last initial.
DropDown2	State	PA	Optional; serves to filter report results by state.
GoButton	N/A	1	Not used by report. Setting this parameter to '1' means the "Get names" button is clicked and the results of the current parameter selection will appear on the dashboard without requiring any user input.

To pass a parameter in the URL, append it to the report URL as follows:

<!-- Report = My Folder.List of names.Name report (banded) -->

<a href="http://myserver/argos/index.html?report=USIXECCRQWTQY2C6IH6EMZXQFEB6TCA4DEQZ6N7UTKTK434Z2S2VSX6NANRUY7MONWZWYRQ73GQZQ&AutoLogOn&DropDown1.Letter=C&DropDown2.State=PA&GoButton=1">Text</a>

When the user follows the link to the report, the dashboard variables prepopulate with the values specified in the URL (which may have been set elsewhere in the calling program and then passed in programmatically via the URL). The user can then click the Save button to download a PDF of the report, without needing to set the variables in the dashboard.