Tutorial: Configuring SAS Customer Intelligence 360 Channel Integrations with Custom Task Types

[BojanBelovic]

Custom Task Types have been released with 23.11 release of SAS Customer Intelligence 360 (in November 2023). This new functionality gives administrators and power users the capability to configure new task types for use by marketing users and leverage existing connector framework integration capabilities.

This post will walk you through a process of configuring a new integration with a third-party service from beginning to end with no code involved. The post is aimed at more technical resources and administrators who will be responsible for connector and custom task type configuration but will be useful to any user of SAS CI360. There is no code involved and everything is done through the CI360 UI, but in order to follow the tutorial step-by-step, one will need some familiarity with web services and APIs in general, and access to an account to be used for connector we are configuring.

The goal is to provide a step-by-step guide to building a fully functional task type (in this case SMS) and demonstrate the ease of doing so. By the end of this article, you will understand how to configure a new connector in CI360 to integrate with an external SMS provider and then create a new task type that marketing users can use to communicate with third party services and customers.

Throughout this post we will assume we are working on a triggered SMS task, and whenever a connector is referenced, it is assumed a triggered connector is being used. At the time of the writing, this is still the only type of connector available, however, bulk custom connectors will be available in CI360 in the future.

About SAS CI360 connectors and custom task types

SAS Customer Intelligence 360 connector framework allows customers to easily integrate additional external systems, further leverage, and enhance CI360 customer journey orchestration capabilities.

Custom task types deliver content to a third-party application by using custom connectors. A custom task type is a template from which users can create multiple custom tasks. You can configure the custom task type with predefined data attributes depending on what data you need or want to send to the third-party application. Once configured by an administrator, custom task types behave like any other task in the system.

You can find more information about connectors and custom task types in CI360 documentation:

https://go.documentation.sas.com/doc/en/cintcdc/production.a/cintag/ch-connectors-about.htm

https://go.documentation.sas.com/doc/en/cintcdc/production.a/cintag/custom-task-create.htm

The most important thing to know and understand when working with triggered connectors in CI360, is that the connector framework in CI360 is event-based framework, as is the whole CI360 platform. When any instance of a Custom Task Type is invoked within CI360 it generates an outbound event which is then processed by the connector framework and passed on to an external API, or in this case, our connector function.

The outbound event is a JSON object that contains all the information we need for execution, and we need to call our target system (and more). All the information we need to pass to an external service is contained within this JSON object and will be mapped to an external API using Custom Request Body feature of a connector endpoint.

SMS Service Example

For the purposes of this tutorial, we will configure a connector for SAS partner Syniverse, which provides a variety of messaging services, including SMS. We will also configure a new SMS custom task type, and see how it is used by marketing user, either standalone or in activity map.

While we are focusing on one specific service provider and one specific channel to make this tutorial as real as possible, and the choice of SMS as a channel is due to its simplicity, but the approach is applicable to any other combination of service provider and channel.

If you want to configure this as a working example in your environment, you will need a Syniverse access token. If you’d like to get one, as well as further explore Syniverse offering and capabilities, you can get a developer account at: https://developer.syniverse.com/

Configuring the Connector

We will start by configuring a new connector and connector endpoint that will invoke Syniverse messaging API.

We can name the connector and provide contact details, which are used for any alerts. For public APIs provided by third party platforms, we likely won’t need to use Access point routing, as that mostly applies to communication with internal systems that are now publicly accessible.

Then we configure the endpoint details. These will come from service provider, in this case Syniverse. We will need the service endpoint URL and HTTP method, which is POST in this case.

For reference purposes, we can look at Syniverse API documentation:

https://sdcsupport.syniverse.com/hc/en-us/articles/236185587-SCG-Quick-Start-guide

We will use their Message Request endpoint in this example: https://api.syniverse.com/scg-external-api/api/v1/messaging/message_requests

For Authorization, Syniverse uses a Bearer token which users can get from their console at: https://developer.syniverse.com/. In the screenshot below, I have blurred the actual token for security purposes.

Finally, we need to provide the API request format, which again we can get from provider’s documentation, and then map data generated and populated by SAS CI360 to vendors API payload.

Mapping involves pairing up variables we specified in the request body above (such as sender_id or mobile_num) to elements in standard CI360 outbound system event JSON payload.

This is where it is useful to understand CI360 outbound event structure. For the purposes of our tutorial, we need three data elements:

• message_text will come from the Plain Text creative used in our SMS task, and thus will be stored in a string variable with JSON path $.impression.creativeContent
• sender_id and mobile_num will also be string variables and will come from Delivery / Outbound Data tab of our task, and will be stored in string variables with JSON path $.outboundProperties.properties.sender_id and $.outboundProperties.properties.mobile_num respectively

Any variable defined in Outbound Data section of a custom task will be available under JSON path $.outboundProperties.properties.

It is worth noting that we are defining the variable mapping here and referencing event structures for task that does not exist yet. When configuring integrations with triggered connectors and custom task types, some planning ahead of time is a good practice, so that we know what the data elements are that user will have to provide within the task that are needed by the service API, as in this example.

Creating the Custom Task Type

Once we have configured the connector endpoint, we can create the Custom Task Type for that endpoint. Select the endpoint and click “New custom task type”. We can also create a custom task type from Custom Task Types section of General Settings.

Configure the look and feel of our new task. This is where you can provide the name, user friendly description and icon and color for the task. In case we are building vendor specific task (e.g. Facebook or WhatsApp) it is a good idea to match vendor primary color, which can be done by using custom color functionality of the color picker and entering color RGB value.

Event name needs to be specified, and it is the name of the event that is generated when a task of this type is executed, just like any other task in the system. Be thoughtful of how this event is being named, since it will be available with specified name for every task, every customer, and every interaction, in UDM and within CI360 for targeting purposes.

Note that we need to indicate if Content tab will be present. This will depend on various integrations, but for SMS we want this enabled as we need to include text creative with the message.

In this tutorial, we won’t be including any custom properties, but if those are needed, new custom properties categories can be defined with class name “customTask” in Custom Properties spreadsheet. For more information on working with custom properties, see:

https://go.documentation.sas.com/doc/en/cintcdc/production.a/cintag/prop-custom-config.htm

Next step is to configure data elements that need to be provided when SMS task is being executed, and these are straight-forward: we need to know which number the message is being sent from, and who is the recipient of the message. In some cases, there may only be one originating number, in which case we could simplify this even more and only require recipient phone number.

For each element we define, we need to indicate whether it’s required or not, and whether the data contained falls under PII. Anything marked as PII will be made available to the connector framework (as will non-PII data), but PII data will not be stored or tracked in CI360 after the execution is completed.

Some data attributes can be defined as dropdown lists. An effective use for dropdown lists is when users have to choose between a small number of pre-defined values and/or when we need to provide a user-friendly display name for otherwise cryptic value as in the example below.

For those following the tutorial and configuring this integration in their environment, for testing purposes, you can use Syniverse public channels, available in Messaging Accounts section of Voice and Messaging console.

If the task type has standard metrics based on previously defined events, they can be included here. Note that we are still configuring the task type definition, which means that metrics we define here will be available by default in every instance of our new task. Marketing users can then add additional metrics to individual tasks if needed.

Using the new SMS task

With out new SMS custom task type configured and activated, we can try it out.

As soon as it’s marked active, SMS task will become available on New Task screen.

From there, marketing users can just use it like any other task – selecting content to use, defining delivery attributes, targeting and properties if desired, or specifying a triggering event.

For SMS messages, plain text creative is of course the right choice. We can personalize the message using merge tags just like in any other task.

On the delivery tab, we need to only provide two delivery attributes – the number messages will come from, which simply involves selecting a desired drop-down value (if more than one was defined at all) and providing a recipient mobile number.

Customer’s mobile number can come in the form of a merge tag, either using a triggering event attribute or a customer profile attribute stored in CI360 data hub.

And finally, we can either execute this task by defining an event Trigger in Orchestration tab of the task, or include it in an activity map as shown below.

If we trigger and execute our new task we will deliver the message to the mobile phone(s).

Conclusion

You can now see how creating a brand new task for use in CI360 involves just a handful of screens once you have all the necessary information, and can in most cases be accomplished through UI configuration only, with no code needed.

Some more complex integrations, specifically where data manipulation or multiple API calls to target platform are required, will still need a connector function to be invoked from the connector. But with release of Custom Task Types in combination with existing connector functionality including Custom Request Body mapping, this number is smaller than ever.

If connector function is in fact required, this tutorial still applies, but the endpoint specified in the connector will the that of the connector function instead of the third-party service API (and it will be connector function’s job to make the calls to the service API). If you’d like more information about writing connector functions, you can read my other post on SAS Communities titled “Tutorial: Building a SAS Customer Intelligence 360 Connector Function”.

Tutorial: Building a SAS Customer Intelligence 360 Connector Function 

Sample Outbound Event Object

For reference, you will find a partial sample event JSON object below. Actual event object contains more information, and type of information carried depends on the type of event itself, but we are limiting the data included to select fields and child objects for space and readability, limited mostly to data referenced in this post.

{
    "guid": "d27f3313-c283-41f0-b2ce-807f823dc28f",
    "eventName": "Outgoing_SMS_Dynamic_External_CRM_v1",
    "eventType": "outboundSystem",
    "sessionId": "2987",
    "channelId": "2987",
    "channelType": "external",
    "date": {
        "generatedTimestamp": 1666274457377,
        "utcOffset": null
    },
    "externalTenantId": "115886462700013adcd822d0",
    "internalTenantId": 1029,
    "identityId": "805bfeca-d9e3-378f-a533-bf5597199652",


    "properties": {
        "subject_id": "2987",
        "sender_id": "channel:FLRGRJQfODhmSlmljKMYB3",
        "externalCode": "TSK_168",
        "channel_user_type": "subject_id",
        "parent_event": "external"
    },

    "outboundProperties": {
        "properties": {
            "sender_id": "channel:FLRGRJQfODhmSlmljKMYB3",
            "mobile_num": "+19195550000"        
        }
    },

    "contactResponse": {
        "contactResponseCode": null,
        "contactResponseTag": null,
        "responseTrackingCode": "3469e066-1499-4c9c-be57-4cf10318ee01",
        "responseType": null,
        "responseValue": null
    }


    "impression": {
        "controlGroup": null,
        "creativeId": "24bb3c95-1814-44a6-9062-97c921f62880",
        "creativeVersionId": "d4uR8KF1R5l2KZiSHpK_17oJqW4Nvfmc",
        "creativeContent": "Hi Bojan! This is your first messages from SAS CI360 SMS custom task type!",
        "goalEvent": null,
        "goalId": null,
        "imprintId": "0",
        "isControlGroup": false,
        "taskId": "643faaa4-e3fd-4dcb-bfff-afcd707058dc",
        "taskName": null,
        "taskType": null,
        "taskVersionId": "IebUmaAlGshdqO_jE8xa2NEDt9G6mIvK"
    }

[BojanBelovic]

It appears the free developer/trial accounts are not currently available through Syniverse. Tutorial and all the steps are still valid, and also a good example of end-to-end integration with a different service, one just will not be able to follow the steps in this tutorial and create a working connection without having the credentials already. I will work on publishing an updated tutorial using a different service as an example that does provide free trial accounts.

[BojanBelovic]

Part 2 of this tutorial, showing an example of configuring a custom task type with a different service provider is here: https://communities.sas.com/t5/SAS-Customer-Intelligence/Tutorial-SAS-Customer-Intelligence-360-Cust...