API Enhancements and Updates

Summary

Information applicable to the enhancements / deprecation outlined below is available in the API documentation at [system]/sdk or access the Stibo Systems Enterprise Platform (STEP) API Documentation from the Start Page.

Details

GraphQL introduction of a 'Path' field for classifications, entities, and products

Introduced for the Classification, Entity, and Product types are path fields that give access to ancestor nodes in the individual hierarchies.

Schema-wise, refer to this example:

type Classification {
  ...  
  path: [Classification]!
  ...
}

type Entity {
  ...  
  path: [Entity]!
  ...
}

type Product {
  ...  
  path: [Product]!
  ...
}

Each array needs to be populated with the nodes from the hierarchy root node (or the top most node that the user has privileges to view) down to the current node.

Data Issues Reports now available in GraphQL API

It is now possible to retrieve Data Issues Reports produced by business rules when evaluating conditions and executing actions, both via the evaluateCondition query and the executeAction and triggerWorkflowEvent mutations.

API extended to include access to Commercial Lists

Functionality is now available for accessing terms from the scripting and extension API. Specifically the following interfaces, classes, and methods have been exposed:

Interface / Class / Method	Description
TermsListHome	Home interface for terms list
TermsListHome.getTermsListByID(String id): TermsList	Gets terms list with supplied ID
HasTerms	Interface implemented by types that can have associated terms
HasTerms.queryTerms (TermsList termsList):query<TermsList.Term>	Retrieve the terms associated with this node
TermsList	A terms list
TermsList.Term	Data for an individual term
TermsList.Term.getValue(): String	Get the term value
TermsList.Term.getUnit(): Unit	Get the term unit or null if none exists
TermsList.Term.getStartDate(): Date	Get the term start date or null if none exists
TermsList.Term.getEndDate(): Date	Get the term end date or null if none exists
TermsList.Term.getMaxQuantity(): int	Get the maximum quantity of the term or -1 if undefined
TermsList.Term.getMinQuantity(): int	Get the minimum quantity of the term

Additional information is also available in the Scripting API section of the STEP API Documentation available at [system]/sdk or accessible from the system Start Page. Also, a Change History link is available in that same section, providing a complete list of all added / updated elements in the Scripting API from the 10.0 to 10.1 release.

New historic data reporting capabilities

More robust historic reporting capabilities are now available and driven by a combination of platform functionality as well as 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.

Two new API post requests are available as described below:

Operation: POST /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 new Historic Data Analyzer processor)
Event Processor: IdOfReport_RG (uses the new Historic Data Generator processor)

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

Operation: POST /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.

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. Users should note that the stricter the parameters for this reporting, the better the performance.

Important: In order 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.

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.

New option for Extension API component deployment

It is now possible to upload packaged extensions to the Stibo Systems' updates server https://updates.stibosystems.com via SPOT. With this, extension components no longer have to be moved manually to the servers on which they are to be deployed but can, like other software components, be fetched from updates. For more information, refer to the STEP Extension API Guide available via the STEP API documentation page.