Historic Reporting

Historic reporting uses a business function created in workbench and the REST API V2 functionality. It allows customers to audit revisions made by specified STEP user(s) for a specified time frame. For more information on REST API v2, refer to the Technical Documentation accessible at [system]/sdk or from the system Start Page.

Create a Business Function in Workbench

The information presented by the report is defined by a JavaScript business function that analyzes the revision and returns a string.

Important: In some cases, historic reporting can involve huge amounts of data due to traversing every object. To assure steady progress of the reporting, limit the analyzing business rule to local data (e.g., values and cross references).

Reporting on relationships outside of the current data object that belongs to the revision currently worked upon, and then requesting further information from those objects severely slows down progress, repeatedly seizes shared resources, and restricts other processes on the system. For example, it is not advisable to follow attribute links, cross references, parent associations, or children associations.

Use these steps to create a business function for historic reporting:

  1. Create a new JavaScript business function. For details, refer to the JavaScript Function Operation topic in the Business Rules documentation.

  2. Edit the JavaScript business function as follows:

    • For Input Parameters, on the 'Parameter name' field, add 'revision' to the text box.

    • For Input Parameters, on the 'Type' field, select 'Revision' from the dropdown.

    • For Return Type, verify the default setting of 'String.'

    • For JavaScript, add your JavaScript code.

      For example, the following code analyzes the revision to determine if a change was made and if a change is found, it returns a string to the report. When the function returns null, the revision is omitted from the report:

      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;

  3. Test the JavaScript.

  4. Save the business function and record the ID for use in REST API v2.

Generate a Report in REST API v2

From REST API v2, use the business function to generate a report as follows:

  1. Start the report with a POST operation — supply a user-defined name for the report in the {reportID} parameter:

    POST ​/reports​/historic-changes​/{reportID}

    For example: POST ​/reports​/historic-changes​/Aug23

    Supply the Query Params, including:

    • reportID = user-defined label for the report, prepended to the name parameter in the output

    • analyzerID = the ID of the business function

    • beginning = first date of revision for the report

    • end = last date of revision for the report

    • context = ID of the context for the report

    • workspace = Main

    • userID = STEP user ID on the revision for the report; for multiple user IDs, refer to the REST API v2 documentation

    This operation starts a historic-changes reporting BGP and reports the BGP ID for use in a GET operation below. The BGP collects revisions modified by the specified user(s) within the specified time frame and the business function evaluates them individually.

    Note: The report is created asynchronously. Depending on parameters for the POST operation, report generation can take some time.

  2. Determine if the BGP is complete.

    Supply the BGP ID in the {id} parameter of the following GET operation: 

    GET ​/background-processes/{id}/attachments

    For example: GET ​/background-processes/BGP_4479586/attachments

    The array remains empty until the report is generated.

    When the report is complete, the array displays the following relevant information:

    • "originalAttachmentId" = "RESULT" when the BGP is complete

    • "id" = copy this ID and paste it into the following GET operation to retrieve the report contents

    • "name" = {user-supplied-reportID}_{system-generated-event-processor-ID}

  3. Retrieve the report contents. (The report is not available in workbench.)

    Supply the BGP ID for the {id} parameter and supply the "id" reported in the previous array for the {attachmentId} parameter of the following GET operation:

    GET ​/background-processes/{id}/attachments/{attachmentId}/content

    For example: GET ​/background-processes/BGP_4479586/attachments/233fcf65-0b77-4f1c-b5ae-3839c12d847a/content

The report contents rows display as follows:

2023-08-09 15:28:52 USERJ step://product?id=40993640 0.10 "Complete approval": <the String returned from the business function>
2023-08-09 15:28:52 USERJ step://product?id=40993640 0.10 "Complete approval": <the String returned from business function>
2023-08-11 07:58:08 USERJ step://product?id=40993691 0.1 : <the String returned from business function>
2023-08-11 11:00:00 USERJ step://product?id=40993640 0.11 "Auto Generated": <the String returned from business function>
2023-08-11 11:00:12 USERJ step://product?id=40993640 0.12 "Complete approval": <the String returned from business function>

Remove the Report in REST API v2

Generating historic reporting creates two event processors on the System Setup tab in workbench. These event processors are saved below the Historic Reporting setup group, in a node with the same name as the business function. The following event processor objects must be removed via a POST operation before you can perform additional historic reporting:

  • {reportID}_RA — uses the Historic Data Analyzer processing plugin

  • {reportID}_RG — uses the Historic Data Generator processing plugin

    For more information on processing plugins, refer to the Processing Plugins topic in the System Setup documentation.

Important: The generated report is deleted when the automatically created event processors are removed.

Historic Reporting Clean-up

From REST API v2, run the clean-up.

Supply the user-defined name for the report in the {reportID} parameter of the following POST operation:

 POST /reports/historic-changes/{reportID}/clean-up

For example: POST /reports/historic-changes/Aug23/clean-up

The event processors are removed from the System Setup tab in workbench.