Using the Resource data client

The ResourceDataClient is a service that can retrieve and mutate resource data in an easy and efficient manner.

You can create a client instance using the createResourceDataClient() method on the component context.

const client = context.createResourceDataClient();

When a component's lifecycle ends, the component context is automatically destroyed, effectively calling destroy() on any ResourceDataClient created via that context.

Retrieving resources

To start retrieving resource data (for example the device name) you can use the query() method to set up a listener. What's nice about this is that when the data is updated, the listener will be called again with the latest data.

const client = context.createResourceDataClient();

client.query([
  { selector: 'Agent', fields: ['name'] }
], result => {
  console.log(result);
  // result: [{ data: { name: 'CNC Machine' }, query: { fields: ['name'], selector: 'Agent' } }]
});

When the ResourceDataClient is destroyed, it will cancel all query listeners that were set up from this client. However, you can choose to manually cancel a specific query listener. A use case could be to stop listening for changes as soon as you receive a first result.

const client = context.createResourceDataClient();

const cancelQuery = client.query([
  { selector: 'MyUser', fields: ['name'] }
], result => {
  console.log('Hello, ' + result[0].data.name + '!');
  // result: "Hello, John Doe!"
  
  // Stops the listener, because the name was needed just once.
  cancelQuery();
});

The next example showcases a query which combines data from two different resources:

const client = context.createResourceDataClient();

client.query([
  { selector: 'Agent', fields: ['custom'] },
  { selector: 'CustomPropertyList', fields: ['name', 'scopeType', 'slug'] }
], results => {
  const agent = results[0].data;
  const customProps = results[1].data;
  const agentCustomProps = customProps.map(prop => ({
    name: prop.name,
    value: agent.custom[prop.scopeType + prop.slug],
  }));
 
  console.log(agentCustomProps);
  // result: [{ name: 'Project number', value: '100' }]
});

Resource query selectors

The ResourceDataClient is limited in the kind of resources and fields it can retrieve. Below you can find the currently supported selectors and their allowed fields.

Selector	Allowed fields	Description	API endpoint used
Agent	activeVpnSession.rscServer.name, activeVpnSession.rscServer.publicId, activeVpnSession.vpnAddress, connectedUsers.name, connectedUsers.publicId, custom, dataSources.name, dataSources.publicId, dataSources.slug, description, lastSeenAgentUserAgent.firmwareVersion, lastSeenAgentUserAgent.hardware, lastSeenAgentUserAgent.hardwareVersion, lastSeenAgentUserAgent.publicId, location.name, loggingMdrServer.name, loggingMdrServer.publicId, loggingMqttChangedOn, macAddress, mdrServer.name, mdrServer.publicId, memberships.group.publicId, memberships.publicId, mqttChangedOn, name, permissions, publicId, rateLimiting.configMqttCommandCounter, rateLimiting.configMqttCommandLastHit, rateLimiting.configMqttCommandLimit, rateLimiting.configMqttDataCounter, rateLimiting.configMqttDataLastHit, rateLimiting.configMqttDataLimit, rateLimiting.configOpenvpnCounter, rateLimiting.configOpenvpnLastHit, rateLimiting.configOpenvpnLimit, scheduledAccessRequests.approver.name scheduledAccessRequests.approver.publicId scheduledAccessRequests.end scheduledAccessRequests.publicId scheduledAccessRequests.reason scheduledAccessRequests.servers.name scheduledAccessRequests.servers.publicId scheduledAccessRequests.start scheduledAccessRequests.status scheduledAccessRequests.user.name scheduledAccessRequests.user.publicId scheduledAccessRequests.vpn serialNumber, servers.custom, servers.name, servers.publicId, servers.serviceGroup, servers.type, type.name, type.publicId	The current Agent (i.e. the Agent for the Page that is currently open, or the Agent for the Card that the component is placed on).	Agent
AppConfig	publicId, values	The current App config. Can be used to directly retrieve the app's configuration set in Admin > Apps.	Only returns a value if the developer marks the app config public. Always returns `null` if the app config is private and the user is not the app's developer.
Asset	custom, description, memberships.group.publicId, memberships.publicId, name, permissions, publicId, resourceVariant.publicId	The current Asset (i.e. the Asset for the Page that is currently open, or the Asset for the Card that the component is placed on).	Asset
AssetAppConfig	publicId, resources.publicId, resources.resourcePublicId, resources.resourceType, resources.slug, resources.stateValues, resources.values, values, stateValues	The current AssetAppConfig. Can be used to store app configuration or state for an Asset	AssetAppConfig
AssetAppConfigList	publicId, resources.publicId, resources.resourcePublicId, resources.resourceType, resources.slug, resources.stateValues, resources.values, values, stateValues	Lists the current AssetAppConfig and all AssetAppConfigs descendant to the current asset.	AssetAppConfig
Branding	logo, publicId, theme.logoHasBackgroundColor	The currently active branding.	CompanyBranding
CustomPropertyList	flags, name, publicId, resourceType, resourceVariant, scopeType, slug	All Custom Properties for the current Company.	CustomPropertyList
GroupList	name, publicId, type.name, type.order, type.publicId	All Groups in the current Company.	GroupList
LicenceList	publicId type.publicId usageType	All Licences active in the current Company.	LicenceList
MyCompany	name, permissions, publicId	The currently active Company.	MyCompany
MyUser	custom, name, publicId, support, unreadMessagesCount	The currently logged in User.	MyUser
PagePage	order, publicId	The individual page within a document-style page (only applicable to reports).	PagePage
PageVersion	pagePages.order, pagePages.publicId, publicId, title	The current Page (i.e. the Page that is currently open, or the Card that the component is placed on).	PageVersion
UserList	name, publicId	All users of the current Company	UserList

Please reach out to us by sending an e-mail to [email protected], if you are missing items on this list and you would like to use the resource data client to retrieve data for other resource types or allowed fields.

Adding resources

The ResourceDataClient can also be used to add resources. To add a resource you can use the add() method to create a Promise that completes when the resource has been added.

const client = context.createResourceDataClient();

client.add({
  selector: 'AssetAppConfigResource',
  data: {
    values: { name: 'item 1' },
  }
})

Resource add selectors

The ResourceDataClient is limited in the kind of resources it can add. Below you can find the currently supported selectors and their allowed fields.

Selector	Allowed fields	Description	API endpoint used
AssetAppConfigResource	publicId, resourcePublicId, resourceType, values, stateValues	Can be used to store a list of resources for app configuration or state for an Asset	AssetAppConfigResource

Please reach out to us by sending an e-mail to [email protected], if you are missing items on this list and you would like to use the resource data client to add data for other resource types.

Updating resources

The ResourceDataClient can also be used to update resources. To update a resource you can use the update() method to create a Promise that completes when the resource has been updated.

const client = context.createResourceDataClient();

client.update({
  selector: 'AssetAppConfig',
  data: {
    stateValues: { item: 5 },
  }
})

Resource update selectors

The ResourceDataClient is limited in the kind of resources it can update. Below you can find the currently supported selectors and their allowed fields.

Selector	Allowed fields	Description	API endpoint used
AssetAppConfig	publicId, values, stateValues	The current AssetAppConfig. Can be used to store app configuration or state for an Asset	AssetAppConfig
AssetAppConfigResource	publicId, resourcePublicId, resourceType, values, stateValues	Can be used to store a list of resources for app configuration or state for an Asset	AssetAppConfigResource

Please reach out to us by sending an e-mail to [email protected], if you are missing items on this list and you would like to use the resource data client to update data for other resource types.

Remove resources

The ResourceDataClient can also be used to remove resources. To remove a resource you can use the remove() method to create a Promise that completes when the resource has been removed. Resources are removed by their publicId.

const client = context.createResourceDataClient();

client.remove({
  selector: 'AssetAppConfigResource',
  publicId: 'pubid0000001',
})

Resource remove selectors

The ResourceDataClient is limited in the kind of resources it can remove. Below you can find the currently supported selectors.

Selector	Description	API endpoint used
AssetAppConfigResource	Can be used to store a list of resources for app configuration or state for an Asset	AssetAppConfigResource

Please reach out to us by sending an e-mail to [email protected], if you are missing items on this list and you would like to use the resource data client to remove data for other resource types.

Template rendering

The ResourceDataClient has built-in support for template rendering. Components can make use of Mustache templating via the render method. The renderer will resolve fields from the given template and re-render the template when a resource is updated. Fields can be referenced via [selector].[field]. Below is an example of a component that references the name field of the Agent resource. Currently, we only support Agent and Asset resources for template rendering.

const client = context.createResourceDataClient();

client.render([
  { template: 'Device name: {{agent.name}}' },
], ([output]) => {
  console.log(output);
  // result: 'Device name: CNC Machine'
});