Business Object Operations

Enterprise Objects > Enterprise Operations > CygNet Business Object Operations > Business Object

Business Object Operations

Read Operations	Description
GetObjects	Retrieves Business Objects for a given interface.
GetObjectAttributeHistory	Returns history records for a specified business object.

Write Operations	Description
UpdateObjects	Updates a list of business objects, identified by their object keys.

GetObjects

The GetObjects operation retrieves Business Objects for a given Business Object Interface.

The Request must include the following.

Either a filter or a list of keys to indicate which objects to retrieve
A list of attributes to export
A list of parameters as applicable (i.e. point-in-time)

The Response will include the following.

All requested attributes for all Business Objects that meet the selection criteria
Any errors that occurred

The Request and Response must validate against an Enterprise Operations EIE schema.

Optional Attributes

If a request includes an attribute defined as optional, then the attribute will be included in the operation. If the attribute does not exist (is not mapped, or is mapped to a point that does not exist) the operation for that object will fail, and an error will be reported in the response. Use the "ReportMissingOptionalData" parameter to change this default behavior as described in the following table of child elements.

Usage

The following table lists and describes all of the child elements of the request node (<GetObjectsReq>).

Element Name	Required	Description
AllowPartialFailure	No	If this element is set to true, the operation will log an error and continue to run if it fails to retrieve an object. Otherwise, the operation will terminate immediately upon failing to retrieve an object.
KeyList*	No*	A list of keys which uniquely identify the objects to be retrieved.
AttrFilter*	No*	A set of rules to filter the returned objects by required interface components.
AttrsToExport	No	Includes a list of object attributes to include in the response.
Parameters	No	“PIT” defines the optional point-in-time for which to retrieve objects.
Parameters	No	If a request for data includes optional attributes which do not exist for a given target object, the default behavior is to report an error in the response. "ReportMissingOptionalData" provides optional alternatives to the default behavior. Options are as follows. Error (default) Warning Ignore

* Note: One (and only one) of KeyList or AttrFilter must be specified.

Filter

Objects may be filtered by using the <AttrFilter> element. The attribute filter node must contain a set of rules to filter the objects which will be returned by this operation. The filter may consist of a hierarchy of expressions using the <MultiExpr> and <SingleExpr> tags. The following example will filter all objects for which CasingPressure.Timestamp is greater than four days ago AND WellID is greater than 1001.

<CasingPressure.Timestamp>d-4 H=0 M=0 S=0</CasingPressure.Timestamp>

</SingleExpr>

</SingleExpr>

</MultiExpr>

</AttrFilter>

Examples

Request

The following example represents a request which filters objects by a list of keys.

<?xml version="1.0" encoding="utf-8"?>

<CygNetEnterpriseOperations

xmlns="https://CygNetSCADA.com/Schemas/BusinessObjects/TestPackage_CHK_Well">

<Key>

</Key>

<Key>

</Key>

</KeyList>

</AttrsToExport>

</GetObjectsReq>

</CygNetEnterpriseOperations>

The following example represents a request which filters objects by attributes.

<?xml version="1.0" encoding="utf-8"?>

<CygNetEnterpriseOperations

xmlns="https://CygNetSCADA.com/Schemas/BusinessObjects/TestPackage_Well">

<CasingPressure.Timestamp>d-4 H=0 M=0 S=0</CasingPressure.Timestamp>

</SingleExpr>

</SingleExpr>

</MultiExpr>

</AttrFilter>

<CasingPressure.Value/>

<CasingPressureL4D.Value/>

</AttrsToExport>

</Parameters>

</GetObjectsReq>

</CygNetEnterpriseOperations>

Response

The following example represents a successful response.

<?xml version="1.0" encoding="UTF-8"?>

<CygNetEnterpriseOperations

xmlns="https://CygNetSCADA.com/Schemas/BusinessObjects/TestPackage_Well">

<Well>

<Key>

</Key>

<CasingPressure.Value>20</CasingPressure.Value>

<CasingPressureL4D.Value>70</CasingPressureL4D.Value>

</Well>

</Objects>

</GetObjectsResp>

</CygNetEnterpriseOperations>

The following example represents an unsuccessful response.

<?xml version="1.0" encoding="UTF-8"?>

<CygNetEnterpriseOperations

xmlns="https://CygNetSCADA.com/Schemas/BusinessObjects/TestPackage_CHK_Well">

<OperationResult type="ERROR" code="50209">No associated FAC found for CYGDEMO.UIS</OperationResult>

</OperationResults>

</GetObjectsResp>

</CygNetEnterpriseOperations>

GetObjectAttributeHistory

The GetObjectAttributeHistory operation retrieves historical data for a single simple attribute, point, or set of point attributes of a given Business Object instance.

If history is requested for a point element, then all attributes for that point element will be returned for the desired historical range.

Note: History cannot be retrieved for attributes that do not support history. Simple elements that are mapped to facility attributes or point configuration attributes do not support history.

Example

If a simple attribute such as "operator" is mapped to a facility attribute, then this attribute will not support history. If "operator" is mapped to a real-time point value however, then history can be retrieved for the attribute.

Use a set of history parameters included in the request to specify rollup information, the time range to retrieve, and the maximum number of entries to include in the response. If the number of entries to be returned exceeds the maximum specified, the response XML will include a special element with continuation information. To continue the operation, the same request must then be repeated, with the additional inclusion of the continuation element from the last request. The return XML will indicate success or failure.

Usage

The following table lists and describes all of the child elements of the request node (<GetObjectAttributeHistoryReq>).

Element Name	Required	Description
Key	Yes	The key which uniquely identifies the object for which to retrieve attribute history.
AttrToExport	Yes	The attribute for which to retrieve history.
HistoryParameters	Yes	A set of parameters which specify the maximum number of entries to return, the time range for entries to retrieve, rollup information, and, if applicable, the time of the next entry to retrieve (if the request is a continuation from a previous request).

Examples

Request

The following example represents a request containing continuation information returned from a previous response.

<?xml version="1.0" encoding="utf-8"?>

<CygNetEnterpriseOperations

xmlns="https://CygNetSCADA.com/Schemas/BusinessObjs/TestPackage1_Well">

<Key>

<Field>TEXAS_5346</Field>

</Key>

</AttrToExport>

<RollupUnits>Hours</RollupUnits>

</NextEntry>

</HistoryParameters>

</GetObjectAttributeHistoryReq>

</CygNetEnterpriseOperations>

Response

The following example represents a successful response.

<?xml version="1.0" encoding="utf-8"?>

<CygNetEnterpriseOperations

xmlns="https://CygNetSCADA.com/Schemas/BusinessObjs/TestPackage1_Well">

<Operator>Michael Scott</Operator>

</AttrHistoryEntry>

</NextEntry>

</GetObjectAttributeHistoryResp>

</CygNetEnterpriseOperations>

The following example represents an unsuccessful response.

<?xml version="1.0" encoding="UTF-8"?>

<CygNetEnterpriseOperations

xmlns="https://CygNetSCADA.com/Schemas/BusinessObjects/TestPackage_CHK_Well">

<Key>

</Key>

<OperationResult type="ERROR" code="50209">No associated FAC found for CYGDEMO.UIS</OperationResult>

</OperationResults>

</GetObjectAttributeHistoryResp>

</CygNetEnterpriseOperations>

UpdateObjects

Note: Optional attributes retrieved with GetObjects can be updated with UpdateObjects.

The UpdateObjects operation is used to update a list of objects, identified by their unique object keys.

The Request must include the following.

The unique object Key
A list of one or more Attribute-Value pairs to update

The list of attributes need not cover all configured attributes for the object.

If an attribute is not included in the update list, then that attribute must not be directly modified.

Note: Some attributes can be modified indirectly, for example point state or point timestamp.

Historical Value Mode Updates

Selecting "Historical Value mode" Updates results in the following.

Real-time record updates will be processed in the CVS.
Updates will not be reflected as the "current value" in the CVS.
Updates will be transmitted from the CVS to the VHS.
Updates will not be transmitted from the CVS to the GNS and CAS.

Notes:

The mapped point targeted by the historical value update must be configured to "report to VHS"; otherwise the update for the associated object will fail.

The update must include an attribute that is mapped to the Real-time Record (RTR) value; otherwise the update will fail.

"Historical Value mode" Updates allow the following.

Future timestamps. If a timestamp is provided for the mapped point, then the timestamp will be used. If a timestamp is not provided in the update, then the mapped relative time adjustment will be applied to the current time in order to calculate the timestamp to apply to the update.
Updates to Interface components. Interface components (both point instances and flattened point attributes) that have been mapped with a relative Point-in-Time (PIT) adjustment can be updated in Historical mode.

Current Value Mode Updates

Selecting "Current Value mode" Updates results in the following.

The standard setpoint message is issued.

"Current Value mode" Updates allow the following.

Timestamps. If a timestamp is provided for the mapped point, then the timestamp will be used. If a timestamp is not provided in the update, then the mapped relative time adjustment will be applied to the current time in order to calculate the timestamp to apply to the update.
Updates to Interface components (both point instances and flattened point attributes) that have been mapped with a relative Point-in-Time (PIT) adjustment.

Attributes

Optional Attributes

Optional attributes can be updated with UpdateObjects. If an UpdateObjects request includes an optional attribute, then the attribute will be updated. If the attribute does not exist (is not mapped, or is mapped to a point that does not exist) the update for that object will fail and will generate an error.

Writable Attributes

The administrator can configure interface components as either read-only or writable. The default is read-only. Optional interface components can be writable.

Note: A writable interface component must not be mapped to an implicitly read-only CygNet native attribute (i.e. point state description).

Table-driven Attribute Descriptions

Table driven attribute descriptions are updatable via the UpdateObjects operation. A description update must be looked up in reverse in the TRS; if the description does not have an associated table entry, then the update will fail for the object in question. If the associated table entry for the provided description is found, then the PNT/FAC record will be updated with the table entry.

Point Status Bits

The PointStatus attribute is not writable; all point status/user bits are writable, however. If an object update occurrence includes a status bit update for a bit that is "enabled" (configured for CVS calculations), then the update will include an error for the object in question.

Usage

The following table lists and describes all of the child elements of the request node (<UpdateObjectsReq>).

Element Name	Required	Description
AllowPartialFailure	No	If this element is set to true, the operation will log an error and continue to run if it fails to update an object. Otherwise, the operation will terminate immediately upon failing to update an object.
HistoricalMode	No	Specifies whether or not “Historical Value mode” will be used. If this element is set to “No” or if it is not included in the request, “Current Value mode” will be used. See Historical Value Mode Updates and Current Value Mode Updates for descriptions of these two modes.
Objects	Yes	A list of object keys (<Key>) paired with writable attributes to update.

Examples

Request

<?xml version="1.0" encoding="utf-8"?>

<CygNetEnterpriseOperations

xmlns="https://CygNetSCADA.com/Schemas/BusinessObjects/TestPackage_Well">

<AllowPartialFailure>false</AllowPartialFailure>

<Well>

<Key>

</Key>

<Description>New description</Description>

</Well>

<Well>

<Key>

</Key>

<CasingPressure.Value>3</CasingPressure.Value>

<CasingPressureL4D.Value>4</CasingPressureL4D.Value>

</Well>

<Well>

<Key>

</Key>

<CasingPressure_Value>3</CasingPressure_Value>

</Well>

</Objects>

</UpdateObjectsReq>

</CygNetEnterpriseOperations>

Response

The following example represents a successful response.

<?xml version="1.0" encoding="utf-8"?>

<CygNetEnterpriseOperations

xmlns="https://CygNetSCADA.com/Schemas/BusinessObjects/TestPackage_Well">

</UpdateObjectsResp>

</CygNetEnterpriseOperations>

The following example represents an unsuccessful response.

<?xml version="1.0" encoding="UTF-8"?>

<CygNetEnterpriseOperations

xmlns="https://CygNetSCADA.com/Schemas/BusinessObjects/TestPackage_Well">

<OperationResult type="ERROR" code="50812">Key 'WellID=0' does not resolve to an object for interface 'Well'</OperationResult>

</OperationResults>

</UpdateObjectsResp>

</CygNetEnterpriseOperations>