Implementation
Overview
The idea of custom connector and Microsoft Power Platform suggests a near-to-no-code environment for software engineer. Hence there is no code involve in building our two connectors. While it is possible to implement custom code for actions in our connector by using the language C#, we are asked by our client to implement IBM Watson APIs for general use that can be further expand if needed by other developers for their task specific project. We therefore did not implement any custom code and use the no-code template auto generated by Power App for each action.
Authentication
All IBM Watson APIs use the 'basic authentication' method for authorising users, which requires the user to fill in a username and password before he/she can access the API functionality. The field 'username' for all Watson APIs are identical, with a fixed string 'apikey' in lowercase, while the field 'password' is filled with the actual APIkey for Watson's service, given by user's IBM Cloud account. When we first implement this we added the message “Please fill in 'apikey' as your username” next to the 'username' field to clear out confusion. Yet we later decided that this was not the best approach and we implemented a drop down menu on the field with one single option 'Default', which force the string 'apikey' to be filled when selected, to tackle this confusing authentication.
Specification
Below states the authentication/connection for our two custom connectors, and their corresponding implemented actions specifications, including their functions, request and response.
IBM Watson Text to Speech (Independent Publisher)1
The IBM Watson Text to Speech service uses IBM's speech-synthesis capabilities to synthesize text into natural-sounding speech in a variety of languages, dialects, and voices.
Creating a Connection
Applicable: All regions
Parameters for creating connection
This is not shareable connection. If the power app is shared with another user, another user will be prompted to create new connection explicitly.
| Name | Type | Description | Required |
|---|---|---|---|
| Service URL | string | The service URL | True |
| API Key Name | string | The API key name | True |
| API Key | SecureString | The service API key | True |
Actions
Get Voice
Operation ID: GetVoice
Gets information about the specified voice.
Parameters
| Name | Key | Required | Type | Description |
|---|---|---|---|---|
| Voice Name | voice | True | string | Voice Name |
Returns
| Name | Path | Type | Description |
|---|---|---|---|
| url | url | string | url |
| name | name | string | name |
| language | language | string | language |
| customizable | customizable | boolean | customizable |
| gender | gender | string | gender |
| voice_transformation | supported_features.voice_transformation | boolean | voice_transformation |
| custom_pronunciation | supported_features.custom_pronunciation | boolean | custom_pronunciation |
| description | description | string | description |
| voice_transformation | voice_transformation | string | voice_transformation |
List Voices
Operation ID: ListVoices
Lists all voices available for use with the service.
Returns
| Name | Path | Type | Description |
|---|---|---|---|
| voices | voices | array of object | |
| url | voices.url | string | url |
| name | voices.name | string | name |
| language | voices.language | string | language |
| customizable | voices.customizable | boolean | customizable |
| gender | voices.gender | string | gender |
| voice_transformation | voices.supported_features.voice_transformation | boolean | voice_transformation |
| custom_pronunciation | voices.supported_features.custom_pronunciation | boolean | custom_pronunciation |
| description | voices.description | string | description |
Pronunciation
Operation ID: Pronunciation
Gets the phonetic pronunciation for the specified word.
Parameters
| Name | Key | Required | Type | Description |
|---|---|---|---|---|
| Voice Name | voices | string | Voice Name | |
| Text | text | string | Text to pronounce |
Returns
| Name | Path | Type | Description |
|---|---|---|---|
| pronunciation | pronunciation | string | pronunciation |
Synthesize
Operation ID: Synthesize
Synthesizes text to audio that is spoken in the specified voice.
Parameters
| Name | Key | Required | Type | Description |
|---|---|---|---|---|
| Voice Name | voices | string | Voice Name | |
| Text | text | True | string | Text to convert to speech |
Returns
| Name | Path | Type | Description |
|---|---|---|---|
| base64 | base64 | string | base64 |
IBM Watson Assistant (Independent Publisher)2
The IBM Watson Assistant service combines machine learning, natural language understanding, and an integrated dialog editor to create conversation flows between your apps and your users.
Creating a Connection
Applicable: All regions
Parameters for creating connection
This is not shareable connection. If the power app is shared with another user, another user will be prompted to create new connection explicitly.
| Name | Type | Description | Required |
|---|---|---|---|
| Service URL | string | The service URL | True |
| Environment ID | string | The Environment ID | True |
| API Key Name | string | The API key name | True |
| API Key | SecureString | The service API key | True |
Actions
Create a session
Operation ID: CreateSession
Create a new session. A session is used to send user input to a skill and receive responses.
Parameters
| Name | Key | Required | Type | Description |
|---|---|---|---|---|
| version | version | True | string | date of release of Watson Assistant version |
Returns
| Name | Path | Type | Description |
|---|---|---|---|
| session_id | session_id | string | session_id |
Delete session
Operation ID: DeleteSession
Deletes a session explicitly before it times out.
Parameters
| Name | Key | Required | Type | Description |
|---|---|---|---|---|
| session | session | True | string | session |
| version | version | string | date of release of Watson Assistant version |
Stateful Message
Operation ID: StatefulMessage
Send user input to an assistant and receive a response, with conversation state (including context data) stored by Watson Assistant for the duration of the session.
Parameters
| Name | Key | Required | Type | Description |
|---|---|---|---|---|
| session | session | True | string | session |
| version | version | string | date of release of Watson Assistant version | |
| text | text | True | string | text |
Returns
| Name | Path | Type | Description |
|---|---|---|---|
| intents | output.intents | array of object | intents |
| intent | output.intents.intent | string | intent |
| confidence | output.intents.confidence | float | confidence |
| generic | output.generic | array of object | generic |
| response_type | output.generic.response_type | string | response_type |
| text | output.generic.text | string | text |
| user_id | user_id | string | user_id |
Stateless Message
Operation ID: StatelessMessage
Send user input to an assistant and receive a response, with conversation state (including context data) managed by your application.
Parameters
| Name | Key | Required | Type | Description |
|---|---|---|---|---|
| version | version | string | date of release of Watson Assistant version | |
| text | text | True | string | text |
Returns
| Name | Path | Type | Description |
|---|---|---|---|
| intents | output.intents | array of object | intents |
| intent | output.intents.intent | string | intent |
| confidence | output.intents.confidence | float | confidence |
| generic | output.generic | array of object | generic |
| response_type | output.generic.response_type | string | response_type |
| text | output.generic.text | string | text |
| user_id | user_id | string | user_id |
- IBM Watson Text to Speech (Independent Publisher)
- IBM Watson Assistant (Independent Publisher) (Preview)