ON THIS PAGE:
This article describes how to create entities using P2 Server Management or the Import/Export spreadsheet. For general information on entities, see: Entities, the Backbone of all Data.
Every now and then, you will need to add a new asset to your system. In P2 Server, these are known as entities. Configuring an entity is a crucial step in setting up a system to model your assets. You can configure an entity using Server Management or the Import/Export spreadsheet.
Before you start, spend some time thinking about where this entity sits in your asset model, which templates you want to use, and what are the attribute values you want to retrieve.
Server Management
In P2 Server Management, fully configuring an entity requires 4 main steps, all performed through the Entities menu option:
- Adding the entity.
- Assigning the templates.
- Configuring the attribute values.
- Assigning the primary templates.
The only prerequisite is that you must have already created the templates you intend to use.
Adding the Entity
1. Open P2 Server Management, and click the Entities icon.
2. Click Create New Entity.
Note: If you want to edit an existing entity, select it from the list below the Create button.
3. Give the entity a name, display name, and a description. Note that the name cannot contain reserved characters. For the description, it's often useful to provide a broader explanation of the asset that is represented by this entity.
4. Click the Save button in the top right corner.
After you have saved, the Assigned Templates menu item becomes active.
Assigning the Templates
For this next step, you must have already created a template. You will now assign a template to this entity. This will enable all of the attributes associated with that template to be passed on to the entity. The entity will then be responsible for populating the attributes with actual values for that specific entity.
Before you move to the next step, make sure you know what all your applicable templates are, and which is to be primary.
5. Click Assigned Templates.
6. Click the Add button next to Templates.
7. Add as many templates as you need. Only templates that have already been added to the system will be available. Each template you add is known as a template instance.
First, select them from the drop-down list, and then assign date ranges for when they apply. Date ranges may overlap. As you add the templates, you will notice the Timeline being updated.
8. Click the Save button.
Video
Configuring Attribute Values
You will notice that the template instances now have a drop-down arrow next to each of them.
This is where you configure where the attributes will retrieve their values from for this entity. So while a Water Injection Well may already have an attribute for Bottom Hole Pressure, the entity still needs to pull that attribute value from somewhere. This is where you configure that.
Note: If you want your templates and attributes to be time-aware, you should assign the template date ranges and save them before assigning attribute values. Otherwise, an error will occur when inserting the attribute values due to clashing dates. For time-aware templates and attributes, skip straight to Time Awareness below.
You will need to perform the following step for each template instance, if you want the attribute to produce a value.
9. Click the drop-down arrow next to the template.
The template section expands to show the fast editor for assigning attributes. On the left of the screen is a list of tags and calculations, and on the right is the list of attributes in the template.
10. Assign a tag or calculation to an attribute by dragging and dropping from the left to the right.
Note: By assigning attribute values this way, P2 Server will take the current value of the tag and will assign it to the attribute with an undefined time range.
Video
11. When you have finished configuring your attribute values, click Save in the top right corner.
You have now configured simple attribute values.
Time Awareness
If you need to add time awareness to your templates and attributes, you will need to use the full editor for assigning attributes.
First, ensure that your templates are time-aware by assigning date ranges to them, and remember to save before proceeding. Note how the timeline changes as you add the dates.
The steps for assigning time-aware attribute values will be shown in the next video. Here are the key points:
- Expand the template in order to assign values to attributes.
- Note that if the template has not been assigned to the current date/time, the fast editor for assigning attributes is not available.
- Click the edit
icon for the attribute to assign a value and date.
- As attributes are also time-aware, the Attribute Values page contains a timeline view similar to the one on the templates page.
- For each of the attributes to which you want to assign values, click the Add button. You can add as many attribute values as necessary.
- An attribute can have a number of values, and they can be of different types. For example, for one date range you may want the attribute to have a fixed value and for another date range you may want the attribute to get its value from a tag.
- Note also that the time ranges available for an attribute are tied to the time range of the template instance, and cannot extend beyond the template instance's start or end times. Date ranges for individual attribute values cannot overlap.
Remember to save before proceeding.
Assigning Primary Templates
The steps for assigning a primary template will be shown in the next video. Here are the key points:
- Only the templates you added in the previous step will be available for adding as a primary template.
- You should assign at least one primary template. The date range for the primary template must also fall within the date range of the template instance.
E.g. If you choose Oil Producing Well for the primary template, the applicable primary date range must not end after 21st August 2017. - If the template you choose has an end date, it will automatically be entered for you.
- You may change the end date so that it occurs earlier, but it cannot occur later.
- As you add the primary template, you will notice the timeline automatically update to reflect your changes.
- When you have finished assigning templates, click the Save button in the top right corner.
Video
After saving, the fast editor for the current active template is available from the Entity Overview page, and you can continue to assign attribute values from there ( watch video).
Done! After completing the above steps, you will have a properly configured entity.
You should now add the entity to a hierarchy so you can include it in an asset model.
Editing Attribute Values
If you need to change the attribute values for the current time, you can do so using the fast editor from the Entity Overview page. During editing, a window will appear with options on how to assign the tag.
There are two options:
- Assign the following times - specify a date and time for which the new tag applies
- Override current - replace the tag with a new tag
Changing the Current Value
The steps for changing the current value of an attribute will be shown in the next video. Here is a quick summary:
1. Open the entity's Overview page.
2. In the Attributes section, drag and drop a tag or calculation from the left onto the attribute on the right.
When you release the mouse button, the 'How do you want to assign this tag' window appears.
3. The selection defaults to 'Assign the following times', however as we just want to replace the existing tag, choose the Override current option.
4. Click Done.
5. Click Save at the top of the Overview page.
Time Awareness
The steps for assigning date ranges to your attribute values are the same as for changing the current value (see above). However in Step 3, keep the default selection in the 'How do you want to assign this tag' window, and assign a date range instead.
Key points:
- Set the start time on the left and the end time on the right.
- Click the calendar
icon to set the date, and click the clock
icon to set the time.
- You may leave the end time blank, in which case this tag will be assigned from now on, until it is changed.
- You cannot assign an end time which is earlier than the start time.
- Click the clear
icon to reset the end time to blank.
Remember to click Save at the top of the Overview page when you have finished.
Note: The entity's Overview page will always show the current value of the attribute.
If you assign tags to an attribute for a time in the future, subsequent changes to the attribute value will need do be done using the full editor.
Import/Export Spreadsheet
The Import/Export spreadsheet is generally only used to make bulk changes, but it provides access to some advanced functionality not currently available through Server Management.
If you want to configure entities as part of a bulk configuration, you need to use several tabs in the Import/Export spreadsheet:
- Entity
- Template Instance
- Attribute Value
Look for the red comment icon in the row headers, to get help with each column.
DO NOT fill in or change anything in the Global Id field – this is the unique identifier for the entity, template instance, and attribute values, that allow them to be tracked across systems, and when anything is renamed. It is automatically generated by the system.
Entity Tab
The screenshot below shows an example of the basic definition for an entity (click to enlarge).
There are 2 important parts to this sheet: the Entity and the System Identifiers.
Let's first look at the Entity. Each entity is on a different row, and each entity has a Name, Display Name, and Description. These fields may also be configured through Server Management.
Now, let's focus on the 3B-2A-8 entity on row 3, and scan across to look at columns E-G. These columns define the system identifiers that allow a set of names to be mapped between an entity in P2 Server and the corresponding asset in an external system. Currently, you cannot do this using Server Management, this must be done through the Import/Export spreadsheet.
To add more system identifiers for an entity, you need to add more repeating sections like E-G. If you look at columns H-J, you will see that they add another system identifier - this time for P2 EU. This means that the entity is available in 2 other systems, and P2 Server is to treat them as the same entity.
You can add as many system identifiers as you need to, by adding more repeating sections like columns E-G.
Dependencies
The Entity tab has a direct dependency on information from the System tab, because a column on the Entity tab directly references a column on the System tab.
This column | On this tab | Why you need to pay attention |
Name | System | Required by the 'System' column on the 'Entity' tab. |
Here is a diagram of the dependent tabs and columns:
Template Instance Tab
The screenshot below shows an example of a template instance, which connects a template with an entity for designated periods of time (click to enlarge).
There are 2 important parts to this sheet: the Template Instance and the Primary Time Periods.
Let's first look at the Template Instance. Each template instance is on a different row, and each instance has an Entity, Template Definition, Start Time, and End Time. The same rules apply here as when you add a template instance in Server Management. If you look carefully at rows 2498-2500, you can see that these are the template instances configured in Server Management, using the above instructions on this page.
Now, let's focus on the 3B-2A-8 entity on row 3, and scan across to look at columns F-H. These columns define the time periods that this instance is the primary template.
To add more primary time periods for the template instance, you need to add more repeating sections like F-H. If you look at columns I-K, you will see that they add another time period for which the template is considered the primary template for that entity.
You can add as many primary time periods as you need to, by adding more repeating sections like columns F-H. Make sure that, for each template definition, the primary time periods do not overlap.
Dependencies
The Template Instance tab has dependencies on the following tabs: System, Entity, Link Group, Link, Image Group, Image, Template Group, and Template Definition.
Direct Dependencies
The Template Instance tab is directly dependent on information from the following tabs: Entity and Template Definition.
This column | On this tab | Why you need to pay attention |
Name | Entity | Required by the 'Entity' column on the 'Template Instance' tab. |
Name | Template Definition | Required by the 'Template Definition' column on the 'Template Instance' tab. |
Cascading Dependencies
A cascading dependency exists when a dependent tab (above) has additional dependencies. Several important dependencies exist for the Entity and Template Definition tabs. These are the columns that you need to pay attention to:
This column | On this tab | Why you need to pay attention |
Name | System | Required by the 'System' column on the 'Entity' tab. |
Name | Template Group | Required by the 'Template Group' column on the 'Template Definition' tab. |
Name | Link Group | Required by the 'Link Group' column on the 'Template Definition' tab. |
Name | Link | Required by the 'Link Name' column on the 'Template Definition' tab. |
Name | Image Group | Required by the 'Image Group' column on the 'Template Definition' tab. |
Name | Image | Required by the 'Image Name' column on the 'Template Definition' tab. |
Here is a diagram of the dependent tabs and columns for Template Instances. Use this to help you visualise how the dependencies work, and ensure all required columns are completed. Use the comments inside the spreadsheet to help you.
Attribute Value Tabs
To enter attribute values for an entity, the import spreadsheet must have an AV_ tab for each template. These tabs are automatically generated when you export a template or when you export the configuration data. Note that the tabs will only be generated when a template has an attribute; templates with no attributes do not have these tabs auto-generated during an export.
The screenshot below shows an example of an attribute value tab, which associates a real-world value with an attribute on a template, when it is assigned to an entity (click to enlarge).
Key Points:
When filling in these tabs, keep the following in mind:
- One AV_ tab per template
- Enter each entity on a separate row for each template instance
- Enter each attribute value definition for an entity in a repeating section
- Only required for templates with attributes
Dependencies
The AV_ (Attribute Value) tab has dependencies on all tabs except for the Hierarchy and Hierarchy Relationship tabs. You should therefore pay special attention to all tabs when editing attribute values.
Direct Dependencies
The AV_ tab is directly dependent on the Entity, Template Definition, and Attribute Definition tabs, because columns on the Attribute Value tab directly reference columns on those tabs.
This column | On this tab | Why you need to pay attention |
Name | Entity | Required by the 'Entity' column on the AV_ tab. |
Name | Template Definition | Required by the AV_ tab to define the object type in cell A1. |
Name (Attribute Definition object type) | Attribute Definition | Required by the AV_ tab to define the attribute definition in cell B1 and in repeating sections. |
Name (Attribute Value Definition object type) | Attribute Definition | Required by the AV_ tab to define the attribute value definition in cell B1 and in repeating sections. |
Other dependencies also exist, depending on the Data Type selected in the AV_ sheet.
If the Data Type is Tag, you will also need to check the dependencies for the Tag and Calculation Tag objects, as follows:
This column | On this tab | Why you need to pay attention |
Start Time End Time |
Template Instance | Must match the 'Start Time' and 'End Time' columns for the template instance on the AV_ tab |
Name | Calculation Tag | Forms the Calculation Tag object and is required by the 'Value' column on the AV_ tab |
Name | Tag | Forms part of the Tag object and is required by the 'Value' column on the AV_ tab |
Tag | Tag Property | Forms part of the Tag object and is required by the 'Name' column on the 'Tag' tab |
Name | Datasource | Required by the 'Datasource' column on the 'Tag' tab |
Datasource | Datasource Parameter | Forms part of the Datasource object and is required by the 'Datasource' column on the 'Tag' tab |
Name | Digital State Set | Required by the 'Digital State Set' column on the 'Tag' tab and 'Calculation Tag' tab |
Datasource | Digital State Set | Required by the 'Digital State Set Datasource' column on the 'Tag' tab and 'Calculation Tag' tab |
Plain Symbol | Unit | Required by the 'Unit' column on the 'Tag' tab and 'Calculation Tag' tab |
If the Data Type is Dataset, you will also need to check the dependencies for the Dataset object, as follows:
This column | On this tab | Why you need to pay attention |
Start Time End Time |
Template Instance | Must match the 'Start Time' and 'End Time' columns for the template instance on the AV_ tab |
Name | Dataset | Forms part of the Dataset object and is required by the 'Value' column on the AV_ tab |
Dataset | Dataset Parameter | Forms part of the Dataset object and is required by the 'Value' column on the AV_ tab |
Dataset | Dataset Parameter Value | Forms part of the Dataset object and is required by the 'Value' column on the AV_ tab |
Name | Datasource | Required by the 'Datasource' column on the 'Dataset' tab |
Datasource | Datasource Parameter | Forms part of the Datasource object and is required by the 'Datasource' column on the 'Dataset' tab |
Cascading Dependencies
A cascading dependency exists when a dependent tab (above) has additional dependencies. Several dependencies exist for the Entity, Template Definition, Attribute Definition, and Digital State tabs:
This column | On this tab | Why you need to pay attention |
Name | System | Required by the 'System' column on the 'Entity' tab. |
Name | Template Group | Required by the 'Template Group' column on the 'Template Definition' tab. |
Name | Link Group | Required by the 'Link Group' column on the 'Template Definition' tab. |
Name | Link | Required by the 'Link Name' column on the 'Template Definition' tab. |
Name | Image Group | Required by the 'Image Group' column on the 'Template Definition' tab. |
Name | Image | Required by the 'Image Name' column on the 'Template Definition' tab. |
Name | Template Definition | Required by the 'Template Definition' column on the 'Attribute Definition' tab. |
Name | Attribute Group | Required by the 'Attribute Group' column on the 'Attribute Definition' tab. |
Name | Digital State Set | Required by the 'Digital State Set' column on the 'Digital State' tab |
Here is a diagram of the dependent tabs and columns for Attribute Values. Use this to help you visualise how the dependencies work, and ensure all required columns are completed. Use the comments inside the spreadsheet to help you.
Release History
- Configuring Entities 4.5.1 (this release)
- Fast attribute editor added to P2 Server Management
- Attribute Value tab in import spreadsheet has been pivoted
- Configuring Entities 4.4.0