How To Use The Rest API End Point - Reports And Letters

Warning Note WARNING: This end-point is currently in development and incomplete.

At present, the only supported destinations are SVG and CSV.

Use this end-point to run a report or letter in Collect!. For the printer destination, you would use SVG. Collect! returns an SVG image in the Response Body that can then be used to send to the printer.

Reports that stop and prompt the user for information will require a Web Socket ID passed in the 'websocket-id' field of the request body. If you are unsure about whether the reports has prompting, then it is best practice to always open a Web Socket connection. Please see Web Sockets above.

Useful Note If the report needs to use a Web Socket, and fails to do so, the plan will fail. Any changes made to the database by the report, up to that point, will be rolled back.

POST Type End-Point

/api/v1/collect/app/report

Request Body

{
  "report":"{report name}",
  "script":"{report script}",
  "starton":"{record type}",
  "rowid":["{rowid}",...],
  "websocket-id":"{websocket-id}",
  "destination":"{destination1},{destination2},...",
  "showmargins":{true/false}
}

Code	Description
report	This is the name of the report or letter to run. This is optional, if script is populated, but required if script is blank (or not supplied).
script	Scripts are report code that can execute directly or alter reports. If a script is supplied, and the report is blank (or not supplied), then the script will execute as is. If a script and report are both supplied, the script is prepended to the top of the report body.
starton	This is the record type that must be active for a report or letter to be run. For example, letters printed to a Debtor would be "starton":"debtor" and letters printed to a Client would be "starton":"client" If Start On is not supplied, then the Report's Start On is used. If a Report Start On were not supplied (IE: just a script), then the the Start On is set to Anywhere.
rowid	This is an array, even if it's just a single value. The array should be a list of rowid's to run the report or letter on.
websocket-id	This is the web socket ID for the applicable socket connection.
destination	This is the output destination to receive in the response. All data is returned as JSON, including file type destinations.
showmargins	This is a true/false option to enable gridlines. When enabled, Margins and Rectangles in the report will display in the output for the SVG destination. This is useful for layout testing. The background grid is in major intervals of 1 inch and minor intervals of 0.5 inches.

Examples

Note that Contact Plans only work for Debtor, Client, Cosigner, and Associate.

Single Record

{
  "report":"Letter 1",
  "starton":"debtor",
  "rowid":["123"],
  "destination": "svg",
  "websocket-id": "43tzLWO2RJzlxQPpsw4EOA=="
  }
}

Multiple Records / Multiple Destinations

{
  "report":"Letter 1",
  "starton":"debtor",
  "rowid":["123", "456", "789"],
  "destination": "svg, csv",
  "websocket-id": "43tzLWO2RJzlxQPpsw4EOA=="
  }
}

Response Body

{
  "svgPages": [
      "",
      "",
      ...
  ],
  "csvRows": [
      "\"{Row 1}\"",
      "\"{Row 2}\",
      ...
  ]
}

Code	Description
svgPages	This is an array of SVG elements. Each element is a page to be printed.
csvRows	This is an array of rows in the CSV. Each element is meant to be put into a text file for output.

Was this page helpful? Do you have any comments on this document? Can we make it better? If so how may we improve this page.

Please click this link to send us your comments: helpinfo@collect.org