Introduction

this section covers off some import information to consider when implementing this integration with jomablue sns message format the payload in the sns message is escaped appropriately for json, but the examples provided in this document do not contain escaped characters for ease of understanding jomablue data is published in the "message" value of the sns payload an example of the raw sns payload is below each message contains resource type within the message as well as at the top level under messageattributes to assist with filtering there are three main sections of the message context the context section provides metadata and contextual information about the resource within a broader scope, such as its association with an event, session, or organizational entity identifiers the identifiers section contains unique identifiers and reference information for the resource, enabling it to be distinctly tracked, linked, or queried data the data section contains descriptive or operational information about the resource, such as its state, timestamps, or additional classifications localization while message structure is always in english, you can expect that message/payload values may be in a different language, such as korean for korean events, thai script for thai events etc keep in mind that not all records for a particular event might be in that language they could be mixed languages jomablue provides messages encoded as utf 8 using sqs we highly recommend ingesting the sns topic into aws sqs simple queue service will allow you to manage the flow of data from jomablue in an orderly queue for processing, meaning you can process the data at your own pace while staying within rate limits you might have on your systems (ie, rate limits on ingesting into your crm) alternatively, ensure you consider using the maxreceivespersecond attribute of sns to prevent overwhelming the destination endpoint message filtering we highly recommend using https //docs aws amazon com/sns/latest/dg/sns message filtering html by default when consuming data from jomablue, this is to ensure that any new data jomablue pushes to the topic in future releases, does not affect integrations you have in place due to unexpected payloads being received the filters can be applied to the sns message body or jomablue provides a "resource type" 'messageattribute' (a feature of aws sns) which is either 'person', 'event', 'lead' or 'session participation' for connivence this resource type is also echoed at the top of the message body if you would like to filter on messagebody additionally you use filters to reduce the messages received by scoping to only data you care about for example, only people that have checked into the event example messagebody filter { "data" { "checked in" \["true"] } } maintaining jomablue id's it is recommended to store jomablue id’s provided in the payloads to ensure future development to include more jomablue interaction data that can be retrospectively linked to an existing person or events in your systems the important identifiers are contained under the ‘identifiers’ node of the message parts of these id's can also be used to make update requests to people via the jomablue bulk import api if you don't provide your own identifiers for people these id’s are structured in the following format {instance}/{resource}/{id} examples id example for events "identifiers" { "id" "acme/event/5" }, id example for people "identifiers" { "id" "acme/event person/51486" }, organisation uid (organisation uid) the organisation uid is a unique identifier of a person, session or vendor from an external system (eg crm’s) for example, if you have a person record in your salesforce crm that has indicated they are attending a jomablue event, the jomablue organisation uid would be the salesforce lead/contact id this allows your systems to keep track of people between systems as well as perform subsequent updates to particular people organisation uid’s are expected to be globally unique and therefore a single organisation uid may denote a person that has a relationship to multiple events in jomablue making updates to a person that is attending multiple jomablue events will update the persons details (first name, last name, job title, company, mobile and email) for all events noting that categories and custom fields are event specific category name changes in jomablue people and event sns messages contain information about categories categories belong to an event and people are added to categories for that event (eg delegate, vip, speaker, exhibitor) a person sns message is not re published upon change of an event level category name if a category name is changed in settings (eg delegate to attendee ), only an event sns message is published (all people with that category are not re published) therefor, if it's important to your use case that people's categories remain up to date, we recommend building and maintaining a relationship between categories in the event payload and the categories id in the people people payload all the category id's are provided for this use case in addition, jomablue can implement event based policies (aka metadata more information below) if required to ensure category name changes are far less common metadata within the payloads you will notice a metadata node this data is produced from implementing "organisational policies" in jomablue organisational policies can enforce certain categories, with specific spelling to be required for each event created in jomablue this can drive consistency across events in your organisation it can also enforce the collection of additional data when administrators creating events in jomablue that may be used for additional business logic in your systems but is not required for the function of jomablue for example, depending on the event type, the region or the owner, you may apply differing ingest logic to the data for example, for each event created in jomablue, you may require the following additional information in additional to the fields required in jomablue region = \[americas, uk, other] cost centre = \[1200, 1500, 1201] owner = \[enter event owner name] source = jomablue (static value) when an event is created, and these (keys) are populated, it will be included in all sns messages for that event (under the metadata node) encryption no custom encryption of the payload is performed prior to sns publish standard sns features of sns topic transport and server side at rest encryption will be used jomablue can consider the use customer managed keys on a case by case basis limits a soft limit of 1 million sns requests per month is set by default for all jomablue plans this equates to approximately 1m people or events add/edits per month these soft limits can be increased, contact jomablue support if you would like to increase your limits sns topic hosting jomablue will host a single sns topic and publish all messages to this single topic sns subscriber message filtering can be applied if you want to apply logic to route messages to different queues or endpoints bursting/handling spikes jomablue batch publishes to sns, which can be up to 100 messages per second there should be appropriate handling (ie, sqs) to cater for these spikes in message these batches can be triggered by an administrator of an even from actions they do within jomablue (eg importing lists or sending email campaigns), so its common to see these spikes processing delays jomablue may delay an sns publish up to 120 seconds for internal processing of events, people or leads before publishing sessions may be delayed up to 300 seconds for processing of 'checked in data' to 'session attendance' additionally, if the feature of inferred sessions is being used, a persons session attendance is usually calculated well after they enter the session its at that point in time that the message is published to sns timestamps timestamps in the api are always provided utc with no timezone offset the event timezone can be found in the event payload if you would like to offset to be local event time all times displayed in the jomablue to event administrators are always displayed in the event local timezone duplication jomablue will publish an identical message for the same person, this happens based on actions the event administrator takes where the person record has been touched but the data altered is not included in the payload therefor it is identical to the last time you received it deduplication and matching rules should be applied to all data before ingesting into your systems you should not expect excessive duplication of messages, if for example a email campaign was sent to 100 people, you would receive 100 messages if you're seeing excessive duplication it could be due to the retry policy on the sns topic if one of your subscriptions is failing to return success for each message multi instance/region configuration if you have multiple instances of jomablue, ie to support different regions all of the instances will publish to the same sns topic and you can differentiate by the identifiers in the payload