External Reports Gateway

The External Reports Gateway is designed to streamline the integration of External reporting tools with the IFS reporting ecosystem. This solution addresses the need for a secure, efficient, and scalable method to generate and store reports using external layout design tools, ensuring compliance with network policies and security guidelines.

Functionality Overview

When a print event is triggered from IFS Cloud Web, selecting an External Reports Gateway layout type, the IFS Reporting Hub asynchronously notifies the External reporting system via IFS Connect. The External reporting system then generates the report and saves the PDF back to IFS using a secure API endpoint. The file undergoes mandatory security scanning before being stored in the IFS File Storage Service. Notifications are sent to users regarding the status of their operations, ensuring transparency and security throughout the process.

Utilizing the External Reports Gateway

To use the External Reports Gateway, go to the Report Definitions page and select the desired report and add a new Layout with the type External Reports Gateway. The Layout name should include the .irg extension, and the Layout title can be a preferred value of your choice. Once you complete the new Layout, a new record will be added to the Layout Definitions and will be shown in the Print Dialog at the Order Report page.

Prerequisites

• The FNDTPI component needs to be active in the Solution set.
• External reporting service (REST) configured to accept requests.
• External reports gateway (.irg) layout entry in Report Definitions.
• External reports gateway configuration parameters need to be configured in IFS Cloud Web.
• Report Endpoint URL – (Mandatory)
• Test Endpoint URL – (Optional)
• API Key – (Mandatory)
• Scanning Timeout Period – (Optional)
• Log Retention Period – (Optional)

Configuring External Reports Gateway Settings

The External Reports Gateway Settings page outlines the necessary configuration options needed to trigger a report generation request towards the External reporting system.

This page provides the following configuration parameters for the administrator:

Parameter	Description
Report Endpoint URL	This parameter requires a valid HTTPS External Report generation endpoint URL. A POST request will be sent to trigger report generation.
Test Endpoint URL	This parameter can be used to test the connection status with the External Reporting system. GET request will be sent to the configured parameter value (can be tested through the Test Connection option). The URL should be a valid HTTPS URL.
API Key	This parameter requires a valid API Key to be provided, which will be encrypted upon storing. The API Key will be validated upon entering and re-entering. This API Key should be, - between 32 and 64 characters - can be alphanumeric characters and include dashes (-) - cannot contain any other special characters
Scanning Timeout Period	This parameter sets the scanning timeout period for files before uploading to the IFS File Storage Service (FSS). If it exceeds the parameter value, it will throw an error message. The default will be 30 minutes.
Log Retention Period	This parameter sets the cleanup age limit for the External Report Gateway Execution Log. The default will be 30 days.

• The IFS Connect Configurations action will display a dropdown menu with various configuration options. Selecting an option will take you to the respective configuration page, filtered to display settings related to the External Reports Gateway (No need to modify the IFS Connect Configurations).
• The Application Messages action will redirect to the Application Messages page, filtered to display messages related to the External Reports Gateway.
• More Information regarding IFS Connect Configuration and Application Messages can be found here.

IFS Connect Configurations

These configurations should be available upon activating the FNDTPI IFS component.

Configuration Type	Configuration Name
REST Sender	“EXTERNAL_REPORTING_REST_SENDER“
Routing Rule	“IFS External Reports Gateway Routing Rule - Asynchronous“
Routing Rule	“IFS External Reports Gateway Routing Rule - Synchronous“
Routing Address	“IFS External Reports Gateway Destination Address”
Message Queue	“EXTERNAL_REPORTING“ - (execution mode set to IN SEQUENCE by default)

Uploading SSL Certificate - if you are using a certificate not obtained from a Certificate Authority (CA) to configure the external reporting system, then it is required to import the certificate using the option on IFS Connect Routing Address page. More information on uploading SSL Certificate can be found here.

(You can navigate to IFS connect routing address - "IFS External Reports Gateway Destination Address" from External Report Gateway Settings page )

Report Generation Trigger Requests (via IFS Connect)

{
   "traceId": "7059c3c1-0f25-4b31-a7b9-d14f5d5000e6",
   "reportKey": "ALARM_REP",
   "dataKey": 27037,
   "layoutName": "abc.irg",
   "printJobKey": 26047,
   "language": "en",
   "numberFormatting": "en-US"
}

Above is a sample JSON payload of the POST request sent to the Report Endpoint URL. This payload contains the following information:

Payload Attribute	Description
traceId	This key represents the unique ID assigned to the external report print request.
reportKey	This key represents the Operational report ID.
dataKey	This key represents the result key.
layoutName	This key represents the layout used for the print job.
printJobKey	This key represents the print job ID.
language	This key represents the language selected for the print job.
numberFormatting	This key represents the locale information selected for the print job (date/number formatting).

Note

The Configured API key will be included in the above POST request as a request header and the external reporting service SHOULD validate the API key value upon receiving the request. 

Authorization Request Header format: "Authorization": ["Bearer <API Key>"]

Report Upload Requests

External reporting service needs to use the following Integration projection delivered with the FNDTPI component for report upload requests.

• OData Service/Projection:- ReportGatewayHandler.svc
• Action Name:- Upload

You need to fetch an access token from the IFS IAM before accessing IFS Cloud endpoints. More information on using access tokens can be found here.

You can use the following IAM Client, Service User and Permission Set delivered with the FNDTPI component to fetch access tokens using client credential authentication flow.

• IAM Client
• Client ID :- IFS_reporting_external
• Client Secret :- will be auto generated / can regenerate if needed
• Service User
• User Identity :- IFSFNDTPIINT
• Description :- IFS FNDTPI Integration Service User
• User Type :- Service User
• Permission Set
• Permission set name :- IFS_FNDTPIINT
• Permission set type :- IFS Managed
• Projections granted :- ReportGatewayHandler

Steps to upload the generated report/PDF file into IFS Cloud from External Reporting Service

1. Create a record inside the FndTempLobs entity set and retrieve the "OData-EntityID" and "ETag" response header values.

2. Request URL - {ifs_cloud_environment_url}/int/ifsapplications/projection/v1/ReportGatewayHandler.svc/FndTempLobs

3. Request Type - POST
4. Payload of the request:

{
 "CreatedByModule":"ReportGatewayHandler"
}

• POST Request Header:

Key	Value
Content-Type	application/json

1. Send the stream content (PDF file) into {{OData-EntityID}}/BlobData (You need to extract LobId from "OData-EntityId" header value retrieved from the previous step).

2. Request URL - {ifs_cloud_environment_url}/int/ifsapplications/projection/v1/ReportGatewayHandler.svc/FndTempLobs(LobId='<Extracted LobId>')/BlobData eg: {ifs_cloud_environment_url}/int/ifsapplications/projection/v1/ReportGatewayHandler.svc/FndTempLobs(LobId='42E3AE5C8E384872B77FB9671B29CE7A')/BlobData

3. Request Type - PUT
4. Payload of the request:

"Actual blob content/pdf file"

• PUT Request Headers:

Key	Value
Content-Type	application/octet-stream
If-Match	{{Extracted ETag header value}}

The ETag header value will be available as a response header in the POST request in Step 1.

1. Call the real Action (Upload) with the OData-EntityID retrieved earlier, in place of the parameter you want to have the real data content.

2. Request URL - {ifs_cloud_environment_url}/int/ifsapplications/projection/v1/ReportGatewayHandler.svc/Upload

3. Request Type - POST
4. Payload of the request:

{
   PrintJobId    : Print Job Id (identifier) relevant to external report print request.
   CorrelationId : Unique Id assigned to external report print request(traceId parameter value sent within trigger request). 
   ResultKey     : Result set identifier relevant to external report print request.
   PdfTempLobId  : Unique Id assigned when uploading external report output to FndTempLobs(Extracted LobId value).
}

Eg:

{
 "PrintJobId" : 25335
 "CorrelationId" : "36525181-4adb-4ec8-866d-d90a9998c7e1"
 "ResultKey" : 28379
 "PdfTempLobId" : "FE4AF981A0B944799708D36013B70DCE"
}

• POST request Headers will be same as the Step 1. if-match header should NOT be included for this request.

Key	Value
Content-Type	application/json

For more Information on “Large Parameters in Actions”.

External Reports Gateway Execution Log

The External Reports Gateway Execution Log facilitates the tracking of External Reports executions. It provides detailed information regarding:

Field	Description
Log Id	This field shows a Unique Log ID.
Print Job Id	This field shows the Unique Print Job ID given for each External Report Request.
Request Type	This field indicates External Report output upload requests with IRG-IN and sending POST requests and responses from the External Reporting service with IRG-OUT.
Timestamp	This field shows the timestamp of the log entry.
Text	This field includes the log messages on POST requests and upload requests.

• The Clear All action will clear all execution logs available.

• Scheduled database task would clear old execution logs which are older than the number of days configured in the Log Retention Period parameter.