To fully understand how xConnect and OData work, it's helpful to manually construct requests and analyze network traffic. Network analyzers are irreplaceable supplements for debugging and implementing integration layer to service such as xConnect. By examining the underlying REST requests, we can get deep insights into service mechanics.
Fiddler is a web debugging tool which logs all HTTP(S) traffic between your computer and the Internet. You can use it to inspect traffic, set breakpoints, and “fiddle” with incoming or outgoing data.
Fiddler enables us to import the xConnect client certificate and establish a manual, low level client. It provides the Composer tool to create custom requests. By default, Composer located at right panel, under the Composer tab.
First, we need to set up xConnect client certificates, so the network analyzer can decrypt SSL traffic and make requests readable. Convert your xConnect client certificate from crt to cer format using OpenSSL. Then, put it in your Fiddler directory as "ClientCertificate.cer" file (C:\Users\<username>\Documents\Fiddler2\ClientCertificate.cer) and it's set.
Before we start making requests, we need to understand our data schema. It's provided by OData metadata file, located at https://<yourinstance>/odata/$metadata. Take your time to read it thoroughly. It describes entities, relations and endpoints we can query.
Let's get familiar with Contact, ContactIdentifier and Facet entities, as we will create and bind them in the next section.
ContactIdentifiers are unique identifiers used to query Contact entities, as defined by Source and Identifier fields. Contact entities wrap ContactIndentifiers and serve as links to Facet entities. Facets are sets of data used to add more context to Contacts. In this example, we will add the PersonalInformation Facet to our Contact.
By following the OData definition file, we can construct a JSON payload to create sample Contact and ContactIdentifier:
The Identifier field is a randomly generated GUID. The official library does that under the hub, but feel free to generate it using online tools. Then, go ahead and post that JSON to https://<yourinstance>/odata/Contacts.
If everything is set up correctly, a response like this should appear:
It's important to save the Id xConnect returned, as we will use it to fetch the created Contact and bind Facets.
Same Contact can now be retrieved by querying ContactIdentifier, such as the following Get request:
https://<yourinstance>/odata/Contacts?$filter=Identifiers/any(id:id/Identifier eq 'Test' and id/Source eq 'Coria')
Next we will add PersonalInformation Facet to the same contact. PersonalInformation can carry a lot of personal data about a Contact. In this example, we will use FirstName and LastName.
Contact GUID must be included as endpoint parameter, so XConnect knows which Contact to bind Facet to. Let's post this JSON to the following endpoint https://<yourinstance>/odata/Contacts(a5a9d2dd-bf85-0000-0000-052ddc0cf60e)/Personal.
Response should be similar to the following:
There you go! Congratulations on adding Corry Corian to your Sitecore9 xDB. Stay tuned for more content, as our next post will cover this same functionality, using official library.
If you missed our first post from the series, you can see it here: xConnect - Overview. You can also check the next post in the series here: xConnect - Debugging with Fiddler.
Feel free to contact us if you have any questions!