Getting Started with the Joyous ServiceNow App

Before you start

To use the Joyous app, you need a subscription to Joyous – you can view pricing or start a free trial here.

Initial Setup

These setup steps will need someone with ServiceNow admin privileges and someone with Joyous admin privileges.

1. Setup API Key:
   1. In Joyous: Setup and copy a Joyous API Key to be used by the ServiceNow integration in Settings > Integrations
   2. In ServiceNow: Navigate to Connections & Credentials > Credentials then click New and select API Key Credential from the list.
   3. Name your key "Joyous API Key", or a name that matches your standard naming conventions. Paste the Joyous API Key you created in step 1 into the API key field. 
   4. Click the lock beside Credential Alias and then find record and add x_joyou_joyous.Joyous_API_Key_Alias – this step is important because it links your API Key credential to the app.
2. Add Joyous Org ID:
   
   1. In Joyous: Open any triggered campaign and view settings, copy the 
      orgId value from the snippet provided.
   2. In ServiceNow: Navigate to All > Joyous > Configuration and Insert the orgId copied above into the x_joyou_joyous.org_id field and then copy the location from Joyous into the x_joyou_joyous.region field.
3. Assign Joyous app permissions
   In ServiceNow, assign x_joyous_admin and x_joyous_user to the appropriate groups or users.
   
   1. x_joyous_admin has full access to all modules within the Joyous menu
   2. x_joyous_user cannot access the configuration module

Now your Joyous app is setup, you can use the Send Joyous Campaign spoke in flow designer.

Using the Joyous Spoke in Flow Designer

1. In Joyous: Navigate to the triggered campaign you wish to send, copy the recurringCampaignGroupId value.
2. In ServiceNow: Create your workflow and add a trigger. 
3. Add an action – find the Joyous app, then select Send Joyous campaign.
4. Paste the Recurring Campaign Group ID copied above
5. Use the data pills from the trigger object or any other connected source to pull in contact details:
   1. Either email or Mobile is required – you can connect one or both, but only one method will be used for sending according to the below:
      1. If both are provided, the contact method specified in Preferred Contact Method will be used.
      2. If details are missing for the preferred contact method, then the alternative contact method will be used.
      3. If you do not wish for an alternative contact method to be used when the preferred method is not available, then do not connect the alternative method to a data pill
6. Save and test your flow:
   1. You can pass the flow any valid email address, or mobile number it does not need to exist within Joyous.
7. Adding First Name/Last Name to your send:
   1. First Name and Last Name are not required, if not sent, the recipient will be addressed as "Participant"
   2. You may send First Name only, but not Last Name only (last name will not be sent if First Name is not set)
8. Adding custom attributes to your send: Custom attributes allow you to filter conversations in Joyous and view insights for different cohorts.
   1. Custom attributes must be configured in the people data settings within Joyous – if an attribute is not configured, it will still be passed, but will not show in the feed or insights until configured.
      

Note: You must have SMS sending enabled on your Joyous account in order to send via SMS. SMS is not available on Free Trial, Basic or Plus Plans.