SPF Reporting – Creating SPF Schema Graph and View Definitions

I don’t use the Schema Editor for schema changes to SPF; I hand-code the updates in XMLSpy. This is pretty straightforward when modelling the more common objects like Classes, Interfaces and Properties. But Graph and View definitions are a little trickier.

I deconstructed some existing Graph and View definitions in order to create some new ones manually; this blog shows what I learned. In this explanation I gloss over the usual stuff like relationships between the objects; it’s the syntax of the definition strings that I go into detail on. This is based on SPF 4.3.3.

To make a new Graph or View (or any Schema object), I just find one similar to the one I want to create, do an Export Data on it, expand all the relationships it has, copy the whole set of XML elements out to my text editor, wrap it in a <Container>…</Container> root element, then start changing each element to be what my new one needs. When done I load it with the Schema Import Wizard and test it.

DirectedGraphDefs

Think of a DirectedGraphDef as a set of related objects from a starting object. For example, starting from a transmittal object, a Graph that identifies all the files to be extracted to a ZIP file might identify the files found at the relationship path: Transmittal > Document Revision > Latest Document Version > Files, and also the files at: Transmittal > Files (those attached directly to the transmittal). A Graph might start from one object, or it might start from a collection or set of multiple objects. The Graph does not identify any specific properties of the objects it identifies; it merely gathers the objects up, and assigns names to them, so they can be referenced from other paths in the Graph, or ultimately from a ViewDef.

Start by defining the basic properties of the DirectedGraphDef like Name, Description, etc. Next define a relationship from this DirectedGraphDef to the InterfaceDef for the object it will “start” from. Use the Export Data XML of an existing example to see how to set this up and what type of relationship to create.

Now comes the fun part. 🙂

The property GraphDefn is the main property for a GraphDef. A typical value looks like this: (newlines added for readability at the commas, normally it is one continuous string)

+ITag/+ITag/,
TagDocument_12/DocumentVersions/+ITag,
SPFFileComposition_21/Files/DocumentVersions

It has the following syntax:

  • It is a comma-delimited list of strings
  • Each string has 3 components separated by forward slashes.

The components that are separated by slashes are, in order (these names are made up by me, so may not agree with what Intergraph’s Schema Editor calls them):

  • Unique ID (which is a RelDef or EdgeDef path)
  • Name
  • (optional) Start From Name

So each string between commas looks like this:

  • Unique ID/Name/Start From Name

Unique ID is either a relationship path in the form RelDef_12, or EDG_EdgeDef to refer to an EdgeDef already defined in your SPF schema. Where it ends, the objects at that end will be the “selected objects”.

Name is an English name given to the objects selected by the Unique ID path.

Start From Name is optional, if not specified then you still need the leading / slash character. It refers to a previously-defined Name value in a prior string in this Graph. If specified, it means the Unique ID “relationship hop” path will start from that set of objects, not the original Interface for the Graph.

So in this example:

  1. +ITag/+ITag/,
  2. TagDocument_12/DocumentVersions/+ITag,
  3. SPFFileComposition_21/Files/DocumentVersions
  • The bold +ITag on line 2 refers to the objects selected by the path on line 1 (which is the starting interface) – this is the typical ending for most strings that are “one hop” from the starting object. Hence the “TagDocument_12” relationship expansion starts from +ITag.
  • The italics DocumentVersions on line 3 refers to the objects selected on line 2, meaning the path continues from there. Hence the “SPFFileComposition_21” relationship expansion starts from the objects at the end of the “TagDocument_12” expansion (which were named “DocumentVersions”)
  • The first line has no “Start From Name” so it starts from the InterfaceDef related to the GraphDef. This could be a single object that has that interface, or it could be a collection of objects that have that interface. This depends how the Graph used.

ViewDefs

If Graphs gather up and assign names to the objects related to a given starting object, then ViewDefs identify the properties to be extracted from those objects, for use in a report, for example; and assigns names and categories to those properties for ease of reference.

ViewDefs can be used directly by users when they select File – New – Report. The initial list displayed is a list of ViewDefs they have access to through an access group (below).

Like a DirectedGraphDef , ViewDefs require a relationship to a starting interface. They also require a relationship to a Group to allow access to use them, like a Method.

ViewDefs also need a DirectedGraphDef. This is not a relationship, rather the name of the DirectedGraphDef is stored in a property value. Certain values in the property string ViewPropsDefn (discussed below)refer to the “Name” components in the Graph’s string.

The property ViewPropsDefn is the main definition of the ViewDef. A typical value looks like this: (newlines added for readability, normally it is one big string)

+ITag/IObject/Name/Name/Identification/1,
+ITag/IObject/Description/Description/Identification/2,
DocumentVersions/ISPFDocumentVersion/SPFIssueDate/Issue Date/Identification/3,
Files/ISPFBusinessFile/SPFLocalFileName/Local File Name/Vault Info/4

It has the following syntax:

  • It is a comma-delimited list of strings
  • Each string has 6 components separated by forward slashes.

Components of each string are:

  • Graph Edge Name
  • Interface
  • Property
  • Name
  • Category
  • Number

So each string between commas looks like this:

  • Graph Edge Name/Interface/Property/Name/Category/Number

Graph Edge Name refers to the Name component (middle part between two /slashes/) of one of the GraphDef strings. This selects the objects to read property values from.

Interface is the name of the interface on those objects to get read property values from.

Property is the name of the property to read values from on the selected objects.

Name is the display name given to those properties.

Category is a heading under which this Name will be grouped.

Number is a sequential number, must go up by 1 for each string. The highest vaule must also be put in the property LastLocalID.

So in this example ViewDef (assuming it has a relationship back to the example graphDef above):

  1. +ITag/IObject/Name/Name/Identification/1,
  2. +ITag/IObject/Description/Description/Identification/2,
  3. DocumentVersions/ISPFDocumentVersion/SPFIssueDate/Issue Date/Identification/3,
  4. Files/ISPFBusinessFile/SPFLocalFileName/Local File Name/Vault Info/4
  • Line 1 grabs the objects selected by the ITag interface, looks at their IObject interface and gets the Name property. It gives it the display name of “Name”, and puts it under a category of Identification.
  • Line 3 grabs the objects from Line 2 of the GraphDef (you will see it was named …/DocumentVersions/…), and gets the SPFIssueDate property from their ISPFDocumentVersion interfaces. It gives these values the display name “Issue Date” and puts it under the Identification category.
  • Line 4 grabs the objects selected by Line 3 of the GraphDef (named /Files/), gets their SPFLocalFileName property from the ISPFBusinessFile interface, and gives it the display name “Local File name” under the “Vault Info” category.

 

Those are the key tricky bits I found to Graph and View definitions in SPF. Now you can create a report that uses the View Definition.

Next I plan to blog on how to create an HTML transmittal report (ie. cover page) using XSLT using Graph and View defs like those above.

Please comment if you found this post useful.