Generate a Dynamic Report without the VeraCore user interface. Use the Dynamic Reporting API to generate any Dynamic Report in your OMS, WMS, or PMA System. Use it to send data to third party applications, your clients, or other vendors and partners.
How it Works
There is some preliminary setup before you can begin using the API. First, you'll need to define and publish the report in the VeraCore database. Then, create a web service user in the PMA database.
Once you have your report and your web service user:
Run the POST Login operation to generate a token for the web service user. You'll use this token in all subsequent operations.
(Optional) Run the GET Reports operation to get a list of Dynamic Reports available to that user.
Select a Dynamic Report from the list. You'll need the reportName from the previous operation.
(Optional) Run the GET Report Details operation to get the report parameters for your selected report.
*Run the POST Reports operation to create the task of running the report. You'll need the report name and filter criteria from previous operations.
*Run the GET Task Status operation to check on the status of the task of running the report. You'll need the TaskId from the previous operation response.
*When your task status is "Done", run the GET Report Task operation to get the report. You'll need the TaskId from earlier.
(Optional) Run the GET Token operation as needed to check your token status.
About the API
Content Type
application/json
Base URL
https://(YourDomain_or_RHU#)/veracore/public.api
Test the API in Swagger
VeraCore's Public API is documented in swagger. You'll be able to try the API and see fully formed json requests and responses there.
Test the API in swagger here: https://(YourDomain_or_RHU#)/veracore/public.api/swagger/ui/index
You will need a Dynamic Report and Web Service User defined to test.
Operations
The seven operations are listed below.
Click the Description link to jump down to the details for each Operation in this article. Below each Operation's detailed section, a sample request and response is provided.
The operations you run will vary depending on whether you're planning a new report task or running a scheduled report. Though your own process can vary, here's an example of how this might look.
Set Up the Report
These might be run on demand.
Sequence
Operation
Remarks
1.
POST Login
Get your Token and its expiration date.
2.
GET Reports
Get a list of available report names.
3.
GET Report Details
Get the report info, columns, and filters for your selected report.
Generate the Report
These might be automated to run on schedule.
Sequence
Operation
Remarks
1.
GET Token
Check the status of your token prior to starting. If Token is valid, skip to Step #3. If token is expired, go to 2.
2.
POST Login
Get your Token. Then repeat Step 1.
3.
POST Report
Create the task of running the report using the report name and filter criteria from step 3 in the Setup process, above. The response is a Task Id, not the report itself.
4.
GET Task Status
Check the task status by Task Id. If the response is "Processing", wait and run this operation again. If the response is "Done", go to step 5. If the response is "Request Too Large", it means the report exceeds 100MB in size. Return to Step 3 with stricter filters to limit the data returned.
5.
GET Report
Get the report results by sending the Task ID for the now "Done" task of running the report. The response is the report itself.
This step creates a token for the Web Service User defined in PMA. Use the token created here in all subsequent operations. NOTE: Tokens expire after 3 months.
Parameters
Parameter
Parameter Type
Description
Data Type
"username"
body
The web service user ID.
string
"password"
body
The web service password.
string
"systemId"
body
The six-character VeraCore OMS/WMS System ID against which you're running the report.
string
Response
Success Response
The response will be the token.
Other Responses
What it Means/How to Fix
Invalid UserID or Password!
Error: Check the user id and/or password in the Web service User setup.
Invalid system specified: {systemId value}
Error: Either this system doesn't exist, or the web service user id is not associated with it.
This identifies which reports the web service user can run. Use the Report Name in the response in operations to get report details and to create the task of running the report.
Parameters
Parameter
Parameter Type
Description
Authorization
header
bearer {Token}
Response
Success Response
The response will be a list of available reports.
Other Responses
What it Means / How to Fix
Get Reports Examples
In the example below, we're sending our token to identify the user. The system returns the Dynamic Report names this user can access.
Note: Access to reports is determined by the Access Level of the web service user tied to the token (see the POST Login operation.) When you set up a web service user, you link them to an access level. When you publish the Dynamic Report in the VeraCore user interface, you restrict access by Access Level.
This operation tells you which columns are on the report and what filters are available. You'll most likely use the filters in the response when setting up the task of running the report (see the Post Report operation, next.)
Parameters
Parameter
Parameter Type
Description
Data Type
"reportName"
query
The reportName from the GET reports operation response.
string
Authorization
header
bearer {Token}
Response
Success Response
The response will show the report details with general report information first, followed by column definitions, followed by filters at the end.
Other Responses
What it Means / How to Fix
Get Report Details Examples
In the example below, we've asked for the report details for the "Order History" report from the previous response. The response here is the report info, a list of columns, and the filter criteria built into the report definition.
This creates the new task of running the report. This step does not return report results. It sets up the job of running the report. Use the filters in the GET reportdetails operation to filter your data. The taskId that is the response will be used to check on the task later and to generate the report results.
Parameters
Parameter
Parameter Type
Description
Data Type
"reportName"
body
The name of the report as it appears in the GET reports operation response.
string
"filterCriteria"
body
(optional) Include applicable filters. Do not include if there are no data filters. Add as many filters as needed by repeating the filterColumnName and either filterValue or startDate/endDate parameters. (See example below.)
"filterColumnName"
body
If you're filtering records based on the value of a column (e.g., Order Date) include the column name as it appears in the GET reportdetails operation response.
string
"filterValue"
body
(optional) If the column you're filtering on is not a date field, enter the filter value here. The system will return records that match that value in the corresponding columnName.
string
"startDate"
body
(optional) If the column you're filtering on is a date field, enter the value for the startDate.
string
"endDate"
body
(optional) If the column you're filtering on is a date field, enter the value for the endDate.
string
Authorization
header
bearer {Token}
Response
Success Response
The response will be the taskId for the task you're creating to run the report. Use this in subsequent operations to check the task status and to get the report results.
Other Responses
What it Means/How to Fix
POST Reports Examples
In the example below, we're calling the Order History Report.
About Filters: In our example, there are two filterCriteria parameters: Order Date falls between 1/1/2018-12/31/2018, and the Ship To Company is "VeraCore". While you cannot add filters in the API request that don't already exist in the dynamic report, you can use a different filter value than the report's default value. For example, in the GET Report Details operation response (above), the filterColumnName "Order Date" has a default value of 30, meaning "the last 30 days of orders." But our filter here can use a different value. Here, we are using the startDate and endDate to get a calendar year of orders. If we wanted the last 365 orders from today, we could have used "filterValue": "365".
This checks on the status of the report. Use the taskId returned in the POST reports operation, above.
Parameters
Parameter
Parameter Type
Description
"TaskId"
path
The taskId for the task you created in the POST report operation, above.
Authorization
header
bearer {Token}
Response
Success Response
The response will be the status of the task. There are three possible statuses: "Done" - The task is completed. You can generate the report. "Processing" - The report is still running. Check back soon. "Request too Large" - The request exceeds 100MB. Narrow your request with filters and create a new task.
This gets the report results. The response for this operation is the report.
Parameters
Parameter
Parameter Type
Description
"taskId"
path
The taskId for the Task you created in the POST report operation, above.
Authorization
header
bearer {Token}
Response
Success Response
The response will be the report itself.
Other Responses
What it Means / How to Fix
GET Report Examples
In this example, we're getting the results from task 5138, which is the report. There were only four orders that met the criteria we used in our POST operation.
