Business Optix Limited Report Builder s Guide Generic reporting on the Business Optix library
CONTENTS Contents 2 Business Optix Reporting... 3 Database Schema... 4 Model table... 5 ModelUrl table... 5 Component table... 5 Property table... 5 Lookup table... 6 Reference table... 6 Operations table... 6 Comment table... 6 Ratings table... 7 TrainingAnswers table... 7 FolderAccess table... 7 Users table... 7 Roles table... 7 UserRole table... 7 Standard reports... 8 The web service API... 9 XML data retrieval... 9 CSV data retrieval... 9 Chart generation... 9 Example query string... 10 9 May 2012 Page 2 of 10
BUSINESS OPTIX REPORTING The Business Optix library service provides a generic reporting mechanism, based on a relational database. This document provides all the detail required to hand-build canned reports. 9 May 2012 Page 3 of 10
DATABASE SCHEMA The foundation of the reporting capability is the Business Optix library database. The following diagram shows the database schema: Other tables may be present in some libraries, depending on the features installed for that library. This document concentrates on the core reporting tables. The following sections describe the use, content and linkages between each table. With the exception of the Operations table (which holds a record of each read, write and delete of a model), all tables hold information on the most recent version of each model. 9 May 2012 Page 4 of 10
Model table The Model table is used to access each model in the library. It holds a row for each model, identified by its (GUID) id. It has data columns for each core (invariant) model property (such as type, name, version owner, author, description etc.). Other model properties are held in the Property, Lookup and Reference tables. When a Model is deleted, all associated Component, Property, Lookup, Reference and ModelUrl rows are also deleted. ModelUrl table The same model may be stored in two or more different locations in a library (e.g. Shared and Stakeholders). This table maps each model to each known URL. It holds a row for each model URL. It has data columns for the model ID along with columns providing the user name and date for checked out models. Component table The Component table is used to access any component of any model. It holds a row for each component, identified by its (GUID) id. It has data columns for the component s name and type. Other component properties are held in the Property, Lookup and Reference tables. Each component identifies the model to which it belongs, its ordinal position in the table of contents, and optionally: a parent component of which it is a nested part (for example, an activity in an embedded sub-process will have the embedded sub-process activity as its parent) the source and target nodes of a link component the lane to which a node component belongs Property table The Property table is used to hold data values for each component, without requiring schema changes when new properties are defined in any stencil. It holds a row for each component property other than those used to link to components (lookup and lookups properties) or other resources (filename and reference properties), identified by the combination of the component (GUID) id and the (stencil) property id. It has data columns for the property s name, type and value. Each property identifies both the component and the model to which it belongs. 9 May 2012 Page 5 of 10
Lookup table The Lookup table is used to hold intra-component references (both inter- and intra-model), to allow bidirectional navigation (e.g. find all deliverables produced or consumed by a given process, and conversely find all processes which produce or consume a given deliverable). It holds a row for each intra-component reference (as defined by single value lookup and multi-value lookups properties), identified by the combination of the referencing component (GUID) id, the (stencil) property id, and the id of the referenced component. It has data columns for the lookup property s name and type. Each lookup identifies both the component and the model to which it belongs. Reference table The Reference table is used to hold non-component URL (or URI) links, to allow bi-directional navigation (e.g. find all documents referenced by a given process, and conversely find all processes which reference a given document). It holds a row for each link (as defined by single value filename and multi-value reference properties), identified by the combination of the referencing component (GUID) id, the (stencil) property id, and the reference URL (or URI). It has data columns for the reference property s name, the reference type, and the (user-provided) label. Each reference identifies both the component and the model to which it belongs. Operations table The Operations table is used to log all Author activity. It holds a row for each Author operation (read, write or delete) performed on each model, identified by an (automatically generated) non-natural id. It has data columns for the model URL, user (login ID), operation (GET, PUT or DELETE), whether a GET or PUT set or cleared a lock, the operation timestamp, the client that performed the operation (Author version or browser name and version) and whether the client is a browser. Comment table The Comment table is used to store any comments added to HTML documentation in the library. It holds a row for each comment added, identified by the timestamp, model ID and user who added the comment. It has data columns for the component that the comment refers to, the comment added and the URL used to make the comment. 9 May 2012 Page 6 of 10
Ratings table The Ratings table is used to store per user data relating to a model. It holds a row for each model and user, identified by the model ID and user. It has data columns for self assessment scores, user rating of the model and notification settings. TrainingAnswers table The TrainingAnswers table is used to store individual answers to self assessment questions. It holds a row for each user s answer to questions in each model, identified by the model ID, user, question ID and answer ID. It has data columns for the user s answer and whether the answer was correct. FolderAccess table The FolderAccess table is used to define which URLs may only be accessed by certain user communities. It holds a row for each restricted URL and the community that has access to the URL. It has a data column defining whether members of the community have read/write access or read-only access to the URL. Users table The Users table is used to store information about each registered user of the library. It holds a row for each registered user, identified by a GUID id. It has data columns for the user s login name, first name, last name, email address and the user s license. In an SSO environment, these are the only details stored about the registered user. In a non-sso environment, the user will also have an Active Directory account with the same login name, where their password is stored. Roles table The Roles table is used to define user communities set up in the library. It holds a row for each user community, defined by a GUID id. It has a data column for the community s name. UserRole table The UserRole table is used to define which users are members of which communities. It holds a row for each member of each community, defined by the user and community GUID ids. 9 May 2012 Page 7 of 10
STANDARD REPORTS A standard installation of the version 5 library includes a Reports folder that should be visible when logging in via the Business Optix Author application or via the web. If this folder is not present in your library then contact Business Optix support. These standard reports can be used as a basis for your own reports. The reports in this folder are either Business Optix report models or HTML files. Report models are the simplest way to generate reports. Tables can be built that display a row for each component in a model, with columns displaying model and component properties. Report builders with a knowledge of SQL can specify the raw SQL used to populate a table. SQL must be used when specifying the contents of charts. HTML reports give the most flexibility but require knowledge of SQL, HTML and JavaScript. They use the data retrieval API via AJAX to populate tables. The standard reports include many examples of populating tables using XML data retrieval. The JavaScript file reports v5.0.js includes helper functions for retrieving data and populating HTML tables and dropdowns. Charts are generated by the library and returned as images displayed in the HTML. 9 May 2012 Page 8 of 10
THE WEB SERVICE API HTML reports are built using the library s data retrieval web service API. Queries are made against the database using http/https GETs typically, but not necessarily, using AJAX against a URL of the form (library URL)?data=(query string) where (library URL) is the URL of the library to be queried for example https://businessoptixhosted.com/company_name/library http://corporate-domain/library and (query string) is the content of the appropriate SQL SELECT, omitting the initial SELECT of the query. XML data retrieval The default format for data returned by the data retrieval API is XML. Example output is shown below. <?xml version="1.0" encoding="utf-8"?> <resultset><result language="en-gb" status="" security="" modified="7/6/2011 10:44:22 AM" created="7/6/2011 10:43:54 AM" author="user" owner="" issued="" version="0.1" name="test Process" type="process" url="my Work/User/Test Process.xbp" id="30bc975d-b82b-4089-9e5e-c56ecccc111f"/></resultset> The top level element is called resultset and each row of the dataset is returned in a result element. Attributes are named based on the column names in the result set. CSV data retrieval Data can also be returned as CSV. This can be useful if the end user would like to view data in Excel for instance. The AllModels.html report has an example link that opens the CSV output in Excel (or whatever viewer the user has configured for CSV files). To return data in CSV format, the query string outputtype=csv should be appended to the URL request. An optional parameter can also be added to the query string to omit a header row for the CSV output. This query string is csvheader=false. Chart generation Charts can be generated by the library and returned as images which can be inserted into HTML reports. An example chart can be seen in the UserActivity.html report. The basic form of the URL required to generate a chart is <library URL>?chart=<SQL query string>. The SQL query string should omit the initial SELECT of the query. The first column of the returned data will be used to build the x-axis of the chart, the second column will be used to build the y-axis. Optional parameters that can be passed to the chart URL are as follows. If the parameter is not provided then the default value will be used. 9 May 2012 Page 9 of 10
Query string Description Default value height The height in pixels of the generated chart 400 width The width in pixels of the generated chart 600 type The type of chart, either column, bar or pie column xinterval The interval between labels on the x-axis 1 xtitle ytitle drawstyle showvalue labelformat The title to add to the x-axis The title to add to the y-axis When type is bar, specifies how the bars will be displayed. Possible values are Cylinder, Emboss, LightToDark, Wedge, Default When included in the query string, shows the value of the data point as a label If showvalue has been specified, defines how the label will be formatted Default Example query string This section provides an example, with explanations, of query strings. One (simple) measure of model complexity is the number of components it contains. To list the number of components of each model in the library, with the model containing the most components first: Model.url AS URL, COUNT(*) AS Complexity FROM Model, Component WHERE Component.modelId=Model.id GROUP BY URL ORDER BY Complexity DESC the (URL and Complexity) columns to return the two tables in which this information is held joined by matching model id grouped by URL and ordered by descending Complexity 9 May 2012 Page 10 of 10