Historic Reporting

Historic reporting capabilities can be done using a combination of platform and REST API V2 functionality. This kind of reporting allows customers to audit who / what made changes and how widespread the changes are. In some cases, the reporting for this kind of scenario involves huge amounts of data due to traversing every object, restrained by revision timestamp or user ID.

This kind of reporting can be done via the REST API V2 using the API post requests described below:

  1. OperationPOST ​/reports​/historic-changes​/{reportID}

    This operation starts a historic-changes reporting process that collects revisions modified by the specified user(s) within the specified time span and feeds them one at a time to the specified business function. The output from the business function is generated and written to a report available as an attachment to the background process identified in the response.

    When a report is started, multiple configuration objects are created (two setup groups and two event processors) in System Setup.

    • Setup Group: Historic Reporting

    • Setup Group: <Name of the business function>

    • Event Processor: IdOfReport_RA (uses the Historic Data Analyzer processor)

    • Event Processor: IdOfReport_RG (uses the Historic Data Generator processor)

      Users can inspect the result of the execution report and save it, if accessing via the API.

      By default, events are triggered on the Approved workspace. Derived event functionality is available for triggering events prior to approval, as defined in the Derived Events topic of the System Setup documentation here.

  2. OperationPOST /reports/historic-changes/{reportID}/clean-up

    This operation can be called for completed reports and will delete the configuration objects that were created behind the scenes (described above) that are specific to that report. Once this endpoint has been called, it is no longer possible to retrieve the generated report.

    Along with the API requests, a business function needs to be written. The function takes a revision in and either returns nothing or returns the information requested by the code.

    Important: To assure steady progress of the reporting, it is significant to restrict the analyzing business rule to local data (e.g., values and cross references). Following attribute links or cross references, parent or children associations, or other relations outside the current data object belonging to the revision currently worked upon, and then requesting further information from these objects, will severely slow down progress and repeatedly seize shared resources, holding back other processes on the system.

    The business function drives the report. An example of code that can be used is shown below:

    var current = revision.getNode().getValue(“founded").getSimpleValue();
    if ("JAN 3 1794".equals(current)) {
      var predecessor = revision.getPredecessor();
      if (predecessor == null)
        return null; // initial value, this is not what you are looking for
      else {
        var formerValue = predecessor.getNode().getValue(”founded").getSimpleValue();
        if (“JAN 3 1794".equals(formerValue))
          return null; // same before, do not report
        else
          return "found JAN 3 1794 changed from " + formerValue;
      }
    } else
      return null;
    

    Work on this solution continues and more details will be provided in future releases. To reiterate the 'Important' message above, users should note that the stricter the parameters for this reporting, the better the performance.

For detailed information about the new POST requests, refer to the Swagger and OpenAPI 3.0 documentation available via the STEP API Documentation page on systems with the STEP Web Services API commercial license activated.

For information regarding Business Functions, refer to the Business Functions section in the Business Rules documentation here. For more information on Processing Plugins, refer to the System SetupEvent Processors documentation here.