{"type":"doc","content":[{"type":"paragraph"},{"type":"paragraph","content":[{"text":"In addition to creating corrections reports through the EPR app, clients and third-party integration companies can also generate reports through our API route. Generating a report through the api only requires two parameters: ","type":"text"},{"text":"project_id","type":"text","marks":[{"type":"strong"}]},{"text":" and ","type":"text"},{"text":"template_id","type":"text","marks":[{"type":"strong"}]},{"text":". This article will walk you through how to generate the report through the API with the correct parameters.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"1. Grabbing the template_id","type":"text"}]},{"type":"paragraph","content":[{"text":"Report templates hold all configurable information that reports can have. This includes the report title, instructions, logos, included project fields, and sort orders. In order to know which template_id to use, you may need to query all reports and choose which template to use from the list of results. To do so, you should first make a ","type":"text"},{"text":"GET","type":"text","marks":[{"type":"strong"}]},{"text":" request to ","type":"text"},{"text":"/resources/reports/templates. ","type":"text","marks":[{"type":"strong"},{"type":"em"}]}]},{"type":"paragraph","content":[{"text":"You should see something similar to the following result:","type":"text"}]},{"type":"codeBlock","content":[{"text":"{\n \"success\": true,\n \"message\": \"3 record(s) found\",\n \"data\": [\n {\n \"options\": {\n \"sort\": [\n \"groupName\",\n \"reviewType\",\n \"reviewerName\"\n ],\n \"includedProjectFields\": [\n \"projectNumber\",\n \"address\",\n \"projectName\",\n \"dueDate\",\n \"startDate\",\n \"notes\",\n \"scopeOfWork\"\n ]\n },\n \"id\": 2,\n \"jsReport_id\": \"H1ls_En1OH\",\n \"name\": \"Irvine Report Template\",\n \"title\": \"EPR Corrections Report\",\n \"logo\": \"https://epr-qa.s3-us-west-2.amazonaws.com/reportLogo/1570148452674Orange.jpg\",\n \"instructions\": \"Example Instructions\",\n \"createdAt\": \"2019-10-08T21:07:30.000Z\",\n \"updatedAt\": \"2019-11-13T16:42:16.000Z\"\n },\n ...]\n}","type":"text"}]},{"type":"paragraph","content":[{"text":"Each template in the list of results holds all the information that will be used to generate the report. The options field holds additional options that may not be apparent: ","type":"text"},{"text":"sort ","type":"text","marks":[{"type":"strong"},{"type":"em"}]},{"text":"and ","type":"text"},{"text":"includedProjectFields:","type":"text","marks":[{"type":"strong"},{"type":"em"}]}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"sort: ","type":"text","marks":[{"type":"strong"}]},{"text":"The sort object is a three-element array that defines the grouping and sort order that the comments should follow in the report. The first element in the array specifies which comment field the comments should be grouped by within the report. The second and third elements then define how the comments ","type":"text"},{"text":"within","type":"text","marks":[{"type":"em"}]},{"text":" each group should be sorted, with precedence given to the second field in the array.","type":"text"}]}]}]},{"type":"panel","attrs":{"panelType":"info"},"content":[{"type":"paragraph","content":[{"text":"Suppose the sort option for a template was ['category', ‘subCategory’, ‘reviewerName’]. In this case comments would be grouped by their category. For example, their could be a list of comments grouped under the ","type":"text","marks":[{"type":"em"}]},{"text":"Civil , ","type":"text","marks":[{"type":"strong"},{"type":"em"}]},{"text":"and another group of comments grouped under ","type":"text","marks":[{"type":"em"}]},{"text":"Structural ","type":"text","marks":[{"type":"strong"},{"type":"em"}]},{"text":"category. Within each of these categories the comments will be ordered alphabetically according to their ","type":"text","marks":[{"type":"em"}]},{"text":"subCategory. ","type":"text","marks":[{"type":"strong"},{"type":"em"}]},{"text":"In the case that two comments within the same list have the same subcategory, the comment with an earlier reviewerName(alphabetically) will be displayed first.","type":"text","marks":[{"type":"em"}]}]}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"includedProjectFields: ","type":"text","marks":[{"type":"strong"}]},{"text":"This will be an array of all project fields that will be included in the report. ","type":"text"}]}]}]},{"type":"paragraph"},{"type":"heading","attrs":{"level":2},"content":[{"text":"2. Generating a report through the api","type":"text"}]},{"type":"paragraph","content":[{"text":"Once you’ve found the id of the template you would like to use you can simply make a ","type":"text"},{"text":"POST ","type":"text","marks":[{"type":"strong"}]},{"text":"request to ","type":"text"},{"text":"/resources/reports/generate ","type":"text","marks":[{"type":"strong"},{"type":"em"}]},{"text":"with the following request body (JSON):","type":"text"}]},{"type":"codeBlock","attrs":{"language":"json"},"content":[{"text":"{\n \"project_id\": ,\n \"template_id\": \n}","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Including Closed Comments","type":"text"}]},{"type":"panel","attrs":{"panelType":"info"},"content":[{"type":"paragraph","content":[{"text":"This format for this api has changed. Please refer to the example below.","type":"text"}]}]},{"type":"paragraph","content":[{"text":"You can also provide an optional parameter in the request body to specify whether or not to include closed comments in the report. By default, closed comments are filtered out in the corrections report. You can add this option like so:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"json"},"content":[{"text":"{\n \"project_id\": ,\n \"template_id\": ,\n \"options\": {\n \"comments\": {\n \"closedComments\": \n }\n }\n}\n\n// old method\n// below is the old method of grabbing closed comments. \n// although it still works, it will be phased out in the future\n{\n \"project_id\": ,\n \"template_id\": ,\n \"options\": {\n \"closedComments\": \n }\n}","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Filtering Comments By Label","type":"text"}]},{"type":"panel","attrs":{"panelType":"info"},"content":[{"type":"paragraph","content":[{"text":"This format for this api has changed. Please refer to the example below.","type":"text"}]}]},{"type":"paragraph","content":[{"text":"There may be times where you have multiple external statuses pointing to an internal status (e.g. Open and Approved w/ Comments both point to the ‘Open’ internal status) and want to filter comments to only show if they have a specific external status. ","type":"text"}]},{"type":"paragraph","content":[{"text":"Beginning with the ","type":"text"},{"text":"2.3.4 Release of EPR","type":"text","marks":[{"type":"em"}]},{"text":", you can add the ","type":"text"},{"text":"excludedLabels","type":"text","marks":[{"type":"strong"}]},{"text":" parameter inside of the ‘options’. This ","type":"text"},{"text":"optional","type":"text","marks":[{"type":"em"}]},{"text":" parameter will be an ","type":"text"},{"text":"array","type":"text","marks":[{"type":"strong"}]},{"text":" of ","type":"text"},{"text":"external status labels","type":"text","marks":[{"type":"strong"}]},{"text":" that you want to filter the report comments by. ","type":"text"},{"text":"If specified, comments whose label matches one of the labels in the array will be ","type":"text","marks":[{"type":"strong"}]},{"text":"excluded","type":"text","marks":[{"type":"strong"},{"type":"em"}]},{"text":" ","type":"text","marks":[{"type":"em"}]},{"text":"from the report. ","type":"text","marks":[{"type":"strong"}]},{"text":"This filter stacks with the ‘closedComments’ option. If the ‘closedComments’ option is set to true ","type":"text"},{"text":"and","type":"text","marks":[{"type":"em"}]},{"text":" the ‘excludedLabels’ array is specified, the api will first grab ","type":"text"},{"text":"all ","type":"text","marks":[{"type":"em"}]},{"text":"the comments for the project, ","type":"text"},{"text":"then","type":"text","marks":[{"type":"em"}]},{"text":" filter out those in the excludedLabels.","type":"text"}]},{"type":"codeBlock","attrs":{"language":"json"},"content":[{"text":"{\n \"project_id\": ,\n \"template_id\": ,\n \"options\": {\n \"comments\": {\n \"closedComments\": true,\n \"excludedLabels\": [\"Open\"] // Comments with label 'Open' will be excluded from the report\n }\n }\n}\n\n// old method (will still work but will be phased out in future)\n{\n ...\n options: {\n \"excludedLabels\": [\"Open\"]\n }\n}","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Include Only Comments With Attachments","type":"text"}]},{"type":"paragraph","content":[{"text":"The following example will generate a report and filter out any comments that do not have attachments. If you want to also include the links to those attachments for users to download, you can do so using the ","type":"text"},{"text":"includeAttachmentLinks","type":"text","marks":[{"type":"strong"}]},{"text":" options. Note that this options can be used independently of one another.","type":"text"}]},{"type":"codeBlock","content":[{"text":"{\n {\n \"project_id\": ,\n \"template_id\": ,\n \"options\": {\n \"comments\": {\n \"withAttachmentsOnly\": // filter out comments without attachments\n \"includeAttachmentLinks\": // include attachment links in the report\n }\n }\n}","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Specifying Report Filename","type":"text"}]},{"type":"paragraph","content":[{"text":"By default, the corrections report that is generated will be saved to the Project Attachments using the ","type":"text"},{"text":"report title","type":"text","marks":[{"type":"strong"}]},{"text":" as the filename. Users can specify a ","type":"text"},{"text":"filename","type":"text","marks":[{"type":"strong"},{"type":"em"}]},{"text":" parameter in the options to choose the name of the file that is saved to the attachments.","type":"text"}]},{"type":"panel","attrs":{"panelType":"note"},"content":[{"type":"paragraph","content":[{"text":"All reports are saved as .pdf files so please do not include the extension in the parameter.","type":"text"}]}]},{"type":"codeBlock","content":[{"text":"{\n \"project_id\": ,\n \"template_id\": ,\n \"options\": {\n \"filename\": \"ChangedFilename\" // attachment will be saved as ChangedFilename.pdf\n }\n}","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"3. Finished!","type":"text"}]},{"type":"paragraph","content":[{"text":"If the report was successfully created you should see something similar to the following:","type":"text"}]},{"type":"codeBlock","content":[{"text":"{\n \"success\": true,\n \"message\": \"Attachment created and stored\",\n \"data\": {\n \"vendor_id\": null,\n \"id\": 38,\n \"project_id\": 9,\n \"filename\": \"Eric's report.pdf\",\n \"updatedAt\": \"2019-11-18T22:58:44.416Z\",\n \"createdAt\": \"2019-11-18T22:58:44.416Z\"\n }\n}","type":"text"}]},{"type":"paragraph","content":[{"text":"Users should then be able to check the attachments tab for that particular project and download the attachment that was created.","type":"text"}]},{"type":"paragraph"},{"type":"rule"},{"type":"heading","attrs":{"level":2},"content":[{"text":"Additional Report Options","type":"text"}]},{"type":"paragraph","content":[{"text":"Users can also now override sort order and included project fields through the report API like so:","type":"text"}]},{"type":"codeBlock","content":[{"text":"{\n \"project_id\": ,\n \"template_id\": ,\n \"options\": {\n \"sort\": [\"groupName\", \"category\", \"subCategory\"],\n \"includedProjectFields\": [\"occupancy\", \"buildingHeight\", \"submittal\"]\n }\n}","type":"text"}]},{"type":"paragraph","content":[{"text":"This will override what is currently in the specified template.","type":"text"}]},{"type":"paragraph","content":[{"text":"List of valid sort order field names","type":"text","marks":[{"type":"strong"}]},{"text":":","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"commentNumber","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"groupName","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"reviewType","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"category","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"reviewerName","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"List of valid project field names ","type":"text","marks":[{"type":"strong"}]},{"text":"(projectNumber and address included by default)","type":"text","marks":[{"type":"em"}]},{"text":":","type":"text","marks":[{"type":"strong"}]}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"projectName","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"contact","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"projectType","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"submittal","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"occupancy","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"constructionType","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"squareFootage","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"buildingHeight","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"applicationType","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"serviceArea","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"site","type":"text"}]}]}]},{"type":"paragraph"},{"type":"rule"},{"type":"paragraph","content":[{"text":"For additional information please refer to the swagger documentation at .eplansoftreview.com/api/core/ under ","type":"text","marks":[{"type":"em"}]},{"text":"Reports.","type":"text","marks":[{"type":"strong"},{"type":"em"}]}]}],"version":1}

Browser not supported