introspectResourcesTask
Create a server task to introspect a data source.
Introspection is the process of analyzing native resources in a data source and creating resources within the TDV that represent them. The introspection plan provides details on what exactly should be introspected. This includes resources to be added, updated, or removed; whether to update all previously introspected resources; introspection attributes for individual resources; and other options.
ntrospection attributes for individual resources need only be provided if any of the introspection attributes for a particular resource have changed. Otherwise, the previously used attributes (if available) or defaults can be used.
The introspection plan contains a list of introspectionPlanEntries. For each entry the following needs to be specified:
• resourceId: The path, type, and subtype of the resource to be introspected. Resource paths are relative to the data source. An empty path, for example, identifies the data source itself.
• action:
— ADD_OR_UPDATE: The resource is added if it does not already exist. Otherwise it is updated.
— REMOVE: The resource is removed if it exists.
Data sources cannot be removed. Use
destroyResource to remove a data source.
— ADD_OR_UPDATE_RECURSIVELY: Not supported.
• attributes: List of introspection-specific attributes to apply during introspection. If a specific attribute is not specified, the attribute that was used during the previous introspection is used. If the resource has not previously been introspected, the default value for that attribute is used.
If the plan’s failFast option is TRUE, the introspection fails when the first error occurs. Otherwise the plan runs to completion as a best effort. The default is FALSE.
If the plan’s commOnFailure option is TRUE, the introspection commits whatever it can. If fastFail is also TRUE, only resources successfully introspected up to that point are committed. The default is FALSE.
If the plan’s autoRollback option is TRUE, the introspection task rolls back rather than being committed. This supersedes all commit options. This allows you to perform a dry run of resource introspection. If autoRollback is TRUE, you can use
introspectResourcesResult. If autoRollback is FALSE or unset, the introspection is not automatically rolled back.
If the plan’s scanForNewResourcesToAutoAdd option is TRUE, the introspection task scans for native resources that have been newly added to the data source. If a newly added resource is found and its parent container has the autoAddChildren introspection attribute set, that child is automatically introspected.
This operation returns a taskId that can be used to get results using introspectResourcesResult, or canceled using
cancelServerTask.
This operation returns the number of resources that are added, removed, or updated in the totalResults element. The totalResults element does not exist until the full total is known. If this number is not known or only partial results are available, this element is empty.
If the TDV session that invokes this operation closes before the task is completed, the task continues to run until completion. However, the taskId can only be used with cancelServerTask. It cannot be used with introspectDataSourceResult.
The introspection task is run within an independent background transaction on the server. It is not necessary to call
introspectResourcesTask within an explicit transaction in order to call introspectResourceResult or cancelServerTask. This background transaction survives across server restarts until it is completed.
Location
/services/webservices/system/admin/resource/operations/
Request Elements
path: The path to the data source.
plan: The introspection plan, which details the resource to act upon. See
Introspection Plan Element.
runInBackgroundTransaction
attributes (optional; same as attribute list and subelements as under plan above). Also see
Attributes Element.
Response Elements
taskId: The ID of the server task performing the work.
totalResults (optional): If known, the total result set size. Otherwise this element does not exist.
completed: Boolean. Whether or not task ran to completion.
Faults
DataSourceError: If a data source connection cannot be established or if a data source request returns an error.
IllegalArgument: If the path, plan, or attributes are malformed.
IllegalState: If the data source is disabled.
NotFound: If a data source resource cannot be found at the given path.
Security: If the user does not have READ access on all items in path other than the last one.
Security: If the user does not have WRITE access on the last item in path.
Security: If the user does not have the ACCESS_TOOLS right.