Building a custom skill to get employee data from external API

In Orchestrate, you can build custom skills by discovering them from resources of an in-product app or by importing them from OpenAPI files.
In this tutorial, learn how to build a sample custom skill from an external API by importing its OpenAPI Specification (OAS) to Orchestrate. This custom skill returns the first and last name, job role, and email for sample employees.

In addition, you also learn how to connect to the app, add its skills to the personal skill set, and use them.

Important: This tutorial provides a sample API that returns a list of employees in a table. The names, job roles, and emails that this API returns are for demonstration purposes only.

Before you begin

You must be an admin or builder in your Orchestrate tenant.

Create the OpenAPI file

The first step is to create the OpenAPI file. The basic OpenAPI to import to Orchestrate is composed by the openapi, info, servers, paths, and components sections. You can use a JSON or a YAML file to create your OpenAPI and import it to Orchestrate.

Click the following buttons to download the OpenAPI (JSON and YAML formats) developed for this tutorial:

Tip: After you download the OpenAPI file, you can go ahead and continue the tutorial by importing this file to Orchestrate.

The following topics describe the sections and properties that the OpenAPI must have to be imported to Orchestrate.

openapi

Use the openapi property to set the version of your OAS. In this tutorial, the version that is used is 3.0.1.

See an example of the openapi property in JSON format.

"openapi": "3.0.1"

info

Use the info section to set the API metadata. The title and version properties are mandatory in this section, but you can also add the IBM x-properties to provide more information about your API. To learn more about IBM x-properties, see Using x-ibm properties.

See an example of the info section in JSON format.

"info": {
    "title": "Sample employee",
    "description": "List the name, email, and job title of sample employees",
    "version": "1.0",
    "x-ibm-application-name": "Sample employee",
    "x-ibm-application-id": "sample-employee",
    "x-ibm-application-icon": "<svg width=\"44\" height=\"44\" xmlns=\"http://www.w3.org/2000/svg\" xmlns:xlink=\"http://www.w3.org/1999/xlink\" xml:space=\"preserve\" overflow=\"hidden\"><defs><clipPath id=\"clip0\"><rect x=\"592\" y=\"312\" width=\"44\" height=\"44\"/></clipPath><clipPath id=\"clip1\"><rect x=\"592\" y=\"312\" width=\"43\" height=\"43\"/></clipPath><clipPath id=\"clip2\"><rect x=\"592\" y=\"312\" width=\"43\" height=\"43\"/></clipPath><clipPath id=\"clip3\"><rect x=\"592\" y=\"312\" width=\"43\" height=\"43\"/></clipPath></defs><g clip-path=\"url(#clip0)\" transform=\"translate(-592 -312)\"><g clip-path=\"url(#clip1)\"><g clip-path=\"url(#clip2)\"><g clip-path=\"url(#clip3)\"><path d=\"M615.74 315.135C615.74 315.878 615.138 316.479 614.396 316.479 613.654 316.479 613.052 315.878 613.052 315.135 613.052 314.393 613.654 313.792 614.396 313.792 615.138 313.792 615.74 314.393 615.74 315.135Z\" fill=\"#000000\" fill-rule=\"nonzero\" fill-opacity=\"1\"/><path d=\"M617.979 319.167C617.979 319.909 617.378 320.51 616.635 320.51 615.893 320.51 615.292 319.909 615.292 319.167 615.292 318.425 615.893 317.823 616.635 317.823 617.378 317.823 617.979 318.425 617.979 319.167Z\" fill=\"#000000\" fill-rule=\"nonzero\" fill-opacity=\"1\"/><path d=\"M613.052 318.271C613.052 319.013 612.45 319.615 611.708 319.615 610.966 319.615 610.365 319.013 610.365 318.271 610.365 317.529 610.966 316.927 611.708 316.927 612.45 316.927 613.052 317.529 613.052 318.271Z\" fill=\"#000000\" fill-rule=\"nonzero\" fill-opacity=\"1\"/><path d=\"M614.396 323.198C614.396 324.187 613.594 324.99 612.604 324.99 611.615 324.99 610.812 324.187 610.812 323.198 610.812 322.208 611.615 321.406 612.604 321.406 613.594 321.406 614.396 322.208 614.396 323.198Z\" fill=\"#000000\" fill-rule=\"nonzero\" fill-opacity=\"1\"/><path d=\"M622.234 349.446 617.083 337.8 617.083 329.917C617.083 328.304 618.382 327.632 618.427 327.587 618.875 327.364 619.054 326.826 618.83 326.378 618.651 326.065 618.338 325.885 617.979 325.885L609.021 325.885C608.662 325.885 608.349 326.065 608.17 326.378 607.946 326.826 608.125 327.364 608.573 327.587 608.573 327.587 609.917 328.304 609.917 329.917L609.917 337.8 604.766 349.446C604.407 350.297 604.497 351.237 604.99 351.999 605.482 352.76 606.333 353.208 607.229 353.208L619.771 353.208C620.667 353.208 621.518 352.76 622.01 351.999 622.503 351.237 622.593 350.297 622.234 349.446ZM615.292 329.917 615.292 331.708 611.708 331.708 611.708 329.917C611.708 328.976 611.44 328.259 611.126 327.677L615.919 327.677C615.56 328.259 615.292 328.976 615.292 329.917Z\" fill=\"#000000\" fill-rule=\"nonzero\" fill-opacity=\"1\"/></g></g></g></g></svg>"
}

servers

Use the servers section to set the array of servers that provides connectivity information to a target server. In this tutorial, the url property is used to set the https://b25yxaezee.execute-api.us-east-2.amazonaws.com API server URL.

See an example of the servers section in JSON format.

"servers": [
    {
        "url": "https://b25yxaezee.execute-api.us-east-2.amazonaws.com"
    }
]

paths

Use the paths section to set the relative paths to the individual endpoints and their operations.

In this tutorial, the /{path} property is /demo/HelloTable and the get property is used to reference the GET operation in the /demo/HelloTable path.

See an example of the paths section in JSON format.

"paths": {
    "/demo/HelloTable": {
        "get": {
            "summary": "Retrieve employees",
            "description": "Retrieve a table with name, role, and email of the sample employees",
            "responses": {
                "200": {
                    "description": "Successfully retrieved the data",
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/hello-table"
                            }
                        }
                    }
                }
            }
        }
    }
}

components

Use the components section to set reusable properties for different aspects of the OpenAPI. You must set the securitySchemes in this section size as it is responsible to connect the app to Orchestrate.

In this tutorial, the components section is used to set the bearerAuth security scheme and to set the hello-table and table-body data types.

See an example of the components section in JSON format.

"components": {
    "schemas": {
        "hello-table": {
            "type": "object",
            "properties": {
                "body": {
                    "$ref": "#/components/schemas/table-body"
                }
            }
        },
        "table-body": {
            "type": "object",
            "properties": {
                "hwtable": {
                    "type": "array",
                    "title": "Team members",
                    "items": {
                        "type": "object",
                        "properties": {
                            "fname": {
                                "type": "string",
                                "title": "First Name",
                                "example": "Jeff"
                            },
                            "lname": {
                                "type": "string",
                                "title": "Last Name",
                                "example": "McGee"
                            },
                            "role": {
                                "type": "string",
                                "title": "Job Role",
                                "example": "Product Manager"
                            },
                            "email": {
                                "type": "string",
                                "title": "Email",
                                "example": "jeff@example.com"
                            }
                        }
                    }
                }
            }
        }
    },
    "securitySchemes": {
        "bearerAuth": {
            "type": "apiKey",
            "in": "header",
            "name": "Authorization"
        }
    }
}

Import the custom skill from the OpenAPI file

The second step is to import the Retrieve employees skill to Orchestrate:

From the menu , select Skill studio.
Click Create skill, and select Import API.
Choose From a file to import the OpenAPI file.
Drag either the sample-employees.json or sample-employees.yml file to the Drag and drop file here or click to upload area, and click Next.
From the list of skills, select Retrieve employees.
Click Add.

{: caption="Figure 1. The process to import a OpenAPI file to Orchestrate and add its resources as skills." caption-side="bottom"}

Quick checkpoint! The custom skill is available in the Skill and apps page. In the Skills list, you can see the Retrieve employees skill with the Ready to publish status. Now, you can go ahead and enhance and publish the custom skill.

Enhance and publish the custom skill

The third step is to enhance and publish the Retrieve employees skill:

From the menu , select Skill studio.
On the Skills and apps > Skills tab, click the vertical ellipsis button next to the Retrieve employees skill.
Select Enhance this skill.
From the enhance page, click the Phrases tab.
Enter the following phrases in the Enter new train phrase field. Press enter after you insert each phrase:
```
Retrieve employees.
```
```
I want to retrieve employees.
```
```
Can you retrieve the employees list?
```
Click Publish.

Figure 2. The process to add phrases while you enhance a custom skill, which makes it ready to publish.

Connect to the Sample employee app

Now that you published the custom skill to Orchestrate, you can add it to your personal skill set and use it. First, you need to connect to the Sample employee app:

On the Orchestrate home page, click Add skills from the catalog.
Click the Sample employee app tile.
Click Connect app.
Enter any data in API Key, for example, 123.
Click Connect app.

Quick checkpoint! The icon A green check icon appears to show that the app is connected.

indicates that the connection was successfully established. Now, it's time to add the Retrieve employees skill to the personal skill set.

Add the Retrieve employee skill to the personal skill set

Next, add the Retrieve employees skill from the skill catalog to the personal skill set:

On the Orchestrate home page, click Add skills from the catalog.
Click the Sample employee app tile.
In the Retrieve employees skill tile, click Add skill +.

Figure 3. The process to connect to the Sample employee app, and add the Retrieve employees skill to the skill set.

Quick checkpoint! Now, you have the Retrieve employee skill in your personal skill set, and are able to use it.

Use the Retrieve employees skill

The last step is to use the skill:

On the Orchestrate home page, click the chat.
Type "Can you retrieve the employees list? and press Enter.
Click the Apply button.

Results

After you use the custom skill, it returns a table with the first name, last name, job role, and email for sample employees.

What to do next

Now that you learned how to build a custom skill from an OpenAPI file, and how to import, enhance and publish the Sample employee app to your skill catalog, you can see the "Creating a skill flow to onboard new hires" tutorial to learn how to create a skill flow to onboard new hires, which includes the custom skill that you build here.