Guides

Enqueue a Job to Generate Reports

Suggest Edits

Using the access token obtained, enqueue a report generation job via the Reporting API.

The job will be picked up by the CGiX Hangfire background processing service which will generate the reports based on the input parameters of the API request.

1. Creating the Request

Create a new request in Postman as follows:

  1. Change the HTTP verb from GET to POST.
  2. Click on the Authorization tab and set the access token as the Bearer Token.
Authorization tab in Postman

Authorization tab in Postman

  1. Specify the URL to the report/{companyId}/{clientId}/calculateandgeneratereports API endpoint, where the companyId and clientId are passed in the URL of the request. For example, https://fslpresales.fslcgix-uat.co.uk/FSLPresales_WebAPI/api/report/FSL/100200400/calculateandgeneratereports, where companyId = "FSL" and clientId = "100200400".

🚧

URL Encoding

The URL parameters companyId and clientId should be URL encoded.

  1. Click on the Body tab and then the raw option.
  2. Set the content type to JSON; the dropdown is found to the right of the raw option.
  3. Paste in your JSON as the request body. An example is provided below.
{
  "calculationExecutionDetails": {
    "calculationToDate": "2021-07-20T14:22:00.000Z"
  },
  "reports": 
  [
    {
      "reportType": "CapitalGainsTax",
      "parameters": [
        {
          "name": "startdate",
          "value": "2019-04-06T00:00:00.000Z"
        },
        {
          "name": "enddate",
          "value": "2020-04-05T00:00:00.000Z"
        },
        {
          "name": "sortbyaccount",
          "value": false
        }
      ]
    },
    {
      "reportType": "ClientIncome",
      "parameters": [
        {
          "name": "startdate",
          "value": "2019-04-06T00:00:00.000Z"
        },
        {
          "name": "enddate",
          "value": "2020-04-05T00:00:00.000Z"
        }
      ]
    },
    {
      "reportType": "NotionalDisposal",
      "parameters": [        
      ]
    }    
  ]
}

The JSON object contains two properties:

Property NameDescription
calculationExecutionDetailsAn object that contains a calculationToDate property whose value is a date that is used to update the client’s “Calculate-to-date”. The client is recalculated to this date before the Notional Disposal report is generated. Finally, the “Calculate to-date” is reset by removing this date from the client before triggering the client for recalculation again.
reportsAn array of objects specifying the reports to generate.

Each report object has two properties:

Property NameDescription
reportTypeMust be one of the following string values: "CapitalGainsTax", "ClientIncome" or "NotionalDisposal".
parametersAn array of objects specifying parameter name-value pairs specific to the report type.

The three report types supported require different parameters as described below:

Report TypeParameter NameParameter Value
CapitalGainsTaxstartdateThe report tax year start date in ISO 8601 format i.e., "2019-04-06T00:00:00.000Z".
enddateThe report tax year end date in ISO 8601 format i.e., "2020-04-05T00:00:00.000Z".
sortbyaccountBoolean value that orders the report data by account or security.
true = Order by account
false = Order by security
CapitalGainsTaxstartdateThe report tax year start date in ISO 8601 format i.e., "2019-04-06T00:00:00.000Z".
enddateThe report tax year end date in ISO 8601 format i.e., "2020-04-05T00:00:00.000Z".

The NotionalDisposal report type is generated from the client's holding positions. No parameters are required. Specify an empty array for the parameters property.

🚧

Report Types

The reports array must contain at least one report object and duplicate report types are not permitted.

2. Sending the Request

Click the Send button to send the prepared request.

Response received in Postman

Request and response in Postman

3. The Response Body

When successful, the API response will return the following information in JSON format:

Property NameDescription
jobIdUnique numeric job id for the report generation job.
reportsAn array of objects specifying the reports being generated.
reportsDeceasedWhen the client is deceased, returns an array of objects specifying the reports being generated for the deceased client. The reports for the probate client are returned via the reports property.
When the client is not deceased, reportsDeceased returns null.

Each report object has two properties:

Property NameDescription
reportTypeWill be one of the following string values: "CapitalGainsTax", "ClientIncome" or "NotionalDisposal".
guidUnique string identifier for the report being generated. This is used later on to fetch the generated report.

Example response:

{
    "jobId": 12780,
    "reports": [
        {
            "reportType": "CapitalGainsTax",
            "guid": "4ff73e73-8cd1-4ace-96f5-70e44127ff2e"
        },
        {
            "reportType": "ClientIncome",
            "guid": "83d53d25-49d1-4c5c-bba9-e1e52bc0b28e"
        },
        {
            "reportType": "NotionalDisposal",
            "guid": "a0c1cde7-9979-48d5-bebc-ef3b5a361546"
        }
    ],
    "reportsDeceased": null
}

Example response when the client is deceased, where the reportsDeceased property is populated:

{
    "jobId": 21950,
    "reports": [
        {
            "reportType": "CapitalGainsTax",
            "guid": "d73b1354-eb53-4ec1-b822-cf086103340d"
        },
        {
            "reportType": "ClientIncome",
            "guid": "5a42a1cf-240b-49e6-9a3c-80236aff6161"
        },
        {
            "reportType": "NotionalDisposal",
            "guid": "dc0261ac-8e50-4f73-a256-1dab7d913fe1"
        }
    ],
    "reportsDeceased": [
        {
            "reportType": "CapitalGainsTax",
            "guid": "f14a6d51-dfe7-402d-97d8-1c6146406fec"
        },
        {
            "reportType": "ClientIncome",
            "guid": "ad98f23c-3d67-4a07-ad07-3ad938565e5d"
        },
        {
            "reportType": "NotionalDisposal",
            "guid": "4eb83501-542d-4a01-92b6-5b8430d8172e"
        }
    ]
}

Updated about 1 year ago