React Hooks

@dynatrace-sdk/react-hooks

v1.3.0

npm install @dynatrace-sdk/react-hooks

Why should I use this package?

This package simplifies interactions with Grail, documents, and app states in React by encapsulating complex state management. It offers easy-to-use hooks that integrate seamlessly with client packages, enhancing developer productivity and usability in React applications.

Simplified data querying from Grail

Traditionally, querying data in Dynatrace involves using the client-query package and managing complex React state. The useDqlQuery hook in this package streamlines this process. The following example showcases how to fetch data with a DQL query:

const { data, error, isLoading } = useDqlQuery({ body: { query: 'fetch logs' } });

This hook is fully compatible with the parameters used in the queryExecute function of the @dynatrace-sdk/client-query package.

For instance, to limit the number of results returned:

const { data, error, isLoading, refetch } = useDqlQuery(
    {
      body: {
        query: 'fetch logs',
        maxResultRecords: 2000,
      },
    },
    { autoFetch: false, autoFetchOnUpdate: false }
  );

You can delay the execution of the query until a user clicks on a button by passing additional options to the hook:

const { data, error, isLoading, refetch } = useDqlQuery({body: {query:  'fetch logs'}, {autoFetch: false}});

function onClickQuery() {
  refetch();
}

You should add appropriate scopes to your app's configuration based on the query type. For more details, refer to the Bucket and table permissions in Grail documentation.

Interacting with documents and app states

Beyond DQL queries, our hooks facilitate interactions with documents and app state. They allow control over immediate or deferred query execution.

const { data, error, isLoading } = useDocument({ id: documentId }, { autoFetch: true });

For creating, updating, or deleting documents or app state, an explicit execute call is necessary:

const { data, execute, error } = useCreateDocument();

function onClickCreateDocument() {
  execute(DOCUMENT_DATA);
}

Depending on your interaction type, add these scopes to your app configuration:

Function	Scope
Document read	document:documents:read
Document write/update	document:documents:write
Document delete	document:documents:delete
State read	state:app-states:read
State write	state:app-states:write
State delete	state:app-states:delete
User state read	state:user-app-states:read
User state write	state:user-app-states:write
User state delete	state:user-app-states:delete

Simplified Use of Davis® Analyzers

Leveraging Davis® analyzers traditionally involves complex state management and polling logic, alongside the @dynatrace-sdk/client-davis-analyzers package. The useAnalyzer hook in this package makes this process much more straightforward:

const { data, error, isLoading } = useAnalyzer({
  analyzerName: 'dt.statistics.GenericForecastAnalyzer',
  body: {
    timeSeriesData: {
      expression: query,
    },
  },
});

This hook supports all the parameters available in the executeAnalyzer method from the @dynatrace-sdk/client-davis-analyzers package.

To defer the execution of the analyzer until a user action, like a button click, configure the hook with additional options:

const { data, error, isLoading, refetch } = useAnalyzer({
  analyzerName: 'dt.statistics.GenericForecastAnalyzer',
  body: {
    timeSeriesData: {
      expression: query,
    },
  }, 
  {
    autoFetch: false,
    autoFetchOnUpdate: true,
  }
});

function onExecuteAnalyzer() {
  refetch();
}

In your app's configuration, include the necessary scope:

Function	Scope
Use analyzer	davis:analyzers:execute

App functions

The useAppFunction hook is the simplest way to call app functions. As the other hooks in this package, it provides state handling for loading and error states:

const { data, error, isLoading } = useAppFunction({ name: 'functionName', data: 'data' });

Sometimes you want to delay the execution of the app function until a user clicks on a button. This can be achieved by passing additional options to the hook:

const { data, error, isLoading, refetch } = useAppFunction({ name: 'functionName', data: 'data' }, { autoFetch: false, autoFetchOnUpdate: false });

function onClick() {
  refetch();
}

Hooks

useAccessorPermissionsV2

useAccessorPermissionsV2(params,options?): Object

Load accessor permissions.

Parameters

Name	Type	Description
params*required	AccessorPermissionsParamsV2	Parameters for the client sdk call.
options	HookOptions	Additional options for the react hook.

useAllUsersPermissionsV2

useAllUsersPermissionsV2(params,options?): Object

Load all-users permissions.

Parameters

Name	Type	Description
params*required	LoadAllUsersPermissionsParamsV2	Parameters for the client sdk call.
options	HookOptions	Additional options for the react hook.

useAnalyzer

useAnalyzer(params,options?): Object

Execute an analyzer with the given data.

Parameters

Name	Type	Description
params*required	AnalyzerParams	Parameters for the client sdk call.
options	AnalyzerHookOptions	Additional options for the react hook.

useAppFunction

useAppFunction(params,options?): Object

Call specified app function by name.

Parameters

Name	Type	Description
params*required	AppFunctionParams	App function params.
options	HookOptions	Additional options for the react hook.

useAppState

useAppState(params,options?): Object

Gets app state

Parameters

Name	Type	Description
params*required	AppStateParams	Parameters for the client sdk call.
options	HookOptions	Additional options for the react hook.

useAppStates

useAppStates(params,options?): Object

List app states

Parameters

Name	Type	Description
params*required	AppStatesParams	Parameters for the client sdk call.
options	HookOptions	Additional options for the react hook.

useCreateDocument

useCreateDocument(): Object

Create a new document.

useCreatePermissionsV2

useCreatePermissionsV2(): Object

Create a new permissions.

useCreateSettings

useCreateSettings(): Object

Create a new setting.

useCreateSettingsV2

useCreateSettingsV2(): Object

Create a new setting.

useDeleteAccessorPermissionsV2

useDeleteAccessorPermissionsV2(): Object

Delete the accessor permissions

useDeleteAllUsersPermissionsV2

useDeleteAllUsersPermissionsV2(): Object

Delete the all-users permissions

useDeleteAppState

useDeleteAppState(): Object

Deletes app state

useDeleteAppStates

useDeleteAppStates(): Object

Delete all app states

useDeleteDocument

useDeleteDocument(): Object

Delete the document

useDeleteSettings

useDeleteSettings(): Object

Delete the setting

useDeleteSettingsV2

useDeleteSettingsV2(): Object

Delete the setting

useDeleteUserAppState

useDeleteUserAppState(): Object

Delete user app state

useDeleteUserAppStates

useDeleteUserAppStates(): Object

Delete all user app states

useDocument

useDocument(params,options?): Object

Retrieve metadata and content for documents.

Parameters

Name	Type	Description
params*required	DocumentParams	Parameters for the client sdk call.
options	HookOptions	Additional options for the react hook.

useDocumentMetaData

useDocumentMetaData(params,options?): Object

Retrieve document metadata.

Parameters

Name	Type	Description
params*required	DocumentMetaDataParams	Parameters for the client sdk call.
options	HookOptions	Additional options for the react hook.

useDownloadDocument

useDownloadDocument(params,options?): Object

Download document content

Parameters

Name	Type	Description
params*required	DownloadDocumentParams	Parameters for the client sdk call.
options	HookOptions	Additional options for the react hook.

useDqlQuery

useDqlQuery(params,options?): Object

Use this hook to execute a DQL query.

Parameters

Name	Type	Description
params*required	QueryParams	Query and enrich options that will be executed.
options	HookOptions	Additional options for the react hook.

Returns

Description
The state of the query, including the result and functions to refetch or cancel the query.

useEffectivePermissions

useEffectivePermissions(params,options?): Object

Retrieve effective settings permissions for the calling user.

Parameters

Name	Type	Description
params*requiredDEPRECATED	Omit<Object | "abortSignal">	Parameters for the client sdk call.
optionsDEPRECATED	HookOptions	Additional options for the react hook.

useEffectivePermissionsV2

useEffectivePermissionsV2(params,options?): Object

Retrieve effective settings permissions for the calling user.

Parameters

Name	Type	Description
params*required	Omit<Object | "abortSignal">	Parameters for the client sdk call.
options	HookOptions	Additional options for the react hook.

useListDocuments

useListDocuments(params,options?): Object

List all documents accessible to you.

Parameters

Name	Type	Description
params*required	undefined | ListDocumentsParams	Parameters for the client sdk call.
options	HookOptions	Additional options for the react hook.

usePermissionsV2

usePermissionsV2(params,options?): Object

Load permissions.

Parameters

Name	Type	Description
params*required	PermissionsParamsV2	Parameters for the client sdk call.
options	HookOptions	Additional options for the react hook.

useSetAppState

useSetAppState(): Object

Updates app state

useSetUserAppState

useSetUserAppState(): Object

Updates user app state

useSettings

useSettings(params,options?): Object

Retrieve metadata and content for settings.

Parameters

Name	Type	Description
params*requiredDEPRECATED	SettingsParams	Parameters for the client sdk call.
optionsDEPRECATED	HookOptions	Additional options for the react hook.

useSettingsObjects

useSettingsObjects(params,options?): Object

Retrieve metadata and content for settings.

Parameters

Name	Type	Description
params*requiredDEPRECATED	SettingsObjectParams	Parameters for the client sdk call.
optionsDEPRECATED	HookOptions	Additional options for the react hook.

useSettingsObjectsV2

useSettingsObjectsV2(params,options?): Object

Retrieve metadata and content for settings.

Parameters

Name	Type	Description
params*required	SettingsObjectParamsV2	Parameters for the client sdk call.
options	HookOptions	Additional options for the react hook.

useSettingsV2

useSettingsV2(params,options?): Object

Retrieve metadata and content for settings.

Parameters

Name	Type	Description
params*required	SettingsParamsV2	Parameters for the client sdk call.
options	HookOptions	Additional options for the react hook.

useTransferOwnershipV2

useTransferOwnershipV2(): Object

Transfer ownership.

useUpdateAccessorPermissionsV2

useUpdateAccessorPermissionsV2(): Object

Update accessor permissions.

useUpdateAllUsersPermissionsV2

useUpdateAllUsersPermissionsV2(): Object

Update all-users permissions.

useUpdateDocument

useUpdateDocument(): Object

Update metadata and content.

useUpdateDocumentMetadata

useUpdateDocumentMetadata(): Object

Update document metadata

useUpdateSettings

useUpdateSettings(): Object

Update metadata and content.

useUpdateSettingsV2

useUpdateSettingsV2(): Object

Update metadata and content.

useUserAppState

useUserAppState(params,options?): Object

Get user app state

Parameters

Name	Type	Description
params*required	UserAppStateParams	Parameters for the client sdk call.
options	HookOptions	Additional options for the react hook.

useUserAppStates

useUserAppStates(params,options?): Object

List user app states

Parameters

Name	Type	Description
params*required	UserAppStatesParams	Parameters for the client sdk call.
options	HookOptions	Additional options for the react hook.

Interfaces

AnalyzerHookOptions

Available options for useAnalyzer hook

Properties

Name	Type	Description
autoFetch*required	boolean	If set to true, the hook will execute the query immediately. If set to false, the query only executes when calling refetch.
autoFetchOnUpdate*required	boolean	If set to true, the hook will execute the query on a component update. If set to false, it is not executed on update.
onError	Object