AF TagDefinition

By using the AF TagDefinition activity, you can retrieve tag definitions from the PI server, modify tag definitions, and create new tags into the PI server.

General

In the General tab, you can specify the name of the activity in the process, establish a connection to the PI AF server, and select what type of operation you want to perform.

The following table lists the fields in the General tab of the AF TagDefinition activity:

Field Module Property? Description
Name No A unique name of the activity in a process.
Server Connection Yes The PI AF shared resource selected to connect to a PI AF server.

Click the icon to select an OSIsoft PI System AF connection resource. If no matching OSIsoft PI System AF connection resource is found, click Create Shared Resource to create one.

Operation No The type of operation you want to perform:
  • getTagDefinitions: retrieves tag definitions.
  • upsertTags: creates or modifies tag definitions.

Description

In the Description tab, you can type a short description for the AF TagDefinition activity.

Input

In the Input tab, you can specify the tag that you want to retrieve, modify, or create for the AF TagDefinition activity.

Input elements in this tab are different depending on the operation you select in the General tab:

Input items for getTagDefinitions.

The following table provides descriptions of the input items for the getTagDefinitions operation.

Input Item Data Type Required Description
requestHeader Complex No The request message header.

For descriptions of all the attributes in this element, see Attributes in requestHeader.

filterExpression String Yes The expression used for filtering the returned tag definitions.
The expression format must correspond with the method you specify in the useMethod element. For example, to get all tags starting with a:
  • If the useMethod element is set to useGetPoints, type "a*" in this field.
  • If the useMethod element is set to useGetPointsSql, type "tag:a*" in this field.
useMethod String No The filtering method used to evaluate the filtering expression in the filterExpression element.

Enter one of the following methods in this field:
  • useGetPoints (default): the method that uses PI server specific syntax.
  • useGetPointsSql: the method that uses SQL-like syntax.
Input items for upsertTags.

The following table provides descriptions of the input items for the upsertTags operation.

Input Item Data Type Required Description
requestHeader Complex No The request message header.

For descriptions of all the attributes in this element, see Attributes in requestHeader.

tagList Complex Yes The list of tag definitions that you want to create or modify.
whenExistsModify Boolean No The parameter that specifies the tag definitions to be either created or modified.
  • If it is set to false, the tag definitions are to be created.
  • If it is set to true, the tag definitions are to be modified.

By default, the value in this field is false.

Output

In the Output tab of the AF TagDefinition activity, you can find the results corresponding to your inputs.

The output elements in this tab are different depending on the operation name you select in the General tab.

Note: All the time is in UTC time zone.

The following table lists the output items for the getTagDefinitions and upsertTags operations:

Output Item Data Type Description
If you select the getTagDefinitions operation, the following output items are available:
responseHeader Complex The response message header.
tagDefinitionList Complex The list of tag definitions that match the provided filtering expression returned by the PI server.

For descriptions of all the attributes in this item, see Attributes in tagDefinitionList.

If you select the upsertTags operation, the following output items are available:
responseHeader Complex The response message header.
failureList Complex A list of tags that are operated in the wrong way.
pointsCreated Integer The number of tags that are successfully created.
pointsModified Integer The number of tags that are successfully modified.

Fault

In the Fault tab, you can find the error messages and error codes of the AF TagDefinition activity. For more information about errors, see Error Codes.

The following table lists the error schema elements in the Fault tab:
Element Name Data Type Description
msg String Displays the error message.
msgCode String Displays the error code.