https://github.com/stevenmmortimer/rdynamicscrm
This R package provides a client to connect to MS Dynamics CRM instances
https://github.com/stevenmmortimer/rdynamicscrm
dynamics-crm r
Last synced: about 2 months ago
JSON representation
This R package provides a client to connect to MS Dynamics CRM instances
- Host: GitHub
- URL: https://github.com/stevenmmortimer/rdynamicscrm
- Owner: StevenMMortimer
- License: other
- Created: 2018-08-11T14:34:23.000Z (almost 7 years ago)
- Default Branch: main
- Last Pushed: 2020-07-23T17:02:02.000Z (almost 5 years ago)
- Last Synced: 2025-01-29T18:22:12.424Z (4 months ago)
- Topics: dynamics-crm, r
- Language: R
- Homepage: https://stevenmmortimer.github.io/rdynamicscrm/
- Size: 194 KB
- Stars: 0
- Watchers: 3
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.Rmd
- Changelog: NEWS.md
- License: LICENSE
Awesome Lists containing this project
README
---
output:
github_document:
html_preview: false
---
```{r, echo = FALSE, message = FALSE}
knitr::opts_chunk$set(
fig.align = 'center',
collapse = TRUE,
comment = "#>",
fig.path = "man/figures/README-")
```
# rdynamicscrm
[](https://travis-ci.org/StevenMMortimer/rdynamicscrm)
[](https://ci.appveyor.com/project/StevenMMortimer/rdynamicscrm)
[](https://codecov.io/gh/StevenMMortimer/rdynamicscrm?branch=master)
**rdynamicscrm** is an R package that creates a client to connect to MS Dynamics CRM.
Package features include:
* An auto-refreshing authentication method (`dyn_auth()`)
* CRUD (Create, Retrieve, Update, Delete) methods for records, such as:
* `dyn_create()`, `dyn_retreive()`, `dyn_update()`, `dyn_delete()`
* Query records using `dyn_query()`
* Basic utility calls (`dyn_whoami()`)
## Table of Contents
* [Installation](#installation)
* [Usage](#usage)
* [Authenticate](#authenticate)
* [Create](#create)
* [Query](#query)
* [Update](#update)
* [Delete](#delete)
* [Future](#future)
* [Credits](#credits)
* [More Information](#more-information)
## Installation
```{r, eval = FALSE}
# this package is not yet available on CRAN
# install the latest version available on GitHub using the devtools package
# install.packages("devtools")
devtools::install_github("StevenMMortimer/rdynamicscrm")
```
If you encounter a clear bug, please file a minimal reproducible example on [GitHub](https://github.com/StevenMMortimer/rdynamicscrm/issues).
## Usage
### Authenticate
First, load the **rdynamicscrm** package and authenticate.
```{r auth, include = FALSE}
suppressWarnings(suppressMessages(library(dplyr)))
suppressWarnings(suppressMessages(library(purrr)))
suppressWarnings(suppressMessages(library(here)))
library(rdynamicscrm)
rdynamicscrm_setup <- readRDS(here::here("tests", "testthat", "rdynamicscrm_setup.rds"))
suppressMessages(dyn_auth(url = rdynamicscrm_setup$url,
username = rdynamicscrm_setup$username,
password = rdynamicscrm_setup$password))
```
```{r, eval=FALSE}
library(rdynamicscrm)
dyn_auth(url = "https://test.ztcrm.org/",
username = "[email protected]",
password = "{PASSWORD_HERE}")
```
The `dyn_auth()` function will obtain a cipher and secret key that will be embedded
in the header of each SOAP API call to securely access the CRM instance. After obtaining
these authentication credentials, you can check your connectivity by looking at
the information returned about the current user. It should be information about you!
```{r}
# pull down information of person logged in
# it's a simple easy call to get started
# and confirm a connection to the APIs
me <- dyn_whoami()
my_info <- dyn_retrieve(me$UserId, entity_name="systemuser",
attributes=c("fullname", "isdisabled"))
#sprintf("Name: %s", my_info$fullname)
sprintf("Disabled?: %s", my_info$isdisabled)
```
### Create
MS Dynamics CRM has entities and those entities contain records. One default entity is the
"contact" entity. This example shows how to create two records in the contact entity.
```{r create-records}
n <- 2
new_contacts <- tibble(firstname = rep("Test", n),
lastname = paste0("Contact-Create-", 1:n))
created_records <- dyn_create(new_contacts, entity_name="contact")
created_records
```
### Query
MS Dynamics CRM has proprietary form of SQL called FetchXML. FetchXML is a powerful
tool that allows you to return the attributes of records on almost any entity in
MS Dynamics CRM including accounts, contacts, custom entities and more!
For simple "SELECT" queries you only need to specify the entity and the fields.
```{r query-records-1}
queried_records <- dyn_query(entity_name = "contact",
attributes = c("modifiedon", "donotbulkemail"), top=3)
queried_records
```
Below is an example where we grab the two contact records we just created using
FetchXML to specifically target those records.
```{r query-records-2}
my_fetchxml <- '
'
queried_records <- dyn_query(fetchxml=my_fetchxml)
queried_records
```
### Update
After creating records you can update them using `dyn_update()`. Updating a record
requires you to pass the MS Dynamics CRM `Id` of the record. MS Dynamics CRM creates
a GUID (globally unique identifier) on each record and uses that to know which record to
attach the update information you provide. Simply include a field or column in your
update dataset called "Id" and the information will be matched. Here is an example
where we update each of the records we created earlier with a new first name
called "TestTest".
```{r update-records}
# Update some of those records
queried_records <- queried_records %>%
mutate(firstname = "TestTest") %>%
rename(id=contactid)
updated_records <- dyn_update(queried_records, entity_name="contact")
updated_records
```
### Delete
Records can easily be deleted individually or in bulk by passing a vector of IDs
to the `dyn_delete()` function. Here we will delete the two records that we created
in this example.
```{r delete-records}
ids_to_delete <- updated_records$id
deleted_records <- dyn_delete(ids_to_delete, entity_name="contact")
deleted_records
```
## Future
Support for:
- Online environments (not just On-Premise IFD environments)
- Upsert
- Related Entities
## Credits
This application has derived inspiration from other open source software components.
The format of the XML in SOAP calls was created by following mimicking implementations
in [Java](https://github.com/jlattimer/CRMSoapAuthJava) by Jason Lattimer and
[Python](https://github.com/veeloinc/python-dynamics) by Veelo, Inc. In addition,
inspiration was drawn from examples created by Jamie Miley that are available on his
[blog](http://mileyja.blogspot.com/p/microsoft-dynamics-crm-2011-sdk-example.html).
We acknowledge and are grateful to these developers for their contributions to open source.
## More Information
Microsoft provides support with a C# client library. Unfortunately R is not a supported
language. However, most all operations supported by Dynamics CRM can be made available
via this package. This package makes requests best formatted to match what the API
requires as input. This articulation is not perfect and continued progress will be
made to add and improve functionality. For details on formatting, attributes, and
methods please refer to
[Microsoft's documentation](https://docs.microsoft.com/en-us/dynamics365/customer-engagement/developer/use-microsoft-dynamics-365-organization-service)
as they are explained better there.
More information is also available on the `pkgdown` site at
https://StevenMMortimer.github.io/rdynamicscrm.
[Top](#rdynamicscrm)
---
Please note that this project is released with a [Contributor Code of Conduct](CONDUCT.md).
By participating in this project you agree to abide by its terms.