Configuring Unbound Actions
The framework supports configuring unbound actions in a domain similar to unbound functions. An unbound action is considered as an operation that can change the state of a service. Due to this, the framework supports calling an action with a POST request. After the unbound action is configured, it is invoked by a POST request to the URL <Domain Root>/<Domain Namespace>.<Unbound Action Name>. The body of the POST request contains the parameters that will be passed to the action.
An unbound action is configured in the import.json file in the same way as an unbound function, except for the following differences:
• An unbound action is specified in the actions collection property in the import.json file.
• When the action is specified in the import.json file, the property includeInServiceDocument is not applicable to actions. This is because actions cannot be included in the service document available at the domain root.
• The action names defined in the import.js file start with action_.
The properties of an unbound action are specified in the import.json file of the domain. In the file, under actions, specify the following properties:
• name—Name of the unbound action, defined in camel case.
• importName—Name of the ActionImport. This is the name that will be in the URI when the unbound action is invoked. For more details about action imports, see the
OData specifications.
• description—Short description of the action. The value is displayed as an annotation (Core.Description) in the EDM.
• isReadOnlyAction—Specifies that the action is read-only and it does not change the state of the service. Default is false. For more information, see Read-only Actions.
• isPageable—Specifies that the action supports paging. Default is false. When set to true, the action must be read-only. If set to true, clients must pass the PTC-EnablePagination header to get the results paged. For more information, see Paging on Actions.
• parameters—JSON array specifying the list of parameters for the unbound action. Each parameter has the following configuration options:
◦ name—Name of the parameter in camel case.
◦ type—OData type of the parameter. It can be an OData primitive, complex type, or entity.
◦ isNullable—Specifies whether the parameter can be omitted in the request.
◦ isCollection—Specifies whether the parameter takes one (false) or multiple (true) values.
• returnType—OData type returned by the action. Specify the following properties for the return types:
◦ type—OData type returned by the action. Can be an OData primitive, complex type, or entity.
◦ isNullable—Specifies if a property can be set as null. The default value is set to false.
◦ isCollection—Specifies whether the action returns one (false) or multiple (true) values.
Paging on Actions
The configuration property isPageable is used to configure an action as pageable. When it is set to true, the action supports paging. The action is rerun, and the result is navigated to the requested page. This configuration option should be used only for actions that can be safely rerun (that is, the action does not modify data) and return a flat list. The default is false.
Example
"actions":
{
"name": "Preview",
"importName": "Preview",
"description": "Generates a preview of the business administrative data changes that meet the specified criteria.",
"isComposable": false,
"isPageable": true,
"parameters": [
{
"name": "types",
"type": "String",
"isCollection": true
},
{
"name": "startDate",
"type": "DateTimeOffset"
},
{
"name": "endDate",
"type": "DateTimeOffset"
}
],
"returnType": {
"type": "PTC.BACMgmt.Delta",
"isCollection": true
}
}
A new request header type Boolean PTC-EnablePagination is introduced. When the header is set to true, the response returned to the client is paginated.
For actions marked as pageable, the action is rerun, and the result is navigated to the requested page.
URI
POST / Windchill/servlet/odata/BACMgmt/Preview HTTP/1.1
Request Header
Make a request with a new request header PTC-EnablePagination set to true. The result returned to the client will be paginated, as specified in the odata.maxpagesize Prefer header. The new request header PTC-EnablePagination by default is set to false to avoid breaking existing clients.
Content-Type: application/json
CSRF_NONCE:<Use the value from Fetch NONCE example>
Prefer: odata.maxpagesize=1000
PTC-EnablePagination: true
Request Body
{
"types": [
"Preference"
],
"startDate": "2022-09-01T00:00:00.000Z",
"endDate": "2022-09-14T00:00:00.000Z"
}
Response
{
"@odata.context": "http://<host>:<port>/Windchill/servlet/odata/BACMgmt/$metadata#Collection(PTC.BACMgmt.Delta)",
"@PTC.AppliedContainerContext.LocalTimeZone": "GMT",
"value": [
{
"oid": "wt.preference.PreferenceInstance:262931",
"type": "Preference",
"localizedType": "Preference",
"context": "Site",
"name": "Default cache vault created",
"description": null,
"details": [
{
"key": "Value",
"value": "true"
},
{
"key": "Locked",
"value": "true"
},
{
"key": "Client",
"value": "Windchill"
}
],
"modifiedDate": "2022-09-12T14:46:40Z",
"localizedModifiedDate": "2022-09-12 14:46:40 GMT",
"modifiedBy": null,
"action": "Create"
},
{
"oid": "wt.preference.PreferenceCategoryDefinition:115478",
"type": "Preference",
"localizedType": "Preference",
"context": null,
"name": "Link [Include related Parts - Collector]",
"description": null,
"details": [
{
"key": "Object Type",
"value": "Link [Defintion - Category]"
},
{
"key": "Internal Name",
"value": "Link [MANAGED_COLLECTION_COLLECTOR_CATEGORY.AddToManagedCollection.ASSOCIATED_WTPART.default.option.id - MANAGED_COLLECTION_COLLECTOR_CATEGORY]"
}
],
"modifiedDate": "2022-09-12T14:37:29Z",
"localizedModifiedDate": "2022-09-12 14:37:29 GMT",
"modifiedBy": null,
"action": "Create"
}
],
"@odata.nextLink": "http://<host>:<port>/Windchill/servlet/odata/BACMgmt/Preview?$count=true&$skiptoken=1000"
}
Read-only Actions
Read-only actions are actions that do not change the state of the service and, therefore, do not have any side effect. Typically, read-only actions are implemented as functions, but they require parameters to be passed in the request body, as opposed to the URL parameters.
For example PTC.ProdMgmt.GetPartStructure is a read-only action and PTC.ProdMgmt.UpdateParts is not a read-only action.
A new Boolean JSON configuration element isReadOnlyAction is introduced for actions. If this element is not specified, then the default will be false, as the OData specification assumes that actions may have side effects (https://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part1-protocol.html#sec_Actions).
When this flag is set, the framework treats the request similar to a GET request.
This typically improves performances for read-only actions in CADDocumentMgmt, EffectivityMgmt, and ProdPlatformMgmt domains.
|
|
Actions that create/update/delete data MUST NOT be flagged as read-only.
|
