Example for a Dataset Script

This example illustrates how the Staes Javascript API is working.

var artifacts =
 pkit.getCurrentProject().getEntities("containsProcess@SYSTEM")
[0].getEntities("containsArtifact@SYSTEM");
for (i = 0; i <artifacts.length; i++) {
 var artifacts_instances =
 artifacts[i].getEntities("containsInstance@SYSTEM");
 for (j = 0; j <artifacts_instances.length; j++) {
 var artifacts_revisions =
 artifacts_instances[j].getEntities("containsRevision@SYSTEM");
 if (artifacts_revisions.length == 0) {
 dataset.setColumnValue("State", "no version");
 } else {
 dataset.setColumnValue("State",
 artifacts_revisions[0].getProperty("state"));
 }
 dataset.setColumnValue("DocumentName",
 artifacts_instances[j].getProperty("LogicalName"));
 dataset.storeResultRow();
}
}

Let's take a look in more detail to this script:

var artifacts =
 pkit.getCurrentProject().getEntities("containsProcess@SYSTEM")
[0].getEntities("containsArtifact@SYSTEM");

We use the global variable pkit to call the method getCurrentProject() to get a handle on the project of the current metric. The method returns the current project.

Now we call the method getEntities() with the parameter “containsProcess@SYSTEM” to retrieve the process on this project. The return is an array, but we mostly want to get the current view, we use the first one by [0].

And now we try to get all Artifacts which are available in the process. So we call getEntities() with the parameter “containsArtifact@SYSTEM” to retrieve the artifacts on this process. As a result we get an array of all artifacts in the variable artifacts.

for (i = 0; i <artifacts.length; i++) {
 var artifacts_instances =
 artifacts[i].getEntities("containsInstance@SYSTEM");

Now we iterate through all artifacts to get the instances of the artifacts, that means the configuration management controlled files. So we call getEntities() with the parameter “containsInstance@SYSTEM” to retrieve the instances. As a result we get an array of all instances in the variable artifacts_instances.

 for (j = 0; j <artifacts_instances.length; j++) {
 var artifacts_revisions =

 artifacts_instances[j].getEntities("containsRevision@SYSTEM");

Now we do the same with the revisions of an instance. Each instance has several revisions. But as you can see later we use only one revision, the latest one. As a result we have a variable with all revisions artifacts_revisions.

if (artifacts_revisions.length == 0) {
 dataset.setColumnValue("State", "no version");
} else {
 dataset.setColumnValue("State",
 artifacts_revisions[0].getProperty("state"));
}

Now we check if a revision exists for an instance. If not then we fill the State column by calling the method dataset.setColumnValue() with a string “no version”. Otherwise we use the value of the first revision. We get the State property of a revision by calling the method getProperty() with the paramter “state”.

dataset.setColumnValue("DocumentName",
 artifacts_instances[j].getProperty("LogicalName"));

We retrieve the document name from the property “LogicalName” and store it in the column with the name “DocumentName”.

The last action to perform is to save the row by calling the method dataset.storeResultRow() with the two columns “State” and “DocumentName”. And we have to this for all artifact's and revisions.

dataset.storeResultRow();