C.1.2. Defining a Lifecycle XML File

A lifecycle is defined in terms of the following constructs:

C.1.2.1. Types

A single lifecycle can be associated with one or more than one types. The type element is used for defining this association.

A type definition consists of the following required attributes:

  • name: used to specify the name of the type associated with this lifecycle. If you are associating the lifecycle with a built-in type, you will need to use the non-localized type name as described in Appendix B: Built-in Types - Reference.

  • enabledByDefault: used to specify whether the lifecycle is enabled by default when an instance of the type is created. Its value can be either true or false. If set to true, this means that whenever an object of this type is created, it will be associated with this lifecycle with the start stage as the current stage. If set to false, the lifecycle will need to be enabled manually.

C.1.2.2. Stages

A stage defines a phase of the lifecycle. Within a stage you can define permissions that specify who can access the object, modify it, or perform other operations on the object that is associated with the lifecycle. You can also specify whether the objects needs to be automatically deleted from the repository and if so after how many days.

A stage definition consists of the following required attributes:

  • name: specifies the name of the stage. As with child names in custom types, node names cannot contain the following special characters:

    / \ : [ ] % * ' " | > < ?

  • description: used to provide a description of the stage

A stage definition may also consist of the following optional attributes:

  • demoteAllowed: specifies whether the object in this stage can be demoted to a previous stage. Its value can either be true or false. If it is unspecified, its value is assumed to be true.

  • expirationDays: specifies the number of days after which the object should be automatically deleted from the repository. Usually this will only be specified in the last phase of the lifecycle, if you want an obsolete object to be automatically deleted after a certain period of time. If it is unspecified, its value is assumed to be 0, which means that the object is not deleted automatically and will be preserved indefinitely.

A stage definition may also contain any number of permission child elements. They are used to specify permissions applicable in the current stage. A permission element consists of the following child elements:

  • type: specifies the type of the permission. One or more than one type elements can be specified in a permission element. Valid values of type are:

    • access: specifies who can access (or view) this object in the user interface

    • create: specifies who can add a child to a folder object

    • delete: specifies who can delete the object

    • modify: specifies who can modify the object

    • lifecycle: specifies who can perform lifecycle operations such as promote and demote

    • download: specifies who can download a file or folder object

    • fullControl: specifies who has full control over the object. Full control means all permissions are available, including the ability to change permissions.

  • member: specifies the name of the user or group for which the permission is specified. One or more than one member elements can be specified in a permission element. Its value must correspond to a user or group name defined in EKM. You can also use * to specify the user who created the object.

The example in Figure 2: Stage Example 1 shows a lifecycle stage named Obsolete which does not have any permissions associated with it, whose demoteAllowed attribute is set to false and whose expirationDays attribute is set to 365 days. This means that once the object goes to this stage, only the user designated as the Root User for a workspace can access this object, it cannot be demoted to a previous stage and it will reside in the repository for 365 days before it is automatically deleted.

Figure 2:  Stage Example 1

stage name="Obsolete" description="description for obsolete" demoteAllowed="false" 
		expirationDays="365" />

The example in Figure 3: Stage Example 2 shows a lifecycle stage named Release with three permission elements. The all group is given access and download permissions. Turbine Group and Combustion Group have been given modify permission and Turbine Group Lead and Combustion Group Lead have been given lifecycle permission. Because the expirationDays attribute is not set, the object in this stage will not be automatically deleted. Also, because demoteAllowed is not specified, the object in this stage can be demoted to a previous stage.

Figure 3:  Stage Example 2

 <stage name="Release" description="description for release">
		<permission>
			<type>access</type>
			<type>download</type>
			<member>all</member>
		</permission>
		<permission>
			<type>modify</type>
			<member>Turbine Group</member>
			<member>Combustion Group</member>
		</permission>
		<permission>
			<type>lifecycle</type>
			<member>Turbine Group Lead</member>
			<member>Combustion Group Lead</member>
		</permission>
	</stage>

C.1.2.3. Transitions

A transition is used to specify the subsequent and preceding stages of the any lifecycle stage. A transition can also optionally specify a signoff process for moving to the next stage.

A transition definition consists of the following required attributes:

  • source: specifies the name of the lifecycle stage from which the transition begins

  • destination: specifies the name of the lifecycle stage at which the transition ends

The transitions must adhere to the following rules:

  • Like process templates, lifecycles should have exactly one start stage. The start stage is the stage that is not the destination of any transition. Unlike process templates, lifecycles can have more than one end stage. The end stage is the stage that is not the source of any transition.

  • Like process templates, lifecycles must be acyclic. For example, if you have a transition from stage A to stage B, then you can’t have a transition from stage B to stage A. Similarly, if you have defined transitions from stage A to stage B and from stage B to stage C, you can’t have a transition from stage C to stage A. In this way, lifecycles, like process templates, are always Directed Acyclic Graphs.

A transition definition may also consist of the following optional attributes:

  • promoteValidationMacro: specifies the name of the macro that is used to perform validation before a promote request can be processed

  • promoteActionMacro: specifies the name of the macro that is used to perform an automatic action after a promotion request has been processed

  • demoteValidationMacro: specifies the name of the macro that is used to perform validation before a demote request can be processed

  • demoteActionMacro: specifies the name of the macro that is used to perform an automatic action after a demote request has been processed

These optional macros are usually specified in the optional script element at the beginning of a lifecycle definition. See the Defining Macros and Custom Dialogs chapter in the EKM User’s Guide to learn more about macro definition and scripting. All these macros take the following arguments:

  • an instance of ModelObjectInterface that specifies the object associated with the lifecycle.

  • the name of the next stage.

These optional macros do not return any values. The validation macros may throw an exception if validation fails. The action macros specify commands that are to be executed when the stage change succeeds. For example, the following XML listing shows a transition with all four macros defined, followed by the definition of each macro. This is a dummy example that is used for illustration purposes, only.

<transition source="Draft" destination="Release" 
	promoteActionMacro="promoteToReleaseAction" 
promoteValidationMacro="promoteToReleaseValidation" 
	demoteActionMacro="demoteToDraftAction" 
demoteValidationMacro="demoteToDraftValidation" />
<script>
	promoteToReleaseValidation(model, nextStage) {
		if (!model.getChildNames().contains("test-child"))
			throw new RuntimeException("test-child doesn't exist");
	}
	
	promoteToReleaseAction(model, nextStage) {
		ekm.startTransaction();
		model.addChild(ekm.createObject("auto-created-folder", "Folder"));
		ekm.commitTransaction();
	}
	
	demoteToDraftValidation(model, nextStage) {
		if (model.getChildNames().contains("test-child"))
			throw new RuntimeException("test-child exists");
	}
	
	demoteToDraftAction(model, nextStage) {
		ekm.startTransaction();
		model.getChild("auto-created-folder").delete();
		ekm.commitTransaction();
	}
	
</script>

In the listing, the promoteToReleaseValidation macro verifies that the object associated with the lifecycle has a child named test-child and the demoteToDraftValidation macro verifies that such a child does not exist. The promoteToReleaseAction adds a folder named auto-created-folder to the object and the demoteToDraftAction removes this folder.

A transition definition may also contain any number of promoteSignoff or demoteSignoff child elements. These elements are used to specify any number of signoff processes that can be associated with promotion or demotion. Multiple signoff elements can be defined to model a multi-level signoff process. For example if you specify two promoteSignoff elements, it means that the promotion process will involve a two-level signoff. The first level signoff will need to be completed before the second level signoff can begin.

A signoff element definition consists of the following required attributes:

  • level: specifies the name of signoff level. There are no character restrictions for the level definition.

  • members: specifies the names of users and groups involved in the signoff at this level. If you specify more than one user or group, you will need to separate their names by a comma. For example: group-1, group-2. In some cases, you may want to use the same lifecycle definition for various teams. In this case, say the stages and transitions are the same and the only difference is the members that are involved in the signoff process. For these situations, you can define a macro for determining the member names. This macro could use some logic, based on object type or path, for example, to determine the list of members to be used in a given context.

    If you want to make use of this feature, you must do the following:

    • Define the macro in the script tag as described above. The macro should take two arguments: the object associated with the lifecycle and the name of the next stage. It should return either an array or a list of strings. Each item in the list or array should correspond to a user or group name. If it returns null or an empty list or array, then the signoff process will advance to the next signoff level if it exists. If no more levels exist, the signoff process will be completed and the request will be approved. The following XML listing shows a sample macro definition of this type. In the example, the list of approvers will be “user1” if the object associated with the lifecycle is in the /Data/Shared Data/bar folder, “user1” and “user2” if the object is in /Data/Shared Data/foo, or null if the object is in any other folder.

      <script>
      	releaseLevel1(model, nextStage) {
      		if (model.getPath().startsWith("/Data/Shared Data/foo"))
      			return new String[] {"user1", "user2"};
      		else if (model.getPath().startsWith("/Data/Shared Data/bar")) {
      			list = new LinkedList();
      			list.add("user1");
      			return list;
      		}
      	}
      </script>
      
    • Define the members to be $ followed by the macro name as shown in the following listing:

      <promoteSignoff members="$releaseLevel1" level="1""/>

A signoff element definition consists of the following optional attributes:

  • inclusive: specifies whether all members of the signoff committee need to approve the signoff at this level. Its value can be either true or false. If it is set true or it is not specified (in which case its value assumed to be true), then all members of the signoff committee must approve the signoff at this level. If it is set to false, then any member can approve the level signoff.

  • dueDays: specifies the number of days allowed for the signoff. If a user has not approved or rejected the signoff by then, a daily email reminder is sent to the user. If it is not specified, then the value is assumed to be 7.

The example in Figure 4: Transition Example 1 shows a transition from Draft stage to In-Work stage. It has a single-level promote signoff involving Turbine Group. Because the inclusive attribute is set to false, the signoff will be completed when any user from the Turbine Group accepts or rejects the signoff.

Figure 4:  Transition Example 1

<transition source="Draft" destination="In-Work">
	<promoteSignoff level="group" members="Turbine Group" inclusive="false"/>
</transition>

The example in Figure 5: Transition Example 2 shows another transition from In-Work stage to Release stage. It has a two-level promote signoff. The first level involves Combustion Group Lead and Turbine Group Lead and the second level involves VP Engineering. Because the inclusive attribute is not specified, all users in the first level will need to accept the signoff before it can advance to the next level.

Figure 5:  Transition Example 2

<transition source="In-Work" destination="Release">
	<promoteSignoff level="lead" members="Combustion Group Lead, Turbine Group Lead"/>
	<promoteSignoff level="vp" members="VP Engineering"/>
</transition>


Release 18.2 - © ANSYS, Inc. All rights reserved.