Instance Definitions User Guide

Last updated on September 16, 2021.

Document Status: Document Feature Complete as of September 16, 2021; PENDING EXTERNAL REVIEW.

Table of Contents

• Instance Definitions User Guide
  • Table of Contents
  • Introduction
  • Definition of Instance Definitions
  • Purpose of Generating Instance Definitions
  • Solution for Generating Instance Definitions
    • Overview
  • Create or Edit Instance Definition Items
    • Create Instance Definition Items
      • Operations
      • Permissions
    • Edit Instance Definition Items
      • Operations
      • Permissions
  • Approve an Instance Definition Item
    • Operations
    • Permissions
  • Delete an Instance Definition Item
    • Operations
    • Permissions
  • Create or Edit Instance Definitions
    • List Instance Definitions
      • Operations
      • Permissions
    • Create an Instance Definition
      • Operations
      • Permissions
    • Add Tokens to a Property
      • Operations
    • Edit an Instance Definition
      • Operations
      • Permissions
    • Approve or Disapprove an Instance Definition
      • Operations
      • Permissions
  • Copy Instance Definitions
    • Operations
    • Permissions
  • Add or Remove Items in an Instance Definition
    • Add an Item to an Instance Definition
      • Operations
      • Permissions
    • Remove an Item from an Instance Definition
      • Operations
      • Permissions
  • Validate an Instance Definition or Reference
    • Validation Indicators
    • Validation Results
  • Replace Items in an Instance Definition
    • Operations
    • Permissions
  • Add or Remove Items From a Referenced Item
    • Add child items
    • Add associations to the item you are currently configuring
    • Operations
    • Permissions
  • Delete an Instance Definition
    • Operations
    • Permissions
  • Export an Instance Definition
    • Operations
    • Permissions
  • Manage Instance Definition Groups
    • Create
    • Delete
    • Edit
    • Export/Download
    • Operations
    • Permissions
  • How to use the Token Search
    • Tokens
    • Tokens built into RPS
    • Token Search
    • Bring up the Token Search
    • Use the Token Search
    • Copy Token
    • Append Token
    • Delete Token
  • Bulk Replace Tokens
    • Operations
    • Permissions
  • How to use Special Characters
    • Supported Special Characters
    • How to Add a Special Character to a Property Value
  • Scenario: How to Create and Export an Instance Definition and its Items
  • Annotated Screenshot Guides
    • Instance Definitions Listing Annotated Guide
    • Create or Edit Instance Definition Annotated Guide
    • Instance Definition Groups Annotated Guide
    • Create or Edit Instance Definition Group Annotated Guide
    • Instance Definition Builder Annotated Guide
    • Add Reference to Instance Definition Annotated Guide
    • Add Association to Instance Definition Annotated Guide
    • Change a Referenced Item in Instance Definition Annotated Guide
    • Instance Definition Items Annotated Guide
    • Token Picker Annotated Guide
  • Glossary

Introduction

This document describes REACTR's instance definitions feature and provides a user guide. The feature was established based on the need for a way to simplify and improve the Rapid Provision Service's (RPS) provisioning process.

Definition of Instance Definitions

Instance definitions are an abstraction layer on top of existing RPS types. Types currently allow developers define a specific type of resource or target item, its expected or possible Properties and their associated value types (string/int/etc.).

Instance definitions allows developers to take these generic types and combine them together to create complex, nested entities composed of many different types through parent/child and assignment relationships, and the known default values for each individual Types' properties.

Examples: SNEs, TCNs, TSI-Large, laptop, could be a VM (because it could be a collection of components).

There are many existing types such as Vehicle, Computer, VirtualMachine, NetworkConfiguration, etc. The entities soldiers and developers are now interacting with are complex and composed of many of these types in parent/child hierarchies.

Instance definitions are collections of type definitions that have the ability to create an object.

Type definitions are parts with detailed properties. The type definitions do not create objects, but they are able to define something you can create which is what an object will consist of.

Example: Virtual Machine, NIC, drive, etc.

Purpose of Generating Instance Definitions

The RPS provisioning process for a soldier or LSI is limited to selection of a template (instance definition) to use for provisioning and providing unit specific data files, and RPS can successfully provision with this information. The goal is to limit the number of choices and decisions that a soldier or LSI needs to make during provisioning.

By simplifying the RPS provisioning process and removing the number of choices a soldier or LSI needs to make in the field, RPS reduces the likelihood of human error and increases likelihood of adoption due to the improved ease of use.

Solution for Generating Instance Definitions

Overview

To simplify the RPS provisioning process, instance definitions can be used as templates to reduce the amount of data the user would need to input, thereby reducing the potential for errors.

The solution for creating instance definitions is a new feature as a part of REACTR that enables users to create instance definition items, create Instance definition templates, and export those Instance definition templates as JSON files.

This new feature is implemented as a web application with a backend that uses Microsoft Azure.

Create or Edit Instance Definition Items

A user interface to create new instance definition items or edit existing instance definition items.

Note

Instance definition items that are 'Approved' cannot be edited.

Once all the necessary instance definition items are created and accurate, they can be used as the toolbox to build instance definitions.

Create Instance Definition Items

The steps necessary to create instance definition items are described below:

1. Navigate to Instance Definitions > View All Instance Definition Items
2. Navigate through the list of items by first selecting the Entity Type.

3. Select the Type Definition that is the type of item you want to add.

   • If the type definition has a schema available it will be displayed in the list.
     1. Click on the Add (+) button next to the type definition name in the list

   • If the type definition is not visible then it does not have a schema available. You can add a custom type definition without a schema by following these steps:

     1. Click on the Add (+) button next to the type definitions heading.

        

     2. Type in the name of the type definition.

     3. Click the Add (+) button next to the type definition name you entered to add it to the list.

        

4. Fill out the Properties for the new item.

5. Click on the Save button to create the new item.

   

Important

Definition item Name is required.

Warning

Definition item Name cannot be a duplicate of an existing instance definition.

Click "Add Property" to add item properties to the instance definition item.

Important

Name is required.

Warning

Value is required unless Data Mapped Property Value is checked.

Cannot add multiple properties with the same name.

Operations

Operation Name	Trigger	Purpose	Additional comments
Item State	Item State toggle	Approves or disapproves an instance definition item so that it becomes uneditable or editable.	Approving an item prevent future changes to the item.
Is Active	Is Active toggle	Sets the IsActive flag on the item.	The IsActive flag is used by RPS to determine whether the item is active or not in RPS.
Add	Add Button	Create a brand-new instance definition item.	The user needs to choose the instance definition item type, type definition, and add values for all required properties for the type selected.
Add Property	Add Property Button	Add a property to an instance definition item.	Property values can be modified after they have been added.

Permissions

Operation	Role	Description
Create	InstanceDefinitionCreator	The instance definition creator can create instance definitions.
Create	InstanceDefinitionAdmin	The instance definition admin can create instance definitions.
Item State Toggle	InstanceDefinitionAdmin	The instance definition admin can toggle the item state for instance definitions to indicate whether the item is approved or not approved.

Edit Instance Definition Items

The steps necessary to edit instance definition items are described below:

1. Navigate to Instance Definitions > View All Instance Definition Items
2. Navigate through the list of items by first selecting the Entity Type.
3. Select the Type Definition that is the type of item you want to edit.
4. Hover over the item and click on the Edit (pencil) button next to the item.
5. Checkmark the desired Roles for the item.
6. Fill out the Property values and add more Properties as needed for the item.

7. Click on the Save button to save the item.

   

   Note

   If an Instance Definition Item is approved the pencil edit icon will not be selectable. Approved items can be identified by the green lock next to the item name.

Operations

Operation Name	Trigger	Purpose	Additional comments
Item State	Item State toggle	Approves or disapproves an instance definition item so that it becomes uneditable or editable.	Approving an item prevent future changes to the item.
Is Active	Is Active toggle	Sets the IsActive flag on the item.	The IsActive flag is used by RPS to determine whether the item is active or not in RPS.
Edit	Edit Button	Allows the user to edit an instance definition item.	Editing an item modify the item stored in the database. These changes modify the item anywhere it is used, across all instance definitions.
Add Property	Add Property Button	Allows the user to add a property to an instance definition item.	Property values can be modified after they have been added.

Permissions

Operation	Role	Description
Edit	InstanceDefinitionCreator	The instance definition creator can edit instance definitions.
Edit	InstanceDefinitionAdmin	The instance definition admin can edit instance definitions.
Item State Toggle	InstanceDefinitionAdmin	The instance definition admin can toggle the item state for instance definitions to indicate whether the item is approved or not approved.

Approve an Instance Definition Item

The user interface provides instance definition administrators multiple methods of approving items. Approving an instance definition item locks the current state of the item so that it is unable to be edited and prevents the item from being deleted.

Item approval functionality is only given to InstanceDefinitionAdmin roles. Items can be approved individually or in bulk by the type of type definition.

The steps necessary to approve an instance definition item are described below:

1. Navigate to Instance Definitions > View All Instance Definition Items
2. Select the Entity Type containing the Type Definition and item you want to approve / disapprove.

3. Select the type of Type Definition containing the item, or list of items, you want to approve / disapprove.

   • Click on the appropriate approval toggle based on the scenario below.
     • Scenario A - Bulk Approval: Select the bulk approval toggle next to the item type header (see screenshot below)
       • This approves all items listed.
     • Scenario B - Individual Item Approval
       • Select the individual item approval toggle next to the item you want to approve.
       • Or, click on the item to view / edit the item for accuracy. Select the individual item approval in the item detail pane.

   

Note

These steps are the same when approving an item from the instance definition builder page or the instance definition item page.

Warning

When approving an item from the instance definition builder view, you are approving the underlying instance definition item being referenced by the instance definition, not just the reference you created. This means the item will be approved for all instance definitions referencing this specific item.

Operations

Operation Name	Trigger	Purpose	Additional comments
Bulk Item State	Bulk Approval Toggle	Bulk approves or disapproves a list of instance definition items by type.	Bulk approving a list of items will prevent future changes to the items.
Item State	Individual Item Approval Toggle	Approves or disapproves an instance definition item so that it becomes uneditable or editable.	Approving an item will prevent future changes to the item.

Permissions

Operation	Role	Description
Edit	InstanceDefinitionCreator	View current approval status
Edit	InstanceDefinitionAdmin	The instance definition admin has the ability to approve or disapprove instance definition items during edit.
Bulk Approval	InstanceDefinitionAdmin	The instance definition admin can view toggle and bulk approve or unapprove items by type
Item Approval	InstanceDefinitionAdmin	The instance definition admin can view toggle and approve or disapprove items using the item toggle in the type listing

Note

Only the instance definition administrators will see the approval toggles. All other roles will still be able to see the status icons showing the current approval status of each item.

Delete an Instance Definition Item

The steps necessary to delete instance definition items are described below:

1. Navigate to Instance Definitions > View All Instance Definition Items
2. Navigate through the list of items by first selecting the Entity Type.
3. Select the Type Definition that is the type of item you want to delete.
4. Click on the Delete (trashcan) button.

5. Click on Delete button to confirm deletion of the instance definition item.

   

   

Note

An instance definition item can only be deleted if it does not have any references or associations to other instance definition items.

Caution

A deleted instance definition item is removed permanently.

Operations

Operation Name	Trigger	Purpose	Additional comments
Delete	Delete Button	Removes an item from the available instance definition items used for building instance definitions.	Deleting an item removes it permanently from the database.

Permissions

Operation	Role	Description
Delete	InstanceDefinitionCreator	The instance definition creator can delete instance definitions.
Delete	InstanceDefinitionAdmin	The instance definition admin can delete instance definitions.

Create or Edit Instance Definitions

A user interface to create new instance definitions or edit existing instance definitions.

Note

Instance definitions that are 'Approved' cannot be edited.

Once all the necessary references and associations are added to the instance definition, it can be exported and used in RPS.

Validation functionality is in place to validate an entire instance definition's references.

List Instance Definitions

The step necessary to list instance definitions is described below:

1. Navigate to Instance Definitions > View All Instance Definitions

   

Operations

Operation Name	Trigger	Purpose	Additional comments
Delete	Delete Button	Removes an instance definition.	Deleting an instance definition removes it permanently from the database.
Add	Add Button	Create a brand-new instance definition.	The user needs to fill out the instance definition details and configure it with references to items and associations between items before exporting it to a file.
Edit	Edit Button	Edit an instance definition.	Editing an instance definition modifies the record stored in the database.
Configure	Configure Button	Configure an instance definition.	Configuring an instance definition updates the instance definition items defining the current instance definition configuration
Duplicate	Duplicate button	Duplicate an instance definition.	Duplicating an instance definition duplicates the instance definition and all its references and associations. It does not duplicate the individual instance definition items.
Export	Export button	Export an instance definition.	Exporting an instance definition triggers a download of the exported instance definition to a JSON file.
Status	Status toggle	Approves or disapproves an instance definition.	An approved instance definition is locked and not configurable.

Permissions

Operation	Role	Description
Add	InstanceDefinitionCreator	The instance definition creator can add instance definitions.
Add	InstanceDefinitionAdmin	The instance definition admin can add instance definitions.
Edit	InstanceDefinitionCreator	The instance definition creator can edit instance definitions.
Edit	InstanceDefinitionAdmin	The instance definition admin can edit instance definitions.
Delete	InstanceDefinitionCreator	The instance definition creator can delete instance definitions.
Delete	InstanceDefinitionAdmin	The instance definition admin can delete instance definitions.
Duplicate	InstanceDefinitionCreator	The instance definition creator can duplicate instance definitions.
Duplicate	InstanceDefinitionAdmin	The instance definition admin can duplicate instance definitions.
Export	InstanceDefinitionViewer	The instance definition viewer can export instance definitions.
Export	InstanceDefinitionCreator	The instance definition creator can export instance definitions.
Export	InstanceDefinitionAdmin	The instance definition admin can export instance definitions.
Status	InstanceDefinitionAdmin	The instance definition admin can change the approved status of instance definitions.

Create an Instance Definition

The steps necessary to create an instance definition are described below:

1. Navigate to Instance Definitions > View All Instance Definitions
2. Click on the Create (+) button on Actions column to create a new instance definition.
3. Fill out the details for the instance definition.

4. Click on the Save button to save the instance definition.

   

   

Important

Name is required and cannot be a duplicate of an existing instance definition name

Important

IP Address and Sync Endpoint URL must have a valid format

Important

If you want an endpoint node to be created then the Name, Entity Name, and IP Address are required, otherwise leave all fields and properties blank.

Click "Add Property" to add node properties to the instance definition.

Important

Name is required

Warning

Value is required unless Data Mapped Property Value is checked

Cannot add multiple properties with the same name

Operations

Operation Name	Trigger	Purpose	Additional comments
Save	Save Button	Save the instance definition.	Saves all changes made to the instance definition to the database.
Add Property	Add Property Button	Add a property to the instance definition.	Property values can be modified after they have been added.

Permissions

Operation	Role	Description
Save	InstanceDefinitionCreator	The instance definition creator can save instance definitions.
Save	InstanceDefinitionAdmin	The instance definition admin can save instance definitions.
Add Property	InstanceDefinitionCreator	The instance definition creator can save instance definitions.
Add Property	InstanceDefinitionAdmin	The instance definition admin can save instance definitions.

Add Tokens to a Property

The steps necessary to add tokens to a property are described below:

1. Follow steps in Creating an Instance Definition to get UI for Create Instance Definition.

2. Hover over or click inside a text field that can receive a token.

   Note

   Not all fields are allowed to contain a token.

   

3. Click the search icon that appears while the text field has focus.
4. In the popup, a list of available tokens appears. This list can be searched.

5. Hover over the desired choice to see the copy icon.

   

6. Click the copy icon to copy the token value to the clipboard.

   

7. Paste the token into the text field using CTRL-V or right-click / paste.

Operations

Operation Name	Trigger	Purpose	Additional comments
Copy	Copy Button	Copies the token to the clipboard.	Tokens that are copied to the clipboard can then be pasted into a text field where the user wants the token.
Delete	Delete Button	Deletes the token from the cache.	Deleting a token will only delete it from the cache, it will not remove the token from item fields where it is used.

Edit an Instance Definition

The steps necessary to edit an instance definition are described below:

1. Navigate to Instance Definitions > View All Instance Definitions
2. Click on the Edit (pencil) button next to the instance definition you want to edit.
3. Fill out the details for the instance definition.

4. Click on the Save button to save the instance definition.

   

   

   When an error occurs, a summary of page errors will appear. The fields will also contain visual indicators.

   

Operations

Operation Name	Trigger	Purpose	Additional comments
Save	Save Button	Save the instance definition.	Saves all changes made to the instance definition to the database.
Add Property	Add Property Button	Add a property to the instance definition.	Property values can be modified after they have been added.

Permissions

Operation	Role	Description
Save	InstanceDefinitionCreator	The instance definition creator can save instance definitions.
Save	InstanceDefinitionAdmin	The instance definition admin can save instance definitions.
Add Property	InstanceDefinitionCreator	The instance definition creator can save instance definitions.
Add Property	InstanceDefinitionAdmin	The instance definition admin can save instance definitions.

Approve or Disapprove an Instance Definition

Note

When an instance definition is approved, it cannot be edited, deleted, or configured.

The steps necessary to approve or dissaprove an instance definition are described below:

1. Navigate to Instance Definitions > View All Instance Definitions
2. Click on the Status toggle for the instance definition that you want to update.

3. Click on the Save button on the confirmation dialog to save the instance definition status.

   

   When the toggle is updated, a confirmation dialog will appear asking for confirmation of the update.

   

Operations

Operation Name	Trigger	Purpose	Additional comments
Status	Status toggle	Approves or disapproves the instance definition so that it becomes uneditable or editable.	Approving an instance definition will prevent future changes to the instance definition.
Save	Save Button	Save the instance definition's status.	Saves the changes made to the instance definition to the database.

Permissions

Operation	Role	Description
Approve/disapprove	InstanceDefinitionAdmin	The instance definition admin can approve or disapprove instance definitions.

Copy Instance Definitions

A user interface to copy instance definitions.

Note

Copying an instance definition makes an exact copy of the instance definition and all its references and associations.

Copying an instance definition does not copy the individual instance definition items.

The steps necessary to copy an instance definition are described below:

1. Navigate to Instance Definitions > View All Instance Definitions

2. Click on the Copy (paper) button next to the instance definition you want to copy.

   

3. Enter the Copy Name for the instance definition you are copying and click on the Copy button.

Important

Copy Name is required.

Warning

Copy Name cannot be a duplicate of an existing instance definition that has the same Name.

Operations

Operation Name	Trigger	Purpose	Additional comments
Copy	Copy button	Copy an instance definition.	Copying an instance definition copies the instance definition and all its references and associations. This does not copy the individual instance definition items.

Permissions

Operation	Role	Description
Copy	InstanceDefinitionCreator	The instance definition creator can copy instance definitions.
Copy	InstanceDefinitionAdmin	The instance definition admin can copy instance definitions.

Add or Remove Items in an Instance Definition

A user interface to add or remove instance definition items in an instance definition.

When an instance definition item is added to an instance definition it is not directly added; rather, it is referenced in the instance definition or associated to another referenced instance definition item.

When an instance definition item is added:

• At the parent/root instance definition level: it is added as a reference.
• Under a referenced instance definition item of the same entity type: it is added as a reference.
• Under a referenced instance definition item of a different entity type: it is added as an association.

Add an Item to an Instance Definition

The steps necessary to add an item to an instance definition are described below:

1. Navigate to Instance Definitions > View All Instance Definitions
2. Click on the Configure (wrench) button next to the instance definition you want to configure/build.
3. Navigate through the instance definition by first selecting the Entity Type.

4. Select the Type Definition that is related to the item you want to add.

   • If the type definition is visible:
     1. Click on the Add (+) button next to the type definition.
     2. Choose the items you want to reference in the instance definition.
   • If the type definition is not visible:
     1. Click on the Add (+) button next to the column header Type Definitions.
        1. Select the type definition you want.

5. Choose the items you want to reference in the instance definition.

6. Click the Select button.

   

Operations

Operation Name	Trigger	Purpose	Additional comments
Add	Add button	Add a reference to an instance definition item or association between instance definition items.	If the parent is the root instance definition or a referenced instance definition item of the same entity type, then a reference will be created. Otherwise, an association will be created between the item being added and the parent item.

Permissions

Operation	Role	Description
Add	InstanceDefinitionCreator	The instance definition creator can add references to instance definition items or associations between instance definition items.
Add	InstanceDefinitionAdmin	The instance definition admin can add references to instance definition items or associations between instance definition items.

Remove an Item from an Instance Definition

The steps necessary to remove an item to an instance definition are described below:

1. Navigate to Instance Definitions > View All Instance Definitions

2. Click on the Configure (wrench) button next to the instance definition you want to configure/build.

   

3. Navigate through the instance definition by first selecting the Entity Type.
4. Select the Type Definition that is related to the item you want to remove.

5. Click on Trash icon to delete.

   

6. Confirm that you want to delete the referenced item from the instance definition.

   

Operations

Operation Name	Trigger	Purpose	Additional comments
Remove	Remove button	Remove a reference to an instance definition item or association between instance definition items.	If the parent is the root instance definition or a referenced instance definition item of the same entity type, then a reference will be removed. Otherwise, an association will be removed between the item being removed and the parent item.

Permissions

Operation	Role	Description
Remove	InstanceDefinitionCreator	The instance definition creator can remove references to instance definition items or associations between instance definition items.
Remove	InstanceDefinitionAdmin	The instance definition admin can remove references to instance definition items or associations between instance definition items.

Validate an Instance Definition or Reference

Validation Overview

Validation of instance definitions works by validating a full referenced item against its type definition schema. A full referenced item consists of:

• referenced item's entity name
• referenced item's properties
• referenced item's roles
• referenced item's children (to other referenced items)
• referenced item's associations (to other referenced items)

Validation is performed by taking the above information and comparing it against the type definition schema of the parent referenced item. If there are any discrepencies then these validation results will be available for you to see by clicking on the validation errors button. Clicking on the validation errors button will open the Validation Results modal.

Validation Indicators

A status message displays the current validation status of the instance definition or reference. The following indicators are displayed based on the status of the validation:

Not validated - Indicates that the validation process has not started. This process is automatic.

Validating - Indicates that the validation process started but has not completed. The screen will update as the validation completes.

Errors - Indicates that there are 1 or more errors. Click on the message to see the detail validation messages.

Valid - Indicates that no validation errors are detected.

Validation Results

Detailed validation messages are show with the validation results. Across the top of the page are tabs based on the type of validation error.

Fixing Validation Errors

To fix a validation error you may need to alter any of the following:

1. Missing, invalid, or extraneous properties on the Item.
2. Missing, invalid, or extraneous properties for a role on the Item.
3. Missing, invalid, or extraneous children or associations for the Item.
4. Missing, invalid, or extraneous properties for any children or associations directly below the parent Item.

Tip

If the error "An error occurred while validating <Item Type>" occurs, make sure the type schema does not contain a property named ExtraProperties.

Replace Items in an Instance Definition

A user interface to replace instance definition items in an instance definition.

Important

When an item is replaced for a different item, it must be replaced with an item of the same entity type and type definition.

The steps necessary to replace items in an instance definition are described below:

1. Navigate to Instance Definitions > View All Instance Definitions

2. Click on the Configure (wrench) button next to the instance definition you want to configure/build.

   

3. Navigate through the instance definition by first selecting the Entity Type.

4. Select the Type Definition that is related to the item you want to remove.

5. Click on the Replace (swap arrows) button next to the referenced item that you want to replace.

   

6. Select (click on) the item that you want to replace it with.

7. Confirm that you want to replace the referenced item in the instance definition by clicking the Select button.

   

Operations

Operation Name	Trigger	Purpose	Additional comments
Replace	Replace button	Replace a reference to an instance definition item with another instance definition item of the same entity type and type definition.

Permissions

Operation	Role	Description
Replace	InstanceDefinitionCreator	The instance definition creator can replace references to instance definition items.
Replace	InstanceDefinitionAdmin	The instance definition admin can replace references to instance definition items.

Add or Remove Items From a Referenced Item

A user interface to add child items under a parent item or make associations between items.

When an instance definition item is added to an instance definition it is not directly added; rather, it is referenced in the instance definition, or associated to another referenced instance definition item.

When an instance definition item is added:

• Under a referenced instance definition item of the same entity type: it is added as a reference.
• Under a referenced instance definition item of a different entity type: it is added as an association.

The steps necessary to add ore remove items from a referenced item are described below:

1. Navigate to Instance Definitions > View All Instance Definitions
2. Click on the Configure (wrench) button next to the instance definition you want to configure/build.
3. Navigate through the instance definition by first selecting the Entity Type.
4. Select the Type Definition that is related to the item you want to configure/build.

5. Click on the Configure (wrench) button next to the referenced item you want to configure/build.

   

   

   

Note

When you configure a referenced item, notice that the breadcrumb at the top of the page now displays the referenced item's name. You are now configuring that specific referenced item's children references and associations.

Add child items

1. Click on the children entity type.
2. Follow these instructions for how to add or remove referenced items: Adding or Removing Items in an Instance Definition

Add associations to the item you are currently configuring

1. Click on any entity type except for children. The children entity type refers to parent/child referenced item relationships.
2. Follow these instructions for how to add or remove referenced items: Adding or Removing Items in an Instance Definition

Note

Any references added like this will become associations that are associated with the referenced item you are currently configuring.

Operations

Operation Name	Trigger	Purpose	Additional comments
Add	Add button	Add a reference to an instance definition item or association between instance definition items.	If the parent is the root instance definition or a referenced instance definition item of the same entity type, then a reference will be created. Otherwise, an association will be created between the item being added and the parent item.
Remove	Remove button	Removes a reference to an instance definition item or association between instance definition items.	If the parent is the root instance definition or a referenced instance definition item of the same entity type, then a reference will be removed. Otherwise, an association will be removed between the item being removed and the parent item.

Permissions

Operation	Role	Description
Add	InstanceDefinitionCreator	The instance definition creator can add references to instance definition items or associations between instance definition items.
Add	InstanceDefinitionAdmin	The instance definition admin can add references to instance definition items or associations between instance definition items.
Remove	InstanceDefinitionCreator	The instance definition creator can remove references to instance definition items or associations between instance definition items.
Remove	InstanceDefinitionAdmin	The instance definition admin can remove references to instance definition items or associations between instance definition items.

Delete an Instance Definition

A user interface to delete an instance definition.

Warning

Deleting an instance definition will permanently delete the instance definition, and any references or associations that it contained.

Note

This does not delete the actual instance definition items that were referenced or associated in the deleted instance definition.

The steps necessary to delete an instance definition are described below:

1. Navigate to Instance Definitions > View All Instance Definitions

2. Click on the Delete (trashcan) button next to the instance definition you want to delete.

   

3. Confirm that you want to delete the instance definition.

   

Operations

Operation Name	Trigger	Purpose	Additional comments
Delete	Delete Button	Removes an instance definition.	Deleting an instance definition removes it permanently from the database.

Permissions

Operation	Role	Description
Delete	InstanceDefinitionCreator	The instance definition creator can delete instance definitions.
Delete	InstanceDefinitionAdmin	The instance definition admin can delete instance definitions.

Export an Instance Definition

A user interface to export an instance definition to a JSON file. The steps necessary to export an instance definition are described below:

1. Navigate to Instance Definitions > View All Instance Definitions

2. Click on the Export (down arrow) button next to the instance definition you want to export.

   

Operations

Operation Name	Trigger	Purpose	Additional comments
Export	Export button	Export an instance definition.	Exporting an instance definition will trigger a download of the exported instance definition to a JSON file.

Permissions

Operation	Role	Description
Export	InstanceDefinitionViewer	The instance definition viewer can export instance definitions.
Export	InstanceDefinitionCreator	The instance definition creator can export instance definitions.
Export	InstanceDefinitionAdmin	The instance definition admin can export instance definitions.

Manage Instance Definition Groups

A user interface to create, edit, delete, and export instance definition groups. An instance definition group is a collection of two or more instance definitions.

The primary purpose of this functionality is to provide the ability to export multiple instance definitions to a single JSON file.

The steps necessary to manage instance definition groups are described below:

1. Navigate to Instance Definitions > View All Instance Definitions
2. Click on the Instance Definition Groups tab.

Create

1. Click on the Create (+) button at the top of the grid to create a new group.
2. Enter a name for the group.
3. Check the instance definitions that you want in the group.
4. Click on the Save button to save your changes.

Delete

1. Click on the Delete (trashcan) button next to the instance definition group you want to delete.

Edit

1. Click on the Edit (pencil) button next to the instance definition group you want to edit.
2. Check the instance definitions that you want in the group.
3. Click on the Save button to save your changes.

Export/Download

1. Click on the Export (down arrow) button next to the instance definition group you want to export.

Operations

Operation Name	Trigger	Purpose	Additional comments
Delete	Delete Button	Removes an instance definition Group.	Deleting an instance definition Group removes it permanently from the database. This does not remove any instance definitions, only the Group.
Add	Add Button	Create a brand-new instance definition Group.	The user needs to select two or more instance definitions to add to the group.
Edit	Edit Button	Edit an instance definition Group.	Editing an instance definition Group modifies the record stored in the database.
Export	Export button	Export an instance definition Group.	Exporting an instance definition Group triggers a download of the exported instance definition Group to a JSON file.

Permissions

Operation	Role	Description
Add	InstanceDefinitionCreator	The instance definition creator can add instance definition groups.
Add	InstanceDefinitionAdmin	The instance definition admin can add instance definition groups.
Edit	InstanceDefinitionCreator	The instance definition creator can edit instance definition groups.
Edit	InstanceDefinitionAdmin	The instance definition admin can edit instance definition groups.
Delete	InstanceDefinitionCreator	The instance definition creator can delete instance definition groups.
Delete	InstanceDefinitionAdmin	The instance definition admin can delete instance definition groups.
Export	InstanceDefinitionViewer	The instance definition viewer can export instance definition groups.
Export	InstanceDefinitionCreator	The instance definition creator can export instance definition groups.
Export	InstanceDefinitionAdmin	The instance definition admin can export instance definition groups.

How to use the Token Search

This section will describe what the token search is, its purpose, how to use it, and how tokens are cached and displayed in the token search.

Tokens

In RPS, tokens are used as placeholders for values which populate when the instance definition is invoked. Tokens allow items and instance definitions to be more dynamic in where values are populated during invocation.

Tokens built into RPS

There are a few tokens built into RPS that will not require a value to be passed in when invoking the instance definition. Typically, these built-in tokens are used to make an item's "Entity Name" unique, but they can be used wherever the user needs.

Fields	Definition
Entity ID	this is the ID of the item
Parent Name	this is the name of the parent item

Token Search

The token search allows the user to browse through cached tokens, eliminating the need to manually type them in each time. The tokens displayed in the token search are updated once every 60 seconds with new tokens. The token search works by checking newly created items to see if there are tokens in an item's fields or properties. It adds any new tokens to the token search. Additionally, if a user has deleted a token from the token picker and saved an item that contains that token, that token will be added back to the cached token list.

Bring up the Token Search

1. When creating/editing an instance definition item (See Creating or Editing Instance Definition Items for instructions), hover over the "Entity Name" field box, and a search icon appears.

   

   Figure 1 - Token Search Icon

   1. Click on the search icon and the Token Search will pop up and appear in the middle of the browser's window. This window will contain a search box which will enable the user to find cached tokens.

      

      Figure 2 - Token Search Window

Use the Token Search

1. The token search window displays the cached tokens, which allows the user to search for the desired token using the search bar.

   

   Figure 1 - Search Function

2. The user can select a token by hovering over the desired token, which then display 3 icons (append, copy, and delete) to the right of the token name. From this step, the user can perform the copy, append, and delete tasks. The following sections explains how to use each of the icons and their purpose:

   

   Figure 2 - Token Search Icons

Copy Token

This action copies a single token that the user chooses, and provides enough data to fill out the value for the "Entity Name" or "Property" value.

1. Click on the Copy icon of the wanted token.

   

   Figure 1 - Copy Icon

2. Then the "Token Search" window will close.

3. Paste the copied token into the field.

   

   Figure 2 - Successful Copy

Append Token

If a single token does not provide enough data to fill out the "Entity Name" or "Property" values, users may append, or add, an additional token to the instance definition.

1. Append icon of the wanted token

   

   Figure 1 - Append Icon

2. Click on the Append icon of the wanted token. This adds the newly selected token to the previous one in the clipboard. A success message appears in the bottom right of the window.

   

   Figure 2 - Successful Append Window

3. Repeat step 2 until user has appended all wanted tokens

   

   Figure 3 - Successful Append Window

4. Close the Search Box by clicking on the "close" icon or on the "cancel" button.

   

   Figure 4 - Exiting the Token Search

5. Paste the copied token into the field using CRTL + V or by right-clicking mouse and selecting "paste" in order to paste. Users see the appended tokens inside the field as show in the following figure:

      ![Completed Token Appended 5](../../../Images/REACTR/InstanceDefinitions/InstanceDefinitionsUserGuide/TokenPicker_Append_Successful_EntityName.png)
   
      Figure 5 - Successful Append in Entity Name
   

Delete Token

Note

This action does not remove the token from any existing instance definitions or instance definition items.

1. Click on the "Delete" icon to the right of the token.

   

   Figure 1 - Selecting token to delete

2. A Delete confirmation window appears in the center of the window. Click on the "Delete" button.

   

   Figure 2 - Delete Confirmation box

3. A confirmation of successful delete appears in the bottom right of the window.

   

   Figure 3 - Successful Deletion confirmation

4. The deleted token is no longer shown in the token search.

   

   Figure 4 - Successful Deletion in Token Search

Bulk Replace Tokens

Tokens can be bulk replaced in instance definition items. By using the Replace Tokens functionality, the user can specify the old token to replace and the new token that should replace it. Token search can be used for the Old Token and New Token fields.

Warning

This will update the token in all items that contain the old token.

The steps necessary to bulk replace tokens are described below:

1. Navigate to Instance Definitions > View All Instance Definition Items

2. Click on the Replace Tokens button.

   

   Figure 1 - Instance Definition Item Replace Tokens

3. Specify the value of the Old Token that you want to replace and the New Token that you want to replace it with.

4. Specify if the tokens should be replaced in the entity name and/or the properties (both checked by default).

5. Click on the Replace button to bulk replace all matching tokens.

   Important

   Old Token and New Token are required.

   

   Figure 2 - Instance Definition Item Replace Tokens Screen

6. A list will be shown of all the items that were updated during the bulk replace.

   

   Figure 3 - Instance Definition Item Replace Tokens Result

Operations

Operation Name	Trigger	Purpose	Additional comments
Replace Tokens	Replace Tokens Button	Bulk replaces the old token with the new token in the entity name and/or properties.	This will affect all items that contain the old token.

Permissions

Operation	Role	Description
Replace Tokens	InstanceDefinitionCreator	The instance definition creator has the ability to bulk replace tokens.
Replace Tokens	InstanceDefinitionAdmin	The instance definition admin has the ability to bulk replace tokens.

How to use Special Characters

Certain special characters are supported when entered in the property values for Instance Definition Items or Nodes.

Supported Special Characters

Special Character	Gets Replaced With	Description
{linefeed}	\n	A line feed means moving one line forward
{newline}	\r\n	A new line in windows is the combination of \r\n. In Linux the equivalent is usually just \n
{carriagereturn}	\r	A carriage return means moving the cursor to the beginning of the line

How to Add a Special Character to a Property Value

1. To edit an Instance Definition Item and its properties or an Instance Definition's Node and its properties follow the instructions in the sections Edit Instance Definition Items or Edit an Instance Definition.
2. When editing the value of an Instance Definition Item Property or a Node Property, you can add one or more special characters in the property value.
3. When saving the Instance Definition Item or Instance Definition (and its Node) the special characters in the property value will be replaced as specified in the table above.

Scenario: How to Create and Export an Instance Definition and its Items

This section describes an end-to-end scenario of how to create, edit, and export an instance definition and its items. Throughout this scenario there are links to various sections of this document that guides you how to accomplish each step of the workflow.

1. The first step in creating an instance definition is to create the individual items that will belong to the instance definition.
   1. Items are reusable between multiple instance definitions and can be 'templatized' by using tokens (see: Add Tokens to a Property) in any properties that may differ between instance definitions.
   2. Once an item is ready to be used in an instance definition, its item Approved should be set to 'Approved' so that further changes to it are prevented (admins can toggle this back to 'Not Approved').
   3. To create instance definition items see: Create or Edit Instance Definitions
   4. To delete instance definition items see: Delete an Instance Definition Item
      1. Since items can be reused between multiple instance definitions, you are not able to delete an item that is referenced in one or more instance definitions. These references must first be removed in order to delete the item.
2. After the instance definition items have all been created, then you can start creating the instance definition which is the template/scaffold/structure for how the individual items are used.
   1. To create instance definitions see: Create or Edit Instance Definitions
   2. To delete instance definitions see: Delete an Instance Definition
   3. To duplicate instance definitions see: Copy Instance Definitions
      1. This copies only the instance definition and its references and associations. This does not copy the actual individual items.
3. Once the instance definition has been created, then you can start configuring/building it by adding references to items.
   1. To add or remove a reference to an item see: Add or Remove Items in an Instance Definition
   2. To replace a reference to an item see: Replace Items in an Instance Definition
   3. To configure/build referenced items see: Add or Remove Items From a Referenced Item
      1. By configuring referenced items you can add children underneath the referenced item.
4. When all references to items have been added to the instance definition, you can continue configuring/building it by adding associations between referenced items.
   1. To configure/build referenced items see: Add or Remove Items From a Referenced Item
5. The last step before exporting is to verify that all your data is correct by reviewing the:
   1. Properties of instance definition
   2. Properties of instance definition items
   3. References to instance definition items
   4. Associations between referenced instance definition items
6. The final step is to export the instance definition to a JSON file.
   1. To export an instance definition see: Export an Instance Definition

Annotated Screenshot Guides

Instance Definitions Listing Annotated Guide

Create or Edit Instance Definition Annotated Guide

Instance Definition Groups Annotated Guide

Create or Edit Instance Definition Group Annotated Guide

Instance Definition Builder Annotated Guide

Add Reference to Instance Definition Annotated Guide

Add Association to Instance Definition Annotated Guide

Change a Referenced Item in Instance Definition Annotated Guide

Instance Definition Items Annotated Guide

Token Picker Annotated Guide

Glossary

Term	Definition
RPS	Rapid Provisioning System
REACTR	RPS Enterprise Automation, Configuration and Testing Routines
Instance Definition	The abstraction layer on top of existing RPS Types.
Instance Definition Reference	The assignment of the instance definition to a root resource item, which results in a set of one or more resource items to be run.
Instance Definition Association	The association between referenced items results in an assignment between resource items or resource groups to either target items or target groups. These assignments allow one-to-one, many-to-one, one-to-many, and many-to-many relationships.
Instance Definition Item	An item on the abstraction layer on top of existing RPS Types.
Instance Definition Node	An item that will result in association of an endpoint node with target items that are created when an instance definition is invoked.
Instance Definition Group	A collection of two or more instance definitions. Groups provide the ability to export multiple instance definitions to a single JSON file.