Set up your Web Service

The JSON Pull Web Service Data Adapter currently supports JSON Schema Draft 4. interacts with external sources using a client web service, that can receive data from the data adapter.

General Requirements

This web service must be built on RESTful concepts, and conform to the following requirements:

• Must accept JSON requests and responses. The response type is determined by the ACCEPT header in the response.
• Must use the following HTTP verbs:
  • POST for Create requests
  • PUT for Update requests
• Must return either an HTTP 201 or HTTP 202 response code. When communicating with The JSON Pull Web Service Data Adapter currently supports JSON Schema Draft 4., if your endpoint does not return either of these codes, you will see an error in Monitor regardless of whether or not the request was actually successful.If the endpoint returns a message in the response, for example, JSON or HTML, The JSON Pull Web Service Data Adapter currently supports JSON Schema Draft 4. regards this as an error message and display an error in Monitor.To avoid seeing errors in Monitor, ensure your endpoint returns either an HTTP 201 or HTTP 202 response code and an empty response.
• Must have a valid SSL certificate installed. This ensures communication occurs over a secure channel using HTTPS. Note that the certificate cannot be self-signed.
• Must be exposed to the web. For example, by adding the service to your external DNS.
• Must add details of the The JSON Pull Web Service Data Adapter currently supports JSON Schema Draft 4. server's outgoing IP address range to the service's whitelist, if communication with the service is to be limited to a specific range of IP addresses. We also advise whitelisting the IP address of the main company office, to assist with debugging.
• Must support either OAuth 2.0 Client Credentials, API key, or Basic authentication.

URL Requirements

When configuring the JSON Push Web Service Data Adapter to work with your web service, you must provide one or both of the following URLs:

• Create Data URL
• Update Data URL

These URLs are required by The JSON Pull Web Service Data Adapter currently supports JSON Schema Draft 4. to access your web service.

The JSON Push Web Service Data Adapter supports the use of port numbers in both the Create Data and Update Data URLs. We recommend, however, that port numbers are only used in URLs for testing purposes and not in a production environment.

Create Data URL

The Create Data URL is typically used to create new customer records in your CRM. It can also be used, for example, to allow The JSON Pull Web Service Data Adapter currently supports JSON Schema Draft 4. to push data to your system to generate a lead or trigger an outbound communication for either an existing or a new customer.

Example

https://mycompany.com/myRESTservice/createlead/

Update Data URL

The Update Data URL enables you to update data held in existing customer records in your CRM. For example, to update an existing customer record based on behavioral insights derived in The JSON Pull Web Service Data Adapter currently supports JSON Schema Draft 4..

This URL must contain a placeholder for the customer key. At runtime, this is replaced by a customer key held in your system.

Example

https://mycompany.com/myRESTservice/updatecustomerdata/{key}

Points to Note

• The customer key placeholder must be in the format .
• The customer key placeholder can be located anywhere in the URL.
• Any captured attribute held in the Customer Metadata data adapter can be used as the key.

Supported Authentication Methods

The JSON Web Service Data Adapter supports the following authentication mechanisms for calling the web service:

• HTTP Basic
• OAuth 2.0
• API Key

HTTP Basic

HTTP Basic provides the simplest method for authenticating communications between your web service and The JSON Pull Web Service Data Adapter currently supports JSON Schema Draft 4..

HTTP Basic passes a username and password over the network as unencrypted base64 encoded text, and should only be used with HTTPS.

The HTTP Basic authentication method is based on the principle that each HTTP request from the data adapter includes an authorization header that specifies the credentials required to access the secure data.

A full description of the HTTP standard, is available at the following link: HTTP Authentication: Basic and Digest Access Authentication.

Example HTTP Authorization Header

An authorization header is constructed, as follows:

1. Combine the username and password into a string username:password.
2. Encode the resulting string using the RFC2045-MIME variant of Base64.You are not limited to 76 characters per line.
3. Add the authorization method and a space, for example, Basic before the encoded string.

For example, if the username is 'Aladdin' and the password is 'open sesame' the header is formed, as follows:

Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

OAuth 2.0

OAuth is an open standard for authorization, that provides a simple way to both publish and interact with secure, protected data. OAuth provides client applications with secure delegated access to server resources on behalf of the resource owner. It also specifies a process for resource owners to authorize third-party access to their server resources without sharing their credentials.

A full description of the OAuth2 standard is available at the following link: The OAuth 2.0 Authorization Framework.

OAuth 2.0 defines four main grant types:

• Authorization code
• Implicit
• Resource owner password credentials
• Client credentials

Both the JSON Pull and JSON Push Web Service Data Adapters use the client credentials grant type.

When configuring the Data Adapter, you must provide:

• Username (Client_id)
• Password (Client_secret)
• URL used to obtain an OAuth 2 access token

You can also choose how to deliver the credentials:

• In the request header (default)
• In the request body

Scope

The JSON Push Web Service adapter offers an optional Scope field you can use to specify the scope of the access request when using OAuth 2.0 authentication. Scope is an optional text field. If you do not define a scope, the adapter does not send this field.

For more information about setting up the client credentials grant type, see the Client Credentials Grant and Action Token Scope documentation.

API Key

If using API Key as your authentication method, you must provide:

• API key header name
• API key value

Supported JSON Payload Formats

The JSON Push Web Service adapter supports two different payload formats:

• Standard JSON. Converts Data Structures into the standard JSON payload format. By default, all new Data Adapters are configured to use this format.
• Legacy Mode. Converts Data Structures into the legacy JSON payload format. By default, any existing Data Adapters will continue to use this format, unless you manually change the payload format to Standard JSON.

Example

You have the following Push Data Structure configured:

When the Data Adapter is triggered at runtime, the Data Structure is converted and the following payload is pushed to your customer records system:

Standard JSON

{ email : “email@address.com”, product : “C1B-PBANK-SAVE-MM”}

Legacy Format

{"root":[{"name":"email", "data":"email@address.com", "type":"SYMBOLIC"}, 
{"name":"product", "data":"C1B-PBANK-SAVE-MM", "type":"SYMBOLIC"}], "list":false}}

Configure the Adapter

1. In The JSON Pull Web Service Data Adapter currently supports JSON Schema Draft 4., choose Collect.

2. Select External Data, click Create.

3. Choose JSON Push Web Service as the type of Data Adapter you want to add.

4. Enter a name for the Data Adapter you are adding. Using a descriptive name makes it easier for you and your team members to know when to use the Data Adapter.

5. Enter a brief description of the Data Adapter you are adding and when it should be used.

6. Enter the configuration details that define the adapter's behavior.

   Field	Description
   Create data URL	URL for your Create data API, in the following format: https://hostname.com/api/. For example, https://acompany.com/create_lead/
   Update data URL	URL for your Update data API, in the following format: https://hostname.com/api/. For example, https://acompany.com/update_contact/4756097
   JSON Format	The JSON payload format to use when passing information to your existing systems. Choose between Standard JSON and Legacy Mode.
   Authentication method	Choose one of the following: - HTTP Basic. Requires a username and password. - OAUTH2. Requires a username, password, and security token. You can send credentials in either the header or body of the request. - API Key. Requires a header name and API key value.
   Security token URL	URL used to obtain an access token for OAUTH2.
   Username	Enter one of the following: - Valid API username for HTTP Basic. - Client ID for OAuth 2.0. - API Key Header Name for API Key.
   Password	Enter one of the following: - Valid API password for HTTP Basic. - Client Secret for OAuth 2.0. - API Key Value for API Key.
   Scope	Optional. Text value representing the scope of the access request when using OAuth 2.0 authentication.

7. Click Test configuration. This tests and verifies that the new configuration details are valid.

8. Click Apply.

9. Click Save.

Common Error Messages

The following table outlines the most common errors reported in The JSON Pull Web Service Data Adapter currently supports JSON Schema Draft 4..