MAPRAPI (MAPS Report API)

MAPRAPI allows you to access an API-enabled report by using an Evisions-developed executable called MAPRAPI (MAPS Report API). This program is distributed as C source code and is intended to be compiled on a UNIX server. 3rd-party applications can use MAPRAPI to call an Argos report and save the results to a specified location. It may be used in conjunction with shell scripts for maximum flexibility.

You can download the MAPRAPI source code and instructions from the Evisions Support site.

Compiling MAPRAPI

Place the .c file on the UNIX server in the location where you want to make the API call from. Rename it to maprapimain.c.

Navigate to the directory where maprapimain.c is located and compile it using the following command:

cc -DOPSYS_UNIX -omaprapi maprapimain.c

Note: Update the command as necessary if you use a compiler other than cc.

Some flavors of UNIX may require one or more of the following flags:

-lsocket

-lnsl

To enable debugging, compile with the following flag:

-DDEBUG

If compilation was successful, you will see an executable called maprapi in the directory. Run the program with no parameters or switches in order to verify it compiled correctly and to display the usage instructions.

Executing MAPRAPI

A call to MAPRAPI takes the following form:

maprapi host port url output_file_name [optional]

where maprapi is the name of the executable, and each entry after it is a parameter.

Required Parameters

• host – The IP address or host name of the server where MAPS is installed.
• port – The port that MAPS is listening on (specified on the Server screen in the MAPS configuration; the default is port 27467).
• url – The URL generated on the API tab of an Argos report that would be used for an HTTP GET request.
• output_file_name – The name of the output file that will be created for the report.
  

Optional Parameters

• timeout=## – Specifies the number of minutes to wait before considering a connection lost in the event of a problem. The default is 15 minutes.
• apitoken=## – Specifies the API security token required to execute API calls.

URL Parameters

URL parameters are appended to the end of the url component of the MAPRAPI call. Each URL parameter must have an ampersand (&) before the name of the parameter.

• DataBlock parameters - The name of an Argos variable. Sub-variable names are specified using dot notation. Any number of DataBlock parameters can be supplied in the URL. Refer to API Examples for a demonstration of how Argos variables can be supplied in the URL.
• REPORTFORMAT=XYZ - Specifies the format of the report. The report format should be compatible with the file extension specified in output_file_name. Supported report formats include:
  • Banded report - HTM, PDF, RTF, XLS, and TXT.
    Note: Use HTM, not HTML.
  • CSV report - CSV and TXT.
    Note: XLS is not supported for CSV reports. You may be able to specify XLS as the file extension, but the REPORTFORMAT must be CSV.
  • Extract report - CSV, TXT, and XML.
  • Crosstab report - PDF
• Timeout=## - When appended to the end of the URL inside of single quotes, this value will override the Client Read Timeout in the MAPS Config Tool.
  

Sample MAPRAPI Call

Depending on your configuration, a call to MAPRAPI will look similar to:

maprapi maps.school.edu 27467 'http://maps.school.edu:8080/mrr?report=DOJM5WFD6ALRNAFMTQTHYOCF2K6KVWHTZSVL6LWQYXKFJIOAWEFJIF&PARAMETER1=AAA&PARAMETER2=BBB&REPORTFORMAT=PDF' ReportOutput.pdf timeout=60