Test of small project of a Marketing Cloud Custom Activity.
This nodejs app is a Journey Builder Application Extension containing two custom activities. Create Case creates an email case using Desk.com’s API in response to a JB interaction trigger being fired. Update Case is to be placed after Create Case within an interaction and will update the subject and priority of the newly created case.
Abbreviated Instructions(for those who have done this sorta thing before)
What the Create Case custom activity demonstrates
What the Update Case custom activity demonstrates
NOTE: You won’t be able to run this locally. It is intended to be ran on a publicly available web server/cloud only.
NOTE: This app and the associated code is NOT intended to be production quality. Its pure purpose is to demonstrate the full flow of custom activities in Journey Builder
Your interaction contains a trigger (ie. foo equals 123) and subsequent activities (ie. ‘send this email’). Something happens in the real world (ie. oil change is due) to fire an event. If your trigger condition resolves to true (foo === 123), your interaction will begin. Data in the payload will be used to update SFMC, then your custom activities’ execute function (see /routes/activityCreate.js) will be called. The public folder pertains to configuration of the custom activity. This is what users of Journey Builder see when they drag your activity onto the canvas and click Configure.
It’s very important to have your data setup correctly in your Marketing Cloud account. The Journey Builder for Apps ebook describes a scenario that can be used to test this custom activity. Instructions for setting up that data can be found in the links below. The gist is that you’ll need subscribers linked to a Data Extension, which in turn will be linked to an Attribute Group in Contact Builder. Notice that config.json contains:
- "inArguments":[
- { "firstName":"{{Contact.Attribute.__your-de-name__.FirstName}}"},
- { "lastName":"{{Contact.Attribute.__your-de-name__.LastName}}"},
- { "emailAddress": "{{Contact.Default.Email}}"}
- ],
When your interaction trigger is fired, the payload you send will be for either an existing contact or a new contact. If for a new contact, also pass in First and Last name so your contact can be updated with those values before your activities’ ‘execute’ function is called. (Make sure your contact model has enabled “Use as root”, otherwise your trigger will fail.) These inArguments are data that will be passed to your custom activity. In the documentation for data binding, attribute sets are synonymous with data extensions. ‘your-de-name‘ is the name of your data extension.
clone this repository locally
git clone git@github.com:sfmc-developer-advocates/custom-activity-deskapi-node
Login to App Center. ‘Create Account’ as a developer if you haven’t already.
Select “Create New App”
Select “Application Extension” as the template type and use the following properties:
Integrate your app with an account which will use this activity.
Data Access: No (SSO Only)
Make sure everything is correct. Take note of the appID, app signature, clientID, and client secret. These will be pasted into the code.
Open /app.js
Copy the values from the App Center Summary Screen into this section of code in app.js
- var APIKeys = {
- appId : '__insert_your_app_id__',
- clientId : '__insert_your_app_client_id__',
- clientSecret : '__insert_your_app_client_secret__',
- appSignature : '__insert_your_app_signature__',
- authUrl : 'https://auth.exacttargetapis.com/v1/requestToken?legacy=1'
- };
At this point we’re going to need the endpoint for our app and subsequently each app extension
If you’re using Heroku, create a new app and copy the endpoint into App Center for this activity.
Open /public/ixn/activities/create-case/config.json and /public/ixn/activities/update-case/config.json
Replace ‘activity-key‘ with the “Key” value of your App Extension Custom Activity (ie. johndoe-jb-example-activity-desk-create-case).
Replace ‘insert_your_custom_activity_endpoint‘ with your web server’s endpoint throughout the file.
Replace ‘your-de-name‘ with the name of the data extension you want to use for this interaction.
In update-case config, replace ‘your-activity-customer-key‘ with the interaction-unique ‘key’ value (ie. REST-1) for create-case activity.
You can get it by querying for details about your interaction:
You can find your interaction's guid in the Network Tab (chrome) when you view interactions in Journey Builder. (https://jbinteractions.exacttargetapps.com/fuelapi/interaction/v1/interactions/) #### Updating the code to reflect our new Desk.com trial account 1. Open /routes/activityUtils.js 2. Replace '__subdomain__', '__username__', and '__password__' with your desk.com subdomain, username and password values. * make sure the desk.com user has either admin or API rights. #### Deploy application to host * Run 'node app' to make sure there are no issues with the app. * Now that you have updated your configuration to point to the appropriate SFMC resources, push your changes to your web server. * Remember to edit your App Center instance to include the "Endpoint URL," if you did not do that earlier. #### Testing our activity loads in the Marketing Cloud 1. Log into the [Marketing Cloud](https://mc.exacttarget.com/cloud) 2. Navigate to Journey Builder and either start a new interaction or open an existing one. 3. You should see the custom activity "Desk.com Create Case" in the left pane under "CUSTOM" #### Creating our Custom Interaction 1. Drag the "Desk.com Create Case" activity from the list onto the Interaction Canvas at Minute 0. * First change the duration of the Canvas to 'minutes'. 2. Hover and click the "Configure" button 3. The custom activity dialog should appear (this is loading from your app) 4. Select a priority other than the default. 5. Click Next. 6. Review your changes and click Done. 7. The Activity is configured. * If you hover again and click the edit icon, you should see the activities 'payload' in the Console tab of Developer Tools. The payload should include the 'priority' change you just made. 8. Add the "Update Case" activity to minute 1 of the interaction, then Configure, and Done. 9. Under the interaction name, set the interaction to "Multiple Entries" so your contact can go through it multiple times. 10. Save and activate your interaction. #### Testing our Custom Interaction This is how the trigger is fired from a REST client like Postman:
headers:Authorization: BearerContent-Type: application/json GET https://jbinteractions.exacttargetapps.com/fuelapi/interaction/v1/interactions/ ?extras=all&versionNumber=9
- POST https://www.exacttargetapis.com/interaction-experimental/v1/events
- Authorization: Bearer
Content-Type: application/json JSON Payload: { "ContactKey":"name@email.com", "EventDefinitionKey":" ", "Data": { "EmailAddress":"name@email.com", "DE_Fieldname": } }
For new contacts, make sure you also pass in First and Last name in “Data” (and those fields exist in your DE).
Make sure the email you use for ContactKey is in your All Subscribers list, or your Contact Model/DE link is set to “Use as root”.
After a minute or two, navigate to Admin / Contacts in Journey Builder. You should see some statuses for your interaction. If your desk.com case is not created within a few minutes, check to see if an error was thrown:
Please see the “LICENSE” file in the root of this repository for information related to licensing of this repository.