Add recipients and articles use SOAP API request

Transcript

Hello. In this video, we are going to use the Adobe Campaign SOAP APIs to create a new recipient. Additionally, we’ll create a custom article data schema in Campaign and submit an article using the API. To start, let’s create a new recipient in our Campaign Instance, using a post request. Navigate to the postman collection XTK Session we created in the Getting Started video. With this collection, select the Write post request, followed by selecting the Body tab. In order to add a new recipient using the API, we need to provide XML information relating to the recipient we wish to add. In order to get this information, we need to look at the recipient schema in Campaign.

Let’s swap back over to Campaign. And as you can see, we currently do not have a Steve Jones recipient. Select the Explorer option, followed by navigating the instance tree, select Administration, Configuration, and within Configuration, select Data schemas. In the name or label search field, type recipient, followed by selecting enter. Some source schemas populate in the results, including the recipients nms schema. Selecting this schema allows us to view all the attributes that we can include, including first names, titles, emails, and more.

Going back to our Postman Write request, we’re now armed with a number of available attributes and can create a recipient. Looking at my screen, you can see that I added a recipient object. To start, we want to provide the operation insert or update, which allows us to create a new recipient or potentially update an existing one. Next, we want to define the key as email, followed by defining the schema we are writing to. This is the nms recipient schema. For the purposes of this demo, I’m only going to add a couple attributes, first name, last name, and email. We also need to make sure to add our session token value. Mine is saved as a variable session token that I will provide in the string section.

Once complete, select the Send option in the top right, and you should receive a successful response with a 200 status. This indicates that the recipient has been added. To confirm, we can navigate back to our Campaign Instance and from the home tab, look at our recipient list.

As you can see, the Steve Jones recipient is now available. Upon selecting the recipient, we can see that only the first name, last name, and email are filled in. Going back to our API call, let’s quickly update our recipient with a different last name.

Upon submitting the updated attribute, we can go back to Campaign to see the last name has changed. Using this method, we can integrate our SOAP API with the backend of a website to consistently create and update recipients within Campaign. Although this method is useful, our use case requires that we have users subscribe to an email list for specific news articles. This means we also need to upload news articles and tag them according to a user subscription tag they are assigned to upon opting in. A quick search of our data schema for articles yields no results. So how do we add them using the same method? Well, to do this, we are going to need to define the schema ourselves in Campaign. Let’s start by adding a new schema. Select the Add icon, followed by making sure the first radio button for creating a new table in the data template is selected. Once complete, select Next to continue. We need to provide a namespace value, a label, and a name. Because this is a custom schema, let’s follow Campaign namespace conventions, and call this namespace cus for custom. The name and label can be the same thing. I’ll call mine Articles. Once complete, select Save, followed by searching for the name of your new schema to make sure it appears in the list. Next, we need to modify the boilerplate XML for the schema. Within the Course Assets zip folder was a text file called Article Schema. Copy and paste the Article Schema file, replacing the current XML. After copy and pasting the schema, we are almost ready to proceed. However, we need to add the tag attribute and parameter. To add an attribute, Campaign allows us to insert an empty piece of XML based on the type of attribute. A tag is used to classify our article. So it would fall under a string attribute. Let’s select Insert, followed by hovering over Attribute and select String.

An empty attribute is added to our data schema. Let’s update the label to be equal to tag, set the name to tag, and we can leave the type as string.

Now that we have everything that we need, let’s take a look at what the schema is doing. In the element, we have autopk set to true. This means that our schema is automatically creating a primary key so that we don’t need to generate a unique key each time we insert a new article. We have the attributes of our article and below the attributes, we also have a custom method being implemented. This method references a library, which is in the form of some custom JavaScript code. In the method, we have parameters and these parameters are the same as our attributes. However, the difference here is we are providing inbound parameters. This means that our four attributes can be submitted to the database. The fifth parameter is optional and best practice. It is an outbound parameter. This is used to receive a detailed response which can assist with debugging errors. Now that our schema is complete and we know how it functions, we need to create the custom JavaScript code file that it is referencing and update our database structure.

To update the database structure, navigate to Tool, hover over Advanced, and select Update Database Structure. The database update wizard appears. If we sort by Synchronize, we can see that the wizard found our recently created custom schema and recognizes that although the schema exists, the table in the database needs to be added still. Select Next, followed by selecting Next once again, and select Start to update the database.

Next, we need to add the JavaScript code we referenced in our schema. Start by navigating to JavaScript Codes from within the Configuration dropdown and create a new code file. The name needs to follow specific conventions and match the name we gave in the data schema, cus:articles.js. Next, within our Course Assets folder, open the Custom Article JavaScript file and copy and paste the following function. This function works by looking for a name, description, tag, and date parameter. The name of the function also follows a naming convention. It needs to be our namespace, underscore our data schema name, underscore insert.

This is how Campaign knows that the function belongs to our Articles schema.

The parameter we pass this function are all defined in our schema. If we had additional parameters in our JavaScript, but they were not defined in the schema as an inbound parameter, we would receive an error stating, not enough parameters.

We, then, save the parameter to a variable called Article, which is equal to a piece of XML. This is where we insert the values. Once this is finished, we use xtek.session.write, and it passes our article XML variable. You may recognize this because we already used it to write, to create and update, a recipient.

If the method is successful, we return success. Otherwise, we use a catch to catch any errors and return the error message.

Now that we have created our schema, updated the Campaign database, and added the custom JavaScript code, we are ready to make an API call and submit an article. To start, we need to grab the schema WSDL for our new schema the same way we did when setting up the XTK session collection in the Getting Started video.

After changing the schema value in the URL to sus:article, copy and paste the XML to a text file.

Going back to Postman, we can import this XML file and upload it.

As you can see, the method we defined and attributes are all available. All we have to do is replace the string values, update our variables, and send the request. I’m going to create an article called Demo Article Name, give it a description, a published date using the following format, and most importantly, a tag.

The tag represents the service we’ll create that a user expresses interest in subscribing to. I’ll call the tag hockey.

Once you have all your information, send the request and you should receive a 200 response, indicating an article was uploaded to our database.

Navigating back to Campaign, we can find our article schema and at the bottom select the Data tab. An article with a random identifier appears. Right-click the article, select Configure List, and add the attributes article name, date, description, and tag. Once we select Ok, our article and its details are displayed, matching the same details we just submitted through the API.

You should now know how to use the Campaign SOAP API to upload recipients and have the necessary knowledge and tools to create a custom schema for uploading inbound attributes. Thanks for watching. -