Microsoft Dynamics CRM Connector Tool v1.3

What is the Microsoft Dynamics CRM Connector Tool v1.3?

The Microsoft Dynamics CRM Connector tool is used to operate with data from/to your Microsoft Dynamics CRM system. The full range of objects in Dynamics CRM can be interacted with, for example, Accounts, Account Leads, Appointments, Calendars, Campaigns, Competitors, Contacts, Contracts, Invoices, Leads, Opportunities, Products, and so on. The range of objects and the data within them is retrieved dynamically from your installation of Dynamics CRM so that custom changes made to CRM are also included.

The Dynamics CRM Connector tool transforms incoming XML data into an XML format for the specific Microsoft Dynamics CRM object and operation selected. This XML is then passed to the Dynamics CRM Web Service which does the actual communication with Dynamics CRM via its API. The response is exposed as XML from the tool, which could include details of the object requested, errors from Dynamics CRM, or the values of any automatically generated ID fields.

The tool does not accept a BPA Platform recordset directly as input but BPA Platform variables containing XML data from any source at task runtime may be used. In addition, a BPA Platform recordset can be processed by the Convert Recordset to XML tool first to transform it into XML if you have this tool available.

Microsoft Dynamics CRM Connector Tool: System Requirements

The Microsoft Dynamics CRM Connector tool requires BPA Platform (formerly “TaskCentre”) 2018 or above. Supported versions of Microsoft Dynamics CRM are as follows:

• Microsoft Dynamics CRM 2013: On-Premises
• Microsoft Dynamics CRM 2015: On-Premises
• Microsoft Dynamics 365 (formerly “Dynamics CRM”) v8.x: On-Premises
• Microsoft Dynamics 365 for Customer Engagement v9.0: Online

White Paper - Microsoft Dynamics CRM Connector 1.3

The Microsoft Dynamics CRM Connector tool reads and updates Microsoft Dynamics CRM.

The range of Dynamics CRM objects, and the data within them, is retrieved dynamically so that custom changes made to CRM are also included.

The Microsoft Dynamics CRM Connector white paper describes how to use the tool.

Download White Paper

Microsoft Dynamics CRM Connector Architecture

The image below provides a high-level system architecture diagram of the Microsoft Dynamics CRM Connector within the context of BPA Platform and Dynamics CRM.

Microsoft Dynamics CRM could be on-premises or in the cloud.

The BPA Platform Microsoft Dynamics CRM Connector tool is used to read and write data into Dynamics CRM through the Dynamics CRM Web Services. It is installed on the BPA Platform Server. It must also be installed on any BPA Platform Client installations that are accessing the BPA Platform Server.

Global Configuration

The global configuration for this tool is used to create connections to the Dynamics CRM Web Service, which communicates with Dynamics CRM. When a connection is set up, the available objects and fields of Dynamics CRM will be retrieved.

When the connection is selected at task level, within the tool, you will then be able to select an object to have BPA Platform data mapped to and select the operation that will be performed, i.e. to retrieve data from or deliver data to your Dynamics CRM system.

The global configuration for the tool can be accessed via the toolbar:

Manage > Tools > Data Connectors > Microsoft Dynamics CRM Connector.
Or, via the BPA Platform system tree under Data Connectors > Microsoft Dynamics CRM Connector.

Click Add to add a new connection.

About the Connection Tab

The Connection tab allows you to provide a name for the global connection and requires you to specify the location of the Dynamics CRM Web Service so communication can be established.

The Connection Name field is the display name of the connection e.g. Microsoft Dynamics CRM. Any text entered here will be visible when selecting the connection at task level.

The Dynamics Discovery Service Domain Name field requires either the name of the Dynamics Server (i.e.
dynsvr01), the fully qualified domain name of the discovery service (i.e. dev.mydomain.com), or the Dynamics Online platform; which can be selected from the drop down list.

Advanced Connection Settings

An Advanced button within the tab allows the port number to be changed.

By default, the connection to the Dynamics CRM server operates on port 80, or port 443 if HTTPS is used.

Alternatively, a custom port number can be set if required. You may need to change the port if another connection is already using it. Some firewalls and routers also allow for “Port Translation”, this means that a service behind a firewall might be on port 443 but the firewall exposes it as an alternative port number. This UI allows specification of the translated port number to use.

The Use HTTPS checkbox allows the connection to the Dynamics CRM server to be made using HTTPS. This would be required when using Dynamics 365 and when connecting to Internet Facing Deployments.

Download Whitepaper

About the Authentication Tab

The Authentication tab requires the credentials of a Dynamics CRM account that has access to the discovery endpoint and/or the required organisations of Dynamics CRM.

This account will be used to establish communication with the server and will also be used by tasks to read data from and write data to an organisation within your Dynamics CRM system.

The Deployment Type drop down list requires you to select the type of account authentication in use. This will be dependent on how your Microsoft Dynamics CRM package has been deployed, i.e. online or on premise.

The following options are available:

• Dynamics CRM On-Premise (Active Directory) — Used in installations on premise where Windows Authentication is being used
• Dynamics CRM On-Premise (IFD) — Used in installations on premise where claims-based authentication is used and the dynamics server is configured for IFD (Internet Facing Deployment) mode
• Dynamics 365 (Office 365 Account) — Used when connecting to Dynamics 365 and an Office 365 account is being used
• Dynamics 365 (Microsoft Account) — Used when connecting to Dynamics 365 and a Windows Live account is being used

About the Organisation Tab

The Organisation tab displays a list of organisations after valid connection details for the Dynamics CRM server have been supplied.

Use the drop-down list to select an organisation for the Microsoft Dynamics CRM Connector tool to operate with, i.e. expose the available objects and operations for mapping at task level.

About the Options Tab

Multi Value Filter Support enables the use of the Multi Value Filter. The Multi Value Filter allows you to perform searches within lists such as xxx in 111,222,333,444 etc.

Multi Value Filter Separator sets the separator to be used when passing multiple values for filtering. i.e. (/) (,) (:) (#)

Update Objects and Operations and Clear Metadata Cache

The global configuration provides two other options which are visible on every tab, they allow for new object data to be obtained from Microsoft Dynamics CRM in the event of a change.

The options are as follows:

• Update objects and operations – If changes are made to objects and their schemas in Microsoft Dynamics CRM, i.e. a new user defined field is added, then this option will need to be checked and the connection resaved. This will enable a refresh of the schemas within the tool and allow all changes to be visible.
  The same applies if you have upgraded to a newer release of the Microsoft Dynamics CRM Connector tool whilst existing connections are still present.
• Clear Metadata Cache – When an object and an operation is selected from within the connector tool, the associated fields for mapping are downloaded and listed within the tool UI. This information is cached locally to speed up the process of displaying the list when the same object and operation is selected again.
  You will want to clear the cache if, for example, new user defined fields are added within Dynamics CRM and you want them to be downloaded and displayed in the tool UI for mapping, instead of displaying an older schema from cached memory. This applies to both online and on-premise versions of Microsoft Dynamics CRM.

Download Whitepaper

Microsoft Dynamics CRM Connector Tool: Step Configuration

About the General Tab

The General tab allows the step to be named and described. An XML data source can also be selected for the tool to consume. This will expose the XML data within the tool and allow it to be mapped to objects of a Dynamics CRM organisation.

The Data source can be either be an existing task step, or a custom source allowing the use of a task variable.

The Task Step drop-down list allows you to select an available step in the task that is capable of natively exposing an XML document. For example, a Convert Recordset to XML step or even another Microsoft Dynamics CRM Connector step. Selecting this option will consume the output XML of the step and will automatically determine the schema (XSD). The schema will then be presented within the Mapping tab for the XML data to be mapped to the fields of an object.

Selecting Custom Schema allows the use of a task variable containing XML as its value. The variable is dragged from the task browser and placed in the Input Source Variable field. The schema describing the structure of the XML in the variable must then be supplied using the Define button.

Custom Schema Configuration

The Custom Schema Configuration is used to define the schema of the XML stored by a variable.

An XML schema describes the structure of the XML, in terms of what tags are present and the nesting of the tags. The format used by the Microsoft Dynamics CRM Connector tool is the industry standard XSD format.

If an XSD schema file is available for the XML that is to be used as the input data, then this can be loaded in from a file on disk (via the Import XSD/XML File button) or copied directly into the text box shown. Any XML passed into the step at runtime must conform to this schema otherwise an error will be reported.

Using an XSD schema file is the recommended way of defining the XML schema. However, if an XSD schema is not available, then an example of the XML that will be used at runtime can be loaded in or copied into the text box. If an XML document is used, then the schema can be determined by pressing the Parse button.

About the Connection Tab

The Connection tab is used to select a connection to the Microsoft Dynamics CRM server which will expose the available objects for mapping within the Mapping tab.

The drop-down list displays all available connections previously created in the tool global configuration.

As an alternative to selecting a connection that has been previously created, a BPA Platform variable may be utilised by dragging it from the task browser into the Connection field to create a dynamic connection. If the dynamic option is used, then at runtime the text in the variable should match the name of one of the connections set up in the Global Configuration.

About the Mapping Tab

The Mapping tab is used to define links between the incoming data of the XML data source, and the outgoing data that is to be sent to Microsoft Dynamics CRM. Once a connection has been specified the objects and operations available will be exposed for selection.

An object is first selected followed by the operation required. The XML structure of the incoming data source is displayed in the left-hand pane whilst the Microsoft Dynamics CRM object data is displayed in the right.

A mapping is completed by dragging a field from the data source left XML tree to a field on the tool input right XML tree, a visual link of the mapping will then be displayed in the middle.

The Object drop-down list displays the available objects of the selected Microsoft Dynamics CRM connection. The Operation drop-down list displays the operations that the selected object supports, in all cases this will be Create, Read, Update, Delete, and Search.

Selecting an object and an operation will change the tree display in the right pane to reflect the fields and child objects available for that selected operation.

For a detailed description of the supported objects and operations, see Supported Objects.

Additionally, a field is present in each objects operation named SupplementaryReference. It allows for traceability throughout the process of transferring data. When mapped, the data will reside locally at run time. It is added to the output and creates a record for your reference purposes only, this means you can choose to map any kind of information to this field to assist with, for example, advising where the data originated from or at what time data transfer occurred.

Download Whitepaper

About the Options Tab

The Options tab allows you to define how errors in this step are handled at task runtime.

If an error occurs, you can decide whether the step should Continue processing, or terminate the step immediately (Abort Step).

If the step is aborted, you can choose to Continue processing onto the next step in the task, or terminate the whole task immediately (Abort Task). Allowing the task to continue allows you to use the error XML received back in a Save File step for investigation purposes, for example.

All errors are recorded to the BPA Platform Event Log (Manage > Event Log).

Download Whitepaper

Microsoft Dynamics CRM Connector Technical Summary

Working with Other Tools

Consuming from Other Tools

Below is a list of other tools that a Microsoft Dynamics CRM Connector step can directly interact with to consume information from:

Icon	Tool Name	Tool Category
	Import Flat File	Input
	Import XML Document	Input
	Convert Recordset to XML	Format
	Web Service Connector	Data Connectors
	Microsoft Dynamics CRM Connector	Data Connectors

Exposing to Other Tools

A Microsoft Dynamics CRM Connector step can also directly expose its output for use by the following steps listed below:

Icon	Tool Name	Tool Category
	Convert XML to Recordset	Format
	Run Microsoft Reporting Services	Format
	Save File	Output
	Web Service Connector	Data Connectors
	Microsoft Dynamics CRM Connector	Data Connectors

Data Processing

When a task containing a Microsoft Dynamics CRM Connector step runs, the Connector Step itself performs all of the processing of data from other steps in the task. It assembles an XML document containing all of the information that the Web Service needs to perform the operation on the object that the step is configured for.

This information includes the data itself to be passed from other steps, connection details for the Microsoft Dynamics CRM API, and the operation to be performed on the Dynamics CRM web service. The XML is then transmitted to the Web Service (if required, via a secure HTTPS connection).

The Web Service then parses the XML and performs the required operation by generating a call to the Microsoft Dynamics CRM API. An XML document is then created which contains the response from the Microsoft Dynamics CRM API. This may be information about the requested object data if for instance the operation was a read or search operation, or it could be a confirmation if an Update operation was attempted.

This XML is then returned to the Microsoft Dynamics CRM Connector Tool for use in subsequent steps.

Supported Objects

The objects and operations available are read from your installation of Dynamics CRM.

Each objects supports the following operations:

• Create
• Read
• Update
• Delete
• Search

List: A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

A
Account
AccountLeads
ActivityMimeAttachment
ActivityParty
ActivityPointer
AdvancedSimilarityRule
Annotation
AnnualFiscalCalendar
ApplicationFile
Appointment
AsyncOperation
Attachment
AttributeMap
Audit
AuthorizationServer
AzureServiceConnection
B
BookableResource
BookableResourceBooking
BookableResourceBookingHeader
BookableResourceCategory
BookableResourceCategoryAssn
BookableResourceCharacteristic
BookableResourceGroup
BookingStatus
BulkDeleteFailure
BulkDeleteOperation
BulkOperation
BulkOperationLog
BusinessDataLocalizedLabel
BusinessProcessFlowInstance
BusinessUnit
BusinessUnitMap
BusinessUnitNewsArticle
C
Calendar
CalendarRule
Campaign
CampaignActivity
CampaignActivityItem
CampaignItem
CampaignResponse
Category
ChannelAccessProfile
ChannelAccessProfileEntryAccessLevel
ChannelAccessProfileRule
ChannelAccessProfileRuleItem
ChannelProperty
ChannelPropertyGroup
Characteristic
ChildIncidentCount
ClientUpdate
ColumnMapping
Commitment
Competitor
CompetitorAddress
CompetitorProduct
CompetitorSalesLiterature
ComplexControl
Connection
ConnectionRole
ConnectionRoleAssociation
ConnectionRoleObjectTypecode
ConstraintBasedGroup
Contact
ContactInvoices
ContactLeads
ContactOrders
ContactQuotes
Contract
ContractDetail
ContractTemplate
ConvertRule
ConvertRuleItem
CustomControl
CustomControlDefaultConfig
CustomControlResource
CustomerAddress
CustomerOpportunityRole
CustomerRelationship
D
DataPerformance
DelveActionHub
Dependency
DependencyFeature
DependencyNode
Discount
DiscountType
DisplayString
DisplayStringMap
DocumentIndex
DocumentTemplate
DuplicateRecord
DuplicateRule
DuplicateRuleCondition
DynamicProperty
DynamicPropertyAssociation
DynamicPropertyInstance
DynamicPropertyOptionSetItem
E
Email
EmailHash
EmailSearch
EmailServerProfile
EmailSignaturE
Entitlement
EntitlementChannel
EntitlementContacts
EntitlementProducts
EntitlementTemplate
EntitlementTemplateChannel
EntitlementTemplateProducts
EntityMap
Equipment
ExchangeSyncIdMapping
ExternalParty
ExternalPartyItem
F
Fax
Feedback
FieldPermission
FieldSecurityProfile
FilterTemplate
FixedMonthlyFiscalCalendar
G
Goal
GoalRollupQuery
H
HierarchyRule
HierarchySecurityConfiguration
I
ImageDescriptor
Import
ImportData
ImportEntityMapping
ImportFile
ImportJob
ImportLog
ImportMap
Incident
IncidentKnowledgeBaseRecord
IncidentResolution
IntegrationStatus
InternalAddress
InterProcessLock
InvalidDependency
Invoice
InvoiceDetail
IsvConfig
K
KbArticle
KbArticleComment
KbArticleTemplate
KnowledgeArticle
KnowledgeArticleIncident
KnowledgeArticlesCategories
KnowledgeArticleViews
KnowledgeBaseRecord
KnowledgeSearchModel
L
LanguageLocale
Lead
LeadAddress
LeadCompetitors
LeadProduct
Letter
License
List
ListMember
LocalConfigStore
LookupMapping
M
Mailbox
MailboxStatistics
MailboxTrackingFolder
MailMergeTemplate
MetadataDifference
Metric
MobileOfflineProfile
MobileOfflineProfileItem
MobileOfflineProfileItemAssociation
MonthlyFiscalCalendar
MsDynPostAlbum
MsDynPostConfig
MsDynPostRuleConfig
msdynwallsavedquery
MsDynWallSavedQueryUserSettings
MultiEntitySearch
MultiEntitySearchEntities
N
Notification
O
OfficeDocument
OfficeGraphDocument
Opportunity
OpportunityClose
OpportunityCompetitors
OpportunityProduct
OrderClose
Organization
OrganizationStatistic
OrganizationUI
OrgInsightsMetric
Owner
OwnerMapping
P
PartnerApplication
PersonalDocumentTemplate
Phonecall
PicklistMapping
PluginAssembly
PluginTraceLog
PluginType
PluginTypeStatistic
Position
Post
PostComment
PostFollow
PostLike
PostRegarding
PostRole
PriceLevel
PrincipalAttributeAccessMap
PrincipalEntityMap
PrincipalObjectAccess
PrincipalObjectAccessReadSnapshot
PrincipalObjectAttributeAccess
PrincipalSyncAttributeMap
Privilege
PrivilegeObjectTypeCodes
ProcessSession
ProcessStage
ProcessTrigger
Product
ProductAssociation
ProductPriceLevel
ProductSalesLiterature
ProductSubstitute
Publisher
PublisherAddress
Q
QuarterlyFiscalCalendar
Queue
QueueItem
QueueItemCount
QueueMemberCount
QueueMemberShip
Quote
QuoteClose
QuoteDetail
R
RatingModel
RatingValue
RecommendationCache
RecommendationModel
RecommendationModelMapping
RecommendationModelVersion
RecommendationModelVersionHistory
RecommendedDocument
RecordCountSnapshot
RecurrenceRule
RecurringAppointmentMaster
RelationshipRole
RelationshipRoleMap
ReplicationBacklog
Report
ReportCategory
ReportEntity
ReportLink
ReportVisibility
Resource
ResourceGroup
ResourceGroupExpansion
ResourceSpec
RibbonCommand
RibbonContextGroup
RibbonCustomization
RibbonDiff
RibbonRule
RibbonTabToCommandMap
Role
RolePrivileges
RoleTemplate
RoleTemplatePrivileges
RollupField
RollupJob
RollupProperties
RoutingRule
RoutingRuleItem
S
SalesLiterature
SalesLiteratureItem
SalesOrder
SalesOrderDetail
SalesProcessInstance
SavedOrgInsightsConfiguration
SavedQuery
SavedQueryVisualization
SdkMessage
SdkMessageFilter
SdkMessagePair
SdkMessageProcessingStep
SdkMessageProcessingStepImage
SdkMessageProcessingStepSecureConfig
SdkMessageRequest
SdkMessageRequestField
SdkMessageResponse
SdkMessageResponseField
SemiAnnualFiscalCalendar
Service
ServiceAppointment
ServiceContractContacts
ServiceEndpoint
SharePointData
SharePointDocument
SharePointDocumentLocation
SharePointSite
SimilarityRule
Site
SiteMap
SLA
SLAItem
SLAKPIInstance
SocialActivity
SocialInsightsConfiguration
SocialProfile
Solution
SolutionComponent
SQLEncryptionAudit
StatusMap
StringMap
Subject
Subscription
SubscriptionClients
SubscriptionManuallyTrackedObject
SubscriptionStatisticsOffline
SubscriptionStatisticsOutlook
SubscriptionSyncEntryOffline
SubscriptionSyncEntryOutlook
SubscriptionSyncInfo
SubscriptionTrackingDeletedObject
SyncAttributeMapping
SyncAttributeMappingProfile
SyncError
SystemApplicationMetadata
SystemForm
SystemUser
SystemUserBusinessUnitEntityMap
SystemUserLicenses
SystemUserManagerMap
SystemUserPrincipals
SystemUserProfiles
SystemUserRoles
SystemUserSyncMappingProfiles
T
Task
Team
TeamMembership
TeamProfiles
TeamRoles
TeamSyncAttributeMappingProfiles
TeamTemplate
Template
Territory
TextAnalyticsEntityMaping
Theme
TimeStampDateMapping
TimeZoneDefinition
TimeZoneLocalizedName
TimeZoneRule
Topic
TopicHistory
TopicModel
TopicModelConfiguration
TopicModelExecutionHistory
TraceAssociation
TraceLog
TraceRegarding
TransactionCurrency
TransformationMapping
TransformationParameterMapping
U
UnresolvedAddress
UoM
UoMSchedule
UserApplicationMetadata
UserEntityInstanceData
UserEntityUISettings
UserFiscalCalendar
UserForm
UserMapping
UserQuerUserQueryVisualization
UserSettings
W
WebResource
WebWizard
WizardAccessPrivilege
WizardPage
Workflow
WorkflowDependency
WorkflowLog
WorkflowWaitSubscription

Download Whitepaper

Microsoft Dynamics CRM Connector Tool Output

The Microsoft Dynamics CRM Connector tool can output either a “success” or “error” XML document depending on whether the execution of the step at run time is successful or not.

Each of these XML documents can then be used within other BPA Platform tools, either as is or through a conversion to a BPA Platform recordset using the Convert XML to Recordset tool. In this case, the Microsoft Dynamics CRM Connector step is selected as the input data source by a subsequent step. This can be beneficial if you wish to log the outcome of a call.

“Success” XML Document

Where successful, the output provides you with the response back from Dynamics CRM and displays the sum total of its processing, i.e. the structure of successful calls.

The object the tool interacted with and the exchange of data between the object fields will all be presented in an XML schema.

The structure of this schema is defined by the chosen mappings made within the Mapping tab of the tool.

“Error” XML Document

An error XML output is always produced when a call is unsuccessful, this may be generated internally by the Microsoft Dynamics CRM Connector tool or received by the tool from Dynamics CRM.

Any errors that occur are created as an <ERROR> node. Similar to a “success” document, it will be presented in an XML schema showing any attempted interaction with a chosen object.

Runtime

The incoming XML is translated into the XML format for the object and operation selected in the configuration. The data for the linked fields is brought across into the output XML — only those fields that were linked are brought across. The XML is passed to the connector tool, which then:

• Processes the data
• Performs the operation requested
• Sends back an XML document containing the response

The XML can then be used by other BPA Platform steps.

Download Whitepaper

Error Handling

Errors are written to the BPA Platform Event Log (Manage > Event Log). You define how errors are handled in the Options tab of the Microsoft Dynamics CRM Connector tool.

Reasons for the errors could include:

• Web service connection errors
• User privilege errors
• Errors from the Microsoft Dynamics CRM API
• Warnings and messages from the Microsoft Dynamics CRMAPI

Microsoft Dynamics CRM Accounts Security

The Microsoft Dynamics CRM API is the only method used to connect to a Microsoft Dynamics CRM database, and perform read / write tasks — all security present in the API is used.