Integrating ASD forms with Google Translate using External Value Definitions

Recently vRA 6.2 was released and together with that ASD got a new feature that allows you to bind the constraints and permissible values of fields in ASD forms to External Value Definitions, that are backed up by vRO scripting actions. This means that you can enhance the request form or resource details form by making fields more dynamic that calculate their state and values from scripting actions. By having all the various vRO’s plugins and especially the REST plugin, you can connect to any* 3rd party system and retrieve values from it.

To give you an example I will use this very nice post, by Cesare Rossi, that came just in time for me to write mine. You can see the post here http://www.ilvirtualista.it/2014/12/18/vrops-if-this-than-that/. His example is sweet, uses the “Send notification” workflow to create a catalog item to send emails and the IFTTT service to send text messages. I will not change anything on the functional level, but rather enhance the presentation of his request form, without touching the workflow nor it’s presentation.

Now, you may have noticed that his post is entirely in Italian. I love the Italian language, but since I know very little, I will build a catalog item that allows entering message contents in English and by using a vRO scripting action that uses Google Translate, the form will instantly translate my message in Italian. We will do it following the steps:

1. Create a scripting action in vRO that talks with the Google Translate service.

To use the Translate API, you will need to setup your Google account with it and choose how your application will authenticate to it. For our example we will use Public API access key, so in the scripting bellow replace the key with your own. The Translate API is RESTful so it is obvious to use vRO’s REST plugin. The following script is responsible for:
1. Create a REST host
2. Make a GET request to https://www.googleapis.com/language/translate/v2?key=INSERT-YOUR-KEY&source=en&target=it&q=Hello%20world
3. Remove the host to clean up after ourselves
4. Return the result.

if (!sourceString) {
    return "";
}

host = new RESTHost("Google Translate");
host.url = "https://www.googleapis.com/";

host.connectionTimeout = 30;
host.operationTimeout = 60;

var auth = "NONE";
var authParams = [];
host.authentication = RESTAuthenticationManager.createAuthentication(auth, authParams);

host = RESTHostManager.addHost(host);

try {

    var key = "INSERT-YOUR-KEY";
    // Target language set to Italian
    var target = "it";
    // The source is passed as URL query parameter
    var encodedSourceString = encodeURIComponent(sourceString); 

    var request = host.createRequest("GET", "language/translate/v2?key=" + key + "&source=en&target=" + target + "&q=" + encodedSourceString);
    request.contentType = "application/json";
    request.setHeader("Accept", "application/json");

    var response = request.execute();

    System.log("response " + response.contentAsString);

    var result = JSON.parse(response.contentAsString);

    RESTHostManager.removeHost(host.id);
    return result.data.translations[0].translatedText;
} catch (e) {
    System.log("error " + e);
    RESTHostManager.removeHost(host.id);
}

The only unclear thing here the sourceString – it is actually a parameter of the scripting action that our form will provide value form. The scripting actions should also return a string.

Testing the scripting action
To test this, we will use the functionality that was introduced in vRO 5.5.2 to execute scripting actions through vRO’s REST API. In this example, the FQN of this scripting action is com.tgeorgiev.blog.demo/translate, this is why we make a POST to /vco/api/actions/com.tgeorgiev.blog.demo/translate/executions/ and pass the parameter sourceString with value “Hello world”.
Request:

POST https://localhost:8281/vco/api/actions/com.tgeorgiev.blog.demo/translate/executions/
Accept: application/json
Content-Type: application/json
{
  "parameters": [
    {
      "name": "sourceString",
      "type": "string",
      "value": {
        "string": {
          "value": "Hello world!"
        }
      }
    }
  ]
}

Response:

200 OK
{
  "value": {
    "string": {
      "value": "Ciao mondo!"
    }
  },
  "type": "string"
}

2. Create an ASD blueprint

The workflow that Cesare used, that we will also use, is the “Send notification” workflow.

Screen Shot 2014-12-22 at 2.44.17 AM

3. Modify the default request form

We will provide fixed values to most of the configuration fields like server address, port, username, password hide them and leave only the “Sender’s name” and “Email content”.
Screen Shot 2014-12-22 at 2.52.18 AM

At this moment if we create the catalog item, we will have pretty much the same request form as the one in Cesare’s example. Now we will start to build up on top of that.
We will add a new TextArea field called “content-en”.
Screen Shot 2014-12-22 at 2.53.23 AM

Screen Shot 2014-12-22 at 2.53.53 AM

This field will be used as the source where the user will enter text. For the actual “content” field, that the workflow is aware of, we will make some modifications.

We will rename it, to be more intuitive to the user.

Screen Shot 2014-12-22 at 2.54.41 AM

4. Bind to external value

We will bind the “content” field to the vRO scripting action and pass the value of the “content-en” field. Now we will add a Fixed value constraint, based on external value.
Screen Shot 2014-12-22 at 2.54.55 AM

When we click on “Add” we can now browse vROs actions. We select the “translate” action
Screen Shot 2014-12-22 at 3.02.06 AM

And now we can bind the one input parameter to existing fields of the form.
Screen Shot 2014-12-22 at 3.02.23 AM

Screen Shot 2014-12-22 at 3.02.39 AM

At this moment the designed form will look like this
Screen Shot 2014-12-22 at 3.02.50 AM

5. Request the catalog item

Now when we publish the blueprint as catalog item, entitle it and request it from the catalog we will see the form that we designed. Only the “Sender’s name” and “Content” are editable, the real “content” i.e. “Content preview” is read only, because we bound it’s value.

Screen Shot 2014-12-22 at 3.13.59 AM
So now when we type something into the “Content” and lose focus of this input, the form update will be triggered causing the vRO scripting action to be executed with the provided value, which on its turn will call Gooogle Translate API, translate the string and return the result. When this is done, the form field will be updated.
Screen Shot 2014-12-22 at 3.14.03 AM

Now when we submit this request, and open the workflow run, we will see as part of the workflow execution attributes those values
Screen Shot 2014-12-22 at 3.16.21 AM

Since the workflow only knows about the “content” parameter and nothing about the “content-en”, the message that it will send will be based on the value of “content”, and the receiver will get the Italian message.

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s