Appendix: Using the Report Attachment API

C Appendix: Using the Report Attachment API

The Brand Compliance Reports module provides a suite of standard reports with the facility for building new reports using the Oracle BI Publisher Template Builder plug-in for Word. Reports are scheduled in the Report Scheduler area where the recipients are assigned, along with whether the report is a single or recurring run, and the type of output (PDF, Excel, RTF, or HTML). When the report has been generated, it is stored as a file attachment in the Report Outputs area, within a hierarchical folder structure.

The Report Attachment API provides a means of automatically retrieving the report output attachments from the Report Outputs area, for taking the data into an external system for further analysis or processing.

When a report is generated, the recipients are notified by an email which contains a link to the report. An external system can be defined as a recipient. The External System record in the Brand Compliance Admin area can have an email address assigned, making it available for selection as the recipient of a report. The email sent to the external system contains a link to the report along with a link to the actual attachment file; the Report Attachment API can then be used to retrieve the attachment using this link.

The data returned by the API is a Base64 encoded text string which must then be processed by a Base64 decoder to convert it to the actual report file.

The following diagram describes the stages of the process for using the Report Attachment API to retrieve a report output.

Figure C-1 Process Flow for Using the Report Attachment API

This shows process flow for the Report Attachment API.

To access the Report Attachment API, the external system must be registered in Brand Compliance as an External System with the ATTACHMENT service, the REPORT_ATTACHMENT_GET endpoint, and an email address assigned.
When a report is scheduled, the external system is selected as a recipient.

When the report runs, if the recipient is an external system, an email is sent containing a link to the report output attachment (may be more than one if multiple formats have been selected).

In order to prevent the URI to the Attachment record being predictable, a 32-character non-sequential globalId key is used.

The template of the REPORTNOTIFICATION email may be configured in the Brand Compliance Admin area; the default content is:

Subject:	Report [Report Name] is ready to view
Body:	The report [Report Name] has been created.
	Use the following link(s) to retrieve the attachment data from the attachment API.
	File name: [File Name].[File Type] [Link to Report Attachments API] File name: [File Name] File Type: [File Type] [Link to Report Attachments API]

The external system initiates the call to the Report Attachment API. This may be triggered automatically on receipt of the email, or could be triggered by another event, by a scheduled job, or by a manual user action.
The external system processes the returned messages and report attachment data according to its intended purpose. The data must first be decoded from Base64 encoding.

Response Example:

<ns1:attachmentFullDTO
  xmlns:ns1="http://www.micros.com/creations/core/domain/dto/v1p0/full"
  xmlns:ns2="http://www.micros.com/creations/core/domain/dto/v1p0/simple">
    <ns1:attachedBy>
      <ns2:code>oau</ns2:code>
      <ns2:disabled>false</ns2:disabled>
      <ns2:externalAuthenticationUser>false</ns2:externalAuthenticationUser>
      <ns2:timeZone>Europe/London</ns2:timeZone>
      <ns2:userType>RETAILER</ns2:userType>
      <ns2:id>22</ns2:id>
   </ns1:attachedBy>
   <ns1:attachedOn>2018-06-28T10:20:27.000+01:00</ns1:attachedOn>
   <ns1:dataLength>3786</ns1:dataLength>
   <ns1:fileName>RT1.pdf</ns1:fileName>
   <ns1:localeData>
      <ns1:description><![CDATA[Test]]></ns1:description>
      <ns1:id>1190</ns1:id>
   </ns1:localeData>
   <ns1:id>1190</ns1:id>
   <ns1:ownerClass>com.micros.creations.core.domain.ReportResult</ns1:ownerClass>
   <ns1:ownerId>156</ns1:ownerId>
   <ns1:data>JVBERi0xLjYNCjUgMCBvYmoNCjw8DQovVHlwZSAvUGFnZQ0KL1Bhc...</ns1:data>
</ns1:attachmentFullDTO>

Note:

It is the responsibility of the retailer/portal owner to build an application to call the Report Attachment API and handle the returned messages and data, including any further processing of the data or interfaces with external systems.

For portals that use the Enhanced Access Control (EAC) level of permissions, the retrieval of reports as attachments through the API does not apply EAC area permissions filtering (as is the case for all other Brand Compliance APIs).