wo-skill-dev-documentation

Overview

Learn how to build skills for use in IBM watsonx Orchestrate. Every time you start to develop new skills, revisit this information for updates.

For style guidelines, such as information about naming and describing skills and examples of the help text to provide, refer to the Skill design content guidelines.

Getting started

To get started, understand the concepts by reading Apps and skills.

Skill flows

Skills are often more valuable when combined with other skills. You can create a linear sequence of skills by using a skill flow. Structure your skill flow to use two or more skills to complete a task. These skills can be from different applications. Using a skill flow, you can combine multiple functional calls to carry out a single workflow.

The following blueprint indicates the steps involved in building skills in watsonx Orchestrate.

Start with an end-to-end use case in mind and then follow this process:

1. Familiarize yourself with the best practices for skill designing skills: Skill design content guidelines.
2. Check whether the skill or skill flow you want to build is already available in watsonx Orchestrate.
3. Build the skills and skill flows needed to achieve the goal of your use case.

Developing skills

Create skills from [OpenAPI files](https://www.ibm.com/docs/en/watson-orchestrate?topic=files-creating-skills-from-openapi. If you don't have an OpenAPI file ready and want to build one from scratch, see Adding skills from files. Then, enhance the OpenAPI file into an exemplary watsonx Orchestrate skill.

After a skill is enhanced and published, it is available for you to add to your skill set from the skill catalog by following these instructions: Adding a skill from skill catalog.

Tip: Users with the either the Admin or Builder role can add the skill to a team skill set.

Combining skills into skill flows

Now that the required skills are available, it's time to build your end-to-end use case as a time-saving skill flow.

Testing skills

Ensure your skills are working as expected. Test the skills by clicking them from the tiles on home page or by typing phrases into the chat bar to find the skills. Revise the skills to adhere to the Skill design content guidelines .

After sufficient testing, export the skills.

Pushing the skills into Github repository

Merge the skills (.json files) into your Github repository. In the Partner Github repository, add documentation for the users of this skill to use the skills efficiently.

Obtaining approval

Add your test evidence, such as a screen capture of the test:

Publishing the skill to be part of watsonx Orchestrate Global skills catalog

In the README.md file, indicate whether you want your skills to be published by the watsonx Orchestrate team to be part of the out-of-the-box skill catalog. When they are included in the skill catalog in the subsequent release, you can test the skills on your production instance of watsonx Orchestrate.

Building an OpenAPI from scratch

You can build an OpenAPI by using a text editor or by using the CURL command in CDK, which is an IBM tool:

1. Log in to CDK at https://explorer.automation.ibm.com/cdk.

2. Identify the API developer documentation for the identified set of skills or APIs, for example https://developer.webex.com/docs/api/v1/recordings. Narrow down to the exact API: https://developer.webex.com/docs/api/v1/recordings/list-recordings.

3. Log in to Connector Development Toolkit using your IBM ID (https://explorer.automation.ibm.com/cdk). You can link any email ID as an IBMid. For partners onboarded as IBM sub-contractors, it is advisable to use a IBM w3 ID as the IBMid.

4. Click Create a connector and provide the essential details like the app name and the icon and then attach the OpenAPI specification file, if it's available.

5. If an OpenAPI is not available, click Create a connector and complete the steps to create an OpenAPI from scratch.

Create a group (optional) to group a set of APIs together, for example a WebexRecording group:

6. Create actions for the WebexRecording API by using a CURL command. Most API documentation provides CURL commands for the APIs, such as this example from Workday:

If a CURL command is not available, get one by using PostMan:

Request

https://webexapis.com/v1/recordings?from=2020-07-12T09:30:00+08:00&to=2020-07-31T09:30:00+08:00&meetingId=f91b6edce9864428af084977b7c68291_I_166641849979635652&hostEmail=john.andersen@example.com&siteUrl=example.webex.com&integrationTag=dbaeceebea5c4a63ac9d5ef1edfe36b9&topic=John's%20Meeting&format=ARF&serviceType=MeetingCenter&status=%5Bobject%20Object%5D,%5Bobject%20Object%5D

In PostMan, click the code button.

7. Copy the CURL command into the CDK and click Add action.

The ListRecording API is now created:

8. From the Request and Response tabs, change any of the fields, mark fields as mandatory, add new fields, add pagination, as you see fit:

9. Create the response schema by copying the response example from Webex developer docs:

10. Add or remove response fields:

11. From the Connection Properties tab, add the required authentication scheme for the API, such as if Webex takes a bearer token:

12. Test the API by providing your credentials:

13. After you connect successfully, test the APIs:

14. Download the app, which is call a "connector" in the Connector Development Kit.

15. Decrypt the .car file to extract the raw OpenAPI needed for the watsonx Orchestrate skill by using the command you received from IBM.

Now you can continue developing the skill.