Dataverse / Dynamics 365 CE (on-premises) client for Node.JS. Use @primno/dataverse-auth to authenticate using a connection string or OAuth 2.0.
npm install @primno/dataverse-client

!build
!node-current
dataverse-client is library for Node.JS to make WebAPI requests to Dataverse and Dynamics 365 CE (on-premises).
dataverse-client provides a Query builder to build OData queries.
Works with a token provider. Use @primno/dataverse-auth to authenticate with a Connection String or OAuth2.
> This package is part of the Primno framework.
dataverse-client works with Dataverse (Dynamics 365 Online) and Dynamics 365 CE (on-premises).
bash
npm install @primno/dataverse-client @primno/dataverse-auth
`$3
With a connection string:
`ts
import { DataverseClient } from '@primno/dataverse-client';
import { ConnStringTokenProvider } from '@primno/dataverse-auth';const tokenProvider = new ConnStringTokenProvider(
"AuthType=OAuth;Url=https://.crm.dynamics.com;UserName=;TokenCacheStorePath=./.cache/token.json",
{
oAuth: {
// For device code flow
deviceCodeCallback: (deviceCode) => {
console.log(deviceCode.message);
}
}
}
);
const client = new DataverseClient(tokenProvider);
const accounts = await client.retrieveMultipleRecords("accounts", { top: 10 });
console.log(accounts);
`With OAuth:
`ts
import { DataverseClient } from '@primno/dataverse-client';
import { OAuthTokenProvider } from '@primno/dataverse-auth';const tokenProvider = new OAuthTokenProvider({
url: "https://.crm.dynamics.com",
credentials: {
clientId: "51f81489-12ee-4a9e-aaae-a2591f45987d", // Sample client id
redirectUri: "app://58145B91-0C36-4500-8554-080854F2AC97", // Sample redirect uri
authorityUrl: "https://login.microsoftonline.com/common",
scope: "https://.crm.dynamics.com/.default",
grantType: "device_code",
userName: ""
},
persistence: {
enabled: false
},
deviceCodeCallback: (deviceCode) => {
console.log(deviceCode.message);
}
});
const client = new DataverseClient(tokenProvider);
const accounts = await client.retrieveMultipleRecords("accounts", { top: 10 });
console.log(accounts);
`Authentication
@primno/dataverse-client needs a token provider to authenticate with Dataverse.
Use @primno/dataverse-auth to authenticate with a Connection String or OAuth2.You can also use your own token provider by implementing the
TokenProvider interface.To learn more about available authentication methods, see the
@primno/dataverse-auth documentation.Queries
The following methods are available to query Dataverse:
-
retrieveMultipleRecords: Retrieves a set of records.
- retrieveRecord: Retrieves a single record by its id.
- createRecord: Creates a record.
- updateRecord: Updates a record by its id.
- deleteRecord: Deletes a record by its id.
- executeAction: Executes an action.Retrieve can be done by providing a
RetrieveMultipleOptions object or a raw query string.Note:
The name of the entity must be the entity set name (plural).
$3
1. Retrieves first 10 accounts.
`ts
interface Account {
name: string;
emailaddress1: string;
} const accounts = await client.retrieveMultipleRecords(
"accounts",
{
top: 10,
select: ["name", "emailaddress1"],
orders: [{ attribute: "name", order: "asc" }]
}
);
`1. Create a contact.
`ts
const contact = await client.createRecord("contacts", {
firstname: "Sophie", lastname: "Germain"
});
`1. Delete a account.
`ts
await client.deleteRecord("accounts", "00000000-0000-0000-0000-000000000000");
`1. Retrieves a contact by its id.
`ts
const contact = await client.retrieveRecord("contacts", "00000000-0000-0000-0000-000000000000", { select: ["firstname"] });
`1. Retrieves actives opportunities using a custom query option string.
`ts
const opportunities = await d365Client.retrieveMultipleRecords("opportunities", "?$select=name,$filter=state eq 0");
`1. Retrieves all contacts using OData pagination.
The page size is set to 50. The nextLink attribute is used to get the next page.
`ts
const contacts = []; // Will contain all contacts. let options: RetrieveMultipleOptions | undefined = {
select: ["firstname", "lastname"]
};
let result: EntityCollection;
do {
result = await client.retrieveMultipleRecords("contacts", options, 50 / Page Size = 50 /);
contacts.push(...result.entities);
options = result.nextLink;
} while(result.nextLink);
console.log(contacts);
`1. Retrieves contacts created this month.
`ts
const contacts = await client.retrieveMultipleRecords("accounts", {
select: ["name"],
filters: [{ conditions: [{ attribute: "createdon", operator: "ThisMonth" }] }]
});
`Troubleshooting
$3
On
on-premises environments, you may have this error :`
Error: unable to verify the first certificate
`To fix this issue, you can add your enterprise CA certificate to the trusted root certificate authorities by setting the
NODE_EXTRA_CA_CERTS` environment variable. See Node.js documentation for more information.Thanks to HSO for query options.