CRM Service Wrapper User Guide

Size: px

Start display at page:

Download "CRM Service Wrapper User Guide"

Elisabeth Wood
5 years ago
Views:

1 Summary This document details the usage of the CRM Service Wrapper by xrm. The service wrapper allows you to communicate with a Microsoft Dynamics CRM application (called CRM for convenience in this document) without having to deal with the authentication and other details of the Microsoft provided API. The wrapper provides a simplified interface to connect to CRM and perform basic CRUD (create, retrieve, update, and delete) operations. The service expects JSON (JavaScript Object Notation) payloads to be provided via an HTTP POST to the service. The service responds back with a JSON result, including success or failure and any error message. Please see the specific operation section for details on the payloads and responses for each operation.

2 Authentication The service accepts a pre-assigned API Key and Access Token. This information is wrapped inside an authenticationdetails object within the JSON payload. This information should be passed in with each request. An example is displayed below (with asterisks representing placeholders for real data that must be supplied during actual use): authenticationdetails: ApiKey: ********, AccessToken: ******** This nested object within the JSON payload is required for all operation types. The attributes are explained in detail below: ApiKey: A unique key assigned to your application. AccessToken: A unique token assigned to your application. This information should not be shared publicly. Page 2 of 11

3 Create The Create operation is used to create new records in CRM. No duplicate detection is performed during the creation of records using the service. The service returns back the unique identifier in the CRM system (the Globally Unique Identifier, or GUID, for the record, consisting of 32 alphanumeric characters interspersed with 4 - separator characters). The URL to perform the create operation is below: /Crm2013Service.aspx/Create An HTTP POST should be performed to the address above. The content type should be set to application/json. The payload should include the authenticationdetails object, along with the logical name of the entity being created, and the attributes to create for the entity. An example of the JSON payload is listed below. ( represents missing information that must be supplied in actual use.) For more information regarding the authenticationdetails object, please see the Authentication portion of this document. authenticationdetails:, logicalname: contact, attributes: firstname: John, lastname: Smith, address1: john.smith@example.com The attributes are explained below: authenticationdetails: Please refer to the authentication portion of this document. logicalname: (The leading l must be lowercase.) This should be set to the logical name of the entity in CRM. The approach to locate the logical name for an entity is outside the scope of this document. Page 3 of 11

4 attributes: This contains all the attributes of the entity that should be given values when the record is created. See the attribute portion of this document for more details on how to handle specific, and more complex, attributes. The service returns back a CreateResult object in JSON format. The object contains the following attributes: RecordId: If successful, this contains the unique identifier (GUID) for the new record, as returned by CRM. Success: A boolean flag indicating whether the operation was a success or not. ErrorMessage: If the Success flag is set to false, this attribute contains a detailed error message. Page 4 of 11

5 Update The Update operation is used to update existing records in CRM. The URL to perform the update operation is below: /Crm2013Service.aspx/Update An HTTP POST should be performed to the address above. The content type should be set to application/json. The payload should include the authenticationdetails object, along with the logical name of the entity being updated, and the attributes to update. In addition, the unique identifier attribute must be specified as well. An example of the JSON payload is listed below ( and * represent data that must be supplied during actual ues). For more information regarding the authenticationdetails object, please see the Authentication portion of this document. authenticationdetails:, logicalname: contact, attributes: contactid: ******, firstname: John, lastname: Smith, telephone1: (555) The attributes are explained below: authenticationdetails: Please refer to the authentication portion of this document. logicalname: This should be set to the logical name of the entity in CRM. The approach to locate the logical name for an entity is outside the scope of this document. Attributes: All the attributes that should be updated on the entity. In addition, the primary key should be provided as well. There s no need to include attributes whose values should remain unchanged in the Page 5 of 11

6 updated record. In the example above, the primary key is contactid. See the attribute portion of this document for more details on how to handle specific, and more complex, attributes. The service returns back an UpdateResult object in JSON format. The object contains the following attributes: Success: A boolean flag indicating whether the operation was a success or not. ErrorMessage: If the Success flag is set to false, this attribute contains a detailed error message. Page 6 of 11

7 Delete The Delete operation is used to delete existing records in CRM. The URL to perform the delete operation is below: /Crm2013Service.aspx/Delete An HTTP POST should be performed to the address above. The content type should be set to application/json. The payload should include the authenticationdetails object, along with the logical name of the entity being deleted and its unique identifier (GUID). An example of the JSON payload is listed below ( and * represent missing information that must supplied during actual use). For more information regarding the authenticationdetails object, please see the Authentication portion of this document. authenticationdetails:, logicalname: contact, entityid: ****** The attributes are explained below: authenticationdetails: Please refer to the authentication portion of this document. logicalname: This should be set to the logical name of the entity in CRM. The approach to locate the logical name for an entity is outside the scope of this document. entityid: The unique identifier (GUID) of the record to be deleted. The service returns back a DeleteResult object in JSON format. The object contains the following attributes: Success: A boolean flag indicating whether the operation was a success or not. ErrorMessage: If the Success flag is set to false, this attribute contains a detailed error message. Page 7 of 11

8 Retrieve The retrieve operation is used to retrieve (or read ) existing records from the database. The URL to perform the retrieve operation is below: /Crm2013Service.aspx/Retrieve An HTTP POST should be performed to the address above. The content type should be set to application/json. The payload should include the authenticationdetails object, along with the entity name to retrieve, and additional attributes that will be searched. If the unique identifier for the record is also supplied, then oly the unique identifier will be utilized to retrieve the record. The last parameter is the list of attributes to retrieve for the records that match the search criteria. An example of the JSON payload is listed below. ( represents information that must be supplied during actual use.) For more information regarding the authenticationdetails object, please see the Authentication portion of this document. authenticationdetails:, logicalname: contact, searchattributes: firstname: John, lastname: Smith, returnedattributes: [ firstname, lastname, address1, telephone1 The attributes are explained below: authenticationdetails: Please refer to the Authentication portion of this document. logicalname: This should be set to the logical name of the entity in CRM. The approach to locate the logical name for an entity is outside the scope of this document. searchattributes: This object should contain all the attributes to search for. Multiple search attributes are treated with logical AND. In the example provided, all contacts with the first name John and the last Page 8 of 11

9 name Smith will be returned. If the unique identifier of the object is already provided in the searchattributes object, then only that record is retrieved regardless of any other attributes provided. returnedattributes: The returned results will only have these attributes populated. The service returns back a RetrieveResult object in JSON format. The object contains the following attributes: RetrievedRecords: An array of Entity record objects as returned by CRM, identified by their GUIDs. Success: A boolean flag indicating whether the operation was a success or not. ErrorMessage: If the Success flag is set to false, this attribute contains a detailed error message. Page 9 of 11

10 Attributes The following section describes the different attributes that are supported by the service, and how to pass those parameters into the service when creating, retrieving, or updating records. String String values must be passed in as a JSON string both when making modifications and when searching. Strings should be surrounded in single quotes. BigInt and Integer BigInt and Integer fields can be passed in as a JSON integer value or a JSON string. The service will convert the string to an integer while processing. Boolean Boolean values can be passed into the service as either a JSON Boolean value (true or false) or a string ( true or false ). Customer, Lookup, and Owner These objects must be handled in a special way, because each can represent any of certain multiple entities. They must be passed in as a nested JSON object. There are two attributes of the object that are required: Id and LogicalName. (The leading L must be uppercase in this context.) An example of the object is below: Id: UniqueIdentifier, LogicalName: account The Id field should be the unique identifier (GUID) of the record in CRM. The LogicalName attribute should be set to the logical name of the entity that the record is an instance of. (For example, a Customer must be determined as either contact or account.) Date and Time Attributes of type Date and Time can be passed in as a JSON date or as a string. The string will be parsed and converted to a Date object. Page 10 of 11

11 Decimal and Double Decimals and doubles are treated the same within the service wrapper. They can be passed in as a decimal value or a string. The string will be parsed into the appropriate CRM type. Money Money values must be passed in as a decimal. A currency symbol doesn t need to be supplied. Memo and String Attributes of type Multiple Lines of Text (sometimes called Memo) and type Single Line of Text must be passed in as strings surrounded by single quotes. If the string needs to contain a single quote character, it can be escaped with \. Option Set UniqueIdentifier The unique identifier for records can be passed in as either a GUID or a string. The string will be parsed into a GUID if provided. Page 11 of 11 Toll Free: Main Number: (949) sales@xrm.com

How to Create Fields in Microsoft CRM Online

How to Create Fields in Microsoft CRM Online Go to https://portal.office.com and log in. Then switch from portal to CRM from the square menu. Once in CRM you need to go to the form you wish to add fields