Services

Services are the interface between botlets and the outside world. Services can connect to APIs, web services, and hosted external code (C#, JavaScript, etc.). Services are integral to actions because an action cannot be created without a service. Actions are performed on botlets and services to allow them to perform their primary tasks. Actions take entity types as inputs and outputs to ensure the semantic nature of the service.

The information that follows will guide you through how to:

  • Create, edit, and delete a service from an organization
  • Create a service with the three service creation options (i.e., API and document, Swagger Specification file, and web service)
  • Add actions to a service

Creating a Service

The steps below will guide you through how to create a service. For this example, we are choosing the service creation option “I have an API and documentation” which is described in more details in the Service Creation Options section. To follow the steps below, you must have permissions to an organization, or you must create an organization in order to create a service botlet under it. If you do not have an organization created in the Workspace and you need information on how to create one, see: Creating an Organization.

  1. In the Items Tree, click the Create new icon, and then click New item.
alternate text
  1. Click Service, and then click Create New.
alternate text
  1. Enter the Organization name.

Note: To create a service botlet, you must have permissions to an organization in the Items tree. For more details about the different types of permissions, see: Organization Permissions.

alternate text
  1. Enter the Service name.
Note: The service name is a user-friendly name that will be shown on the portal. It may contain any combination of upper and lower-case letters as well as special symbols.
  1. Enter the Service ID.
Note: The service ID is automatically generated with a service name. You may modify the service ID by typing in the text field.
  1. Click a Category from the drop-down list.
Note Pick a category that best describes your service.
  1. Click Next.
  2. Enter a brief Description of the service.
alternate text

(Optional): Click Browse to upload a PNG or JPG image for your service botlet.

Note: It is recommended that the images be in the shape of square and have minimum dimensions of 150 x 150 pixels.

  1. Click Next.
  2. Select a service creation option (e.g., I have an API and documentation).
alternate text
  1. Click Done.

The images below show an example of the newly created service botlet in the Items Tree. Click the Services drop-down to see the name of the service. Click on the name of the service. This will display the Control Panel that manages the service properties.

Example: New service listed under an organization

alternate text

Example: Below is an example of the newly created service with the Overview menu tab displaying its properties.

alternate text

Editing Service Properties

At any time, you can update the properties of a service. You can update a service’s properties by changing its:

  • Description
  • Image
  • Webservice URL (Webhook)
  • Add new actions or edit existing actions

Note: The Webservice URL is autogenerated if the service is created as an API wrapper or from a Swagger specification. Precaution: Changing the Webservice URL may cause the Swagger and API wrapper service to generate an exception.

To edit a service’s properties, refer to the steps below.

  1. In the Items Tree, click an organization and a service under it.
alternate text
  1. In the Overview menu tab, click Edit on a property that you want to change.
alternate text

Note: You can add an action to your service by clicking + New Action.
  1. Make changes to the service properties (e.g., description, webservice URL).
alternate text
  1. Click Done.
alternate text
  1. Click Save.
alternate text

Unsaved Changes

In the Control Panel, you may notice a red dot next to the Discoverability tab. This red dot indicates that the updated changes made to the service properties have not been saved.

alternate text

To avoid losing the changes made to the properties, click Cancel and stay on this page, Save Changes, or Discard Changes.

If you do not save your changes and click on another organization or leave the Workspace, the following message will warn you about navigating away with unsaved changes.

alternate text

In the steps that follow, you will be guided through how to delete a service from an organization.

Deleting a Service

  1. In the Items Tree, click the name of your organization to expand its properties.
  2. Click Services, and then select the service botlet to delete.
  3. Click Delete.
alternate text
  1. Click OK to confirm the deletion of the service or click Cancel to stop the service deletion process.
alternate text

This concludes the basic steps on how to create a service, edit service properties, and how to delete a service from an organization. The information in the following section will guide you how to create a service using the three different service creation options.

Service Creation Options

The information in this section describes the three different options that you can select when creating a new service in an organization.

These service creation options are:

  • I have an API and document
  • I have a swagger specification (Swagger JSON file)
  • I have a web service

In addition, the steps for adding an action to a service are included for two of the three service creation options. If you import a swagger specification file, you will not need to manually create any actions because they automatically get generated for you.

Create New Service - I have an API and documentation

If you intend on creating a service that wraps an existing API, select the option I have an API and documentation. Two examples of APIs that you can wrap include Flickr and Dark Sky. A wizard will then guide you through the service creation steps. After the new service has been created, you can then define its actions by adding the input and output parameters. The actions user interface makes it easy for you to map the input requests and output responses to common entities in the system.

Note: If your service does validation checks against an existing API using JSON web tokens (JWT), refer to the Service Botlet Validation with JSON Web Tokens for a sample implementation.

The steps below describe how to create a new API wrapper service.

  1. In the Items Tree, click the Create new icon, and then click New item.
  2. Click Service.
  3. Enter a Service name, Service ID, and click a Category.
  4. Click Next.
  5. Enter a Description that best describes the service.

(Optional) Click Browse to upload a PNG or JPG image for your Service image.

  1. For the Service Type, click I have an API and documentation.
alternate text
  1. Click Done.

Now that you have been guided through the steps of creating a new service type with the option “I have an API and documentation,” we are now going to cover the steps of adding an action to this service.

Adding Actions - API Wrapper

Actions are performed on botlets and services to allow them to perform their primary tasks. Actions take entity types as inputs and outputs to ensure the semantic nature of the service. Additionally, services can have more than one action.

In the Workspace, actions are created from the Actions menu tab. It is here that you can add, edit,and delete actions. If you have an action, you can use SCL commands to invoke it. For more details about SCL or to see the list of SCL commands, see: Semantic Composition Language.

Step 0 – Create an Action with a Name and Description

This step assumes that that there are no actions already created for this service type. If you have an action already added to a service, then you may omit these steps and refer to the section Adding More Actions to an existing service.

  1. In the Items Tree, click an organization and select a service botlet under it.
  2. In the Control Panel, click the Actions menu tabs.
alternate text
  1. Enter an Action name and write a Description, and then click Add.
Notes: The Action name field is a required field and is limited to 30 characters. The description field is optional. The Action ID field is auto-generated, but you can modify it.
  1. Click Save.
alternate text

Adding More Actions

If you already have an action to your service and you need to add more actions to it, click + Add a new action, and then give the new action a Name and Description. You can also click the Edit icon to edit the name and description of an existing action, or you can click the Delete icon to delete an action from a service.

alternate text

It is at this point that you can either add more actions, or you can start entering the API information.

Step 1 – Enter API Information

It is here that you can enter your HTTP configurations. You can also add headers and paste the JSON details into the Body field to test out the HTTP response.

  1. Copy your API request URL, and then paste it into the request URL field.
alternate text
  1. Click the drop-down arrow and select HTTP method (e.g., GET, POST, etc.).
Note: For those methods which have the body in the request (e.g., POST), the body input text area will get displayed when you choose this method as an example.
  1. Click + Add a new header and enter the Key and Value header properties.
Note: Click the + symbol to add more header properties to the HTTP response.
  1. Depending on which HTTP method you select, copy the JSON details into the Body text field.
  2. Click Send to test and view the HTTP response.
  3. Click Next.

Note: If the you receive an error message in the HTTP response, the Next button will be inactive. Review the details of the HTTP response to correct the cause of the error.

alternate text

Step 2 – Enter Input Parameters

The steps below will guide you through how to create input parameters, bind the mapping rules of the API parameters, and input entities. Depending on your needs, you may skip this step and enter the output parameters that are described in the next section.

  1. To add input parameters, click New input parameter.
alternate text
  1. You can choose Input or Input (required). When you choose Input (required), it means your parameter is required when calling this action in the service. Otherwise, the parameter can be optional.
  2. Enter the Parameter name for the input parameter.
  3. Enter the Entity type for the input parameter (e.g., string).
  4. Enter the Description for the input parameter.
  1. Click Add to save the input parameters.

The result of the newly created input parameter is shown in the example below.

alternate text

It is here that you can create additional input parameters. You can also make edits or delete your input parameters. It also here that you can click Edit HTTP Parameters -> to the process of binding the input mapping fields.

Binding Input Mapping Fields

In the steps that follow, you will mark all your API parameters. The user interface has features that allow you to double-click inside the URL, Headers, and Body fields to activate a pop-up window for entering a parameter name. It is these parameters that will get mapped to the input entities.

alternate text

The steps below describe how to map the URL parameters to the text of the query.

  1. Click the link Edit HTTP Parameters to bind the input mapping rules.
  1. Click the API request URL or select sections of the URL to activate the pop-up window.
alternate text

  1. Enter the Parameter Name (e.g., id) in the pop-up window.
  2. From the previous step, the selection of the URL gets mapped to an URL Parameters in the Preview pane. Refer to the image below to see this example. Repeat these same steps for the Headers and Body of the JSON.
alternate text

  1. Click Match Input Parameters →.
  2. Drag and drop the input entities parameters located in the right panel, and then move them to the URL parameters located in the left panel.
alternate text

  1. Click Next to map the URL parameter ID to the text of the query.

Step 3 – Enter Output parameters

In this step, the output parameters require that you create output parameters and map the outbound API response to the output entities.

  1. To add Output parameters, click New output parameters.
  1. Enter the Parameter name for the output parameter.
  2. Enter the Entity type for the output parameter.
  3. Enter the Description for the output parameter.
alternate text
  1. Click Add to save the Output parameters.

    alternate text
Note: Repeat steps 1 and 2 to add more output parameters.
  1. Click Match Output Parameters to bind the output mapping rules.

The steps below describe how to map the API response to the output entities.

  1. Drag the name field of the API Response, and then drop it to the name field of the Output entities.
alternate text
  1. Drag the status field of the API Response, and then drop it to the status field of the Output Entities.
  2. Click Preview.

The results of the Output entities and the Output preview are shown in the image below.

alternate text
  1. Click Done to finish configuring the API wrapper action.

Create New Service – Import Swagger API

The service type I have a swagger specification applies when you have a Swagger JSON file. A Swagger specification file defines all the input and output parameters. It automatically creates all the entity types and Actions for you.

Swagger is a standard for defining API schemas. If you already have an API, Swagger provides tools to automatically generate Swagger definitions from your codebase. For more information about these tools, visit the Swagger website. You can also write your own custom definition around an existing API using the Swagger editor.

The steps below describe how to import a Swagger JSON file.

  1. Repeat the steps in the section Create New Service - I have an API and documentation.
  2. For the Service Type, click I have a Swagger specification.
alternate text
  1. Click Done.
  2. Click Choose a file to upload the swagger.json file.
alternate text
  1. Browse to locate the swagger.json file, and then click Open.
  2. Next, click Validate.
alternate text

The Swagger JSON file will display inside the Editor View. Additionally, the File Status should display in green text the word “Successful”. If it does not, it means something was improper with the Swagger specifications file, and it needs to be corrected.

alternate text

Note: You have the option to delete the swagger.json file by clicking the Delete button. This button is located in the file status field as shown in the previous image.

There are two situations that can impact your ability upload a Swagger definition file.

  • One situation is a partial failure which means only some of the actions in the file are correct. You can still upload the Swagger definition file, but the failed Actions cannot be imported and created.
  • The other situation is a complete failure. This means that the actions are not properly defined. It also means that you can’t upload the Swagger file.

Refer to the screenshots below to see examples of these file status messages.

Partial Failure

alternate text

Complete Failure

alternate text

Note: Click Delete to remove a failed Swagger file.

  1. Click Upload.

Note: You will be required to rename the entities or overwrite them if entities in the imported swagger files have the same names with the existing ones in the current namespace.

alternate text

Entities Generated for Output

The entities required for this Service are also auto generated by the Swagger service as shown in the image below.

alternate text

Viewing Actions Output

To view the Actions created by the Swagger specifications file, click the Service name in the Items Tree, and then click Actions.

alternate text

It is also important to note that a service can have multiple actions. Refer to the above image to see the list of actions created for the service called “swagger_service”.

Re-import

If you had made any changes to the Swagger specifications file, click Re-Import to upload the latest version of it.

Adding Actions – Swagger Specification

Actions are automatically created when you import a Swagger specifications file. As shown in the image below, the input and output parameters are auto filled. There are no manual steps that you need to do with regards to creating an action with this service creation option.

alternate text

Notes: When you import a Swagger specification file, you will not be able to add additional input and output parameters unless you make the changes to the Swagger file itself and then reimport the updated version of the file. However, you can edit or delete the input and output parameters as shown in the above screenshot.

Create New Service – I have a web service

The service type I have a web service applies when you want to wrap and call your own web service. A web service provides you the input and output parameters for the actions of your service.

  1. Repeat steps 1 through 7 in the section Create New Service - I have an API and documentation.
  2. For the Service Type, click I have a web service.
alternate text
  1. Enter the Webservice URL of your hosted service.
  2. Click Done.

Note: The image below shows an example of the newly created service botlet.

alternate text

Notice that your service botlet and your web service are following a JSON schema to communicate. The request and response of your web service must follow the mst.botresponse and mst.botrequest JSON schema. For more details about the schema, refer to the tutorial Using C # Code in your Botlet Logic and the Key Points section.

Adding Actions – Web Service

Adding an action to the service type “I have a web service” is similar to adding an action to the service type using the API wrapper. Refer to the steps below on adding an action to a service using the option “I have a web service.”

Step 1 – Create an Action with a Name and Description

  1. In the Items Tree, click an organization and select a service botlet under it.
  2. In the Control Panel, click the Actions menu tabs.
  3. Enter an Action name and write a Description, and then click Add.
  4. Click Save.
alternate text

Now that the action has been created, you can proceed with entering the input and output parameters.

Step 2 – Enter Input Parameters

  1. Click Add parameters.
alternate text
  1. Click + New input parameter.
  2. Click Input or Input(required), enter a Parameter name, Entity type, and Description.
alternate text
  1. Click Add.
  2. Click Save.
alternate text

Step 3 – Enter Output Parameters

  1. Click Add parameters.
  2. Enter a Parameter name, Entity Type, and Description.
alternate text
  1. Click Add.
  2. Click Save.
alternate text

Invoking an Action with SCL Commands

It doesn’t matter how an action is created (i.e., API Wrapper Action, Swagger specification file, or a web service). If you have an action, you can use SCL commands to invoke it.

For more details about SCL, see: Semantic Composition Language.

The steps below are a shortcut to generate a set of SCL commands to call a specific action. The steps below are also valid for a botlet.

  1. Click the name of your service in the Items Tree.
  2. Under the Actions section of the Overview tab, locate the name of your action, and click Copy to code.
alternate text
  1. As described in the previous step and shown in the sample below, paste your copied action into your botlet code.
CREATE "string" STORE input_1
CALL "service_creation_test.api_wrapper_service", "getpet", query=input_1
SET output_1 = CALL_RESULT.response.pet

**Note**: You can write the code yourself, but you do not always have to. You can use the **Copy to code** feature on items found in the Store and Workspace and then reuse the code in your own flow.

Editing and Deleting an Action

  1. To edit an action, click Edit, and then modify the name or description properties.

Note: Ensure to click Save to save your changes.

alternate text
  1. To delete an action, click Delete.
  2. Click Delete to confirm deleting the action.
alternate text

For information about the supported and unsupported input entity types and the limitations of the API Wrapper, see: Limitations of API Wrapper.

Service Botlet Validation with JSON Web Tokens

The code sample below is the DoradoJWTAuthorization attribute.

[DoradoJWTAuthorization]

[HttpPost]

[Route("api/create-accessor-token")]

public async Task<IHttpActionResult> GenerateSocialAccessorToken()

{

 string body = await this.Request.Content.ReadAsStringAsync();
      RequestBody request = JsonConvert.DeserializeObject<RequestBody>(body);

      string saToken = sa.GenerateExternalToken(request.BotletId, AccountType.Dorado, request.UserId, null, null, null, null, (long)request.ValidDuration.TotalSeconds);
      return Json(saToken);
}

What Does the DoradoJWTAuthorization Attribute Do?

The DoradoJWTAuthorization attribute is derived from the System.Web.Http.AuthorizeAttribute and is meant to do authorization checks. This implementation overrides the IsAuthorized method to do the custom validation of an incoming request as shown in the example below.

protected override bool IsAuthorized(HttpActionContext actionContext)

TokenValidationParameters tokenValidationParameters = new TokenValidationParameters()

{

  ValidIssuers = this.issuers,
  IssuerSigningTokens = this.GetIssuerTokens(),
  ValidAudience = audience

};

In the previous code sample, the third party service is validating the issuer (e.g., the token that is issued by “Dorado”). The issuer tokens, which are the issuer signing tokens, are in the allowed list of certificates signed.

The third party service is doing the validation of the audience which is the current request URL (i.e., service URL).

string header = Base64UrlEncoder.Decode(actionContext.Request.Headers.Authorization.Parameter.Split('.')[0]);
JObject headerObj = JObject.Parse(header);

JToken algoToken = headerObj.SelectToken("alg");

this.telemetryClient.TrackTrace(string.Format("JWTAuth Got a request for Auth Check with Algo set to {0}", algoToken.ToString()));
if (algoToken.ToString() != "RS256")

{
 return false;
}

 handler.ValidateToken(actionContext.Request.Headers.Authorization.Parameter, tokenValidationParameters, out securityToken);

The third party service is extracting the authorization header to get the token and to validate the algorithm. It also gets the token using the System.IdentityModel.Tokens.Jwt validator.