To aid with formatting, transforming, and using the yaml specification files, we built the finopspp CLI tool. Currently, to use it you have to build it from source from this repository. To do this, please read through Developing the finopspp CLI tool in the development guide.
Below we will go through a few of the key commands this CLI tools provides. If you have the tool installed, we encourage you to play around with the tools and look at commands not discussed below, such as the finopspp version command.
The most useful commands to use with finopspp will be related to generate some aspect of the framework. Either markdown documentation or Excel files.
The most useful (or powerful) of the most useful commands offered by finopspp is the command used to generate the framework markdown and assessment worksheet files for a profile. The framework markdown files are designed to give a one-stop shop for getting an overview, in tabular format, of how a framework (generated from a profile) is logically grouped together. While the assessment worksheet is used for scoring the priority weighted maturity of an organization against action completeness for a profile.
To generate the markdown for the framework overview and assessment excel file, make sure that the profile you desire to use is included under specifications/profiles or, if need be, create a new profile.
Then run the following
finopspp generate assessment --profile="<desired-profile-name>"
you can run finopspp generate assessment --help to see the list of profile options. The files generated by this command can be found in assessments. Simply search in this directory for a <desired-profile-name> subdirectory. This subdirectory will include your framework markdown and assessment.
These files are designed to be generally more human readable and easier to navigate than the yaml specifications. The four components supported directly correlate with the four specification types used currently by finopspp. Which are profiles, domains, capabilities, and actions; and can be found in subdirectories of the same names under.
Note
profiles markdown files are generated and offered on an as-best-as-possible basis. This is because of the customization allowed for this type. Generally it is recommended to use the Framework markdown to get a true overview of the profiles. But we include them for the sake of compilation.
To generate the files in these folder fresh from the yaml files, you can call the following command
finopspp generate components --specification-type=<desired-spec-type>
Note
The serialization number for a markdown file uses the schema xxx.md, where xxx will match the serialization number of the yaml specification for the profile or component.
A set of utility commands that can do a number of different actions relevant to the yaml specifications. This range from showing the OpenAPI schema for the different specifications types, to full updates of the specifications via changes to a specification model derived using Pydantic.
One of the most useful command is the validation command
finopspp specifications validate --specification-type=<desired-spec-type> <spec-id-or-all>
With this, you can validate a specific specification by ID and type. Or, by passing in all, you can validate all specification for a specific type. Validation is relatively strict, and makes uses of Pydantic validator. Validation failures are logged to stderr for the user, and results in a failure return code on the command if any specifications fail to validate during a run.
Another really useful command is update, which can be called with the following
finopspp specifications update --specification-type=<desired-spec-type> <spec-id-or-all>
Giving a specification type, and corresponding changes to the specification type's model definitions, you can update that specification type's files by ID or all at once to match the new definition. Some updates work out-of-the-box, like adding/removing fields. While other more complex updates, such as renaming a field or changing the order of fields in the schema, are allowed by creating custom alias for fields or by using Pydantic model_serializer.
The new command will allow you to create new specification files from smart defaults, which can be found, in code, under models/defaults.py. The new specification file, created for a desired specification type, can be used as template to fill-in until the specification is in a state that is ready to be publish.
The command to create these new specification is simply
finopspp specifications new --specification-type=<desired-spec-type> <desired-id>
Important
If you are creating a new profile, make sure to select a Title for the specification that has not already been used. Otherwise this will cause a collision issues with the generate assessment command.
The only requirement is that the desired ID be unique. If it has been used previously, an error will be returned and the specification file will not be created.