- SECTIONS
The Vermilion API, enables users to programmatically access FactSet's Vermilion Reporting Suite (VRS) and seamlessly integrate into customer's 3rd party upstream and downstream applications. The API is referred to as two key product initiatives, the REST API and the SCIM API.
REST API
Leveraging the API's ease of operability and integration customers can utilise the following information from the application: Data, Reports, Report Instance and Entities
- Through the REST API, users can optimise their data processes by integrating with the Get Data service to retrieve a list of all data sources as well as the data they contain creating a standardised list of data sets for customer integration and use.
- Reporting delivery workflows can be streamlined by integrating with the Get Report service and the Report Retrieval service. These endpoints can enable customers to submit and cancel report generation requests on the VRS system for the specified report and its parameters. The request will return a report generation request id (the report instance id) which will be used to identify the generation request. The status of a report as to whether it is waiting, in progress, completed etc. can be utilized by systems to validate SLA’s. Once the report is completed, the API can be used to retrieve generated reports ready for distribution or storage.
- Entity models can be reviewed via the Get Entities service. This function will return a list of the entity values for the specified entity. The list of entity values returned will contain the entity key and description and can also provide a full list of all entity fields with their values. Combining these series of endpoints provides an extremely powerful set of tools for our customers to automate their systems.
SCIM API
Likewise the SCIM API can be utilised by customers to automate provision and management of their users and roles (groups). This API is using the System for Cross-domain Identity Management (SCIM) 2.0 protocol. More details on SCIM can be found on https://scim.cloud/
The System for Cross-domain Identity Management (SCIM) specification is designed to make managing user identities in cloud-based applications and services easier. The specification suite seeks to build upon experience with existing schemas and deployments, placing specific emphasis on simplicity of development and integration, while applying existing authentication, authorisation, and privacy models. Its intent is to reduce the cost and complexity of user management operations by providing a common user schema and extension model, as well as binding documents to provide patterns for exchanging this schema using standard protocols. In essence: make it fast, less expensive and easy to move users in to, out of, and around the cloud.
SCIM 2.0 is built on an object model where a Resource is the common denominator and all SCIM objects are derived from it. For manipulation of resources, SCIM provides a REST API with a rich but simple set of operations, which support everything from patching a specific attribute on a specific user to doing large bulk updates.
Please note:
- A full audit trail history is maintained with the Vermilion Reporting Suite which also details what instructions were sent via the Vermilion API for REST and SCIM versus activity which took place in the user interface.
- All aspects of this spec for both the REST and SCIM are provided in the attached document entitled VRS API Developers Manual.
- Updates to the Vermilion API for REST and SCIM happen on a frequent basis, therefore please refer to the latest Release Notes for the most up to date list of changes.
Should you require any further information, please contact the Vermilion Support team via Issue Tracker/RPD.
import time # For delay/timer
from datetime import datetime
from pathlib import Path
from fds.sdk.Vermilion import ApiClient, Configuration
from fds.sdk.Vermilion.api.report_instance_api import (
ReportInstanceApi,
ReportGenerationRequestBody
)
from fds.sdk.Vermilion.model.report_generation_request import ReportGenerationRequest
from fds.sdk.Vermilion.model.entity_selection import EntitySelection
conf = Configuration(
username="xxxxxxxxxxxxx",
password="xxxxxxxxxxxxx",
host="xxxxxxxxxxxxx",
# verify_ssl=False
)
# ----- This code snippet demonstrates how to run a VRS report and download the generated report file -----
#
def vrsRunReport():
# conf.debug=True
api_client = ApiClient(conf)
vrs_env = {"vrs_tenant": "XXXXXXXXX"}
# ----- Load report to run -----
# This will load:
# report_code e.g. XX_REP0RT
# output_format e.g. PDF
# selections e.g. {"XX_FUND": {"key": "BIIEX"},"SYSTEM_DATE": {"key": "31 January 2023 00:00:00"}}
reportRequestBody = ReportGenerationRequestBody(
vrs={
"1": ReportGenerationRequest(
report="XX_REP0RT",
output_format="PDF",
tenancy=vrs_env["vrs_tenant"],
entity_selection={
"SYSTEM_DATE": EntitySelection(key="31 October 2023 00:00:00")
},
)
}
)
try:
report_generation = ReportInstanceApi(api_client)
# ----- Start the generation -----
reportGenerationResponse = (
report_generation.start_report_generation_with_http_info(
report_generation_request_body=reportRequestBody
)
)
if reportGenerationResponse[1] != 202:
vrs_report_instanceID = 0
return
else:
vrs_report_instanceID = reportGenerationResponse[0].data.report_instance_id
# ----- Wait for the report to finish -----
logOutput(f"Generating instance {str(vrs_report_instanceID)}")
stillGenerating = True
while stillGenerating:
reportInstance = report_generation.get_report_instance_by_id_with_http_info(
str(vrs_report_instanceID),
vrs_env["vrs_tenant"],
_check_return_type=False,
)
if reportInstance[1] != 200:
logOutput(
"ReportInstance error: " + str(reportInstance[0]), logType="E"
)
instanceData = []
stillGenerating = False
return
else:
instanceData = reportInstance[0]
vrs_report_internalName = instanceData.data["reportName"]
vrs_report_status = instanceData.data["reportRevision"]["reportStatus"]
percentageComplete = instanceData.data["reportRevision"][
"percentageComplete"
]
logOutput(
"ReportInstance percentageComplete : "
+ str(percentageComplete)
+ ", Report Status : "
+ vrs_report_status
)
if vrs_report_status == "ABORTED":
logOutput(
"ReportInstance ABORTED: " + str(reportInstance[0]), logType="E"
)
stillGenerating = False
return
else:
if percentageComplete == None or percentageComplete < 100:
logOutput("Waiting for: 5 seconds")
time.sleep(5.0) ## pause 5s before trying again
else:
stillGenerating = False
# ----- Download the generated report and save locally -----
logOutput("Generated reportFileName : " + str(vrs_report_internalName))
reportData = report_generation.download_report_file_with_http_info(
vrs_env["vrs_tenant"],
str(vrs_report_instanceID),
vrs_report_internalName,
_preload_content=False,
)
output_result(vrs_report_internalName, reportData.read())
except Exception as ex:
logOutput("Errors during report generation progress: " + str(ex), logType="E")
return
def output_result(reportFileName, result):
filename = Path(f"{reportFileName}")
print(f"Writing output to {filename}")
filename.write_bytes(result)
def logOutput(message, logType="I"):
if logType == "W":
prefix = "WARN "
elif logType == "E":
prefix = "ERROR "
else:
prefix = "INFO "
now = datetime.now()
timestamp = now.strftime("%Y-%m-%d %H:%M:%S")
log_entry = f"{timestamp}: {prefix+message}\n"
print(log_entry)
# ----- Command line parameters ------
# python RunReport.py
#
def main():
vrsRunReport()
if __name__ == "__main__":
main()
v1
Summary
- v1.0.0 - Released on 01/05/2024
Functionality Additions
- No changes
Changes
- No changes
Bug Fixes
- Improved API documentation.[v1.0.0]