MicroStrategy ONE

Builder Page of the Task Administrator Application

When you click the Builder tab on the Task Administrator application, the Builder page is displayed. This page can be used to construct and test URLs that invoke any of the public tasks that are currently registered with the Task Processor.

Constructing a URL that executes a Task

When the Builder page is opened, a generic, incomplete URL is displayed in the pane at the bottom of the page. To construct a complete URL, you do the following:

  1. From the Task ID combo box, select a task.

    The parameters available for that task are now displayed on the Builder page.  

  2. From the Task Envelope combo box, select the envelope in which the content of the task execution will be passed.

    When a task is invoked, the caller must specify an "envelope". This is a predefined "form" that defines how the contents generated by the task are packaged up and returned to the caller. Most envelopes imply a specific content type. For example, the "juil_iframe" envelope conveys that the caller is coming from a JavaScript User Interface Library (JUIL) context. When you use a "juil_iframe" envelope, the content type is implicitly "JSON". When you use an "xml" envelope, it is clear that the content type is "XML". Envelope choices include:

    • juil_iframe
       The "juil_iframe" envelope conveys that the caller is coming from a JavaScript User Interface Library (JUIL) context. The default content type is implicitly "JSON".

    • juil_xhr
      The "juil_xhr" envelope conveys that the caller is coming from a JavaScript User Interface Library (JUIL) context. The default content type is implicitly "JSON".  

    • xhr
      When you use an "xhr" envelope, there is no way to infer a default content type. You must specify the desired content type ("JSON" or "XML").

      XMLHttpRequest (XHR) is a content-agnostic communication protocol. Any type of content can be requested and downloaded. XHR is a DOM API that can be used inside a web browser scripting language, such as Javascript, to send an HTTP request directly to a web server and load the server response data directly back into the scripting language. Once the data is within the scripting language, it is available as both an XML document, if the response was valid XML markup, and as plain text. The XML data can easily be used to manipulate the currently active document in the browser without the need for the client to load a new web page document. Plain text data can be evaluated within the scripting language to manipulate the document as well. In the example of Javascript, the plain text may be formatted as JSON by the web server and evaluated within Javascript to create an object of data for use on the current DOM.

    • xml
      When you use an "xml'"envelope, the default content type is "XML".

      You should always include thetaskEnvparameter when you make a task call to explicitly specify how the contents generated by the task should be packaged. The Task Administrator application enforces this practice by providing a combo box for choosing the task envelope.

  3. From the Task Content Type combo box, select the format in which the content of the task execution will be generated. The default content types associated with each envelope are defined in the taskProcessorControllerConfig.xml file.

    Tasks generate some type of content. For some tasks, the type of content they generate is fixed. For most tasks, however, the caller has some control over the type of content returned. For example, you can use the folderBrowse task to return either XML content or JSON content. Content type choices include: 

    • ---
      Make this selection  when you do not want to specify a content type. For example, if you are using an envelope that specifies a default content type, you do not need to explicitly set one. 

    • ml
      The task returns XML. 

    • json (default)
      The task returns JSON.

      JSON (JavaScript Object Notation) is a lightweight computer data interchange format. It is a text-based, human-readable format for representing simple data structures and associative arrays (called objects). The JSON format is often used for transmitting structured data over a network connection in a process called serialization. Its main application is in Ajax web application programming, where it serves as an alternative to the use of the XML format.

    • jsond
       The task returns JSON, with some extra diagnostic information. 

  4. For each parameter that you want to include in the URL, check the Include? check box. Enter a value for the parameter or leave it blank.

    You must check the Include? check box to add a parameter to the URL. Even if a value is entered into the Value text field, it is not submitted unless the Include? check box is set.

    All required parameters must be included (that is, the Include? check box must be checked), even if the values are blank.

  5. Click the Update URL button.

    he parameters that you checked and the associated values that you entered for them are used to update the generic URL into a complete URL to invoke the task.

Testing a URL that executes a Task

To test how the newly generated URL works, click the Invoke URL button at the bottom left of the page. The results of the task execution are displayed in a pane directly below the button. You can continue to edit the values of the parameters until you are satisfied with the result. However, each time that you change a value, you must update the Task URL by clicking the Update URL button and retest it by clicking the Invoke URL button. You can also copy and paste this URL into a web browser to see it run.

If you edit a parameter and simply click the Invoke URL button without first clicking the Update URL button, the application will not use the value you entered, but instead it will use the previously entered one. The Invoke URL button simply submits the generated URL currently displayed in the lower pane.

When a task, such as login, generates an XML response that includes the “session state”, this value can be copied into the Clipboard and used for subsequent task invocations.

In the sample screenshot shown below, the browseElements task is selected in the Task ID combo box and all of its parameters are listed below. You can see that this task has fifteen possible parameters, and only one of them is required. You can provide a value for a parameter and specify whether or not it should be included.