Possible Error Messages in the Context of Version Management APIs

Learn how to prevent possible error messages when you use version management APIs.

Operate on Deleted Planning Versions

A previously deleted version, whether it was deleted by the script API or end user interaction, behaves differently from a non-deleted one.

Return Values for Calls Made on Deleted Versions

Use the following getter functions on versions:

PlanningVersion.getId() => returns last ID before deletion
PlanningVersion.isDirty() => returns last modified stated before deletion
PlanningVersion.deleteVersion() => returns true (the promised state was reached)
PlanningVersion.publish() => returns false (the promised state cannot be reached)
PlanningVersion.publishAs() => returns false (the promised state cannot be reached)
PlanningVersion.revert() => returns true (the promised state was reached)

Reproduction

The easiest way to reproduce this is to delete any version and simply continue with script execution:

// delete new Budget version and operate on it afterwards
var newBudgetVersion = Table_1.getPlanning().getPublicVersion("newBudget");
if (newBudgetVersion) {
    console.log("VersionId before deletion:" + newBudgetVersion.getId());
    newBudgetVersion.deleteVersion();
    console.log("VersionId after deletion:" + newBudgetVersion.getId());
    newBudgetVersion.publish();
};

When calling any action function (revert, publishAs, publish or delete), the following error message is displayed: Version 'newBudget' does not exist anymore.

Publish a Private Version with a Wrong Name

There are several errors that can occur when you use the publishAs API.

Empty String as Version Name

The following code leads to an error, as the version name shouldn't be empty:

//Don't use this code as it leads to error
var myActualVersion = Table_1.getPlanning().getPrivateVersion("myActual");
if (myActualVersion) {
    myActualVersion.publishAs("");
};

The following error message is shown: Enter a name for your version before you publish it.

String Too Long to Be a Version Name

The following code leads to an error, as the version name is too long:

//Don't use this code as it leads to error
var myActualVersion = Table_1.getPlanning().getPrivateVersion("myActual");
if (myActualVersion) {
  myActualVersion.publishAs("255characters");
};

The following error message is displayed: Enter a version name that is shorter than 255 characters.

Unauthorized Characters in Version Name

The following code leads to an error, as the version name contains characters that aren't allowed:

//Don't use this code as it leads to error
var myActualVersion = Table_1.getPlanning().getPrivateVersion("myActual");
if (myActualVersion) {
    myActualVersion.publishAs("\:Version");
};

The following error message is displayed: Enter a version name that doesn't contain the characters \\ : ; ' = [ ].

Using Existing Version Name

The following code leads to an error, as the version name already exists:

//Don't use this code as it leads to error
var myActualVersion = Table_1.getPlanning().getPrivateVersion("myActual");
if (myActualVersion) {
    myActualVersion.publishAs("Actual");
};

The following error message is displayed: You can't save this version with name 'Actual', because this name already exists. Please use a different name.

Deleting Actual Version

The following code leads to an error, as the actual version shouldn't be deleted.

//Don't use this code as it leads to error
var actualVersion = Table_1.getPlanning().getPublicVersion("Actual");
if (actualVersion) {
    actualVersion.deleteVersion();
};

The following error message is displayed: You can't delete the public version of category 'Actual'. This version always has to be available.