API
- Introduction
-
This video will take a look at how to utilize the power of REST web services, APIs, OAuth and JSON in the creation of a robot. Specifically we will go through the process of automating the posting of a share to a LinkedIn account based on content extracted from another website. This process involves the following:
-
creating an app through a LinkedIn developer account
-
looking at the LinkedIn documentation reference and understanding how the share API works
-
creating a robot which extracts from News Magazine and posts to LinkedIn through a REST call to the LinkedIn share API, and finally
-
scheduling execution of that robot and adding users to it from the Management Console.
After watching, you should be able to access and call the LinkedIn API. Even if you are only interested in other APIs, this video will still serve as a fine introduction.
-
- OAuth and the LinkedIn API
-
Before we can start working on the robot in Design Studio, we need to get access to the LinkedIn API. This is only possible with a developer account, but fortunately it is quite easy to get one. Start by going to developer.linkedin.com and sign in in the upper right corner. In the popup window that opens, type your username and password and allow the LinkedIn Developer Network to access your account.
Once you have successfully logged in, click on the link to API Keys, in the dropdown in the upper right corner. This will give you a list of the applications associated with your account. This list should be empty unless you have already created some LinkedIn applications. Add a new application, and fill in the form. Apart from filling in the required fields, you should also check off any permission that your robot might need. Since we need to post to the users account, we will check the rw_nus permission. When you are done, click Add Application at the bottom.
LinkedIn now gives us back a page showing the OAuth credentials needed to access their API. We leave the page open so we can have access to these credentials when we need them.
In a new tab, we open developer.linkedin.com again. This time we go to the Documentation dropdown box and click REST APIs. We need to find the part of the API which lets us share something to an account on the user's behalf. We choose Share and Social Streaming in the Documentation Menu on the right, then choose Share API from the submenu. Now we are on the page for documentation of the Share API.
Scrolling down a bit, we see what a sample payload for the Share API looks like. The example is in XML, but we will be posting using a JSON payload instead. The translation from XML to JSON is pretty straight forward, as we will see. Above the example is a table which shows all the fields available to the Share API. It is possible to set a comment, a title, a url, an image and a description.
- JSON and REST call
-
Now that we have OAuth credentials for the LinkedIn API, it is time to start building our robot. We create a new robot called LinkedInShare. Then, we add a variable of the type OAuthCredentials, name it credentials and mark it as an input variable. It is important to make it an input variable so we will later be able to schedule the robot in the Management Console. Then, we give it the following default values which will let us call the LinkedIn API: We write LinkedIn in the serviceProvider attribute, copy the API Key to the consumerKey attribute, Secret Key to consumerSecret, OAuth User Token to accessToken, and OAuth User Secret to accessTokenSecret. As you might notice, there is no strict naming convention these four tokens. Hence the names differ between LinkedIn and Design Studio. Then, we click OK.
We now need to create a new type: One in which we can extract the front page article from a website called News Magazine. We create a new type and call it Share.type. For this type, we should name each attribute according to the input fields specified by the Share API. Going back to the documentation of the Share API, we see that the fields we are worried about are called title, submitted-url, submitted-image-url, and description.
In Design Studio, we add the four corresponding attributes to our type: title as a short text, … submitted_url as a short text, … submitted_image_url as a short text, … and finally description as a long text. Note that we use an underscore instead of a hyphen since hyphens can't be used in valid attribute names. Luckily, LinkedIn does not distinguish between the two. That's it! We save the Share type.
Going back to the robot, it is time to start the fun part, which is building the robot. We start by adding two variables, one of the type we just created, and one of the simple type JSON. The JSON type variable should be able to contain the JSON payload which will be used in the API call.
Starting with the jsonPayload variable, we add it to the robot and edit the default value of the variable to reflect a payload template. I have made the template ahead of time. You can copy the template for the payload from the text associated with this video:
{ "comment" : "News Magazine article of the day", "visibility" : { "code" : "anyone" } }The payload template contains a default value for the comment field. This could be created dynamically if you wanted to. It also contains a value for the visibility of the share with the code "anyone". This means that anyone, not just connections, will be able to see what we post to the user's profile. Save the variable.
We then add a variable of the type Share.
Now all we need to do, is to load News Magazine, extract from the front page story, add that content to the payload and call the LinkedIn API with a Call REST Web Service step.
News Magazine is most easily loaded by inserting a snippet step and choosing the snippet LoadNewsMagazine for it. This is one of the snippets that comes with the default project when you install Kofax Kapow.
Executing the snippet step, we are able to see the front page of News Magazine. From the featured article on the front page, we extract the title, url, image url and description into the share variable.
To build the payload, we now have to open the jsonPayload variable. This can be done by right clicking it and choosing insert step>>open variable. The value is now showed in the JSON view. Click the plus icon in the toolbar above the JSON view to expand all lists and objects and view the entire content of the variable.
Inserting the content from News Magazine into the payload is very easy. Simply right click the comment property and choose Modify>>Insert>>After. In the Name field we write "content". For the Value field, choose Generate From Variable from the value selector on the right. Now we can choose our share variable in the field called Variable to Format. Click OK to finish.
The JSON payload should now have been correctly formatted for our REST call. We insert a new action step as the last step before the end step and choose for it the Call REST Web Service action. All we need to do is configure this step and the robot will then be ready to be deployed. Here is how to do it.
From the Share API documentation, we copy the URL and paste it into the URL field.
The request method is POST, which is also stated in the API documentation.
From the dropdown just below the request method, we choose that we want to specify the raw body of the request rather than individual parameters.
For the request body, we select variable from the value selector and choose our JSON payload variable.
Correspondingly, we choose application/json as the content type.
Going down to the bottom of the Step Action, we need to specify credentials for the REST call. We have already prepared these. Choose OAuth as authentication type, and select the OAuthCredentials variable.
That was the final step in finishing the robot and it should now be ready to for deployment. First however, we will run it in debug mode to check that it works as expected.
We switch to debug mode and run the robot. If it is successful, there should not be any error messages.
Next, we log into LinkedIn to check that the share has been posted successfully. It may take a couple of minutes before the share appears.
Once we have ensured that everything looks good, it is time to upload the robot to the Management Console in order to schedule it and to add multiple users.
- Schedule the robot
-
Going back to Design Mode from Debug Mode, we upload the robot to the Management Console and click the link that appears to the Management Console. Since our robot uses the OAuthCredentials type as input variable, setting up the scheduling is a bit different than you might be used to. Here is how to do it.
In the repository, we go to the OAuth section. Here we add a new application, namely our LinkedIn application. We name it "LinkedInShare", choose LinkedIn as our service provider, copy our application API Key to the consumerKey field, and our Secret Key to the consumerSecret field. We leave the Scope and Callback fields as they are and click Save.
Then, we add a user. We call the user "user1", click Next and click the link to authorize the user. In a new window, our application will now request permission to access whatever LinkedIn account we are logged in to. Allow access and the Callback page will confirm that permission has been granted. Close the window or tab to go back to the Management Console.
Now we click Next, and then Finish, to finally add the user to our application. Multiple users can be added in this way, but let's keep it simple and stick to just one user at the moment.
Clicking on the Schedules tab, we are now going to create a schedule for the robot. We configure the schedule, give it a name, set it to run daily, and add a job to the job list. We choose to add a single robot and select the LinkedInShare robot. In the last step of the dialog, we choose the user we created for OAuth and click Finish and save the schedule.
The task has now been completed. We have set up an automated process which uses the LinkedIn API to post daily updates to a LinkedIn profile.
You should now be able to use the LinkedIn API. If you want to learn more about the using OAuth to access sites like Salesforce, Facebook, and Twitter, please consult Kapow documentation, where you will find a section called OAuth.