Building Web Services with RapidConnect Part 1: The Basics

     

One of the great features of RapidConnect is the flexibility to execute action sets.  There are three methods for running your action sets:

  • Manually
  • Scheduled
  • Web Services 

Today, we are focusing on the Web Services approach. However, let’s briefly discuss the other two methods: manual and scheduling.

The manual method for running an action set may seem obvious.  While building your action set, the manual method is a great way to test functionality.  In addition, manually running action sets can also be very useful when performing “one-off” tasks that don’t need to be executed on a scheduled basis.

Most customers schedule their action sets.  This can happen as often as every minute of every day to as little as once per year.

Let’s talk about the web services approach.

If you have access to a RapidConnect session right now, create a simple action set by using the  “log” action to display “Hello, World”.  Now run that action set.  Copy that URL in the run window, and paste it into a brand new browser session.  Does it run?  It should.  That is a RESTful (aka web services) execution of an action set.

 Technical_Blog_1_Image_1.png

What RESTful action set execution means is
you can execute an action set from any system or device that is capable of calling a URL (aka calling a RESTful web service API).  I’ll continue to demonstrate this amazing benefit using a browser as my client, but we certainly aren’t limited to that.

However, there is more work to do here.  Let’s break up the URL into its parts.

Here is an example URL captured from our run window:Technical_Blog_1_Image_2.png

https://my.test.local/dss/ws/dss/ :  This is the base URL for all web service calls to your RapidConnect instance.  The “dss” term is the legacy name of RapidConnect.

/run : The “run” parameter tells RapidConnect to simply run the action and display the trace messages.  You could also use “runForValue” if the action set has a return action or use “runAsync” if you want to simply execute the action without waiting for any feedback from RapidConnect.

?authToken : This is the authentication/authorization token that was generated when we established our session with RapidConnect through the user interface.

&message : This is our request payload, which includes the action set to be executed and any input properties we want to pass (if applicable).  When you run an action set manually, this will always be a urlencoded xml payload.  If you use a urldecoder, you’ll see the clean xml, such as this (which is the urldecoded xml from the example above):

Technical_Blog_1_Image_3.png

The authToken parameter is only going to work when running an action set manually in the RapidConnect interface.  You wouldn’t have a token if you didn’t run it manually (and that token is only good for a short duration).  So, when making a web service call to RapidConnect, you need to replace the authToken parameter with an authUser and authPassword token. These are (urlencoded) username and password that have enough rights to run the action set being called.

We have also made improvements along the way, so that your web service call doesn’t have to include the url encoded xml payload that you see when running action sets manually.  Here is the latest supported syntax for building your request:

https://my.test.local/dss/ws/dss/ :  The base URL does not change.

/run : The “run”, “runForValue" or “runAsync” path also remains unchanged.

/[project.]actionset : This path is new!  Here, you give the action set name that you are calling (including the project if not in the main project).

?authUser : The username with action set execution permissions (urlencoded as necessary).

&authPassword : The password of the user (urlencoded as necessary).

&arg-[input_property]=’value’ : If your action set has input properties, you can add them here and add as many as required.  For example, if you have an input property called “log_only”, then your parameter would be something like “...&arg-log_only=’true’”.

With that, here are a few examples of what some web service executions end up looking like:

No input properties, no return values
Technical_Blog_1_Image_4.png

With input properties, no return values 
Technical_Blog_1_Image_5.png

With input properties and return values
Technical_Blog_1_Image_6.png




Request a Live Demo

Comments

Subscribe Here!